monogate-capcard-cli 1.0.0__py3-none-any.whl

capcard_cli/__init__.py

@@ -0,0 +1,55 @@
+"""CapCard CLI — persistent identity + verification for Monogate agents.
+
+Phase 1 (0.1.0): agent registry + ``register`` / ``status`` CLIs.
+Phase 2 (0.2.0): ``verify`` CLI — records evidence-backed outcomes,
+appends a JSONL log, bumps registry counters per the result-type
+contract.
+Phase 3 (0.3.0): ``playbook`` CLI — emits a session-end summary with
+lessons / tactics / open_questions and a trust delta vs. the prior
+playbook. Next agent inherits via ``capcard-playbook search``.
+Phase 4 (0.4.0): weighted trust score. ``trust = sum(w_i) / sum(|w_i|)``
+clamped to ``[0, 1]``; ``--evidence-type`` declares evidence
+strength (lean-proof = 1.0, self-report = 0.2, ci-broken = -0.3, …).
+Phase 6 (0.5.0): cross-agent attestation. ``capcard-verify
+--needs-attestation`` writes a pending record; another agent runs
+``capcard-attest --verification-id <id> --verifier-agent <vid>
+--pass | --reject | --dispute`` to confirm or reject. Both parties'
+trust update under the registry lock. Builder = verifier is rejected
+(no self-grading); trust is transitive via a verifier-trust
+modulator with a 0.5 floor for new verifiers.
+Phase 6.5 (0.6.0): dispute resolution + trust hygiene.
+``attestation_status_for`` collapses per-verifier votes so flip-flops
+count as one current stance, then quorum-resolves disputes when 2+
+distinct non-disputer verifiers agree. ``capcard-recompute-trust
+--all --use-current-verifier-trust`` walks the registry with a 2-pass
+converge so verifier-trust changes propagate back into builders they
+attested. Read-only views: ``capcard-attestations --pending | --by |
+--on``.
+Phase 5 (0.7.0): training-data extraction + agent lineage. The CLI
+doesn't train models — it turns the CapCard archive into trainable
+signal. ``AgentRecord`` gains ``generation: int`` and
+``parent_id: str | None``; ``capcard-register --generation N
+--parent ID`` and ``capcard list --by-lineage / --descendants-of``
+walk the chain. New module ``capcard_cli.training`` exposes
+``reward_for_playbook`` (shaped: trust_delta + 0.2 honest-negative
+bonus + -0.3 ci-broken extra; clamped [-1, 1]),
+``export_episodes``, ``rank_tactics`` (trust-weighted),
+``agent_stats``, and ``evidence_type_histogram``. New CLIs:
+``capcard-export``, ``capcard-tactics``, ``capcard-stats``.
+Phase 6.7 + 7 (1.0.0): closes the BACKLOG and ships the wire
+format. Time-decay opt-in clears stale dispute markers
+(``capcard-recompute-trust --dispute-decay-days 7``); iterative
+trust converge (``--iterative --epsilon 0.001``) handles
+verifier-cycle pathologies. New ``capcard_cli.bundle`` module +
+``capcard-bundle export/import`` ship a versioned, idempotent-
+merge JSON wire format ready for a Phase 7+ network gossip layer.
+``capcard-fingerprint --verification-id VID --rerun`` re-executes
+the original evidence command and compares the SHA-256 output
+digest. ``AgentRecord`` gains a forward-reserved ``pubkey: str |
+None`` field for cross-registry signature verification once a
+network protocol exists. Stdlib-only constraint preserved — actual
+ZK proofs and gossip are an out-of-CLI research project (see
+``docs/BACKLOG.md``).
+"""
+
+__version__ = "1.0.0"

capcard_cli/attest.py

