consequa-x 1.2.0__tar.gz → 2.0.0__tar.gz

{consequa_x-1.2.0 → consequa_x-2.0.0}/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changes
 
+## 2.0.0 - 19 October 2026 (breaking)
+
+See [the 2.0 design](docs/design-2.0.md) and the
+[migration guide](docs/migrating-to-2.0.md). Deferred to 2.1: verifier
+composition, optional framework integrations and OpenTelemetry export.
+
+- Typed exceptions: every intentional error derives from `ConsequaError` and
+  still from `ValueError` or `TypeError`. `ValidationError` (invalid records,
+  traces and settings; malformed JSON is now one too), `SchemaVersionError`,
+  `ConsequaTypeError`, `ContractError` (a verifier cannot evaluate the
+  contract), `ReceiptError` (a verifier or matcher result crosses its identity
+  boundary, or recorded evidence cannot support the interpretation) and
+  `RecorderError`. `InsufficientEvidenceError` and `PolicyError` join the
+  hierarchy.
+- Captured payloads are deeply read-only. Event data, arguments, contract
+  expectations, results, readback records, scopes and evidence details are
+  `FrozenDict` and `FrozenList` values: they compare equal to and serialize
+  like ordinary dicts and lists, but any change raises `ConsequaTypeError`.
+  `copy.deepcopy` returns the same read-only value; `thaw()` returns an
+  editable copy, and `to_dict()` still exports ordinary dicts and lists.
+- Trace schema `1.0`. A trace holds one or more `actions`, each with its own
+  contract; `responses`, `assessments` (zero or more per action) and
+  `verifications` each name their `action_id`. A required `time_base`
+  (`unix_ms` or `relative_ms`) says what the integer millisecond times count
+  from. `trace_id` is no longer repeated on actions and events. All records
+  are keyword-only. Schema `0.1` input is refused with a `SchemaVersionError`
+  that names the migration route; the packaged schema is `trace-v1.0.json`.
+  New helpers: `Trace.get_action`, `single_action`, `responses_for`,
+  `assessments_for`, `verifications_for`, `latest_assessment`,
+  `latest_verification`.
+- `TraceRecorder.register` can be called for several actions and returns an
+  `ActionCapture` whose `attempt`, `call`, `dispatch`, `response`,
+  `assessment` and `verify` record for that action. The recorder-level methods
+  still work while exactly one action is registered. Assessments are optional
+  and may be repeated. The default clock is wall-clock `unix_ms`; a custom
+  clock records `relative_ms` unless told otherwise. `capture_tool` and
+  `call_mcp_tool` accept an `ActionCapture`.
+- `explain()` returns a `TraceExplanation` with one `ActionExplanation` per
+  action (`for_action`, `single_action`). An action without verification is
+  reported as `NO_VERIFICATION` instead of raising. The evidence graph has a
+  contract node per action, and offline reports show every action, with an
+  Action column for responses and verifications and the time base in the
+  footer.
+- Verifiers own domain interpretation. `VerificationResult` gains
+  `target_effect_ids` (`None` when the verifier did no target matching,
+  otherwise this action's effects that match the full target) and `findings`
+  (`Finding(code, effect_ids, detail)`). `RefundVerifier` records refund
+  matches and the `EXCESS_EFFECTS`, `DUPLICATE_EFFECT`, `PARAMETER_MISMATCH`,
+  `PARTIAL_EFFECT` and `REVERSED_EFFECT` findings; `RecordVerifier` records
+  record matches and `EXCESS_EFFECTS`, `DUPLICATE_EFFECT`,
+  `PARAMETER_MISMATCH` and `REMOVED_EFFECT`. `TargetMatcher`,
+  `RecordTargetMatcher`, `RecordVerifier.target_matcher()` and
+  `explain(..., target_matcher=...)` are removed; a custom verifier sets
+  `target_effect_ids` instead.
+- `explain()` is domain-independent: it reads receipts, responses and
+  assessments and never reinterprets evidence details. Diagnoses are
+  structured `Diagnosis(code, evidence, message)` records; `codes` gives the
+  codes and `diagnosis` a display label. `UNASSESSABLE_ASSESSMENT` now applies
+  to every predicate whenever the outcome is known but alignment cannot be
+  judged (1.x omitted it for refunds). `CORE_DIAGNOSES` lists the codes
+  `explain()` produces.
+- Offline reports show each action's assessment alignment and diagnosis
+  codes, computed from the recorded receipts. Codes from custom verifiers are
+  counted rather than printed.
+- Migration: `migrate_trace()` and `consequa-x migrate OLD --output NEW`
+  convert schema `0.1` traces. Target matches and findings are added only when
+  the 2.0 verifier (the refund verifier by default; pass others with
+  `verifiers=`) reproduces the recorded receipt exactly; no recorded conclusion
+  is changed. `consequa-x validate` checks trace files. Migrated traces of the
+  1.x demo reproduce their 1.x explanations; fixtures written by the released
+  1.2.0 package are in `tests/fixtures/v0.1`.
+- `summarize(traces)` and `consequa-x summarize PATH... [--format text|markdown|json]`
+  count verified state, origin, alignment, tool responses and diagnoses over
+  every action, with stated denominators; `unknown` and `unverified` stay
+  separate from failures, and actions with divergences or violations are
+  listed. Folders (non-trace JSON is skipped and counted) and `.jsonl` stores
+  are accepted; invalid inputs are listed by path and error type only and make
+  the command exit 2.
+- `poll_readback(capture, read, until_ms=, interval_ms=)` waits until the
+  contract horizon, then reads back and verifies repeatedly (every observation
+  and receipt is recorded) until the outcome is `satisfied` or `violated` or the
+  time limit passes; an unresolved `unknown` is returned as is.
+- Async agents: `capture_tool` wraps `async def` tools, `ActionCapture.acall`
+  (and `TraceRecorder.acall`) awaits a tool as one recorded attempt,
+  `averify`/`ActionCapture.averify` accept verifiers whose `verify` is a
+  coroutine (receipts are checked exactly as `verify` checks them), and
+  `apoll_readback` polls with awaited reads and `asyncio.sleep`.
+- `retry_advice(receipt or trace)` turns verified evidence into
+  `DO_NOT_RETRY` (the outcome already holds, whoever produced it), `WAIT`
+  (missing or unknown readback), `ESCALATE` (relevant effects that do not
+  satisfy the contract) or `RETRY_PERMITTED` (a complete readback shows no
+  relevant effect; retry with an idempotency key, since an in-flight attempt can
+  still commit), each with a reason.
+- `compare(left, right)` and `consequa-x compare A B [--fail-on-difference]`
+  compare two traces action by action: contract, tool responses, latest
+  assessment, verified state and origin, alignment and diagnosis codes, plus
+  actions present in only one trace.
+- `consequa-x verify TRACE --readback OBS.json [--scope-field F] --output NEW`
+  verifies a captured readback file with the built-in refund or record
+  verifier and saves the trace with the new receipt, without Python code.
+- `render_report(..., include_details=True, redact=("card_number", ...))` and
+  `consequa-x report --include-details --redact KEY` replace the values of the
+  named JSON keys everywhere in the included trace. Values under other keys are
+  kept; this is omission by name, not anonymization.
+- `TraceStore(path)`: an append-only JSON Lines file of validated traces with
+  unique trace IDs; reading reports the line number of an invalid entry.
+- Research interfaces (`EffectEstimate`, `Intervention`, `leave_one_out`,
+  `recency_attribution`, the policy types) are imported from
+  `consequa_x.research` instead of the top-level namespace.
+- Research code (benchmark, replay, policies, studies and their audit
+  scripts) produces and reads schema `1.0` traces. Retained 1.x study outputs
+  under `output/` are unchanged.
+
 ## 1.2.0 - 19 October 2026
 
 Additive only: the 1.x API and trace schema `0.1` are unchanged.
@@ -33,6 +146,11 @@ Additive only: the 1.x API and trace schema `0.1` are unchanged.
 - The website's workflow cards, documentation and quickstart show the capture
   API. `scripts/check_installed_release.py` now also exercises the recorder,
   tool capture and record verifier from the installed wheel.
+- Published to PyPI with registry hashes verified; see the
+  [release record](output/release-1.2.0-2026-10-19/README.md). Installed checks
+  passed on Windows Python 3.11.9 and 3.12.10, on one Alpine Linux 3.24.2 QEMU
+  guest with Python 3.14.8 and from a fresh PyPI install. macOS has never been
+  tested.
 
 ## 1.1.1 - 18 October 2026
 

{consequa_x-1.2.0 → consequa_x-2.0.0}/MANIFEST.in

@@ -5,3 +5,5 @@ recursive-include docs/studies *.json
 recursive-include tests *.py
 recursive-include examples *.py
 recursive-include scripts *.py
+recursive-include tests/fixtures *.json
+recursive-include tests/fixtures *.md

{consequa_x-1.2.0/src/consequa_x.egg-info → consequa_x-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: consequa-x
-Version: 1.2.0
+Version: 2.0.0
 Summary: Evidence-aware explanation of consequential agent actions
 Author: Devrajsinh Jhala
 License-Expression: MIT
@@ -76,98 +76,103 @@ evaluation only; never pass it to an explainer.
 
 ## Use it in Python
 
-Register the intended outcome before the action, capture what happened, read the
-outcome back from a trusted read-only source, then verify and explain:
+Register each consequential action with its intended outcome before running it,
+let the recorder capture what happens, read the outcome back from a trusted
+read-only source, then verify and explain:
 
 ```python
 from consequa_x import (
-    Action, AgentAssessment, AssessmentStatus, Observation, OutcomeContract,
-    Trace, explain, render_report, verify,
+    Observation, OutcomeContract, RecordVerifier, TraceRecorder, explain, render_report,
 )
 
-expected = {"payment_id": "p1", "amount_minor": 1000, "currency": "INR"}
-contract = OutcomeContract("contract-1", "refund_processed", expected,
-                           deadline_ms=50, stability_ms=20)
-action = Action("refund-1", "trace-1", "agent", "refund", expected, 0, contract)
-
-# In an application, capture this independently from a trusted read-only source.
-observation = Observation(
-    "readback-1", "independent-ledger", 100, 100, {"payment_id": "p1"},
-    ({**expected, "effect_id": "effect-1", "committed_at_ms": 25,
-      "status": "processed", "action_id": "refund-1", "actor": "agent"},),
-)
-receipt = verify(action, observation)
-trace = Trace("trace-1", action, (), (),
-              AgentAssessment(AssessmentStatus.FAILURE, 10),
-              (observation,), (receipt,))
-
-assert receipt.status.value == "satisfied"      # the refund really happened
-assert receipt.origin.value == "confirmed"      # and this action produced it
-assert explain(trace).assessment_alignment == "contradicted"  # the agent said failure
-html = render_report(trace)                      # offline, minimal disclosure
-```
-
-The built-in `refund_processed` verifier checks payment, integer amount,
-currency, exact count, commit deadline and a persistence window. Unavailable,
-incomplete, wrongly scoped or stale readback produces `unknown`. Effect origin is
-a separate conclusion: `confirmed`, `other_actor` or `unknown`.
-
-Traces round-trip through a portable, versioned JSON schema (`0.1`):
-`Trace.from_json(trace.to_json())` rejects unknown fields, broken identity links
-and dependency cycles. `consequa_x.schema.get_trace_schema()` returns the bundled
-JSON Schema.
-
-## Capture a real agent's tool call
-
-`TraceRecorder` records an action while your agent runs, and `RecordVerifier`
-checks any outcome that leaves records behind (rows, orders, tickets, files):
-
-```python
-from consequa_x import OutcomeContract, RecordVerifier, TraceRecorder, explain
-
-contract = OutcomeContract("refund-o-17", "record_present",
-                           {"order_id": "o-17", "amount_minor": 5000, "currency": "INR"},
-                           deadline_ms=200, stability_ms=50)
 verifier = RecordVerifier(scope_fields=("order_id",))
+rec = TraceRecorder("run-17", actor="support-agent", time_base="relative_ms")
+refund = rec.register(
+    "refund-o-17", "issue_refund", {"order_id": "o-17"}, at_ms=0,
+    contract=OutcomeContract(contract_id="refund-o-17", predicate="record_present",
+                             expected={"order_id": "o-17", "amount_minor": 5000},
+                             deadline_ms=200, stability_ms=50))
 
-rec = TraceRecorder("run-17", actor="support-agent")
-rec.register("refund-o-17", "issue_refund", {"order_id": "o-17"}, contract=contract)
 try:
-    with rec.attempt(data={"tool": "issue_refund"}) as attempt:
-        issue_refund("o-17", attempt_id=attempt.attempt_id)   # your tool
-    rec.assessment("success")                                  # what the agent reported
+    with refund.attempt(at_ms=5) as attempt:      # your tool call goes here
+        attempt.at_ms = 30
+        raise TimeoutError                        # ...and it timed out
 except TimeoutError:
-    rec.assessment("failure")
-rec.verify(read_refunds_for("o-17"), verifier=verifier)       # your read-only readback
-print(explain(rec.trace(), target_matcher=verifier.target_matcher()).diagnoses)
+    refund.assessment("failure", at_ms=31)        # what the agent reported
+
+# Captured independently, after the horizon, from a read-only replica of the orders table.
+readback = Observation(
+    observation_id="read-1", source="orders-replica", observed_at_ms=300, as_of_ms=300,
+    scope={"order_id": "o-17"},
+    records=({"effect_id": "rf-1", "order_id": "o-17", "amount_minor": 5000,
+              "committed_at_ms": 20, "action_id": "refund-o-17",
+              "attempt_id": "refund-o-17:attempt-1", "actor": "support-agent"},))
+receipt = refund.verify(readback, verifier=verifier)
+
+result = explain(rec.trace()).for_action("refund-o-17")
+assert receipt.status.value == "satisfied"         # the refund really happened
+assert receipt.origin.value == "confirmed"         # and this action produced it
+assert result.assessment_alignment == "contradicted"   # the agent said failure
+print(result.codes)  # ('ASSESSMENT_DIVERGENCE', 'ACKNOWLEDGEMENT_EFFECT_DIVERGENCE')
+html = render_report(rec.trace())                  # offline, minimal disclosure
 ```
 
-`capture_tool` decorates a synchronous tool so every call is recorded the same
-way. The
-[agent-loop example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/agent_loop_sqlite.py)
-runs this end to end against a real SQLite database, offline, in three modes:
-a timeout after the refund committed, a refund made by someone else, and a
-readback too stale to decide.
+A run can register several actions; each `register` returns that action's
+`ActionCapture`, and its attempts, assessments and verifications stay separate.
+`capture_tool` decorates a tool (synchronous or `async def`) so every call is
+recorded. `poll_readback` re-reads a lagging source until the outcome is known,
+and `retry_advice` turns the receipt into a retry decision.
+
+The built-in verifiers are `RecordVerifier` (rows, orders, tickets, files:
+`record_present`) and `RefundVerifier` (`refund_processed`). Both check values,
+count, commit deadline and persistence; unavailable, incomplete, wrongly scoped or
+stale readback produces `unknown`. Effect origin is a separate conclusion:
+`confirmed`, `other_actor` or `unknown`. Verifiers also record which effects match
+the target and domain findings (excess, duplicate, mismatched, reversed or
+removed effects); `explain` reads those receipts without any domain logic of its
+own.
+
+The [agent-loop example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/agent_loop_sqlite.py)
+runs this end to end against a real SQLite database, offline, in three modes: a
+timeout after the refund committed, a refund made by someone else, and a readback
+too stale to decide. The
+[framework guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/framework-integration.md)
+shows where the calls go in OpenAI Agents SDK, LangChain, Claude Agent SDK and MCP
+tool loops.
+
+Traces round-trip through a portable, versioned JSON schema (`1.0`):
+`Trace.from_json(trace.to_json())` rejects unknown fields, broken identity links
+and dependency cycles, and every captured payload is read-only.
 
 ## Bring your own domain
 
-Supply a read-only `Verifier` for your predicate, and a `TargetMatcher` when the
-agent's reported success or failure should be judged against that contract:
+Write a read-only `Verifier` for your predicate. It returns a
+`VerificationResult` with the state, origin and the effects it saw; to let the
+agent's report be judged, it also records `target_effect_ids` (this action's
+effects that match the full target):
 
 ```python
 receipt = verify(action, observation, verifier=MyVerifier())
-explanation = explain(trace, target_matcher=MyTargetMatcher())
 ```
 
 Your application owns source trust, scope, completeness, timing and provenance;
-Consequa-X checks that receipts bind to the supplied contract and observation,
-and keeps the evidence structured. The
+Consequa-X checks that receipts bind to the supplied action, contract and
+observation, and keeps the evidence structured. The
 [artifact-delivery example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/artifact_delivery.py)
-implements both adapters with public APIs only, and the
+implements a verifier with public APIs only, and the
 [integration guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/application-integration.md)
 describes the boundary in detail. The
 [stable API](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/stable-api.md)
-page lists what version 1 guarantees.
+page lists what version 2 guarantees.
+
+## Upgrading from 1.x
+
+Version 2.0 changes the trace schema to `1.0` (several actions per trace, a
+declared time base, keyword-only and read-only records) and moves domain
+interpretation into verifiers. Convert saved 1.x traces with
+`consequa-x migrate OLD.json --output NEW.json` or `migrate_trace()`. The
+[migration guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/migrating-to-2.0.md)
+lists every change and its replacement.
 
 ## Command line
 
@@ -175,12 +180,17 @@ page lists what version 1 guarantees.
 | --- | --- |
 | `consequa-x demo --output DIR` | Write the twelve synthetic refund scenarios: traces, explanations, schema and manifest |
 | `consequa-x explain TRACE [--output FILE]` | Explain an existing trace without replay; prints JSON or writes a new file |
-| `consequa-x report TRACE --output FILE` | Render a self-contained HTML report; add `--include-details` to embed the full capture |
+| `consequa-x report TRACE --output FILE` | Render a self-contained HTML report; `--include-details` embeds the full capture, `--redact KEY` blanks named keys in it |
+| `consequa-x summarize PATH... [--format markdown]` | Count outcomes, alignment and divergences across trace files, folders and `.jsonl` stores |
+| `consequa-x compare A B` | Compare two traces action by action |
+| `consequa-x verify TRACE --readback OBS --output NEW` | Verify a captured readback file with a built-in verifier |
+| `consequa-x validate TRACE...` / `consequa-x migrate OLD --output NEW` | Check traces; convert schema `0.1` traces |
 | `consequa-x experiment …` and research commands | Paired replay, decision attribution and calibration studies (see Research) |
 
 ## What it does not do
 
 - It does not watch or control a live agent; your application captures the records.
+  `retry_advice` is advice derived from captured evidence, not a guarantee.
 - It does not authenticate a readback source or prove that provider metadata is true.
 - An evidence-graph link records provenance, not causal necessity.
 - Default reports omit captured strings and identifiers, but keep times, counts
@@ -189,8 +199,8 @@ page lists what version 1 guarantees.
 
 ## Research
 
-The repository also contains declared research interfaces, separate from the
-stable core: isolated replay, contrastive and Shapley-style decision attribution,
+The repository also contains declared research interfaces, imported from
+`consequa_x.research`: isolated replay, contrastive and Shapley-style decision attribution,
 calibration studies, an optional local Ollama adapter, and the retained evidence
 for each study. Results so far are synthetic or exploratory local-model studies
 and are reported with their denominators and limits. Start with the

{consequa_x-1.2.0 → consequa_x-2.0.0}/README.md

@@ -49,98 +49,103 @@ evaluation only; never pass it to an explainer.
 
 ## Use it in Python
 
-Register the intended outcome before the action, capture what happened, read the
-outcome back from a trusted read-only source, then verify and explain:
+Register each consequential action with its intended outcome before running it,
+let the recorder capture what happens, read the outcome back from a trusted
+read-only source, then verify and explain:
 
 ```python
 from consequa_x import (
-    Action, AgentAssessment, AssessmentStatus, Observation, OutcomeContract,
-    Trace, explain, render_report, verify,
+    Observation, OutcomeContract, RecordVerifier, TraceRecorder, explain, render_report,
 )
 
-expected = {"payment_id": "p1", "amount_minor": 1000, "currency": "INR"}
-contract = OutcomeContract("contract-1", "refund_processed", expected,
-                           deadline_ms=50, stability_ms=20)
-action = Action("refund-1", "trace-1", "agent", "refund", expected, 0, contract)
-
-# In an application, capture this independently from a trusted read-only source.
-observation = Observation(
-    "readback-1", "independent-ledger", 100, 100, {"payment_id": "p1"},
-    ({**expected, "effect_id": "effect-1", "committed_at_ms": 25,
-      "status": "processed", "action_id": "refund-1", "actor": "agent"},),
-)
-receipt = verify(action, observation)
-trace = Trace("trace-1", action, (), (),
-              AgentAssessment(AssessmentStatus.FAILURE, 10),
-              (observation,), (receipt,))
-
-assert receipt.status.value == "satisfied"      # the refund really happened
-assert receipt.origin.value == "confirmed"      # and this action produced it
-assert explain(trace).assessment_alignment == "contradicted"  # the agent said failure
-html = render_report(trace)                      # offline, minimal disclosure
-```
-
-The built-in `refund_processed` verifier checks payment, integer amount,
-currency, exact count, commit deadline and a persistence window. Unavailable,
-incomplete, wrongly scoped or stale readback produces `unknown`. Effect origin is
-a separate conclusion: `confirmed`, `other_actor` or `unknown`.
-
-Traces round-trip through a portable, versioned JSON schema (`0.1`):
-`Trace.from_json(trace.to_json())` rejects unknown fields, broken identity links
-and dependency cycles. `consequa_x.schema.get_trace_schema()` returns the bundled
-JSON Schema.
-
-## Capture a real agent's tool call
-
-`TraceRecorder` records an action while your agent runs, and `RecordVerifier`
-checks any outcome that leaves records behind (rows, orders, tickets, files):
-
-```python
-from consequa_x import OutcomeContract, RecordVerifier, TraceRecorder, explain
-
-contract = OutcomeContract("refund-o-17", "record_present",
-                           {"order_id": "o-17", "amount_minor": 5000, "currency": "INR"},
-                           deadline_ms=200, stability_ms=50)
 verifier = RecordVerifier(scope_fields=("order_id",))
+rec = TraceRecorder("run-17", actor="support-agent", time_base="relative_ms")
+refund = rec.register(
+    "refund-o-17", "issue_refund", {"order_id": "o-17"}, at_ms=0,
+    contract=OutcomeContract(contract_id="refund-o-17", predicate="record_present",
+                             expected={"order_id": "o-17", "amount_minor": 5000},
+                             deadline_ms=200, stability_ms=50))
 
-rec = TraceRecorder("run-17", actor="support-agent")
-rec.register("refund-o-17", "issue_refund", {"order_id": "o-17"}, contract=contract)
 try:
-    with rec.attempt(data={"tool": "issue_refund"}) as attempt:
-        issue_refund("o-17", attempt_id=attempt.attempt_id)   # your tool
-    rec.assessment("success")                                  # what the agent reported
+    with refund.attempt(at_ms=5) as attempt:      # your tool call goes here
+        attempt.at_ms = 30
+        raise TimeoutError                        # ...and it timed out
 except TimeoutError:
-    rec.assessment("failure")
-rec.verify(read_refunds_for("o-17"), verifier=verifier)       # your read-only readback
-print(explain(rec.trace(), target_matcher=verifier.target_matcher()).diagnoses)
+    refund.assessment("failure", at_ms=31)        # what the agent reported
+
+# Captured independently, after the horizon, from a read-only replica of the orders table.
+readback = Observation(
+    observation_id="read-1", source="orders-replica", observed_at_ms=300, as_of_ms=300,
+    scope={"order_id": "o-17"},
+    records=({"effect_id": "rf-1", "order_id": "o-17", "amount_minor": 5000,
+              "committed_at_ms": 20, "action_id": "refund-o-17",
+              "attempt_id": "refund-o-17:attempt-1", "actor": "support-agent"},))
+receipt = refund.verify(readback, verifier=verifier)
+
+result = explain(rec.trace()).for_action("refund-o-17")
+assert receipt.status.value == "satisfied"         # the refund really happened
+assert receipt.origin.value == "confirmed"         # and this action produced it
+assert result.assessment_alignment == "contradicted"   # the agent said failure
+print(result.codes)  # ('ASSESSMENT_DIVERGENCE', 'ACKNOWLEDGEMENT_EFFECT_DIVERGENCE')
+html = render_report(rec.trace())                  # offline, minimal disclosure
 ```
 
-`capture_tool` decorates a synchronous tool so every call is recorded the same
-way. The
-[agent-loop example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/agent_loop_sqlite.py)
-runs this end to end against a real SQLite database, offline, in three modes:
-a timeout after the refund committed, a refund made by someone else, and a
-readback too stale to decide.
+A run can register several actions; each `register` returns that action's
+`ActionCapture`, and its attempts, assessments and verifications stay separate.
+`capture_tool` decorates a tool (synchronous or `async def`) so every call is
+recorded. `poll_readback` re-reads a lagging source until the outcome is known,
+and `retry_advice` turns the receipt into a retry decision.
+
+The built-in verifiers are `RecordVerifier` (rows, orders, tickets, files:
+`record_present`) and `RefundVerifier` (`refund_processed`). Both check values,
+count, commit deadline and persistence; unavailable, incomplete, wrongly scoped or
+stale readback produces `unknown`. Effect origin is a separate conclusion:
+`confirmed`, `other_actor` or `unknown`. Verifiers also record which effects match
+the target and domain findings (excess, duplicate, mismatched, reversed or
+removed effects); `explain` reads those receipts without any domain logic of its
+own.
+
+The [agent-loop example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/agent_loop_sqlite.py)
+runs this end to end against a real SQLite database, offline, in three modes: a
+timeout after the refund committed, a refund made by someone else, and a readback
+too stale to decide. The
+[framework guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/framework-integration.md)
+shows where the calls go in OpenAI Agents SDK, LangChain, Claude Agent SDK and MCP
+tool loops.
+
+Traces round-trip through a portable, versioned JSON schema (`1.0`):
+`Trace.from_json(trace.to_json())` rejects unknown fields, broken identity links
+and dependency cycles, and every captured payload is read-only.
 
 ## Bring your own domain
 
-Supply a read-only `Verifier` for your predicate, and a `TargetMatcher` when the
-agent's reported success or failure should be judged against that contract:
+Write a read-only `Verifier` for your predicate. It returns a
+`VerificationResult` with the state, origin and the effects it saw; to let the
+agent's report be judged, it also records `target_effect_ids` (this action's
+effects that match the full target):
 
 ```python
 receipt = verify(action, observation, verifier=MyVerifier())
-explanation = explain(trace, target_matcher=MyTargetMatcher())
 ```
 
 Your application owns source trust, scope, completeness, timing and provenance;
