probe-contracts 0.1.0__py3-none-any.whl

probe_contracts/__init__.py

@@ -0,0 +1,51 @@
+"""probe-contracts: what the server, the SDK/CLI and the dashboard must agree on, defined once.
+
+The front door is lazy: `import probe_contracts.scrubber` must not pay for
+pydantic and every record class. `from probe_contracts import Run` loads them.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+_RECORDS = (
+    "AnchorLevel",
+    "Artifact",
+    "ArtifactStatus",
+    "Experiment",
+    "LineageEntityType",
+    "LineageRelation",
+    "MetricNonFinite",
+    "MetricPoint",
+    "ParentRelation",
+    "Project",
+    "ProjectKind",
+    "Record",
+    "Run",
+    "RunCounts",
+    "RunStatus",
+    "Span",
+)
+
+_CLIENT_MESSAGES = (
+    "Action",
+    "Audience",
+    "ClientMessage",
+    "ClientMessageList",
+    "ClientRefusalBody",
+    "MessageCode",
+    "Severity",
+)
+
+__all__ = [*_RECORDS, *_CLIENT_MESSAGES, "CONTRACTS", "Contracts"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in _RECORDS:
+        return getattr(importlib.import_module(".records", __name__), name)
+    if name in _CLIENT_MESSAGES:
+        return getattr(importlib.import_module(".client_messages", __name__), name)
+    if name in ("CONTRACTS", "Contracts"):
+        return getattr(importlib.import_module(".probe_contracts", __name__), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

probe_contracts/agent_surface/DESIGN.md

@@ -0,0 +1,104 @@
+# contracts/probe_contracts/agent_surface: the view vocabulary both agent surfaces speak
+
+## Why one vocabulary, in a module that imports nothing (`agent_surface.py`)
+
+Probe has two agent surfaces over the same research record: the MCP server
+(`agent/src/probe/mcp/`), which external coding agents and the dashboard assistant both read
+through, and the page-generation agent (`app/generation/agent/`). Both answer the same question
+("open this run and show me its trajectory"). If they answer to different words, a researcher who
+learns one surface has learned nothing about the other, and a fix to one silently diverges from
+the other. The MCP already fixed a lineage bug by making that view return ancestry and edges; a
+second, independent matrix would re-break it.
+
+So the vocabulary lives here with no dependencies: the backend reads it directly, and it is
+generated into the agent package (`agent/tools/codegen/gen_views.py`, `make gen-views`). That is the
+direction `agent/schema/openapi.json` already flows: the agent pulls from the backend, the backend
+never writes into the agent.
+
+Coverage may differ, spelling may not. `VIEW_MATRIX` is the union of what the surfaces offer,
+because they genuinely differ. Each surface declares the subset it serves and a test holds it to
+that. Neither may invent a second word for a read the other already named.
+
+## trial (`ViewKind.TRIAL`, 0135)
+
+A rollout as an entity, not a span. It is reached by its rollout span id, which is both the URL
+identity the dashboard uses and the durable metric-point -> rollout -> manifest join, so an agent
+handed a trial link opens the same record a person is looking at. It carries an authored title,
+description and notes, which is what makes it an entity rather than a filter on a run's spans: a
+caveat written on one rollout is invisible from the run that contains 500.
+
+`View.TRIALS` lists them under a run, named like `GROUPS` on an experiment: a trial only ever
+exists under one run, so enumerating them is a view on the container, not a listing with a
+mandatory parent. Before it, a run's trials were reachable only by reading every span the run
+logged and filtering for `rollout`, which returns the span, not the authored Trial, so it cannot
+see a title, a description or a note.
+
+## trial views (the `ViewKind.TRIAL` row of `VIEW_MATRIX`)
+
+A trial is not a notes carrier, the only research entity that is not: a rollout ran once and is
+immutable afterwards, so `description` holds what a later reader needs, and a notes document
+beside it is one more place to look. So it gets identity plus the one read that is its own.
+
+`trajectory` is not reachable by narrowing the run's: the rollout's descendants are a subtree,
+and the spans route filters by direct `parent_span_id` only, so an agent asking a run for "the
+spans of trial X" gets one level and reads it as the whole rollout.
+
+No `artifacts` and no `diff`, both on purpose:
+
+- Run artifacts carry a `span_id`, but the list route has no `span_id` filter, so the view could
+  only narrow a bounded page client-side and would report "no artifacts" for a trial whose
+  manifest sat past the cap.
+- `diff` stays on the run because the sandbox-state route is keyed by the provider's trial name,
+  which a researcher-customized `Trial.name` no longer matches; pointing it at a trial id would
+  404 exactly on the trials someone had bothered to rename.
+
+## Other kinds and views
+
+- `ViewKind.PAPER` (0152): a kind, not a filter on the project's `papers` view, so "open this
+  paper" is a read of a thing, not a narrowing of a list.
+- `ViewKind.TEAM_NOTE`: MCP-only as a readable entity. The assistant is handed this document in
+  its system prompt every turn (`render_team_note`), so a read tool for it would be a second copy
+  of something already in context, and its cap is exactly the assistant's whole tool-result
+  budget.
+- `View.LINEAGE`: both relations, not one or the other (see `_view_run_lineage` in the MCP). The
+  ancestry walk alone answered "no lineage" for a run that had plainly consumed a dataset and
+  produced three artifacts, which an agent reads as fact. On an artifact (0255) it is the
+  file-side half of "what produced this number".
+- `View.VIEWS`: the assistant could create a saved metric view and, before this, not list one
+  back, so a view it saved last week was unfindable by the agent that saved it.
+- `View.CONTENT`: the artifact-content lane (1.36) as a view rather than a generation-only
+  expansion. Publish means publish, so an unpublished artifact refuses this view rather than
+  returning bytes.
+- `View.SUMMARY_HISTORY`: the page's history was a dashboard-only surface, and a recorder that
+  rewrites the summary needs to see what it is replacing and what a person last wrote.
+- `View.PICKS` (#3624): the current pick rode the branches header alone, so pick churn (who
+  overwrote whose pick, and how often) was unreadable by agents.
+
+## VIEW_PURPOSE
+
+One agent-facing line per view, for the error a wrong view raises: it lists the kind's views with
+what each returns. `available_views` on a response stays a bare list (see `_views_offered` in the
+agent's MCP service for why).
+
+Separate from the `#:` comments on `View`, deliberately. Those are for whoever maintains the file
+and say why a view exists, which incident shaped it, what it used to do wrong. The purpose lines
+say what an agent gets if it asks, in one line, and nothing else: a maintainer's note shipped into
+a tool response is context spent on history the caller cannot act on.
+
+Kept beside `VIEW_MATRIX` rather than in the MCP package for the same reason as the matrix: two
+agent surfaces answer with the same words, and a second copy of the vocabulary goes stale. A view
+absent here still works; the list surfaces print its name bare, as they all did before this
+existed (`tests/unit/core/test_agent_view_vocabulary_is_generated.py` still requires a line for every
+view).
+
+## GENERATION_VIEWS
+
+The subset the generation surface serves, declared rather than discovered. It is a third surface,
+and the one that cannot afford a silent miss: an unserved (kind, view) that falls through to a
+card returns a confident answer to a different question, and the summary says it checked
+something it never read. So the pairs are enumerated, a structural test holds the dispatcher to
+exactly this table, and anything outside it refuses by naming what is valid.
+
+It is narrower than `VIEW_MATRIX` where a read has no in-process reader yet (`reproduce`,
+`events`, `diff`, `views`, `handoff`, `code`, `readme`). Those are gaps to close, not words to
+invent: the spelling is already agreed.

probe_contracts/agent_surface/__init__.py

@@ -0,0 +1 @@
+"""The view vocabulary both agent surfaces speak (`agent_surface.py`)."""

probe_contracts/agent_surface/agent_surface.py

@@ -0,0 +1,360 @@
+"""The view vocabulary both agent surfaces (MCP, page generation) speak; generated into agent/.
+
+Imports nothing. Coverage may differ per surface, spelling may not. Why: DESIGN.md.
+"""
+
+from __future__ import annotations
+
+from ..compat import StrEnum
+
+
+class ViewKind(StrEnum):
+    """Entities a view can be taken on.
+
+    The shared noun list. A surface serves a subset of it and a contract test
+    holds each surface to its subset, so one surface adding a kind never
+    silently changes another's vocabulary.
+    """
+
+    PROJECT = "project"
+    EXPERIMENT = "experiment"
+    RUN = "run"
+    #: One titled sub-note (0146), by its own id (the one catalog rows and sub-note lists carry).
+    #: Card-only: the card is the document (title, body, headroom); history stays on the dashboard.
+    SUB_NOTE = "sub_note"
+    #: One rollout as an entity, not a span (0135): it carries an authored title, description and notes.
+    #: Reached by its rollout span id, the dashboard's URL identity. Why: DESIGN.md (trial).
+    TRIAL = "trial"
+    ARTIFACT = "artifact"
+    #: One paper (0152) a research project was built from. A kind, not a filter on `papers`: it has its
+    #: own row, distilled record and citation identity (`source_ref.paper_id`).
+    PAPER = "paper"
+    GROUP = "group"
+    SESSION = "session"
+    #: The tenant's one shared note. MCP-only: the assistant gets it in its system prompt every turn
+    #: (`render_team_note`), and its cap is the assistant's whole tool-result budget.
+    TEAM_NOTE = "team-note"
+    #: The data catalog (C3/C4): a team dataset and its versions, an external source, a checkpoint.
+    #: Reached by prefix ref only (`app/catalog/refs.py`). MCP-only today.
+    DATASET = "dataset"
+    SOURCE = "source"
+    CHECKPOINT = "checkpoint"
+
+
+class View(StrEnum):
+    """One word per purpose-shaped read.
+
+    THIS IS THE THIN HARNESS. Capability lives in this parameter rather than in
+    extra tools, so reading a trajectory costs a `view` value and not a
+    `read_run_spans` entry in every turn's catalog. The MCP's own contract module
+    says the same thing in the same words, which is the point.
+    """
+
+    #: The cheap identity/status glance, and the default everywhere.
+    CARD = "card"
+    #: Explicit complete-record read on MCP; supports selecting one nested field.
+    #: Delivery is bounded separately from the stored record's shape.
+    RECORD = "record"
+    #: The spans themselves, not span-type COUNTS.
+    TRAJECTORY = "trajectory"
+    #: Both relations on a run: the parent/child walk and artifact provenance edges (`_view_run_lineage`).
+    #: The walk alone said "no lineage" for a run that consumed a dataset and produced 3 artifacts.
+    LINEAGE = "lineage"
+    #: Everything needed to run it again, plus an honest completeness verdict.
+    REPRODUCE = "reproduce"
+    #: The append-only lifecycle log.
+    EVENTS = "events"
+    #: Saved metric views. Without it an agent could save a view but never list it back.
+    VIEWS = "views"
+    #: One trial's begin/end filesystem diff. Needs a `trial`, which comes off
+    #: the run's own files.
+    DIFF = "diff"
+    #: Which coding sessions produced this thing.
+    SESSIONS = "sessions"
+    #: The files registered under this entity. MCP-only as a VIEW.
+    ARTIFACTS = "artifacts"
+    #: Free-text notes as a document of their own.
+    NOTES = "notes"
+    #: Sweeps and ensembles under an experiment.
+    GROUPS = "groups"
+    #: Rollouts under a run (like `GROUPS` on an experiment: a trial has one parent run). Filtering the
+    #: run's spans for `rollout` returns spans, not authored Trials, so no title, description or note.
+    TRIALS = "trials"
+    #: Immutable published manifests.
+    VERSIONS = "versions"
+    #: A session's normalized transcript, in bounded sections.
+    TRANSCRIPT = "transcript"
+    #: A project's rendered README.
+    README = "readme"
+    #: Dashboard-visible authored Markdown on a project, experiment or run.
+    SUMMARY = "summary"
+    #: Complete unified saved Overview, including generated and authored content.
+    OVERVIEW = "overview"
+    #: Series summaries. MCP-only; the MCP's `metrics` tool is the richer
+    #: per-grain read.
+    METRICS = "metrics"
+    #: Everything a new session needs to continue. MCP-only today.
+    HANDOFF = "handoff"
+    #: GitHub resolution per grain: a project's code sources and proxied timeline; an experiment's per-run
+    #: `owner/repo@sha` and stored commit window; a run's own (compare diffs another). MCP-only today.
+    CODE = "code"
+    #: A published document's own text, bounded (the artifact-content lane, 1.36, as a view). An
+    #: unpublished artifact refuses it; everything else about an artifact stays metadata.
+    CONTENT = "content"
+    #: A project's papers (0152), one row each: the paper's idea, the repo read alongside it, where they
+    #: disagree. MCP-only today; the dashboard shows the same rows as a tab.
+    PAPERS = "papers"
+    #: What a fork reads live from its source: its runs as they were at the fork, or their files. Same
+    #: word in the API and CLI (`GET .../experiments/{E}/inherited`, `probe experiment inherited`).
+    INHERITED = "inherited"
+    #: A project's or experiment's summary versions, newest first (who, when, via what), or one by number.
+    #: MCP-only; a recorder rewriting the summary must see what it replaces and what a person last wrote.
+    SUMMARY_HISTORY = "summary_history"
+    #: Lines of work: a project's tree, or an experiment's line and those it split from; best value on the
+    #: declared metric, effort, state, links (swarm D6). MCP-only; workspace: `browse mode=branches`.
+    BRANCHES = "branches"
+    #: A project's best-pick history, newest first: each pick and clear, who and why (#3624). The branches
+    #: header shows only the current pick, hiding churn. MCP-only; workspace: rides `browse mode=branches`.
+    PICKS = "picks"
+
+
+#: What a view MEANS on a kind. The union across both surfaces; each declares the
+#: subset it serves. A pair absent here is a pair neither surface may invent.
+VIEW_MATRIX: dict[ViewKind, frozenset[View]] = {
+    ViewKind.SUB_NOTE: frozenset({View.CARD}),
+    ViewKind.PROJECT: frozenset(
+        {
+            View.CARD,
+            View.RECORD,
+            View.NOTES,
+            View.SUMMARY,
+            View.README,
+            View.OVERVIEW,
+            View.SESSIONS,
+            View.ARTIFACTS,
+            View.CODE,
+            View.PAPERS,
+            # lineage plan 2 (L12/L18): its OWN links, in and out, and its
+            # children each with a derived origin (GET /v1/projects/{id}/lineage).
+            View.LINEAGE,
+            # The summary's versions (GET /v1/projects/{P}/summary/versions[/{v}]).
+            View.SUMMARY_HISTORY,
+            # Its tree's lines of work (GET /v1/projects/{P}/branches).
+            View.BRANCHES,
+            # Its best pick's history (GET /v1/projects/{P}/best?history=N).
+            View.PICKS,
+        }
+    ),
+    ViewKind.EXPERIMENT: frozenset(
+        {
+            View.CARD,
+            View.RECORD,
+            View.NOTES,
+            View.GROUPS,
+            View.VERSIONS,
+            View.REPRODUCE,
+            View.LINEAGE,
+            View.SESSIONS,
+            View.ARTIFACTS,
+            View.SUMMARY,
+            View.OVERVIEW,
+            # integrations-v2 phase 6: repo changes between this experiment's runs
+            # (stored rows only; GET /v1/experiments/{ref}/code).
+            View.CODE,
+            # A fork's runs and files read live from its source
+            # (GET /v1/projects/{P}/experiments/{E}/inherited).
+            View.INHERITED,
+            # The summary's versions
+            # (GET /v1/projects/{P}/experiments/{E}/summary/versions[/{v}]).
+            View.SUMMARY_HISTORY,
+            # Its own line of work and the ones it split from
+            # (GET /v1/projects/{P}/experiments/{E}/branch).
+            View.BRANCHES,
+        }
+    ),
+    ViewKind.RUN: frozenset(
+        {
+            View.CARD,
+            View.RECORD,
+            View.NOTES,
+            View.TRAJECTORY,
+            View.LINEAGE,
+            View.REPRODUCE,
+            View.EVENTS,
+            View.VIEWS,
+            View.DIFF,
+            View.SESSIONS,
+            View.METRICS,
+            View.HANDOFF,
+            View.ARTIFACTS,
+            View.TRIALS,
+            # integrations-v2 phase 6: the run's owner/repo@sha, and a diff against another run
+            # (GET /v1/runs/{ref}/code and /code/compare).
+            View.CODE,
+        }
+    ),
+    # The one entity with no notes (immutable; `description` holds it). Its `trajectory` is its whole
+    # subtree, which narrowing the run's cannot give; no `artifacts` or `diff`: DESIGN.md (trial views).
+    ViewKind.TRIAL: frozenset({View.CARD, View.RECORD, View.TRAJECTORY}),
+    #: `lineage` (0255): which run wrote this file and which read it. No `notes` here or on a group: since
+    #: 2026-10-16 a file is described in its run's notes, a sweep in its experiment's.
+    ViewKind.ARTIFACT: frozenset(
+        {
+            View.CARD,
+            View.RECORD,
+            View.VERSIONS,
+            View.SESSIONS,
+            View.CONTENT,
+            View.LINEAGE,
+        }
+    ),
+    ViewKind.GROUP: frozenset({View.CARD, View.RECORD}),
+    #: `card` is the distilled record (row plus digest, what comparisons use). No separate `digest`
+    #: view: the useful read would always be the second call.
+    ViewKind.PAPER: frozenset({View.CARD}),
+    ViewKind.SESSION: frozenset({View.CARD, View.RECORD, View.TRANSCRIPT}),
+    ViewKind.TEAM_NOTE: frozenset({View.CARD, View.RECORD}),
+    #: `versions`: a dataset's versions, a checkpoint's run's other saves. `lineage`: the provenance walk
+    #: (`GET /v1/provenance`), which reaches sources. A source has no versions: its revision is in its key.
+    ViewKind.DATASET: frozenset({View.CARD, View.RECORD, View.VERSIONS, View.LINEAGE}),
+    ViewKind.CHECKPOINT: frozenset({View.CARD, View.RECORD, View.VERSIONS, View.LINEAGE}),
+    ViewKind.SOURCE: frozenset({View.CARD, View.RECORD, View.LINEAGE}),
+}
+
+
+#: One agent-facing line per view (what it returns, no history), for the error a wrong view raises.
+#: `available_views` stays bare (`_views_offered`, MCP service); a view absent here prints bare. DESIGN.md.
+VIEW_PURPOSE: dict[View, str] = {
+    View.CARD: "identity, status, and this kind's available_views",
+    View.RECORD: "the raw source record, pageable; one field via view_options.field",
+    View.SUMMARY: "the person-written block of the Overview page (`document`)",
+    View.OVERVIEW: "the complete saved Overview page: generated content, authored edits and chart data",
+    View.NOTES: "hidden operational notes: decisions, caveats, handoffs",
+    View.ARTIFACTS: "the files the work produced at this grain",
+    View.VERSIONS: "an artifact's or dataset's versions (a checkpoint: its run's saves); the reuse check",
+    View.METRICS: "series summaries; view_options.key drills to raw points",
+    View.TRAJECTORY: "the spans themselves -- ask a TRIAL for one rollout's subtree",
+    View.TRIALS: "the run's authored trials, newest step first",
+    View.EVENTS: "the append-only lifecycle log",
+    View.LINEAGE: "what it came from: parents, files read, and who wrote them",
+    View.REPRODUCE: "everything needed to run it again, plus a completeness verdict",
+    View.HANDOFF: "what a new session needs to continue the work",
+    View.CODE: "the GitHub resolution at this grain; diff with view_options.compare_to",
+    View.GROUPS: "sweeps and ensembles under an experiment",
+    View.PAPERS: "the literature attached to this project",
+    View.TRANSCRIPT: "a captured session's text; view_options.grep or view_options.start_line",
+    View.SESSIONS: "the captured agent sessions that touched this entity",
+    View.CONTENT: "the artifact's own bytes",
+    View.README: "the repository's README at this grain",
+    View.VIEWS: "saved metric views on this entity",
+    View.DIFF: "what changed, against the comparison this kind defines",
+    View.INHERITED: "what a fork reads live from its source: its files, or its runs with runs=true",
+    View.SUMMARY_HISTORY: "the summary's versions, newest first; view_options.version=N reads one's markdown",
+    View.BRANCHES: "lines of work: best value, effort, state; view_options.branch for one in full",
+    View.PICKS: "the best pick's history, newest first: who picked or cleared what, and why",
+}
+
+
+class MissingMarker(StrEnum):
+    """Why a payload is incomplete, in words a model can act on.
+
+    A view that clips and says nothing is worse than one that refuses: the model
+    reads a short list as a complete list and answers confidently from it. Every
+    projection that can clip must emit one of these.
+    """
+
+    #: The server capped the rows before we saw them, and the route takes no
+    #: offset -- so paging here would page an already-truncated list.
+    ROWS_CAPPED_BY_SERVER = "rows_capped_by_server"
+    #: We asked for a window and the window filled. Move the window, do not page.
+    WINDOW_FULL = "window_full"
+    #: The source route answered, but with a degraded body (legacy rows).
+    SOURCE_DEGRADED = "source_degraded"
+
+
+class Admits(StrEnum):
+    """What citing power a GRANTED view hands the summary writer.
+
+    THE HALF THAT MAKES CITING SAFE, as a table rather than as a branch. A
+    Tier-2 grant widens the context and the allowed-ref set together, and the
+    two must move as one -- so the rule lives beside the view it belongs to
+    rather than inside an `elif` chain that a new view forgets to extend.
+
+    Route-specific ON PURPOSE. A generic "admit whatever came back" reads a
+    session digest's incidental run mention as a citeable measurement, and a
+    card's `project_id` as something a metric block may point at.
+    """
+
+    #: Prose about a thing, not a reading of it. Nothing here is a source.
+    NOTHING = "nothing"
+    #: The rows the DATABASE returned become citeable -- never the ids asked
+    #: for, which is how a scoped-out request stops being an existence oracle.
+    RETURNED_IDS = "returned_ids"
+    #: A metric read: the run AND the (run, key) pairs it actually carried.
+    RUN_AND_METRIC_KEYS = "run_and_metric_keys"
+
+
+#: Per view, not per kind: a `card` admits its own row's id, run or paper. A view absent here admits
+#: NOTHING, asserted by a test so a new view cannot silently inherit citing power.
+VIEW_ADMISSION: dict[View, Admits] = {
+    View.CARD: Admits.RETURNED_IDS,
+    View.RECORD: Admits.NOTHING,
+    View.ARTIFACTS: Admits.RETURNED_IDS,
+    View.TRIALS: Admits.RETURNED_IDS,
+    View.GROUPS: Admits.RETURNED_IDS,
+    View.VERSIONS: Admits.RETURNED_IDS,
+    View.LINEAGE: Admits.RETURNED_IDS,
+    View.PAPERS: Admits.RETURNED_IDS,
+    View.INHERITED: Admits.RETURNED_IDS,
+    View.TRAJECTORY: Admits.RETURNED_IDS,
+    View.METRICS: Admits.RUN_AND_METRIC_KEYS,
+    # Prose and documents: readable evidence, never a citation source.
+    View.NOTES: Admits.NOTHING,
+    View.SESSIONS: Admits.NOTHING,
+    View.TRANSCRIPT: Admits.NOTHING,
+    View.SUMMARY: Admits.NOTHING,
+    View.SUMMARY_HISTORY: Admits.NOTHING,
+    View.OVERVIEW: Admits.NOTHING,
+    View.README: Admits.NOTHING,
+    View.CONTENT: Admits.NOTHING,
+    View.REPRODUCE: Admits.NOTHING,
+    View.EVENTS: Admits.NOTHING,
+    View.HANDOFF: Admits.NOTHING,
+    View.CODE: Admits.NOTHING,
+    View.DIFF: Admits.NOTHING,
+    View.VIEWS: Admits.NOTHING,
+    # Computed standings and effort: a reading of many records, not one.
+    View.BRANCHES: Admits.NOTHING,
+    # Who chose what, and when: a judgement about results, never a reading of one.
+    View.PICKS: Admits.NOTHING,
+}
+
+
+#: The pairs the generation surface serves; a test holds its dispatcher to exactly this, and any other
+#: pair refuses, naming what is valid. Narrower than VIEW_MATRIX: DESIGN.md (GENERATION_VIEWS).
+GENERATION_VIEWS: dict[ViewKind, frozenset[View]] = {
+    ViewKind.PROJECT: frozenset(
+        {View.CARD, View.NOTES, View.SESSIONS, View.PAPERS, View.ARTIFACTS, View.SUMMARY}
+    ),
+    ViewKind.EXPERIMENT: frozenset(
+        {View.CARD, View.NOTES, View.SESSIONS, View.LINEAGE, View.ARTIFACTS, View.SUMMARY}
+    ),
+    ViewKind.RUN: frozenset(
+        {
+            View.CARD,
+            View.NOTES,
+            View.SESSIONS,
+            View.LINEAGE,
+            View.METRICS,
+            View.ARTIFACTS,
+            View.TRIALS,
+            # No `summary`: 0220 removed a run's authored document (a column, never on the
+            # Overview page lane), so there is nothing to read.
+        }
+    ),
+    ViewKind.TRIAL: frozenset({View.CARD, View.TRAJECTORY}),
+    # No `notes`: an artifact carries a `description`, not a notes document.
+    ViewKind.ARTIFACT: frozenset({View.CARD, View.VERSIONS, View.CONTENT}),
+    ViewKind.SESSION: frozenset({View.CARD}),
+    ViewKind.PAPER: frozenset({View.CARD}),
+}

probe_contracts/analytics/__init__.py

@@ -0,0 +1,5 @@
+"""The product-analytics event catalog (events.json) and its checked loader."""
+
+from .analytics import CATALOG_PATH, CatalogError, CatalogEvent, CatalogGroup, EventCatalog, Runtime
+
+__all__ = ["CATALOG_PATH", "CatalogError", "CatalogEvent", "CatalogGroup", "EventCatalog", "Runtime"]

probe_contracts/analytics/analytics.py

@@ -0,0 +1,116 @@
+"""EventCatalog: the one list of product-analytics events (events.json beside it), checked on load.
+
+Codegen draws each runtime's `Event` enum from it; nothing reads the JSON at run time.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..compat import StrEnum
+
+#: The catalog this package ships.
+CATALOG_PATH = Path(__file__).with_name("events.json")
+
+_KEY = re.compile(r"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*")
+
+
+class Runtime(StrEnum):
+    """Who sends an event. `plugin` is the hooks, which keep their own constants (no generated enum)."""
+
+    SERVER = "server"
+    AGENT = "agent"
+    PLUGIN = "plugin"
+    DASHBOARD = "dashboard"
+
+
+@dataclass(frozen=True)
+class CatalogEvent:
+    """One event: its enum key (UPPER_SNAKE), wire name, who sends it and a one-line why."""
+
+    key: str
+    name: str
+    runtimes: tuple[Runtime, ...]
+    doc: str = ""
+
+
+@dataclass(frozen=True)
+class CatalogGroup:
+    """A titled run of related events, drawn as a comment block in each generated enum."""
+
+    title: str
+    events: tuple[CatalogEvent, ...]
+    doc: str = ""
+
+
+class CatalogError(ValueError):
+    """events.json breaks a catalog rule (named in the message)."""
+
+
+@dataclass(frozen=True)
+class EventCatalog:
+    about: str
+    groups: tuple[CatalogGroup, ...]
+
+    @classmethod
+    def load(cls, path: Path = CATALOG_PATH) -> EventCatalog:
+        """Read and check a catalog: unique keys and names, UPPER_SNAKE keys, known runtimes."""
+        data = json.loads(path.read_text(encoding="utf-8"))
+        groups = tuple(
+            CatalogGroup(
+                title=group["title"],
+                doc=group.get("doc", ""),
+                events=tuple(
+                    CatalogEvent(
+                        key=event["key"],
+                        name=event["name"],
+                        runtimes=tuple(Runtime(r) for r in event["runtimes"]),
+                        doc=event.get("doc", ""),
+                    )
+                    for event in group["events"]
+                ),
+            )
+            for group in data["groups"]
+        )
+        catalog = cls(about=data["about"], groups=groups)
+        catalog.check()
+        return catalog
+
+    @property
+    def events(self) -> tuple[CatalogEvent, ...]:
+        return tuple(event for group in self.groups for event in group.events)
+
+    def check(self) -> None:
+        """Raise CatalogError on the first broken rule. A name is unique in the whole catalog; a key
+        only within a runtime (the server's `onboarding.completed` and the browser's
+        `onboarding_completed` are both ONBOARDING_COMPLETED in their own enum)."""
+        keys: set[tuple[Runtime, str]] = set()
+        names: set[str] = set()
+        for event in self.events:
+            if not _KEY.fullmatch(event.key):
+                raise CatalogError(f"{event.name}: key {event.key!r} is not UPPER_SNAKE")
+            if event.name in names:
+                raise CatalogError(f"name {event.name!r} is used twice")
+            if not event.runtimes or len(set(event.runtimes)) != len(event.runtimes):
+                raise CatalogError(f"{event.key}: runtimes must be a non-empty list without repeats")
+            for runtime in event.runtimes:
+                if (runtime, event.key) in keys:
+                    raise CatalogError(f"{runtime} key {event.key} is used twice")
+                keys.add((runtime, event.key))
+            names.add(event.name)
+
+    def get_groups(self, runtime: Runtime) -> tuple[CatalogGroup, ...]:
+        """The groups with an event `runtime` sends, holding only those events, in catalog order."""
+        kept = []
+        for group in self.groups:
+            events = tuple(e for e in group.events if runtime in e.runtimes)
+            if events:
+                kept.append(CatalogGroup(title=group.title, events=events, doc=group.doc))
+        return tuple(kept)
+
+    def get_names(self, runtime: Runtime) -> list[str]:
+        """Every wire name `runtime` sends, in catalog order."""
+        return [event.name for group in self.get_groups(runtime) for event in group.events]