repo-context-optimizer 0.1.0__py3-none-any.whl

rco/__init__.py

@@ -0,0 +1,3 @@
+"""repo-context-optimizer: deterministic contract Trees for coding agents."""
+
+__version__ = "0.1.0"

rco/__main__.py

@@ -0,0 +1,6 @@
+"""python -m rco"""
+import sys
+
+from rco.cli import main
+
+sys.exit(main())

rco/build.py

@@ -0,0 +1,88 @@
+"""Build Trees and Maps from a commit (tree-contract section 6)."""
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path, PurePosixPath
+from typing import Sequence
+
+from rco import canon, extract, gitread, modules, redact
+from rco.model import Kind, Map, Module, Node, SourceFile, Tree, node_sort_key
+
+
+def _sorted(n: Node) -> Node:
+    return replace(
+        n,
+        attrs=tuple(sorted(n.attrs)),
+        children=tuple(sorted((_sorted(c) for c in n.children), key=node_sort_key)),
+    )
+
+
+def file_node(path: str, attrs: tuple[tuple[str, str], ...] = ()) -> Node:
+    return Node(Kind.FILE, PurePosixPath(path).name, path, attrs=attrs)
+
+
+def nodes_for(src: SourceFile, link: bool = False) -> list[Node]:
+    """Every extractor that claims the file; FILE outline when none does."""
+    if link:
+        return [file_node(src.path, (("link", "1"),))]
+    if src.data.startswith(gitread.LFS_MAGIC):
+        return [file_node(src.path, (("lfs", "pointer"),))]
+    out: list[Node] = []
+    claimed = False
+    for ex in extract.EXTRACTORS:
+        if ex.claims(src.path):
+            claimed = True
+            out.extend(ex.extract(src))
+    if not claimed:
+        return [file_node(src.path)]
+    # duplicate FILE error nodes from several extractors collapse into one
+    seen: set[tuple] = set()
+    uniq = []
+    for n in out:
+        if n.kind is Kind.FILE:
+            k = (n.name, n.path, n.attrs)
+            if k in seen:
+                continue
+            seen.add(k)
+        uniq.append(n)
+    return uniq
+
+
+def build_tree(module: Module, files: Sequence[SourceFile],
+               links: frozenset[str] = frozenset()) -> Tree:
+    """Tree of one module. files must cover module.files; links are symlink paths."""
+    by_path = {f.path: f for f in files}
+    nodes: list[Node] = []
+    for p in module.files:
+        nodes.extend(nodes_for(by_path[p], p in links))
+    nodes = [_sorted(redact.redact_node(n)) for n in nodes]
+    vers = extract.versions()
+    return Tree(
+        module=module.id,
+        module_hash=canon.module_hash(module, {f.path: f.blob for f in files}, vers),
+        extractors=vers,
+        nodes=tuple(sorted(nodes, key=node_sort_key)),
+    )
+
+
+def build_map(repo: Path, sha: str, only: Sequence[str] | None = None) -> Map:
+    """Map of every module at sha, or of the modules that own the paths in only."""
+    notes: list[str] = []
+    entries: list[gitread.Entry] = []
+    for e in gitread.ls_tree(repo, sha):
+        if e.mode == gitread.MODE_SUBMODULE:
+            notes.append(f"skipped submodule {e.path}")
+        else:
+            entries.append(e)
+    mods = modules.group(e.path for e in entries)
+    if only is not None:
+        want = {modules.module_of(p.strip("/")) for p in only}
+        mods = tuple(m for m in mods if m.id in want)
+    keep = {p for m in mods for p in m.files}
+    entries = [e for e in entries if e.path in keep]
+    links = frozenset(e.path for e in entries if e.mode == gitread.MODE_SYMLINK)
+    data = gitread.read_blobs(repo, [e.blob for e in entries if e.path not in links])
+    srcs = {e.path: SourceFile(e.path, e.blob, b"" if e.path in links else data[e.blob])
+            for e in entries}
+    trees = tuple(build_tree(m, [srcs[p] for p in m.files], links) for m in mods)
+    return Map(sha=sha, trees=trees, notes=tuple(sorted(notes)))