-Consequa-X checks that receipts bind to the supplied contract and observation,
-and keeps the evidence structured. The
+Consequa-X checks that receipts bind to the supplied action, contract and
+observation, and keeps the evidence structured. The
 [artifact-delivery example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/artifact_delivery.py)
-implements both adapters with public APIs only, and the
+implements a verifier with public APIs only, and the
 [integration guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/application-integration.md)
 describes the boundary in detail. The
 [stable API](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/stable-api.md)
-page lists what version 1 guarantees.
+page lists what version 2 guarantees.
+
+## Upgrading from 1.x
+
+Version 2.0 changes the trace schema to `1.0` (several actions per trace, a
+declared time base, keyword-only and read-only records) and moves domain
+interpretation into verifiers. Convert saved 1.x traces with
+`consequa-x migrate OLD.json --output NEW.json` or `migrate_trace()`. The
+[migration guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/migrating-to-2.0.md)
+lists every change and its replacement.
 
 ## Command line
 
@@ -148,12 +153,17 @@ page lists what version 1 guarantees.
 | --- | --- |
 | `consequa-x demo --output DIR` | Write the twelve synthetic refund scenarios: traces, explanations, schema and manifest |
 | `consequa-x explain TRACE [--output FILE]` | Explain an existing trace without replay; prints JSON or writes a new file |
