warrant-graph 2.0.0a1__py3-none-any.whl

warrant/__init__.py

@@ -0,0 +1,11 @@
+"""Warrant 2: transitions of work, exact closures and what remains open (SPEC.md)."""
+from .jcs import canon, loads
+from .engine import assess, capsule, frontier, profile, questions, reliance
+from .keys import Key
+from .records import accept, challenge, duty, grant, item, observation, record, transition
+from .store import Snapshot, Store, Trust
+
+__version__ = "2.0.0a1"
+__all__ = ["Key", "Snapshot", "Store", "Trust", "accept", "assess", "canon", "capsule", "challenge", "duty",
+           "frontier", "grant", "item", "loads", "observation", "profile", "questions", "record", "reliance",
+           "transition"]

warrant/bindings.py

@@ -0,0 +1,145 @@
+"""Bindings and roles of a repository's trust (the open circle of witnesses, part A, and
+AMEND 1 of #170): the one rule tools/claims.py and a warrant-agent workspace admit keys by.
+
+A binding certifies itself: its key signs canon({actor, public, purpose}). `admit_bindings`
+admits one mechanically, in file order, under the roles .warrant/roles.json pins; nobody judges
+who may join. A binding grants only "this key signs as this actor" (SPEC §6). This module reads
+documents; it writes none and runs nothing (the claims tool writes them)."""
+from . import jcs as C
+from . import keys as K
+from . import records as R
+from . import shapes as S
+from .store import Trust
+
+
+# Open circle of witnesses: a binding certifies itself (its key signs it); nobody admits anyone.
+BINDINGS = "warrant-claims/bindings@1"       # .warrant/trust.json: {"bindings": BINDINGS, "keys": [...]}
+BINDING = "warrant-claims/binding@1"         # the purpose a proof signs: canon({actor, public, purpose})
+BINDING_FIELDS = ("actor", "public", "proof")
+ROLES = "warrant-claims/roles@1"             # .warrant/roles.json: the actors the configuration gives a role
+COLLECTIVE = "collective"                    # a role no key signs as (readers): never bindable
+
+
+def binding_message(actor, public):
+    """The bytes a binding's proof signs: canon({actor, public, purpose}). It starts with `{`,
+    so it is never the message of a record signature ("warrant-sig-v1:" || id)."""
+    return C.canon({"actor": actor, "public": public, "purpose": BINDING})
+
+
+def binding_proof(key, actor):
+    return key.sign(binding_message(actor, key.public))
+
+
+def read_roles(doc):
+    """({actor: public hex | None | COLLECTIVE}, problems) of a roles document (.warrant/roles.json).
+
+    AMEND 1 of #170: a name the repository's own configuration gives a role (an acceptor, a
+    creditor, the claims' author) is not first-come. Its key is pinned here, as a receiver's
+    profile pins the keys it trusts: a hex64 public key (a binding of that actor is admitted
+    with exactly that key), null (reserved: not bindable until a pin names its key) or
+    "collective" (a role no key signs as, such as `readers`: never bindable). Every other
+    name stays first-come. Changing who a role is, is a diff of this reviewed file."""
+    if not (isinstance(doc, dict) and set(doc) == {"roles", "actors"} and doc["roles"] == ROLES
+            and isinstance(doc["actors"], dict)):
+        return {}, [("ROLES_SHAPE", f".warrant/roles.json is not {{\"roles\": {ROLES!r}, \"actors\": {{...}}}}")]
+    roles, problems = {}, []
+    for actor, v in doc["actors"].items():
+        try:
+            R.check_actor(actor)
+        except R.Invalid as e:
+            problems.append(("ROLES_SHAPE", f".warrant/roles.json: {actor[:60]!r} is not an actor id: {e}"))
+            continue
+        if not (v is None or v == COLLECTIVE or S.hex64(v)):
+            problems.append(("ROLES_SHAPE", f".warrant/roles.json: {actor}: a role is a hex64 public key, null or "
+                             f"{COLLECTIVE!r}, not {str(v)[:70]!r}"))
+            continue
+        roles[actor] = v
+    return roles, problems
+
+
+def _role_name(v):
+    """A role value for a message: 'key <id>' for a key, else what it is (never raises)."""
+    if S.hex64(v):
+        return f"key {K.key_id(v)[:12]}"
+    if v == COLLECTIVE:
+        return "collective"
+    return "reserved" if v is None else repr(v)[:40]
+
+
+def admit_bindings(doc, legacy=False, roles=None):
+    """(admitted [(actor, public)], problems [(code, detail)]) of a bindings document.
+
+    A binding is admitted mechanically, in file order, iff its proof is the signature of its
+    own key over binding_message(actor, public), its actor id has SPEC-3-21's shape, its
+    actor's role (`roles`, read_roles) admits that key, its key is not bound already, and its
+    actor is not bound already to another key: the first binding of a name with no role
+    wins, and a second key for it would need a record signed by the first, which this tool
+    does not implement (rotation is out of scope), so it is refused. Nobody judges who may
+    join; what a binding grants is only "this key signs as this actor" (SPEC §6). `legacy`
+    reads a trust/2 document (actor, public, no proof) as admitted: only for a base revision
+    written before bindings carried proofs."""
+    if legacy and isinstance(doc, dict) and doc.get("warrant") == "trust/2":
+        try:
+            return [(a, p) for a, p in Trust(doc).keys.values()], []
+        except R.Invalid as e:
+            return [], [("BINDINGS_SHAPE", f".warrant/trust.json: {e}")]
+    if not (isinstance(doc, dict) and set(doc) == {"bindings", "keys"} and doc["bindings"] == BINDINGS
+            and isinstance(doc["keys"], list)):
+        return [], [("BINDINGS_SHAPE", f".warrant/trust.json is not {{\"bindings\": {BINDINGS!r}, \"keys\": [...]}} "
+                                       "(tools/claims.py bind writes it)")]
+    admitted, problems = [], []
+    publics = [k.get("public") for k in doc["keys"] if isinstance(k, dict)]
+    for i, k in enumerate(doc["keys"]):
+        code, why = _binding_problem(k, publics, admitted, roles or {})
+        if code:
+            problems.append((code, f".warrant/trust.json keys[{i}]: {why}"))
+        else:
+            admitted.append((k["actor"], k["public"]))
+    return admitted, problems
+
+
+def _binding_problem(k, publics, admitted, roles):
+    """(code, why) when entry `k` is not admitted after `admitted`, else (None, None)."""
+    if not (isinstance(k, dict) and set(k) <= set(BINDING_FIELDS) and {"actor", "public"} <= set(k)
+            and S.hex64(k["public"])):
+        return "BINDING_SHAPE", f"an entry is {{actor, public: hex64, proof: hex128}}, not {str(k)[:120]}"
+    try:
+        R.check_actor(k["actor"])
+    except R.Invalid as e:
+        return "BINDING_ACTOR_SHAPE", f"{str(k['actor'])[:60]!r} is not an actor id (SPEC-3-21): {e}"
+    if "proof" not in k:
+        return "BINDING_UNPROVEN", f"{k['actor']}: no proof; the key's own signature over the binding is needed"
+    msg = binding_message(k["actor"], k["public"])
+    if not K.verify(k["public"], k["proof"], msg):
+        other = [p for p in publics if p != k["public"] and isinstance(p, str) and K.verify(p, k["proof"], msg)]
+        if other:
+            return "BINDING_PROOF_OTHER_KEY", (f"{k['actor']}: the proof is signed by key {K.key_id(other[0])[:12]}, "
+                                               f"not by the key it binds ({K.key_id(k['public'])[:12]})")
+        return "BINDING_PROOF_FORGED", f"{k['actor']}: the proof is not the bound key's signature over this binding"
+    role = roles.get(k["actor"], k["public"])
+    if role != k["public"]:                 # one rule; the code only says which kind of role refused it
+        if role == COLLECTIVE:
+            return "BINDING_ROLE_COLLECTIVE", f"{k['actor']} is a collective role in .warrant/roles.json: no key signs as it"
+        if role is None:
+            return "BINDING_ROLE_RESERVED", (f"{k['actor']} is reserved in .warrant/roles.json: it is bindable once a "
+                                             "reviewed pin names its key")
+        return "BINDING_ROLE_KEY", (f"{k['actor']}: .warrant/roles.json pins {_role_name(role)}, this binding is of "
+                                    f"key {K.key_id(k['public'])[:12]}")
+    if any(p == k["public"] for _, p in admitted):
+        return "BINDING_KEY_TWICE", f"key {K.key_id(k['public'])[:12]} is bound already"
+    first = next((p for a, p in admitted if a == k["actor"]), None)
+    if first is not None:
+        return "BINDING_ACTOR_TAKEN", (f"{k['actor']} is bound already to key {K.key_id(first)[:12]}; the first "
+                                       "binding wins, and rotation (a record signed by the first key) is not "
+                                       "implemented, so a second key for an actor is refused")
+    return None, None
+
+
+def trust_of(bindings):
+    """A Trust of (actor, public) pairs, the first binding of each key kept."""
+    seen, pairs = set(), []
+    for a, p in bindings:
+        if p not in seen:
+            seen.add(p)
+            pairs.append((a, p))
+    return Trust(Trust.document(pairs))

