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

consequa_x-2.0.0/CHANGELOG.md

@@ -0,0 +1,298 @@
+# 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.
+
+- Added `TraceRecorder` (`consequa_x.capture`), which records one action as it
+  happens (context, decision, registration with its outcome contract,
+  dispatches, tool responses, the agent's assessment, readbacks and
+  verification) and returns an ordinary validated `Trace`. Events are linked
+  as in the package fixtures, so graphs, reports and `explain()` work unchanged.
+- Added tool-call capture: `TraceRecorder.attempt()` (context manager),
+  `TraceRecorder.call()` and the `capture_tool` decorator record the dispatch
+  and the response (success, `timeout` for `TimeoutError`, or `error`) around
+  a synchronous tool, keep JSON results, keep only exception type names, and
+  re-raise. A recorded timeout says nothing about whether the effect happened.
+- Added `RecordVerifier` and `RecordTargetMatcher` for a generic `record_present`
+  predicate: records with given field values, an exact or minimum count,
+  a commit deadline and a persistence window, with configurable field names.
+  Unavailable, out-of-scope, incomplete, stale or malformed readback stays
+  `unknown`, and origin stays a separate conclusion, as for refunds.
+- Added `examples/agent_loop_sqlite.py`: a stdlib-only, offline tool-calling
+  loop that writes to a real SQLite database, is captured with `TraceRecorder`,
+  and is verified through a separate read-only connection with `RecordVerifier`.
+  Modes: `timeout_after_commit`, `other_actor` and `stale_readback`.
+  It is also in the website's quickstart download.
+- README section on capturing a real agent's tool call.
+- Added `TraceRecorder.now()`, the recorder clock for readback times.
+- Added `consequa_x.mcp_capture.call_mcp_tool`, which records an awaited MCP
+  tool call from any session exposing `call_tool(name, arguments)` without an
+  MCP dependency. Tool content is not copied into the trace.
+- Added a framework integration guide (`docs/framework-integration.md`).
+- 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
+
+- Documentation and metadata release. Runtime code and schema `0.1` are
+  identical to 1.1.0 apart from the version number.
+- Rewrote the package description for PyPI with absolute links that work outside
+  the repository. Project URLs now point to the public source repository and to
+  <https://consequa-x.onrender.com>.
+- The source repository is public. Its issue forms and security policy replace
+  the separate community repository, whose quickstart and release notes moved to
+  `docs/quickstart.md` and `docs/release-notes.md`.
+- The website inspector and live demo replay recorded output from real package
+  runs, generated by `scripts/build_site_demo.py` and pinned by
+  `tests/test_site_demo.py`. The site deploys from this repository.
+- The snapshot-integrity test now verifies every committed manifest format and
+  ignores uncommitted study outputs.
+- Published to PyPI with registry hashes verified; see the
+  [release record](output/release-1.1.1-2026-10-18/README.md). Installed checks
+  passed on Windows Python 3.11.9 and 3.12.10 and from a fresh PyPI install.
+  Linux and macOS were not rerun for 1.1.1; macOS has never been tested.
+
+## 1.1.0 - 17 October 2026
+
+- Added `render_report(trace, include_details=False)` and
+  `consequa-x report trace.json --output report.html`, with a self-contained
+  chronology, contract, responses, assessment, readback, verification/origin and
+  SVG evidence graph plus complete accessible graph tables.
+- Default reports omit arbitrary captured values throughout the file. Explicit
+  details mode includes the full trace as escaped inert JSON. No report executes
+  actions, verifiers, target matchers or replay; alignment remains unassessable
+  in the report. The original trace remains separate evidence.
+- Preserved source and existing output files with exclusive creation. Invalid
+  schema data is refused before an output directory is created, with captured
+  values omitted from report-command decoding errors.
+- Added a synthetic artifact-delivery visual quickstart and public documentation,
+  support and security routes, while retaining the private research repository.
+- Added installed-package release checks and browser/report security gates.
+  Release receipts bind the final artifact, actual platform checks and
+  publication state; public release notes report the tested environments.
+- Preserved the dependency-free version-1 core and portable wire schema `0.1`.
+  GitHub Actions stays disabled.
+
+## Post-release research update - 16 October 2026
+
+The predeclared physical-interaction study finished collection on 15 October
+2026 at frozen runtime source `0bd744df4fc8784e4cf1a1e2eb62f892c6f3c8c9`.
+It retained all 2,048 trials and 655,360 planned branch slots, with 628,535 actual
+scripted policy calls, no model calls and no additional comparison calls.
+The [protocol](output/interaction-sampling-2026-10-15/protocol.json),
+[complete summary](output/interaction-sampling-2026-10-15/summary.json) and
+[execution receipt](output/interaction-sampling-2026-10-15-execution.json) retain
+the collection identity separately from the public stable release. The
+[independent audit](output/interaction-sampling-audits-2026-10-15/independent.json)
+passed 44,698,925 assertions, covering every planned trial/branch and 4,210
+preselected complete traces. The
+[derived findings](output/interaction-sampling-findings-2026-10-15/FINDINGS.md)
+retain coverage, width, detection and refusal denominators. The defined
+framework and protocol/software paper scope is complete on 16 October 2026:
+the [illustrated eight-page IEEE PDF](output/pdf/Consequa-X_IEEE_Paper.pdf) compiled and all
+rendered pages passed visual review. The [QA receipt](output/pdf/qa.json) binds
+it to the frozen [editable source](paper/consequa-x-ieee.tex) and four vector
+figures. Actual venue selection, final human
+review, reviewer access and submission remain maintainer steps. These results
+do not establish held-out model performance, a new estimator or baseline
+superiority.
+
+## 1.0.0 - 15 October 2026
+
+Runtime source is frozen at `0bd744df4fc8784e4cf1a1e2eb62f892c6f3c8c9`.
+The [stable release is public on PyPI](https://pypi.org/project/consequa-x/1.0.0/),
+built from `85ce6c316838c995782aadc8c10770acc708339b` with all 36 runtime files
+matching that freeze. Both downloads were independently hash/size checked;
+[publication](output/release-1.0.0-2026-10-15/publication.json) and
+[fresh registry-install](output/release-1.0.0-2026-10-15/registry-install.json)
+receipts record the achieved release. PR #8 merged as `708d064`; GitHub remains
+private. Published artifacts retain their original reviewed bytes and dated
+build-time documentation.
+
+- Defined the version 1 stable evidence-core API while retaining wire schema
+  `0.1`. Benchmark procedures, exact policy prompts and study commands remain
+  explicitly scoped research interfaces.
+- Added explicit application verifiers to `verify(..., verifier=...)`, with
+  receipt checks for contract, observation identity, source, watermark and
+  capture time. Adapter semantics and source authentication remain application
+  responsibilities.
+- Added `TargetMatcher` and `explain(..., target_matcher=...)`. Non-refund
+  predicates remain domain-neutral and unassessable without declared target
+  semantics; unknown receipts never execute the matcher. Invalid adapter methods
+  and inputs have controlled type errors, and invalid target returns or known
+  refund details have controlled value errors.
+- Exported `Evidence`, `ToolResponse`, `ResponseStatus` and `TargetMatcher` from
+  the package root. Added the standalone artifact-delivery application example
+  and source-archive integration documentation.
+- Preserved successive and duplicate effect records as separate graph witnesses,
+  with identity edges and observation-specific verification/origin links.
+  Conflicting later payloads or provenance cannot overwrite an earlier witness.
+  Source-owned reserved fields remain available verbatim; attribution candidates
+  must identify captured events.
+- Made demonstration, fixture-experiment and explanation output paths preserve
+  existing evidence. Run directories must be new or empty; explanation output
+  must be a new file distinct from the input trace.
+- Added `calibrate-interactions`, reproducible repeated physical refund sampling,
+  same-draw uncertainty comparisons, bounded parallel execution, complete
+  refusal/cost records and an independently implemented audit. The retained
+  2,048-trial collection completed after the distribution-build checkpoint;
+  its later research status is recorded above without changing released bytes.
+
+The full frozen-source suite passed 1,480 tests and 240 subtests. Twenty
+additional stable-publisher tests passed; final installed-wheel Windows Python
+3.11.9 conformance passed 200 tests and 165 subtests. Independent Windows Python
+3.12.14 wheel, source-archive and registry installations each passed 12 trace
+round-trips and four artifact-adapter checks. All eight local release gates,
+public artifact hash/size verification and the fresh registry installation are
+complete. No GitHub Actions were used. These software checks do not establish
+held-out model performance or attribution superiority.
+
+## 0.1.0a2 — 14 October 2026
+
+- Default decision-contrastive uncertainty now uses exact binomial intervals.
+  Signed Shapley pair means use Hoeffding bounds; independent endpoint
+  differences use two exact binomial marginals with a split failure allowance.
+  Original bootstrap/normal modes remain explicit comparators.
+- Added `compare-intervals`, with a pre-call protocol, complete same-draw
+  retention, exact finite distribution calculations, width/power metrics and
+  independent numerical/artifact audits. Original calibration data is preserved.
+- Added an explicit on-reach positional game for normally terminated later
+  decisions. The strict game remains the default, and incompatible operations,
+  unknown evidence, provider failures and budget refusals remain explicit.
+- Added `refund-interactions` to enumerate physical selection/retry interactions,
+  idempotency and evidence/budget controls through actual payment readback.
+- Interval rescoring now reconstructs Shapley pair vectors from replay evidence
+  and validates stored coverage, points and endpoint diagnostics.
+- Cached static record annotations while retaining validation of every value;
+  added a working paper, reproducible evidence links and release preparation.
+
+This is an engineering alpha. Sampling assumptions, individual-interval scope
+and intervention games remain explicit. Synthetic validation does not establish
+live-model calibration, cross-task generalization or attribution superiority.
+GitHub Actions remains disabled; checks and builds run locally.
+
+## 0.1.0a1
+
+Initial Python alpha with portable evidence records, independent refund
+verification, evidence graphs, local policy adapters and bounded replay
+experiments. No registry publication is implied by the source version.

{consequa_x-1.1.1 → 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.1.1/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.1.1
+Version: 2.0.0
 Summary: Evidence-aware explanation of consequential agent actions
 Author: Devrajsinh Jhala
 License-Expression: MIT
@@ -76,66 +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
+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))
+
+try:
+    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:
+    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
 ```
 
-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`):
+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. `consequa_x.schema.get_trace_schema()` returns the bundled
-JSON Schema.
+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
 
@@ -143,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
@@ -157,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