mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/visual_run/sdk.py

@@ -0,0 +1,892 @@
+"""The supported agent-facing API for durable, observable research work."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_json_bytes
+from mostlyright.data_harness.visual_run.contracts import (
+    ACTORS,
+    ArtifactReference,
+    TerminalError,
+    VisualRunDraft,
+    VisualRunError,
+    VisualRunEvent,
+)
+from mostlyright.data_harness.visual_run.materialize import MAX_MATERIALIZED_NOTEBOOK_BYTES
+from mostlyright.data_harness.visual_run.observations import (
+    scrub_for_display,
+    validate_stage_observation,
+)
+from mostlyright.data_harness.visual_run.reducer import CellState, reduce_events
+from mostlyright.data_harness.visual_run.store import VisualRunStore
+
+
+def validate_markdown_checkpoint(source: str) -> None:
+    """Load renderer-backed authoring policy only when an agent writes markdown."""
+
+    from mostlyright.data_harness.visual_run.authoring import validate_markdown_checkpoint
+
+    validate_markdown_checkpoint(source)
+
+
+def validate_markdown_completion(source: str) -> None:
+    """Load renderer-backed completion policy only when an agent completes markdown."""
+
+    from mostlyright.data_harness.visual_run.authoring import validate_markdown_completion
+
+    validate_markdown_completion(source)
+
+
+def validate_markdown_document(source: str) -> None:
+    """Load the full-document authoring rule only for agent markdown writes."""
+
+    from mostlyright.data_harness.visual_run.authoring import validate_markdown_document
+
+    validate_markdown_document(source)
+
+
+def _utc_now() -> str:
+    return datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def next_attempt_coordinate(store: VisualRunStore, scope: str, attempt: str) -> str:
+    """Return the active or next durable attempt coordinate for a retryable command.
+
+    Producer attempt ids are fences and intentionally remain stable across process retries.  A
+    visual phase, however, is one concrete invocation.  Reusing the fence as the phase identity
+    caused a later failure to collide with the first invocation's terminal event and mask the
+    real error.  Active phases are resumed idempotently; completed/failed phases advance to a
+    deterministic retry coordinate derived only from the durable log.
+    """
+
+    if not scope or ":" in scope:
+        raise ValueError("attempt scope must be a non-empty coordinate segment")
+    state = reduce_events(store.events())
+    ordinal = 0
+    while True:
+        base = f"{scope}:{attempt}"
+        coordinate = base if ordinal == 0 else f"{base}:retry-{ordinal}"
+        object_id = VisualWork._attempt_identity(coordinate)
+        existing = state.objects.get(object_id)
+        if existing is None or existing.status == "active":
+            return coordinate
+        ordinal += 1
+
+
+def attempt_event_key(scope: str, coordinate: str, transition: str) -> str:
+    """Bind an attempt transition key to its invocation without exposing long coordinates."""
+
+    if transition not in {"started", "completed", "failed"}:
+        raise ValueError("unknown attempt transition")
+    digest = hashlib.sha256(coordinate.encode("utf-8")).hexdigest()[:24]
+    return f"{scope}:attempt:{digest}:{transition}"
+
+
+class VisualWork:
+    """Persist meaningful agent cell phases through one versioned API.
+
+    Callers provide complete source/output states at real checkpoints. The SDK never sleeps,
+    slices text, invents progress, or derives ordering from timestamps.
+    """
+
+    @staticmethod
+    def _run_identity(run_id: str) -> str:
+        return f"run:{hashlib.sha256(run_id.encode('utf-8')).hexdigest()[:24]}"
+
+    def _run_object_id(self) -> str:
+        """Use the namespaced identity, while preserving already-durable v1 run objects."""
+
+        state = self._state()
+        existing = [object_id for object_id, kind in state.object_kinds.items() if kind == "run"]
+        if len(existing) > 1:
+            raise VisualRunError("VISUAL_RUN_TRANSITION", "run has multiple identity objects")
+        return existing[0] if existing else self._run_identity(self.store.run_id)
+
+    def __init__(
+        self,
+        store: VisualRunStore,
+        *,
+        observed_at: Callable[[], str] = _utc_now,
+        actor: str = "agent",
+    ) -> None:
+        if actor not in ACTORS:
+            raise ValueError("actor is outside the visual-run contract")
+        self.store = store
+        self._observed_at = observed_at
+        self._actor = actor
+
+    def _state(self) -> Any:
+        return reduce_events(self.store.events())
+
+    def _cell(self, cell_id: str) -> CellState:
+        cell = self._state().cells.get(cell_id)
+        if cell is None:
+            raise KeyError(cell_id)
+        return cell
+
+    def _append(
+        self,
+        event_type: str,
+        key: str,
+        *,
+        object_id: str,
+        object_version: int,
+        previous_object_version: int | None,
+        payload: Mapping[str, Any],
+        artifact: ArtifactReference | None = None,
+        status: str | None = None,
+        error: TerminalError | None = None,
+        phase: str = "researching",
+        stage: str = "authoring",
+    ) -> VisualRunEvent:
+        existing = self.store.event_for_key(key)
+        draft = VisualRunDraft.from_mapping(
+            {
+                "schema_version": "visual-run-event.v2",
+                "run_id": self.store.run_id,
+                "event_type": event_type,
+                "event_version": 1,
+                "actor": self._actor,
+                "phase": phase,
+                "stage": stage,
+                "object_id": object_id,
+                "object_version": object_version,
+                "previous_object_version": previous_object_version,
+                # Retries compare the durable timestamp, because time is not command intent.
+                "observed_at": existing.observed_at
+                if existing is not None
+                else self._observed_at(),
+                "idempotency_key": key,
+                "payload": dict(payload),
+                "artifact": artifact.to_mapping() if artifact is not None else None,
+                "status": status,
+                "error": error.to_mapping() if error is not None else None,
+            }
+        )
+        if existing is not None:
+            existing_value = VisualRunDraft.from_event(existing).to_mapping()
+            retry_value = draft.to_mapping()
+            existing_value.pop("observed_at")
+            retry_value.pop("observed_at")
+            if existing_value == retry_value:
+                return existing
+            raise VisualRunError(
+                "VISUAL_RUN_IDEMPOTENCY_CONFLICT", "idempotency key names another command"
+            )
+        return self.store.append(draft)
+
+    def start_run(self, *, key: str = "run-started") -> VisualRunEvent:
+        return self._append(
+            "run.started",
+            key,
+            # Run identity and object identity are separate namespaces.  Hashing keeps an
+            # operator-selected run id such as ``build`` from colliding with fixed worker
+            # objects while the event's top-level ``run_id`` remains the public identity.
+            object_id=self._run_object_id(),
+            object_version=1,
+            previous_object_version=None,
+            payload={},
+        )
+
+    def start_cell(
+        self,
+        cell_id: str,
+        cell_type: str,
+        *,
+        key: str,
+        after_cell_id: str | None = None,
+    ) -> VisualRunEvent:
+        created = self._append(
+            "cell.created",
+            key,
+            object_id=cell_id,
+            object_version=1,
+            previous_object_version=None,
+            payload={"cell_type": cell_type},
+        )
+        if after_cell_id is not None:
+            self.move_after(cell_id, after_cell_id, key=f"{key}-position")
+        return created
+
+    def update_source(self, cell_id: str, source: str, *, key: str) -> VisualRunEvent:
+        if not isinstance(source, str):
+            raise TypeError("source must be text")
+        content = source.encode("utf-8")
+        existing = self.store.event_for_key(key)
+        if existing is not None:
+            reference = self._retry_artifact_reference(
+                existing,
+                content,
+                expected_schema="mostlyright.cell-source.v1",
+            )
+            return self._append(
+                "cell.source_extended",
+                key,
+                object_id=cell_id,
+                object_version=existing.object_version,
+                previous_object_version=existing.previous_object_version,
+                payload={"source_length": len(source)},
+                artifact=reference,
+            )
+        cell = self._cell(cell_id)
+        if cell.source is not None:
+            previous = self.store.read_artifact(cell.source)
+            if not content.startswith(previous) or content == previous:
+                raise ValueError("source extension must strictly append to the prior source")
+        if self._actor == "agent" and cell.cell_type == "markdown":
+            validate_markdown_document(content.decode("utf-8"))
+            previous_length = 0 if cell.source is None else len(previous)
+            validate_markdown_checkpoint(content[previous_length:].decode("utf-8"))
+        media_type = "text/markdown" if cell.cell_type == "markdown" else "text/x-python"
+        reference = self._install(
+            content,
+            artifact_id=f"{cell_id}-source-v{cell.version + 1}",
+            media_type=media_type,
+            artifact_schema="mostlyright.cell-source.v1",
+            projected=True,
+            replacing=cell.source,
+        )
+        return self._append(
+            "cell.source_extended",
+            key,
+            object_id=cell_id,
+            object_version=cell.version + 1,
+            previous_object_version=cell.version,
+            payload={"source_length": len(source)},
+            artifact=reference,
+        )
+
+    def revise_source(self, cell_id: str, source: str, *, key: str) -> VisualRunEvent:
+        if not isinstance(source, str):
+            raise TypeError("source must be text")
+        content = source.encode("utf-8")
+        existing = self.store.event_for_key(key)
+        if existing is not None:
+            reference = self._retry_artifact_reference(
+                existing,
+                content,
+                expected_schema="mostlyright.cell-source.v1",
+            )
+            return self._append(
+                "cell.source_revised",
+                key,
+                object_id=cell_id,
+                object_version=existing.object_version,
+                previous_object_version=existing.previous_object_version,
+                payload={"source_length": len(source)},
+                artifact=reference,
+            )
+        cell = self._cell(cell_id)
+        if self._actor == "agent" and cell.cell_type == "markdown":
+            validate_markdown_document(source)
+            validate_markdown_checkpoint(source)
+        media_type = "text/markdown" if cell.cell_type == "markdown" else "text/x-python"
+        reference = self._install(
+            content,
+            artifact_id=f"{cell_id}-revision-v{cell.version + 1}",
+            media_type=media_type,
+            artifact_schema="mostlyright.cell-source.v1",
+            projected=True,
+            replacing=cell.source,
+        )
+        return self._append(
+            "cell.source_revised",
+            key,
+            object_id=cell_id,
+            object_version=cell.version + 1,
+            previous_object_version=cell.version,
+            payload={"source_length": len(source)},
+            artifact=reference,
+        )
+
+    def move_after(self, cell_id: str, after_cell_id: str, *, key: str) -> VisualRunEvent:
+        existing = self.store.event_for_key(key)
+        if existing is not None:
+            return self._append(
+                "cell.moved",
+                key,
+                object_id=cell_id,
+                object_version=existing.object_version,
+                previous_object_version=existing.previous_object_version,
+                payload={"after_cell_id": after_cell_id},
+            )
+        cell = self._cell(cell_id)
+        return self._append(
+            "cell.moved",
+            key,
+            object_id=cell_id,
+            object_version=cell.version + 1,
+            previous_object_version=cell.version,
+            payload={"after_cell_id": after_cell_id},
+        )
+
+    def execution_started(self, cell_id: str, execution_count: int, *, key: str) -> VisualRunEvent:
+        existing = self.store.event_for_key(key)
+        if existing is not None:
+            return self._append(
+                "cell.execution_started",
+                key,
+                object_id=cell_id,
+                object_version=existing.object_version,
+                previous_object_version=existing.previous_object_version,
+                payload={"execution_count": execution_count},
+                stage="executing",
+            )
+        cell = self._cell(cell_id)
+        return self._append(
+            "cell.execution_started",
+            key,
+            object_id=cell_id,
+            object_version=cell.version + 1,
+            previous_object_version=cell.version,
+            payload={"execution_count": execution_count},
+            stage="executing",
+        )
+
+    def output(
+        self,
+        cell_id: str,
+        output: Mapping[str, Any],
+        *,
+        output_kind: str,
+        key: str,
+        index: int | None = None,
+    ) -> VisualRunEvent:
+        import json
+
+        content = (
+            json.dumps(
+                output, ensure_ascii=False, allow_nan=False, sort_keys=True, separators=(",", ":")
+            )
+            + "\n"
+        ).encode()
+        existing = self.store.event_for_key(key)
+        replace = index is not None
+        if existing is not None:
+            output_index = index if index is not None else existing.payload.get("output_index")
+            reference = self._retry_artifact_reference(
+                existing,
+                content,
+                expected_schema="mostlyright.cell-output.v1",
+            )
+            return self._append(
+                "cell.output_replaced" if replace else "cell.output_appended",
+                key,
+                object_id=cell_id,
+                object_version=existing.object_version,
+                previous_object_version=existing.previous_object_version,
+                payload={"output_index": output_index, "output_kind": output_kind},
+                artifact=reference,
+                stage="executing",
+            )
+        cell = self._cell(cell_id)
+        output_index = index if index is not None else len(cell.outputs)
+        if replace and not 0 <= output_index < len(cell.outputs):
+            raise ValueError("output replacement index is outside the current outputs")
+        reference = self._install(
+            content,
+            artifact_id=f"{cell_id}-output-{output_index}-v{cell.version + 1}",
+            media_type="application/json",
+            artifact_schema="mostlyright.cell-output.v1",
+            projected=True,
+            replacing=cell.outputs[output_index] if replace else None,
+        )
+        return self._append(
+            "cell.output_replaced" if replace else "cell.output_appended",
+            key,
+            object_id=cell_id,
+            object_version=cell.version + 1,
+            previous_object_version=cell.version,
+            payload={"output_index": output_index, "output_kind": output_kind},
+            artifact=reference,
+            stage="executing",
+        )
+
+    def complete(self, cell_id: str, *, key: str) -> VisualRunEvent:
+        existing = self.store.event_for_key(key)
+        if existing is not None:
+            return self._append(
+                "cell.completed",
+                key,
+                object_id=cell_id,
+                object_version=existing.object_version,
+                previous_object_version=existing.previous_object_version,
+                payload={},
+                stage="complete",
+            )
+        cell = self._cell(cell_id)
+        if self._actor == "agent" and cell.cell_type == "markdown" and cell.source is not None:
+            validate_markdown_completion(self.store.read_artifact(cell.source).decode("utf-8"))
+        return self._append(
+            "cell.completed",
+            key,
+            object_id=cell_id,
+            object_version=cell.version + 1,
+            previous_object_version=cell.version,
+            payload={},
+            stage="complete",
+        )
+
+    def fail(self, cell_id: str, error: TerminalError, *, key: str) -> VisualRunEvent:
+        existing = self.store.event_for_key(key)
+        if existing is not None:
+            return self._append(
+                "cell.failed",
+                key,
+                object_id=cell_id,
+                object_version=existing.object_version,
+                previous_object_version=existing.previous_object_version,
+                payload={},
+                error=error,
+                stage="failed",
+            )
+        cell = self._cell(cell_id)
+        return self._append(
+            "cell.failed",
+            key,
+            object_id=cell_id,
+            object_version=cell.version + 1,
+            previous_object_version=cell.version,
+            payload={},
+            error=error,
+            stage="failed",
+        )
+
+    def _update_versions(self, object_id: str, key: str) -> tuple[int, int]:
+        existing = self.store.event_for_key(key)
+        if existing is not None:
+            if existing.previous_object_version is None:
+                raise VisualRunError(
+                    "VISUAL_RUN_IDEMPOTENCY_CONFLICT", "update key names a creation command"
+                )
+            return existing.object_version, existing.previous_object_version
+        current = self._state().object_versions.get(object_id)
+        if current is None:
+            raise KeyError(object_id)
+        return current + 1, current
+
+    @staticmethod
+    def _stage_identity(node_id: str) -> tuple[str, str, str]:
+        digest = hashlib.sha256(node_id.encode("utf-8")).hexdigest()
+        coordinate = node_id if len(node_id) <= 64 else f"{node_id[:47]}-{digest[:16]}"
+        return f"stage:{node_id}", digest, coordinate
+
+    def transformation_started(self, node_id: str, operation: str, *, key: str) -> VisualRunEvent:
+        object_id, _, coordinate = self._stage_identity(node_id)
+        return self._append(
+            "transformation.started",
+            key,
+            object_id=object_id,
+            object_version=1,
+            previous_object_version=None,
+            payload={"operation": operation},
+            phase="building",
+            stage=coordinate,
+        )
+
+    @staticmethod
+    def _attempt_identity(attempt: str) -> str:
+        return f"attempt:{hashlib.sha256(attempt.encode('utf-8')).hexdigest()[:24]}"
+
+    def attempt_started(self, attempt: str, *, key: str) -> VisualRunEvent:
+        return self._append(
+            "phase.started",
+            key,
+            object_id=self._attempt_identity(attempt),
+            object_version=1,
+            previous_object_version=None,
+            payload={},
+            phase="building",
+            stage="attempt",
+        )
+
+    def attempt_completed(self, attempt: str, *, key: str) -> VisualRunEvent:
+        object_id = self._attempt_identity(attempt)
+        version, previous = self._update_versions(object_id, key)
+        return self._append(
+            "phase.completed",
+            key,
+            object_id=object_id,
+            object_version=version,
+            previous_object_version=previous,
+            payload={},
+            phase="building",
+            stage="attempt",
+        )
+
+    def attempt_failed(self, attempt: str, error: TerminalError, *, key: str) -> VisualRunEvent:
+        object_id = self._attempt_identity(attempt)
+        version, previous = self._update_versions(object_id, key)
+        return self._append(
+            "phase.failed",
+            key,
+            object_id=object_id,
+            object_version=version,
+            previous_object_version=previous,
+            payload={},
+            error=error,
+            phase="building",
+            stage="attempt",
+        )
+
+    def transformation_completed(
+        self, node_id: str, operation: str, row_count: int, *, key: str
+    ) -> VisualRunEvent:
+        object_id, _, coordinate = self._stage_identity(node_id)
+        version, previous = self._update_versions(object_id, key)
+        return self._append(
+            "transformation.completed",
+            key,
+            object_id=object_id,
+            object_version=version,
+            previous_object_version=previous,
+            payload={"operation": operation, "row_count": row_count},
+            phase="building",
+            stage=coordinate,
+        )
+
+    def source_selected(self, source_id: str, source_kind: str, *, key: str) -> VisualRunEvent:
+        return self._append(
+            "source.selected",
+            key,
+            object_id=f"source:{source_id}",
+            object_version=1,
+            previous_object_version=None,
+            payload={"source_kind": source_kind},
+            phase="researching",
+            stage="source-selection",
+        )
+
+    def publish_source_observation(
+        self,
+        source_id: str,
+        observation: Mapping[str, Any],
+        *,
+        observation_kind: str,
+        key: str,
+    ) -> VisualRunEvent:
+        object_id = f"source:{source_id}"
+        version, previous = self._update_versions(object_id, key)
+        normalized, redacted = scrub_for_display(dict(observation))
+        assert isinstance(normalized, dict)
+        content = canonical_json_bytes(normalized) + b"\n"
+        digest = hashlib.sha256(source_id.encode("utf-8")).hexdigest()
+        reference = self._install(
+            content,
+            artifact_id=f"source-{digest[:24]}-observation-v{version}",
+            media_type="application/json",
+            artifact_schema="mostlyright.source-observation.v1",
+            display="summary" if redacted else "inline",
+            projected=True,
+        )
+        return self._append(
+            "source.observation_ready",
+            key,
+            object_id=object_id,
+            object_version=version,
+            previous_object_version=previous,
+            payload={"observation_kind": observation_kind},
+            artifact=reference,
+            phase="researching",
+            stage="source-inspection",
+        )
+
+    def publish_quality_observation(
+        self,
+        checks_passed: int,
+        checks_total: int,
+        *,
+        key: str,
+        report: Mapping[str, Any] | None = None,
+    ) -> VisualRunEvent:
+        observation = (
+            dict(report)
+            if report is not None
+            else {
+                "schema_version": "mostlyright.quality-observation.v1",
+                "status": "passed" if checks_passed == checks_total else "failed",
+                "checks": [],
+            }
+        )
+        observation = {
+            "schema_version": "mostlyright.quality-observation.v1",
+            "checks_passed": checks_passed,
+            "checks_total": checks_total,
+            "report": observation,
+        }
+        normalized, redacted = scrub_for_display(observation)
+        assert isinstance(normalized, dict)
+        content = canonical_json_bytes(normalized) + b"\n"
+        reference = self._install(
+            content,
+            artifact_id="quality-observation",
+            media_type="application/json",
+            artifact_schema="mostlyright.quality-observation.v1",
+            display="summary" if redacted else "inline",
+        )
+        return self._append(
+            "quality.completed",
+            key,
+            object_id="quality",
+            object_version=1,
+            previous_object_version=None,
+            payload={"checks_passed": checks_passed, "checks_total": checks_total},
+            artifact=reference,
+            phase="building",
+            stage="quality",
+        )
+
+    def table_written(
+        self, table_sha256: str, *, row_count: int, column_count: int, key: str
+    ) -> VisualRunEvent:
+        if len(table_sha256) != 64 or any(
+            character not in "0123456789abcdef" for character in table_sha256
+        ):
+            raise ValueError("table_sha256 must be lowercase SHA-256")
+        content = (
+            canonical_json_bytes(
+                {
+                    "schema_version": "mostlyright.table-reference.v1",
+                    "table_sha256": table_sha256,
+                    "row_count": row_count,
+                    "column_count": column_count,
+                }
+            )
+            + b"\n"
+        )
+        reference = self._install(
+            content,
+            artifact_id=f"table-{table_sha256[:24]}",
+            media_type="application/json",
+            artifact_schema="mostlyright.table-reference.v1",
+            display="summary",
+        )
+        return self._append(
+            "table_written",
+            key,
+            object_id="table",
+            object_version=1,
+            previous_object_version=None,
+            payload={"row_count": row_count, "column_count": column_count},
+            artifact=reference,
+            phase="building",
+            stage="table",
+        )
+
+    def publish_table_observation(
+        self, table_sha256: str, *, row_count: int, column_count: int, key: str
+    ) -> VisualRunEvent:
+        return self.table_written(
+            table_sha256, row_count=row_count, column_count=column_count, key=key
+        )
+
+    def build_sealed(self, candidate_digest: str, *, key: str) -> VisualRunEvent:
+        return self._append(
+            "build.sealed",
+            key,
+            object_id="build",
+            object_version=1,
+            previous_object_version=None,
+            payload={"candidate_digest": candidate_digest},
+            phase="building",
+            stage="sealing",
+        )
+
+    def build_verified(self, candidate_digest: str, *, key: str) -> VisualRunEvent:
+        version, previous = self._update_versions("build", key)
+        return self._append(
+            "build.verified",
+            key,
+            object_id="build",
+            object_version=version,
+            previous_object_version=previous,
+            payload={"candidate_digest": candidate_digest},
+            phase="building",
+            stage="verification",
+        )
+
+    def notebook_materialized(self, kind: str, content: bytes, *, key: str) -> VisualRunEvent:
+        if kind not in {"research", "table"}:
+            raise ValueError("notebook kind must be research or table")
+        digest = hashlib.sha256(content).hexdigest()
+        reference = self._install(
+            content,
+            artifact_id=f"notebook-{kind}-{digest[:24]}",
+            media_type="application/x-ipynb+json",
+            artifact_schema="mostlyright.notebook.v1",
+            display="inline",
+        )
+        return self._append(
+            f"notebook.{kind}_materialized",
+            key,
+            object_id=f"notebook:{kind}",
+            object_version=1,
+            previous_object_version=None,
+            payload={"notebook_digest": digest},
+            artifact=reference,
+            phase="building" if kind == "table" else "researching",
+            stage="notebook",
+        )
+
+    def complete_run(self, *, key: str) -> VisualRunEvent:
+        object_id = self._run_object_id()
+        version, previous = self._update_versions(object_id, key)
+        return self._append(
+            "run.completed",
+            key,
+            object_id=object_id,
+            object_version=version,
+            previous_object_version=previous,
+            payload={},
+            status="completed",
+            phase="complete",
+            stage="complete",
+        )
+
+    def fail_run(self, error: TerminalError, *, key: str) -> VisualRunEvent:
+        object_id = self._run_object_id()
+        version, previous = self._update_versions(object_id, key)
+        return self._append(
+            "run.failed",
+            key,
+            object_id=object_id,
+            object_version=version,
+            previous_object_version=previous,
+            payload={},
+            status="failed",
+            error=error,
+            phase="failed",
+            stage="failed",
+        )
+
+    def publish_stage_observation(
+        self,
+        observation: Mapping[str, Any],
+        *,
+        key: str,
+    ) -> VisualRunEvent:
+        """Persist one deterministic graph-stage observation before candidate sealing."""
+
+        candidate, redacted = scrub_for_display(dict(observation))
+        assert isinstance(candidate, dict)
+        if redacted:
+            candidate["display"] = "schema_only"
+            candidate["sample"] = []
+            if "operation_parameters" in candidate:
+                candidate["operation_parameters"] = {}
+            if "source_coordinates" in candidate:
+                candidate["source_coordinates"] = []
+        normalized = validate_stage_observation(candidate)
+        node_id = str(normalized["node_id"])
+        operation = str(normalized["operation"])
+        row_count = normalized["output_rows"]
+        object_id, node_digest, stage_coordinate = self._stage_identity(node_id)
+        if object_id not in self._state().object_versions:
+            self.transformation_started(node_id, operation, key=f"{key}:started")
+        content = canonical_json_bytes(normalized) + b"\n"
+        display = {
+            "full": "inline",
+            "redacted": "redacted",
+            "aggregate_only": "summary",
+            "schema_only": "summary",
+        }.get(str(normalized["display"]))
+        if display is None:
+            raise ValueError("stage observation display policy is invalid")
+        reference = self._install(
+            content,
+            artifact_id=f"stage-{node_digest[:24]}-observation",
+            media_type="application/json",
+            artifact_schema=str(normalized["schema_version"]),
+            display=display,
+            projected=True,
+        )
+        version, previous = self._update_versions(object_id, f"{key}:ready")
+        return self._append(
+            "stage.observation_ready",
+            f"{key}:ready",
+            object_id=object_id,
+            object_version=version,
+            previous_object_version=previous,
+            payload={"operation": operation, "row_count": row_count},
+            artifact=reference,
+            phase="building",
+            stage=stage_coordinate,
+        )
+
+    def _install(
+        self,
+        content: bytes,
+        *,
+        artifact_id: str,
+        media_type: str,
+        artifact_schema: str,
+        display: str = "inline",
+        projected: bool = False,
+        replacing: ArtifactReference | None = None,
+    ) -> ArtifactReference:
+        if projected:
+            state = self._state()
+            current_bytes = sum(
+                reference.byte_size
+                for cell in state.cells.values()
+                for reference in ((cell.source,) if cell.source is not None else ()) + cell.outputs
+            ) + sum(reference.byte_size for reference in state.observations)
+            prospective_bytes = current_bytes + len(content)
+            if replacing is not None:
+                prospective_bytes -= replacing.byte_size
+            if prospective_bytes > MAX_MATERIALIZED_NOTEBOOK_BYTES:
+                raise VisualRunError(
+                    "VISUAL_RUN_PROJECTION_LIMIT",
+                    "event would exceed the materialized research notebook limit",
+                )
+        if len(content) > MAX_MATERIALIZED_NOTEBOOK_BYTES:
+            raise VisualRunError(
+                "VISUAL_RUN_PROJECTION_LIMIT",
+                "artifact exceeds the materialized research notebook limit",
+            )
+        reference = ArtifactReference.from_mapping(
+            {
+                "schema_version": "visual-run-artifact-ref.v2",
+                "artifact_id": artifact_id,
+                "sha256": hashlib.sha256(content).hexdigest(),
+                "media_type": media_type,
+                "artifact_schema": artifact_schema,
+                "byte_size": len(content),
+                "truncated": False,
+                "original_byte_size": len(content),
+                "display": display,
+            }
+        )
+        self.store.install_artifact(reference, content)
+        return reference
+
+    def _retry_artifact_reference(
+        self,
+        existing: VisualRunEvent,
+        content: bytes,
+        *,
+        expected_schema: str,
+    ) -> ArtifactReference:
+        """Rebuild retry intent without consulting mutable state or installing an artifact."""
+
+        reference = existing.artifact
+        if reference is None or reference.artifact_schema != expected_schema:
+            raise VisualRunError(
+                "VISUAL_RUN_IDEMPOTENCY_CONFLICT",
+                "idempotency key names another command",
+            )
+        return ArtifactReference.from_mapping(
+            {
+                **reference.to_mapping(),
+                "sha256": hashlib.sha256(content).hexdigest(),
+                "byte_size": len(content),
+                "original_byte_size": len(content),
+            }
+        )
+
+
+__all__ = ["VisualWork", "attempt_event_key", "next_attempt_coordinate"]