twincheck 0.12.0a1__tar.gz

twincheck-0.12.0a1/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+## Unreleased
+
+No user-facing changes are currently unreleased.
+
+## 0.12.0a1 - Pinned exploration protocol corpus v1 and public alpha release
+
+- Rewrite the README for public alpha users and add a standalone installation and quick-start guide.
+- Add a publication-safety audit record and automated Gitleaks, CodeQL, OpenSSF Scorecard and Dependabot configuration.
+- Add a draft GitHub Release workflow that builds and verifies artifacts from version tags.
+- Add a PyPI Trusted Publishing workflow gated by the GitHub `pypi` environment and a published GitHub Release.
+- Require the quick-start guide to be included in verified source distributions.
+- Clarify the alpha release and compatibility policy.
+- Pin GitHub Actions dependencies to immutable commit SHAs for supply-chain integrity.
+
+- Add a separate, versioned synthetic exploration corpus with clean-control, response-value drift, stateful read-ordering, and paired-field interaction cases.
+- Pin fixture, schema and protocol-runner SHA-256 digests and validate the corpus manifest and workflow/contract schemas before executing targets.
+- Add a matched-budget static/adaptive protocol runner that checks expected findings, records sanitized schedule fingerprints, and repeats each fixed seed to test reproducibility.
+- Report per-case outcomes, paired detection categories, schedule stability, run times, seeds and budgets while explicitly limiting claims to the synthetic fixtures.
+- Run the protocol in the Linux/Windows CI matrix and include its files in the verified source archive.
+
+This remains an alpha validation fixture, not an external benchmark or claim of general effectiveness. The paired-field interaction is an intentionally narrow toy defect and its seed is pinned to a known schedule.
+
+## 0.11.0a1 - Supported public Python API v1 (alpha)
+
+- Expose a versioned Python API for command-line differential comparisons, compatibility contracts, and JSON/JUnit report output.
+- Re-export the documented API symbols at the package root and define API_VERSION = 1 as the explicit public compatibility marker.
+- Add API compatibility tests for exports, deterministic generated-case comparison, contract loading, serialization and report writers.
+- Add a clean-wheel API smoke test and require the public API documentation and tests in the source archive.
+- Document which Python imports are supported, how breaking API changes are versioned, and which HTTP workflows remain CLI-only.
+
+This remains pre-1.0 software. API v1 is an explicit compatibility commitment for the documented exports, not a guarantee for internal modules, every report field, or every CLI option.
+
+## 0.10.0a1 - Observation-driven stateful exploration (alpha)
+
+- Add an opt-in adaptive exploration mode that generates paired scalar-boundary candidates after newly observed response branches, adjacent transitions, or difference signatures.
+- Preserve static seeded exploration as the default and record the algorithm version, generation rationale, selection rationale, candidate counts, budget and stop reason.
+- Add a bounded wall-clock start gate alongside case, timeout, output and minimization-trial limits. Each reset-backed candidate/minimization workflow continues to use explicit reset and health semantics.
+- Add an end-to-end test where adaptive exploration finds a two-field interaction defect that static exploration misses under the same two-case budget.
+- Add a repeatable static-vs-adaptive comparison script for a pinned synthetic corpus fixture and run it in the Linux/Windows CI matrix.
+- Document that the heuristic is not general state-machine learning and that response-shape novelty is not source-code coverage.
+- Add distribution validation that builds a wheel and source archive, checks metadata, and installs the wheel in an isolated environment outside the checkout.
+- Add a manual release-candidate workflow and an explicit pre-1.0 CLI/schema/Python API compatibility policy; the workflow does not publish to PyPI.
+- Use SPDX-style PEP 639 license metadata and include the license file explicitly in built distributions.
+
+This remains an alpha. The comparison is fixture-only and is not a general performance or superiority claim. An in-flight workflow can finish after the wall-clock deadline, bounded by the remaining per-request timeout and sequence limits.
+
+## 0.9.0a1 - Reproducible stateful evidence (alpha)
+
+- Add a versioned five-case synthetic corpus: declared volatile-ID control, cart total drift, stateful read-ordering defect, idempotency/retry defect, and a reset-health guard that must block a stale target.
+- Add `python benchmarks/verify_stateful_corpus.py` to check pinned fixture hashes, validate the corpus and project schemas, execute expected cases, inspect safe difference pointers, prove minimization preserves a named mismatch, export/replay a pack, and reject tampering.
+- Add value-free per-step explanations with status/content-type metadata, the active comparison contract rules, and bounded safe JSON Pointer paths instead of duplicate field values.
+- Expand CI to Linux/Python 3.11, 3.12 and 3.13 plus Windows/Python 3.11; upload synthetic corpus evidence as a GitHub Actions artifact.
+- Keep schema validation in the optional `test` extra; the core library remains dependency-free.
+
+This remains an alpha. The corpus is a deterministic correctness fixture, not a performance benchmark or an indication of coverage-guided testing. The synthetic API does not model distributed state, real databases, or concurrent payment processing.
+
+## 0.8.0a1 - Verifiable stateful regression workflows (alpha)
+
+- Add an optional versioned reset-health contract to stateful sequences. After every configured reset, TwinCheck makes a separate read-only GET request and checks explicit scalar JSON Pointer assertions on both local targets before running the tested workflow.
+- Record whether reset checking was status-only or assertion-verified. Health summaries retain assertion paths and pass/fail metadata, not observed response values.
+- Add explicit `depends_on` metadata to stateful steps and reject dependencies that are duplicated, implicit, unknown, or ordered after their consumer.
+- Prevent the bounded adjacent-swap explorer from deliberately reversing directly declared dependencies.
+- Add a versioned synthetic stateful regression corpus, a broken-reset negative control, and reproducibility instructions.
+- Add regression coverage for a reset endpoint that returns 200 without clearing state and for invalid dependency ordering.
+
+This remains an alpha. A health contract verifies only the declared assertions, not all hidden state. Loopback-only HTTP targeting is not a sandbox. Instrumented coverage, dynamically generated mutation operators, and broad real-world benchmarking remain future work.
+
+## 0.7.0a1 - Portable stateful regression packs (alpha work in progress)
+
+- Add `export-http-sequence-pack` to save one stateful finding as a regression pack containing the request sequence, optional reset workflow, and pinned compatibility contract.
+- Add `replay-http-sequence-pack` to replay the pack against explicit loopback targets, with reset-before-repeat behavior and a required side-effect acknowledgement.
+- Exclude response traces and request-header values from pack contents; provide authentication headers only at replay time.
+- Verify file and canonical hashes before replay and refuse to overwrite existing export destinations.
+- Add regression tests and a versioned pack-manifest schema.
+
+This remains an alpha. A successful reset status cannot prove all hidden service state was cleared. Use disposable local services and synthetic data. GitHub publication and the complete Python-version CI matrix remain pending verification.
+
+## 0.6.0a1 - Feedback-guided stateful exploration
+
+- Add value-free response-branch signatures using HTTP status, content type and JSON response shape, plus adjacent transition fingerprints.
+- Execute the baseline first, then prioritize a seeded bounded candidate queue using uncovered mutation features, category balance and steps that recently exposed new response behavior.
+- Record per-case priority scores/reasons, novel response branches/transitions, difference signatures and aggregate coverage counts in exploration reports.
+- Extend minimization from step deletion to structural JSON shrinking (remove fields/items) and scalar simplification, with the same reset-backed failure-preservation check and a shared trial budget.
+- Keep normal stateful comparison reports unchanged unless coverage capture is explicitly requested by the exploration engine; signatures do not store response values.
+- Document the feedback model and its limits; bump alpha version to `0.6.0a1`.
+
+This remains an alpha. The scheduler ranks a bounded pre-generated candidate pool; it does not synthesize arbitrary mutations from runtime traces. Response-shape fingerprints are not code coverage, and reset success still depends on the user's reset workflow actually clearing the relevant state.
+
+## 0.5.0a1 - Transition-aware stateful workflow exploration
+
+- Add `explore-http-sequence` to generate reproducible JSON body boundary variants, adjacent step reorderings, step removals, and duplicate-step transitions.
+- Require a user-authored reset workflow for every test variant and minimization trial; stop before the candidate workflow if either target's reset step fails or is not 2xx.
+- Add bounded step-level delta debugging that preserves a selected mismatch category at the same named step.
+- Store the mutation metadata, reset workflow definition and hashes, and minimized sequence so findings can be replayed with `replay-http-sequence`.
+- Allow ordinary `compare-http-sequence` runs to opt into reset-before-repeat semantics.
+- Extend test services, CLI validation, examples and regression coverage for deterministic exploration and faithful replay.
+
+This is still an alpha. The reset endpoint is user-defined and trusted; a 2xx response cannot prove a service has fully reset. The mutator only explores the documented set of local mutations, and minimization removes steps rather than minimizing individual values. Run only against loopback test services using synthetic data.
+
+## 0.4.0a1 - Stateful HTTP compatibility workflows
+
+- Add `compare-http-sequence` for bounded, user-authored multi-request workflows against two loopback HTTP implementations.
+- Support response-value capture using JSON Pointer and safe interpolation into later request paths and JSON bodies.
+- Preserve independent cookie jars within each target workflow and reset the jars between repeats; redirects remain disabled and proxy environment variables are ignored.
+- Include source and canonical sequence hashes, source workflow definition, request-body hashes, per-step observations, and pinpointed differences in reports.
+- Add `replay-http-sequence` for replaying a saved finding against explicitly supplied loopback targets; require `--allow-side-effects` and preserve the original compatibility contract.
+- Add an example cart service, workflow and contract; add validation, capture, cookie, mismatch and replay tests.
+
+This is an alpha milestone. The workflow is authored explicitly; TwinCheck does not automatically discover state transitions. Request bodies and response observations are part of failure evidence, so workflows must not contain real secrets or customer data. The adapter is not a sandbox.
+
+## 0.3.0a1 - Structured inputs and local HTTP adapter
+
+- Add deterministic JSON Schema-guided request generation, including local JSON Pointer `$ref`, objects, arrays, enums/constants, common scalar constraints, and fail-closed diagnostics for unsupported validation keywords.
+- Add `twincheck compare --schema` to drive existing command-line targets with schema-generated JSON inputs and record schema SHA-256 provenance.
+- Add `twincheck compare-http` to compare two loopback HTTP implementations using schema-generated JSON request bodies.
+- Compare HTTP status, JSON response bodies, and `content-type` by default; allow an explicit response-header allowlist and use the existing versioned compatibility contract for JSON Pointer ignores.
+- Keep request header values out of reports, reject non-loopback HTTP targets, and add runnable quote-API examples.
+- Add schema generator and HTTP adapter tests; no runtime dependencies added.
+
+This is an alpha increment. JSON Schema generation implements a documented subset rather than the full specification. HTTP mode currently uses a fixed path and request JSON body; it is not a security sandbox or a general network scanner.
+
+## 0.2.0a1 - Development alpha
+
+- Add repeated-run instability detection with per-run evidence for findings.
+- Add bounded output retention using file-backed capture and output-limit reporting.
+- Add `twincheck replay` to rerun a finding's exact input using explicitly supplied commands.
+- Add JUnit XML export with one testcase per executed input.
+- Add a versioned JSON Schema for evidence reports.
+- Expand README, architecture, threat-model, design-decision and benchmark documentation.
+- Make the default per-process timeout more tolerant for slower machines and CI.
+
+This remains an alpha: the runner is not a sandbox, performance has not been benchmarked against mature fuzzing tools, and broad protocol/binary adapters are not implemented.
+
+## 0.1.0 - Initial prototype
+
+- Add deterministic input generation for mixed, text, integer and JSON-like inputs.
+- Add shell-free CLI execution with stdin and `{input}` argument support.
+- Compare stdout, stderr, exit code, and timeout behavior.
+- Add bounded delta-debugging input minimization.
+- Add JSON reports, examples, standard-library tests, CI and project documentation.

