capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/cli/guard_cmds.py

@@ -0,0 +1,361 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``capsule guard`` verbs: dry-run replay + self-contained HTML report (moved
+here, matching ``fold_cmds.py``'s per-verb-module convention, so ``main.py``
+stays a thin dispatcher), plus ``guard enforce`` -- a minimal, honest local
+marker command (see ``_cmd_guard_enforce``'s own docstring for exactly what
+it does and doesn't do).
+
+Every guard-dry-run invocation here checks the current packaging arm
+(``capsule_ledger.packaging``) and, in "guards-only", both suppresses the
+evidence chrome in the rendered HTML report (``render_report_html``'s own
+``arm`` param) and rewords/suppresses this command's own stdout so it never
+prints a capsule id or a share/verify link -- see this module's inline
+comments at each print site.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .. import packaging
+from ..envcompat import env_get
+
+__all__ = ["add_parser"]
+
+DEFAULT_CATALOG_DIR = Path(__file__).resolve().parent.parent / "folds" / "catalog_defs"
+DEFAULT_WICKET_DIR = Path(__file__).resolve().parent.parent / "guards" / "wickets" / "catalog_defs"
+DEFAULT_MANIFEST_PATH = Path(__file__).resolve().parent.parent / "policy" / "catalog_defs" / "default.yaml"
+
+
+def _catalog_dir(args: argparse.Namespace) -> Path:
+    if getattr(args, "dir", None):
+        return Path(args.dir)
+    env = env_get("CAPSULE_FOLD_DIR")
+    if env:
+        return Path(env)
+    return DEFAULT_CATALOG_DIR
+
+
+def _wicket_dir(args: argparse.Namespace) -> Path:
+    if getattr(args, "wicket_dir", None):
+        return Path(args.wicket_dir)
+    env = env_get("CAPSULE_WICKET_DIR")
+    return Path(env) if env else DEFAULT_WICKET_DIR
+
+
+def _resolve_manifest(args: argparse.Namespace, *, strict: bool):
+    """The policy manifest that governs this replay (``--manifest``, default
+    the built-in one), resolved against the fold catalog (``_catalog_dir``)
+    and the wicket catalog (``--wicket-dir``). ``strict``: one that does not
+    resolve is an error (``None``, after saying why) rather than a warning."""
+    from ..policy import PolicyManifestError, load_manifest_file, resolve_manifest
+
+    manifest_path = Path(args.manifest) if getattr(args, "manifest", None) else DEFAULT_MANIFEST_PATH
+    try:
+        manifest = load_manifest_file(manifest_path)
+        return resolve_manifest(manifest, fold_catalog_dir=_catalog_dir(args), wicket_catalog_dir=_wicket_dir(args))
+    except PolicyManifestError as exc:
+        if strict:
+            print(f"capsule guard dry-run: policy manifest {manifest_path} did not resolve ({exc.reason}): {exc}",
+                  file=sys.stderr)
+        else:
+            print(f"warning: policy manifest {manifest_path} did not resolve ({exc.reason}: {exc}); "
+                  "proceeding without a manifest citation", file=sys.stderr)
+        return None
+
+
+def _resolve_manifest_digest(args: argparse.Namespace) -> str | None:
+    """Resolve the policy manifest that governs this replay (``--manifest``,
+    default the built-in one) against the same fold catalog this command is
+    already using (``_catalog_dir``) and the wicket catalog (``--wicket-dir``).
+
+    Best-effort: a caller pointing ``--dir``/``--wicket-dir`` at a catalog the
+    configured manifest doesn't (yet) pin correctly gets a warning, not a
+    hard failure -- the replay report itself is still real and useful without
+    a resolvable manifest citation. ``--no-manifest`` skips this entirely."""
+    if getattr(args, "no_manifest", False):
+        return None
+    resolved = _resolve_manifest(args, strict=False)
+    return resolved.manifest_digest if resolved is not None else None
+
+
+def _parse_cap_args(items: list[str]) -> dict[str, int] | None:
+    caps_minor: dict[str, int] = {}
+    for item in items or []:
+        cls, sep, value = item.partition("=")
+        if not sep:
+            print(f"--cap must be CLASS=MINOR_UNITS, got {item!r}", file=sys.stderr)
+            return None
+        try:
+            caps_minor[cls] = int(value)
+        except ValueError:
+            print(f"--cap value must be an integer (minor units), got {item!r}", file=sys.stderr)
+            return None
+    return caps_minor
+
+
+def _cmd_guard_dry_run(args: argparse.Namespace) -> int:
+    from agent_action_capsule import compute_capsule_id
+
+    from ..folds.loader import load_definition_file
+    from ..guards.capsule import local_only_refusal
+    from ..packs import PackDefinitionError, load_proposals_file
+    from ..report import build_dry_run_report, build_dry_run_report_with_proposal, render_report_html
+    from ..report.render import TelemetryConfig, decode_fragment, to_fragment_payload
+    from ..telemetry.record import record_evidence_touch, record_guard_configured, record_guard_evaluated
+
+    if bool(args.model_note) != bool(args.model_id):
+        print("--model-note and --model-id must be given together (or neither)", file=sys.stderr)
+        return 1
+
+    caps_minor = _parse_cap_args(args.cap)
+    if caps_minor is None:
+        return 1
+
+    arm = packaging.current_arm()
+    evidence_visible = packaging.evidence_visible(arm)
+
+    since = None if args.since in (None, "all") else args.since
+    fold_path = Path(args.fold_file) if args.fold_file else _catalog_dir(args) / "spend.weekly.yaml"
+    caps_fold = load_definition_file(fold_path)
+    per_action_minor = None
+    per_action_reads = None
+    if getattr(args, "caps_from_manifest", False):
+        # The resolved manifest's own caps wicket: its window and per-action
+        # limits, and the fold it names. A --cap still sets a window limit.
+        if getattr(args, "no_manifest", False):
+            print("--caps-from-manifest needs a manifest: drop --no-manifest", file=sys.stderr)
+            return 1
+        resolved = _resolve_manifest(args, strict=True)
+        if resolved is None:
+            return 1
+        if not resolved.caps_minor():
+            print("capsule guard dry-run: --caps-from-manifest: the manifest configures no caps limits", file=sys.stderr)
+            return 1
+        caps_minor = {**resolved.caps_minor(), **caps_minor}
+        per_action_minor = resolved.per_action_minor() or None
+        per_action_reads = resolved.per_action_reads()
+        if not args.fold_file and resolved.caps_fold() is not None:
+            caps_fold = resolved.caps_fold()
+        manifest_digest = resolved.manifest_digest
+    else:
+        manifest_digest = _resolve_manifest_digest(args)
+
+    proposed_caps_minor = None
+    proposal_rationale = None
+    if args.proposals:
+        try:
+            _, proposals = load_proposals_file(args.proposals)
+        except PackDefinitionError as exc:
+            print(f"capsule guard dry-run: --proposals failed to load ({exc.reason}): {exc}", file=sys.stderr)
+            return 1
+        proposed_caps_minor = {p["action_class"]: p["proposed_cap_minor"] for p in proposals}
+        parts = [f"{cls}={cap}" for cls, cap in sorted(proposed_caps_minor.items())]
+        proposal_rationale = f"proposed: {', '.join(parts)}"
+
+    def _build():
+        if proposed_caps_minor is not None:
+            return build_dry_run_report_with_proposal(
+                args.ledger,
+                caps_fold=caps_fold,
+                proposed_caps_minor=proposed_caps_minor,
+                since=since,
+                caps_minor=caps_minor,
+                proposal_rationale=proposal_rationale,
+                operator=args.operator,
+                model_note=args.model_note,
+                model_id=args.model_id,
+                manifest_digest=manifest_digest,
+                per_action_minor=per_action_minor,
+                per_action_reads=per_action_reads,
+            )
+        return build_dry_run_report(
+            args.ledger,
+            caps_fold=caps_fold,
+            since=since,
+            caps_minor=caps_minor,
+            operator=args.operator,
+            model_note=args.model_note,
+            model_id=args.model_id,
+            manifest_digest=manifest_digest,
+            per_action_minor=per_action_minor,
+            per_action_reads=per_action_reads,
+        )
+
+    report = _build()
+
+    # The printed link carries every row's decision capsule and the capsule
+    # it cites; one holding a local-only field must not leave this machine.
+    if args.share and evidence_visible:
+        shared = [c for section in report.guards for row in section.rows for c in (row.capsule, row.cited_capsule) if c]
+        refusal = local_only_refusal(shared)
+        if refusal is not None:
+            print(f"capsule guard dry-run --share: refused: {refusal}; rerun without --share", file=sys.stderr)
+            return 1
+
+    telemetry = None
+    if args.telemetry_opt_in and args.telemetry_endpoint:
+        telemetry = TelemetryConfig(opted_in=True, endpoint=args.telemetry_endpoint)
+
+    html, fragment = render_report_html(report, arm=arm, telemetry=telemetry)
+    out_path = Path(args.out)
+    out_path.write_text(html, encoding="utf-8")
+    url = f"file://{out_path.resolve()}#{fragment}"
+
+    print(f"wrote {out_path}")
+    if report.manifest_digest is not None:
+        print(f"evaluated under manifest {report.manifest_digest}")
+    # Arm A ("guards-only"): the share link is a verify-link suggestion --
+    # not printed, matching the report itself never surfacing its evidence
+    # chrome. The file above still exists and is still openable; this CLI
+    # just doesn't advertise the fragment-carried permalink.
+    if args.share and evidence_visible:
+        print(url)
+
+    if caps_minor:
+        record_guard_configured(arm)
+    if report.actions_replayed:
+        record_guard_evaluated(arm)
+    if evidence_visible and (args.share or args.verify):
+        record_evidence_touch(arm)
+
+    if args.verify:
+        written_payload = decode_fragment(fragment)
+        rebuilt_payload = to_fragment_payload(_build())
+        # exclude generated_at: the one field that legitimately differs
+        # between two otherwise-identical replays (it's a wall-clock
+        # generation timestamp, not derived from the ledger).
+        lhs = {k: v for k, v in written_payload.items() if k != "generated_at"}
+        rhs = {k: v for k, v in rebuilt_payload.items() if k != "generated_at"}
+        if lhs != rhs:
+            print("FAIL: replaying the same ledger did not reproduce the same report", file=sys.stderr)
+            return 1
+
+        mismatches = []
+        for section in written_payload["guards"]:
+            for row in section["rows"]:
+                for capsule in (row.get("capsule"), row.get("cited_capsule")):
+                    if not capsule:
+                        continue
+                    if compute_capsule_id(capsule) != capsule.get("capsule_id"):
+                        mismatches.append(capsule.get("capsule_id"))
+        if mismatches:
+            # Arm A: "cited record(s)", never the word "capsule" in output.
+            noun = "cited capsule(s)" if evidence_visible else "cited record(s)"
+            print(f"FAIL: {len(mismatches)} {noun} do not re-verify", file=sys.stderr)
+            return 1
+        tail = " and every cited capsule verifies" if evidence_visible else ""
+        print(f"OK: report is reproducible{tail}")
+
+    return 0
+
+
+def _cmd_guard_enforce(args: argparse.Namespace) -> int:
+    """Records, locally, that this install has moved from dry-run to
+    enforce -- nothing more. ``GuardEngine.check(..., dry_run=...)`` is
+    already a real parameter your own integration code controls (this CLI
+    only ever drives it in dry-run mode via ``guard dry-run``); this
+    command does not gate anything itself. It exists so there is a real,
+    minimal, honest action to record the M2 ("enforcement-on") telemetry
+    fact against, matching the report's own "$ capsule guard enforce" callout.
+    """
+    from ..telemetry.record import record_enforcement_flip
+
+    arm = packaging.current_arm()
+    record_enforcement_flip(arm)
+    print(
+        "recorded: this install has moved from dry-run to enforce (locally, opt-in telemetry only).\n"
+        "This command does not itself gate actions -- wire GuardEngine.check(..., dry_run=False) into "
+        "your own integration to actually enforce."
+    )
+    return 0
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    guard = sub.add_parser("guard", help="guard API: dry-run replay + report (full CLI lands in a later task)")
+    guard_sub = guard.add_subparsers(dest="guard_command")
+    guard.set_defaults(guard_parser=guard)
+
+    p_dry_run = guard_sub.add_parser(
+        "dry-run", help="replay a ledger through the guard checks and emit a self-contained HTML report"
+    )
+    p_dry_run.add_argument(
+        "--ledger", required=True, action="append", help="ledger JSONL file or LedgerStore directory (repeatable)"
+    )
+    p_dry_run.add_argument(
+        "--since", default="7d",
+        help="rolling window, e.g. '7d' (anchored to the ledger's own latest record); 'all' for no filter",
+    )
+    p_dry_run.add_argument(
+        "--share", action="store_true",
+        help="print the full shareable file://...#<fragment> URL (no-op in the guards-only packaging arm)",
+    )
+    p_dry_run.add_argument(
+        "--verify", action="store_true", help="re-replay and re-verify every cited capsule before exiting"
+    )
+    p_dry_run.add_argument("--out", default="dry-run-report.html", help="output HTML path (default: dry-run-report.html)")
+    p_dry_run.add_argument(
+        "--operator", default=None, help="override the displayed operator label (default: the ledger's own)"
+    )
+    p_dry_run.add_argument(
+        "--cap", action="append", default=[], metavar="CLASS=MINOR_UNITS",
+        help="per-action-class cap for the caps check, e.g. money.transfer=10000000 (repeatable; omit an action "
+        "class to leave it unconfigured -- it will never trigger the caps guard, matching GuardEngine's own default)",
+    )
+    p_dry_run.add_argument(
+        "--model-note", default=None, help="optional pre-written model commentary quote (never generated by this CLI)"
+    )
+    p_dry_run.add_argument(
+        "--model-id", default=None, help="model id the note above was drafted by (required together with --model-note)"
+    )
+    p_dry_run.add_argument(
+        "--fold-file", default=None,
+        help="fold definition YAML the caps check evaluates against (default: the built-in "
+        "spend.weekly.yaml) -- point this at a pack's own materialized fold, e.g. "
+        ".capsule/catalog/folds/payments_safety.yaml, to replay under that pack's caps",
+    )
+    p_dry_run.add_argument(
+        "--proposals", default=None,
+        help="proposals YAML file (from `capsule thresholds propose --out`) -- when given, adds a "
+        "section showing what would ALSO have been held under the proposed caps, on top of what "
+        "--cap already configures (the P2 'conversion moment': what tightening to the proposal "
+        "would additionally catch)",
+    )
+    p_dry_run.add_argument(
+        "--dir", help="fold catalog directory the caps check's fold definition lives in (default: built-in catalog, or $CAPSULE_FOLD_DIR)"
+    )
+    p_dry_run.add_argument(
+        "--manifest", help="policy manifest YAML resolved for this replay (default: built-in manifest)"
+    )
+    p_dry_run.add_argument(
+        "--wicket-dir", dest="wicket_dir",
+        help="wicket catalog directory the manifest's wicket refs resolve against (default: built-in catalog, or $CAPSULE_WICKET_DIR)",
+    )
+    p_dry_run.add_argument(
+        "--caps-from-manifest", dest="caps_from_manifest", action="store_true",
+        help="apply the resolved manifest's caps wicket to the replay: its window and per-action limits "
+        "(e.g. caps/3.0.0) and the fold it names; --cap still sets a window limit (default: off, only --cap limits apply)",
+    )
+    p_dry_run.add_argument(
+        "--no-manifest", dest="no_manifest", action="store_true",
+        help="skip policy-manifest resolution entirely (report carries no manifest_digest)",
+    )
+    p_dry_run.add_argument(
+        "--telemetry-opt-in", action="store_true",
+        help="embed a disclosed, anonymous open-beacon in the report for the M6 (viral unit) metric -- "
+        "requires --telemetry-endpoint too, and is off by default; see `capsule telemetry status`",
+    )
+    p_dry_run.add_argument(
+        "--telemetry-endpoint", default=env_get("CAPSULE_LEDGER_TELEMETRY_ENDPOINT"),
+        help="where the open-beacon above (if enabled) sends its single anonymous event (default: "
+        "$CAPSULE_LEDGER_TELEMETRY_ENDPOINT, or none -- with no endpoint the beacon is never embedded)",
+    )
+    p_dry_run.set_defaults(func=_cmd_guard_dry_run)
+
+    p_enforce = guard_sub.add_parser(
+        "enforce", help="record locally that this install has moved from dry-run to enforce (telemetry marker only)"
+    )
+    p_enforce.set_defaults(func=_cmd_guard_enforce)
+
+    return guard

capsule_engine/cli/init_cmds.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``capsule init --pack <name>``: install a starter pack in observe mode.
+
+Materializes the pack's constraints and folds into ``<project-dir>/.capsule/``,
+writes the policy manifest fragment that cites them plus the pack itself (by
+digest, mode ``observe``) -- so which pack version is in force is provable --
+and, when ``--ledger`` is given, records that installation as a signed
+``policy_manifest_activated`` event capsule (``packs/install.py``'s
+``record_pack_activation``).
+
+When ``--pins`` is given, every artifact this install would trust (the pack
+itself, plus every fold it ships) is verified against that pins file before
+anything is installed -- fail closed on a missing or mismatched pin,
+nothing materialized, nothing recorded (``packs/pins.py``). This stands in
+for a live ``capsule-registry`` fetch, which does not exist yet
+(registry-architecture-and-namespace-2026-08-10.md §6); the verification
+gate's shape does not change when that swap happens later. Without
+``--pins``, this command prints each artifact's own digest so a first
+install can seed a pins file for the next one.
+
+This command does not run anything against live traffic itself -- it hands
+back the manifest a caller's own integration resolves and builds a
+``GuardEngine`` from (``packs.build_engine``), calling
+``GuardEngine.check(..., dry_run=True)`` for as long as the pack stays in
+observe mode. "Observe mode" is a property of the installed manifest
+(``PackRef.mode``), not something this command enforces at runtime.
+"""
+from __future__ import annotations
+
+import argparse
+import secrets
+import sys
+from pathlib import Path
+
+from cll.ledger import LedgerStore
+
+from ..envcompat import env_get
+from ..guards.signing import LocalSigner
+from ..packs import (
+    PackDefinitionError,
+    RegistryPinError,
+    install_pack,
+    load_pack_dir,
+    load_pins_file,
+    record_pack_activation,
+    verify_pins,
+)
+
+__all__ = ["add_parser"]
+
+BUILTIN_PACK_CATALOG_DIR = Path(__file__).resolve().parent.parent / "packs" / "catalog"
+
+_KEY_ID_ENV = "CAPSULE_MCP_SIGNING_KEY_ID"
+_SECRET_ENV = "CAPSULE_MCP_SIGNING_SECRET"
+
+
+def _available_packs(catalog_dir: Path) -> list[str]:
+    if not catalog_dir.is_dir():
+        return []
+    return sorted(p.name for p in catalog_dir.iterdir() if (p / "pack.yaml").is_file())
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    catalog_dir = Path(args.pack_catalog_dir) if args.pack_catalog_dir else BUILTIN_PACK_CATALOG_DIR
+    pack_dir = catalog_dir / args.pack
+
+    if not (pack_dir / "pack.yaml").is_file():
+        available = _available_packs(catalog_dir)
+        print(f"capsule init: no pack named {args.pack!r} in {catalog_dir}", file=sys.stderr)
+        print(f"  available packs: {available or '<none>'}", file=sys.stderr)
+        return 2
+
+    try:
+        pack = load_pack_dir(pack_dir)
+    except PackDefinitionError as exc:
+        print(f"capsule init: pack {args.pack!r} failed to load ({exc.reason}): {exc}", file=sys.stderr)
+        return 1
+
+    if args.pins:
+        try:
+            pins = load_pins_file(args.pins)
+            verify_pins(pack, pins)
+        except RegistryPinError as exc:
+            print(f"capsule init: registry-pin verification failed ({exc.reason}): {exc}", file=sys.stderr)
+            print("nothing installed -- fail closed on a missing or mismatched pin.", file=sys.stderr)
+            return 1
+        print(f"registry-pin verification passed against {args.pins} ({1 + len(pack.folds)} artifact(s))")
+
+    project_dir = Path(args.project_dir)
+    installed = install_pack(pack, project_dir=project_dir, mode="observe")
+
+    print(f"installed {pack.pack_id} in observe mode")
+    print(f"  manifest:      {installed.manifest_path}")
+    print(f"  manifest id:   {installed.manifest.manifest_id}")
+    print(f"  manifest digest: {installed.resolved.manifest_digest}")
+    print(f"  fold catalog:  {installed.fold_catalog_dir}")
+    print(f"  wicket catalog: {installed.wicket_catalog_dir}")
+    print(f"  obligations:   {', '.join(o.id for o in pack.obligations)}")
+    if not args.pins:
+        print("  artifact digests (seed a pins file with these to verify future installs with --pins):")
+        print(f"    {pack.pack_id}: {pack.definition_digest()}")
+        for fold in pack.folds:
+            print(f"    {fold.fold_id}: {fold.definition_digest()}")
+    print(
+        "observe mode: every action this pack governs will be recorded with its would-be verdict "
+        "(allow/deny/escalate) -- nothing is enforced until a human runs `capsule enforce --pack "
+        f"{args.pack}` (not yet built)."
+    )
+
+    if not args.ledger:
+        print()
+        print("no --ledger given: manifest written to disk only, no activation capsule recorded")
+        return 0
+
+    key_id = args.key_id or env_get(_KEY_ID_ENV)
+    secret_text = args.secret or env_get(_SECRET_ENV)
+    generated_secret = secret_text is None
+    if key_id is None:
+        key_id = f"{args.operator}-pack-install-key"
+    if secret_text is None:
+        secret_text = secrets.token_hex(32)
+    signer = LocalSigner(key_id=key_id, secret=secret_text.encode("utf-8"))
+
+    ledger = LedgerStore(args.ledger)
+    try:
+        capsule = record_pack_activation(
+            installed, ledger=ledger, operator=args.operator, developer=args.developer, signer=signer
+        )
+    finally:
+        ledger.close()
+
+    print()
+    print(f"activation recorded: {capsule['capsule_id']}")
+    if generated_secret:
+        print("(signed with a freshly generated key -- not persisted anywhere; pass --key-id/--secret, or set "
+              f"${_KEY_ID_ENV}/${_SECRET_ENV}, to reuse a stable key next time)")
+        print(f"  export {_KEY_ID_ENV}={key_id}")
+        print(f"  export {_SECRET_ENV}={secret_text}")
+    return 0
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    p_init = sub.add_parser("init", help="install a starter pack in observe mode (records, enforces nothing)")
+    p_init.add_argument("--pack", required=True, help="pack name, e.g. payments-safety (built-in catalog)")
+    p_init.add_argument(
+        "--project-dir", default=".", help="where to materialize .capsule/ (catalogs + manifest); default: cwd"
+    )
+    p_init.add_argument(
+        "--pack-catalog-dir", default=None, help="override the built-in pack catalog directory (mainly for tests)"
+    )
+    p_init.add_argument(
+        "--pins", default=None,
+        help="pins file (artifact id -> 64-hex digest) to verify the pack and its folds against before "
+        "installing; fail closed on a missing or mismatched pin (default: none, no verification -- "
+        "this command still prints each artifact's digest so you can seed one)",
+    )
+    p_init.add_argument(
+        "--ledger", default=None,
+        help="ledger store directory to record this install's activation capsule into (default: none, manifest "
+        "is still written to disk)",
+    )
+    p_init.add_argument("--operator", default="local", help="operator identity for the activation capsule (default: 'local')")
+    p_init.add_argument(
+        "--developer", default="capsule-init-tool", help="developer identity for the activation capsule"
+    )
+    p_init.add_argument("--key-id", default=None, help=f"signing key id for the activation capsule (default: ${_KEY_ID_ENV})")
+    p_init.add_argument("--secret", default=None, help=f"signing key secret (default: ${_SECRET_ENV}, or freshly generated)")
+    p_init.set_defaults(func=_cmd_init)
+    return p_init

capsule_engine/cli/main.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsule-engine` CLI entry point: the verbs this repo owns -- `guard`
+(dry-run replay + report, enforce marker), `telemetry` (disclosure/status,
+funnel report), `init` (install a starter pack), `constraints` (list the
+registered guard checks + action-class taxonomy), `tenant`
+(engine-instance-per-tenant provisioning), plus the evidence verbs `verify`
+(verify one ledger record or an offline bundle), `bundle` (produce a
+self-contained verifiable slice of the ledger), and `console` (serve the
+local console UI) -- registered only in the "full" packaging arm, same
+two-arm switch (`capsule_engine.packaging`) the original monorepo used.
+
+This is a deliberately minimal dispatcher: the original monorepo's
+`cli/main.py` wired every verb across ledger, folds, guards, packs, policy,
+console, telemetry, etc. Post-split, this repo only owns the verb modules
+that actually live here -- the rest stayed with their owning repo.
+`cli/format.py` is not wired as a subcommand: it has no `add_parser`, it is
+shared output-formatting helpers used by the verbs above.
+
+This module is a thin dispatcher; each verb's logic lives in its own
+`cli/*_cmd.py` module.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .. import packaging
+from . import (
+    bundle_cmd,
+    console_cmd,
+    constraints_cmd,
+    guard_cmds,
+    init_cmds,
+    packs_cmds,
+    telemetry_cmd,
+    tenant_cmds,
+    verify_cmd,
+)
+
+__all__ = ["main"]
+
+
+def _build_parser(arm: str | None = None) -> argparse.ArgumentParser:
+    arm = arm or packaging.current_arm()
+    parser = argparse.ArgumentParser(prog="capsule-engine", description="capsule-engine control plane")
+    parser.add_argument("--version", action="store_true", help="print the version and exit")
+    sub = parser.add_subparsers(dest="command")
+
+    init_cmds.add_parser(sub)
+    constraints_cmd.add_parser(sub)
+    guard_cmds.add_parser(sub)
+    tenant_cmds.add_parser(sub)
+    telemetry_cmd.add_parser(sub)
+    packs_cmds.add_parser(sub)
+
+    # The record-query/evidence verbs -- capsule verify, the shareable
+    # bundle, and the local console UI -- are the "evidence": registered
+    # only in the "full" arm. See ``packaging.py``'s module docstring for
+    # why an env var, not a fork, drives this.
+    if packaging.evidence_visible(arm):
+        verify_cmd.add_parser(sub)
+        bundle_cmd.add_parser(sub)
+        console_cmd.add_parser(sub)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        from .. import __version__
+
+        print(__version__)
+        return 0
+
+    from ..telemetry.record import record_install_seen
+
+    record_install_seen(packaging.current_arm())
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "constraints":
+        if getattr(args, "constraints_command", None) is None:
+            args.constraints_parser.print_help()
+            return 0
+        return args.func(args)
+
+    if args.command == "guard":
+        if getattr(args, "guard_command", None) is None:
+            args.guard_parser.print_help()
+            return 0
+        return args.func(args)
+
+    if args.command == "tenant":
+        if getattr(args, "tenant_command", None) is None:
+            args.tenant_parser.print_help()
+            return 0
+        return args.func(args)
+
+    if args.command == "telemetry":
+        if getattr(args, "telemetry_command", None) is None:
+            args.telemetry_parser.print_help()
+            return 0
+        return args.func(args)
+
+    if args.command == "packs":
+        if getattr(args, "packs_command", None) is None:
+            args.packs_parser.print_help()
+            return 0
+        return args.func(args)
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())