@@ -0,0 +1,444 @@
+"""Cross-agent attestation — Phases 6, 6.5, 6.7.
+
+A verification can be self-attested (the default; Phase 4 behavior
+preserved) or cross-attested. Cross-attestation requires:
+
+  1. The builder records the verification with ``--needs-attestation``
+     so the row is written with ``needs_attestation=True`` and starts
+     in the ``pending`` state, contributing 0 to the trust score.
+
+  2. A separate agent (the verifier) calls ``capcard-attest`` with
+     the verification's id, their own agent id, and a ``--pass`` /
+     ``--reject`` / ``--dispute`` outcome. We refuse to record an
+     attestation where the verifier and the builder are the same
+     agent — the whole point is independent review.
+
+  3. The attestation lands in ``~/.capcard/attestations.jsonl``
+     (override via ``CAPCARD_ATTESTATION_LOG_PATH``). Both the
+     builder's and the verifier's trust scores are recomputed and
+     re-cached on the registry.
+
+State machine for one verification:
+
+::
+
+    self-attested ←  needs_attestation=False, immediate trust
+    pending       ←  needs_attestation=True, no attestation yet
+    confirmed     ←  needs_attestation=True, latest non-dispute is "pass"
+    rejected      ←  needs_attestation=True, latest non-dispute is "reject"
+    disputed      ←  any "dispute" outcome present (treated as 0
+                     until full Phase 6.5+ resolution flow ships)
+
+Attestation log is append-only JSONL — overturning a previous
+verdict means recording a new attestation, not editing the old row.
+"""
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+import datetime as _dt
+import errno
+import fcntl
+import json
+import os
+import uuid
+from pathlib import Path
+from typing import Any
+
+from capcard_cli.registry import (
+    AgentNotFound, AgentRecord, RegistryError, _atomic_write, _load_raw,
+    _locked, _utc_now_iso, registry_path,
+)
+from capcard_cli.verify import (
+    VerificationRecord, _utc_now_iso_us, find_verification_by_id,
+    read_verifications, weighted_trust_for_agent,
+)
+
+
+# ──────────────────────────── Outcomes ──────────────────────────
+
+
+KNOWN_ATTESTATION_OUTCOMES: tuple[str, ...] = ("pass", "reject", "dispute")
+
+
+# ──────────────────────────── Attestation record ────────────────
+
+
+@dataclasses.dataclass(frozen=True)
+class Attestation:
+    """One verifier signature on a verification record.
+
+    Attestations are append-only — overturning a previous verdict
+    means recording a *new* attestation, not editing the old row.
+    The ``attestation_status_for`` resolver reads "the latest non-
+    dispute outcome wins, plus any dispute marker raises the row
+    into the disputed state."
+    """
+
+    attestation_id: str             # uuid4 hex (12 chars)
+    verification_id: str            # foreign key into verifications.jsonl
+    verifier_agent_id: str
+    outcome: str                    # one of KNOWN_ATTESTATION_OUTCOMES
+    verifier_trust_at_time: float   # snapshot at the time of attestation
+    evidence: str | None            # what the verifier looked at
+    note: str | None
+    timestamp: str                  # microsecond ISO-8601 UTC
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)
+
+
+# ──────────────────────────── Path + IO ─────────────────────────
+
+
+def attestation_log_path() -> Path:
+    """Resolve the attestation log path.
+
+    Precedence: ``CAPCARD_ATTESTATION_LOG_PATH`` env var, else
+    ``~/.capcard/attestations.jsonl``.
+    """
+    override = os.environ.get("CAPCARD_ATTESTATION_LOG_PATH")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".capcard" / "attestations.jsonl"
+
+
+def _append_jsonl(path: Path, row: dict[str, Any]) -> None:
+    """Append one JSON object as a single line under a sidecar
+    flock so concurrent writers don't interleave bytes mid-line.
+    Mirrors the verification log's IO contract."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = path.with_name(path.name + ".lock")
+    fd_lock = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        try:
+            fcntl.flock(fd_lock, fcntl.LOCK_EX)
+        except OSError as e:
+            if e.errno in (errno.ENOSYS, errno.ENOTSUP):
+                raise RegistryError(
+                    f"flock unsupported on filesystem hosting {path}; "
+                    f"set CAPCARD_ATTESTATION_LOG_PATH to a local path."
+                ) from e
+            raise
+        with open(path, "ab") as f:
+            line = json.dumps(row, sort_keys=True).encode("utf-8") + b"\n"
+            f.write(line)
+            f.flush()
+            os.fsync(f.fileno())
+    finally:
+        with contextlib.suppress(OSError):
+            fcntl.flock(fd_lock, fcntl.LOCK_UN)
+        os.close(fd_lock)
+
+
+def _new_attestation_id() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+# ──────────────────────────── State resolver ────────────────────
+
+
+def _collapse_per_verifier(
+    relevant: list[Attestation],
+) -> list[Attestation]:
+    """Phase 6.5: keep only the latest attestation from each verifier.
+
+    A single verifier flipping their vote counts as one current vote
+    (their latest stance), not two cancelling votes. The append-only
+    log preserves the audit trail; this collapse is read-side only.
+    """
+    by_verifier: dict[str, Attestation] = {}
+    for a in relevant:
+        prev = by_verifier.get(a.verifier_agent_id)
+        if prev is None or a.timestamp > prev.timestamp:
+            by_verifier[a.verifier_agent_id] = a
+    return list(by_verifier.values())
+
+
+def _parse_iso8601(ts: str) -> _dt.datetime | None:
+    """Parse an ISO-8601 UTC timestamp (supports both second and
+    microsecond resolutions, with or without a trailing Z). Returns
+    None for unparseable strings — defensive against legacy log
+    rows from before microsecond timestamps."""
+    if not ts:
+        return None
+    s = ts.rstrip("Z")
+    for fmt in ("%Y-%m-%dT%H:%M:%S.%f", "%Y-%m-%dT%H:%M:%S"):
+        try:
+            return _dt.datetime.strptime(s, fmt).replace(tzinfo=_dt.timezone.utc)
+        except ValueError:
+            continue
+    return None
+
+
+def attestation_status_for(
+    rec: VerificationRecord,
+    attestations: list[Attestation],
+    *,
+    now: _dt.datetime | None = None,
+    dispute_decay_days: float | None = None,
+) -> tuple[str, Attestation | None]:
+    """Resolve the attestation state of one verification record.
+
+    Returns ``(status, latest_decision)`` where ``status`` is one of
+    ``self-attested`` / ``pending`` / ``confirmed`` / ``rejected`` /
+    ``disputed`` and ``latest_decision`` is the most recent ``pass``
+    / ``reject`` attestation that drove the status (or None for
+    ``self-attested`` / ``pending`` / ``disputed``-with-no-decision).
+
+    Phase 6.5 added two refinements:
+
+      * **Per-verifier collapse:** multiple attestations from the same
+        verifier on the same record collapse to their latest stance,
+        so a flip-flop counts as one current vote, not two.
+
+      * **Dispute quorum resolution:** a ``dispute`` marker can be
+        cleared when ≥2 *distinct* non-disputer verifiers' current
+        votes agree on the same verdict and that verdict has a strict
+        majority among non-disputer current votes. Otherwise the
+        record stays in the ``disputed`` state.
+
+    Phase 6.7 added time-decay (opt-in):
+
+      * **dispute_decay_days:** when set together with ``now``, a
+        dispute marker whose latest occurrence is older than the
+        threshold is ignored (treated as cleared). The underlying
+        decision (the latest pass/reject among current votes) drives
+        the status. This closes the "stuck disputed" edge from the
+        Phase 6.5 review without requiring an arbiter actor — it's
+        an explicit hygiene knob the caller turns on (default
+        behaviour preserves the Phase 6.5 strict-quorum semantics).
+    """
+    if not rec.needs_attestation:
+        return "self-attested", None
+
+    if not rec.verification_id:
+        # Old log row missing an id — can't be attested. Treat as
+        # self-attested even with needs_attestation flagged (defensive).
+        return "self-attested", None
+
+    relevant = [a for a in attestations if a.verification_id == rec.verification_id]
+    if not relevant:
+        return "pending", None
+
+    # Per-verifier collapse. A verifier's current stance is their
+    # latest attestation; earlier votes from the same verifier are
+    # superseded. Length of `current` ≤ number of distinct verifiers.
+    current = _collapse_per_verifier(relevant)
+
+    has_dispute = any(a.outcome == "dispute" for a in current)
+
+    # Phase 6.7 time-decay. If the caller supplied a decay threshold
+    # AND the most recent dispute among current votes is older than
+    # that threshold, treat the dispute as cleared. We only consider
+    # the *most recent* dispute timestamp because a fresh dispute
+    # from a new verifier should always reset the clock.
+    if has_dispute and dispute_decay_days is not None and now is not None:
+        latest_dispute_time: _dt.datetime | None = None
+        for a in current:
+            if a.outcome != "dispute":
+                continue
+            t = _parse_iso8601(a.timestamp)
+            if t is None:
+                continue
+            if latest_dispute_time is None or t > latest_dispute_time:
+                latest_dispute_time = t
+        if latest_dispute_time is not None:
+            age_seconds = (now - latest_dispute_time).total_seconds()
+            if age_seconds > dispute_decay_days * 86400:
+                has_dispute = False
+
+    decisions = [a for a in current if a.outcome in ("pass", "reject")]
+
+    if not decisions:
+        # Only disputes (current). No verdicts to resolve to.
+        if has_dispute:
+            return "disputed", None
+        return "pending", None  # defensive — shouldn't reach here
+
+    # Latest decision among current verdicts.
+    latest = max(decisions, key=lambda a: a.timestamp)
+
+    if has_dispute:
+        # Phase 6.5: quorum resolution. Count distinct non-disputer
+        # verdicts (each verifier's current vote). 2+ matching the
+        # majority → resolve.
+        passes = [a for a in decisions if a.outcome == "pass"]
+        rejects = [a for a in decisions if a.outcome == "reject"]
+        if len(passes) >= 2 and len(passes) > len(rejects):
+            return "confirmed", max(passes, key=lambda a: a.timestamp)
+        if len(rejects) >= 2 and len(rejects) > len(passes):
+            return "rejected", max(rejects, key=lambda a: a.timestamp)
+        # Tied / not enough non-disputer verdicts → stay disputed.
+        return "disputed", latest
+
+    if latest.outcome == "pass":
+        return "confirmed", latest
+    return "rejected", latest
+
+
+# ──────────────────────────── Read API ──────────────────────────
+
+
+def read_attestations(
+    *,
+    verification_id: str | None = None,
+    verifier_agent_id: str | None = None,
+    limit: int | None = None,
+) -> list[Attestation]:
+    """Read the attestation log, optionally filtered. Newest-first."""
+    path = attestation_log_path()
+    if not path.exists():
+        return []
+    out: list[Attestation] = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                d = json.loads(line)
+            except json.JSONDecodeError:
+                # Skip torn lines; same contract as the verification log.
+                continue
+            if verification_id is not None and d.get("verification_id") != verification_id:
+                continue
+            if verifier_agent_id is not None and d.get("verifier_agent_id") != verifier_agent_id:
+                continue
+            known = {f.name for f in dataclasses.fields(Attestation)}
+            out.append(Attestation(**{k: v for k, v in d.items() if k in known}))
+    out.reverse()
+    if limit is not None:
+        out = out[:limit]
+    return out
+
+
+# ──────────────────────────── Public write API ──────────────────
+
+
+def record_attestation(
+    *,
+    verification_id: str,
+    verifier_agent_id: str,
+    outcome: str,
+    evidence: str | None = None,
+    note: str | None = None,
+) -> tuple[Attestation, AgentRecord, AgentRecord]:
+    """Record a cross-agent attestation.
+
+    Looks up the target verification, validates the actors, appends
+    one row to ``attestations.jsonl``, and recomputes BOTH the
+    builder's and the verifier's trust scores under the registry
+    lock.
+
+    Returns ``(attestation, builder_record, verifier_record)``.
+
+    Raises:
+      * :class:`RegistryError` for unknown outcomes, empty fields,
+        attestations of self-attested rows, or builder = verifier
+        (the no-self-grading rule).
+      * :class:`AgentNotFound` if the verifier_agent_id has no
+        registry row OR the target verification doesn't exist.
+    """
+    if not verification_id.strip():
+        raise RegistryError("--verification-id must be non-empty")
+    if not verifier_agent_id.strip():
+        raise RegistryError("--verifier-agent must be non-empty")
+    if outcome not in KNOWN_ATTESTATION_OUTCOMES:
+        raise RegistryError(
+            f"unknown outcome {outcome!r}; "
+            f"valid: {', '.join(KNOWN_ATTESTATION_OUTCOMES)}"
+        )
+
+    # Look up the target verification. Linear scan but fine at scale.
+    target = find_verification_by_id(verification_id)
+    if target is None:
+        raise AgentNotFound(
+            f"no verification with id {verification_id!r} "
+            f"in {attestation_log_path().parent}/verifications.jsonl"
+        )
+    if not target.needs_attestation:
+        raise RegistryError(
+            f"verification {verification_id!r} is self-attested "
+            f"(needs_attestation=False); cross-attestation is only "
+            f"meaningful when the builder asked for it via "
+            f"--needs-attestation"
+        )
+    if target.agent_id == verifier_agent_id:
+        raise RegistryError(
+            f"refuse to attest: verifier {verifier_agent_id!r} is "
+            f"the same as the builder. Cross-attestation requires "
+            f"an independent agent."
+        )
+
+    # Verifier must be a registered agent so we can snapshot their
+    # trust at attestation time.
+    rpath = registry_path()
+    with _locked(rpath):
+        raw = _load_raw(rpath)
+        v_d = raw["agents"].get(verifier_agent_id)
+        if v_d is None:
+            raise AgentNotFound(
+                f"no agent with id {verifier_agent_id!r} (verifier "
+                f"must be registered via capcard-register)"
+            )
+        verifier_trust_snapshot = float(v_d.get("trust_score", 0.0))
+
+    # Build the attestation record.
+    a = Attestation(
+        attestation_id=_new_attestation_id(),
+        verification_id=verification_id,
+        verifier_agent_id=verifier_agent_id,
+        outcome=outcome,
+        verifier_trust_at_time=verifier_trust_snapshot,
+        evidence=evidence,
+        note=note,
+        timestamp=_utc_now_iso_us(),
+    )
+
+    # Append the log first so the recompute walk sees this attestation.
+    _append_jsonl(attestation_log_path(), a.to_dict())
+
+    # Recompute trust for BOTH parties in one registry lock so the
+    # two writes are seen atomically by readers.
+    with _locked(rpath):
+        raw = _load_raw(rpath)
+
+        history = read_verifications()
+        attns = read_attestations()
+
+        builder_d = raw["agents"].get(target.agent_id)
+        if builder_d is None:
+            # Builder was deleted between the verification write and
+            # this attestation. Surface it — the attestation lives on
+            # disk regardless.
+            raise AgentNotFound(
+                f"builder {target.agent_id!r} disappeared; "
+                f"attestation logged at {a.attestation_id} but trust "
+                f"could not be updated"
+            )
+        builder_d["trust_score"] = weighted_trust_for_agent(
+            target.agent_id, records=history, attestations=attns,
+        )
+        builder_d["last_active"] = _utc_now_iso()
+        raw["agents"][target.agent_id] = builder_d
+
+        v_d = raw["agents"].get(verifier_agent_id)
+        # We re-read the verifier row inside the lock to avoid
+        # clobbering any concurrent update from elsewhere.
+        if v_d is None:
+            raise AgentNotFound(
+                f"verifier {verifier_agent_id!r} disappeared mid-attest"
+            )
+        v_d["trust_score"] = weighted_trust_for_agent(
+            verifier_agent_id, records=history, attestations=attns,
+        )
+        v_d["last_active"] = _utc_now_iso()
+        raw["agents"][verifier_agent_id] = v_d
+
+        _atomic_write(rpath, raw)
+
+        builder_rec = AgentRecord.from_dict(builder_d)
+        verifier_rec = AgentRecord.from_dict(v_d)
+
+    return a, builder_rec, verifier_rec