typedstandards 0.1.0__py3-none-any.whl

typedstandards/__init__.py

@@ -0,0 +1,67 @@
+"""Typed Standards records from Python, through @typedstandards/cli as a child process.
+
+The package vendors @typedstandards/cli and runs it with a located Node binary. It holds no
+key, reads no signing seed and computes none of the format's hashes: the CLI reads the seed
+from the environment it inherits, and does all of the format's work.
+"""
+
+from __future__ import annotations
+
+from ._badge import badge_cell
+from ._cli import cli_entry
+from ._cli import run as _run
+from ._commands import attest, sign, verify, view, withdraw
+from ._comparison import comparison_cell
+from ._node import NODE_FLOOR, NODE_OVERRIDE, locate_node
+from ._show import Shown, show
+from ._sidecar import sidecar
+from .errors import (
+    CliError,
+    CliNotVendoredError,
+    InternalError,
+    NodeLocatorError,
+    SeedError,
+    UsageError,
+    VerificationError,
+)
+from .pin import Pinned, pin
+
+__version__ = "0.1.0"
+
+#: The version of @typedstandards/cli this release vendors (package.json pins it exactly).
+CLI_VERSION = "0.2.0"
+
+
+def cli_version() -> str:
+    """The ``version`` the vendored CLI prints for ``--version``."""
+    return _run("--version")["version"]
+
+
+__all__ = [
+    "CLI_VERSION",
+    "NODE_FLOOR",
+    "NODE_OVERRIDE",
+    "CliError",
+    "CliNotVendoredError",
+    "InternalError",
+    "NodeLocatorError",
+    "Pinned",
+    "SeedError",
+    "Shown",
+    "UsageError",
+    "VerificationError",
+    "__version__",
+    "attest",
+    "badge_cell",
+    "cli_entry",
+    "cli_version",
+    "comparison_cell",
+    "locate_node",
+    "pin",
+    "show",
+    "sidecar",
+    "sign",
+    "verify",
+    "view",
+    "withdraw",
+]

typedstandards/_badge.py

