capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/bundle_viewer/viewer.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Render ``capsule bundle --with-viewer``'s self-contained HTML artifact.
+
+The template (``static/offline_shell.html``) is a vendored, byte-for-byte
+copy of scitt-cose's ``hosted_profiles.hosted.render_bundle_page(offline=True)``
+output -- see ``scripts/vendor_bundle_viewer.py`` for how it's re-synced.
+scitt-cose's own ``hosted_profiles/`` package is deliberately excluded from
+its published wheel, so there is no pip dependency that could pull this in
+at install time; vendoring one generated artifact (both repos are
+Apache-2.0) is the mechanism, not a live fetch from a running verify
+service -- ``capsule bundle`` is otherwise a fully local, network-free
+command reading only the local ledger file, and ``--with-viewer`` keeps
+that property rather than making bundle *production* depend on a service
+being reachable. The template embeds MMR_JS and BUNDLE_JS inline (no
+``<script src>``) so the artifact this writes needs no network to open or
+verify, on either end.
+
+The template carries one real embed slot,
+``window.__BUNDLE_FRAGMENT_B64U__="@@BUNDLE_FRAGMENT@@"`` -- substituted
+here with the same base64url fragment ``capsule bundle`` already computes
+for its permalink. Other appearances of that placeholder text elsewhere in
+the template are BUNDLE_JS's own placeholder-detection / re-splice logic
+(its in-browser "download self-contained copy" button) and must not be
+touched, so this replaces only the one assignment, not every occurrence of
+the bare token.
+"""
+from __future__ import annotations
+
+import json
+from importlib import resources
+
+__all__ = ["render_offline_viewer_html"]
+
+_EMBED_SLOT_PLACEHOLDER = '<script>window.__BUNDLE_FRAGMENT_B64U__="@@BUNDLE_FRAGMENT@@";</script>'
+
+
+def _load_template() -> str:
+    return (
+        resources.files("capsule_engine.bundle_viewer")
+        .joinpath("static", "offline_shell.html")
+        .read_text(encoding="utf-8")
+    )
+
+
+def render_offline_viewer_html(fragment: str) -> str:
+    """Return the self-contained HTML for *fragment* (the same base64url
+    bundle fragment used in the bundle's permalink). The result carries no
+    external references at all -- open it directly, no server required."""
+    template = _load_template()
+    if template.count(_EMBED_SLOT_PLACEHOLDER) != 1:
+        raise RuntimeError(
+            "vendored offline_shell.html's embed slot is missing or no longer "
+            "unique -- re-check it against a fresh vendor pass "
+            "(scripts/vendor_bundle_viewer.py) before shipping --with-viewer"
+        )
+    embed_slot = f"<script>window.__BUNDLE_FRAGMENT_B64U__={json.dumps(fragment)};</script>"
+    return template.replace(_EMBED_SLOT_PLACEHOLDER, embed_slot, 1)

capsule_engine/cli/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``capsule-engine`` CLI package: thin verb dispatcher, see ``main.py``."""
+from .main import main
+
+__all__ = ["main"]

capsule_engine/cli/bundle_cmd.py

@@ -0,0 +1,269 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsule bundle`: a self-contained, independently verifiable slice of the
+ledger, plus a verify-surface permalink.
+
+"Self-contained" is load-bearing: the bundle transitively pulls in any
+``chain.parent_capsule_id`` a selected record cites (walking the real
+ledger) so the slice verifies on its own, without needing the rest of the
+ledger present -- verification below runs with ``store=`` restricted to
+exactly the bundle's own capsule ids, never the full ledger, to prove that
+property rather than assume it.
+
+The permalink is fragment-carried (``#...``, after the URL's ``#``): per
+the workspace's other verify surfaces (`agentactioncapsule-site` /
+`scitt-cose`'s hosted verifier), capsule data that goes after ``#`` is never
+sent to a server -- only the browser-side JS reads it. ``verify.
+agentactioncapsule.org`` is this workspace's existing public verify domain
+(see CLAUDE.md / STATUS.md T7 notes); the base URL is still overridable
+(``--verify-base-url`` / ``$CAPSULE_VERIFY_BASE_URL``) since no bundle-specific
+route exists there yet -- this is this package's own convention until one
+does.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import dataclasses
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from agent_action_capsule import verify as verify_capsule
+from capsule_emit.checkpoint import MmrLedger
+from capsule_emit.checkpoint import core as mmr_core
+from capsule_emit.ledger_io import (
+    add_scan_query_args,
+    build_scan_query,
+    echo_parts,
+    open_ledger,
+    require_ledger_path,
+)
+from capsule_emit.period import add_period_arg, apply_period
+from cll.ledger.api import ScanQuery
+
+from ..envcompat import env_get
+from ..guards.capsule import local_only_refusal
+from .format import build_echo, format_staleness
+
+__all__ = ["add_parser", "run"]
+
+DEFAULT_VERIFY_BASE_URL = "https://verify.agentactioncapsule.org/bundle"
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    p = sub.add_parser("bundle", help="produce a self-contained verifiable slice of the ledger")
+    add_scan_query_args(p)
+    add_period_arg(p)
+    p.add_argument("--out", default="bundle.json", help="output path for the bundle file (default: %(default)s)")
+    p.add_argument(
+        "--verify-base-url",
+        dest="verify_base_url",
+        default=env_get("CAPSULE_VERIFY_BASE_URL", DEFAULT_VERIFY_BASE_URL),
+        help="base URL the permalink's fragment is appended to (default: %(default)s)",
+    )
+    p.add_argument(
+        "--with-viewer",
+        dest="with_viewer",
+        action="store_true",
+        help=(
+            "also write a self-contained offline HTML viewer next to --out, so the "
+            "bundle verifies on a machine with no network (default viewer path: "
+            "--out with a .html extension)"
+        ),
+    )
+    p.add_argument(
+        "--viewer-out",
+        dest="viewer_out",
+        default=None,
+        help="output path for the offline viewer HTML (implies --with-viewer; default: derived from --out)",
+    )
+    p.set_defaults(func=run)
+    return p
+
+
+def _echo_safe_out(out: str) -> str:
+    """The ``--out`` value ``cli_echo`` renders on the public bundle
+    permalink and offline viewer -- it must show where the file went
+    relative to the invocation, never the operator's absolute filesystem
+    layout. An absolute path outside the cwd tree (no relative route to it)
+    falls back to just the filename rather than leaking the full path."""
+    p = Path(out)
+    if not p.is_absolute():
+        return out
+    rel = os.path.relpath(p, Path.cwd())
+    return rel if not rel.startswith("..") else p.name
+
+
+def _default_viewer_out(out: str) -> str:
+    """``bundle.json`` -> ``bundle.html`` alongside it; falls back to a
+    ``-viewer.html`` suffix on the rare path where ``--out`` already ends in
+    ``.html`` (so the two outputs never collide)."""
+    p = Path(out)
+    candidate = p.with_suffix(".html")
+    if str(candidate) == out:
+        candidate = p.with_name(p.stem + "-viewer.html")
+    return str(candidate)
+
+
+def _collect_with_parents(store, matched):
+    """Pull in any cited chain parent not already selected, so the bundle
+    verifies standalone without needing the rest of the ledger. A parent
+    that genuinely isn't in the ledger (a real gap) is left out -- it
+    surfaces honestly as a finding on the citing record, never hidden."""
+    by_id = {r.capsule_id: r for r in matched}
+    frontier = list(matched)
+    missing: set[str] = set()
+    while frontier:
+        rec = frontier.pop()
+        parent_id = (rec.capsule.get("chain") or {}).get("parent_capsule_id")
+        if not parent_id or parent_id in by_id or parent_id in missing:
+            continue
+        parent = store.fetch(parent_id)
+        if parent is None:
+            missing.add(parent_id)
+            continue
+        by_id[parent.capsule_id] = parent
+        frontier.append(parent)
+    return sorted(by_id.values(), key=lambda r: r.seq)
+
+
+def _build_completeness_certificate(store, records, tree_size: int) -> dict | None:
+    """MMR range proof (plus a consistency proof bridging to the full
+    ledger's checkpoint, when the bundle's range doesn't already reach it)
+    over the bundle's own record range.
+
+    Shape matches scitt-cose's viewer (``MMR_JS`` / ``checkCompleteness`` in
+    ``hosted_profiles/hosted.py``) field for field -- that module ports this
+    package's MMR core to JS and already checks a certificate in this shape;
+    this is the CLI side of that contract, not a new one.
+    """
+    if not records:
+        return None
+
+    mmr = MmrLedger(store)
+    mmr.sync()
+
+    from_seq, to_seq = records[0].seq, records[-1].seq
+    proof = mmr.range_proof(from_seq, to_seq)
+    range_root = mmr.root_at(proof.size).hex()
+
+    checkpoint_size = mmr_core.node_count(tree_size)
+    if checkpoint_size == proof.size:
+        checkpoint_root = range_root
+        consistency = None
+    else:
+        checkpoint_root = mmr.root_at(checkpoint_size).hex()
+        consistency = mmr.consistency_proof(proof.size, checkpoint_size)
+
+    return {
+        "v": 1,
+        "range_proof": {
+            "from_seq": proof.from_seq,
+            "to_seq": proof.to_seq,
+            "size": proof.size,
+            "from_index": proof.from_index,
+            "to_index": proof.to_index,
+            "witness": list(proof.witness),
+        },
+        "range_root": range_root,
+        "checkpoint_size": checkpoint_size,
+        "checkpoint_root": checkpoint_root,
+        "consistency_proof": dataclasses.asdict(consistency) if consistency is not None else None,
+    }
+
+
+def run(args: argparse.Namespace) -> int:
+    # ``bundle`` only exists at all in the "full" packaging arm -- see
+    # ``cli/main.py`` -- so any use of it is M5's "bundle/share created" fact.
+    from ..telemetry.record import record_evidence_touch
+
+    record_evidence_touch("full")
+
+    ledger_path = require_ledger_path("bundle", args)
+    if ledger_path is None:
+        return 2
+
+    apply_period(args)  # --period fills in args.since/args.until in place when unset
+    query = build_scan_query(args)
+    with open_ledger(ledger_path) as store:
+        matched = list(store.scan(query))
+        records = _collect_with_parents(store, matched)
+        capsules = [r.capsule for r in records]
+        refusal = local_only_refusal(capsules)
+        if refusal is not None:
+            print(f"capsule bundle: refused: {refusal}; narrow the selection to records without them", file=sys.stderr)
+            return 2
+        ids = [c["capsule_id"] for c in capsules]
+
+        verification: dict[str, dict] = {}
+        all_ok = True
+        for capsule in capsules:
+            result = verify_capsule(capsule, store=ids)
+            verification[capsule["capsule_id"]] = {
+                "ok": result.ok,
+                "findings": [{"code": f.code, "detail": f.detail, "severity": f.severity} for f in result.findings],
+            }
+            all_ok = all_ok and result.ok
+
+        tree_size = sum(1 for _ in store.scan(ScanQuery()))
+        completeness_certificate = _build_completeness_certificate(store, records, tree_size)
+
+    echo = build_echo(
+        "bundle", flags=[*echo_parts(args), ("--period", args.period), ("--out", _echo_safe_out(args.out))]
+    )
+    bundle = {
+        "bundle_version": "1",
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "query": {
+            k: v
+            for k, v in {
+                "agent": args.agent,
+                # args.since/args.until already reflect --period's resolved
+                # bounds (apply_period mutates them in place above) -- a
+                # bundle's recorded query must show what was actually
+                # scanned, not the pre-resolution flag.
+                "since": args.since,
+                "until": args.until,
+                "period": args.period,
+                "counterparty": args.counterparty,
+                "verdict": args.verdict,
+                "action_type": args.action_type,
+                "limit": args.limit,
+            }.items()
+            if v is not None
+        },
+        "cli_echo": echo,
+        "records": capsules,
+        "range": [records[0].seq, records[-1].seq] if records else [0, -1],
+        "checkpoint": {"tree_size": tree_size},
+        "verification": verification,
+        "completeness_certificate": completeness_certificate,
+    }
+
+    with open(args.out, "w", encoding="utf-8") as fh:
+        json.dump(bundle, fh, indent=2, sort_keys=True)
+
+    payload = json.dumps(bundle, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    fragment = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+    permalink = f"{args.verify_base_url}#{fragment}"
+
+    r0, r1 = bundle["range"]
+    status = "all verify" if all_ok else "VERIFICATION FAILURE in this slice"
+    print(f"wrote {args.out} ({len(records)} record(s), records {r0}–{r1}, {status})")
+    print(f"checkpoint #{tree_size} · as of {format_staleness(0)}")
+    print(f"verify: {permalink}")
+
+    if args.with_viewer or args.viewer_out is not None:
+        from ..bundle_viewer import render_offline_viewer_html
+
+        viewer_out = args.viewer_out or _default_viewer_out(args.out)
+        viewer_html = render_offline_viewer_html(fragment)
+        with open(viewer_out, "w", encoding="utf-8") as fh:
+            fh.write(viewer_html)
+        print(f"wrote {viewer_out} (self-contained, opens with no network)")
+
+    print()
+    print(echo)
+    return 0 if all_ok else 1

capsule_engine/cli/console_cmd.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsule console`: serve the local console UI (record stream, filters,
+per-record inspector, fold strip) over the real ledger.
+
+LOCAL ONLY -- binds to localhost by default, no hosted anything, no account
+system. See `capsule_ledger/console/server.py` for the HTTP wiring and
+`capsule_ledger/console/{tokens,components}.css` for the shared component
+library this UI is built from (never re-invented here).
+"""
+from __future__ import annotations
+
+import argparse
+
+from capsule_emit.ledger_io import require_ledger_path
+
+from .format import build_echo
+
+__all__ = ["add_parser", "run"]
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8420
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    p = sub.add_parser(
+        "console", help="serve the local console UI (record stream + inspector) over the real ledger"
+    )
+    p.add_argument("--ledger", help="ledger store directory or a JSONL fixture file (default: $CAPSULE_LEDGER)")
+    p.add_argument(
+        "--host", default=DEFAULT_HOST, help="bind host -- local only by default (default: %(default)s)"
+    )
+    p.add_argument("--port", type=int, default=DEFAULT_PORT, help="bind port (default: %(default)s)")
+    p.set_defaults(func=run)
+    return p
+
+
+def run(args: argparse.Namespace) -> int:
+    # The console only exists at all in the "full" packaging arm (see
+    # ``cli/main.py``) -- it renders capsule vocabulary and verification
+    # state throughout, matching log/show/verify/bundle's own M5 marker.
+    from ..telemetry.record import record_evidence_touch
+
+    record_evidence_touch("full")
+
+    ledger_path = require_ledger_path("console", args)
+    if ledger_path is None:
+        return 2
+
+    from ..console.server import build_server
+
+    server = build_server(ledger_path, host=args.host, port=args.port)
+    url = f"http://{args.host}:{args.port}/"
+    print(f"capsule console: serving {ledger_path} at {url} (local only — no hosted anything, no account system)")
+    print(
+        build_echo(
+            "console",
+            flags=[
+                ("--ledger", args.ledger),
+                ("--host", args.host if args.host != DEFAULT_HOST else None),
+                ("--port", args.port if args.port != DEFAULT_PORT else None),
+            ],
+        )
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0

capsule_engine/cli/constraints_cmd.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsule constraints list`: the registered guard checks + the starter
+action-class taxonomy (T3's ``guards/classes.py``) -- a static catalog, not
+a ledger query, so it needs no ``--ledger``."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from ..folds.catalog import Catalog
+from ..guards.classes import TAXONOMY, UNCLASSIFIED_DEFAULT
+
+__all__ = ["add_parser", "run_list", "CHECKS", "DEFAULT_CAPS_FOLD_ID", "DEFAULT_CATALOG_DIR"]
+
+DEFAULT_CATALOG_DIR = Path(__file__).resolve().parent.parent / "folds" / "catalog_defs"
+# The caps check's fold is a per-deployment GuardEngine configuration
+# (`GuardEngine(caps_fold=...)`); this listing resolves the one T3 wires up
+# in its own tests/fixtures (`conftest.py`'s `caps_fold` fixture) as the
+# representative default, rather than invent one of its own.
+DEFAULT_CAPS_FOLD_ID = "spend.weekly/1.0.0"
+
+# (check_id, check_type, method, description) -- method is None for `caps`,
+# whose method is the configured fold_id, resolved at print time below.
+# Public (not `_`-prefixed): the MCP server's `constraints.list` tool reuses
+# this exact catalog rather than keeping its own copy in sync by hand.
+CHECKS = [
+    (
+        "dedupe",
+        "policy",
+        "exact_match_index_v0",
+        "equivalence lookup over a rolling window — exact-match only, no fuzzy/semantic matching",
+    ),
+    (
+        "caps",
+        "policy",
+        None,
+        "fold predicate: weekly_spend + amount <= cap (integer minor units only)",
+    ),
+    (
+        "verify_before_dispatch",
+        "policy",
+        "agent_action_capsule.verify",
+        "the cited mandate capsule must exist in the ledger and independently re-verify",
+    ),
+]
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    constraints = sub.add_parser("constraints", help="the registered guard checks and the action-class taxonomy")
+    csub = constraints.add_subparsers(dest="constraints_command")
+    constraints.set_defaults(constraints_parser=constraints)
+
+    p_list = csub.add_parser("list", help="list the registered guard checks and the action-class taxonomy")
+    p_list.add_argument("--dir", help="fold catalog directory the caps check reads from (default: built-in catalog)")
+    p_list.set_defaults(func=run_list)
+
+    return constraints
+
+
+def run_list(args: argparse.Namespace) -> int:
+    catalog_dir = Path(args.dir) if getattr(args, "dir", None) else DEFAULT_CATALOG_DIR
+    caps_entry = Catalog(catalog_dir).get(DEFAULT_CAPS_FOLD_ID)
+    caps_method = caps_entry.definition.fold_id if caps_entry is not None else "(no caps fold configured)"
+
+    print("checks:")
+    for check_id, check_type, method, description in CHECKS:
+        resolved_method = caps_method if check_id == "caps" else method
+        print(f"  {check_id:<24} {check_type:<8} {resolved_method:<28} {description}")
+
+    print()
+    print("action classes (absent or unrecognized -> unclassified, fail-closed):")
+    for ac in (*TAXONOMY.values(), UNCLASSIFIED_DEFAULT):
+        print(f"  {ac.name:<26} consequential={str(ac.consequential):<6} fail_open_allowed={ac.fail_open_allowed}")
+    return 0

capsule_engine/cli/format.py

@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared CLI output discipline: the DM Mono fold-envelope line, staleness
+copy, the CLI-echo canonical form, and one capsule-summary helper.
+
+The envelope-line format is copied verbatim from the design handoff
+README's "Product laws" section (`design_handoff_capsule_ledger_ux/README.md`):
+``fold <id> · records N–M · checkpoint #X · as of <staleness>`` -- literal
+text output, not a font choice. ``<id>`` is the fold's own ``fold`` envelope
+field (the definition digest already computed by the fold engine), never a
+name this module invents.
+"""
+from __future__ import annotations
+
+import re
+import shlex
+
+from ..registry import describe_action_class
+
+__all__ = [
+    "format_staleness",
+    "format_envelope_line",
+    "format_coverage_footnote",
+    "build_echo",
+    "cli_echo_leaks_absolute_path",
+    "summarize_action",
+    "format_action_class",
+    "assurance_grade_parts",
+    "format_assurance_grade",
+]
+
+_WINDOWS_DRIVE_RE = re.compile(r"[A-Za-z]:\\")
+
+
+def format_staleness(age_ms: int) -> str:
+    """Render a checkpoint age in the design's "as of 14s ago" style.
+
+    ``age_ms <= 0`` (a value freshly computed by this same CLI invocation,
+    never backdated) renders as "just now" rather than "0s ago".
+    """
+    if age_ms <= 0:
+        return "just now"
+    seconds = age_ms / 1000
+    if seconds < 60:
+        return f"{round(seconds)}s ago"
+    minutes = seconds / 60
+    if minutes < 60:
+        return f"{round(minutes)}m ago"
+    hours = minutes / 60
+    if hours < 24:
+        return f"{round(hours)}h ago"
+    days = hours / 24
+    return f"{round(days)}d ago"
+
+
+def format_envelope_line(envelope: dict) -> str:
+    """Render a fold result envelope (spec §4 shape) as the literal DM Mono line."""
+    r0, r1 = envelope["range"]
+    checkpoint_num = envelope["checkpoint"].get("tree_size")
+    staleness_ms = envelope["staleness"].get("checkpoint_age_ms", 0)
+    return (
+        f"fold {envelope['fold']} · records {r0}–{r1} · "
+        f"checkpoint #{checkpoint_num} · as of {format_staleness(staleness_ms)}"
+    )
+
+
+def format_coverage_footnote(coverage: dict) -> str:
+    """Render a fold's coverage statement (T2R rev9(a),
+    ``EvaluationTrace.coverage_statement()``) as the design's literal
+    per-number footnote: "range-complete through C · captured under boundary
+    B, rule R · reconciled against O over interval T". The rule this
+    enforces (rev9(a)): *a report cannot render a number without its
+    coverage statement* -- every caller that shows a fold's ``result`` shows
+    this alongside it, never bare.
+
+    ``capture: "unknown"`` (no boundary/rule declared for this evaluation)
+    renders visibly rather than being silently dropped from the footnote;
+    ``reconciled: None`` (no external comparison set) renders as
+    "reconciled: none" for the same reason.
+    """
+    _, range_end = coverage["range"]
+    capture = coverage["capture"]
+    if capture == "unknown":
+        capture_part = "captured under boundary: unknown"
+    else:
+        capture_part = f"captured under boundary {capture['boundary']}, rule {capture['rule']}"
+    reconciled = coverage["reconciled"]
+    reconciled_part = (
+        "reconciled: none"
+        if reconciled is None
+        else f"reconciled against {reconciled['source']} over interval {reconciled['interval']}"
+    )
+    return f"range-complete through {range_end} · {capture_part} · {reconciled_part}"
+
+
+def build_echo(verb: str, *, positional: str | None = None, flags: list[tuple[str, object]] = ()) -> str:
+    """The CLI-echo canonical form: the exact, copy-pasteable invocation that
+    produced this output (design handoff README, "CLI echo standing rule").
+    Flag order is fixed (whatever the caller passes), not the order the user
+    typed them in, so the same query always echoes identically.
+    """
+    tokens = ["capsule", verb]
+    if positional is not None:
+        tokens.append(shlex.quote(str(positional)))
+    for flag, value in flags:
+        if value is None or value is False:
+            continue
+        tokens.append(flag)
+        if value is not True:
+            tokens.append(shlex.quote(str(value)))
+    return "≡ " + " ".join(tokens)
+
+
+def cli_echo_leaks_absolute_path(cli_echo: str) -> bool:
+    """``cli_echo`` is rendered verbatim on the bundle permalink and the
+    offline viewer -- a public page -- so it must never carry an operator's
+    absolute filesystem layout (home directory, machine username). Flags any
+    token that is a POSIX absolute path (a leading ``/``, with no allowlisted
+    exception defined) or a Windows drive path (``C:\\...``); callers that
+    build ``cli_echo`` from user-supplied paths must relativize them first
+    rather than adding an exception here."""
+    tokens = shlex.split(cli_echo.removeprefix("≡ "))
+    for token in tokens:
+        if token.startswith("/") or _WINDOWS_DRIVE_RE.match(token):
+            return True
+    return False
+
+
+def summarize_action(capsule: dict) -> str:
+    """The verb portion of ``action_id`` (e.g. "approve_purchase"), falling
+    back to ``action_type`` for records with no ``action_id``."""
+    action_id = capsule.get("action_id") or ""
+    verb = action_id.split("/", 1)[0] if action_id else ""
+    return verb or capsule.get("action_type") or "(unnamed action)"
+
+
+def format_action_class(capsule: dict) -> str | None:
+    """Convention-label line for this capsule's ``asg_payload.action_class``
+    (design principle item 2) -- ``None`` when the capsule carries no
+    ``action_class`` at all (a legitimately different state from an
+    unregistered *value*, which renders instead of being hidden)."""
+    action_class = (capsule.get("asg_payload") or {}).get("action_class")
+    convention = describe_action_class(action_class)
+    if convention.action_class is None:
+        return None
+    if convention.registered:
+        return f"{convention.action_class} — {convention.label}"
+    return f"{convention.action_class} (unregistered)"
+
+
+_ATTESTATION_LABELS = {"self_attested": "self-attested", "anchored": "anchored"}
+
+
+def assurance_grade_parts(assurance: dict) -> tuple[str, bool]:
+    """(label, badged) for this assurance block -- the one place that
+    decides which attestation modes are "badged" (design principle item 3).
+    Extensible to a future ``countersigned`` value the same way, once that
+    assurance mode is a real field this codebase produces; ``badged`` is
+    never about paid/free, only about attestation strength."""
+    mode = assurance.get("attestation_mode")
+    label = _ATTESTATION_LABELS.get(mode, mode or "(none)")
+    ledger_mode = assurance.get("ledger_mode")
+    grade = f"{label} · ledger: {ledger_mode}" if ledger_mode else label
+    return grade, mode == "anchored"
+
+
+def format_assurance_grade(assurance: dict) -> str:
+    """Assurance grades do the honesty work everywhere (design principle
+    item 3): ``self_attested`` renders plain, ``anchored`` is badged
+    (``[...]``) -- driven only by the real ``attestation_mode``/
+    ``ledger_mode`` values on the record, never invented, never upsell
+    copy."""
+    grade, badged = assurance_grade_parts(assurance)
+    return f"[{grade}]" if badged else grade