-| `consequa-x report TRACE --output FILE` | Render a self-contained HTML report; add `--include-details` to embed the full capture |
+| `consequa-x report TRACE --output FILE` | Render a self-contained HTML report; `--include-details` embeds the full capture, `--redact KEY` blanks named keys in it |
+| `consequa-x summarize PATH... [--format markdown]` | Count outcomes, alignment and divergences across trace files, folders and `.jsonl` stores |
+| `consequa-x compare A B` | Compare two traces action by action |
+| `consequa-x verify TRACE --readback OBS --output NEW` | Verify a captured readback file with a built-in verifier |
+| `consequa-x validate TRACE...` / `consequa-x migrate OLD --output NEW` | Check traces; convert schema `0.1` traces |
 | `consequa-x experiment …` and research commands | Paired replay, decision attribution and calibration studies (see Research) |
 
 ## What it does not do
 
 - It does not watch or control a live agent; your application captures the records.
+  `retry_advice` is advice derived from captured evidence, not a guarantee.
 - It does not authenticate a readback source or prove that provider metadata is true.
 - An evidence-graph link records provenance, not causal necessity.
 - Default reports omit captured strings and identifiers, but keep times, counts
@@ -162,8 +172,8 @@ page lists what version 1 guarantees.
 
 ## Research
 
-The repository also contains declared research interfaces, separate from the
-stable core: isolated replay, contrastive and Shapley-style decision attribution,
+The repository also contains declared research interfaces, imported from
+`consequa_x.research`: isolated replay, contrastive and Shapley-style decision attribution,
 calibration studies, an optional local Ollama adapter, and the retained evidence
 for each study. Results so far are synthetic or exploratory local-model studies
 and are reported with their denominators and limits. Start with the