warrant/cli.py

@@ -0,0 +1,401 @@
+"""`warrant` — the one command-line interface of Warrant 2 (SPEC.md).
+
+Writing:   init, key, trust, blob, file, accept, observe, manifest, compute
+Reading:   assess, reliance, frontier, questions, capsule
+Every reading command assesses one view: --store, --trust, --profile, --as-of,
+and optionally --current and --workspace. Output is JSON."""
+import argparse
+import base64
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from . import jcs as C
+from . import compute as P
+from . import engine as E
+from . import limits as L
+from . import records as R
+from . import triggers as TR
+from .keys import Key
+from .store import Store, Trust
+
+
+def _out(doc):
+    sys.stdout.write(json.dumps(doc, indent=2, ensure_ascii=False, sort_keys=True) + "\n")
+
+
+def _read_json(arg):
+    if arg == "-":
+        return json.loads(sys.stdin.read())
+    if arg.lstrip().startswith(("{", "[")):
+        return json.loads(arg)
+    return json.loads(Path(arg).read_text())
+
+
+def _key(path):
+    return Key.from_seed_hex(Path(path).read_text())
+
+
+def _now(v):
+    return int(time.time()) if v is None else v
+
+
+# ---------------------------------------------------------------- writing
+
+def cmd_init(a):
+    Store(a.store).init()
+    _out({"store": str(Path(a.store))})
+
+
+def cmd_key(a):
+    p = Path(a.out)
+    if p.exists():
+        raise SystemExit(f"refusing to overwrite {p}")
+    k = Key.generate()
+    fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(k.seed_hex() + "\n")
+    _out({"key_file": str(p), "public": k.public, "key_id": k.id})
+
+
+def cmd_trust(a):
+    p = Path(a.trust)
+    doc = json.loads(p.read_text()) if p.exists() else Trust.document([])
+    pub = _key(a.key).public if a.key else a.public
+    doc["keys"].append({"actor": a.actor, "public": pub})
+    Trust(doc)                                    # refuse a malformed or doubly bound file
+    p.write_bytes(C.canon(doc))
+    _out({"trust": str(p), "actor": a.actor, "public": pub})
+
+
+def cmd_blob(a):
+    s = Store(a.store).init()
+    if a.json is not None:
+        h = s.put_json(_read_json(a.json))
+    else:
+        h = s.put_blob(sys.stdin.buffer.read() if a.file == "-" else Path(a.file).read_bytes())
+    _out({"blob": h})
+
+
+# Structural members `warrant file` fills when a body omits them. Only empty
+# values: nothing here states a meaning. Semantic members (a duty's statement,
+# holder, owed_to, accept_by, condition; a transition's basis, established,
+# residual, closes) are never filled, so their absence is still refused.
+STRUCTURAL = {
+    "duty": {"release_by": [], "schedule": None, "requires": [], "serves": [], "answers": None, "subject": None},
+    "transition": {"relied_on": [], "opened": [], "subject": None, "supersedes": [], "triggers": []},
+}
+
+
+def fill(rtype, body):
+    """`body` with omitted structural members filled; given members are kept as they are.
+    A transition that omits `evidence` carries exactly the evidence its items cite."""
+    if rtype not in STRUCTURAL or not isinstance(body, dict):
+        return body
+    out = {k: v for k, v in STRUCTURAL[rtype].items() if k not in body}
+    if rtype == "transition" and "evidence" not in body and isinstance(body.get("closes"), list):
+        out["evidence"] = sorted({h for m in body["closes"] if isinstance(m, dict)
+                                  for h in (m.get("evidence") if isinstance(m.get("evidence"), list) else [])})
+    out.update(body)
+    return out
+
+
+def _store(a):
+    """The store a signer writes, with its own verdicts directory if it names one (F44)."""
+    return Store(a.store, verdicts=a.verdicts).init()
+
+
+def _append(s, rtype, actor, at, body, key):
+    """File a record extending `actor`'s chain in store `s` (SPEC §3: `prev` is its head)."""
+    try:
+        return s.append(rtype, actor, at, body, key)
+    except R.Invalid as e:
+        raise SystemExit(f"invalid {rtype}: {e}")
+    except ValueError as e:
+        raise SystemExit(str(e))
+
+
+def cmd_file(a):
+    s = _store(a)
+    body = fill(a.type, _read_json(a.body))
+    rid = _append(s, a.type, a.actor, _now(a.at), body, _key(a.key))
+    if a.id:
+        sys.stdout.write(rid + "\n")
+    else:
+        _out({"record": rid, "type": a.type})
+
+
+def cmd_accept(a):
+    """Accept one exact item (or a transition's results) as it is filed."""
+    s = _store(a)
+    snap = s.snapshot()
+    env = C.loads(snap.records[a.transition])
+    t = env["record"]["body"]
+    ev = t["evidence"] if a.item is None else t["closes"][a.item]["evidence"]
+    rid = _append(s, "accept", a.actor, _now(a.at), R.accept(a.transition, a.item, ev, a.support or []), _key(a.key))
+    _out({"record": rid, "type": "accept"})
+
+
+def cmd_observe(a):
+    """Run a probe once and file what was observed, when, and how."""
+    s = _store(a)
+    probe = _read_json(a.probe)
+    if not (isinstance(probe, dict) and isinstance(probe.get("argv"), list) and probe["argv"]):
+        raise SystemExit("a probe is {\"argv\": [...], ...}: the command this observer runs")
+    probe_h = s.put_json(probe)
+    t0 = int(time.time())
+    try:
+        p = subprocess.run(probe["argv"], capture_output=True, timeout=probe.get("timeout", 30), check=False)
+        result = p.stdout.decode(errors="replace").strip()[:R.MAX_TEXT]
+        raw = [s.put_blob(p.stdout), s.put_json({"exit": p.returncode, "stderr": p.stderr.decode(errors="replace")[-2000:]})]
+    except (OSError, subprocess.TimeoutExpired) as e:
+        result, raw = f"PROBE_FAILED: {type(e).__name__}", []
+    t1 = max(t0, int(time.time()))
+    body = R.observation(a.target, probe_h, [t0, t1], result, raw)
+    rid = _append(s, "observation", a.actor, _now(a.at) if a.at is not None else t1, body, _key(a.key))
+    _out({"record": rid, "type": "observation", "result": result, "window": [t0, t1]})
+
+
+def cmd_manifest(a):
+    s = Store(a.store).init()
+    try:
+        doc = TR.manifest(a.repo, a.rev, sorted(a.paths))
+    except TR.Refusal as e:
+        raise SystemExit(f"manifest refused: {e}")
+    _out({"blob": s.put_json(doc), "commit": TR.resolve(a.repo, a.rev)})
+
+
+# ---------------------------------------------------------------- compute (producer side)
+
+def _env_blobs(s, env_h):
+    snap = s.snapshot()
+    doc = snap.json_blob(env_h)
+    if doc is None or P.environment_problem(doc):
+        raise SystemExit("not a sigma environment manifest in this store")
+    hashes = P.environment_hashes(doc)
+    return hashes, {h: snap.blobs[h] for h in hashes if h in snap.blobs}
+
+
+def _call(op, args, blobs=None):
+    try:
+        out = P.Provider.capture().call(op, args, blobs)
+    except P.ProviderError as e:
+        raise SystemExit(f"provider: {e}")
+    if "refused" in out:
+        raise SystemExit(f"provider refused: {out['refused']}")
+    return out
+
+
+def cmd_compute(a):
+    s = Store(a.store).init()
+    runtime = {"book1": P.BOOK1, "rich": P.RICH}[a.runtime]
+    if a.op == "provider":
+        try:
+            p = P.Provider.capture()
+        except P.ProviderError as e:
+            raise SystemExit(f"provider: {e}")
+        return _out({"provider": p.id, "where": p.where, "files": p.identity["files"]})
+    if a.op == "term":
+        out = _call("term", {"expr": a.expr})
+        nodes = [s.put_blob(base64.b64decode(b)) for b in out["nodes"].values()]
+        env_h = s.put_json(P.environment_doc(nodes))
+        return _out({"input": out["input"], "environment": env_h, "runtime": runtime, "nodes": len(nodes)})
+    hashes, blobs = _env_blobs(s, a.environment)
+    base = {"runtime": runtime, "input": a.input, "hashes": hashes}
+    if a.op == "start":
+        out = _call("start", base, blobs)
+    elif a.op == "advance":
+        snap = s.snapshot()
+        out = _call("advance", dict(base, checkpoint=base64.b64encode(snap.blobs[a.checkpoint]).decode(),
+                                    state=base64.b64encode(snap.blobs[a.state]).decode(), credit=a.credit), blobs)
+    elif a.op == "cycle":
+        out = _call("find_cycle", dict(base, max_steps=a.max_steps), blobs)
+        if out.get("witness") is None:
+            return _out({"cycle": None, "outcome": out.get("outcome")})
+        w = s.put_blob(base64.b64decode(out["witness"]))
+        doc = {"cycle": "sigma-resume", "target": a.target, "input": a.input, "environment": a.environment,
+               "witness": w, "lost": []}
+        return _out({"cycle": s.put_json(doc), "witness": w})
+    else:
+        raise SystemExit(f"unknown compute op {a.op}")
+    ck = s.put_blob(base64.b64decode(out["checkpoint"]))
+    st = s.put_blob(base64.b64decode(out["state"]))
+    res = {"outcome": out.get("outcome", "STARTED"), "checkpoint": ck, "state": st, "result": out.get("result")}
+    if out.get("outcome") == "NORMAL_FORM" and a.target:
+        res["receipt"] = s.put_json({"receipt": "sigma-resume", "target": a.target, "input": a.input,
+                                     "environment": a.environment, "checkpoint": ck, "state": st,
+                                     "claimed": out["result"], "lost": []})
+    _out(res)
+
+
+# ---------------------------------------------------------------- reading
+
+def _limits(a):
+    out = {}
+    for item in a.limit:
+        name, _, value = item.partition("=")
+        if not value.isdigit():
+            raise SystemExit(f"--limit {item!r}: NAME=N")
+        out[name] = int(value)
+    try:
+        return L.resolve(out)
+    except ValueError as e:
+        raise SystemExit(str(e)) from None
+
+
+def _report(a):
+    s = Store(a.store)
+    lim = _limits(a)
+    snap = s.snapshot(limits=lim)
+    trust = Trust.load(a.trust)
+    prof = _read_json(a.profile) if a.profile else E.profile()
+    ws = None
+    if a.workspace:
+        repo, _, rev = a.workspace.rpartition("@")
+        ws = (repo, rev or "HEAD")
+    try:
+        provider = P.Provider.capture()
+    except P.ProviderError as e:
+        print(f"warning: provider unavailable, replays are UNVERIFIED: {e}", file=sys.stderr)
+        provider = None
+    return E.assess(snap, trust, _now(a.as_of), prof, current=a.current or [], workspace=ws, provider=provider,
+                    replay_cache=a.replay_cache, limits=lim, verdicts=a.verdicts)
+
+
+def cmd_assess(a):
+    _out(_report(a))
+
+
+def cmd_reliance(a):
+    _out(E.reliance(_report(a), a.target, a.use))
+
+
+def cmd_frontier(a):
+    rep = _report(a)
+    _out({"assessment_id": rep["assessment_id"], "actor": a.actor, "frontier": E.frontier(rep, a.actor)})
+
+
+def cmd_questions(a):
+    rep = _report(a)
+    _out({"assessment_id": rep["assessment_id"], "questions": E.questions(rep, a.scope, owned=a.all)})
+
+
+def cmd_capsule(a):
+    _out(E.capsule(_report(a), a.target, a.use))
+
+
+def build_parser():
+    ap = argparse.ArgumentParser(prog="warrant", description=__doc__, allow_abbrev=False,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def store(p):
+        p.add_argument("--store", required=True)
+
+    def signer(p):
+        store(p)
+        p.add_argument("--key", required=True, help="file holding the signer's Ed25519 seed (hex)")
+        p.add_argument("--actor", required=True)
+        p.add_argument("--at", type=int, help="record time (default: now)")
+        p.add_argument("--verdicts", help="directory of this signer's earlier authentication verdicts (cost only)")
+
+    def view(p):
+        store(p)
+        p.add_argument("--trust", required=True)
+        p.add_argument("--profile", help="the recipient's profile JSON (default: one use 'act', no acceptors)")
+        p.add_argument("--as-of", type=int, help="end of the view (default: now)")
+        p.add_argument("--current", action="append", help="a revision the recipient treats as current")
+        p.add_argument("--workspace", help="REPO@REV for subject_changed triggers")
+        p.add_argument("--replay-cache", help="directory of this recipient's earlier verified replays (cost only)")
+        p.add_argument("--verdicts", help="directory of this recipient's earlier authentication verdicts (cost only)")
+        p.add_argument("--limit", action="append", default=[], metavar="NAME=N",
+                       help="override an admission limit (SPEC §9), e.g. duty_periods=50000")
+
+    p = sub.add_parser("init", help="create a store")
+    store(p)
+    p.set_defaults(fn=cmd_init)
+    p = sub.add_parser("key", help="generate an Ed25519 key file (0600, never overwritten)")
+    p.add_argument("--out", required=True)
+    p.set_defaults(fn=cmd_key)
+    p = sub.add_parser("trust", help="bind a key to an actor in a trust file")
+    p.add_argument("--trust", required=True)
+    p.add_argument("--actor", required=True)
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--key")
+    g.add_argument("--public")
+    p.set_defaults(fn=cmd_trust)
+    p = sub.add_parser("blob", help="add bytes (FILE or -) or a JSON document (--json) to the store")
+    store(p)
+    p.add_argument("file", nargs="?", default="-")
+    p.add_argument("--json")
+    p.set_defaults(fn=cmd_blob)
+    p = sub.add_parser("file", help="sign and file a record body (SPEC §3); a duty or transition body may omit "
+                                    "its structural members (empty lists, nulls; a transition's evidence is "
+                                    "then the evidence its items cite)")
+    signer(p)
+    p.add_argument("--type", required=True, choices=R.TYPES)
+    p.add_argument("--id", action="store_true", help="print only the new record id")
+    p.add_argument("body", help="JSON body, a file, or -")
+    p.set_defaults(fn=cmd_file)
+    p = sub.add_parser("accept", help="accept one exact item of a transition, or its results")
+    signer(p)
+    p.add_argument("transition")
+    p.add_argument("--item", type=int, help="item index; omit to accept the transition's results")
+    p.add_argument("--support", action="append")
+    p.set_defaults(fn=cmd_accept)
+    p = sub.add_parser("observe", help="run a probe and file the observation")
+    signer(p)
+    p.add_argument("--target", required=True)
+    p.add_argument("--probe", required=True, help='JSON {"argv": [...], "timeout": s}')
+    p.set_defaults(fn=cmd_observe)
+    p = sub.add_parser("manifest", help="store a subject_changed baseline for explicit paths at a revision")
+    store(p)
+    p.add_argument("--repo", required=True)
+    p.add_argument("--rev", required=True)
+    p.add_argument("paths", nargs="+")
+    p.set_defaults(fn=cmd_manifest)
+    p = sub.add_parser("compute", help="the installed Sigma provider: provider (its identity), term, start, advance, cycle")
+    store(p)
+    p.add_argument("op", choices=("provider", "term", "start", "advance", "cycle"))
+    p.add_argument("--runtime", choices=("book1", "rich"), default="book1")
+    p.add_argument("--expr")
+    p.add_argument("--input")
+    p.add_argument("--environment")
+    p.add_argument("--checkpoint")
+    p.add_argument("--state")
+    p.add_argument("--credit", type=int, default=0)
+    p.add_argument("--max-steps", type=int, default=10000)
+    p.add_argument("--target", help="crossing target named in the receipt or cycle")
+    p.set_defaults(fn=cmd_compute)
+    for name, fn, extra in (("assess", cmd_assess, None), ("reliance", cmd_reliance, "target"),
+                            ("frontier", cmd_frontier, "actor"), ("questions", cmd_questions, None),
+                            ("capsule", cmd_capsule, "target")):
+        p = sub.add_parser(name)
+        view(p)
+        if extra:
+            p.add_argument(extra)
+        if name in ("reliance", "capsule"):
+            p.add_argument("--use", default="act")
+        if name == "questions":
+            p.add_argument("--scope")
+            p.add_argument("--all", action="store_true", help="include questions a duty has taken")
+        p.set_defaults(fn=fn)
+    return ap
+
+
+def main(argv=None):
+    a = build_parser().parse_args(argv)
+    try:
+        a.fn(a)
+    except L.LimitExceeded as e:
+        # An operational refusal (SPEC §9), never a report: nothing was assessed.
+        print(f"warrant: RESOURCE_LIMIT {e}", file=sys.stderr)
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())