rco/canon.py

@@ -0,0 +1,127 @@
+"""Canonical JSON and hashes (docs/design/tree-contract.md, section 3)."""
+from __future__ import annotations
+
+import hashlib
+import json
+
+from rco.model import Kind, Map, Module, Node, Tree
+
+SCHEMA_TREE = "rco.tree/1"
+SCHEMA_MAP = "rco.map/1"
+SCHEMA_MODULEHASH = "rco.modulehash/1"
+
+_NODE_KEYS = frozenset({"kind", "name", "path", "sig", "doc", "attrs", "children"})
+_TREE_KEYS = frozenset({"schema", "module", "module_hash", "extractors", "nodes", "tree_hash"})
+_MAP_KEYS = frozenset({"schema", "sha", "notes", "modules"})
+
+
+def canonical_json(obj) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False, allow_nan=False).encode("utf-8")
+
+
+def sha256_tag(b: bytes) -> str:
+    return "sha256:" + hashlib.sha256(b).hexdigest()
+
+
+def node_to_obj(n: Node) -> dict:
+    o: dict = {"kind": n.kind.value, "name": n.name}
+    if n.path:
+        o["path"] = n.path
+    if n.sig:
+        o["sig"] = n.sig
+    if n.doc:
+        o["doc"] = n.doc
+    if n.attrs:
+        o["attrs"] = dict(n.attrs)
+    if n.children:
+        o["children"] = [node_to_obj(c) for c in n.children]
+    return o
+
+
+def tree_to_obj(t: Tree) -> dict:
+    return {
+        "schema": SCHEMA_TREE,
+        "module": t.module,
+        "module_hash": t.module_hash,
+        "extractors": [list(e) for e in t.extractors],
+        "nodes": [node_to_obj(n) for n in t.nodes],
+    }
+
+
+def tree_hash(t: Tree) -> str:
+    """sha256 of the Tree's contract: everything but module_hash.
+
+    module_hash moves on any file edit; TreeHash must move only when the
+    contract does (README incremental update: "TreeHash changed? no,
+    internal change").
+    """
+    obj = tree_to_obj(t)
+    del obj["module_hash"]
+    return sha256_tag(canonical_json(obj))
+
+
+def map_to_obj(m: Map) -> dict:
+    mods = []
+    for t in m.trees:
+        o = tree_to_obj(t)
+        o["tree_hash"] = tree_hash(t)
+        mods.append(o)
+    return {"schema": SCHEMA_MAP, "sha": m.sha, "notes": list(m.notes), "modules": mods}
+
+
+def module_hash(module: Module, blobs: dict[str, str],
+                extractors: tuple[tuple[str, str], ...]) -> str:
+    return sha256_tag(canonical_json({
+        "schema": SCHEMA_MODULEHASH,
+        "module": module.id,
+        "files": [[p, blobs[p]] for p in module.files],
+        "extractors": [list(e) for e in extractors],
+    }))
+
+
+def _strict(o: dict, allowed: frozenset[str], what: str) -> None:
+    if not isinstance(o, dict):
+        raise ValueError(f"{what}: expected an object")
+    extra = set(o) - allowed
+    if extra:
+        raise ValueError(f"{what}: unknown keys {sorted(extra)}")
+
+
+def node_from_obj(o: dict) -> Node:
+    _strict(o, _NODE_KEYS, "node")
+    attrs = o.get("attrs", {})
+    if not isinstance(attrs, dict):
+        raise ValueError("node: attrs must be an object")
+    return Node(
+        kind=Kind(o["kind"]),
+        name=str(o["name"]),
+        path=str(o.get("path", "")),
+        sig=str(o.get("sig", "")),
+        doc=str(o.get("doc", "")),
+        attrs=tuple(sorted((str(k), str(v)) for k, v in attrs.items())),
+        children=tuple(node_from_obj(c) for c in o.get("children", [])),
+    )
+
+
+def tree_from_obj(o: dict) -> Tree:
+    _strict(o, _TREE_KEYS, "tree")
+    if o.get("schema") != SCHEMA_TREE:
+        raise ValueError(f"tree: schema must be {SCHEMA_TREE}")
+    return Tree(
+        module=str(o["module"]),
+        module_hash=str(o["module_hash"]),
+        extractors=tuple((str(a), str(b)) for a, b in o["extractors"]),
+        nodes=tuple(node_from_obj(n) for n in o["nodes"]),
+    )
+
+
+def map_from_obj(o: dict) -> Map:
+    _strict(o, _MAP_KEYS, "map")
+    if o.get("schema") != SCHEMA_MAP:
+        raise ValueError(f"map: schema must be {SCHEMA_MAP}")
+    return Map(
+        sha=str(o["sha"]),
+        trees=tuple(tree_from_obj(t) for t in o["modules"]),
+        notes=tuple(str(n) for n in o.get("notes", [])),
+    )

