strata-agent-memory 0.2.6__tar.gz → 0.2.8__tar.gz

{strata_agent_memory-0.2.6/strata_agent_memory.egg-info → strata_agent_memory-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strata-agent-memory
-Version: 0.2.6
+Version: 0.2.8
 Summary: Portable, auditable, cross-vendor memory for LLM agents: evidence-bound claims, trust tiers, and compiled context views.
 Author: Strata Intelligence
 License-Expression: Apache-2.0

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.8}/agent_memory/__init__.py

@@ -9,4 +9,4 @@ see, what did it claim, and can the proof be re-run.
 The core is dependency-free (Python 3.10+ standard library only).
 """
 
-__version__ = "0.2.6"
+__version__ = "0.2.8"

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.8}/agent_memory/cli.py

@@ -606,9 +606,10 @@ def _private_contract_refusal(args) -> Optional[int]:
 
 
 def _acceptance_checks(args) -> List[dict]:
-    """The acceptance checks a `contract create` asks for, in the order the flags read
-    them. The remote lane files the same contract as the local one, so both build the
-    list here: a check that got lost on the way is a contract nobody can prove."""
+    """The acceptance checks a `contract create` asks for, or a `contract update` amends the
+    list to (ctr_649e0b459a758929), in the order the flags read them. The remote lane files
+    the same record as the local one, so both build the list here: a check that got lost on
+    the way is a contract nobody can prove."""
     acceptance = [{"kind": "command", "cmd": c, "expect_exit": 0} for c in args.check or []]
     acceptance += [{"kind": "human", "statement": s} for s in args.human_check or []]
     acceptance += [{"kind": "file", "path": f} for f in args.file_check or []]
@@ -637,8 +638,13 @@ def cmd_contract(args) -> int:
         _print(out)
         return 0 if signed else 3
     if args.action == "update":
-        rec = contracts.update(ledger, author, scope, args.id, args.status, note=args.note, claims=args.claims or (),
-                               assigned_to=getattr(args, "assign", None))
+        try:
+            rec = contracts.update(ledger, author, scope, args.id, args.status, note=args.note, claims=args.claims or (),
+                                   assigned_to=getattr(args, "assign", None),
+                                   acceptance_checks=_acceptance_checks(args) or None)
+        except ValidationError as exc:
+            print(f"rejected: {exc}", file=sys.stderr)
+            return 3
         out = {"id": rec["id"], "status": args.status}
         signed = _sign_after(args, ledger, author, scope, rec, out)
         _print(out)
@@ -1479,7 +1485,10 @@ def _remote_recheck(args, client) -> int:
                                max=args.max, cwd=root, timeout=args.timeout, path_map=path_map,
                                dry_run=args.dry_run, min_age_days=args.min_age_days, force=args.force,
                                assessment=view.assessment, file=file,
-                               policy=_sandbox_policy(args, _local_sandbox(view.config, root)))
+                               policy=_sandbox_policy(args, _local_sandbox(view.config, root)),
+                               # a re-run away from the outcome's bound commit refutes nothing
+                               # (the lane's rule, ctr_207af145a59463ed)
+                               away_is_error=True)
     except ValueError as exc:
         print(f"recheck: {exc}", file=sys.stderr)
         return 2
@@ -1679,7 +1688,8 @@ def _remote_contract_update(args, client) -> int:
         return 2
     claims = list(args.claims or [])
     body = contracts.update_body(args.id, args.status, note=args.note, claims=claims,
-                                 assigned_to=getattr(args, "assign", None))
+                                 assigned_to=getattr(args, "assign", None),
+                                 acceptance_checks=_acceptance_checks(args) or None)
     payload = {"kind": "contract_update", "body": body, "derived_from": [args.id, *claims]}
     rec, _ = client.post_record(_scoped_payload(payload, _remote_scope(args, client)))
     out = {"id": rec["id"], "status": rec["body"]["status"]}
@@ -1704,9 +1714,16 @@ def _remote_contract_accept(args, client) -> int:
     if local is None:
         return 2
     served = _ServedLedger(client, local)
+    # read once, before anything runs: the checks the replica says the contract answers to
+    # now, an amendment's included (the served view holds no contract_updates to find one
+    # in, ctr_649e0b459a758929), and the status the run reports it started under, which
+    # ``contracts.run_acceptance`` reads before its checks run too (PROTOCOL 4.1)
+    started = client.contract_status(args.id)
+    checks = started.get("acceptance")
     results = contracts.run_acceptance(served, args.id, cwd=args.cwd or str(local.root),
                                        timeout=args.timeout, file=False,
-                                       policy=_sandbox_policy(args, served.config))
+                                       policy=_sandbox_policy(args, served.config),
+                                       checks=checks if isinstance(checks, list) else None)
     # asked once and used for the receipts and the run alike: a --scope this client typed
     # has to reach the server the way `claim` and `retract` send it, and a project scope
     # is still the server's own to stamp
@@ -1716,7 +1733,7 @@ def _remote_contract_accept(args, client) -> int:
         if body and body.get("kind") in ("command", "test"):
             rec, _ = client.post_record(_scoped_payload({"kind": "evidence", "body": body}, scope))
             r["receipt"] = rec["id"]
-    status = client.contract_status(args.id)["status"]  # an acceptance run reports, it does not promote
+    status = started["status"]  # an acceptance run reports, it does not promote
     client.post_record(_scoped_payload({"kind": "contract_update", "body": {
         "contract": args.id, "status": status,
         "acceptance": [{"check": r["check"], "outcome": r["outcome"], "detail": r["detail"],
@@ -2349,6 +2366,12 @@ def build_parser() -> argparse.ArgumentParser:
     c.add_argument("--note")
     c.add_argument("--claims", nargs="*")
     c.add_argument("--assign", help="hand the contract to this agent (the board follows the latest assignee)")
+    # an amendment of the acceptance checks: the whole list, as `contract create` takes it
+    # (ctr_649e0b459a758929); refused under the contract's assignee's own key
+    c.add_argument("--check", action="append", help="amend the acceptance: a command expecting exit 0 (repeatable)")
+    c.add_argument("--human-check", action="append", help="amend the acceptance: a human sign-off (repeatable)")
+    c.add_argument("--file-check", action="append", help="amend the acceptance: a file that must exist (repeatable)")
+    c.add_argument("--acceptance-json", help="amend the acceptance: a JSON list of checks, replacing the contract's")
     _add_identity(c)
     _add_signing(c)
     c = cs.add_parser("from-issue", help="create a contract from a GitHub issue (needs the gh CLI)")
@@ -2419,7 +2442,8 @@ def build_parser() -> argparse.ArgumentParser:
                                        "verifications under the running identity; with --remote, the "
                                        "replica's claims, re-run here under the replica's re-check policy")
     s.add_argument("--only", choices=list(recheck_mod.ONLY_CHOICES), default="unverified",
-                   help="unverified (tier evidenced, default), stale, or all (everything but refuted/tainted)")
+                   help="unverified (tier evidenced or self-verified, whatever inconclusives it carries; the "
+                        "default), stale, or all (everything but refuted/tainted)")
     s.add_argument("--type", action="append",
                    help="restrict to these claim types, comma-separated (e.g. outcome,fact)")
     s.add_argument("--max", type=int, help="stop after this many claims")

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.8}/agent_memory/compiler.py

@@ -14,6 +14,7 @@ Roles and modes follow the fork/isolate rule:
 from __future__ import annotations
 
 import re
+import sys
 from dataclasses import dataclass, field
 from datetime import timedelta
 from typing import Callable, Dict, Iterable, List, Optional, Tuple
@@ -142,6 +143,9 @@ class Compiled:
     pinned_cap: Optional[int] = None
     pinned_cut: Dict[str, int] = field(default_factory=dict)
     pinned_full: Dict[str, int] = field(default_factory=dict)
+    # the retrieval plugin that took part (ctr_9e166c2f291b829b): {plugin, share, ids}, and
+    # error when it could not run; None when config.retrieval names none
+    retrieval: Optional[Dict] = None
 
     def included_ids(self) -> List[str]:
         return [i.id for items in self.sections.values() for i in items]
@@ -590,6 +594,10 @@ def compile_context(
         else:
             out.sections["working"].append(item)
 
+    # the retrieval plugin (ctr_9e166c2f291b829b): the ids it finds for the task, of which
+    # the reader sees only what this compile's own policy filter let through (candidates)
+    retrieval_cfg, retrieved = _retrieval(ledger, task, {item.id: item for item, _ in candidates}, out, assessment)
+
     seen_dnr = set()
     for it in do_not_retry:
         key = (it.id, it.statement)
@@ -619,35 +627,72 @@ def compile_context(
     # costed provisionally here and the difference is charged once it is known
     provisional = _obligations(role, mode, round_no, bool(out.sections["cross_check"]), bool(contract_id), lens)
     overhead = overhead_tokens(out, provisional)
-    used = overhead
-    kept: Dict[str, List[Item]] = {name: [] for name in SECTION_ORDER}
-    remaining_by_section = {name: [] for name in SECTION_ORDER}
-    # pass 1: each section up to its share; pass 2: fill leftovers in priority order
-    for name in SECTION_ORDER:
-        cap = int(budget * SECTION_SHARE[name])
-        # half of the constraints section is kept for its human-filed items, which arrive
-        # in standing order, so the freshly filed ones compete for the other half only
-        reserved = int(cap * CONSTRAINT_HUMAN_RESERVE) if name == "constraints" else 0
-        section_used = unreserved_used = 0
-        for item in out.sections[name]:
-            cost = cost_of(item)
-            reserve_eligible = bool(reserved) and item.is_human
-            fits_share = reserve_eligible or unreserved_used + cost <= cap - reserved
-            if section_used + cost <= cap and fits_share and used + cost <= budget:
-                kept[name].append(item)
-                section_used += cost
-                unreserved_used += 0 if reserve_eligible else cost
-                used += cost
-            else:
-                remaining_by_section[name].append(item)
-    for name in SECTION_ORDER:
-        for item in remaining_by_section[name]:
-            cost = cost_of(item)
-            if used + cost <= budget:
-                kept[name].append(item)
-                used += cost
-            else:
-                out.excluded.append((item.id, "budget"))
+    def allocate(reserve: int, found: List[Item], fixed: Optional[List[Item]] = None):
+        """(kept, used, left out for the budget): pass one fills each section up to its
+        share, the retrieval plugin's ``found`` fill its section up to ``reserve``, and pass
+        two fills leftovers in priority order. ``fixed`` is the constraints section as
+        compile alone keeps it: the plugin's share is never taken from what always applies
+        (the review of ctr_9e166c2f291b829b)."""
+        used = overhead
+        kept: Dict[str, List[Item]] = {name: [] for name in SECTION_ORDER}
+        remaining_by_section: Dict[str, List[Item]] = {name: [] for name in SECTION_ORDER}
+        # pass 1: each section up to its share; pass 2: fill leftovers in priority order
+        for name in SECTION_ORDER:
+            if name == "constraints" and fixed is not None:
+                kept[name] = list(fixed)
+                used += sum(cost_of(item) for item in fixed)
+                held = {id(item) for item in fixed}
+                remaining_by_section[name] = [item for item in out.sections[name] if id(item) not in held]
+                continue
+            cap = int(budget * SECTION_SHARE[name])
+            # half of the constraints section is kept for its human-filed items, which arrive
+            # in standing order, so the freshly filed ones compete for the other half only
+            reserved = int(cap * CONSTRAINT_HUMAN_RESERVE) if name == "constraints" else 0
+            section_used = unreserved_used = 0
+            for item in out.sections[name]:
+                cost = cost_of(item)
+                reserve_eligible = bool(reserved) and item.is_human
+                fits_share = reserve_eligible or unreserved_used + cost <= cap - reserved
+                if section_used + cost <= cap and fits_share and used + cost <= budget - reserve:
+                    kept[name].append(item)
+                    section_used += cost
+                    unreserved_used += 0 if reserve_eligible else cost
+                    used += cost
+                else:
+                    remaining_by_section[name].append(item)
+        taken = {item.id for items in kept.values() for item in items}
+        if found:
+            # what the plugin found and pass 1 did not already keep, in the plugin's order,
+            # up to its share: a record shown once, in the section that placed it first
+            kept["retrieved"], spent = [], 0
+            for item in found:
+                cost = cost_of(item)
+                if item.id not in taken and spent + cost <= reserve and used + cost <= budget:
+                    kept["retrieved"].append(item)
+                    taken.add(item.id)
+                    spent += cost
+                    used += cost
+        left_out: List[str] = []
+        for name in SECTION_ORDER:
+            for item in remaining_by_section[name]:
+                if item.id in taken:
+                    continue  # the retrieved section placed it
+                cost = cost_of(item)
+                if used + cost <= budget:
+                    kept[name].append(item)
+                    used += cost
+                else:
+                    left_out.append(item.id)
+        return kept, used, left_out
+
+    # compile alone; and when the retrieval plugin found something, again with its share
+    # held back from every section but the constraints, which keep what compile alone
+    # gives them. A plugin that finds nothing changes nothing (BENCHMARK-PLAN 1.2)
+    kept, used, left_out = allocate(0, [])
+    if retrieved:
+        kept, used, left_out = allocate(int(budget * retrieval_cfg["share"]), retrieved, fixed=kept["constraints"])
+        out.retrieval["ids"] = [item.id for item in kept["retrieved"]]
+    out.excluded += [(rid, "budget") for rid in left_out]
     out.sections = kept
     out.used_tokens = used
 
@@ -668,6 +713,34 @@ def compile_context(
     return out
 
 
+def _retrieval(ledger, task: Optional[str], eligible: Dict[str, "Item"], out: "Compiled",
+               assessment: Optional[dict] = None):
+    """(the plugin's settings or None, the eligible items it found, best first), and
+    ``out.retrieval`` set to what the receipt records. A plugin that cannot run leaves the
+    view as compile alone makes it, and says so: on the receipt, and in one stderr line."""
+    from . import retrieval as retrieval_mod  # local: retrieval imports this module
+    try:
+        cfg = retrieval_mod.settings(ledger.config)
+    except retrieval_mod.RetrievalError as exc:
+        out.retrieval = {"plugin": retrieval_mod.configured_name(ledger.config), "share": None, "ids": [],
+                         "error": str(exc)}
+        print(f"agent-memory: the retrieval plugin did not run ({exc}); compiled without it", file=sys.stderr)
+        return None, []
+    if cfg is None:
+        return None, []
+    out.retrieval = {"plugin": cfg["plugin"], "share": cfg["share"], "ids": []}
+    if not task:
+        return cfg, []  # nothing to search by: a view with no task is compile's alone
+    try:
+        found = retrieval_mod.retrieve(ledger, task, cfg, assessment)
+    except retrieval_mod.RetrievalError as exc:
+        out.retrieval["error"] = str(exc)
+        print(f"agent-memory: the retrieval plugin {cfg['plugin']} did not run ({exc}); compiled without it",
+              file=sys.stderr)
+        return cfg, []
+    return cfg, [eligible[rid] for rid in found if rid in eligible]
+
+
 def compiled_from_json(payload: dict) -> Compiled:
     """Rebuild a Compiled from ``render.render_json``'s payload.
 
@@ -690,6 +763,7 @@ def compiled_from_json(payload: dict) -> Compiled:
         # saying it was cut
         board=[dict(row) for row in payload.get("board") or []],
     )
