interaction-check 0.1.0a6__tar.gz

interaction_check-0.1.0a6/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0a6 / v0.1.0-alpha.6 — unpublished candidate
+
+- Prepare PyPI metadata, installation instructions and a manual Trusted Publishing
+  workflow. Its default mode builds and checks packages without uploading them.
+- Publish only from a matching version tag, with separate build and upload jobs.
+- CLI/report version advances to `0.1.0a6`; schema 1, protocol 1 and runtime behavior
+  are unchanged from alpha.5. Existing GitHub archives and tags remain unchanged.
+
+## 0.1.0a5 / v0.1.0-alpha.5
+
+- Export each state-mismatch prefix with `--failure-dir`, without replacing expected
+  states or overwriting an existing output directory. JSON reports link to saved files.
+- Add a native-test handoff guide using the executable pyee and XState examples.
+- Add wheel/sdist packaging and the `interaction-check` command, with zero runtime
+  dependencies. `--version` works without an adapter. Python metadata/report versions
+  now use the standard Python spelling `0.1.0a5` (previous report: `0.1.0-alpha.4`).
+- Schema 1, JSONL protocol 1, comparison rules and adapter commands are unchanged.
+
+Published as a GitHub prerelease on 26 October 2026; not published on PyPI.
+See the [alpha compatibility policy](docs/RELEASING.md#alpha-compatibility) before upgrading.

interaction_check-0.1.0a6/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

interaction_check-0.1.0a6/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PerchAnton
+
+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.

interaction_check-0.1.0a6/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md PACKAGE.md CHANGELOG.md LICENSE-MIT LICENSE-APACHE
+include test_*.py
+include tools/check_distribution.py
+include docs/NATIVE_TESTS.md docs/RELEASING.md

interaction_check-0.1.0a6/PACKAGE.md

@@ -0,0 +1,47 @@
+# interaction-check
+
+A small Python command-line tool that replays semantic JSON event sequences against
+an explicitly selected local adapter. Python 3.10+; **zero runtime dependencies**.
+Licensed under MIT OR Apache-2.0. Experimental alpha: formats and CLI may still change.
+
+## Installation
+
+Install a published copy of this prerelease from PyPI:
+
+```sh
+python -m pip install 'interaction-check==0.1.0a6'
+```
+
+An exact version selects this prerelease without opting into all future prereleases.
+Use a virtual environment. On Windows, the same command works with `py -m pip`.
+For other distribution options and current publication status, see the
+[project README](https://github.com/PerchAnton/interaction-check#install-the-released-command).
+
+## Usage
+
+```sh
+interaction-check --version
+interaction-check --failure-dir failures --trace --report report.json scenario.json -- path/to/adapter
+```
+
+The adapter is a trusted program you select; it receives events as JSONL and returns
+states. Expected states are never sent to it. Each scenario starts a fresh process.
+The runner is not a sandbox and does not download or discover adapters automatically.
+
+`--failure-dir` creates a **new** directory containing numbered JSON scenarios through
+the first state mismatch. Expectations stay unchanged. These are checked prefixes, not
+automatically minimized or independently verified reproductions. Re-run an export with
+the same adapter revision. Crashes, timeouts and malformed protocol replies do not
+produce a guessed state-mismatch scenario.
+
+The installed wheel contains the runner and its licenses. Examples and application
+adapters remain in the repository and may have their own dependencies. The separate
+Rust library edit-session is not required.
+
+- [Scenario and adapter protocol](https://github.com/PerchAnton/interaction-check#scenario-format)
+- [Worked XState example](https://github.com/PerchAnton/interaction-check/tree/main/examples/xstate)
+- [Moving a useful scenario into a native test](https://github.com/PerchAnton/interaction-check/blob/main/docs/NATIVE_TESTS.md)
+- [Measured benefits and costs](https://github.com/PerchAnton/interaction-check/blob/main/docs/VALUE.md)
+
+If a normal project test is simpler, keep that test. Replay is useful when sharing an
+event sequence and a consistent report earns the adapter and runner maintenance cost.

interaction_check-0.1.0a6/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: interaction-check
+Version: 0.1.0a6
+Summary: Replay semantic event sequences against explicit local adapters
+Author: PerchAnton
+License-Expression: MIT OR Apache-2.0
+Project-URL: Repository, https://github.com/PerchAnton/interaction-check
+Project-URL: Documentation, https://github.com/PerchAnton/interaction-check#readme
+Project-URL: Issues, https://github.com/PerchAnton/interaction-check/issues
+Project-URL: Changelog, https://github.com/PerchAnton/interaction-check/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE-MIT
+License-File: LICENSE-APACHE
+Dynamic: license-file
+
+# interaction-check
+
+A small Python command-line tool that replays semantic JSON event sequences against
+an explicitly selected local adapter. Python 3.10+; **zero runtime dependencies**.
+Licensed under MIT OR Apache-2.0. Experimental alpha: formats and CLI may still change.
+
+## Installation
+
+Install a published copy of this prerelease from PyPI:
+
+```sh
+python -m pip install 'interaction-check==0.1.0a6'
+```
+
+An exact version selects this prerelease without opting into all future prereleases.
+Use a virtual environment. On Windows, the same command works with `py -m pip`.
+For other distribution options and current publication status, see the
+[project README](https://github.com/PerchAnton/interaction-check#install-the-released-command).
+
+## Usage
+
+```sh
+interaction-check --version
+interaction-check --failure-dir failures --trace --report report.json scenario.json -- path/to/adapter
+```
+
+The adapter is a trusted program you select; it receives events as JSONL and returns
+states. Expected states are never sent to it. Each scenario starts a fresh process.
+The runner is not a sandbox and does not download or discover adapters automatically.
+
+`--failure-dir` creates a **new** directory containing numbered JSON scenarios through
+the first state mismatch. Expectations stay unchanged. These are checked prefixes, not
+automatically minimized or independently verified reproductions. Re-run an export with
+the same adapter revision. Crashes, timeouts and malformed protocol replies do not
+produce a guessed state-mismatch scenario.
+
+The installed wheel contains the runner and its licenses. Examples and application
+adapters remain in the repository and may have their own dependencies. The separate
+Rust library edit-session is not required.
+
+- [Scenario and adapter protocol](https://github.com/PerchAnton/interaction-check#scenario-format)
+- [Worked XState example](https://github.com/PerchAnton/interaction-check/tree/main/examples/xstate)
+- [Moving a useful scenario into a native test](https://github.com/PerchAnton/interaction-check/blob/main/docs/NATIVE_TESTS.md)
+- [Measured benefits and costs](https://github.com/PerchAnton/interaction-check/blob/main/docs/VALUE.md)
+
+If a normal project test is simpler, keep that test. Replay is useful when sharing an
+event sequence and a consistent report earns the adapter and runner maintenance cost.

interaction_check-0.1.0a6/README.md

@@ -0,0 +1,281 @@
+# interaction-check
+
+Replay a semantic event sequence and inspect each checked state. A standalone Python
+development tool that uses an explicit local adapter. It can test consumers with or
+without the separate [edit-session](https://github.com/PerchAnton/edit-session) Rust library.
+
+[![CI](https://github.com/PerchAnton/interaction-check/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/PerchAnton/interaction-check/actions/workflows/ci.yml)
+[![Replay evidence](https://github.com/PerchAnton/interaction-check/actions/workflows/evidence.yml/badge.svg?branch=main&event=push)](https://github.com/PerchAnton/interaction-check/actions/workflows/evidence.yml)
+
+**[Download](#current-prerelease)** · **[Install](#install-the-released-command)** · **[Export a failure](#export-a-failure-and-keep-a-native-test)** · **[Evidence](#evidence-and-trade-offs)** · **[License](#license)**
+
+## Current prerelease
+
+**[v0.1.0-alpha.5](https://github.com/PerchAnton/interaction-check/releases/tag/v0.1.0-alpha.5) · released 26 October 2026 · Python 3.10+**
+
+**[Download the wheel](https://github.com/PerchAnton/interaction-check/releases/download/v0.1.0-alpha.5/interaction_check-0.1.0a5-py3-none-any.whl)** · [Source archive](https://github.com/PerchAnton/interaction-check/releases/download/v0.1.0-alpha.5/interaction_check-0.1.0a5.tar.gz) · [SHA-256 checksums](https://github.com/PerchAnton/interaction-check/releases/download/v0.1.0-alpha.5/SHA256SUMS) · [Changelog](CHANGELOG.md)
+
+![interaction-check alpha 5, released 26 October 2026: 0 runtime dependencies, 49 runner tests, 12.6 KiB wheel. Replay a scenario, export its original expectations through the first mismatch, and manually translate useful behavior into a native test.](docs/assets/release.svg)
+
+Release snapshot: **49 runner tests**, **0 runtime dependencies**, **12.6 KiB wheel
+(12,937 bytes)**. [Exact files, hashes and release CI](docs/evidence/release-alpha5.json).
+These are dated release facts; the CI badges above track current main. The handoff is
+manual, and an export must be replayed before sharing. Examples and adapters are separate.
+
+Trying the alpha? [Report a bug](https://github.com/PerchAnton/interaction-check/issues/new?template=bug_report.yml)
+with your runner and adapter versions, or read the [alpha compatibility policy](docs/RELEASING.md#alpha-compatibility).
+
+## Install the released command
+
+**PyPI candidate: `0.1.0a6` (not published yet).** The [publishing guide](docs/RELEASING.md#registry-publication)
+records the remaining account setup and verification. After publication, installation
+will be `python -m pip install 'interaction-check==0.1.0a6'` in a virtual environment.
+Until then, use the existing GitHub release below.
+
+Download the wheel above, then run these commands in its directory:
+
+```sh
+python -m venv .venv
+.venv/bin/python -m pip install ./interaction_check-0.1.0a5-py3-none-any.whl
+.venv/bin/interaction-check --version
+```
+
+On Windows use `.venv\Scripts\python.exe` and `.venv\Scripts\interaction-check.exe`.
+For a source checkout, use `python -m pip install .` inside your virtual environment.
+The installed command uses Python version spelling `0.1.0a5`. Packages are available
+from GitHub Releases; there is no PyPI publication. Start with the
+[XState walkthrough](examples/xstate/README.md) or the [native-test guide](docs/NATIVE_TESTS.md).
+
+## Evidence and trade-offs
+
+<details>
+<summary>Open measured results, comparisons and sources</summary>
+
+![interaction-check evidence: zero third-party Python packages; 49 runner and six Node tests pass; PdfCraft passes ten scenarios and 79 steps. The focused XState install has one lockfile package entry versus 120 in the earlier bundle. Native tests have a 74.6 ms median and replay 183.9 ms across 30 paired samples; replay is slower in this pilot.](docs/assets/overview.svg)
+
+### The numbers behind the overview
+
+Evidence snapshot: **26 October 2026**. CI badges are live; the graphic and counts are
+dated results. The runner count includes eight alpha 5 export/CLI tests; Node,
+PdfCraft and timing figures retain their earlier 26 October evidence. Package counts describe the example installation; timings describe the
+same three example scenarios on one macOS arm64 machine.
+
+| Measure | Recorded result | Source and scope |
+| --- | --- | --- |
+| Runner Python dependencies | **0 third-party packages** | [Runner source](interaction_check.py); adapters have their own requirements |
+| Verification tests | **49 Python + 6 Node pass** | [Runner checks](docs/VALIDATION.md), [native example tests](examples/xstate/native.test.mjs), [adapter tests](examples/xstate/adapter.test.mjs) |
+| Real PdfCraft replay | **10 scenarios / 79 steps pass** | [State report](docs/evidence/pdfcraft-alpha4.json); real widgets and engine, proposed integration |
+| Focused XState installation | **120 → 1 package entries; −99.2%** | [Lockfile comparison](docs/VALUE.md#a-smaller-installation-for-one-example); excludes unrelated examples and formatter; XState is unchanged |
+| Median / p95 execution time | **Native: 74.6 / 80.5 ms; replay: 183.9 / 191.9 ms** | [30 paired samples](docs/evidence/xstate.json), [method](docs/VALUE.md#measured-execution-overhead); startup included, install and JSON report writes excluded |
+| Controlled example mutations | **3/3 detected by both methods** | [Three deliberate defects](docs/VALUE.md#does-it-detect-wrong-behavior); not upstream bugs or a general coverage score |
+
+Replay is **2.46× slower** in this small pilot. Its value is a shareable trace and common
+failure report. Native tests also need only XState; fewer total lines of code or faster
+application behavior are not demonstrated.
+
+**Experimental, 0.1.0a5 (alpha 5).** Maintained by [PerchAnton](https://github.com/PerchAnton).
+No PyPI release or upstream adoption is claimed. The first adapter uses a fixed
+edit-session revision and commits through PhotoCraft's actual `Session` command API;
+consumer-owned adapters also exercise the real PhotoCraft and PdfCraft dialogs.
+
+</details>
+
+## A useful outcome can be one native test
+
+![Pyee native test audit: unchanged source passes 53 original tests or 54 with the candidate. A deliberate remove-after-callback mutation passes the original 53 tests but fails the new reentrant-once test. No current upstream bug or adoption is claimed.](docs/assets/pyee-coverage.svg)
+
+Following [maintainer feedback](https://github.com/jfhbrook/pyee/issues/226#issuecomment-6409488443),
+we checked the full pyee suite and translated one external trace into a native pytest
+candidate. On the pinned source: **53/53 existing tests pass; 54/54 with the candidate**.
+One deliberate local mutation escapes the original suite but is caught by the added test.
+The candidate needs **no new dependency** in pyee and no interaction-check runner.
+
+[Test, method, raw results and reproduction](examples/pyee/README.md).
+This is one demonstrated coverage gap, not a current pyee bug, a general coverage score
+or upstream adoption. These are pyee suite counts, separate from our 49 runner tests.
+
+## Start with one reviewable reproduction
+
+The [XState walkthrough](examples/xstate/README.md) includes three small traces, the
+expected state after every event and a failure you can reproduce. Its focused install
+contains **1 npm package instead of the 120 entries in our earlier multi-consumer
+lockfile**. The Python runner itself still uses only the standard library.
+
+Use `--trace --report result.json` to retain each checked event, expectation and actual
+state. A failing report includes the checked prefix and the first mismatching state.
+This makes a regression report readable before someone runs the reproduction.
+
+[Measured value and trade-offs](docs/VALUE.md) includes native tests, source counts,
+30 paired timing samples and three controlled mutations. Both test paths detect all
+three mutations; native tests are shorter and faster here. The reason to choose replay
+is a shareable trace and common report format. Upstream adoption remains unconfirmed.
+
+## Proposed PhotoCraft UI consumer
+
+[PhotoCraft PR #9190](https://github.com/storytold/photocraft/pull/9190) adds a PhotoCraft-owned
+adapter that drives the shipped Edit Selected Guides dialog, egui canvas/dialog frames, control
+field setter and real Session. Its CI fetches this runner at
+`f8d4282d61576ffe78d18553c642d215887e2d9f`; Python is not an application runtime dependency.
+[Ten scenarios / 44 steps](https://github.com/PerchAnton/photocraft/tree/46b4a183d5f44035bbc216dcf6196701bcb45bc9/tests/interactions/guide-edit)
+pass locally, covering preview, commit, Cancel/Escape, invalid input, no-ops and stale drafts.
+This consumer patch is awaiting maintainer review; upstream adoption is not claimed.
+
+## Proposed PdfCraft UI consumer
+
+[PdfCraft PR #4594](https://github.com/storytold/pdfcraft/pull/4594) uses this runner for **Document Properties**.
+Its runtime draft lifecycle uses edit-session; this runner checks the resulting UI and engine state.
+Description, Initial View and Custom values share a draft bound to document identity,
+edit generation and permissions. `check_live` rejects stale input after edits, Undo/Redo,
+reload or a document switch; the existing engine commits one atomic batch. Cancel,
+Escape and no-ops do not add history. Failed engine edits retain the form for correction.
+Clean inspection tabs retain their existing live refresh without rebasing typed input.
+
+The consumer owns a [real UI adapter](https://github.com/PerchAnton/pdfcraft/blob/535d990d10832baf3b0a64910c51b280c224bd5c/crates/ui-egui/examples/properties_scenarios.rs)
+and [10 scenarios / 79 steps](https://github.com/PerchAnton/pdfcraft/tree/535d990d10832baf3b0a64910c51b280c224bd5c/tests/interactions/document-properties),
+replayed by interaction-check, including save/reopen and preservation of custom metadata.
+Local scoped UI tests, strict Clippy, assets, parity and wasm checks pass. Both dependencies
+are pinned; upstream review of the source-policy exception and adoption is pending.
+See [reproduction instructions](https://github.com/PerchAnton/pdfcraft/blob/535d990d10832baf3b0a64910c51b280c224bd5c/docs/document-properties-sessions.md).
+
+## Run
+
+Requires Python 3.10+ (tested with Python 3.14 on macOS arm64).
+
+```sh
+python3 -m unittest -v
+cargo build --locked --manifest-path adapters/photocraft/Cargo.toml
+python3 interaction_check.py --report result.json --junit result.xml scenarios/photocraft/*.json -- \
+  adapters/photocraft/target/debug/edit-session-photocraft-probe
+```
+
+The Rust adapters need Rust 1.99+ (tested with 1.99.1). For the bundled PhotoCraft adapter,
+Cargo fetches both Rust repositories at fixed commits; no sibling checkout or path override is required.
+See the [adapter README](adapters/photocraft/README.md). Each scenario starts a fresh process. Exit 0
+means all scenarios passed and requested reports were written; 1 means a scenario or report
+write failed; invalid CLI usage exits 2.
+
+## Reports for CI
+
+Add `--trace` with `--report FILE` for per-step JSON evidence. Each entry has `step`
+(1-based), `event`, `expect`, `actual`, and `passed`; a mismatch also has `differences`.
+Only checked steps up to the first mismatch are included. Later events may already have
+executed: this is post-execution checking, not stop-on-first-failure execution. Malformed
+replies have no invented state; process crashes/timeouts do not produce a checked trace.
+The option does not change JSONL requests, default compact reports, or JUnit output.
+Reports include the event/state values chosen by the adapter; review them before sharing.
+
+`--report FILE` writes JSON and `--junit FILE` writes JUnit XML; either or both are optional.
+JUnit contains one test case per scenario, failure details and captured adapter stderr,
+including failed assertions, invalid replies, nonzero exits and timeouts. The Python API
+exposes these diagnostics as `CheckError.stderr`; JSON reports use `stderr`, and JUnit
+uses `system-err`. Scenario failures keep their declared name and source path in both formats. If the
+input cannot be parsed, its filename is used instead. A failed scenario does not prevent
+the remaining scenarios from running or the reports from being written.
+
+Each report is replaced atomically after a complete write. Create parent directories first.
+Report paths that refer to a scenario input or to the other report (including existing
+symlinks/hard links) are rejected before starting an adapter. Report write failures produce
+a diagnostic on stderr and exit 1, even when every scenario passed. Characters forbidden by
+XML 1.0 are replaced with U+FFFD in JUnit; the JSON report preserves the original strings.
+
+## Export a failure and keep a native test
+
+```sh
+python3 interaction_check.py --failure-dir failures --report report.json scenario.json -- path/to/adapter
+python3 interaction_check.py failures/0001.json -- path/to/adapter
+```
+
+`--failure-dir` creates a new directory and writes each failing scenario through its
+first state mismatch. It preserves expectations and metadata; JSON reports link to
+the saved files. Numbered filenames follow input order. Successful runs create no
+scenario files. Existing directories are refused to avoid mixing old and new failures.
+
+The export is a checked prefix, not an automatically minimized or rerun reproduction.
+Re-run it with the same adapter revision. Crashes, timeouts and protocol errors keep
+their diagnostics instead of exporting a guessed assertion failure. The
+[native-test guide](docs/NATIVE_TESTS.md) shows how to move useful pyee and XState
+behavior into the consumer's normal tests, without retaining a runner dependency.
+
+## Scenario format
+
+```json
+{
+  "schema": 1,
+  "name": "Cancel a preview without changing history",
+  "steps": [
+    {"event": {"op": "begin"}, "expect": {"undo_depth": 0, "error": null}},
+    {"event": {"op": "preview", "value": 0.5},
+     "expect": {"committed": 1, "preview": 0.5, "undo_depth": 0, "error": null}},
+    {"event": {"op": "cancel"},
+     "expect": {"committed": 1, "preview": null, "undo_depth": 0, "error": null}}
+  ]
+}
+```
+
+Each request is a JSON line with `protocol: 1`, an integer `id`, and `event`.
+The adapter returns exactly one JSON line per request with the same `protocol`/`id` and a
+`state` object, then exits at stdin EOF. Logs go to stderr. Expectations are never sent to
+the adapter. Objects match recursively by expected fields, including objects inside arrays.
+Arrays must have the same length and order; each element uses the same matching rules.
+Booleans are distinct from numbers. Missing fields are distinct from null.
+Non-finite numbers, duplicate keys, missing/extra replies, wrong IDs, adapter crashes,
+timeouts and malformed JSON fail the run.
+
+JSONL records are separated by LF (CRLF also works), with an optional final newline.
+Unicode line separators inside a JSON string are data, not record boundaries. Extra blank
+lines are invalid. Inputs and replies allow at most 64 nested objects/arrays and must use
+Unicode scalar values (no unpaired surrogates); malformed data fails with a diagnostic.
+
+The whole scenario's events are sent in order. The adapter must process them sequentially
+and finish each event before replying. This is semantic replay, not timed pointer playback.
+Use a custom adapter to translate events into `egui_kittest` interactions or an app protocol.
+
+## Existing tools and scope
+
+Keep `egui_kittest` for widget/accessibility/pixel tests, `teatest` for Bubble Tea, and
+`proptest` for input generation. This prototype adds a portable trace plus explicit assertions
+and a machine-readable report; it does not replace those tools or discover bugs by itself.
+
+The bundled engine-only PhotoCraft adapter drives real commands and history in a headless process. It does
+not connect to the live application's UI or test its renderer, saved files or native input.
+Upstream adoption is pending. The [PdfCraft adapter](adapters/pdfcraft/README.md) is owned
+by the consumer repository and also uses engine save/reopen. No Bubbles adapter,
+auto-recording or shrinking is implemented.
+
+Adapters are trusted local test programs, launched without a shell. A per-scenario timeout
+defaults to five seconds. Input is limited to 1 MiB. Stdin and output capture use temporary
+files so a non-reading adapter cannot block input delivery and logs do not grow in RAM.
+While the adapter runs, stdout and stderr sizes are checked about every 50 ms; either
+stream exceeding 1 MiB stops the adapter. A final check also catches fast-exiting writers.
+At most 1 MiB of stderr is retained in a failure report.
+
+Polling is not a hard disk quota: a fast writer can overshoot between checks. This is not
+a sandbox. Timeout, output-limit handling and cancellation stop and reap the direct
+adapter process, not a tree of spawned descendants. Adapters must manage their children.
+
+## Evidence
+
+- [PdfCraft UI report](reports/pdfcraft-properties.json): ten scenarios / 79 steps; see the
+  [adapter instructions](adapters/pdfcraft/README.md) for immutable source pins and replay.
+
+- [Alpha 2 review and regression checks](docs/VALIDATION.md): Unicode JSONL, report safety,
+  JUnit, bounded JSON nesting and compatibility with existing PhotoCraft adapters.
+- [Current PhotoCraft Session scenarios](photocraft-session-report.json): eight scenarios,
+  41 steps, using the published Git dependency and real command dispatch. Each step also
+  checks the command journal count, so previews and no-op commits cannot silently send edits.
+- [Earlier PhotoCraft component scenarios](photocraft-report.json): eight scenarios against
+  the original Document/History adapter, before switching to Session dispatch.
+- [Earlier deliberate mutation](mutation-report.json): expected failures after disabling context
+  protection in a temporary library copy. Stale-target and undo-back-to-original scenarios
+  detect a wrong document mutation/history change. A third scenario detects the changed error.
+- [Detailed validation](https://github.com/PerchAnton/edit-session/blob/main/docs/VALIDATION.md).
+
+The same runner now passes real UI scenarios in both proposed consumers. The next milestone
+is maintainer review of their behavior and dependency policy; this is not a claim of upstream adoption.
+
+## License
+
+Licensed under either the [MIT license](LICENSE-MIT) or the
+[Apache License, Version 2.0](LICENSE-APACHE), at your option.
+Unless explicitly stated otherwise, contributions submitted for inclusion are offered
+under the same dual license.