rco/check.py

@@ -0,0 +1,229 @@
+"""Map checker (README Verification layer 2; tree-contract rco.check/1).
+
+Re-extracts at SHA and compares with a given map. Every finding has a
+path; findings are sorted, so output is byte-identical for the same input.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from collections import defaultdict
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Literal
+
+from rco import build, canon
+from rco.model import Kind, Map, Node, Tree, walk
+from rco.output import Exit
+
+SCHEMA_CHECK = "rco.check/1"
+SCHEMA_SELFTEST = "rco.selftest/2"
+
+Status = Literal["missing", "extra", "changed", "stale", "edge"]
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    status: Status
+    key: str
+    path: str
+    detail: str
+
+
+def _shapes(t: Tree) -> dict[str, list[tuple[str, tuple]]]:
+    out: dict[str, list[tuple[str, tuple]]] = defaultdict(list)
+    for key, n in walk(t):
+        out[key].append(n.shape())
+    return {k: sorted(v) for k, v in out.items()}
+
+
+def _path_of(key: str) -> str:
+    return key.split(":", 2)[1]
+
+
+def _fmt(shapes: list[tuple[str, tuple]]) -> str:
+    return "; ".join(f"sig={s!r}" + (f" attrs={dict(a)!r}" if a else "") for s, a in shapes)
+
+
+def compare(claimed: Map, actual: Map) -> tuple[Finding, ...]:
+    """Every mismatch between a claimed map and a fresh one."""
+    found: list[Finding] = []
+    if claimed.sha != actual.sha:
+        found.append(Finding("stale", "map:sha", "", f"map sha {claimed.sha} != {actual.sha}"))
+    cm = {t.module: t for t in claimed.trees}
+    am = {t.module: t for t in actual.trees}
+    for mod in sorted(set(cm) | set(am)):
+        c, a = cm.get(mod), am.get(mod)
+        mkey = f"module:{mod}"
+        if c is None:
+            found.append(Finding("missing", mkey, mod, "module not in map"))
+        elif a is None:
+            found.append(Finding("extra", mkey, mod, "module not in code"))
+        elif c.module_hash != a.module_hash:
+            found.append(Finding("stale", mkey, mod, "module_hash"))
+        cs = _shapes(c) if c else {}
+        as_ = _shapes(a) if a else {}
+        for key in sorted(set(cs) | set(as_)):
+            if key not in as_:
+                found.append(Finding("extra", key, _path_of(key), "claimed, not in code"))
+            elif key not in cs:
+                found.append(Finding("missing", key, _path_of(key), "in code, not in map"))
+            elif cs[key] != as_[key]:
+                found.append(Finding("changed", key, _path_of(key),
+                                     f"{_fmt(cs[key])} -> {_fmt(as_[key])}"))
+    return tuple(sorted(found, key=lambda f: (f.path, f.key, f.status)))
+
+
+@dataclass(frozen=True, slots=True)
+class CheckReport:
+    sha: str
+    map_sha: str
+    findings: tuple[Finding, ...]
+
+    def to_obj(self) -> dict:
+        counts = {s: 0 for s in ("changed", "extra", "missing", "stale", "edge")}
+        for f in self.findings:
+            counts[f.status] += 1
+        return {
+            "schema": SCHEMA_CHECK, "sha": self.sha, "map_sha": self.map_sha,
+            "counts": counts,
+            "findings": [{"status": f.status, "key": f.key, "path": f.path, "detail": f.detail}
+                         for f in self.findings],
+        }
+
+    def to_markdown(self) -> str:
+        lines = [f"# rco check  (SHA={self.sha[:12]}, map={self.map_sha[:12]})", ""]
+        if not self.findings:
+            lines.append("map matches the code: no findings")
+        for f in self.findings:
+            lines.append(f"- {f.status}: `{f.key}` {f.detail}")
+        return "\n".join(lines) + "\n"
+
+    def exit_code(self) -> Exit:
+        return Exit.FINDINGS if self.findings else Exit.OK
+
+
+def prose_name_findings(store, actual: Map) -> tuple[Finding, ...]:
+    """Names cited in stored prose that are not in the module's Tree."""
+    from rco.prose import flags as prose_flags
+    found: list[Finding] = []
+    for t in actual.trees:
+        for name in prose_flags(store.get_prose(t.module), t):
+            found.append(Finding("extra", f"prose:{t.module}:{name}", t.module,
+                                 "cited in prose, not in the Tree"))
+    return tuple(sorted(found, key=lambda f: (f.path, f.key, f.status)))
+
+
+def check(repo: Path, sha: str, claimed: Map | None = None, store=None,
+         claimed_forest=None) -> CheckReport:
+    t0 = time.perf_counter()
+    findings: tuple[Finding, ...] = ()
+    map_sha = ""
+    if claimed is not None:
+        actual = build.build_map(repo, sha)
+        findings = compare(claimed, actual)
+        map_sha = claimed.sha
+        if store is not None:
+            findings = findings + prose_name_findings(store, actual)
+    if claimed_forest is not None:
+        from rco.forest import build_forest, compare_edges
+        findings = findings + compare_edges(claimed_forest, build_forest(repo, sha))
+        findings = tuple(sorted(findings, key=lambda f: (f.path, f.key, f.status)))
+        if not map_sha:
+            map_sha = claimed_forest.sha
+    rep = CheckReport(sha=sha, map_sha=map_sha, findings=findings)
+    print(f"rco check: {len(rep.findings)} findings in {time.perf_counter() - t0:.3f}s",
+          file=sys.stderr)
+    return rep
+
+
+# ------------------------------------------------------------ planted drift
+
+def _edit_first(nodes: tuple[Node, ...], pred, fn) -> tuple[tuple[Node, ...], bool]:
+    """Apply fn to the first node (depth-first) matching pred; fn may return None to drop."""
+    out = []
+    done = False
+    for n in nodes:
+        if not done and pred(n):
+            r = fn(n)
+            done = True
+            if r is not None:
+                out.append(r)
+            continue
+        if not done and n.children:
+            kids, done = _edit_first(n.children, pred, fn)
+            n = replace(n, children=kids)
+        out.append(n)
+    return tuple(out), done
+
+
+def _edit_map(m: Map, pred, fn) -> Map:
+    trees = []
+    done = False
+    for t in m.trees:
+        if not done:
+            nodes, done = _edit_first(t.nodes, pred, fn)
+            t = replace(t, nodes=nodes)
+        trees.append(t)
+    if not done:
+        raise AssertionError("planted drift found no target")
+    return replace(m, trees=tuple(trees))
+
+
+def plants(m: Map) -> tuple[tuple[str, Status, Map], ...]:
+    """The six planted drifts: (name, status the checker must report, map)."""
+    k = lambda kind: (lambda n: n.kind is kind)  # noqa: E731
+    first_mod = m.trees[0]
+    added = Node(Kind.FUNCTION, "planted_extra", "", "() -> None")
+    return (
+        ("remove a flag", "missing", _edit_map(m, k(Kind.FLAG), lambda n: None)),
+        ("rename a column", "extra",
+         _edit_map(m, k(Kind.COLUMN), lambda n: replace(n, name=n.name + "_renamed"))),
+        ("change a sig", "changed",
+         _edit_map(m, k(Kind.FUNCTION), lambda n: replace(n, sig=n.sig + " # planted"))),
+        ("add a function", "extra",
+         _edit_map(m, k(Kind.PYMODULE),
+                   lambda n: replace(n, children=n.children + (added,)))),
+        ("drop a module", "missing", replace(m, trees=m.trees[1:])),
+        ("alter a module_hash", "stale",
+         replace(m, trees=(replace(first_mod, module_hash="sha256:" + "0" * 64),) + m.trees[1:])),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class SelftestReport:
+    rows: tuple[tuple[str, str, int, bool], ...]  # name, expected status, findings, caught
+
+    def to_obj(self) -> dict:
+        return {"schema": SCHEMA_SELFTEST,
+                "plants": [{"name": n, "expect": s, "findings": c, "caught": ok}
+                           for n, s, c, ok in self.rows]}
+
+    def to_markdown(self) -> str:
+        lines = ["# rco check --selftest", ""]
+        for n, s, c, ok in self.rows:
+            lines.append(f"- {'caught' if ok else 'MISSED'}: {n} (expect {s}, {c} findings)")
+        return "\n".join(lines) + "\n"
+
+    def exit_code(self) -> Exit:
+        return Exit.OK if self.rows and all(r[3] for r in self.rows) else Exit.FINDINGS
+
+
+def selftest_on(m: Map) -> SelftestReport:
+    if compare(m, m):
+        raise AssertionError("an unchanged map must have no findings")
+    rows = []
+    for name, status, planted in plants(m):
+        found = compare(planted, m)
+        rows.append((name, status, len(found), any(f.status == status for f in found)))
+    return SelftestReport(tuple(rows))
+
+
+def selftest() -> SelftestReport:
+    """Build the drift fixture's map in a scratch repo and plant six errors."""
+    from rco import fixture
+    t0 = time.perf_counter()
+    with fixture.drift_repo() as (repo, sha):
+        rep = selftest_on(build.build_map(repo, sha))
+    print(f"rco check --selftest: {time.perf_counter() - t0:.3f}s", file=sys.stderr)
+    return rep

rco/cli.py

@@ -0,0 +1,202 @@
+"""rco command line (tree-contract section 8)."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from rco import __version__, build, canon, check, diff, gitread
+from rco.forest_model import Forest
+from rco.model import Map
+from rco.output import Exit, UsageError, emit
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str):  # argparse would exit 2 itself; keep it one path
+        raise UsageError(message)
+
+
+def _common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--repo", default=".", help="git repository (default: .)")
+    p.add_argument("--format", choices=("markdown", "json"), default="markdown",
+                   help="output format (default: markdown)")
+    p.add_argument("--out", type=Path, default=None, help="write the report to FILE")
+
+
+def make_parser() -> argparse.ArgumentParser:
+    p = _Parser(prog="rco", description="Deterministic repo context for coding agents.")
+    p.add_argument("--version", action="version", version=f"rco {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True, parser_class=_Parser)
+
+    t = sub.add_parser("tree", help="print the Map (Trees) of a commit")
+    t.add_argument("sha", nargs="?", default="HEAD")
+    t.add_argument("--for", dest="for_paths", nargs="+", default=None, metavar="PATH",
+                   help="only the modules that own these paths")
+    _common(t)
+
+    c = sub.add_parser("check", help="check a map or forest against the code at a commit")
+    c.add_argument("map", nargs="?", default=None,
+                   help="map JSON (rco tree --format json) or forest JSON (rco forest --format json)")
+    c.add_argument("sha", nargs="?", default=None, help="commit (default: the map's sha)")
+    c.add_argument("--selftest", action="store_true", help="run the planted-drift self-test")
+    _common(c)
+
+    d = sub.add_parser("diff", help="contract changes between two commits")
+    d.add_argument("base", nargs="?", default=None)
+    d.add_argument("head", nargs="?", default=None)
+    _common(d)
+
+    u = sub.add_parser("update", help="publish a commit to the store (.rco/rco.db)")
+    u.add_argument("new", nargs="?", default="HEAD")
+    u.add_argument("--name", default="main", help="pointer name (default: main)")
+    _common(u)
+
+    k = sub.add_parser("pack", help="Forest plus Trees for an agent, within a token budget")
+    k.add_argument("sha", nargs="?", default="HEAD")
+    k.add_argument("--for", dest="for_paths", nargs="+", default=None, metavar="FILE")
+    k.add_argument("--budget", type=int, default=8000, help="estimated tokens (default: 8000)")
+    _common(k)
+
+    r = sub.add_parser("triage", help="hint per branch: clean or a structural brief (never rebases)")
+    r.add_argument("branches", nargs="*", metavar="BRANCH")
+    r.add_argument("--onto", default=None, help="target ref (default: the default branch)")
+    _common(r)
+
+    n = sub.add_parser("notice", help="cross-PR contract notice: other branches using this PR's changes")
+    n.add_argument("others", nargs="*", metavar="BRANCH")
+    n.add_argument("--base", default=None, help="this PR's base (default: merge-base)")
+    n.add_argument("--head", default=None, help="this PR's head (default: HEAD)")
+    _common(n)
+
+    f = sub.add_parser("forest", help="print the computed Forest of a commit")
+    f.add_argument("sha", nargs="?", default="HEAD")
+    _common(f)
+
+    pn = sub.add_parser("pin", help="pin the contract of files (commit it as the intended contract)")
+    pn.add_argument("sha", nargs="?", default="HEAD")
+    pn.add_argument("--for", dest="for_paths", nargs="+", required=True, metavar="FILE")
+    _common(pn)
+
+    dr = sub.add_parser("drift", help="contract drift from committed pins (a report, not a block)")
+    dr.add_argument("pins", nargs="+", type=Path, metavar="PIN", help="pin file or directory of *.json pins")
+    dr.add_argument("--at", default="HEAD", help="commit to check (default: HEAD)")
+    _common(dr)
+    return p
+
+
+@dataclass(frozen=True)
+class MapReport:
+    map: Map
+
+    def to_obj(self) -> dict:
+        return canon.map_to_obj(self.map)
+
+    def to_markdown(self) -> str:
+        from rco.render import map_markdown
+        return map_markdown(self.map)
+
+    def exit_code(self) -> Exit:
+        return Exit.OK
+
+
+def _read_claim(path: str) -> Map | Forest:
+    """A claimed rco.map/1 or rco.forest/1 file."""
+    try:
+        obj = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, ValueError) as e:
+        raise UsageError(f"unreadable map {path}: {e}") from None
+    schema = obj.get("schema") if isinstance(obj, dict) else None
+    try:
+        if schema == "rco.map/1":
+            return canon.map_from_obj(obj)
+        if schema == "rco.forest/1":
+            from rco.forest_model import forest_from_obj
+            return forest_from_obj(obj)
+    except (ValueError, KeyError, TypeError) as e:
+        kind = "map" if schema == "rco.map/1" else "forest"
+        raise UsageError(f"unreadable {kind} {path}: {e}") from None
+    raise UsageError(f"unreadable map {path}: schema must be rco.map/1 or rco.forest/1")
+
+
+def run(args: argparse.Namespace) -> Exit:
+    repo = Path(args.repo)
+    if args.cmd == "tree":
+        sha = gitread.resolve(repo, args.sha)
+        return emit(MapReport(build.build_map(repo, sha, args.for_paths)), args.format, args.out)
+    if args.cmd == "check":
+        if args.selftest:
+            return emit(check.selftest(), args.format, args.out)
+        if args.map is None:
+            raise UsageError("check needs MAP or FOREST or --selftest")
+        claim = _read_claim(args.map)
+        if isinstance(claim, Forest):
+            sha = gitread.resolve(repo, args.sha or claim.sha)
+            return emit(check.check(repo, sha, claimed_forest=claim), args.format, args.out)
+        m = claim
+        sha = gitread.resolve(repo, args.sha or m.sha)
+        store = None
+        db = repo / ".rco" / "rco.db"
+        if db.exists():  # read only: check never creates a store
+            from rco.store.sqlite import SqliteStore
+            store = SqliteStore(db)
+        return emit(check.check(repo, sha, m, store), args.format, args.out)
+    if args.cmd == "diff":
+        return emit(diff.diff(repo, args.base, args.head), args.format, args.out)
+    if args.cmd == "update":
+        from rco import update
+        from rco.prose import drain_queue
+        from rco.store.sqlite import open_repo_store
+        store = open_repo_store(repo)
+        res = update.update(repo, store, args.new, args.name)
+        drain_queue(repo, store, args.name)  # mined prose: queue is not a separate CLI step
+        return emit(update.UpdateReport(res), args.format, args.out)
+    if args.cmd == "triage":
+        from rco import triage
+        return emit(triage.triage(repo, args.branches, args.onto), args.format, args.out)
+    if args.cmd == "notice":
+        from rco import triage
+        return emit(triage.notice(repo, args.base, args.head, args.others), args.format, args.out)
+    if args.cmd == "forest":
+        from rco import forest
+        sha = gitread.resolve(repo, args.sha)
+        return emit(forest.ForestReport(forest.build_forest(repo, sha)), args.format, args.out)
+    if args.cmd == "pack":
+        from rco import pack
+        sha = gitread.resolve(repo, args.sha)
+        store = None
+        db = repo / ".rco" / "rco.db"
+        if db.exists():  # read only: pack never creates a store
+            from rco.store.sqlite import SqliteStore
+            store = SqliteStore(db)
+        p = pack.pack(repo, sha, args.for_paths, args.budget, store)
+        return emit(pack.PackReport(p, " ".join(args.for_paths or ())), args.format, args.out)
+    if args.cmd == "pin":
+        from rco import pin
+        sha = gitread.resolve(repo, args.sha)
+        return emit(pin.make_pin(repo, sha, args.for_paths), args.format, args.out)
+    if args.cmd == "drift":
+        from rco import pin
+        files = pin.pin_files(args.pins)
+        sha = gitread.resolve(repo, args.at)
+        return emit(pin.drift(repo, files, sha), args.format, args.out)
+    raise UsageError(f"unknown command {args.cmd}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    try:
+        args = make_parser().parse_args(argv)
+        return int(run(args))
+    except UsageError as e:
+        print(f"rco: {e}", file=sys.stderr)
+        return int(Exit.USAGE)
+    except SystemExit as e:  # --help / --version
+        return int(e.code or 0)
+    except Exception as e:  # noqa: BLE001 - the exit-3 contract
+        if os.environ.get("RCO_DEBUG") == "1":
+            raise
+        print(f"rco: internal error: {type(e).__name__}: {e}", file=sys.stderr)
+        return int(Exit.INTERNAL)