+    out.retrieval = payload.get("retrieval") if isinstance(payload.get("retrieval"), dict) else None
     display = payload.get("reader_display")
     out.reader_display = display if isinstance(display, str) and display else None
     out.config_notes = [n for n in payload.get("config_notes") or [] if isinstance(n, str)]
@@ -840,6 +914,10 @@ def record_compilation(ledger, compiled: Compiled, rendered: str, render_name: s
         # which reliability numbers the reader was shown, or null when annotation was off
         "reliability": compiled.reliability_meta,
     }
+    if compiled.retrieval is not None:
+        # which configuration produced the view (ctr_9e166c2f291b829b): the plugin, its
+        # share, the ids it added, and why it did not run when it did not
+        body["retrieval"] = compiled.retrieval
     # which repository the view was cut to, and where it was served and asked from: set
     # only when they are, so a plain view's receipt is what it always was
     for key, value in (("repo", compiled.repo), ("served", compiled.served or None),

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.8}/agent_memory/contracts.py

@@ -181,6 +181,116 @@ def _linked_claims(ledger, contract_id: str, extra: Iterable[str] = ()) -> List[
     return out
 
 
+def _assignee_of(body: dict) -> Optional[str]:
+    value = (body or {}).get("assigned_to")
+    return value.strip().lower() if isinstance(value, str) and value.strip() else None
+
+
+def assignee_now(ledger, contract_id: str) -> Optional[str]:
+    """Who holds the contract: the latest update that names an assignee, else the one it
+    was filed with (what ``status_of`` reports as ``assigned_to``)."""
+    rec = ledger.get(contract_id)
+    held = _assignee_of((rec or {}).get("body") or {})
+    for u in sorted(ledger.contract_updates(contract_id), key=sort_key):
+        held = _assignee_of(u["body"]) or held
+    return held
+
+
+def _may_amend(config: dict, author: dict) -> bool:
+    """A person, or the ledger's PM (config.pm): an agent's standing to amend a bar would
+    rest on an assignment any token can file, so no other agent has it."""
+    return author.get("kind") == "human" or is_pm(config, author)
+
+
+def _names_of(author: dict) -> set:
+    """The names that mean ``author`` when a contract is assigned: its user id and the local
+    part the relay addresses it by, as a reader is matched (``compiler._reader_names``,
+    PROTOCOL section 11). Every holder test here goes through it (the review of #148)."""
+    from .compiler import _reader_names  # local: compiler imports this module
+    return _reader_names(author)
+
+
+def _has_note(body: dict) -> bool:
+    note = body.get("note")
+    return isinstance(note, str) and bool(note.strip())
+
+
+def amendment_refusal(ledger, author: dict, contract_id: str, assigned_to: Optional[str] = None,
+                      note: Optional[str] = None) -> Optional[str]:
+    """Why ``author`` may not amend the contract's acceptance checks, or None
+    (ctr_649e0b459a758929). The worker never writes their own bar, so only a person or
+    the PM amends one. Reassignment is open to any token, so "anybody but the assignee"
+    would let the assignee reassign the contract away and amend it in the next update,
+    and would leave an unassigned contract to whoever wants it (the review of this
+    story). The PM does not amend a contract it holds, or one the same update hands to
+    it; a person may, as a person may reopen a closed one: the bar is the person's to set
+    (the PE's ruling). An amendment is a decision on the record, so it carries a note.
+    A contract names its holder by user id or by local part, and both mean the author."""
+    names = _names_of(author)
+    if not _may_amend(getattr(ledger, "config", None) or {}, author):
+        return (f"{author.get('user') or 'this agent'} may not amend contract {contract_id}'s acceptance checks: "
+                f"an amendment is a person's or the PM's (config.pm), since the worker never writes their own bar")
+    if not (note or "").strip():
+        return (f"an amendment of contract {contract_id}'s acceptance checks is a decision on the record: "
+                f"say why in --note")
+    if author.get("kind") == "human":
+        return None
+    holder = assignee_now(ledger, contract_id)
+    if holder and holder in names:
+        return (f"contract {contract_id} is assigned to {holder}, and the assignee never amends its own "
+                f"acceptance checks: the PM or somebody else does")
+    handed = _assignee_of({"assigned_to": assigned_to})
+    if handed and handed in names:
+        return (f"an amendment of contract {contract_id}'s acceptance checks may not assign the contract to its "
+                f"own author ({handed})")
+    return None
+
+
+def amendments(ledger, contract_id: str) -> List[dict]:
+    """The contract_updates that amend the contract's acceptance checks, oldest first.
+
+    Refused where it is filed, and not counted where it is read, by the same rules: an
+    amendment by anybody but a person or the PM, or with no note, or whose agent author
+    held the contract when it was filed (by user id or local part), or which handed it to
+    that author, changes nothing (one written by hand, or through a replica that did not
+    know the key). The history is folded in ``sort_key`` order, so every machine counts
+    the same ones."""
+    config = getattr(ledger, "config", None) or {}
+    rec = ledger.get(contract_id)
+    held = _assignee_of((rec or {}).get("body") or {})
+    counted = []
+    for u in sorted(ledger.contract_updates(contract_id), key=sort_key):
+        body = u.get("body") or {}
+        if "acceptance_checks" in body and "acceptance" not in body:
+            author = u.get("author") or {}
+            names = _names_of(author)
+            handed = _assignee_of(body)
+            held_by_author = author.get("kind") != "human" and bool(
+                (held and held in names) or (handed and handed in names))
+            if _may_amend(config, author) and _has_note(body) and not held_by_author:
+                counted.append(u)
+        held = _assignee_of(body) or held
+    return counted
+
+
+def acceptance_of(ledger, contract_id: str) -> tuple:
+    """(the acceptance checks the contract answers to, the amendment that set them or
+    None): the latest counted amendment's list, else the one the contract was filed with.
+    Every reader and runner of the checks goes through here (ctr_649e0b459a758929)."""
+    rec = ledger.get(contract_id)
+    if rec is None or rec.get("kind") != "contract":
+        raise KeyError(f"no contract {contract_id}")
+    if not hasattr(ledger, "contract_updates"):
+        # a view that holds no contract_updates cannot see an amendment, and running the list
+        # the contract was filed with would be the very slip this reads past: a caller with
+        # such a view passes the checks the replica reports (``run_acceptance(checks=)``)
+        raise TypeError(f"the acceptance of {contract_id} needs a ledger that holds its contract_updates")
+    latest = amendments(ledger, contract_id)
+    if latest:
+        return latest[-1]["body"]["acceptance_checks"], latest[-1]["id"]
+    return rec["body"]["acceptance"], None
+
+
 def acceptance_runs(ledger, contract_id: str) -> List[dict]:
     """Acceptance-run contract_updates for a contract, oldest first."""
     runs = [u for u in ledger.contract_updates(contract_id) if u["body"].get("acceptance")]
@@ -270,6 +380,13 @@ def verification_basis(ledger, contract_id: str, assessment=None) -> dict:
         return out
     latest = runs[-1]
     out["run"] = latest["id"]
+    amended = amendments(ledger, contract_id)
+    if amended and sort_key(amended[-1]) > sort_key(latest):
+        # the run asked the checks the contract answered to then, not the ones it answers to
+        # now (ctr_649e0b459a758929)
+        out["reason"] = (f"the acceptance was amended by {amended[-1]['id']} after the latest run; "
+                         f"run `agent-memory contract accept {contract_id}`")
+        return out
     if not _run_ok(latest):
         failing = [r.get("check", {}).get("cmd") or r.get("check", {}).get("path") or r.get("check", {}).get("kind")
                    for r in latest["body"]["acceptance"] if r.get("outcome") not in ("match", "skipped")]
@@ -452,6 +569,11 @@ def transition_refusal(ledger, rec: dict, assessment=None) -> Optional[str]:
                           note=note if isinstance(note, str) else None, assessment=assessment)
     except ValidationError as exc:
         return str(exc)
