mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/event_presentation.py

@@ -0,0 +1,576 @@
+"""Plain, bounded presentation of run-feed records.
+
+The event feed is the authority for what happened.  This module supplies the one presentation
+vocabulary shared by Watch and the Notebook Viewer, plus a pure reducer for the Viewer's compact
+Build block.  It opens no files, reads no clocks, and never re-derives records from receipts.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from mostlyright.data_harness.events import NOTEBOOK_SIDECAR_EVENT_NAMES, validate_facts
+
+# The rail is a plain-vocabulary rendering of the build and evidence stages declared by
+# ``cli._agent_workflow_surface()``. Presentation-only observability is intentionally absent. A
+# test owns the one-way subset contract because importing ``cli`` here would close a cycle.
+STAGE_RAIL: tuple[Mapping[str, Any], ...] = (
+    {
+        "stage": "question_and_requirements",
+        "label": "Question and requirements",
+        "events": (),
+        "members": ("question.json", "requirements.json"),
+        "steps": (),
+    },
+    {
+        "stage": "source_candidates_and_fitness",
+        "label": "Sources proposed",
+        "events": (),
+        "members": ("source-proposals.json",),
+        "steps": (),
+    },
+    {
+        "stage": "frozen_recipe",
+        "label": "Recipe written",
+        "events": (),
+        "members": ("recipe.json",),
+        "steps": (),
+    },
+    {
+        "stage": "recipe_approval",
+        "label": "Recipe approved",
+        "events": (),
+        "members": ("recipe-approval.json",),
+        "steps": (),
+    },
+    {
+        "stage": "acquire_clean_join_validate_package",
+        "label": "Build",
+        "events": ("run_started", "rights_checked", "build_failed", "run_interrupted"),
+        "steps": (
+            {"step": "sources_read", "label": "Sources read", "events": ("source_read",)},
+            {
+                "step": "sources_opened",
+                "label": "Sources opened",
+                "events": ("source_parsed",),
+            },
+            {
+                "step": "cleaning_applied",
+                "label": "Cleaning applied",
+                "events": ("cleaning_applied",),
+            },
+            {"step": "joined", "label": "Joined", "events": ("join_completed",)},
+            {"step": "checks", "label": "Checks", "events": ("checks_completed",)},
+            {
+                "step": "table_written",
+                "label": "Table written",
+                "events": ("table_written",),
+            },
+            {
+                "step": "receipt_sealed",
+                "label": "Receipt sealed",
+                "events": ("member_sealed", "build_sealed"),
+            },
+        ),
+    },
+    {"stage": "independent_review", "label": "Review", "events": (), "steps": ()},
+    {
+        "stage": "independent_verification",
+        "label": "Independent check",
+        "events": (),
+        "steps": (),
+    },
+    {
+        "stage": "handoff",
+        "label": "Handoff",
+        "events": ("notebook_sidecar_ready",),
+        "steps": (),
+    },
+    {"stage": "hosted_export", "label": "Hosted export", "events": (), "steps": ()},
+)
+
+
+# One short sentence per event name. Internal event names never reach either page.
+EVENT_SENTENCES: Mapping[str, str] = {
+    "run_started": "Build started",
+    "rights_checked": "Rights checked",
+    "sources_read_started": "Started reading {total} sources",
+    "source_read": "Read {source_id} ({bytes} bytes)",
+    "sources_parsed_started": "Started opening {total} sources",
+    "source_parsed": "Opened {source_id}: {rows} rows, {columns} columns",
+    "evidence_matched": "Sources matched their proposals: {matched} of {total}",
+    "cleaning_started": "Started {total} cleaning steps",
+    "cleaning_applied": "Cleaning step {step_index} of {step_total} on {source_id}: {operation}",
+    "sources_profiled": "Cleaned sources profiled: {sources} sources, {columns} columns",
+    "join_completed": "Joined: {matched_left_rows} of {left_rows} rows matched",
+    "rows_selected": "Rows selected: {rows} rows, {columns} columns",
+    "checks_started": "Started {total} output checks",
+    "check_completed": "Check {index} of {total}: {check_id}",
+    "checks_completed": "Checks: {passed} of {total} passed",
+    "table_written": "Table written: {rows} rows, {columns} columns",
+    "members_sealed_started": "Started sealing {total} receipt parts",
+    "member_sealed": "Receipt part sealed ({bytes} bytes)",
+    "candidate_installed": "Build installed: {members} parts, {bytes} bytes",
+    "snapshot_verify_started": "Started checking {total} receipt parts",
+    "member_verified": "Receipt part checked ({bytes} bytes)",
+    "snapshot_verified": "Build checked: {members} parts match",
+    "build_sealed": "Receipt sealed",
+    "build_failed": "Build stopped: {message}",
+    "run_interrupted": "Build interrupted",
+    "notebook_sidecar_started": "Generating table notebook",
+    "notebook_sidecar_ready": "Table notebook ready",
+    "notebook_sidecar_failed": "Table notebook could not be rendered ({code})",
+}
+
+STOPPED_EVENTS = frozenset({"build_failed", "run_interrupted"})
+
+
+# A fixed span vocabulary makes the rendered block bounded independently of source, check, and
+# receipt-member counts. Per-unit records update one existing line; they never create another line.
+BUILD_SPANS: tuple[Mapping[str, Any], ...] = (
+    {
+        "key": "prepare",
+        "label": "Start the Build",
+        "complete": "run_started",
+    },
+    {"key": "rights", "label": "Check source rights", "complete": "rights_checked"},
+    {
+        "key": "read",
+        "label": "Read source bytes",
+        "start": "sources_read_started",
+        "unit": "source_read",
+        "unique": "source_id",
+        "noun": "sources read",
+    },
+    {
+        "key": "open",
+        "label": "Open source data",
+        "start": "sources_parsed_started",
+        "unit": "source_parsed",
+        "unique": "source_id",
+        "noun": "sources opened",
+    },
+    {"key": "match", "label": "Match source evidence", "complete": "evidence_matched"},
+    {
+        "key": "clean",
+        "label": "Apply declared cleaning",
+        "start": "cleaning_started",
+        "unit": "cleaning_applied",
+        "unique": "step_index",
+        "noun": "steps applied",
+    },
+    {"key": "profile", "label": "Profile cleaned sources", "complete": "sources_profiled"},
+    {"key": "join", "label": "Join sources", "complete": "join_completed"},
+    {"key": "select", "label": "Select dataset rows", "complete": "rows_selected"},
+    {
+        "key": "checks",
+        "label": "Run output checks",
+        "start": "checks_started",
+        "unit": "check_completed",
+        "unique": "index",
+        "complete": "checks_completed",
+        "noun": "checks run",
+    },
+    {"key": "write", "label": "Write the table", "complete": "table_written"},
+    {
+        "key": "seal",
+        "label": "Seal receipt parts",
+        "start": "members_sealed_started",
+        "unit": "member_sealed",
+        "unique": "evidence.member",
+        "noun": "parts sealed",
+    },
+    {"key": "install", "label": "Install the Build", "complete": "candidate_installed"},
+    {
+        "key": "verify",
+        "label": "Check the installed Build",
+        "start": "snapshot_verify_started",
+        "unit": "member_verified",
+        "unique": "evidence.member",
+        "complete": "snapshot_verified",
+        "noun": "parts checked",
+    },
+    {"key": "finish", "label": "Finish the Build", "complete": "build_sealed"},
+)
+
+
+def sentence(event: str, facts: Mapping[str, Any]) -> str:
+    """Render one event in plain words, retaining a safe fallback for producer drift."""
+
+    template = EVENT_SENTENCES.get(event)
+    if template is None:
+        return event.replace("_", " ")
+    try:
+        return template.format(**facts)
+    except (KeyError, IndexError, ValueError, TypeError):
+        return event.replace("_", " ")
+
+
+def _facts(record: Mapping[str, Any]) -> Mapping[str, Any]:
+    value = record.get("facts")
+    return value if isinstance(value, Mapping) else {}
+
+
+def _moment(record: Mapping[str, Any]) -> float | None:
+    value = record.get("at")
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    return None
+
+
+def _unique_value(record: Mapping[str, Any], key: str) -> object | None:
+    if key == "evidence.member":
+        evidence = record.get("evidence")
+        return evidence.get("member") if isinstance(evidence, Mapping) else None
+    return _facts(record).get(key)
+
+
+def _sequence(record: Mapping[str, Any]) -> int | None:
+    value = record.get("seq")
+    if isinstance(value, int) and not isinstance(value, bool) and value > 0:
+        return value
+    return None
+
+
+def _valid_sidecar_record(
+    record: Mapping[str, Any],
+    event: str,
+    *,
+    previous: Mapping[str, Any],
+) -> bool:
+    """Admit one schema-valid, evidence-free record at the next fixed sequence position."""
+
+    if (
+        record.get("event") != event
+        or "evidence" not in record
+        or record.get("evidence") is not None
+    ):
+        return False
+    facts = record.get("facts")
+    try:
+        validate_facts(event, facts)  # type: ignore[arg-type]
+    except ValueError:
+        return False
+    sequence = _sequence(record)
+    previous_sequence = _sequence(previous)
+    moment = _moment(record)
+    previous_moment = _moment(previous)
+    return (
+        sequence is not None
+        and previous_sequence is not None
+        and sequence == previous_sequence + 1
+        and moment is not None
+        and previous_moment is not None
+        and moment >= previous_moment
+    )
+
+
+def _latest_attempt(records: Sequence[Mapping[str, Any]]) -> list[Mapping[str, Any]]:
+    """Use the latest narrated run if malformed bytes contain two starts in one attempt."""
+
+    start = 0
+    for index, record in enumerate(records):
+        if record.get("event") == "run_started":
+            start = index
+    return list(records[start:])
+
+
+def coherent_build_seal_candidate(records: Sequence[Mapping[str, Any]]) -> str | None:
+    """Return a selected attempt's schema-valid, evidence-free terminal candidate digest."""
+
+    selected = _latest_attempt(records)
+    terminal = next(
+        (record for record in selected if record.get("event") in {"build_sealed", *STOPPED_EVENTS}),
+        None,
+    )
+    if terminal is None or terminal.get("event") != "build_sealed":
+        return None
+    if "evidence" not in terminal or terminal.get("evidence") is not None:
+        return None
+    facts = terminal.get("facts")
+    try:
+        validate_facts("build_sealed", facts)  # type: ignore[arg-type]
+    except ValueError:
+        return None
+    digest = facts.get("candidate_digest") if isinstance(facts, Mapping) else None
+    return digest if isinstance(digest, str) else None
+
+
+def reduce_lifecycle(
+    records: Sequence[Mapping[str, Any]],
+    *,
+    table_ready: bool,
+    allow_legacy_handoff: bool = True,
+) -> dict[str, Any]:
+    """Reduce real feed records to one bounded, JSON-ready lifecycle snapshot.
+
+    ``table_ready`` is the Viewer's independent verified-sidecar admission result. It authorizes
+    handoff; the untrusted feed narrates the Build but never authorizes access to dataset bytes.
+    """
+
+    bounded = list(records)
+    post_seal: list[Mapping[str, Any]] = []
+    following: list[Mapping[str, Any]] = []
+    sidecar_narrated = False
+    first_terminal = next(
+        (
+            index
+            for index, record in enumerate(bounded)
+            if record.get("event") in {"build_sealed", *STOPPED_EVENTS}
+        ),
+        None,
+    )
+    if first_terminal is not None:
+        terminal_prefix = bounded[: first_terminal + 1]
+        terminal_name = bounded[first_terminal].get("event")
+        if terminal_name == "build_sealed":
+            following = bounded[first_terminal + 1 :]
+            sidecar_narrated = any(
+                record.get("event") in NOTEBOOK_SIDECAR_EVENT_NAMES for record in following
+            )
+            # The sidecar tail is a fixed state machine, not an arbitrary post-seal extension. A
+            # forged or malformed ordering cannot claim readiness: facts must match the declared
+            # event schema, evidence must be absent, and sequence/time must grow exactly once from
+            # the seal through started -> ready|failed. The first valid outcome is terminal; no
+            # record after it is considered part of this attempt.
+            if following and _valid_sidecar_record(
+                following[0], "notebook_sidecar_started", previous=terminal_prefix[-1]
+            ):
+                post_seal.append(following[0])
+                if len(following) > 1:
+                    outcome = following[1]
+                    outcome_name = outcome.get("event")
+                    if outcome_name in NOTEBOOK_SIDECAR_EVENT_NAMES - {
+                        "notebook_sidecar_started"
+                    } and _valid_sidecar_record(
+                        outcome,
+                        str(outcome_name),
+                        previous=post_seal[0],
+                    ):
+                        post_seal.append(outcome)
+        bounded = [*terminal_prefix, *post_seal]
+    selected = _latest_attempt(bounded) if bounded else []
+    if not selected:
+        return {
+            "status": "completed" if table_ready else "idle",
+            "phase": "Table notebook ready" if table_ready else "Research notebook",
+            "progress": 100 if table_ready else 0,
+            "started_at": None,
+            "ended_at": None,
+            "sealed": table_ready,
+            "handoff": table_ready,
+            "lines": [],
+            "terminal": None,
+            "sidecar_narrated": False,
+            "sidecar_state": "absent",
+            "legacy_handoff_allowed": allow_legacy_handoff,
+        }
+
+    by_name: dict[str, list[Mapping[str, Any]]] = {}
+    for record in selected:
+        name = record.get("event")
+        if isinstance(name, str):
+            by_name.setdefault(name, []).append(record)
+
+    terminal_record = next(
+        (record for record in selected if record.get("event") in {"build_sealed", *STOPPED_EVENTS}),
+        None,
+    )
+    terminal_name = terminal_record.get("event") if terminal_record is not None else None
+    narrated_seal = coherent_build_seal_candidate(selected) is not None
+    sealed = narrated_seal
+    stopped = terminal_name in STOPPED_EVENTS
+    sidecar_started = bool(post_seal)
+    sidecar_outcome = post_seal[-1].get("event") if post_seal else None
+    sidecar_ready = sidecar_outcome == "notebook_sidecar_ready"
+    sidecar_failed = sidecar_outcome == "notebook_sidecar_failed"
+    if not sidecar_narrated:
+        sidecar_state = "absent"
+    elif not post_seal:
+        sidecar_state = "invalid"
+    elif len(post_seal) == 1 and len(following) > 1:
+        sidecar_state = "invalid"
+    elif sidecar_ready:
+        sidecar_state = "ready"
+    elif sidecar_failed:
+        sidecar_state = "failed"
+    else:
+        sidecar_state = "started"
+    # Existing sealed feeds predate sidecar narration and retain their independently admitted
+    # handoff. A current CLI attempt announces ``started`` before touching the path, so it cannot
+    # hand off on file timing alone: both its real ``ready`` record and independent admission are
+    # required.
+    # Only a feed with no sidecar names at all is legacy. A malformed, evidence-bearing, or
+    # out-of-sequence sidecar tail is current narration that failed validation, not permission to
+    # fall back to legacy handoff.
+    handoff = (
+        narrated_seal
+        and table_ready
+        and (sidecar_ready or (allow_legacy_handoff and not sidecar_narrated))
+    )
+
+    lines: list[dict[str, str]] = []
+    completed = 0
+    for span in BUILD_SPANS:
+        start_name = span.get("start")
+        complete_name = span.get("complete")
+        unit_name = span.get("unit")
+        starts = by_name.get(str(start_name), []) if start_name else []
+        completions = by_name.get(str(complete_name), []) if complete_name else []
+        units = by_name.get(str(unit_name), []) if unit_name else []
+        if not starts and not completions and not units:
+            continue
+
+        is_done = bool(completions)
+        detail_record = completions[-1] if completions else units[-1] if units else starts[-1]
+        detail = sentence(str(detail_record.get("event", "")), _facts(detail_record))
+        if unit_name and starts:
+            total_value = _facts(starts[-1]).get("total")
+            total = (
+                total_value
+                if isinstance(total_value, int)
+                and not isinstance(total_value, bool)
+                and total_value >= 0
+                else None
+            )
+            unique_key = str(span.get("unique", ""))
+            values: set[object] = set()
+            for record in units:
+                value = _unique_value(record, unique_key)
+                if value is None:
+                    continue
+                try:
+                    hash(value)
+                except TypeError:
+                    # Reader-side fact drift must not make the live viewer fail to start.
+                    continue
+                values.add(value)
+            done = len(values)
+            if total is not None:
+                done = min(done, total)
+                is_done = is_done or done >= total
+                detail = f"{done} of {total} {span['noun']}"
+        if is_done:
+            completed += 1
+        lines.append(
+            {
+                "key": str(span["key"]),
+                "label": str(span["label"]),
+                "status": "done" if is_done else "running",
+                "detail": detail,
+            }
+        )
+
+    if stopped and terminal_record is not None:
+        lines.append(
+            {
+                "key": "stopped",
+                "label": "Build stopped",
+                "status": "failed",
+                "detail": sentence(str(terminal_name), _facts(terminal_record)),
+            }
+        )
+
+    if post_seal:
+        sidecar_record = post_seal[-1]
+        sidecar_name = str(sidecar_record.get("event", ""))
+        sidecar_status = "failed" if sidecar_failed else "done" if sidecar_ready else "running"
+        lines.append(
+            {
+                "key": "table-notebook",
+                "label": "Prepare table notebook",
+                "status": sidecar_status,
+                "detail": sentence(sidecar_name, _facts(sidecar_record)),
+            }
+        )
+
+    started_record = by_name.get("run_started", [selected[0]])[0]
+    started_at = _moment(started_record)
+    ended_at = _moment(terminal_record) if terminal_record is not None else None
+    latest = selected[-1]
+    latest_name = str(latest.get("event", ""))
+    if handoff:
+        status = "completed"
+        phase = "Build complete · table notebook ready"
+    elif sidecar_failed:
+        status = "completed"
+        phase = "Build complete · table notebook unavailable"
+    elif sidecar_ready:
+        status = "completed"
+        phase = "Build complete · checking table notebook"
+    elif sidecar_started:
+        status = "completed"
+        phase = "Build complete · generating table notebook"
+    elif sealed:
+        status = "completed"
+        phase = "Build complete · preparing table notebook"
+    elif stopped:
+        status = "failed"
+        phase = sentence(str(terminal_name), _facts(terminal_record or {}))
+    else:
+        status = "running"
+        phase = sentence(latest_name, _facts(latest))
+    progress = 100 if sealed else round(100 * completed / len(BUILD_SPANS))
+    terminal: dict[str, str | None] | None = None
+    if stopped and terminal_record is not None:
+        terminal_facts = _facts(terminal_record)
+        finding_id = terminal_facts.get("finding_id")
+        severity = terminal_facts.get("severity")
+        terminal = {
+            "event": str(terminal_name),
+            "title": "Build interrupted" if terminal_name == "run_interrupted" else "Build stopped",
+            "detail": sentence(str(terminal_name), terminal_facts),
+            "finding_id": finding_id if isinstance(finding_id, str) else None,
+            "severity": severity if isinstance(severity, str) else None,
+        }
+    return {
+        "status": status,
+        "phase": phase,
+        "progress": progress,
+        "started_at": started_at,
+        "ended_at": ended_at,
+        "sealed": sealed,
+        "handoff": handoff,
+        "lines": lines,
+        "terminal": terminal,
+        "sidecar_narrated": sidecar_narrated,
+        "sidecar_state": sidecar_state,
+        "legacy_handoff_allowed": allow_legacy_handoff,
+    }
+
+
+def actual_run_started_record(
+    records: Sequence[Mapping[str, Any]],
+) -> Mapping[str, Any] | None:
+    """Return the selected attempt's real ``run_started`` record, never a fallback record."""
+
+    bounded: list[Mapping[str, Any]] = []
+    for record in records:
+        bounded.append(record)
+        if record.get("event") in {"build_sealed", *STOPPED_EVENTS}:
+            break
+    selected = _latest_attempt(bounded) if bounded else []
+    starts = [record for record in selected if record.get("event") == "run_started"]
+    return starts[0] if starts else None
+
+
+def elapsed_seconds(lifecycle: Mapping[str, Any], *, now: float) -> int | None:
+    """Return a non-negative whole-second run clock from lifecycle timestamps."""
+
+    started = lifecycle.get("started_at")
+    if not isinstance(started, (int, float)) or isinstance(started, bool):
+        return None
+    ended = lifecycle.get("ended_at")
+    stop = float(ended) if isinstance(ended, (int, float)) and not isinstance(ended, bool) else now
+    return max(0, int(stop - float(started)))
+
+
+def format_elapsed(seconds: int | None) -> str:
+    """Format the run clock without locale or wall-clock dependencies."""
+
+    if seconds is None:
+        return ""
+    hours, remainder = divmod(seconds, 3600)
+    minutes, secs = divmod(remainder, 60)
+    return f"{hours:d}:{minutes:02d}:{secs:02d}" if hours else f"{minutes:02d}:{secs:02d}"