@@ -0,0 +1,167 @@
+"""``badge_cell``: the verifier badge as a notebook's first cell (Jupyter) or a ``mo.md`` cell (Marimo).
+
+The link and the badge follow ``@typedstandards/host-core``'s ``links.ts`` (typedstandards
+``116882a``, ``packages/host-core/src/links.ts``): ``buildVerifyHref`` (:42-48) puts a hosted
+bundle URL through ``?url=`` percent-encoded with ``encodeURIComponent``, and
+``buildEmbedMarkdown`` (:70-79) writes a linked image whose destination is in angle brackets.
+The constants are copied from :15-28. ``tests/test_badge.py`` compares this module's output with
+strings captured from host-core's own functions.
+
+The cell is written before the notebook is signed, and under ``raw-bytes/v1`` the notebook's
+bytes are the record's output, so the cell can carry only facts known by name before signing:
+the badge linked to the bundle URL, the host and the capture method. It never carries a hash or
+a time; the verifier shows those from the signed record. Spec §8.8.4 calls such a cell "purely a
+reader affordance".
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from urllib.parse import quote, unquote, urlsplit
+
+from ._notebook import insert_cell, source_lines
+
+#: host-core links.ts:16, the verifier's canonical origin.
+CANONICAL_ORIGIN = "https://typedstandards.org"
+#: links.ts:19.
+BADGE_ASSET_PATH = "/badge/typed-standards-verify.svg"
+#: links.ts:22-23.
+BADGE_WIDTH = 248
+BADGE_HEIGHT = 30
+#: links.ts:28: it describes the action, not a verdict.
+BADGE_ALT = "Verify this record with Typed Standards"
+
+#: The characters ``encodeURIComponent`` leaves unescaped besides ASCII letters and digits.
+_URI_COMPONENT_SAFE = "-_.!~*'()"
+
+#: The badge cell's id (nbformat 4.5).
+BADGE_CELL_ID = "typedstandards-badge"
+
+_HEX64 = re.compile(r"[0-9a-fA-F]{64}")
+_DATE_OR_TIME = re.compile(r"\d{4}-\d{2}-\d{2}|\d{2}:\d{2}(?::\d{2})?")
+_UNSAFE_IN_TABLE = re.compile(r"[|`\\\"\x00-\x1f\x7f]")
+
+
+def encode_uri_component(value: str) -> str:
+    """JavaScript's ``encodeURIComponent``: UTF-8, every byte escaped but ``A-Z a-z 0-9 - _ . ! ~ * ' ( )``."""
+    return quote(value, safe=_URI_COMPONENT_SAFE)
+
+
+def verify_href(bundle_url: str) -> str:
+    """The verifier deep link for a hosted bundle: ``https://typedstandards.org/verify?url=<encoded>``."""
+    url = bundle_url.strip()
+    if not re.match(r"https?://", url, re.IGNORECASE):
+        raise ValueError(f"bundle_url must be an http(s) URL of a served bundle, not {bundle_url!r}")
+    return f"{CANONICAL_ORIGIN}/verify?url={encode_uri_component(url)}"
+
+
+def badge_markdown(bundle_url: str) -> str:
+    """host-core's ``buildEmbedMarkdown`` for a hosted bundle (light theme)."""
+    return f"[![{BADGE_ALT}]({CANONICAL_ORIGIN}{BADGE_ASSET_PATH})](<{verify_href(bundle_url)}>)"
+
+
+def _check_fact(name: str, value: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be a non-empty string")
+    if _UNSAFE_IN_TABLE.search(value):
+        raise ValueError(
+            f"{name} {value!r} holds a character the cell's table cannot carry (|, `, \\, \" or a control)"
+        )
+    return value.strip()
+
+
+def refuse_hash_or_time(text: str, *, authorities: tuple[str, ...] = ()) -> str:
+    """Raise ``ValueError`` when ``text`` holds a 64-hex string, a date or a time of day.
+
+    The badge cell is part of the signed bytes, written before signing: a hash in it cannot be
+    the record's own, and a time in it cannot be the signing time, so either would mislead.
+    Each of ``authorities`` (a URL's host and port, as the text carries them) is left out of the
+    date and time check, so ``192.168.1.10:8080`` is not read as the time ``10:80``.
+    """
+    if _HEX64.search(text):
+        raise ValueError(
+            "the badge cell would carry a 64-hex string; it is written before signing, so it names no hash"
+        )
+    scan = text
+    for authority in authorities:
+        if authority:
+            scan = scan.replace(authority, " ")
+    if _DATE_OR_TIME.search(scan):
+        raise ValueError("the badge cell would carry a date or time; it is written before signing, so it names no time")
+    return text
+
+
+def badge_text(bundle_url: str, *, capture_method: str, host: str | None = None) -> str:
+    """The badge cell's Markdown: the badge, a two-row table (host, capture method), one sentence."""
+    url = bundle_url.strip()
+    parts = urlsplit(url)
+    if host is None:
+        host = parts.netloc
+    host = _check_fact("host", host)
+    capture_method = _check_fact("capture_method", capture_method)
+    text = (
+        f"{badge_markdown(bundle_url)}\n"
+        "\n"
+        "| Typed Standards record | |\n"
+        "|---|---|\n"
+        f"| Host | `{host}` |\n"
+        f"| Capture method | `{capture_method}` |\n"
+        "\n"
+        "This cell is a reader affordance and is not authoritative: verification reads the signed record, "
+        "not this cell, and the verifier shows the record's signer, hash and time.\n"
+    )
+    # The cell carries the URL percent-encoded, which hides a time's ":"; so the URL past its
+    # authority (path, query, fragment) is checked as written and decoded too.
+    rest = url[len(parts.scheme) + 3 + len(parts.netloc) :]
+    refuse_hash_or_time(f"{rest}\n{unquote(rest)}")
+    return refuse_hash_or_time(text, authorities=(f"`{host}`", encode_uri_component(parts.netloc)))
+
+
+def _marimo_source(markdown: str) -> str:
+    """A Marimo cell's source that renders ``markdown`` with ``mo.md``."""
+    if '"""' not in markdown and "\\" not in markdown and not markdown.endswith('"'):
+        return f'mo.md(\n    """{markdown}"""\n)\n'
+    return f"mo.md({markdown!r})\n"
+
+
+def badge_cell(
+    bundle_url: str,
+    *,
+    capture_method: str,
+    notebook: str | os.PathLike[str] | None = None,
+    host: str | None = None,
+    marimo: bool = False,
+    cell_id: str = BADGE_CELL_ID,
+) -> str:
+    """The verifier badge as a notebook cell, written before signing.
+
+    ``bundle_url`` is where the record's bundle will be served (for example
+    ``https://<host>/bundles/<name>.bundle.json``). ``capture_method`` is the record's
+    ``captureMethod`` (for example ``script-run``). ``host`` defaults to the bundle URL's host.
+
+    Jupyter (the default): with ``notebook``, the cell is inserted as the notebook's first cell,
+    a markdown cell with id ``cell_id`` on nbformat 4.5 or later, and every other byte of the
+    file is kept. Returns the cell's Markdown. An existing cell with the same id is refused, so
+    a second call does not add a second badge.
+
+    Marimo (``marimo=True``): returns the source of a cell that renders the same Markdown with
+    ``mo.md``, to paste into the app. ``notebook`` is refused, since a Marimo app is Python
+    source, not a notebook file.
+
+    The cell names no hash and no time: a URL or fact holding a 64-hex string, a date or a time
+    is refused with ``ValueError``.
+    """
+    text = badge_text(bundle_url, capture_method=capture_method, host=host)
+    if marimo:
+        if notebook is not None:
+            raise ValueError("marimo=True returns a cell's source; it does not edit a notebook file")
+        return _marimo_source(text)
+    if notebook is not None:
+        insert_cell(
+            notebook,
+            {"cell_type": "markdown", "metadata": {}, "source": source_lines(text)},
+            where="first",
+            cell_id=cell_id,
+        )
+    return text

typedstandards/_cli.py

@@ -0,0 +1,74 @@
+"""Run the vendored CLI as a child process and read its result."""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from ._node import locate_node
+from .errors import (
+    CliError,
+    CliNotVendoredError,
+    InternalError,
+    SeedError,
+    UsageError,
+    VerificationError,
+)
+
+#: The CLI's entry file inside the vendored tree that hatch_build.py writes.
+CLI_ENTRY = Path(__file__).parent / "_vendor" / "node_modules" / "@typedstandards" / "cli" / "dist" / "bin" / "main.js"
+
+#: The CLI's exit codes (packages/cli/src/errors.ts:3-14 in typedstandards). 1 is handled apart,
+#: since verify prints its verdict before exiting 1.
+_RAISES: dict[int, type[CliError]] = {2: UsageError, 3: SeedError, 4: InternalError}
+
+_log = logging.getLogger("typedstandards")
+
+
+def cli_entry() -> Path:
+    """The vendored CLI's entry file; raises :class:`CliNotVendoredError` when it is missing."""
+    if not CLI_ENTRY.is_file():
+        raise CliNotVendoredError(
+            f"the vendored @typedstandards/cli is missing ({CLI_ENTRY}); reinstall typedstandards, or in a "
+            "checkout run `uv sync --reinstall-package typedstandards`"
+        )
+    return CLI_ENTRY
+
+
+def _parse(stdout: bytes) -> Any:
+    return json.loads(stdout.decode("utf-8"))
+
+
+def run(command: str, args: Sequence[str] = (), *, stdin: bytes | None = None) -> Any:
+    """Run one CLI command and return its stdout parsed as JSON.
+
+    The child inherits this process's environment: no ``env`` is passed, and nothing here reads
+    or sets a variable for it. What the CLI writes on stderr when it succeeds (attention
+    readings, such as an offline ``registry_unavailable``) is logged at INFO on the
+    ``typedstandards`` logger.
+    """
+    node = locate_node()
+    entry = cli_entry()
+    feed: dict[str, Any] = {"input": stdin} if stdin is not None else {"stdin": subprocess.DEVNULL}
+    proc = subprocess.run([node, str(entry), command, *args], capture_output=True, check=False, **feed)
+    stderr = proc.stderr.decode("utf-8", errors="replace")
+    code = proc.returncode
+    if code == 0:
+        for line in stderr.splitlines():
+            _log.info("%s", line)
+        try:
+            return _parse(proc.stdout)
+        except ValueError as err:
+            raise CliError(0, f"stdout is not JSON ({err}); stderr: {stderr}", command) from err
+    if code == 1:
+        # verify prints {ok: false, ...} before exiting 1; sign, withdraw and attest print nothing.
+        try:
+            document = _parse(proc.stdout) if proc.stdout.strip() else None
+        except ValueError:
+            document = None
+        raise VerificationError(code, stderr, command, document)
+    raise _RAISES.get(code, CliError)(code, stderr, command)

typedstandards/_commands.py

@@ -0,0 +1,156 @@
+"""The five pass-through commands: ``sign``, ``withdraw``, ``attest``, ``view``, ``verify``.
+
+Each takes the CLI's inputs as Python values and returns the CLI's stdout parsed as JSON.
+An input given as a mapping is sent as JSON on standard input (``--input -``); a ``str`` or
+``os.PathLike`` is a path the CLI reads. The wrapper computes nothing the format defines: the
+CLI builds, signs, hashes and verifies.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any
+
+from ._cli import run
+
+#: An input: a JSON object as a mapping, or the path of a JSON file.
+Input = Mapping[str, Any] | str | os.PathLike[str]
+
+
+def _json_bytes(value: Mapping[str, Any]) -> bytes:
+    return json.dumps(value, ensure_ascii=False, allow_nan=False).encode("utf-8")
+
+
+def _input_args(value: Input, flag: str) -> tuple[list[str], bytes | None]:
+    if isinstance(value, Mapping):
+        return [flag, "-"], _json_bytes(value)
+    if isinstance(value, (str, os.PathLike)):
+        return [flag, os.fspath(value)], None
+    raise TypeError(f"{flag} takes a mapping (sent as JSON on stdin) or a path, not {type(value).__name__}")
+
+
+def _as_file(value: Input, directory: str, name: str, what: str) -> str:
+    if isinstance(value, Mapping):
+        path = Path(directory) / name
+        path.write_bytes(_json_bytes(value))
+        return str(path)
+    if isinstance(value, (str, os.PathLike)):
+        return os.fspath(value)
+    raise TypeError(f"{what} takes a mapping or a path, not {type(value).__name__}")
+
+
+def sign(
+    input: Input,
+    *,
+    output_file: str | os.PathLike[str] | None = None,
+    output_url: str | None = None,
+    content_type: str | None = None,
+) -> dict[str, Any]:
+    """``typedstandards sign``: build and sign a record from an envelope input.
+
+    ``output_file`` signs a file's bytes inline under ``raw-bytes/v1``; with ``output_url``, by
+    reference as a BlobRef (``content_type`` names its type). Returns
+    ``{package, envelopeHash, signature}``. The CLI reads the signing seed from its own
+    environment, which it inherits from this process.
+    """
+    args, stdin = _input_args(input, "--input")
+    if output_file is not None:
+        args += ["--output-file", os.fspath(output_file)]
+    if output_url is not None:
+        args += ["--output-url", output_url]
+    if content_type is not None:
+        args += ["--content-type", content_type]
+    return run("sign", args, stdin=stdin)
+
+
+def withdraw(input: Input) -> dict[str, Any]:
+    """``typedstandards withdraw``: sign an ``attestation/withdraws/v1``. Returns ``{node, nodeId, signature}``."""
+    args, stdin = _input_args(input, "--input")
+    return run("withdraw", args, stdin=stdin)
+
+
+def attest(input: Input) -> dict[str, Any]:
+    """``typedstandards attest``: sign a ``supersedes``, ``revises``, ``corroborates`` or ``contradicts``
+    attestation. Returns ``{node, nodeId, signature}``."""
+    args, stdin = _input_args(input, "--input")
+    return run("attest", args, stdin=stdin)
+
+
+def view(
+    signed: Input,
+    *,
+    visibility: str,
+    attestations: Iterable[Input] = (),
+    trust_registry_url: str | None = None,
+    package_url: str | None = None,
+    title: str | None = None,
+) -> dict[str, Any]:
+    """``typedstandards view``: build the commitment view a host serves, with the package inline.
+
+    ``signed`` is what :func:`sign` returned (or its path); each of ``attestations`` is what
+    :func:`withdraw` or :func:`attest` returned (or its path). Mappings are written to temporary
+    files, removed before this returns, since only one input can be standard input.
+    """
+    if isinstance(attestations, (Mapping, str, os.PathLike)):
+        raise TypeError("attestations takes a list of attestations, not one")
+    with tempfile.TemporaryDirectory(prefix="typedstandards-view-") as directory:
+        args = ["--signed", _as_file(signed, directory, "signed.json", "signed"), "--visibility", visibility]
+        for i, attestation in enumerate(attestations):
+            args += ["--attestation", _as_file(attestation, directory, f"attestation-{i}.json", "attestations")]
+        if trust_registry_url is not None:
+            args += ["--trust-registry-url", trust_registry_url]
+        if package_url is not None:
+            args += ["--package-url", package_url]
+        if title is not None:
+            args += ["--title", title]
+        return run("view", args)
+
+
+def _without_trust_registry(value: Input) -> Input:
+    """G0 D9 = A, typedstandards#136: CLI 0.2.0's verify exits 2 on a bundle's top-level
+    ``trustRegistry``, which host-core inlines in every bundle it serves under a registry. Drop that
+    one key from a bundle (a document with ``packageHash``) and change nothing else; any other
+    document, and a bundle file without the key, reach the CLI as given.
+
+    Remove this workaround when the wrapper pins a CLI whose verify accepts the key.
+    """
+    document: Any = value
+    if not isinstance(value, Mapping):
+        if not isinstance(value, (str, os.PathLike)):
+            return value
+        try:
+            document = json.loads(Path(value).read_bytes())
+        except (OSError, ValueError):
+            return value  # the CLI reports an unreadable or malformed file
+    if isinstance(document, Mapping) and "packageHash" in document and "trustRegistry" in document:
+        return {key: item for key, item in document.items() if key != "trustRegistry"}
+    return value
+
+
+def verify(
+    input: Input,
+    *,
+    blobs: Iterable[str | os.PathLike[str]] = (),
+    full: bool = True,
+) -> dict[str, Any]:
+    """``typedstandards verify``: verify what :func:`sign` or :func:`view` printed, offline.
+
+    ``full`` (the default) passes ``--json``, so the result carries every check's fields
+    (``checks``) and the lifecycle resolution (``lifecycle``) beside ``ok``, ``nodeId`` and
+    ``failures``. ``blobs`` are local files for the record's BlobRefs. A record that does not
+    verify raises :class:`~typedstandards.errors.VerificationError`, whose ``document`` is the
+    verdict. A bundle's top-level ``trustRegistry`` is dropped before the CLI sees it
+    (typedstandards#136); nothing else is changed.
+    """
+    if isinstance(blobs, (str, os.PathLike)):
+        raise TypeError("blobs takes a list of paths, not one")
+    args, stdin = _input_args(_without_trust_registry(input), "--input")
+    for blob in blobs:
+        args += ["--blob", os.fspath(blob)]
+    if full:
+        args.append("--json")
+    return run("verify", args, stdin=stdin)

typedstandards/_comparison.py

@@ -0,0 +1,164 @@
+"""``comparison_cell``: the spec §8.7.4 comparison cell, appended as a notebook's last cell.
+
+The cell embeds the values an execution produced as Python literals, recomputes them with the
+caller's expression, and prints each delta, in the canonical shape of spec §8.7.4 (the hub's
+``docs/architecture/typed-standards-specification.md``, lines 860-874 at ``6957a3a``)::
+
+    # ORIGINAL VALUES (captured at executedAt = <ISO-8601 timestamp>)
+    original = {
+        "<metric-name>": <literal value>,
+    }
+
+    # CURRENT VALUES (re-computed against live data using the same helpers + queries above)
+    current = <the caller's recompute expression>
+
+    # DELTAS
+    for k in original:
+        delta = ...
+        print(...)
+
+The spec's block indents by one space; the cell indents by four, as Python code usually is. The
+cell is appended before signing, so it is inside the signed bytes.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import math
+import os
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from typing import Any
+
+from ._notebook import insert_cell, source_lines
+
+#: The comparison cell's id (nbformat 4.5).
+COMPARISON_CELL_ID = "typedstandards-comparison"
+
+_CURRENT_COMMENT = "# CURRENT VALUES (re-computed against live data using the same helpers + queries above)"
+_DELTAS = (
+    "# DELTAS\n"
+    "for k in original:\n"
+    "    delta = (current[k] - original[k]) if isinstance(original[k], (int, float)) else (original[k], current[k])\n"
+    '    print(f"{k}: original={original[k]}, current={current[k]}, delta={delta}")\n'
+)
+
+
+def _string(value: str, where: str) -> str:
+    try:
+        value.encode("utf-8")
+    except UnicodeEncodeError as err:
+        raise ValueError(f"{where} is a string that is not valid UTF-8 text") from err
+    return json.dumps(value, ensure_ascii=False)  # a JSON string is also a Python string literal
+
+
+def literal(value: Any, where: str = "value") -> str:
+    """``value`` as Python literal source. Admits ``None``, ``bool``, ``int``, finite ``float``,
+    ``str``, and lists and str-keyed dicts of those; a subclass of ``int``, ``float`` or ``str``
+    (a NumPy float, an ``IntEnum``) is written as its base value. Anything else raises
+    ``TypeError``, and a non-finite float ``ValueError``."""
+    if value is None:
+        return "None"
+    if isinstance(value, bool):
+        return "True" if value else "False"
+    if isinstance(value, int):
+        return repr(int(value))
+    if isinstance(value, float):
+        number = float(value)
+        if not math.isfinite(number):
+            raise ValueError(f"{where} is {number!r}, which has no Python literal")
+        return repr(number)
+    if isinstance(value, str):
+        return _string(str(value), where)
+    if type(value) is list:
+        return "[" + ", ".join(literal(item, f"{where}[{i}]") for i, item in enumerate(value)) + "]"
+    if type(value) is dict:
+        parts = []
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise TypeError(f"{where} has a key {key!r} that is not a string")
+            parts.append(f"{_string(str(key), where)}: {literal(item, f'{where}[{key!r}]')}")
+        return "{" + ", ".join(parts) + "}"
+    raise TypeError(
+        f"{where} is a {type(value).__name__}, not a literal: comparison values are None, bool, int, float, "
+        "str, or lists and str-keyed dicts of those"
+    )
+
+
+def _captured_at(value: str | datetime) -> str:
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise ValueError("captured_at must be timezone-aware")
+        return value.astimezone(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+    if not isinstance(value, str) or "\n" in value or "\r" in value:
+        raise ValueError("captured_at must be an ISO 8601 timestamp on one line")
+    try:
+        datetime.fromisoformat(value)
+    except ValueError as err:
+        raise ValueError(f"captured_at {value!r} is not an ISO 8601 timestamp") from err
+    return value
+
+
+def _recompute(expression: str) -> str:
+    if not isinstance(expression, str) or not expression.strip() or "\n" in expression or "\r" in expression:
+        raise ValueError("recompute must be one line of Python: an expression that returns the current values")
+    try:
+        ast.parse(expression, mode="eval")
+    except SyntaxError as err:
+        raise ValueError(f"recompute {expression!r} is not a Python expression") from err
+    return expression.strip()
+
+
+def comparison_source(values: Mapping[str, Any], *, recompute: str, captured_at: str | datetime) -> str:
+    """The comparison cell's source, without writing it anywhere."""
+    if not isinstance(values, Mapping) or not values:
+        raise ValueError("values must be a non-empty mapping of names to literal values")
+    items = []
+    for name, value in values.items():
+        if not isinstance(name, str) or not name:
+            raise TypeError(f"value names must be non-empty strings, not {name!r}")
+        items.append(f"    {_string(name, 'a value name')}: {literal(value, repr(name))},\n")
+    original = "original = {\n" + "".join(items) + "}\n"
+    if ast.literal_eval(original.split("=", 1)[1].strip()) != dict(values):  # pragma: no cover - a defect here
+        raise AssertionError("the literal does not read back as the values")
+    return (
+        f"# ORIGINAL VALUES (captured at executedAt = {_captured_at(captured_at)})\n"
+        f"{original}"
+        "\n"
+        f"{_CURRENT_COMMENT}\n"
+        f"current = {_recompute(recompute)}\n"
+        "\n"
+        f"{_DELTAS}"
+    )
+
+
+def comparison_cell(
+    notebook: str | os.PathLike[str],
+    values: Mapping[str, Any],
+    *,
+    recompute: str,
+    captured_at: str | datetime,
+    cell_id: str = COMPARISON_CELL_ID,
+) -> str:
+    """Append the spec §8.7.4 comparison cell to ``notebook`` as its last cell; return its source.
+
+    ``values`` names the values the execution produced, each a literal (``None``, ``bool``,
+    ``int``, finite ``float``, ``str``, or lists and str-keyed dicts of those); anything else is
+    refused. ``recompute`` is one line of Python, an expression that returns a mapping with the
+    same names, run against live data when the notebook is re-executed (for example
+    ``recompute_key_metrics()``). ``captured_at`` is the execution's time, an ISO 8601 string or
+    a timezone-aware ``datetime``.
+
+    The cell is a code cell with id ``cell_id`` (nbformat 4.5 or later), no outputs and no
+    execution count, and every other byte of the notebook is kept. Append it after executing the
+    notebook and before signing it: the cell is part of the signed bytes.
+    """
+    source = comparison_source(values, recompute=recompute, captured_at=captured_at)
+    insert_cell(
+        notebook,
+        {"cell_type": "code", "execution_count": None, "metadata": {}, "outputs": [], "source": source_lines(source)},
+        where="last",
+        cell_id=cell_id,
+    )
+    return source