mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/render.py

@@ -0,0 +1,657 @@
+"""Plain-language rendering of the payload mappings the CLI already emits as JSON.
+
+The renderer is a pure function over the payload mapping: it never re-reads a written file, never
+touches the environment, and never inspects an exception's cause or traceback. That is what keeps
+``cli._snapshot_result_receipt``'s claim honest -- the plain rendering and the ``--json`` rendering
+carry the same facts from the same dict, so neither can quietly say more than the other.
+
+Nothing here prints. Every function returns a string, so the same facts can be rendered into a
+browser page later without re-deriving them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+# Plain names for the payload keys a user or their agent reads. Internal identifiers keep their
+# engineering-precise spelling; only the label shown to a human moves (docs/VOCABULARY.md).
+PLAIN_LABELS: dict[str, str] = {
+    # Identity of a build
+    # The bare key is mapped as well as the compounds: an unmapped key falls back to the key's own
+    # spelling, and that fallback is a label no sweep of the source can see, because it is built at
+    # render time rather than written down anywhere.
+    "candidate": "Build",
+    "candidate_digest": "Build fingerprint",
+    "candidate_contract_version": "Build contract version",
+    "producer_principal": "Built by",
+    "producer_attempt": "Build attempt",
+    "table_sha256": "Data fingerprint",
+    "manifest_version": "Receipt version",
+    "validation_policy_digest": "Checks fingerprint",
+    "row_count": "Rows",
+    "columns": "Columns",
+    # Looking at a file or an address before anything is built
+    "source": "Looked at",
+    "origin": "Opened from",
+    "data_format": "Format",
+    "input_sha256": "Bytes fingerprint",
+    "content_sha256": "Content fingerprint",
+    "schema_digest": "Schema fingerprint",
+    "schema": "Column facts",
+    "sample": "First rows",
+    "fetched_from": "Fetched from",
+    "saved_to_disk": "Saved to disk",
+    "null_count": "Missing values",
+    "distinct_count": "Different values",
+    "minimum": "Lowest",
+    "maximum": "Highest",
+    "grain": "One row per",
+    "engine": "Engine",
+    # Recipes and approvals
+    "recipe_id": "Recipe ID",
+    "recipe_version": "Recipe version",
+    "recipe_digest": "Recipe fingerprint",
+    "predecessor_recipe_digest": "Previous recipe fingerprint",
+    "approval_id": "Approval ID",
+    "approval_digest": "Approval fingerprint",
+    "approval_policy_digest": "Approval policy fingerprint",
+    "approved_by": "Approved by",
+    "approved_at": "Approved at",
+    "execution_digest": "Run-settings fingerprint",
+    "execution_mode": "Run mode",
+    # Review
+    "decision_digest": "Decision fingerprint",
+    "review_decision_digest": "Review decision fingerprint",
+    "acquisition_bundle_digest": "Acquisition evidence fingerprint",
+    "review_dir": "Review folder",
+    "review_authority": "Who verified this",
+    "review_record": "Review record",
+    "signed_report": "Signed report",
+    "release_eligible": "Ready to go live",
+    "drift_report": "Drift alert",
+    # Places
+    "workspace": "Workbench folder",
+    "run_dir": "Build folder",
+    "root": "Folder looked in",
+    "output": "Wrote",
+    "input_root": "Input folder",
+    "member_paths": "Receipt contents",
+    # Records and receipts
+    "schema_version": "Record version",
+    "run_id": "Run ID",
+    # One deployed run's own state, as Studio holds it. The key spellings stay Studio's; only
+    # these labels move, and `repair_task_id` moves because its own fallback label would print
+    # the internal name for a fix-it task at somebody sitting at a terminal.
+    "run_status": "Run state",
+    # `run_disposition`, not `disposition`: the bare key is already a field of the local search
+    # trace, and a label declared here reaches every payload that carries the key. Naming this one
+    # for the run keeps a label written for a deployed run out of an unrelated command's output.
+    "run_disposition": "Where this stands",
+    "run_seconds": "Run took, in seconds",
+    "watch_limit_seconds": "Waited at most, in seconds",
+    "repair_task_id": "Fix-it task ID",
+    "revision": "Revision",
+    "state_phase": "Stage",
+    "publication": "File receipt",
+    "expected_size_bytes": "Size in bytes",
+    "expected_content_digest": "Content fingerprint",
+    "output_bytes": "Bytes written",
+    "output_bytes_sha256": "Written-bytes fingerprint",
+    "media_type": "Media type",
+    "request_sha256": "Request fingerprint",
+    "evidence_authority": "Authoritative record",
+    "file_observed": "File seen on disk",
+    "linearization_point": "Observed at",
+    "namespace_linearization": "Observed at",
+    "post_linearization_path_persistence": "After this observation",
+    "authority": "Authority",
+    "hosted_release": "Live in Studio",
+    "successor_repair_closure": "Fix-it cycle closed",
+    "url": "Address",
+    "dir": "Folder",
+    # Question and sources
+    "question": "Question",
+    "question_id": "Question ID",
+    "requirements": "Requirements",
+    "requirements_id": "Requirements ID",
+    "feasibility": "Feasibility",
+    "sources": "Sources",
+    "source_ids": "Source IDs",
+    "source_proposals": "Source options",
+    "required_check_ids": "Required checks",
+    "quality": "Quality checks",
+    "join": "Join",
+    "lineage": "Where it came from",
+    "counts": "Counts",
+    "manifest_sha256": "Manifest fingerprint",
+    "aggregate_sha256": "Aggregate fingerprint",
+    "entry_count": "Indexed entries",
+    "locator_count": "Private locations",
+    "diagnostic_count": "Diagnostics",
+    "total_bytes": "Indexed bytes",
+    "checkpoint_sha256": "Checkpoint fingerprint",
+    "staging_sha256": "Complete staging fingerprint",
+    "fill_receipt_sha256": "Fill receipt fingerprint",
+    "fill_receipt": "Fill receipt",
+    "flagged_queue_sha256": "Flagged-rights queue fingerprint",
+    "classification_sha256": "Delta classification fingerprint",
+    "classification_checkpoint_sha256": "Classification checkpoint fingerprint",
+    "publication_sha256": "Publication receipt fingerprint",
+    "provider_count_reconciliation": "Provider count rule",
+    "convergence_passes": "Convergence passes",
+    "reason_code": "Reason code",
+    "recommendation": "Recommendation",
+    "representations": "Representations",
+    "fallback_reason": "Fallback reason",
+    "role": "Role",
+    "tasks": "Steps",
+    "events": "History",
+}
+
+# One plain headline sentence per status the harness puts on stdout. Statuses remain machine
+# contract values; only the sentence shown to a human is translated into plain language.
+STATUS_HEADLINES: dict[str, str] = {
+    "ready": "Notebook ready.",
+    # Workbench folder states (offline._PHASES)
+    "initialized": "Workbench folder created.",
+    "planned": "Plan checked and recorded.",
+    "building": "A build is in progress.",
+    "idle": "No Build is running.",
+    "done": "Build finished.",
+    "candidate_built": "Build sealed.",
+    "review_recorded": "Review decision sealed.",
+    "failed": "The last build failed.",
+    # Workbench folder commands
+    "plan_validated": "Plan checked and recorded.",
+    "candidate_inspected": "Build inspected and replayed exactly.",
+    "candidate_verified": "Build re-checked and intact.",
+    "deployment_approval_required": "Deployment is waiting for human approval.",
+    "dataset_activation_queued": "Dataset activation queued.",
+    # Both answers about a queued run are answers whatever they say. The headline never claims the
+    # run finished: which of the thirteen states it is in is the line below it, every time.
+    "run_status_reported": "Here is what Studio says about that run.",
+    "run_watch_timed_out": (
+        "The wait ran out and the run had not settled. Below is the state it was really in."
+    ),
+    "hosted_dataset_ready": "The released Build is here and its dataset notebook is ready.",
+    "reconciled": "The prior deployment result was recovered.",
+    # Cloud device-key lifecycle. Each status says what durable local state or Cloud's exact
+    # answer established; none implies that a parent-process environment override changed.
+    "logged_out": "The stored device credential was removed.",
+    "local_recovery_completed": "The local credential recovery is complete.",
+    "recovered": "The credential state was recovered.",
+    "recovery_required": "Credential recovery is required before this can continue.",
+    "revoked": "The device credential was revoked.",
+    "rotated": "A new device credential was stored and the old one was revoked.",
+    # Recipes
+    "frozen_recipe_validated": "Recipe checked. Nothing was approved or run.",
+    "recipe_authored": "Recipe written from your YAML.",
+    "recipe_exported": "Recipe written.",
+    "recipe_approved": "Recipe approved.",
+    # The hosted half of an approval. Two words rather than one, because "the ask was recorded"
+    # and "a person settled it" are the two different things somebody needs to be able to tell
+    # apart -- and a single word covering both is how a pending approval gets read as a yes.
+    "approval_requested": "The approval was asked for. A person still has to grant it.",
+    "approval_settled": "A person settled that approval.",
+    # The decision record, written into a hosted run's own log. Two words for the same reason the
+    # two above are two: writing a cell and reading what is written are different answers, and a
+    # single word covering both would let a list read as though something had just been recorded.
+    "narrative_cell_appended": "Note written into the run's record.",
+    "narrative_listed": "The notes written about this run.",
+    "version_built": "Recipe version built.",
+    "recipe_version_verified": "Recipe version verified.",
+    # Review
+    "report_signed": "Report signed.",
+    "reported": "Report prepared.",
+    "reviewed_candidate": "Review passed. No blocking findings.",
+    "fixes_required": "Review found blocking findings. Fixes are required.",
+    # Local deterministic checks do not create a review decision.
+    "local_checks_completed": "Checks run here. Nothing has been decided.",
+    "review_setup_created": "Protected review setup created. This does not approve a Build.",
+    # Capturing a live source: what was recorded is now sealed and can be built from.
+    "stream_recorded": "Recorded messages sealed.",
+    # Looking before authoring
+    "peeked": "Here is what is in there.",
+    # Asking what would stop a build, and what this build can do at all. Both are answers whatever
+    # they contain: "this machine cannot write a file safely" is the thing the command was run to
+    # find out, so the headline does not change into an apology when it says so.
+    "preflight_completed": "Here is what would stop a build on this machine.",
+    "inventory_listed": "Here is what this build can do.",
+    "catalog_searched": "Here is the best admitted source in that verified catalog.",
+    "catalog_fill_incomplete": (
+        "Catalog fill stopped incomplete. Resume from its exact checkpoint."
+    ),
+    "catalog_published": "Public catalog successor published.",
+    # The three explicit provider-scale mutations. Each one is a separate answer with its own
+    # receipt, so none of them may read as another: a sweep that stopped is not a generation, and
+    # a key file that was accepted is not a sweep.
+    "harvest_preflight_accepted": (
+        "That key file was accepted. Nothing was fetched and nothing was written."
+    ),
+    "harvest_complete": "The provider sweep finished. Nothing has been published yet.",
+    "harvest_incomplete": (
+        "The provider sweep stopped before it finished. The reason below says what stopped it; "
+        "run the same command again with --resume to carry on from exactly there."
+    ),
+    "generation_published": "Public catalog generation published, and read back from disk.",
+    "generation_incomplete": (
+        "The generation stopped before it was published. What is already written is verified and "
+        "kept; run the same command again with --resume to carry on from exactly there."
+    ),
+    "build_index_published": "Private Build index published.",
+    "local_search_complete": "Local search complete.",
+    # A public store can be searched under a stated work budget, and a budget that closes before
+    # every relevant part of it has been read is not an answer. The headline says so out loud
+    # rather than letting "no match" stand in for "we stopped looking".
+    "local_search_incomplete": (
+        "Local search stopped before it finished. Nothing was ruled out; the reason below says "
+        "which budget closed."
+    ),
+    # Writing one generation of catalog entries out into bounded parts. These two words are the
+    # whole answer of that command -- it puts its own receipt's `status` at the top of what it
+    # prints -- so without a sentence here a reader was shown the bare word `complete`.
+    "complete": "Authoring finished. Every record in that generation was written.",
+    "incomplete": (
+        "Authoring stopped before it finished. The reason below says what stopped it, and what "
+        "was written is listed under it."
+    ),
+    # The catalogue pipeline job, asked to resolve its deployment's configuration and stop. The
+    # word is the whole answer: nothing ran, so the headline has to say so rather than let a
+    # reader take a printed receipt for a completed stage.
+    "dry-run": "Nothing ran. This is the stage that would have run, and what it would have run as.",
+    # Trying a plan before committing to it. The build was real; the folder it went into was not
+    # kept, so the headline says what was learned rather than what was made.
+    "plan_checked": "That plan builds.",
+    # Reading back what you already have
+    "build_shown": "Here is what this build holds.",
+    "builds_listed": "Here are the builds under that folder.",
+    # Comparing two of them. Both outcomes are ordinary answers, so both read as answers: a
+    # difference is something to look at, not something that went wrong.
+    "builds_identical": "Those two builds hold the same data, in the same shape.",
+    "builds_differ": "Those two builds are not the same.",
+    # Agent-facing surfaces
+    "agent_request_validated": "Agent request checked. No model was called.",
+    "source_proposals_validated": "Source options checked. Nothing was fetched.",
+    "workflow_described": "Here is the workflow and who decides at each step.",
+    "adapters_listed": "Here are the available source adapters.",
+    "events_read": "Here is the build history.",
+    "fleet_scanned": "Here is the worker fleet.",
+    "no_new_run": "No new Recipe run was needed.",
+    "refused": "That request was refused.",
+    "slices_acquired": "The requested source slices were acquired.",
+    "source_acquired": "The source was acquired.",
+    # Handoff
+    "hosted_candidate_exported": "Build packaged for Studio.",
+    "viewer_started": "Viewer running.",
+    "notebook_ready": "Table notebook ready.",
+    # Signing in to the Mostly Right cloud, and reading back what is stored locally
+    "device_authenticated": "Signed in. A device credential is stored on this machine.",
+    "authenticated": "This machine is signed in.",
+    "not_authenticated": "This machine is not signed in.",
+    "listed": "Here are the device credentials Cloud knows about.",
+    "not_implemented": "That credential operation is not available in this release.",
+    "unsupported": "That transport-token operation is not supported.",
+    # A deployment plan is only a request document. These statuses deliberately name the plan,
+    # never external state: the command contacts nothing, and Studio remains the authority that
+    # decides whether anything runs live.
+    "deployment_plan_ready": (
+        "Here is the request for running this dataset live. Nothing has been sent."
+    ),
+    "deployment_plan_refused": (
+        "A deployment request could not be prepared. The reasons are below."
+    ),
+    # The hosted lane. Every one of these headlines is about a run on the backend, and none of
+    # them claims anything about this machine: "queued" is what Studio accepted, "terminal" is
+    # what Studio's own state machine reached, and "the watch ended" is honest about the case
+    # where the connection stopped before the run did.
+    "run_queued": "The run is queued. Watch it at the address below.",
+    "run_reported": "Here is what Studio says about that run.",
+    "run_terminal": "The run has finished. Its final state is below.",
+    "watch_ended": "The watch ended before the run did. The run is unaffected.",
+    "artifacts_downloaded": "The dataset is here, and its digest matched.",
+    # The research session. Three words for opening one, because "a worker holds it", "Studio
+    # recorded it and nobody holds it yet" and "it ended" are three different answers to the same
+    # command; and three for a probe, because a probe that settled without an answer is neither
+    # an answer nor still running, and a single word covering all three is how a failed probe gets
+    # read as a result.
+    "research_session_ready": "The research session is ready. Its worker is warm.",
+    "research_session_opened": (
+        "The research session is recorded. Its worker has not taken it yet; the state is below."
+    ),
+    "research_session_ended": "The research session ended before a worker answered.",
+    "research_session_reported": "Here is what Studio says about that research session.",
+    "research_session_closed": "The research session is closed. Its worker exits.",
+    "research_probe_submitted": "The probe is queued. Its answer is read back separately.",
+    "research_probe_answered": "The worker answered the probe. The answer is below.",
+    "research_probe_settled": "The probe settled without an answer. The state is below.",
+    # The authoring front door. Three words because "a stage stopped where you asked", "the
+    # proposal exists and nothing has approved it", and "the approval is open and waiting on a
+    # person" are three different answers to the one command, and a single word covering all three
+    # is how a proposal nobody has approved gets read as a finished one.
+    "authoring_stage_complete": "The authoring stage you asked for is done. What is next is below.",
+    "recipe_proposed": "The recipe proposal exists. Nothing has approved it yet.",
+    "recipe_proposal_approval_requested": (
+        "The recipe proposal is open and waiting for a person to approve it."
+    ),
+    "recipe_proposal_approved": "A person approved the recipe. Queue its first build below.",
+    "recipe_proposal_not_approved": "The approval settled without approving the recipe.",
+    "recipe_build_queued": "The approval already started the first build. Follow the run below.",
+    # `build` against a proposal whose confirmation already started the run: that run is reported
+    # rather than a second one queued, and the word says so.
+    "run_already_queued": "This build was already queued by the approval. Its run is below.",
+}
+
+RECOMMENDATION_HEADLINES: dict[str, str] = {
+    "reuse_build": "A verified local Build can be reused.",
+    "use_source": "An admitted public source can be used.",
+    "no_match": "No fitting local Build or admitted public source was found.",
+    "public_incomplete": (
+        "The public source search stopped before it finished, so nothing was ruled out."
+    ),
+}
+
+# Facts a reader looks for first. Everything not named here follows, sorted, so the rendering is
+# deterministic whatever order the payload dict happens to carry.
+_HEADLINE_KEYS: tuple[str, ...] = (
+    # Whether anything is stopping you, and then what to do about it. `mr-data preflight` exists to
+    # be read by somebody who is stuck, and the list of everything that was fine is not the answer
+    # they came for. These two keys appear in no other payload.
+    "blocked",
+    "what to do",
+    # What is about to be frozen comes before the receipt for freezing it: the point of
+    # `mr-data approve` is that the block is read before the outcome lines (29-07). The section
+    # names below belong to that block alone and appear in no other payload, so naming them here
+    # orders the summary without touching how any other command reads.
+    "summary",
+    "what this answers",
+    "one row is",
+    "it covers",
+    "the columns",
+    "the sources",
+    # Directly under the source list, because that is what the sentence is about: what the Recipe
+    # declares the result is for, and the permission every source above has to carry for it.
+    "what the result may be used for",
+    "the cleaning steps",
+    "the join",
+    "the ordered graph steps",
+    "the graph output",
+    "the checks it must pass",
+    "the refresh bounds",
+    "the backfill window",
+    "the pinned versions",
+    "the recipe",
+    "the fingerprint being frozen",
+    "what freezing means",
+    # What a thing is comes before the detail of it, so one listed change reads in the order a
+    # person says it: what changed, which column, from what, to what, by how much. Sorted
+    # alphabetically these would arrive as "difference, from, related drift alert, to", which is
+    # nobody's sentence.
+    "what",
+    "column",
+    "from",
+    "to",
+    "difference",
+    # What a thing is called comes before anything said about it.
+    "name",
+    "run_id",
+    "workspace",
+    "run_dir",
+    "review_dir",
+    "output",
+    "url",
+    "dir",
+    "root",
+    "recipe_id",
+    "recipe_version",
+    "approval_id",
+    "candidate_digest",
+    "table_sha256",
+    "recipe_digest",
+    "approval_digest",
+    "decision_digest",
+    "review_decision_digest",
+    "acquisition_bundle_digest",
+    "execution_digest",
+    "row_count",
+    "columns",
+    "grain",
+    "manifest_version",
+    "engine",
+    "release_eligible",
+)
+
+# Facts that are the last thing a reader should read, whatever else the payload carries. A key
+# named here renders after every other key, with a blank line before it, so a closing sentence
+# stays closing even when the block above it is a list of checks. Only the top level is affected;
+# nested blocks keep their ordinary order.
+_TAIL_KEYS: tuple[str, ...] = (
+    # `review --local` must end by saying that human review is still pending.
+    "what happens next",
+    # `plan-check` must end by saying which fingerprint it did not report, and why. It reads as a
+    # closing line only after the fingerprint it does report.
+    "what this does not tell you",
+)
+
+# Two levels of indentation, then a count. Deeper structure is a machine record, not a human line.
+_MAX_DEPTH = 2
+_INDENT = "  "
+_EMPTY = "(none)"
+
+
+def render_human(payload: Mapping[str, Any]) -> str:
+    """Render one payload mapping as plain labelled lines.
+
+    The ``status`` key becomes the headline sentence and is not repeated as a line. Every other
+    key becomes ``label: value``. Nested mappings become indented blocks up to
+    :data:`_MAX_DEPTH`; anything deeper renders as a count that points at ``--json``.
+
+    ⚠ A PAYLOAD THAT STATES ITS OWN ``headline`` STATES IT, and it is not then repeated as a
+    labelled field. The status map is the sentence for a status word; a ``headline`` is a sentence
+    about this particular answer, which the acquisition receipt carries in both profiles -- how
+    many members were fetched, and from where -- and which the status word cannot know. Printing
+    both would open every one of those answers with two headlines, the general one and the true
+    one, in that order.
+    """
+
+    status = payload.get("status")
+    stated = payload.get("headline")
+    if isinstance(stated, str) and stated:
+        headline = stated
+    elif status is None:
+        headline = "Done."
+    elif status == "local_search_complete" and isinstance(payload.get("recommendation"), Mapping):
+        kind = payload["recommendation"].get("kind")
+        headline = RECOMMENDATION_HEADLINES.get(str(kind), STATUS_HEADLINES[str(status)])
+    else:
+        headline = STATUS_HEADLINES.get(str(status), str(status))
+    lines = [_printable(headline)]
+    lines.extend(_render_mapping(payload, depth=0, skip=("status", "headline")))
+    return "\n".join(lines)
+
+
+def render_error(
+    headline: str,
+    *,
+    code: str | None = None,
+    severity: str | None = None,
+    remediation: Sequence[str] = (),
+    note: str | None = None,
+) -> str:
+    """Render one failure as a plain block: what happened, what to do, what to quote.
+
+    ``code`` is what a person quotes in a bug report, so it survives into plain mode verbatim.
+    Remediation lines are supplied by the error-remediation map; the default is empty. ``note``
+    sits with the code rather than with the advice, because it is about this rendering of the
+    failure rather than about the failure.
+    """
+
+    # The headline carries a raise-site message, and a raise-site message regularly carries a name
+    # somebody else chose -- a path, a column, a member. One refusal is one line, so a name with a
+    # line break or an escape sequence in it is written out rather than acted on, by the same rule
+    # every other rendered value goes through.
+    lines = [_printable(headline)]
+    if remediation:
+        lines.append("")
+        lines.extend(f"{_INDENT}{_printable(str(item))}" for item in remediation)
+    tail = []
+    if severity is not None:
+        tail.append(f"Severity: {severity}")
+    if code is not None:
+        tail.append(f"Code: {code}")
+    if note is not None:
+        tail.append(note)
+    if tail:
+        lines.append("")
+        lines.extend(tail)
+    return "\n".join(lines)
+
+
+def render_lines(mapping: Mapping[str, Any], *, skip: Sequence[str] = ()) -> list[str]:
+    """Render one mapping as plain labelled lines, with no headline sentence.
+
+    This is :func:`render_human` without the status line, for a block of facts that is part of a
+    larger payload rather than the whole of one. A caller that has its own structured record and
+    wants the terminal rendering of it uses this, so the block a person reads and the record a
+    machine reads never become two truths.
+    """
+
+    return _render_mapping(mapping, depth=0, skip=skip)
+
+
+def plain_label(key: str) -> str:
+    """Plain label for one payload key; an unmapped key still renders, never crashes."""
+
+    mapped = PLAIN_LABELS.get(key)
+    if mapped is not None:
+        return mapped
+    return key.replace("_", " ").capitalize()
+
+
+def _render_mapping(
+    mapping: Mapping[str, Any],
+    *,
+    depth: int,
+    skip: Sequence[str] = (),
+) -> list[str]:
+    indent = _INDENT * depth
+    lines: list[str] = []
+    for key in _ordered_keys(mapping, skip=skip):
+        value = mapping[key]
+        # Lexical mode was explicitly selected, so no fallback happened. The token remains in the
+        # JSON receipt for compatibility but is not a human-facing reason to explain.
+        if key == "fallback_reason" and value == "NEURAL_NOT_REQUESTED":
+            continue
+        label = plain_label(str(key))
+        if depth == 0 and key in _TAIL_KEYS and lines:
+            lines.append("")
+        if isinstance(value, Mapping):
+            if depth >= _MAX_DEPTH:
+                lines.append(f"{indent}{label}: {_summary(len(value))}")
+                continue
+            lines.append(f"{indent}{label}:")
+            if not value:
+                lines.append(f"{indent}{_INDENT}{_EMPTY}")
+                continue
+            lines.extend(_render_mapping(value, depth=depth + 1))
+            continue
+        if _is_block(value):
+            # A value written over several lines is a block a person reads, not a field. Putting
+            # it after its own label keeps every line of it flush with the others -- and every
+            # line of it goes through `_printable`, so the newlines this branch honours are the
+            # only control characters that survive into the rendering.
+            lines.append(f"{indent}{label}:")
+            lines.extend(f"{indent}{_INDENT}{_printable(part)}" for part in str(value).split("\n"))
+            continue
+        if _is_sequence(value):
+            items = list(value)
+            if not items:
+                lines.append(f"{indent}{label}: {_EMPTY}")
+                continue
+            if all(_is_scalar(item) for item in items):
+                joined = ", ".join(_scalar(item) for item in items)
+                lines.append(f"{indent}{label}: {joined}")
+                continue
+            lines.append(f"{indent}{label}: {_summary(len(items))}")
+            continue
+        lines.append(f"{indent}{label}: {_scalar(value)}")
+    return lines
+
+
+def _ordered_keys(mapping: Mapping[str, Any], *, skip: Sequence[str] = ()) -> list[Any]:
+    present = [key for key in mapping if key not in skip]
+    tail = [key for key in _TAIL_KEYS if key in present]
+    headline = [key for key in _HEADLINE_KEYS if key in present and key not in tail]
+    remainder = sorted(
+        (key for key in present if key not in headline and key not in tail),
+        key=lambda key: (_is_container(mapping[key]), str(key)),
+    )
+    return [*headline, *remainder, *tail]
+
+
+def _summary(count: int) -> str:
+    noun = "item" if count == 1 else "items"
+    return f"<{count} {noun} - use --json for the full record>"
+
+
+def _is_scalar(value: Any) -> bool:
+    return value is None or isinstance(value, str | int | float | bool)
+
+
+def _is_sequence(value: Any) -> bool:
+    return isinstance(value, list | tuple)
+
+
+def _is_block(value: Any) -> bool:
+    """Whether this value is text written over more than one line."""
+
+    return isinstance(value, str) and "\n" in value
+
+
+def _is_container(value: Any) -> bool:
+    return isinstance(value, Mapping) or _is_sequence(value) or _is_block(value)
+
+
+def _scalar(value: Any) -> str:
+    if value is None:
+        return _EMPTY
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    return _printable(str(value))
+
+
+def _printable(text: str) -> str:
+    """One line of text with every character that is not one written as an escape.
+
+    A payload value is regularly a cell out of a file nobody has cleaned -- that is what `mr-data
+    peek` is for -- and the plain rendering is what a person, and per SKILL.md a driving agent,
+    reads and branches on. Text goes to a terminal, and a terminal acts on some of what it is
+    given: a newline in a cell puts attacker-chosen text at column 0, where `[ok] ...` and
+    `All checks passed: yes` live, and an escape sequence in a cell reaches the terminal itself.
+    Neither is a thing this renderer may pass on.
+
+    The rule is the Reader's own, one level down. A column *name* carrying a control character is
+    refused outright (`PARSE_COLUMN_NAME`); a value may not be refused, because refusing messy
+    values would leave peek unable to do the only thing it exists for -- so it is shown instead,
+    exactly, as the escape that spells it. ``str.isprintable`` is the test, so the C0 and C1
+    control characters, the delete character, and the line and paragraph separators are all
+    covered by one rule rather than by a list that has to be kept up to date.
+
+    A multi-line string that is a block of the product's own prose never reaches here: it is
+    rendered as an indented block, where every line is already flush with the others and none of
+    them can start at column 0. Each line of that block is still put through this function.
+    """
+
+    if text.isprintable():
+        return text
+    return "".join(part if part.isprintable() else _escaped(part) for part in text)
+
+
+def _escaped(character: str) -> str:
+    """One character that cannot be printed, written the way Python writes it in a string.
+
+    ``repr`` is the spelling, so a newline reads as ``\\n`` and an escape as ``\\x1b`` -- the form
+    a person recognises and can paste back into a search.
+    """
+
+    return repr(character)[1:-1]