mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/narrative.py

@@ -0,0 +1,589 @@
+"""``mr-data note``: the agent's decision record, written into the hosted run's own log.
+
+WHAT WAS MISSING. The local notebook let the agent driving a build write the operator-facing
+decision record -- outcome-led ``##`` headings, cells checkpointed against what had just happened,
+a revision when a conclusion changed. The hosted notebook (Studio #88) renders from the run header
+and the event log and nothing else, and the only client-writable path into that log was the fenced
+worker surface, whose producer vocabulary is a closed, attempt-scoped six-value enum. So a hosted
+run kept every number the local one had and lost every sentence: it could say what happened and
+never why. This repository wrote that gap down as a fact of the hosted profile and told the agent
+not to try -- which was the honest thing to say while it was true, and is no longer true.
+
+Studio PR #98 added ``POST /v3/runs/{run_id}/narrative`` under a new ``run:narrate`` scope, narrow
+the way ``approval:request`` is narrow: it grants exactly one power, causing a row that says
+somebody wrote something. That scope is reachable by the organisation service principal the thin
+CLI runs as, which is the entire point -- an autonomous agent can now write the record a person
+reads, without being able to decide, release, or approve anything.
+
+WHAT A CELL IS, AND IS NOT. It is a durable ``run_narrative_appended`` event carrying an explicitly
+UNSEALED adjunct. The sealed record's only content is a ``payload_digest``, so the prose is
+tamper-evident inside the log while claiming no authority: it is never attestation evidence, no
+receipt quotes it, and no verifier reads it. ``sealed`` comes back ``false`` on every cell and this
+lane asserts it rather than assuming it, because "not evidence" is the property the whole design
+rests on and a client that stopped checking would be the first place it could quietly stop being
+true.
+
+⚠ THE BOUNDS ARE ENFORCED HERE TOO, IN STUDIO'S OWN WORDS. 65536 UTF-8 **bytes** of markdown, a
+200-character single-line heading, and no control character but tab and newline -- carriage return
+included, refused rather than normalised, because normalising would mean the digest binds bytes
+the client never sent. Studio refuses all three itself; checking them here as well is not
+belt-and-braces. An agent that has just composed four pages of prose should learn that it is one
+kilobyte over the ceiling before the round trip and before the idempotency key is spent, and it
+should read the same sentence either way -- so the messages below are Studio's, copied
+deliberately, and ``tests/test_thin_narrative.py`` holds them equal to the contract's bounds.
+
+⚠ WHAT THIS MODULE MAY NOT DO. Append, and list. There is no delete and no edit-in-place: a
+correction is a new append that supersedes, the superseded cell stays in the log, and the record of
+what was thought earlier survives being wrong. :data:`RUN_NARRATIVE_PATH` is the only route here
+and both verbs are on it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from collections.abc import Mapping, Sequence
+from typing import Any
+from uuid import UUID
+
+from mostlyright.data_harness.thin import THIN_SCHEMA_PREFIX
+from mostlyright.data_harness.thin.parity import _no_effect, _run_id
+from mostlyright.data_harness.thin.runs import StudioApiClient, new_idempotency_key
+from mostlyright.data_harness.thin.session import StudioSession, open_studio_session
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+
+NOTE_SCHEMA = f"{THIN_SCHEMA_PREFIX}-narrative.v1"
+
+#: The one route, and both verbs are on it. POST appends a cell, GET lists every cell this run
+#: holds, superseded revisions included and flagged.
+RUN_NARRATIVE_PATH = "/v3/runs/{run_id}/narrative"
+
+#: The automation scope the append needs. Not checked here -- a client cannot check its own
+#: authority, and pretending to would only teach a reader to trust the wrong assertion. It is
+#: written down so the refusal a caller without it gets has a name in this file to match against.
+NARRATE_SCOPE = "run:narrate"
+
+#: ``run-narrative.schema.json#/$defs/markdown``, counted in BYTES. The character bound in the
+#: schema is its loosest possible restatement; the API enforces this one.
+MAX_MARKDOWN_BYTES = 65536
+
+#: ``run-narrative.schema.json#/$defs/heading``.
+MAX_HEADING_CHARS = 200
+
+#: ``run-narrative.schema.json#/$defs/cell_id``.
+MAX_CELL_ID_CHARS = 64
+
+#: ``run-narrative.schema.json#/$defs/checkpoint_seq``. The contract's own ceiling, which is
+#: JavaScript's exact-integer bound rather than a statement about how long a run can be.
+MAX_CHECKPOINT_SEQ = 9007199254740991
+_CELL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+#: Every control character the body admits. Tab and newline, and nothing else -- carriage return
+#: is a control character here and is refused rather than stripped.
+_BODY_ALLOWED_CONTROLS = frozenset("\t\n")
+
+#: A heading is one line by construction, so it admits none of them at all.
+_HEADING_ALLOWED_CONTROLS: frozenset[str] = frozenset()
+
+#: What a cursor from ``mr-data watch`` looks like: the same fixed-width, zero-padded decimal the
+#: event stream carries as ``id``. Accepted beside a bare integer because the number an agent has
+#: in its hand at a checkpoint is the one ``watch`` just printed, and making it retype that as an
+#: unpadded integer is an invitation to retype it wrong.
+_CURSOR = re.compile(r"^[0-9]{1,20}$")
+
+#: Trimmed off a slugged heading so a derived identifier never opens or closes on punctuation.
+_SLUG_TRIM = ".-_"
+
+#: How much of the heading's digest a derived identifier carries when the slug does not fit.
+#: Eight hex characters is 32 bits over at most 512 cells in one run, which is a collision this
+#: repository is content to have never seen; the alternative, a bare truncation, collides on the
+#: ordinary case of two headings that open the same way.
+_DERIVED_DIGEST_CHARS = 8
+
+
+class StudioNarrativeClient(StudioApiClient):
+    """The two narrative calls, and no third one.
+
+    ``append_cell`` is the only mutation this lane can make, and what it can cause is one row
+    saying somebody wrote something. It cannot start, cancel, approve or release anything: those
+    are other routes under other scopes, and none of them is reachable from here.
+    """
+
+    def append_cell(
+        self,
+        run_id: str,
+        *,
+        body: Mapping[str, Any],
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Append one cell and return it as Studio stored it, with its log coordinates."""
+
+        return self._call(
+            "POST",
+            RUN_NARRATIVE_PATH.format(run_id=run_id),
+            body=body,
+            extra_headers={
+                "Idempotency-Key": idempotency_key or new_idempotency_key("mr-data-note")
+            },
+            expected=(201,),
+        )
+
+    def run_narrative(self, run_id: str) -> dict[str, Any]:
+        """Every cell this run holds, in log order, superseded revisions included."""
+
+        return self._call("GET", RUN_NARRATIVE_PATH.format(run_id=run_id), expected=(200,))
+
+
+def cell_id_from_heading(heading: str) -> str:
+    """A stable identifier derived from the heading, for the caller who named none.
+
+    ⚠ DERIVED, NOT RANDOM, AND THAT IS THE WHOLE POINT. ``cell_id`` is what makes a second append
+    a revision rather than a duplicate, so the default has to be a function of something the agent
+    will write the same way twice. A random id would make every correction a new cell and turn one
+    changing conclusion into three contradictory ones sitting side by side in the notebook. The
+    heading is the one thing an outcome-led cell keeps while its body is being rewritten.
+
+    A caller whose heading itself changes with the conclusion should pass ``--cell-id`` and choose
+    the stable name, which is why the flag exists and why this is a default rather than the rule.
+    """
+
+    slug = re.sub(r"[^A-Za-z0-9]+", "-", heading).strip(_SLUG_TRIM).lower()
+    if not slug:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "this heading has no letters or digits to derive a cell identifier from; name one "
+            "with --cell-id",
+        )
+    if len(slug) > MAX_CELL_ID_CHARS:
+        # ⚠ TRUNCATION ALONE WOULD COLLIDE, AND A COLLISION HERE IS AN OVERWRITE. A heading may run
+        # to two hundred characters and an identifier to sixty-four, so two headings that differ
+        # only past the cut would slug to one id -- and writing an id again is how this command
+        # revises, so the second cell would silently replace the first. The tail is therefore a
+        # digest of the whole heading rather than the part that fitted: still a function of the
+        # heading, so a revision under the same heading still lands on the same cell, and no
+        # longer a function of a prefix of it.
+        stem = slug[: MAX_CELL_ID_CHARS - _DERIVED_DIGEST_CHARS - 1].rstrip(_SLUG_TRIM)
+        tail = hashlib.sha256(heading.encode("utf-8")).hexdigest()[:_DERIVED_DIGEST_CHARS]
+        slug = f"{stem}-{tail}"
+    if _CELL_ID.fullmatch(slug) is None:  # pragma: no cover - the substitution above guarantees it
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "this heading does not derive a usable cell identifier; name one with --cell-id",
+        )
+    return slug
+
+
+def _cell_id(value: Any, *, flag: str) -> str:
+    """Refuse an identifier the contract would refuse, before it is spent on a round trip."""
+
+    if not isinstance(value, str) or not value:
+        raise ThinLaneError("THIN_REQUEST_INVALID", f"{flag} names one cell identifier")
+    if len(value) > MAX_CELL_ID_CHARS or _CELL_ID.fullmatch(value) is None:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"{flag} is at most {MAX_CELL_ID_CHARS} characters of letters, digits, dot, dash and "
+            "underscore, opening on a letter or a digit",
+        )
+    return value
+
+
+def _forbidden_control_character(value: str, admitted: frozenset[str]) -> str | None:
+    """The first control character this field may not carry, or ``None``."""
+
+    for character in value:
+        code = ord(character)
+        if (code < 0x20 or code == 0x7F) and character not in admitted:
+            return character
+    return None
+
+
+def _checkpoint(value: Any) -> int | None:
+    """One run-event sequence, from a bare integer or from a cursor ``watch`` printed."""
+
+    if value is None:
+        return None
+    if type(value) is int:
+        sequence = value
+    elif isinstance(value, str) and _CURSOR.fullmatch(value.strip()):
+        sequence = int(value.strip(), 10)
+    else:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "--checkpoint names one run-event sequence, as the number or as the cursor "
+            "mr-data watch printed beside it",
+        )
+    if sequence < 1:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID", "--checkpoint names a run-event sequence, counted from 1"
+        )
+    if sequence > MAX_CHECKPOINT_SEQ:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"--checkpoint is at most {MAX_CHECKPOINT_SEQ}, which is the largest sequence this "
+            "contract admits; no run has that many events",
+        )
+    return sequence
+
+
+def check_cell_bounds(*, heading: str, markdown: str) -> None:
+    """Refuse a cell the contract would refuse, in the words the contract would refuse it with.
+
+    Called by :func:`note` before a credential is resolved and again by :func:`append_cell_body`
+    on the way out, so the rule has one home whichever path reaches it. Not because the server is
+    untrusted: the caller is an agent that has just spent effort composing the thing being refused,
+    and it should learn the body is a kilobyte over the ceiling before the request rather than
+    after it -- reading the sentence it would have read either way.
+    """
+
+    if not isinstance(heading, str) or not heading.strip():
+        raise ThinLaneError("THIN_REQUEST_INVALID", "--heading is the cell's one outcome-led line")
+    if not isinstance(markdown, str) or not markdown:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "a cell has a body; give it on standard input or name a file with --markdown-file",
+        )
+    if len(heading) > MAX_HEADING_CHARS:
+        raise ThinLaneError(
+            "THIN_NARRATIVE_CELL_TOO_LARGE", "Narrative heading exceeds its character ceiling."
+        )
+    markdown_bytes = len(markdown.encode("utf-8"))
+    if markdown_bytes > MAX_MARKDOWN_BYTES:
+        # Bytes, not characters. The ceiling protects the object store and the browser that opens
+        # the notebook, and both count bytes -- so a body of accented prose reaches it sooner than
+        # its character count suggests, which is exactly the surprise this sentence exists to
+        # remove.
+        raise ThinLaneError(
+            "THIN_NARRATIVE_CELL_TOO_LARGE",
+            f"Narrative markdown is {markdown_bytes} bytes; the ceiling is {MAX_MARKDOWN_BYTES}.",
+        )
+    for field, value, admitted in (
+        ("heading", heading, _HEADING_ALLOWED_CONTROLS),
+        ("markdown", markdown, _BODY_ALLOWED_CONTROLS),
+    ):
+        offending = _forbidden_control_character(value, admitted)
+        if offending is not None:
+            raise ThinLaneError(
+                "THIN_NARRATIVE_CELL_CONTROL_CHARACTER",
+                f"Narrative {field} carries control character U+{ord(offending):04X}; "
+                "only tab and newline are admitted, and only in the body.",
+            )
+
+
+def append_cell_body(
+    *,
+    workspace_id: UUID,
+    run_id: str,
+    cell_id: str,
+    heading: str,
+    markdown: str,
+    checkpoint_seq: int | None = None,
+    revision_of: str | None = None,
+) -> dict[str, Any]:
+    """The ``AppendNarrativeCellCommand`` this lane sends, with the contract applied here."""
+
+    check_cell_bounds(heading=heading, markdown=markdown)
+    body: dict[str, Any] = {
+        "schema_version": "3.0.0",
+        "workspace_id": str(workspace_id),
+        "run_id": run_id,
+        "cell_id": cell_id,
+        "heading": heading,
+        "markdown": markdown,
+    }
+    if checkpoint_seq is not None:
+        body["checkpoint_seq"] = checkpoint_seq
+    if revision_of is not None:
+        if revision_of == cell_id:
+            # Reusing the id IS the revision, so accepting both spellings would make one cell its
+            # own predecessor. Studio refuses it; this refuses it one round trip earlier, because
+            # `--revise X` with no `--cell-id` is the shape a caller reaches for first.
+            raise ThinLaneError(
+                "THIN_NARRATIVE_REVISION_INVALID",
+                "A cell revises itself by reusing its cell_id, not through revision_of.",
+            )
+        body["revision_of"] = revision_of
+    return body
+
+
+def _session(args: argparse.Namespace) -> StudioSession:
+    return open_studio_session(resolve_cloud_credentials())
+
+
+def _client(args: argparse.Namespace) -> StudioNarrativeClient:
+    return StudioNarrativeClient(_session(args))
+
+
+def _read_markdown(args: argparse.Namespace, *, stdin: Any = None) -> str:
+    """The cell body: the named file, or standard input when no file was named.
+
+    Standard input is the default rather than a flag, because the caller is a program composing
+    prose and a heredoc is how a program hands over prose. A terminal with nobody typing into it is
+    not that, so it is refused by name rather than blocking forever on a read that will not come.
+    """
+
+    named = getattr(args, "markdown_file", None)
+    stream = sys.stdin if stdin is None else stdin
+    if named is not None:
+        import os
+        from pathlib import Path
+
+        from mostlyright.data_harness.ux.plain_file import (
+            PlainFileRefusal,
+            open_plain_file,
+            read_bounded,
+        )
+
+        # ⚠ `open_plain_file` RATHER THAN `read_plain_file`, for the size. A file over the ceiling
+        # is not an unreadable file, and telling somebody it could not be read is answering a
+        # question they did not ask with a fact that is not true. The descriptor's own size is the
+        # byte count the ceiling counts, so the refusal can be the ceiling's own sentence, naming
+        # the real number -- which a bounded read cannot do, because it stops before it knows it.
+        target = Path(named).expanduser()
+        try:
+            descriptor, size = open_plain_file(target)
+        except PlainFileRefusal as refusal:
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID",
+                f"--markdown-file did not name one readable file: {refusal.path}",
+            ) from refusal
+        except OSError as error:
+            # `open_plain_file` lets an OSError that is not one of its four named refusals travel,
+            # deliberately -- a permission denial is not a malformed path. It still has to arrive
+            # as a typed code rather than as a traceback out of the standard library.
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID", f"--markdown-file could not be opened: {target}"
+            ) from error
+        try:
+            if size > MAX_MARKDOWN_BYTES:
+                raise ThinLaneError(
+                    "THIN_NARRATIVE_CELL_TOO_LARGE",
+                    f"Narrative markdown is {size} bytes; the ceiling is {MAX_MARKDOWN_BYTES}.",
+                )
+            # One byte past the ceiling, so a file that GREW between the descriptor's size and the
+            # read is caught as the ceiling it crossed rather than as a body that happens to end
+            # mid-character. `read_plain_file` makes the same second check for the same reason.
+            raw = read_bounded(descriptor, max_bytes=MAX_MARKDOWN_BYTES + 1)
+        finally:
+            os.close(descriptor)
+        if len(raw) > MAX_MARKDOWN_BYTES:
+            raise ThinLaneError(
+                "THIN_NARRATIVE_CELL_TOO_LARGE",
+                f"Narrative markdown grew past {MAX_MARKDOWN_BYTES} bytes while it was being read.",
+            )
+        if not raw:
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID", f"--markdown-file named an empty file: {target}"
+            )
+        try:
+            return raw.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID", "--markdown-file is not UTF-8 text"
+            ) from error
+    if getattr(stream, "isatty", lambda: False)():
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "a cell has a body; pipe it in on standard input, or name a file with --markdown-file",
+        )
+    # ⚠ THE SAME ENCODING GUARD THE FILE ARM HAS. `sys.stdin` decodes with `surrogateescape` under
+    # the default error handler, so bytes that are not UTF-8 arrive as lone surrogates rather than
+    # as a decode error -- and the first thing that touches them is `len(markdown.encode("utf-8"))`
+    # in the bounds check, which raises `UnicodeEncodeError` out of the middle of a validator. That
+    # is a traceback on the documented default input path. It is checked here, where the sentence
+    # can name standard input.
+    body = stream.read()
+    if not isinstance(body, str):  # pragma: no cover - a text stream answers with text
+        raise ThinLaneError("THIN_REQUEST_INVALID", "standard input did not answer with text")
+    try:
+        body.encode("utf-8")
+    except UnicodeEncodeError as error:
+        raise ThinLaneError("THIN_REQUEST_INVALID", "standard input is not UTF-8 text") from error
+    return body
+
+
+def _cell_receipt(cell: Mapping[str, Any]) -> dict[str, Any]:
+    """One cell as Studio stored it, reduced to the coordinates that place it.
+
+    ``sealed`` is asserted rather than reported. A narrative cell is an unsealed adjunct by
+    construction, and a client that quietly passed a ``true`` through would be the first surface
+    where "this is not evidence" stopped being checkable.
+    """
+
+    if cell.get("sealed") is not False:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID",
+            "Studio did not describe this narrative cell as unsealed; a cell is an unsealed "
+            "adjunct and is never attestation evidence",
+        )
+    return {
+        "cell_id": cell.get("cell_id"),
+        "heading": cell.get("heading"),
+        "checkpoint_seq": cell.get("checkpoint_seq"),
+        "revision_of": cell.get("revision_of"),
+        "sequence": cell.get("sequence"),
+        "cursor": cell.get("cursor"),
+        "appended_at": cell.get("appended_at"),
+        "payload_digest": cell.get("payload_digest"),
+        "superseded": cell.get("superseded"),
+        "markdown_bytes": len(str(cell.get("markdown", "")).encode("utf-8")),
+    }
+
+
+#: `note` honours every argument it declares, so there is nothing to report as inert. The empty
+#: table is here rather than absent so the payload key exists on this command exactly as it does on
+#: every other hosted one, and a script does not have to branch on which command answered.
+#:
+#: ⚠ THIS IS EMPTY BECAUSE THE FLAGS ARE REFUSED, NOT BECAUSE THEY ARE HONOURED EVERYWHERE.
+#: `--list` is a read, and the five flags that describe a cell mean nothing to it; the answer to
+#: that is :data:`_WRITE_ONLY_FLAGS` below, which refuses the combination by name. `_no_effect` is
+#: for a flag the hosted lane accepts and cannot honour, and none of these is that.
+_NOTE_NO_EFFECT: Sequence[tuple[str, str, str]] = ()
+
+#: The five arguments that describe a cell being written. `--list` writes nothing, so every one of
+#: them is inapplicable there -- and inapplicable is not the same as inert. Silently dropping
+#: `--heading` on a `--list` reads, to whoever typed it, like a filter that did not match.
+_WRITE_ONLY_FLAGS: tuple[tuple[str, str], ...] = (
+    ("heading", "--heading"),
+    ("cell_id", "--cell-id"),
+    ("markdown_file", "--markdown-file"),
+    ("checkpoint", "--checkpoint"),
+    ("revise", "--revise"),
+)
+
+
+def note(
+    args: argparse.Namespace,
+    *,
+    client: StudioNarrativeClient | None = None,
+    stdin: Any = None,
+) -> dict[str, Any]:
+    """``mr-data note``: write one cell of the decision record, or list what is written.
+
+    ⚠ ``--list`` IS A DIFFERENT ANSWER, NOT A FLAG ON THIS ONE. It reads under ``run:read`` and
+    writes nothing, so it is separated at the top rather than threaded through the append path:
+    a read that shares a code path with a write is a read that can accidentally become one.
+    """
+
+    run_id = _run_id(getattr(args, "run", None))
+    if getattr(args, "list", False):
+        given = [
+            flag for destination, flag in _WRITE_ONLY_FLAGS if getattr(args, destination, None)
+        ]
+        if given:
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID",
+                f"--list reads what is already written and writes nothing, so {', '.join(given)} "
+                "cannot mean anything here; drop it, or drop --list to write the cell it describes",
+            )
+        return _list(client or _client(args), run_id)
+    heading = getattr(args, "heading", None)
+    if not isinstance(heading, str) or not heading.strip():
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "--heading is the cell's one outcome-led line; it is what the notebook shows and "
+            "what a revision of this cell is recognised by",
+        )
+    heading = heading.strip()
+    named = getattr(args, "cell_id", None)
+    cell_id = (
+        _cell_id(named, flag="--cell-id") if named is not None else cell_id_from_heading(heading)
+    )
+    revise = getattr(args, "revise", None)
+    revision_of = _cell_id(revise, flag="--revise") if revise is not None else None
+    checkpoint_seq = _checkpoint(getattr(args, "checkpoint", None))
+    # ⚠ EVERY FLAG IS SETTLED BEFORE THE BODY IS READ. Standard input can be read once, so a typo
+    # in `--revise` discovered after the read would have consumed prose the caller then has to
+    # compose again. Reading it last costs nothing and makes the refusal recoverable.
+    markdown = _read_markdown(args, stdin=stdin)
+    check_cell_bounds(heading=heading, markdown=markdown)
+    # The credential is resolved only now, after everything a client can settle on its own has
+    # been settled. It is still before the bounds could be checked against the LOG -- the per-run
+    # cell budget and whether `--revise` names a real cell are Studio's to answer, and this lane
+    # does not read the log to guess at them.
+    selected = client or _client(args)
+    cell = selected.append_cell(
+        run_id,
+        body=append_cell_body(
+            workspace_id=selected.session.workspace_id,
+            run_id=run_id,
+            cell_id=cell_id,
+            heading=heading,
+            markdown=markdown,
+            checkpoint_seq=checkpoint_seq,
+            revision_of=revision_of,
+        ),
+    )
+    return {
+        "schema_version": NOTE_SCHEMA,
+        "status": "narrative_cell_appended",
+        "lane": "hosted",
+        "run_id": run_id,
+        "workspace_id": str(selected.session.workspace_id),
+        "cell": _cell_receipt(cell),
+        "sealed": False,
+        "not_evidence": NOT_EVIDENCE,
+        "flags_without_effect": _no_effect(args, _NOTE_NO_EFFECT),
+    }
+
+
+def _list(client: StudioNarrativeClient, run_id: str) -> dict[str, Any]:
+    """``mr-data note --list``: every cell this run holds, superseded revisions flagged."""
+
+    narrative = client.run_narrative(run_id)
+    cells = narrative.get("cells")
+    if not isinstance(cells, list):
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio answered the narrative without a list of cells"
+        )
+    if any(not isinstance(cell, Mapping) for cell in cells):
+        # ⚠ REFUSED, NOT FILTERED. A list route elsewhere in this lane drops a malformed member,
+        # because a page of runs is still a useful page with one bad row in it. A narrative is a
+        # document: dropping a cell would report a smaller count than the run holds and read as
+        # the record being shorter than it is.
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio listed a narrative cell that is not an object"
+        )
+    listed = [_cell_receipt(cell) for cell in cells]
+    workspace_id = narrative.get("workspace_id")
+    return {
+        "schema_version": NOTE_SCHEMA,
+        "status": "narrative_listed",
+        "lane": "hosted",
+        "run_id": run_id,
+        "workspace_id": workspace_id if isinstance(workspace_id, str) else None,
+        "cell_count": len(listed),
+        "rendered_count": sum(1 for cell in listed if cell["superseded"] is not True),
+        "cells": listed,
+        "sealed": False,
+        "not_evidence": NOT_EVIDENCE,
+        # Present and empty, so the two answers this command gives have the same key set and a
+        # script does not have to know which one it got before it reads them.
+        "flags_without_effect": {},
+    }
+
+
+#: Said in every answer, for the same reason ``approvals`` says ``never_decides`` in every one of
+#: its own: the property has to survive being read by somebody who only sees one payload.
+NOT_EVIDENCE = (
+    "A narrative cell is an unsealed adjunct: it records what was decided and why, carries no "
+    "authority, and is never attestation evidence."
+)
+
+
+__all__ = [
+    "MAX_CELL_ID_CHARS",
+    "MAX_HEADING_CHARS",
+    "MAX_MARKDOWN_BYTES",
+    "NARRATE_SCOPE",
+    "NOTE_SCHEMA",
+    "NOT_EVIDENCE",
+    "RUN_NARRATIVE_PATH",
+    "StudioNarrativeClient",
+    "append_cell_body",
+    "cell_id_from_heading",
+    "check_cell_bounds",
+    "note",
+]