awgit 0.2.0__tar.gz → 0.3.1__tar.gz

{awgit-0.2.0 → awgit-0.3.1}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: awgit
-Version: 0.2.0
+Version: 0.3.1
 Summary: Aither World-Graph git — semantic version control on top of git: edit-ops keyed on stable node ids, content-addressed bodies, differential sync.
 License: Apache-2.0
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.25.0
+Provides-Extra: multilang
+Requires-Dist: repowise>=0.31.0; extra == "multilang"
 Dynamic: license-file
 
 # awgit — Aither World-Graph git

{awgit-0.2.0 → awgit-0.3.1}/awgit/capture.py

@@ -128,10 +128,23 @@ def resolve_actor(
     """
     github = _github_identity(data_root)
     env_actor = os.environ.get("AITHER_ACTOR")
+    # The SESSION, before the GitHub login. Every agent on this box shares one
+    # GitHub identity, so resolving to `github` collapsed every session into one
+    # actor: measured 2026-08-09, an op-log of 188 ops across 189 files had
+    # exactly ONE actor, which makes "two actors touched this node" impossible to
+    # express and the collision view structurally blind. The schema already
+    # separates CLAIMED from VERIFIED — `verified_actor` still records the
+    # GitHub identity below — so the claimed actor is free to be the session
+    # that actually made the edit, which is what attribution is for. Matches
+    # the lease gate's `_actor()`, and the two disagreeing is what made leases
+    # discriminate per session while captures did not.
+    session = os.environ.get("CLAUDE_CODE_SESSION_ID")
     if actor_arg:
         actor, source = actor_arg, "arg"
     elif env_actor:
         actor, source = env_actor, "env"
+    elif session:
+        actor, source = f"claude:{session}", "session"
     elif github:
         actor, source = github, "github"
     else:
@@ -151,9 +164,57 @@ def _ancestor_shas(repo: Path, sha: str) -> List[str]:
     return out[1:]  # first entry is sha itself
 
 
+def _was_leased(actor: str, files: List[str]) -> bool:
+    """Did `actor` hold leases covering every guarded file in this commit?
+
+    This was HARDCODED False, so the op-log's record of whether work was leased
+    was a constant — measured 2026-08-09, 40 consecutive ops said `leased=false`
+    including commits made while the author demonstrably held leases. That makes
+    lease ADOPTION unmeasurable: the one field that could answer "are agents
+    actually using this?" always answered no. Same silent-no-op class as a
+    checker that cannot fail.
+
+    Evaluated at capture time, i.e. just after the commit, while the lease is
+    typically still live. A lease that expired between commit and capture reads
+    as unleased — deliberately conservative: this records evidence, and absent
+    evidence must not read as proof.
+    """
+    try:
+        from awgit.leases import coverage_gap  # noqa: PLC0415
+
+        guarded_missing = coverage_gap(list(files or []), actor)
+        return not guarded_missing
+    except Exception:
+        # Never let attribution bookkeeping break a capture.
+        return False
+
+
 def _node_records(src: Optional[bytes], rel_path: str) -> List[Dict[str, Any]]:
     if src is None:
         return []
+    if not rel_path.endswith(".py"):
+        # NON-PYTHON: identity comes from repowise, which parses 75 extensions
+        # across 20+ languages and emits ids of the form `path::qualified_name`
+        # — verified stable across a symbol MOVING and its body changing, which
+        # is the property node-level merge rests on. Without this every
+        # .ts/.tsx/.go/.cs file was invisible to awgit: of the 20,451 files
+        # repowise has indexed in this repo, 12,600+ are not Python.
+        from awgit.repowise_parser import parse_symbols
+
+        text = src.decode("utf-8", errors="ignore").split("\n")
+        out: List[Dict[str, Any]] = []
+        for sym in parse_symbols(src, rel_path):
+            start, end = sym.get("start_line") or 0, sym.get("end_line") or 0
+            body = "\n".join(text[start - 1:end]) if start and end else ""
+            out.append({
+                "name": sym["symbol"] or sym["node_id"],
+                "path": rel_path,
+                "type": sym.get("kind") or "symbol",
+                "signature": "",
+                "body": body,
+            })
+        return out
+
     # lazy: CodeGraph's import chain is ~15s (AitherConfig auto-tune etc.); only
     # pay it when actually parsing (capture/diff/merge runtime), never for
     # `vcs lease`/`status` which import this module but never parse.
@@ -401,8 +462,13 @@ def capture_ops(
         manager = StableNodeIDManager(path=data / "nodes.json", persist=True)
         store = BodyStore(data_root=data)
         node_changes: List[NodeChange] = []
+        from awgit.repowise_parser import language_for
+
         for rel in files:
-            if not rel.endswith(".py"):
+            # Python natively; anything else only when repowise can parse it,
+            # so a file type nobody can give node identity to is skipped rather
+            # than recorded as an empty change.
+            if not rel.endswith(".py") and not language_for(rel):
                 continue
             old_src = git_blob(repo, parent, rel)
             new_src = git_blob(repo, git_sha, rel)
@@ -426,7 +492,7 @@ def capture_ops(
             file_paths=files,
             node_changes=node_changes,
             summary=_make_summary(actor_name, node_changes),
-            leased=False,
+            leased=_was_leased(actor_name, files),
             actor_verified=bool(prov["actor_verified"]),
             actor_source=str(prov["actor_source"]),
             verified_actor=str(prov["verified_actor"]),

{awgit-0.2.0 → awgit-0.3.1}/awgit/cli.py

@@ -156,8 +156,39 @@ def _cmd_lease(args: argparse.Namespace) -> int:
             from awgit.leases import is_guarded
 
             repo = Path(os.environ.get("VCS_REPO_ROOT", os.getcwd()))
-            targets += [f for f in _staged_files(repo) if is_guarded(f)]
-            targets = sorted(set(targets))
+            named = set(targets)
+            staged = [f for f in _staged_files(repo) if is_guarded(f)]
+            # ADOPTION: files that are staged but that this caller never named.
+            # In a shared worktree they are routinely somebody else's — a peer
+            # stages while you are mid-command — and leasing them is what makes
+            # the pre-commit gate print OK on a sweep, because you then genuinely
+            # hold a lease on their work. Measured 2026-08-10 (D-1887): three
+            # portal-kit files a peer had staged seconds earlier were adopted in
+            # silence, and 9 of their files landed in someone else's commit. The
+            # gate CANNOT catch this at commit time — the committer's leases are
+            # all valid — so it is caught here, at the moment of adoption.
+            adopted = sorted(f for f in staged if f not in named)
+            if adopted and not getattr(args, "adopt", False):
+                print("vcs: REFUSED — these files are staged but you did not name "
+                      "them:", file=sys.stderr)
+                for adopted_path in adopted:
+                    print("vcs:   " + adopted_path, file=sys.stderr)
+                print("vcs: in a shared worktree these are routinely a PEER's "
+                      "in-flight work, and leasing them makes the pre-commit gate "
+                      "pass on a commit that sweeps it (D-1887).", file=sys.stderr)
+                print("vcs: name your own paths instead, or re-run with --adopt if "
+                      "you have read that list and every file is yours.",
+                      file=sys.stderr)
+                return 1
+            if adopted:
+                # Proceeding deliberately still gets its own block: the failure
+                # mode was these paths being indistinguishable from the ones the
+                # caller actually asked for.
+                print("vcs: ADOPTING " + str(len(adopted))
+                      + " staged file(s) you did not name:")
+                for adopted_path in adopted:
+                    print("vcs:   + " + adopted_path)
+            targets = sorted(named | set(staged))
             if not targets:
                 print("vcs: nothing staged that the gate guards — no leases needed")
                 return 0
@@ -171,8 +202,29 @@ def _cmd_lease(args: argparse.Namespace) -> int:
         except LeaseConflictError as exc:
             print(f"vcs: {exc}", file=sys.stderr)
             return 1
+        # A lease over an ALREADY-DIRTY file captures a baseline that contains work
+        # which is not yours, and `stage-mine` computes (baseline -> worktree), so it
+        # cannot separate what it never saw as separate. Leasing after a peer has
+        # started editing therefore looks exactly like leasing a clean file, and the
+        # commit sweeps them — measured 2026-08-10, ~29 lines of a peer's in-flight
+        # HYG004 work landed in someone else's commit that way.
+        #
+        # This cannot REFUSE: the dirt is often your own (edit, then remember to
+        # lease), and refusing would break the common case. So it says so, loudly,
+        # once per dirty target, and names the fix.
+        dirty = _dirty_targets([lz.target for lz in leases])
         for lz in leases:
             print(f"vcs: lease {lz.lease_id} {lz.target} until {lz.expires_ts}")
+        if dirty:
+            print("vcs: WARNING — leased with UNCOMMITTED changes already present:",
+                  file=sys.stderr)
+            for rel in dirty:
+                print(f"vcs:   ! {rel}", file=sys.stderr)
+            print("vcs: the baseline just snapshotted INCLUDES those changes, so "
+                  "`awgit stage-mine` cannot tell them from yours.", file=sys.stderr)
+            print("vcs: if any of it is a peer's, verify before committing: "
+                  "`git diff --stat -- <path>` must match the size of YOUR edit.",
+                  file=sys.stderr)
         return 0
     if cmd == "heartbeat":
         print(f"vcs: heartbeat refreshed {registry.heartbeat(who, args.ids)} leases")
@@ -203,6 +255,66 @@ def _staged_files(repo: Path) -> List[str]:
     return [ln for ln in out.splitlines() if ln.strip()]
 
 
+def _cmd_stage_mine(args: argparse.Namespace) -> int:
+    """Stage only this actor's edits, and refuse if any of them would be lost."""
+    from awgit.staging import StagingError, stage_mine, verify_staged
+
+    if getattr(args, "self_test", False):
+        from awgit.staging_selftest import run_self_test
+        return run_self_test()
+
+    repo = Path(os.environ.get("VCS_REPO_ROOT", os.getcwd()))
+    who = _actor(args)
+    registry = LeaseRegistry()
+    held = {lz.target: lz for lz in registry.leases_by_actor(who) if lz.status == "active"}
+
+    failed = False
+    for rel in args.paths:
+        rel = rel.replace("\\", "/")
+        lease = held.get(rel)
+        if lease is None:
+            # Without a lease there is no baseline, and without a baseline "your
+            # edits" is a guess. Refusing is the whole point of the command.
+            print(
+                f"vcs: {rel}: no active lease for {who!r} — take it BEFORE editing "
+                f"(awgit lease acquire {rel})",
+                file=sys.stderr,
+            )
+            failed = True
+            continue
+        try:
+            result = stage_mine(rel, lease.baseline_blob, repo, dry_run=args.dry_run)
+        except StagingError as exc:
+            print(f"vcs: {exc}", file=sys.stderr)
+            failed = True
+            continue
+
+        if result.missing:
+            print(f"vcs: {rel}: {result.note}", file=sys.stderr)
+            for line in result.missing[:8]:
+                print(f"       lost: {line[:100]}", file=sys.stderr)
+            failed = True
+            continue
+
+        print(f"vcs: {rel}: {result.note}")
+
+        if result.staged and args.require:
+            absent = verify_staged(rel, args.require, repo)
+            if absent:
+                # This is the assertion that would have caught the 2026-08-10
+                # dropped-registration bug: the function was staged, the line
+                # wiring it was not, and everything else looked correct.
+                print(
+                    f"vcs: {rel}: REQUIRED text missing from the STAGED copy — "
+                    f"your change is staged incomplete:",
+                    file=sys.stderr,
+                )
+                for needle in absent:
+                    print(f"       missing: {needle[:100]}", file=sys.stderr)
+                failed = True
+    return 1 if failed else 0
+
+
 def _cmd_lease_check(args: argparse.Namespace) -> int:
     if os.environ.get("VCS_LEASES_ENFORCE", "0") != "1":
         print("vcs: lease-check not enforced (VCS_LEASES_ENFORCE=0)")
@@ -223,6 +335,34 @@ def _cmd_lease_check(args: argparse.Namespace) -> int:
     return 0
 
 
+
+def _cmd_graph(args: argparse.Namespace) -> int:
+    from awgit.graph import build, to_json, to_mermaid
+
+    g = build(since=args.since, actor=args.actor)
+    text = to_json(g) if args.format == "json" else to_mermaid(g)
+    if args.out:
+        try:
+            Path(args.out).write_text(text, encoding="utf-8")
+        except OSError as exc:
+            print(f"vcs: cannot write {args.out}: {exc}", file=sys.stderr)
+            return 2
+        print(f"vcs: wrote {args.format} graph to {args.out} "
+              f"({g['ops']} ops, {len(g['collisions'])} collision(s))")
+    else:
+        print(text)
+    return 0
+
+
+
+def _cmd_evidence(args: argparse.Namespace) -> int:
+    from awgit.evidence import gather, render, to_json
+
+    ev = gather(since=args.since)
+    print(to_json(ev) if args.json else render(ev))
+    return 0
+
+
 def _cmd_bodies(args: argparse.Namespace) -> int:
     from awgit.bodies import BodyStore
 
@@ -300,24 +440,72 @@ def _cmd_dedupe(args: argparse.Namespace) -> int:
 
 def _cmd_ledger(args: argparse.Namespace) -> int:
     """Attribution view — who changed what, under a verified GitHub identity."""
+    import json as _json
+
     from awgit.ledger import op_to_ledger_entry
     from awgit.oplog import OpLog
 
     ops = OpLog().all_ops()
     if args.op:
-        ops = [o for o in ops if o.op_id == args.op]
+        # 🪤 `--op` used to match ONLY `op_id`, while the listing below prints
+        # `ledger_ref` as its first column and the op_id NOWHERE. So the one
+        # identifier the command hands you was the one identifier it refused,
+        # and `awgit ledger --op <id-copied-from-awgit-ledger>` answered
+        # "no ops match" — which reads as "that op does not exist" rather than
+        # "you passed the wrong one of two ids you were never shown". Accept
+        # either; they are both stable handles for the same op.
+        # 🪤 PREFIX match, not equality. The listing abbreviates op_id to 16
+        # chars, so an exact-match lookup rejects the very string it printed —
+        # the identical defect one layer down, and it was reintroduced while
+        # fixing the first one. Git accepts short shas for exactly this reason.
+        wanted = args.op
+        matches = [
+            o for o in ops
+            if o.op_id.startswith(wanted)
+            or (op_to_ledger_entry(o).ledger_ref or "").startswith(wanted)
+        ]
+        if len(matches) > 1 and not any(
+            o.op_id == wanted or op_to_ledger_entry(o).ledger_ref == wanted
+            for o in matches
+        ):
+            # Ambiguity must be LOUD. Silently taking the first match is how a
+            # lookup starts answering about the wrong op.
+            print(
+                f"vcs: ledger: '{wanted}' is ambiguous ({len(matches)} ops match) "
+                "— use more characters",
+                file=sys.stderr,
+            )
+            return 1
+        ops = matches
     elif args.sha:
         ops = [o for o in ops if o.git_sha == args.sha]
     if not ops:
         print("vcs: ledger: no ops match", file=sys.stderr)
         return 1
+
+    if getattr(args, "json", False):
+        # Machine surface. The text form is lossy on purpose (it is a human
+        # attribution view), so anything programmatic — a world-model seeder, a
+        # reward program, an export — needs the full op rather than a re-parse
+        # of a display string that was never a contract.
+        entries = []
+        for op in ops:
+            entry = op_to_ledger_entry(op)
+            d = op.to_dict()
+            d["ledger_ref"] = entry.ledger_ref
+            entries.append(d)
+        print(_json.dumps(entries, indent=2, sort_keys=True))
+        return 0
+
     for op in ops:
         entry = op_to_ledger_entry(op)
         verified = (
             f" (verified {entry.verified_actor})" if entry.actor_verified else ""
         )
+        # op_id is printed too: it is half of what `--op` accepts, and omitting
+        # it is what made the lookup unusable from this command's own output.
         print(
-            f"{entry.ledger_ref} {entry.actor}{verified} "
+            f"{entry.ledger_ref} {op.op_id[:16]} {entry.actor}{verified} "
             f"{entry.git_sha[:10]} {entry.node_changes} node_changes {entry.ts}"
         )
     return 0
@@ -384,6 +572,39 @@ def _cmd_hooks(args: argparse.Namespace) -> int:
     return 2
 
 
+
+def _dirty_targets(targets):
+    """Which of these paths already carry uncommitted changes.
+
+    Best-effort and NEVER fatal: this runs on the happy path of `lease acquire`, and a
+    git hiccup must not stop someone taking a lease. Returning [] on failure is safe
+    because the warning is advisory — the lease itself is unaffected.
+    """
+    if not targets:
+        return []
+    try:
+        import subprocess
+
+        proc = subprocess.run(
+            ["git", "status", "--porcelain", "--", *targets],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=10,
+        )
+    except Exception:
+        return []
+    if proc.returncode != 0:
+        return []
+    out = []
+    for line in proc.stdout.splitlines():
+        rel = line[3:].strip().strip('"')
+        if rel:
+            out.append(rel)
+    return out
+
+
 def main(argv: Optional[List[str]] = None) -> int:
     parser = argparse.ArgumentParser(
         prog="awgit",
@@ -405,6 +626,19 @@ def main(argv: Optional[List[str]] = None) -> int:
     p_diff.add_argument("b", help="target sha")
 
     sub.add_parser("status", help="op-log status")
+    p_graph = sub.add_parser(
+        "graph", help="render the op-log as a graph (mermaid or json)")
+    p_ev = sub.add_parser(
+        "evidence", help="the measurable claim, computed from your own op-log")
+    p_ev.add_argument("--json", action="store_true")
+    p_ev.add_argument("--since", default=None, help="ISO timestamp")
+    p_graph.add_argument("--format", choices=("mermaid", "json"),
+                         default="mermaid")
+    p_graph.add_argument("--since", default=None,
+                         help="ISO timestamp — only ops at or after it")
+    p_graph.add_argument("--actor", default=None, help="restrict to one actor")
+    p_graph.add_argument("--out", default=None,
+                         help="write to a file instead of stdout")
 
     p_mp = sub.add_parser("merge-preview", help="node-level merge preview of two shas")
     p_mp.add_argument("a", help="base-side sha")
@@ -425,6 +659,10 @@ def main(argv: Optional[List[str]] = None) -> int:
     p_la.add_argument("--staged", action="store_true",
                       help="also lease every STAGED file the gate guards "
                            "(the one-command way to satisfy the pre-commit gate)")
+    p_la.add_argument("--adopt", action="store_true",
+                      help="with --staged: proceed even though some staged files "
+                           "were not named. READ THE LIST FIRST — in a shared "
+                           "worktree they are routinely a peer's work (D-1887)")
     p_la.add_argument("--ttl", type=int, default=300)
     p_la.add_argument("--reason", default="")
     p_la.add_argument("--actor", default=None)
@@ -440,6 +678,23 @@ def main(argv: Optional[List[str]] = None) -> int:
     p_lc = sub.add_parser("lease-check", help="pre-commit lease gate")
     p_lc.add_argument("--actor", default=None)
 
+    p_sm = sub.add_parser(
+        "stage-mine",
+        help="stage ONLY your edits to files other sessions are also editing",
+    )
+    # nargs="*" so `--self-test` needs no dummy path — a gate you cannot run
+    # without inventing an argument is a gate that does not get run.
+    p_sm.add_argument("paths", nargs="*", help="repo-relative paths you hold a lease on")
+    p_sm.add_argument("--actor", default=None)
+    p_sm.add_argument("--dry-run", action="store_true",
+                      help="report what would be staged without touching the index")
+    p_sm.add_argument("--require", action="append", default=[], metavar="TEXT",
+                      help="text that MUST appear in the staged copy; repeatable. "
+                           "Use it for the line that wires your change up — that is "
+                           "the one a heuristic drops.")
+    p_sm.add_argument("--self-test", action="store_true",
+                      help="prove the merge and the completeness assertion still work")
+
     p_bodies = sub.add_parser(
         "bodies", help="content-addressed body store (read a sha / stats)"
     )
@@ -468,8 +723,14 @@ def main(argv: Optional[List[str]] = None) -> int:
     p_ledger = sub.add_parser(
         "ledger", help="op-log as attribution records (who changed what)"
     )
-    p_ledger.add_argument("--op", default=None, help="op_id to show")
+    p_ledger.add_argument(
+        "--op", default=None, help="op_id OR ledger_ref to show (either is accepted)"
+    )
     p_ledger.add_argument("--sha", default=None, help="git sha to show")
+    p_ledger.add_argument(
+        "--json", action="store_true",
+        help="emit full ops as JSON (machine surface; the text form is lossy)",
+    )
 
     p_sync = sub.add_parser(
         "sync", help="differential sync over the mesh (ops + bodies)"
@@ -518,6 +779,12 @@ def main(argv: Optional[List[str]] = None) -> int:
         return _cmd_lease(args)
     if args.cmd == "lease-check":
         return _cmd_lease_check(args)
+    if args.cmd == "stage-mine":
+        return _cmd_stage_mine(args)
+    if args.cmd == "graph":
+        return _cmd_graph(args)
+    if args.cmd == "evidence":
+        return _cmd_evidence(args)
     if args.cmd == "bodies":
         return _cmd_bodies(args)
     if args.cmd == "dedupe":

awgit-0.3.1/awgit/evidence.py

@@ -0,0 +1,137 @@
+"""The evidence for awgit's own claim, computed from YOUR op-log.
+
+awgit asserts something measurable: that agents working in one repo collide on
+the same code, that git cannot see it, and that node identity plus leases can.
+For a long time that was an argument. This turns it into a number anyone can
+run against their own history:
+
+    awgit evidence            # human summary
+    awgit evidence --json     # machine-readable, for a dashboard or a badge
+
+What it reports, and why each one:
+
+  ops / actors        Is anything being captured, and by more than one identity?
+                      A single-actor op-log CANNOT express a collision, so this
+                      is the precondition for every other number being real.
+  lease adoption      What share of captured work was leased. This was
+                      unmeasurable until `leased` stopped being hardcoded.
+  collisions          Nodes two or more actors have touched — the thing git
+                      shows you nothing about.
+  languages           Node identity is only as broad as the parser; a Python-only
+                      install honestly reports Python-only coverage.
+
+LOCAL AND OFFLINE, ALWAYS. This reads the op-log on disk and talks to nothing.
+awgit is a version-control tool: it sees every line of proprietary code its user
+writes, and a tool in that position that phones home — even "anonymously" — has
+made a decision for its user that is not its to make. If aggregate sharing ever
+happens it must be an explicit, separate, opt-IN action with the payload visible
+first. `--json` exists so a user can look at exactly what they would share.
+"""
+from __future__ import annotations
+
+import json
+from collections import Counter, defaultdict
+from typing import Optional
+
+from awgit.oplog import OpLog
+
+
+def _language_of(path: str) -> str:
+    _, _, ext = (path or "").rpartition(".")
+    return ext.lower() if ext else "(none)"
+
+
+def gather(data_root=None, since: Optional[str] = None) -> dict:
+    """Compute the evidence. Pure read of the op-log; no network, no writes."""
+    log = OpLog(data_root=data_root)
+    ops = log.ops_since(since) if since else log.all_ops()
+
+    actors: Counter = Counter()
+    leased = 0
+    langs: Counter = Counter()
+    touched: dict = defaultdict(set)      # (path, node_id) -> {actor}
+    nodes = 0
+
+    for op in ops:
+        who = getattr(op, "actor", None) or "unknown"
+        actors[who] += 1
+        if getattr(op, "leased", False):
+            leased += 1
+        for ch in (getattr(op, "node_changes", None) or []):
+            nid = getattr(ch, "node_id", None)
+            if not nid:
+                continue
+            nodes += 1
+            path = getattr(ch, "path", None) or "?"
+            langs[_language_of(path)] += 1
+            touched[(path, nid)].add(who)
+
+    collisions = [
+        {"path": p, "node_id": n, "actors": sorted(a)}
+        for (p, n), a in touched.items() if len(a) > 1
+    ]
+    # Split the headline number, because the raw count OVER-STATES the claim.
+    # An op-log that spans an attribution change contains collisions where the
+    # same worker appears under an old label and a new one — real-looking, and
+    # not evidence of two agents at all. Measured 2026-08-09 on this repo: 27
+    # raw collisions, of which exactly ONE involved two distinct agent sessions.
+    # Reporting 27 would have been a lie of aggregation.
+    def _agent_sessions(actors: list) -> int:
+        return len([a for a in actors if str(a).startswith("claude:")])
+
+    confirmed = [c for c in collisions if _agent_sessions(c["actors"]) >= 2]
+    ambiguous = [c for c in collisions if _agent_sessions(c["actors"]) < 2]
+    total = len(ops)
+    multi_actor = len(actors) > 1
+    return {
+        "ops": total,
+        "node_changes": nodes,
+        "distinct_nodes": len(touched),
+        "actors": dict(actors),
+        "actor_count": len(actors),
+        "leased_ops": leased,
+        "lease_adoption_pct": round(leased * 100 / total, 1) if total else 0.0,
+        "languages": dict(langs.most_common(12)),
+        "collisions": confirmed or ambiguous,
+        "collision_count": len(collisions),
+        # The number that actually supports the claim: two DISTINCT agent
+        # sessions on one node. Everything else is a candidate, not evidence.
+        "confirmed_multi_agent_collisions": len(confirmed),
+        "ambiguous_collisions": len(ambiguous),
+        # The honesty flag. Every collision number below is meaningless without
+        # it, and a reader who does not know that will over-read a zero.
+        "can_detect_collisions": multi_actor,
+    }
+
+
+def render(ev: dict) -> str:
+    """Human summary. States what CANNOT be concluded as plainly as what can."""
+    out = [
+        "awgit evidence",
+        f"  ops captured        {ev['ops']}",
+        f"  node changes        {ev['node_changes']} across "
+        f"{ev['distinct_nodes']} distinct nodes",
+        f"  actors              {ev['actor_count']} "
+        f"({', '.join(list(ev['actors'])[:3]) or 'none'})",
+        f"  lease adoption      {ev['lease_adoption_pct']}% "
+        f"({ev['leased_ops']}/{ev['ops']} ops leased)",
+    ]
+    if ev["languages"]:
+        top = ", ".join(f".{k}:{v}" for k, v in list(ev["languages"].items())[:6])
+        out.append(f"  languages           {top}")
+    out.append(f"  node collisions     {ev['collision_count']} raw — "
+               f"{ev.get('confirmed_multi_agent_collisions', 0)} CONFIRMED "
+               f"(two distinct agent sessions), "
+               f"{ev.get('ambiguous_collisions', 0)} ambiguous")
+    if not ev["can_detect_collisions"]:
+        out.append("")
+        out.append("  NOTE: only ONE actor appears in this op-log, so a collision")
+        out.append("  is not merely absent — it is INEXPRESSIBLE. Read the count")
+        out.append("  as 'not measured', never as 'none happened'.")
+    for c in ev["collisions"][:5]:
+        out.append(f"    {c['path']}  {c['node_id'][:16]}  {', '.join(c['actors'])}")
+    return "\n".join(out)
+
+
+def to_json(ev: dict) -> str:
+    return json.dumps(ev, indent=2, sort_keys=True)