strata-agent-memory 0.2.2__tar.gz → 0.2.4__tar.gz

{strata_agent_memory-0.2.2/strata_agent_memory.egg-info → strata_agent_memory-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strata-agent-memory
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -201,6 +201,7 @@ tests/             pytest suite; tests/sit/phase3/ is the CLI-driven system test
 - [docs/RESEARCH-SYNTHESIS.md](docs/RESEARCH-SYNTHESIS.md): the nine sources, what was taken from each, and what none of them had.
 - [docs/INTEGRATION.md](docs/INTEGRATION.md): setup per harness, the local verifier lane, the contract loop.
 - [docs/COMMS-BUS-PLAN.md](docs/COMMS-BUS-PLAN.md): how agents talk through the ledger without spending tokens while they wait, and [docs/RUNBOOK-RELAY.md](docs/RUNBOOK-RELAY.md) to run a relay per agent.
+- [docs/HARNESS-MATRIX.md](docs/HARNESS-MATRIX.md): the M3 harness reach matrix: MCP, hooks, wake paths, compile injection and relay fitness for every harness surface, from vendor documentation (nothing run).
 - [docs/LANDSCAPE.md](docs/LANDSCAPE.md): the competing systems, their verified licenses, the standards receipts align with, and what none of them do.
 - [docs/UAT-PLAN.md](docs/UAT-PLAN.md): the one-week acceptance test across Claude Code, Codex, Antigravity and Grok.
 - [docs/UAT-SELF.md](docs/UAT-SELF.md): the same test for one person with two subscriptions, Claude Code and Codex CLI, with `scripts/uat/` to set it up and to run the cross-lineage verification.

{strata_agent_memory-0.2.2 → strata_agent_memory-0.2.4}/README.md

@@ -177,6 +177,7 @@ tests/             pytest suite; tests/sit/phase3/ is the CLI-driven system test
 - [docs/RESEARCH-SYNTHESIS.md](docs/RESEARCH-SYNTHESIS.md): the nine sources, what was taken from each, and what none of them had.
 - [docs/INTEGRATION.md](docs/INTEGRATION.md): setup per harness, the local verifier lane, the contract loop.
 - [docs/COMMS-BUS-PLAN.md](docs/COMMS-BUS-PLAN.md): how agents talk through the ledger without spending tokens while they wait, and [docs/RUNBOOK-RELAY.md](docs/RUNBOOK-RELAY.md) to run a relay per agent.
+- [docs/HARNESS-MATRIX.md](docs/HARNESS-MATRIX.md): the M3 harness reach matrix: MCP, hooks, wake paths, compile injection and relay fitness for every harness surface, from vendor documentation (nothing run).
 - [docs/LANDSCAPE.md](docs/LANDSCAPE.md): the competing systems, their verified licenses, the standards receipts align with, and what none of them do.
 - [docs/UAT-PLAN.md](docs/UAT-PLAN.md): the one-week acceptance test across Claude Code, Codex, Antigravity and Grok.
 - [docs/UAT-SELF.md](docs/UAT-SELF.md): the same test for one person with two subscriptions, Claude Code and Codex CLI, with `scripts/uat/` to set it up and to run the cross-lineage verification.

{strata_agent_memory-0.2.2 → strata_agent_memory-0.2.4}/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.2"
+__version__ = "0.2.4"

strata_agent_memory-0.2.4/agent_memory/approvals.py

@@ -0,0 +1,460 @@
+"""The human-only acts on a ledger, one decision each (docs/PROTOCOL.md section 10).
+
+Agents verify and a PM closes (section 4.1). What is left for a person is small and
+should cost a person one read and one word each: ``pending`` lists it, and ``answer``
+files the person's record for it. An item is one of
+
+    close        a submitted contract that is verified by derivation and that no PM may
+                 close (``pm_may_close`` off, or ``config.pm`` names nobody). A gate.
+    pm-close     a close a PM filed. Information, not a gate: the close stands; the
+                 person acknowledges it, or objects in a note.
+    retraction   a note tagged ``approval:retraction`` asking that a claim be withdrawn:
+                 the claim is the note's ``derived_from`` (or the first claim id its
+                 statement names), the reason is the note.
+    reopen       a note tagged ``approval:reopen --contract <id>``: back to ``accepted``,
+                 or to the status a ``status:<s>`` tag names.
+    reject       a note tagged ``approval:reject --contract <id>``: the work will not be
+                 done.
+    constraint   a note tagged ``approval:constraint``: its statement becomes a
+                 human-filed constraint.
+    needs-human  a relay's breaker stopped a thread (section 11); the person's answer is
+                 a human record on that thread, which is what releases it.
+
+``approval_mode`` decides who is asked for what. human (the default): all of the above.
+auto: the agents close among themselves, so only constraints and retractions -- the acts
+that change what every reader is told is true -- reach a person, and a stopped thread,
+which is an alarm rather than an approval.
+
+A person's answer carries the tags ``approval:approved`` or ``approval:rejected`` and
+``answers:<item id>``, and an item with such an answer from a human is no longer
+pending. Every item carries five lines -- the title and the PR, what was done, the
+evidence (receipt, who re-ran it, the result), the review verdict with its record id, the
+risk -- and the expected answer: approve, reject or hold.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable, List, Optional
+
+from . import contracts
+from .relay.core import agent_name
+from .records import ValidationError, new_record, scope_for_target, sort_key
+
+GATE_KINDS = ("close", "retraction", "reopen", "reject", "constraint", "needs-human")
+PROPOSAL_KINDS = ("retraction", "reopen", "reject", "constraint")
+AUTO_KINDS = ("retraction", "constraint")
+APPROVED, REJECTED = "approval:approved", "approval:rejected"
+PR_URL = re.compile(r"https://github\.com/[\w.-]+/[\w.-]+/pull/(\d+)")
+PR_REF = re.compile(r"\bPR\s*#?(\d+)\b", re.I)
+REOPEN_STATUSES = ("proposed", "accepted", "in_progress")
+LINE = 160  # a summary line a person reads at a glance
+# Every summary is text an agent wrote, shown to the person whose answer it asks for: C0
+# and C1 controls (ESC, CSI) would let it move the cursor and rewrite what the person
+# reads, and bidirectional overrides would reorder it. They become spaces.
+CONTROL = re.compile("[\x00-\x1f\x7f-\x9f\u200b-\u200f\u202a-\u202e\u2066-\u2069]")
+
+
+def _plain(text) -> str:
+    return " ".join(CONTROL.sub(" ", str(text or "")).split())
+
+
+def _short(text: Optional[str], limit: int = LINE) -> str:
+    text = _plain(text)
+    return text if len(text) <= limit else text[:limit - 1].rstrip() + "…"
+
+
+def _first_sentence(text: Optional[str]) -> str:
+    text = _plain(text)
+    match = re.search(r"[.;:](\s|$)", text)
+    return _short(text[:match.start() + 1] if match and match.start() > 20 else text)
+
+
+def _tags(rec: dict) -> List[str]:
+    return [t for t in (rec.get("tags") or []) if isinstance(t, str)]
+
+
+def _human(rec: dict) -> bool:
+    return (rec.get("author") or {}).get("kind") == "human"
+
+
+def _who(author: dict) -> str:
+    return f"{author.get('harness') or author.get('kind') or '?'}/{author.get('user') or '?'}"
+
+
+def _on_thread(ledger, thread: str, author: dict) -> bool:
+    """Whether a note's author is on the thread its tag names: the root's author or one of
+    its addressees, as the relay that stopped the thread is."""
+    root = ledger.get(thread)
+    if not isinstance(root, dict):
+        return False
+    names = {agent_name(root.get("author") or {})}
+    names.update(t[len("to:"):] for t in _tags(root) if t.startswith("to:"))
+    return agent_name(author) in names
+
+
+def _answered(ledger) -> tuple:
+    """({item id: the newest human answer's ts}, {thread: the newest human record's ts}).
+
+    An answer is explicit: a human record tagged ``answers:<id>``; an agent's record
+    carrying the tag answers nothing. A person who replied on a stopped thread some other
+    way has answered it too -- that reply is what released it (section 11) -- so the
+    newest human ``thread:`` record per thread is kept as well. Nothing else counts: a
+    human's unrelated update on a contract is not an answer to whether to close it.
+    """
+    ids, threads = {}, {}
+    for rec in ledger.all():
+        if not _human(rec):
+            continue
+        ts = rec.get("ts") or ""
+        for tag in _tags(rec):
+            if tag.startswith("answers:"):
+                key = tag[len("answers:"):]
+                ids[key] = max(ids.get(key, ""), ts)
+            elif tag.startswith("thread:"):
+                thread = tag[len("thread:"):]
+                threads[thread] = max(threads.get(thread, ""), ts)
+    return ids, threads
+
+
+def _evidence_moved(ledger, contract_id: str, basis: dict) -> str:
+    """The newest ts among the records a close rests on: the latest acceptance run, the
+    standing outcome claims, their verifications, the contract's transitions. A person's
+    answer older than this was an answer to other evidence, so the item is asked again."""
+    stamps = [u.get("ts") or "" for u in ledger.contract_updates(contract_id)]
+    for cid in basis.get("outcomes") or []:
+        stamps.append((ledger.get(cid) or {}).get("ts") or "")
+        stamps += [v.get("ts") or "" for v in ledger.verifications_for(cid)]
+    return max(stamps, default="")
+
+
+# --------------------------------------------------------------------------- the lines
+
+def _pr(ledger, contract_id: Optional[str]) -> Optional[str]:
+    """The newest PR a contract's own records name: its updates' notes, then its claims."""
+    if not contract_id:
+        return None
+    texts = [(u["ts"], u["body"].get("note") or "") for u in ledger.contract_updates(contract_id)]
+    texts += [(c["ts"], c["body"].get("statement") or "") for c in ledger.claims_for_contract(contract_id)]
+    for _, text in sorted(texts, reverse=True):
+        url = PR_URL.search(text)
+        if url:
+            return f"PR #{url.group(1)} ({url.group(0)})"
+        ref = PR_REF.search(text)
+        if ref:
+            return f"PR #{ref.group(1)}"
+    return None
+
+
+def _contract_notes(ledger, contract_id: Optional[str], tag: str) -> List[dict]:
+    """Claims about a contract carrying ``tag`` (or a ``tag:...`` form), newest first."""
+    if not contract_id:
+        return []
+    found = [c for c in ledger.claims_for_contract(contract_id)
+             if any(t == tag or t.startswith(tag + ":") for t in _tags(c))
+             and not ledger.retractions_for(c["id"])]
+    return sorted(found, key=sort_key, reverse=True)
+
+
+def _review(ledger, contract_id: Optional[str]) -> dict:
+    """The newest review note on the contract: tag ``review``, verdict from a ``verdict:``
+    tag (approve, approve-with-nits, changes, reject) or the review's first words."""
+    notes = _contract_notes(ledger, contract_id, "review")
+    if not notes:
+        return {"verdict": None, "id": None, "line": "review: none on file"}
+    note = notes[0]
+    verdict = next((t[len("verdict:"):] for t in _tags(note) if t.startswith("verdict:")), None)
+    shown = verdict or _short(note["body"].get("statement"), 60)
+    return {"verdict": verdict, "id": note["id"],
+            "line": f"review: {shown} ({note['id']}, {_who(note['author'])})"}
+
+
+def _risk(ledger, contract_id: Optional[str]) -> dict:
+    """The newest open risk or finding filed against the contract."""
+    notes = _contract_notes(ledger, contract_id, "risk") + _contract_notes(ledger, contract_id, "finding")
+    if not notes:
+        return {"id": None, "line": "risk: none recorded"}
+    note = sorted(notes, key=sort_key, reverse=True)[0]
+    return {"id": note["id"], "line": f"risk: {_short(note['body'].get('statement'), LINE - 20)} ({note['id']})"}
+
+
+def _evidence(ledger, basis: Optional[dict]) -> str:
+    """Receipt, who re-ran it, the result -- for each outcome the contract rests on."""
+    if not basis or not basis.get("outcomes"):
+        return "evidence: none on file"
+    parts = []
+    for cid in basis["outcomes"]:
+        claim = ledger.get(cid) or {}
+        receipts = [e for e in (claim.get("body") or {}).get("evidence") or [] if isinstance(e, str)]
+        checks = [ledger.get(v) for v in basis["verifications"].get(cid, [])]
+        checks = [v for v in checks if v]
+        if checks:
+            v = checks[-1]
+            results = [r.get("outcome") for r in (v.get("body") or {}).get("results") or [] if isinstance(r, dict)]
+            parts.append(f"{', '.join(receipts) or cid} re-run by {_who(v['author'])} ({v['id']}): "
+                         f"{(v.get('body') or {}).get('verdict')}{', ' + ', '.join(results) if results else ''}")
+        else:
+            parts.append(f"{', '.join(receipts) or cid}: not re-checked by another identity")
+    if basis.get("run"):
+        parts.append(f"acceptance {basis['run']}: " + ("passed" if basis.get("ok") else _short(basis.get("reason"), 80)))
+    return _short("evidence: " + "; ".join(parts), LINE * 2)
+
+
+def _expected_for_close(review: dict, risk: dict) -> str:
+    if review["verdict"] in ("changes", "reject", "request-changes", "blocked"):
+        return "hold"
+    if review["id"] is None or risk["id"] is not None:
+        return "hold"
+    return "approve"
+
+
+def _item(ledger, kind: str, rid: str, contract_id: Optional[str], title: str, done: str, evidence: str,
+          review: dict, risk: dict, expected: str, gate: bool, **extra) -> dict:
+    pr = _pr(ledger, contract_id)
+    # every field an agent wrote is cleaned here, in the item GET /approvals, memory_approvals
+    # and --json hand on, not only in the summary a person reads
+    title, done, evidence = _plain(title), _plain(done), _plain(evidence)
+    review_line, risk_line = _plain(review["line"]), _plain(risk["line"])
+    extra = {key: (_plain(value) if isinstance(value, str) else value) for key, value in extra.items()}
+    lines = [f"{title} -- {pr or 'no PR named'}", done, evidence, review_line, risk_line]
+    return {"id": rid, "kind": kind, "gate": gate, "contract": contract_id, "title": title, "pr": pr,
+            "done": done, "evidence": evidence, "review": review_line, "review_id": review["id"],
+            "risk": risk_line, "risk_id": risk["id"], "expected": expected,
+            "summary": [_short(line, LINE * 2) for line in lines], **extra}
+
+
+# --------------------------------------------------------------------------- the list
+
+def pending(ledger, assessment=None, reader: Optional[str] = None) -> dict:
+    """What waits for a person on this ledger, with the policy that put it there.
+
+    ``assessment`` is the trust assessment to read tiers from (computed once when
+    omitted). ``reader`` is the user asking: a user-scoped proposal is listed only to
+    its owner, as every other user-scoped record is.
+    """
+    config = ledger.config
+    mode = contracts.approval_mode(config)
+    tiers = assessment if assessment is not None else contracts._Lazy(ledger)
+    answered, released = _answered(ledger)
+    items: List[dict] = []
+
+    def visible(rec: dict) -> bool:
+        scope = rec.get("scope") or {}
+        return scope.get("level") != "user" or (reader is not None and scope.get("user") == reader)
+
+    no_pm = not contracts.pm_may_close(config) or not contracts.pm_users(config)
+    for rec in sorted(ledger.by_kind("contract"), key=sort_key):
+        cid = rec["id"]
+        filed = contracts.filed_status(ledger, cid)
+        title = _short(rec["body"].get("title"), 100)
+        if mode == "human" and filed in ("submitted", "verified") and no_pm:
+            # a `verified` filed before the rule is history the old machine judged: its
+            # close is still a person's, and the lines show what it rests on today. A
+            # person who declined it is asked again once the evidence moves.
+            basis = contracts.verification_basis(ledger, cid, tiers)
+            fresh = cid not in answered or answered[cid] < _evidence_moved(ledger, cid, basis)
+            if fresh and (basis["ok"] or filed == "verified"):
+                outcome = (ledger.get(basis["outcomes"][0]) if basis["outcomes"] else None) or {}
+                review, risk = _review(ledger, cid), _risk(ledger, cid)
+                items.append(_item(ledger, "close", cid, cid, title,
+                                   _first_sentence((outcome.get("body") or {}).get("statement")),
+                                   _evidence(ledger, basis), review, risk,
+                                   _expected_for_close(review, risk), gate=True))
+        if mode == "human" and filed == "closed":
+            close = contracts.transitions(ledger, cid)[-1]
+            # a PM's close, listed so a person sees it; an agent that closed before there
+            # was a PM rule is history, not something to acknowledge now
+            if contracts.is_pm(config, close["author"]) and close["id"] not in answered:
+                review, risk = _review(ledger, cid), _risk(ledger, cid)
+                basis = contracts.verification_basis(ledger, cid, tiers)
+                items.append(_item(ledger, "pm-close", close["id"], cid, title,
+                                   _short(f"closed by {_who(close['author'])}: {close['body'].get('note') or ''}"),
+                                   _evidence(ledger, basis), review, risk, "approve", gate=False))
+
+    kinds = AUTO_KINDS if mode == "auto" else PROPOSAL_KINDS
+    for note in sorted(ledger.by_kind("claim"), key=sort_key):
+        if note["id"] in answered or not visible(note) or ledger.retractions_for(note["id"]):
+            continue
+        tags = _tags(note)
+        if "needs-human" in tags:  # an alarm in either mode: auto removes approvals, not alarms
+            thread = next((t[len("thread:"):] for t in tags if t.startswith("thread:")), None)
+            if thread and released.get(thread, "") <= (note.get("ts") or ""):
+                # a relay's note on a stop something released before the note was due (a
+                # contract update, section 11) is news for a person, and waits on nobody --
+                # when the relay that stopped is the one saying so: any token can file a note,
+                # and one tagged released by a stranger to the thread is still a stop
+                gone = "released" in tags and _on_thread(ledger, thread, note.get("author") or {})
+                items.append(_item(ledger, "needs-human", note["id"], (note.get("body") or {}).get("contract"),
+                                   f"thread {thread}", _short(note["body"].get("statement")),
+                                   f"evidence: the last message on it is {', '.join(note.get('derived_from') or []) or '?'}",
+                                   {"verdict": None, "id": None, "line": "review: none (a breaker, not work)"},
+                                   {"id": None, "line": ("risk: none -- the thread was released before this note, "
+                                                         "and what it held goes to the agent with the release")
+                                    if gone else
+                                    "risk: the thread stays stopped until a person answers on it"},
+                                   "approve", gate=not gone, thread=thread))
+            continue
+        kind = next((t[len("approval:"):] for t in tags if t.startswith("approval:")), None)
+        if kind not in kinds:
+            continue
+        item = _proposal(ledger, note, kind, tiers)
+        if item is not None:
+            items.append(item)
+    return {"approval_mode": mode, "pm_may_close": contracts.pm_may_close(config),
+            "pm": contracts.pm_users(config), "items": items,
+            "waiting": sum(1 for i in items if i["gate"]), "information": sum(1 for i in items if not i["gate"])}
+
+
+def _target_claim(ledger, note: dict) -> Optional[dict]:
+    """The one claim a retraction proposal names: its derived_from when that names any
+    record, else the claim ids in its statement -- and only when exactly one claim is
+    named. A note that names two would otherwise have the person retract whichever came
+    first (review, story 1); it waits, saying why, until it names one."""
+    named = [rid for rid in (note.get("derived_from") or []) if rid != note["id"]]
+    if not named:
+        named = [rid for rid in contracts.CLAIM_ID.findall(note["body"].get("statement") or "") if rid != note["id"]]
+    named = list(dict.fromkeys(named))
+    if len(named) != 1:
+        return None
+    rec = ledger.get(named[0])
+    return rec if rec is not None and rec.get("kind") == "claim" else None
+
+
+def _proposal(ledger, note: dict, kind: str, tiers) -> Optional[dict]:
+    """A PM's note asking for a human-only act, as an item -- or None once the act has
+    happened by some other road (the claim already withdrawn, the contract already there)."""
+    body = note.get("body") or {}
+    cid = body.get("contract")
+    title = _short((ledger.get(cid) or {}).get("body", {}).get("title"), 100) if cid else "(no contract)"
+    review, risk = _review(ledger, cid), _risk(ledger, cid)
+    asked = f"{_who(note['author'])} asks: {_short(body.get('statement'), LINE - 30)}"
+    if kind == "retraction":
+        target = _target_claim(ledger, note)
+        if target is None:
+            return _item(ledger, kind, note["id"], cid, title if cid else "retract (no single claim named)", asked,
+                         "evidence: the note names no single claim to retract; name exactly one in derived_from",
+                         review, risk, "reject", gate=True, target=None)
+        if ledger.retractions_for(target["id"]):
+            return None
+        tier = tiers.get(target["id"], {}).get("tier", "?")
+        evidence = f"evidence: {target['id']} by {_who(target['author'])} is {tier}"
+        return _item(ledger, kind, note["id"], cid, title if cid else f"retract {target['id']}", asked, evidence,
+                     review, risk, "approve", gate=True, target=target["id"])
+    if kind in ("reopen", "reject"):
+        if not cid or ledger.get(cid) is None:
+            return None
+        filed = contracts.filed_status(ledger, cid)
+        if kind == "reject" and filed == "rejected":
+            return None
+        if kind == "reopen" and filed not in contracts.TERMINAL_STATUSES:
+            return None
+        status = "rejected" if kind == "reject" else next(
+            (t[len("status:"):] for t in _tags(note) if t.startswith("status:")
+             and t[len("status:"):] in REOPEN_STATUSES), "accepted")
+        return _item(ledger, kind, note["id"], cid, title, asked,
+                     f"evidence: the contract is {filed}; this moves it to {status}",
+                     review, risk, "approve", gate=True, to_status=status)
+    if kind == "constraint":
+        # the whole statement is what becomes the constraint, so the whole of it is shown:
+        # a summary cut at 160 characters would let a tail nobody read be approved
+        return _item(ledger, kind, note["id"], cid, title if cid else "a constraint for every reader", asked,
+                     "evidence: a constraint is what a person says always applies; nothing to re-run",
+                     review, risk, "approve", gate=True, text=_plain(body.get("statement")))
+    return None
+
+
+# --------------------------------------------------------------------------- the answer
+
+def answer(ledger, author: dict, scope: dict, item_id: str, verdict: str = "approve",
+           note: Optional[str] = None, assessment=None) -> List[dict]:
+    """File a person's answer to one pending item; returns the records filed.
+
+    Refused for anything but a human identity: an agent may explain and recommend, and
+    the record this files is the one thing it may not. ``reject`` needs a note (the reason
+    is the record); ``approve`` takes one. Raises ValidationError with the refusal, or
+    KeyError when nothing is pending under that id.
+    """
+    if author.get("kind") != "human":
+        raise ValidationError(
+            f"approving is a person's act: this identity is an agent's ({_who(author)}); file the answer under "
+            f"a human token (agent-memory approve --as-human locally, or a human's token over --remote)")
+    if verdict not in ("approve", "reject"):
+        raise ValidationError("an answer is approve or reject; hold is filing nothing")
+    note = (note or "").strip() or None
+    if verdict == "reject" and not note:
+        raise ValidationError("a rejection needs a note: the reason is the record")
+    # one assessment for the list and the close's basis: each would otherwise compute its own
+    assessment = assessment if assessment is not None else contracts._Lazy(ledger)
+    view = pending(ledger, assessment)
+    item = next((i for i in view["items"] if i["id"] == item_id), None)
+    if item is None:
+        raise KeyError(f"nothing pending under {item_id} (agent-memory approvals lists what is)")
+    tags = [APPROVED if verdict == "approve" else REJECTED, f"answers:{item_id}"]
+    said = f": {note}" if note else ""
+    if verdict == "reject" or item["kind"] == "pm-close":
+        return [_answer_note(ledger, author, scope, item, verdict, note, tags)]
+    kind = item["kind"]
+    if kind == "close":
+        basis = contracts.verification_basis(ledger, item["contract"], assessment)
+        relied = [f"{c} re-checked in {', '.join(basis['verifications'].get(c, [])) or '-'}" for c in basis["outcomes"]]
+        return [contracts.update(ledger, author, scope, item["contract"], "closed",
+                                 note=f"approved: {'; '.join(relied)}{said}", tags=tags)]
+    if kind in ("reopen", "reject"):
+        proposal = ledger.get(item_id)
+        reason = note or (proposal or {}).get("body", {}).get("statement")
+        return [contracts.update(ledger, author, scope, item["contract"], item["to_status"],
+                                 note=f"approved {item_id}: {_short(reason, 400)}", tags=tags)]
+    if kind == "retraction":
+        if not item.get("target"):
+            raise ValidationError(f"{item_id} names no single claim to retract: reject it, and ask for a note "
+                                  f"that names exactly one in derived_from")
+        proposal = ledger.get(item_id) or {}
+        target = ledger.get(item["target"])
+        reason = f"approved {item_id}: {proposal.get('body', {}).get('statement')}{said}"
+        rec = new_record("retraction", author, scope_for_target(target, scope),
+                         {"claim": target["id"], "reason": _short(reason, 1900)},
+                         derived_from=[target["id"]], tags=tags)
+        return [ledger.append(rec)]
+    if kind == "constraint":
+        proposal = ledger.get(item_id) or {}
+        body = {"type": "constraint", "statement": proposal["body"]["statement"]}
+        if proposal["body"].get("contract"):
+            body["contract"] = proposal["body"]["contract"]
+        return [ledger.append(new_record("claim", author, scope, body, derived_from=[item_id], tags=tags))]
+    if kind == "needs-human":
+        tags.append(f"thread:{item['thread']}")
+        body = {"type": "note", "statement": f"released thread {item['thread']}{said or ': read and answered'}"}
+        return [ledger.append(new_record("claim", author, scope, body, derived_from=[item_id], tags=tags))]
+    raise ValidationError(f"no answer is defined for a {kind} item")
+
+
+def _answer_note(ledger, author: dict, scope: dict, item: dict, verdict: str, note: Optional[str],
+                 tags: Iterable[str]) -> dict:
+    """The record for an acknowledgement or a rejection: a note, on the contract when the
+    item has one, deriving from the item when the item is a claim (rule 10)."""
+    word = "acknowledged" if verdict == "approve" else "declined"
+    body = {"type": "note", "statement": _short(f"{word} {item['kind']} {item['id']}{': ' + note if note else ''}", 1900)}
+    if item.get("contract"):
+        body["contract"] = item["contract"]
+    target = ledger.get(item["id"])
+    derived = [item["id"]] if target is not None and target.get("kind") == "claim" else []
+    return ledger.append(new_record("claim", author, scope, body, derived_from=derived, tags=list(tags)))
+
+
+def render(view: dict) -> str:
+    """The text a person reads: a header, then five lines and the expected answer per item."""
+    lines = [f"approvals: approval_mode {view['approval_mode']}, pm_may_close "
+             f"{'on' if view['pm_may_close'] else 'off'}, PM {', '.join(view['pm']) or 'none'}; "
+             f"{view['waiting']} waiting, {view['information']} for information"]
+    for item in view["items"]:
+        lines.append("")
+        lines.append(f"[{item['kind']}] {item['id']}" + ("" if item["gate"] else "  (information: the close stands)"))
+        for n, text in enumerate(item["summary"], 1):
+            lines.append(f"  {n} {text}")
+        if item.get("text"):
+            lines.append(f"  the constraint, in full: {item['text']}")
+        lines.append(f"  -> {item['expected']}:  agent-memory approve {item['id']}   |   "
+                     f"agent-memory reject {item['id']} --note \"...\"")
+    if not view["items"]:
+        lines.append("nothing waits for a person")
+    # the view may come from a replica (GET /approvals): the text is cleaned here as well
+    return "\n".join(CONTROL.sub(" ", line) for line in lines)