twincheck-0.12.0a1/CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Code of Conduct
+
+## Our commitment
+
+The TwinCheck community aims to be welcoming, respectful and constructive. We want participation to be safe and productive for people with different backgrounds, experience levels and perspectives.
+
+## Expected behavior
+
+- Be respectful and considerate in discussions and reviews.
+- Give and receive constructive feedback gracefully.
+- Focus criticism on ideas, code and behavior rather than people.
+- Acknowledge mistakes, learn from them and help repair their impact.
+- Respect different viewpoints and experiences.
+- Keep discussions relevant and professional.
+
+## Unacceptable behavior
+
+- Harassment, intimidation, discrimination or personal attacks.
+- Sexualized language or unwelcome sexual attention.
+- Insults, demeaning comments or deliberate disruption.
+- Publishing another person's private information without permission.
+- Threats, stalking or sustained unwanted contact.
+- Other conduct that would reasonably make participation unsafe or hostile.
+
+## Scope
+
+This Code of Conduct applies in project spaces, including issues, pull requests, discussions, reviews and project-related events or communications. It also applies when someone is representing the project in public.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, report it privately to the project maintainers through GitHub. Do not include private information in a public issue. Reports will be handled as confidentially as practical.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing this Code of Conduct. They may remove or edit comments, reject contributions, temporarily restrict participation, or permanently exclude someone from project spaces when necessary.
+
+Maintainers will consider the nature and impact of the behavior, relevant context and any prior pattern. People asked to stop unacceptable behavior are expected to comply immediately.
+
+## Attribution
+
+This policy is adapted from the Contributor Covenant, version 2.1:
+
+https://www.contributor-covenant.org/version/2/1/code_of_conduct/