+    if "acceptance_checks" in body:
+        assigned = body.get("assigned_to")
+        return amendment_refusal(ledger, rec.get("author") or {}, contract_id,
+                                 assigned if isinstance(assigned, str) else None,
+                                 note=note if isinstance(note, str) else None)
     return None
 
 
@@ -461,6 +583,7 @@ def update_body(
     note: Optional[str] = None,
     claims: Iterable[str] = (),
     assigned_to: Optional[str] = None,
+    acceptance_checks: Optional[List[dict]] = None,
 ) -> dict:
     """The body of a contract_update that asks for a move, without filing it.
 
@@ -473,6 +596,8 @@ def update_body(
         body["note"] = note
     if assigned_to:
         body["assigned_to"] = assigned_to
+    if acceptance_checks:
+        body["acceptance_checks"] = list(acceptance_checks)
     return body
 
 
@@ -486,13 +611,21 @@ def update(
     claims: Iterable[str] = (),
     tags: Iterable[str] = (),
     assigned_to: Optional[str] = None,
+    acceptance_checks: Optional[List[dict]] = None,
 ) -> dict:
     """File a status transition, enforcing the rules above. ``assigned_to`` hands the
     contract to another agent: the latest update that names one is who holds it, which
-    is what the compiled board shows (a PM reassigns with `contract update --assign`)."""
+    is what the compiled board shows (a PM reassigns with `contract update --assign`).
+    ``acceptance_checks`` replaces the checks the contract answers to from here on
+    (``acceptance_of``); the assignee may not file one (``amendment_refusal``)."""
     _check_transition(ledger, author, contract_id, status, claims, note=note)
