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

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

@@ -1,5 +1,59 @@
 # Changes
 
+## 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.
+
+## 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-1.1.0 → consequa_x-1.2.0}/CONTRIBUTING.md

@@ -1,16 +1,29 @@
 # Contributing to Consequa-X
 
-Collaborators with access to this private repository can contribute to the Python framework and research. Stable [`1.0.0` is public on PyPI](https://pypi.org/project/consequa-x/1.0.0/). It separates the application evidence core from research interfaces using refund simulation, programmatic policies, and an optional local Ollama adapter. [Release receipts](output/release-1.0.0-2026-10-15/README.md) retain the installation and publication checks. Recorded results include [audited synthetic sampling](output/interaction-sampling-findings-2026-10-15/FINDINGS.md) and an exploratory [local-model validation](output/local-validation-2026-10-14/FINDINGS.md). These establish declared implementation behavior, not empirical superiority or a new causal estimator. Preserve original samples when adding prompt profiles or evaluations.
-
-Start with the [README](README.md), [design](docs/design.md), and [research roadmap](docs/research-roadmap.md). The [policy replay guide](docs/policy-replay.md) covers bounded context comparisons and evidence exports. Use an issue to discuss a larger adapter, schema change, new domain, or study before investing in the implementation. Small fixes and reproducible bug reports can go straight to a pull request.
-
-The [launch plan](docs/launch-readiness.md) separates shipped functionality from
-proposed adoption features. A private repository issue is available to authorized
-collaborators; it is not yet a public support channel for PyPI users.
+Thanks for helping. This public repository holds the Python package, its tests
+and documentation, the website, and the research records behind the paper. The
+current release is on [PyPI](https://pypi.org/project/consequa-x/). It separates
+a stable application evidence core from declared research interfaces (refund
+simulation, programmatic policies, replay attribution and an optional local
+Ollama adapter). Recorded studies establish declared implementation behavior,
+not empirical superiority or a new causal estimator. Preserve original samples
+when adding prompt profiles or evaluations.
+
+Start with the [README](README.md), [design](docs/design.md), and
+[research roadmap](docs/research-roadmap.md). The
+[policy replay guide](docs/policy-replay.md) covers bounded context comparisons
+and evidence exports. Release receipts under `output/release-*` record the exact
+artifacts and installation checks for each published version.
+
+Use a [GitHub issue](https://github.com/Devrajsinh-Jhala/consequa-x/issues/new/choose)
+to discuss a larger adapter, schema change, new domain, or study before investing
+in the implementation. Small fixes and reproducible bug reports can go straight
+to a pull request. Report vulnerabilities privately as described in
+[SECURITY.md](SECURITY.md), never in a public issue.
 
 ## Set up a development environment
 
-With repository access, clone the repository or an authorized fork and create a branch for your change. Use Python 3.11 or 3.12:
+Fork and clone the repository, then create a branch for your change. Use Python 3.11 or 3.12:
 
 ```sh
 python -m venv .venv
@@ -32,9 +45,8 @@ python -m ruff check src tests
 python -m build
 ```
 
-GitHub Actions is currently disabled because the account quota is exhausted.
-Automatic push and pull-request triggers have been removed; use the local
-checks above. The retained workflow is manual only and must not be re-enabled
+GitHub Actions is currently disabled for this repository. Automatic push and
+pull-request triggers have been removed; use the local checks above. The retained workflow is manual only and must not be re-enabled
 or dispatched without the maintainer's authorization. Its configured test matrix
 does not establish a current test result. Local release checks include fresh
 package installations and access to the bundled trace schema.

consequa_x-1.2.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: consequa-x
+Version: 1.2.0
+Summary: Evidence-aware explanation of consequential agent actions
+Author: Devrajsinh Jhala
+License-Expression: MIT
+Project-URL: Homepage, https://consequa-x.onrender.com
+Project-URL: Documentation, https://consequa-x.onrender.com/docs.html
+Project-URL: Changelog, https://consequa-x.onrender.com/changelog.html
+Project-URL: Repository, https://github.com/Devrajsinh-Jhala/consequa-x
+Project-URL: Issues, https://github.com/Devrajsinh-Jhala/consequa-x/issues
+Project-URL: Security, https://github.com/Devrajsinh-Jhala/consequa-x/security/policy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: jsonschema>=4.23; extra == "dev"
+Dynamic: license-file
+
+# Consequa-X
+
+**Evidence-aware explanation of consequential agent actions.**
+
+When an agent calls a tool that changes something (a refund, a delivery, a
+database write), the tool's response is only part of the story. A timeout can
+hide a refund that went through. A "success" can hide one that never landed.
+Another actor can produce the very outcome the agent was asked for.
+
+Consequa-X keeps four things apart: the **tool response**, what the **agent
+reported**, the outcome established by an **independent read-only readback**, and
+**who produced the effect**. Missing, stale or incomplete evidence stays
+`unknown` instead of being guessed.
+
+- Website, live inspector and docs: <https://consequa-x.onrender.com>
+- Package: <https://pypi.org/project/consequa-x/>
+- Source and issues: <https://github.com/Devrajsinh-Jhala/consequa-x>
+
+Python 3.11+ · MIT licensed · no required runtime dependencies · no model, API
+key or network access needed for the core or the offline examples.
+
+## Install
+
+```sh
+python -m pip install consequa-x
+consequa-x --version
+```
+
+Use `python -m consequa_x` wherever a command below uses `consequa-x`.
+
+## See it in a minute
+
+```sh
+consequa-x demo --output my-demo
+consequa-x report my-demo/traces/episode_01.json --output my-report.html
+```
+
+`demo` writes twelve synthetic refund scenarios with simulated money: timeouts
+before and after commit, false success, partial and duplicate effects, delayed
+readback, retries, another actor and missing provenance. Episode 1 is a timeout
+after commit: the tool timed out and the agent reported failure, but readback
+shows the refund committed and linked to the agent's action. Open
+`my-report.html` in any browser. It is one self-contained file with no scripts
+or network requests.
+
+Each run needs a new output directory, and a report never overwrites an existing
+file. The demo's `evaluator_truth/` folder is simulator ground truth for
+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:
+
+```python
+from consequa_x import (
+    Action, AgentAssessment, AssessmentStatus, Observation, OutcomeContract,
+    Trace, explain, render_report, verify,
+)
+
+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")
+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
+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)
+```
+
+`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.
+
+## 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:
+
+```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
+[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
+[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.
+
+## Command line
+
+| Command | What it does |
+| --- | --- |
+| `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 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.
+- 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
+  and relationships. That is field omission, not anonymization.
+- No accuracy advantage over other methods is claimed.
+
+## Research
+
+The repository also contains declared research interfaces, separate from the
+stable core: 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
+[research roadmap](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/research-roadmap.md)
+and the [paper notes](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/paper/README.md).
+
+## Platforms
+
+The package is pure Python. Released wheels have been install-tested on Windows
+with Python 3.11 and 3.12 and on one Alpine Linux virtual machine with Python
+3.14. macOS has not been tested yet. See the
+[release notes](https://consequa-x.onrender.com/changelog.html) for exact
+environments.
+
+## Contributing and support
+
+- Questions and bugs: [GitHub issues](https://github.com/Devrajsinh-Jhala/consequa-x/issues/new/choose).
+  Use synthetic data only; never post real traces, customer data or credentials.
+- Security: report vulnerabilities privately as described in
+  [SECURITY.md](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/SECURITY.md).
+- Development: see [CONTRIBUTING.md](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/CONTRIBUTING.md).
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check src tests scripts
+```
+
+## License
+
+MIT, copyright Devrajsinh Jhala. The website's self-hosted fonts keep their SIL
+Open Font License.

consequa_x-1.2.0/README.md

@@ -0,0 +1,198 @@
+# Consequa-X
+
+**Evidence-aware explanation of consequential agent actions.**
+
+When an agent calls a tool that changes something (a refund, a delivery, a
+database write), the tool's response is only part of the story. A timeout can
+hide a refund that went through. A "success" can hide one that never landed.
+Another actor can produce the very outcome the agent was asked for.
+
+Consequa-X keeps four things apart: the **tool response**, what the **agent
+reported**, the outcome established by an **independent read-only readback**, and
+**who produced the effect**. Missing, stale or incomplete evidence stays
+`unknown` instead of being guessed.
+
+- Website, live inspector and docs: <https://consequa-x.onrender.com>
+- Package: <https://pypi.org/project/consequa-x/>
+- Source and issues: <https://github.com/Devrajsinh-Jhala/consequa-x>
+
+Python 3.11+ · MIT licensed · no required runtime dependencies · no model, API
+key or network access needed for the core or the offline examples.
+
+## Install
+
+```sh
+python -m pip install consequa-x
+consequa-x --version
+```
+
+Use `python -m consequa_x` wherever a command below uses `consequa-x`.
+
+## See it in a minute
+
+```sh
+consequa-x demo --output my-demo
+consequa-x report my-demo/traces/episode_01.json --output my-report.html
+```
+
+`demo` writes twelve synthetic refund scenarios with simulated money: timeouts
+before and after commit, false success, partial and duplicate effects, delayed
+readback, retries, another actor and missing provenance. Episode 1 is a timeout
+after commit: the tool timed out and the agent reported failure, but readback
+shows the refund committed and linked to the agent's action. Open
+`my-report.html` in any browser. It is one self-contained file with no scripts
+or network requests.
+
+Each run needs a new output directory, and a report never overwrites an existing
+file. The demo's `evaluator_truth/` folder is simulator ground truth for
+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:
+
+```python
+from consequa_x import (
+    Action, AgentAssessment, AssessmentStatus, Observation, OutcomeContract,
+    Trace, explain, render_report, verify,
+)
+
+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")
+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
+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)
+```
+
+`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.
+
+## 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:
+
+```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
+[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
+[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.
+
+## Command line
+
+| Command | What it does |
+| --- | --- |
+| `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 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.
+- 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
+  and relationships. That is field omission, not anonymization.
+- No accuracy advantage over other methods is claimed.
+
+## Research
+
+The repository also contains declared research interfaces, separate from the
+stable core: 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
+[research roadmap](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/research-roadmap.md)
+and the [paper notes](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/paper/README.md).
+
+## Platforms
+
+The package is pure Python. Released wheels have been install-tested on Windows
+with Python 3.11 and 3.12 and on one Alpine Linux virtual machine with Python
+3.14. macOS has not been tested yet. See the
+[release notes](https://consequa-x.onrender.com/changelog.html) for exact
+environments.
+
+## Contributing and support
+
+- Questions and bugs: [GitHub issues](https://github.com/Devrajsinh-Jhala/consequa-x/issues/new/choose).
+  Use synthetic data only; never post real traces, customer data or credentials.
+- Security: report vulnerabilities privately as described in
+  [SECURITY.md](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/SECURITY.md).
+- Development: see [CONTRIBUTING.md](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/CONTRIBUTING.md).
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check src tests scripts
+```
+
+## License
+
+MIT, copyright Devrajsinh Jhala. The website's self-hosted fonts keep their SIL
+Open Font License.

consequa_x-1.2.0/SECURITY.md

@@ -0,0 +1,24 @@
+# Security policy
+
+Please report suspected package vulnerabilities privately through
+[GitHub's private vulnerability reporting form](https://github.com/Devrajsinh-Jhala/consequa-x/security/advisories/new).
+A GitHub account is required. Do not open a public issue containing an exploit,
+credential, private trace or customer data. Use a synthetic reproduction and
+include package/Python/OS versions, impact and reproduction steps. Do not send
+working production credentials.
+
+The latest stable release is the primary maintenance target. Version 1 core
+and schema compatibility are documented; no response deadline or long-term
+support period is promised. Security fixes and breaking changes will be stated
+in release notes. Research interfaces can evolve under their declared scope.
+
+Default HTML reports omit arbitrary captured fields. They retain timing, counts
+and relationships and do not guarantee anonymity. --include-details explicitly
+includes the entire captured trace as escaped text. Keep those reports private
+when the trace is private. The offline renderer makes no network calls and
+does not execute verifiers, replay or application writes.
+
+The framework does not authenticate your readback source or validate that a
+provider's metadata is true. Application-owned adapters must establish source
+trust and domain semantics. Sharing a report does not replace preserving the
+original trace and source evidence.

{consequa_x-1.1.0 → consequa_x-1.2.0}/docs/application-integration.md

@@ -16,7 +16,27 @@ It does not authenticate a source or prove a predicate's domain semantics.
 ## Outcome verification
 
 `verify(action, observation)` retains the built-in `refund_processed` verifier.
-For another domain, explicitly supply a read-only adapter:
+For an outcome that leaves records behind (rows, orders, tickets, files), start
+with the built-in `RecordVerifier` before writing an adapter. Use the predicate
+`record_present`; `contract.expected` lists the field values a matching record
+must carry, and `scope_fields` names the fields the readback snapshot covers:
+
+```python
+verifier = RecordVerifier(scope_fields=("order_id",))
+receipt = verify(action, observation, verifier=verifier)
+explanation = explain(trace, target_matcher=verifier.target_matcher())
+```
+
+It checks the exact or minimum count, the commit deadline and the persistence
+window, and returns `unknown` for unavailable, out-of-scope, incomplete, stale
+or malformed readback. Record identifier, commit time, removal time, action,
+actor and attempt field names are configurable; with the defaults the
+evidence graph also links each record to its dispatch.
+
+To capture an action while an agent runs, use `TraceRecorder`; see
+[capturing agents built with a framework](framework-integration.md).
+
+For any other domain, explicitly supply a read-only adapter:
 
 ```python
 receipt = verify(action, observation, verifier=application_verifier)