twincheck-0.12.0a1/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to TwinCheck
+
+Thanks for helping improve TwinCheck. The project prioritizes reproducible findings, small understandable changes and honest statements about limitations.
+
+## Before opening an issue
+
+- Search existing issues for duplicates.
+- Include TwinCheck version, Python version, operating system, a minimal command, the seed and a sanitized report when possible.
+- Remove credentials, personal data, proprietary inputs and confidential logs before sharing traces.
+
+## Development setup
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m pip install --upgrade build twine
+python -m build --outdir dist
+python scripts/verify_distribution.py --dist-dir dist
+```
+
+The distribution check validates the built wheel and source archive, then installs the wheel into a temporary environment outside the checkout and exercises the CLI entry point. No runtime dependencies are required. Keep the test suite runnable with the Python standard library wherever practical.
+
+## Pull request expectations
+
+1. Describe the behavior changed and why it matters.
+2. Add a regression test for bug fixes.
+3. Keep the same seed reproducible and avoid using process-global random state.
+4. Preserve the principle that reports contain executed evidence, not guessed explanations.
+5. Update docs and the roadmap when behavior or scope changes.
+6. Do not introduce network activity or API keys into the core engine.
+
+## Code style
+
+Follow standard Python conventions, add types for public interfaces, keep functions focused, and prefer clear error messages over silent fallback. Do not broaden permissions or use `shell=True` to make a command work.
+
+## Release and compatibility policy
+
+Before changing CLI flags, report schemas or file formats, read [the release and compatibility policy](docs/release-process.md). TwinCheck is pre-1.0: the Python import API is not stable, and changes to documented interfaces must be reflected in the changelog and relevant schema/version notes. The manual release-candidate workflow builds and verifies artifacts; it intentionally does not publish packages.
+
+## Security-sensitive changes
+
+Please read [SECURITY.md](SECURITY.md). Do not run unknown submissions locally. TwinCheck currently executes target commands using the user's privileges and is not a sandbox.

twincheck-0.12.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TwinCheck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

twincheck-0.12.0a1/MANIFEST.in

@@ -0,0 +1,15 @@
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include SECURITY.md
+include LICENSE
+include pyproject.toml
+
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include scripts *.py
+recursive-include docs *.md *.json
+recursive-include examples *.md *.json
+recursive-include benchmarks *.md *.py *.json
+

twincheck-0.12.0a1/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: twincheck
+Version: 0.12.0a1
+Summary: Reproducible evidence-first differential testing with portable stateful regression workflows.
+Author: TwinCheck contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ArnabIITP/twincheck
+Project-URL: Repository, https://github.com/ArnabIITP/twincheck
+Project-URL: Issues, https://github.com/ArnabIITP/twincheck/issues
+Project-URL: Documentation, https://github.com/ArnabIITP/TwinCheck/blob/main/docs/quickstart.md
+Project-URL: Changelog, https://github.com/ArnabIITP/TwinCheck/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/ArnabIITP/TwinCheck/blob/main/SECURITY.md
+Keywords: differential-testing,black-box-testing,compatibility-testing,api-compatibility,fuzzing,regression-testing,counterexample-minimization,stateful-testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: jsonschema<5,>=4.21; extra == "test"
+Dynamic: license-file
+
+<div align="center">
+
+# TwinCheck
+
+**Evidence-first differential testing for software compatibility.**
+
+Give TwinCheck a reference implementation and a candidate replacement. It runs both against the same reproducible inputs, compares their observable behavior, and turns differences into evidence you can replay and use in regression testing.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/ArnabIITP/TwinCheck/ci.yml?branch=main&label=CI)](https://github.com/ArnabIITP/TwinCheck/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Project status: alpha](https://img.shields.io/badge/status-alpha-orange)](CHANGELOG.md)
+
+</div>
+
+> **Alpha software.** TwinCheck is actively developed and its CLI and file formats may evolve before 1.0. It is a testing tool, not a proof of program equivalence, a production monitoring system, or a security sandbox. The first PyPI alpha release is being prepared. Until it is published, use the source installation instructions below. After publication, install the pinned alpha with `python -m pip install twincheck==0.12.0a1`.
+
+## Why TwinCheck?
+
+A replacement can pass its unit tests and still behave differently from the system it is meant to replace. Differences may appear in edge cases, error handling, whitespace, status codes, response bodies, session state, or sequences of operations.
+
+TwinCheck helps investigate that compatibility gap by comparing two implementations as black boxes. It does not need access to their source code or require them to use the same programming language.
+
+Typical use cases include:
+
+- Replacing a legacy command-line tool with a new implementation.
+- Porting a parser, formatter, or data-processing utility.
+- Checking whether two local API implementations behave consistently.
+- Testing a migration before switching traffic or removing the old implementation.
+- Preserving a discovered mismatch as a replayable regression case.
+
+## Get started
+
+**Requirements:** Python 3.11 or newer.
+
+Clone the repository and install the project in editable mode:
+
+```bash
+git clone https://github.com/ArnabIITP/TwinCheck.git
+cd TwinCheck
+python -m pip install -e .
+```
+
+Create a directory for the report files, then run the included command-line example:
+
+```bash
+mkdir -p reports
+twincheck compare \
+  --reference "python examples/reference.py" \
+  --candidate "python examples/candidate.py" \
+  --strategy text \
+  --cases 8 \
+  --seed 7 \
+  --minimize \
+  --max-minimization-trials 8 \
+  --output reports/demo.json \
+  --junit reports/demo-junit.xml
+```
+
+The example candidate deliberately differs from the reference. TwinCheck should report a mismatch and exit with status `1`. That nonzero exit is intentional: a detected difference can fail a CI job. The JSON report contains the executed input and observations; the JUnit file can be consumed by CI test-report tools.
+
+For a complete walkthrough, see the **[Quick-start guide](docs/quickstart.md)**.
+
+## What TwinCheck can do today
+
+| Area | Current capability |
+| --- | --- |
+| Command-line comparison | Run two commands without a shell, passing the same input through stdin or an argv placeholder |
+| Input generation | Seeded text, integer-boundary, JSON-shaped and documented JSON Schema-subset generation |
+| Known corpora | Replay UTF-8 corpus files in stable path order before generated cases |
+| Behavioral observations | Compare stdout, stderr, exit status, timeout behavior, output truncation and repeated-run instability |
+| Compatibility contracts | Choose exact or structural JSON comparison, ignore selected JSON Pointer paths, and configure exit-code/timeout comparison |
+| Local HTTP comparison | Send matching JSON requests to two loopback services and compare status, selected headers and response bodies |
+| Stateful HTTP workflows | Run ordered multi-request workflows with independent cookies, response-value capture, reset checks and bounded exploration |
+| Failure minimization | Reduce stable mismatches using bounded delta debugging |
+| Replay and regression evidence | Save JSON reports, export portable counterexample packs, and replay findings against explicitly supplied targets |
+| CI reporting | Produce human-readable summaries, JSON evidence and JUnit XML |
+| Python API | Versioned API v1 for command-line comparison, contracts and report helpers |
+
+The implementation is deliberately bounded. See [current limitations](docs/roadmap.md) and the [release and compatibility policy](docs/release-process.md) before relying on it in automation.
+
+## How it works
+
+1. **Choose two targets.** Provide the reference and candidate commands, or two local HTTP service URLs.
+2. **Define the comparison.** Use defaults or a versioned compatibility contract to specify which observations matter.
+3. **Generate or provide inputs.** Set a seed and optionally provide a corpus or supported JSON Schema.
+4. **Execute both targets.** TwinCheck runs matching cases and records observable behavior.
+5. **Inspect differences.** Findings include the input, observations, comparison metadata and provenance.
+6. **Minimize and replay.** Where supported, shrink stable mismatches and preserve them as regression evidence.
+
+```mermaid
+flowchart TD
+    A[Seed, strategy, schema or corpus] --> B[Reproducible inputs]
+    B --> C[Reference implementation]
+    B --> D[Candidate implementation]
+    C --> E[Compare observations]
+    D --> E
+    E --> F{Difference observed?}
+    F -- No --> G[Record completed case]
+    F -- Yes --> H[Evidence report]
+    H --> I[Optional bounded minimization]
+    I --> J[Replayable regression evidence]
+    G --> K[Run summary]
+    J --> K
+```
+
+A clean run means only that no difference was observed in the cases executed under the selected comparison policy. It does **not** establish equivalence for all possible inputs.
+
+## Examples
+
+### Compare command-line programs
+
+```bash
+twincheck compare \
+  --reference "python reference.py" \
+  --candidate "python replacement.py" \
+  --strategy mixed \
+  --cases 500 \
+  --seed 42 \
+  --repeat 2 \
+  --timeout 5 \
+  --max-output-bytes 1000000 \
+  --minimize \
+  --output reports/compatibility.json \
+  --junit reports/compatibility.xml
+```
+
+Inputs can be supplied through stdin or a `{input}` argument placeholder. Commands are launched without invoking a shell. See the [CLI guide](docs/quickstart.md#command-line-comparison) for more options.
+
+### Compare local HTTP implementations
+
+Start two local example services:
+
+```bash
+python examples/http_service.py --port 8001 --delta 0
+python examples/http_service.py --port 8002 --delta 1
+```
+
+In another terminal:
+
+```bash
+twincheck compare-http \
+  --reference-url http://127.0.0.1:8001 \
+  --candidate-url http://127.0.0.1:8002 \
+  --path /quotes \
+  --method POST \
+  --schema examples/schemas/quote-request-v1.json \
+  --contract examples/contracts/http-api-v1.json \
+  --cases 25 \
+  --seed 42 \
+  --output reports/http-compatibility.json
+```
+
+HTTP targets are restricted to loopback addresses. This adapter is intended for local test services, not remote API scanning.
+
+### Compare stateful API workflows
+
+TwinCheck can execute a user-authored sequence such as create a cart, add an item, and read the cart back. It keeps reference and candidate cookies separate, supports scalar response capture for later requests, and can apply a user-defined reset workflow with explicit health assertions.
+
+See the [stateful workflow walkthrough](docs/quickstart.md#stateful-http-workflow) and the checked-in [sequence examples](examples/sequences/).
+
+## Python API
+
+The supported Python API v1 covers command-line comparisons, compatibility contracts and report helpers:
+
+```python
+import shlex
+import sys
+
+from twincheck import compare_commands, write_json_report
+
+report = compare_commands(
+    shlex.join([sys.executable, "reference.py"]),
+    shlex.join([sys.executable, "replacement.py"]),
+    cases=100,
+    seed=42,
+)
+
+write_json_report("reports/compatibility.json", report)
+```
+
+Only documented exports are covered by API v1. Stateful HTTP comparison and exploration are currently CLI features. Read the [Python API reference](docs/python-api.md) and [compatibility policy](docs/release-process.md).
+
+## Benchmarks and evidence
+
+The repository includes pinned, synthetic compatibility corpora for cart and booking/reservation workflows. Their fixtures, schemas and expected outcomes are versioned so that results can be reproduced.
+
+These are **synthetic validation fixtures**, not independent real-world benchmarks. They do not establish a general detection rate, performance advantage, or production readiness. See the [benchmark protocol](benchmarks/README.md).
+
+## Safety and data handling
+
+TwinCheck is **not a sandbox**. It launches configured commands with the permissions of the current user. A target can access files, use the network, spawn processes and consume resources available to that user. Run only commands and services you trust and are authorized to test.
+
+Reports, replay artifacts and workflow definitions can contain failing inputs and service observations. Treat them as potentially sensitive. Use synthetic data where possible and review evidence before sharing it. See [SECURITY.md](SECURITY.md) for the project's security boundaries and vulnerability reporting guidance.
+
+## Documentation
+
+- [Quick start and CLI walkthrough](docs/quickstart.md)
+- [Python API v1](docs/python-api.md)
+- [JSON Schema generation support](docs/schema-generation.md)
+- [Stateful HTTP sequence format](docs/stateful-http-sequence-v1.schema.json)
+- [Benchmark protocol and limitations](benchmarks/README.md)
+- [Release and compatibility policy](docs/release-process.md)
+- [Architecture and design](docs/architecture.md)
+- [Roadmap and known limitations](docs/roadmap.md)
+- [Security policy](SECURITY.md)
+- [Contributing guide](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Changelog](CHANGELOG.md)
+
+## Development
+
+Install the optional test dependency and run the suite:
+
+```bash
+python -m pip install -e ".[test]"
+python -m unittest discover -s tests -v
+```
+
+Build and verify distributable artifacts:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build --outdir dist
+python scripts/verify_distribution.py --dist-dir dist
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development expectations and [docs/release-process.md](docs/release-process.md) for release validation.
+
+## Contributing
+
+Bug reports, reproducible examples, documentation improvements and focused pull requests are welcome. Please remove credentials, customer information and proprietary data from reports before sharing them.
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md), review open [issues](https://github.com/ArnabIITP/TwinCheck/issues), and use the issue templates when reporting a problem.
+
+## License
+
+TwinCheck is released under the [MIT License](LICENSE).