+    if acceptance_checks:
+        refusal = amendment_refusal(ledger, author, contract_id, assigned_to, note=note)
+        if refusal:
+            raise ValidationError(refusal)
     rec = new_record("contract_update", author, scope,
-                     update_body(contract_id, status, note=note, claims=claims, assigned_to=assigned_to),
+                     update_body(contract_id, status, note=note, claims=claims, assigned_to=assigned_to,
+                                 acceptance_checks=acceptance_checks),
                      derived_from=[contract_id, *claims], tags=tags)
     return ledger.append(rec)
 
@@ -522,6 +655,8 @@ def status_of(ledger, contract_id: str, assessment: Optional[dict] = None) -> di
     for u in updates:
         linked_ids.update(u["body"].get("claims", []))
     claims = [ledger.get(i) for i in sorted(linked_ids) if ledger.get(i)]
+    checks, amended_by = acceptance_of(ledger, contract_id)
+    amended_note = next((u["body"].get("note") for u in updates if u["id"] == amended_by), None)
     out = {
         "id": contract_id,
         "title": rec["body"]["title"],
@@ -537,7 +672,11 @@ def status_of(ledger, contract_id: str, assessment: Optional[dict] = None) -> di
         # thread besides the assignee's (ctr_b3b3e487832b5c94): a relay asks the replica
         "pm": pm_users(getattr(ledger, "config", None) or {}),
         "issue": rec["body"].get("issue"),
-        "acceptance": rec["body"]["acceptance"],
+        "acceptance": checks,
+        # the amendment the checks come from, or None for the list the contract was filed
+        # with, and the note that says why (an amendment is a decision on the record)
+        "acceptance_amended_by": amended_by,
+        "acceptance_amended_note": amended_note,
         "updates": [{"ts": u["ts"], "status": u["body"]["status"], "by": u["author"].get("harness"), "note": u["body"].get("note")} for u in updates],
         "acceptance_runs": [],
         "last_acceptance_ok": False,
@@ -560,7 +699,7 @@ def status_of(ledger, contract_id: str, assessment: Optional[dict] = None) -> di
 
 def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout: Optional[float] = 600,
                    author: Optional[dict] = None, scope: Optional[dict] = None, file: bool = True,
-                   policy: Optional[dict] = None) -> List[dict]:
+                   policy: Optional[dict] = None, checks: Optional[List[dict]] = None) -> List[dict]:
     """Run each acceptance check and return [{check, outcome, detail, receipt_body, receipt}].
 
     With ``file=True`` and an author and scope, the command/test receipts and a
@@ -588,7 +727,12 @@ def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout:
     except ev.SandboxError as exc:  # asked for and malformed: no check runs at all
         sandbox, unsandboxable = None, str(exc)
     results = []
-    for check in rec["body"]["acceptance"]:
+    # what this runner saw when it started (PROTOCOL 4.1: the status its runner read before
+    # the checks ran), as the remote lane reads it, never a status a close filed mid-run
+    started = status_now(ledger, contract_id) if file and author and scope else None
+    # the checks it answers to now (``acceptance_of``); a caller whose ledger holds no
+    # updates (the remote lane's served view) passes the list the replica reports
+    for check in (checks if checks is not None else acceptance_of(ledger, contract_id)[0]):
         kind = check.get("kind")
         if kind == "command":
             where = ev.resolved_directory(base / check["cwd"] if check.get("cwd") else base,
@@ -621,7 +765,8 @@ def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout:
             detail = (f"exit {body['exit']} (expected {expect_exit})" + (f"; {body.get('summary')}" if body.get("summary") else "")
                       + ("; timed out, and everything it started was stopped" if body.get("timed_out") else ""))
             if sandbox is not None:
-                reason = ev.sandbox_failure(sandbox["image"], body, expect_exit, check["cmd"]) if not ok else None
+                reason = (ev.sandbox_failure(sandbox["image"], body, expect_exit, check["cmd"],
+                                             unproven=ev.image_proof(sandbox, where)) if not ok else None)
                 if reason:
                     outcome, detail = "error", f"{reason}; {detail}"
                 detail = f"sandboxed: podman {sandbox['image']}; {detail}"
@@ -646,7 +791,7 @@ def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout:
             body = r.get("receipt_body")
             if body and body.get("kind") in ("command", "test"):
                 r["receipt"] = ledger.append(new_record("evidence", author, scope, body))["id"]
-        status = status_now(ledger, contract_id)  # what this runner saw: a run reports, it never promotes
+        status = started  # what this runner saw when it started: a run reports, it never promotes
         body = {
             "contract": contract_id,
             "status": status,