wireskein 0.0.1__tar.gz

wireskein-0.0.1/.gitignore

@@ -0,0 +1,20 @@
+corpus/raw/
+corpus/work/
+__pycache__/
+*.py[cod]
+.venv/
+research/boundary-bench/target/
+research/plugin-lang-bench/target*/
+research/plugin-lang-bench/wasm-plugin/target/
+research/plugin-lang-bench/build-*.log
+research/plugin-lang-bench/stderr-*.log
+research/plugin-lang-bench/results.jsonl
+research/zerocopy-bench/target/
+.cache/
+
+# packaging
+build/
+dist/
+*.egg-info/
+uv.lock
+.pytest_cache/

wireskein-0.0.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog / 変更履歴
+
+## Unreleased
+
+## 0.0.1
+- (EN) First beta. The prototype is now the `wireskein` package on PyPI (`pip install --pre wireskein`, Python 3.13+, numpy only). Public modules are `wireskein.runlog` (recording a test run, standard library only), `wireskein.verify` (checking a recorded run) and `wireskein.analyze` (decoding a capture, beta), with a `wireskein` command (`analyze`, `segments`, `verify`). The `wsproto` import and `prototype/ws.py` are gone; evaluation scripts moved to `research/` and are not packaged.
+- (JA) 最初のβ版。プロトタイプを PyPI の `wireskein` package にした（`pip install --pre wireskein`、Python 3.13 以上、依存は numpy だけ）。公開の module は `wireskein.runlog`（テストの実行の記録。標準ライブラリだけ）、`wireskein.verify`（記録の照合）、`wireskein.analyze`（キャプチャの復号。β）。コマンドは `wireskein`（`analyze`、`segments`、`verify`）。`wsproto` の import と `prototype/ws.py` はなくなった。評価のスクリプトは `research/` に移し、package には入れない。
+- (EN) Checks: `square`, `level`, `starts`, `ends`, `only_moving`, `pulses`, `i2c`, `spi` and `uart`. The UART check measures the bit rate from the edges, takes the format (`bits`, `parity`, `stop`), does not count characters cut by the window as errors, and with `baud=None` only measures. An I2C transaction cut at the window end is reported with `complete: false` and `pending_bits`. A capture whose meta has `time_base_slipped: true` keeps its verdict, and a failure's reason names the slip.
+- (JA) 検査は `square`、`level`、`starts`、`ends`、`only_moving`、`pulses`、`i2c`、`spi`、`uart`。UART はエッジからビットレートを測り、フォーマット（`bits`、`parity`、`stop`）を指定でき、窓で切れた文字をエラーにせず、`baud=None` で測るだけにもできる。窓の終わりで切れた I2C の取引は `complete: false` と `pending_bits` 付きで返す。meta に `time_base_slipped: true` があるキャプチャは判定を変えず、NG の理由にそれを書く。
+- (EN) Repeated heading names under one parent keep their own expectations (`name[0]`, `name[1]`). A check whose pins are not captured is unchecked, never NG.
+- (JA) 同じ親の下で繰り返した見出しは、それぞれの期待を持つ（`name[0]`、`name[1]`）。ピンがキャプチャにない検査は、NG ではなく未検査。
+- (EN) Run format: `wireskein-run/0`, unchanged from the prototype, so runs recorded before this release still verify.
+- (JA) 記録の形式は `wireskein-run/0` で、プロトタイプから変えていない。このリリースより前の記録もそのまま照合できる。

wireskein-0.0.1/LICENSE

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

wireskein-0.0.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: wireskein
+Version: 0.0.1
+Summary: Logic-analyzer captures to protocol decodes, and waveform checks of recorded hardware test runs
+Project-URL: Homepage, https://github.com/Open-Embedded-Probe/wireskein
+Project-URL: Repository, https://github.com/Open-Embedded-Probe/wireskein
+Author: TANAKA Masayuki
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.13
+Requires-Dist: numpy>=2.0
+Description-Content-Type: text/markdown
+
+# WireSkein
+
+[日本語 README](https://github.com/Open-Embedded-Probe/wireskein/blob/main/README.ja.md)
+
+WireSkein reads logic-analyzer captures. It has two uses:
+
+- **Checking recorded hardware test runs.** A test records what it sent, the captures, and what each step should look like on the wire (a 1 kHz square wave, an I2C write to 0x42, a UART at F_CPU / BRR). `wireskein verify` checks every capture against these expectations and reports OK / NG with measured values, as text, JSON and JUnit XML.
+- **Decoding unknown captures.** `wireskein analyze` finds which pins carry I2C, SPI, UART, RVSWD / SWIO, SWD or CAN, and decodes them. Upper layers (NMEA, Modbus, known I2C / SPI devices) are tried on top.
+
+Status: **beta** (`0.1.0b1`). Breaking changes may still happen; see [Stability](#stability).
+
+## Install
+
+```sh
+pip install --pre wireskein        # or: uv add --prerelease=allow wireskein
+```
+
+Python 3.13 or newer. The only dependency is numpy.
+
+## Checking a test run
+
+A test records a run with `wireskein.runlog`. This module uses only the standard library.
+
+```python
+from wireskein.runlog import Recorder, square, level, only_moving
+
+rec = Recorder("out/run1", target="x035")
+with rec.section(1, "test_pwm"):
+    for duty in (64, 128, 0):
+        want = [square("PA1", 1000, duty / 255), only_moving(["PA1"])] if duty else [level("PA1", 0)]
+        with rec.section(2, f"duty={duty}", expect=want):
+            rec.command(f"PWM {duty}")          # what the host sent
+            rec.reply(reply_line)               # what the device answered
+            t = rec.armed()                     # right after arming the capture
+            data = read_capture()               # bytes, one sample per byte, bit k = pin k
+            rec.capture(data, rate, ["PA1", "PA0"], t, start_us=segment_start_us)
+rec.close()
+```
+
+Then check it:
+
+```sh
+wireskein verify out/run1 --junit out/run1/report.xml --json out/run1/report.json
+```
+
+```text
+OK  test_pwm/duty=64  square  c0001.bin
+NG  test_pwm/duty=128  square  c0002.bin  duty 0.6999 vs 0.5020
+OK  test_pwm/duty=0  level  c0003.bin
+2 ok, 1 ng, 0 unchecked (4 segments, 3 captures)
+```
+
+The exit code is 1 when a check fails. A check whose pins are not in the capture is **unchecked** (`--`). Unchecked results do not fail the run.
+
+### Headings and segments
+
+Headings split the run into a tree of segments. `#` is a test, `##` is a step, and a heading without a name (`##`) closes that level. `Recorder.section()` opens a heading and closes it when the `with` block ends. A capture belongs to the segment in which it was armed. Expectations are stored under the segment path, for example `test_pwm/duty=64`. When a name repeats under the same parent, each repetition gets an index (`duty=64[0]`, `duty=64[1]`) and keeps its own expectations. A broken structure, such as a skipped level, is always reported as NG.
+
+### Checks
+
+| Helper | Checks |
+| --- | --- |
+| `square(pin, freq_hz, duty, tol_freq, tol_duty, max_jitter)` | A steady square wave: frequency (relative tolerance), duty (absolute), period spread |
+| `level(pin, value)` | The pin does not move |
+| `starts({pin: v})` / `ends({pin: v})` | The level at the first / last sample |
+| `only_moving([pins])` | No other captured pin moves |
+| `pulses(pin, count, period_s, tol)` | Number of rising edges and their period |
+| `i2c(scl, sda, transactions, hz, tol_hz, released)` | Transactions (address, direction, bytes, ACK, `complete`), SCL rate, and a released bus at the end |
+| `spi(clk, mosi, miso, cs, mode, mosi_bytes, miso_bytes, hz)` | Mode, bytes on both lines, SCK rate, and CS high at the end |
+| `uart(pin, baud, data, tol_baud, idle, bits, parity, stop, max_errors)` | Bit rate measured from the edges, data, idle level, and framing / parity errors. `baud=None` only measures |
+
+Pins and roles are given, so these checks are verification, not discovery. `docs/capture-test-guide.ja.md` explains how to choose capture windows and tolerances, with examples from real runs.
+
+If a capture has the meta `time_base_slipped: true` (the probe knows some samples were taken late), the verdict does not change, but a failure's reason says so.
+
+### Python API
+
+```python
+from wireskein.verify import verify, junit, dumps, lines, summary_line
+
+report = verify("out/run1")          # dict: results (with measured values), summary, log
+xml = junit(report)                  # JUnit XML
+text = dumps(report)                 # JSON
+print(summary_line(report), *lines(report), sep="\n")   # NG and unchecked lines, as the CLI prints them
+```
+
+For pytest, [pytest-embedded-wireskein](https://github.com/Open-Embedded-Probe/pytest-embedded-wireskein) gives each test a `ws_run` recorder and runs `verify` after the test.
+
+## Decoding a capture
+
+```sh
+wireskein analyze capture.sr                              # sigrok .sr, or a fixture directory
+wireskein analyze capture.sr --hint '{"protocols": ["i2c"]}'
+wireskein analyze capture.sr --mode all --out result.json
+wireskein segments capture.sr --results                   # a capture with marker lines on a UART
+```
+
+`--hint` restricts what is tried. It can name protocols, or give pins with their roles and baud rates. The result is still scored by the decoders' own checks.
+
+```python
+from wireskein.analyze import load, analyze, export
+
+cap = load("capture.sr")
+res = analyze(cap, {"protocols": ["spi"]})
+doc = export(res, cap)
+```
+
+## Stability
+
+| Part | Promise during the beta |
+| --- | --- |
+| `wireskein.runlog` (names, arguments and meaning of `Recorder` and the check helpers) | Stable. New arguments get defaults that keep the old meaning |
+| Run format (`run.json`, `FORMAT = "wireskein-run/0"`) | Stable. An incompatible change raises `FORMAT`, and `verify` refuses older runs with a clear error |
+| `wireskein.verify.verify` / `junit`, `wireskein verify` | Stable. Report fields may be added |
+| `wireskein.analyze`, `wireskein analyze` / `segments` output | May change |
+| `wireskein._engine` | Internal |
+
+## Repository layout
+
+```text
+src/wireskein/          the package (runlog, verify, analyze, cli, _engine, decl/ data)
+tests/                  pytest
+research/               evaluation scripts, benchmarks and findings (not packaged)
+corpus/                 real and synthetic fixtures for research/
+docs/                   design notes (Japanese)
+```
+
+To run the research scripts: `uv sync --group research`, then `uv run python research/evaluate.py --synth 200 --engine staged`. See `research/README.ja.md`.
+
+## Development
+
+```sh
+uv run pytest
+uv build
+```
+
+## Release
+
+Releases use GitHub Actions, the same way as pytest-embedded-arduino-cli.
+
+1. Update the `## Unreleased` section of `CHANGELOG.md`.
+2. Run the `Release` workflow manually and enter the version, for example `0.1.0b1`.
+3. The workflow does the rest. It updates the version in `pyproject.toml` and `src/wireskein/__init__.py`, moves the changelog entries under the new version, runs the tests, builds, commits, tags `v<version>`, creates a GitHub Release, and publishes to PyPI.
+
+PyPI publishing uses Trusted Publishing.
+
+## License
+
+MIT

wireskein-0.0.1/README.ja.md

@@ -0,0 +1,114 @@
+# WireSkein
+
+[English README](https://github.com/Open-Embedded-Probe/wireskein/blob/main/README.md)
+
+WireSkein は、ロジックアナライザのキャプチャを読むツールです。用途は 2 つあります。
+
+- **実機のテストの記録を照合する。** テストは、送ったコマンド、キャプチャ、各ステップの線の上であるべき姿（1 kHz の方形波、0x42 への I2C の書き込み、F_CPU / BRR の UART など）を記録します。`wireskein verify` は、その期待とキャプチャを照らし合わせます。結果は、測定値付きの OK / NG として、テキスト、JSON、JUnit XML で出します。
+- **中身の分からないキャプチャを復号する。** `wireskein analyze` は、どのピンが I2C、SPI、UART、RVSWD / SWIO、SWD、CAN かを見つけて復号します。その上の層（NMEA、Modbus、既知の I2C / SPI デバイス）も試します。
+
+状態: **β 版**（`0.1.0b1`）です。互換のない変更が入ることがあります（[安定性](#安定性)を参照）。
+
+## 入れ方
+
+```sh
+pip install --pre wireskein        # または uv add --prerelease=allow wireskein
+```
+
+Python 3.13 以上が要ります。依存は numpy だけです。
+
+## テストの記録を照合する
+
+テストは、`wireskein.runlog` で記録します。このモジュールは、標準ライブラリだけで動きます。
+
+```python
+from wireskein.runlog import Recorder, square, level, only_moving
+
+rec = Recorder("out/run1", target="x035")
+with rec.section(1, "test_pwm"):
+    for duty in (64, 128, 0):
+        want = [square("PA1", 1000, duty / 255), only_moving(["PA1"])] if duty else [level("PA1", 0)]
+        with rec.section(2, f"duty={duty}", expect=want):
+            rec.command(f"PWM {duty}")          # PC が送ったもの
+            rec.reply(reply_line)               # デバイスの応答
+            t = rec.armed()                     # キャプチャを開始した直後
+            data = read_capture()               # bytes。1 サンプル 1 バイト、ビット k がピン k
+            rec.capture(data, rate, ["PA1", "PA0"], t, start_us=segment_start_us)
+rec.close()
+```
+
+照合は次のコマンドで行います。
+
+```sh
+wireskein verify out/run1 --junit out/run1/report.xml --json out/run1/report.json
+```
+
+NG があれば、終了コードは 1 です。検査に使うピンがキャプチャにないときは、未検査（`--`）になります。未検査は、実行を失敗にしません。
+
+- 見出し（`#` がテスト、`##` がステップ、名前のない `##` で閉じる）で、区間の木を作ります。
+- キャプチャは、開始した時刻を含む区間に割り当てます。
+- 期待は、区間のパス（例 `test_pwm/duty=64`）に付けます。同じ親の下で名前が重なると、`duty=64[0]`、`duty=64[1]` のように連番を付け、それぞれが自分の期待を持ちます。
+
+検査の一覧、窓と許容誤差の決め方、実機の例は [docs/capture-test-guide.ja.md](docs/capture-test-guide.ja.md) にあります。
+
+pytest からは、[pytest-embedded-wireskein](https://github.com/Open-Embedded-Probe/pytest-embedded-wireskein) を使います。test ごとに記録器 `ws_run` を渡し、test の後に照合します。
+
+## キャプチャを復号する
+
+```sh
+wireskein analyze capture.sr                              # sigrok の .sr、または fixture のディレクトリ
+wireskein analyze capture.sr --hint '{"protocols": ["i2c"]}'
+wireskein segments capture.sr --results                   # UART にマーカーの行を流したキャプチャ
+```
+
+```python
+from wireskein.analyze import load, analyze, export
+
+cap = load("capture.sr")
+doc = export(analyze(cap, {"protocols": ["spi"]}), cap)
+```
+
+## 安定性
+
+| 部分 | β の間の約束 |
+| --- | --- |
+| `wireskein.runlog`（`Recorder` と検査の helper の名前、引数、意味） | 変えない。足す引数は、既定値で今の意味を保つ |
+| 記録の形式（`run.json`、`FORMAT = "wireskein-run/0"`） | 変えない。互換のない変更をするときは `FORMAT` を上げ、`verify` は古い形式をはっきりしたエラーで断る |
+| `wireskein.verify.verify` / `junit`、`wireskein verify` | 変えない。報告の項目は増えることがある |
+| `wireskein.analyze`、`wireskein analyze` / `segments` の出力 | 変わることがある |
+| `wireskein._engine` | 内部 |
+
+## リポジトリの構成
+
+```text
+src/wireskein/          package（runlog、verify、analyze、cli、_engine、decl/ のデータ）
+tests/                  pytest
+research/               評価のスクリプト、ベンチ、実験の記録（package に入れない）
+corpus/                 research/ が使う実記録と合成の fixture
+docs/                   設計のメモ
+```
+
+## 開発
+
+```sh
+uv run pytest
+uv build
+```
+
+## リリース
+
+pytest-embedded-arduino-cli と同じく、GitHub Actions で出します。
+
+1. `CHANGELOG.md` の `## Unreleased` を更新します。
+2. `Release` の workflow を手で実行し、版（例 `0.1.0b1`）を入れます。
+3. 残りは workflow が行います。
+   - `pyproject.toml` と `src/wireskein/__init__.py` の版を書き換える
+   - 変更履歴を新しい版の見出しの下へ移す
+   - テストとビルドを行い、コミットして `v<版>` のタグを付ける
+   - GitHub Release を作り、PyPI に出す
+
+PyPI への公開は Trusted Publishing で行います。
+
+## ライセンス
+
+MIT

wireskein-0.0.1/README.md

@@ -0,0 +1,149 @@
+# WireSkein
+
+[日本語 README](https://github.com/Open-Embedded-Probe/wireskein/blob/main/README.ja.md)
+
+WireSkein reads logic-analyzer captures. It has two uses:
+
+- **Checking recorded hardware test runs.** A test records what it sent, the captures, and what each step should look like on the wire (a 1 kHz square wave, an I2C write to 0x42, a UART at F_CPU / BRR). `wireskein verify` checks every capture against these expectations and reports OK / NG with measured values, as text, JSON and JUnit XML.
+- **Decoding unknown captures.** `wireskein analyze` finds which pins carry I2C, SPI, UART, RVSWD / SWIO, SWD or CAN, and decodes them. Upper layers (NMEA, Modbus, known I2C / SPI devices) are tried on top.
+
+Status: **beta** (`0.1.0b1`). Breaking changes may still happen; see [Stability](#stability).
+
+## Install
+
+```sh
+pip install --pre wireskein        # or: uv add --prerelease=allow wireskein
+```
+
+Python 3.13 or newer. The only dependency is numpy.
+
+## Checking a test run
+
+A test records a run with `wireskein.runlog`. This module uses only the standard library.
+
+```python
+from wireskein.runlog import Recorder, square, level, only_moving
+
+rec = Recorder("out/run1", target="x035")
+with rec.section(1, "test_pwm"):
+    for duty in (64, 128, 0):
+        want = [square("PA1", 1000, duty / 255), only_moving(["PA1"])] if duty else [level("PA1", 0)]
+        with rec.section(2, f"duty={duty}", expect=want):
+            rec.command(f"PWM {duty}")          # what the host sent
+            rec.reply(reply_line)               # what the device answered
+            t = rec.armed()                     # right after arming the capture
+            data = read_capture()               # bytes, one sample per byte, bit k = pin k
+            rec.capture(data, rate, ["PA1", "PA0"], t, start_us=segment_start_us)
+rec.close()
+```
+
+Then check it:
+
+```sh
+wireskein verify out/run1 --junit out/run1/report.xml --json out/run1/report.json
+```
+
+```text
+OK  test_pwm/duty=64  square  c0001.bin
+NG  test_pwm/duty=128  square  c0002.bin  duty 0.6999 vs 0.5020
+OK  test_pwm/duty=0  level  c0003.bin
+2 ok, 1 ng, 0 unchecked (4 segments, 3 captures)
+```
+
+The exit code is 1 when a check fails. A check whose pins are not in the capture is **unchecked** (`--`). Unchecked results do not fail the run.
+
+### Headings and segments
+
+Headings split the run into a tree of segments. `#` is a test, `##` is a step, and a heading without a name (`##`) closes that level. `Recorder.section()` opens a heading and closes it when the `with` block ends. A capture belongs to the segment in which it was armed. Expectations are stored under the segment path, for example `test_pwm/duty=64`. When a name repeats under the same parent, each repetition gets an index (`duty=64[0]`, `duty=64[1]`) and keeps its own expectations. A broken structure, such as a skipped level, is always reported as NG.
+
+### Checks
+
+| Helper | Checks |
+| --- | --- |
+| `square(pin, freq_hz, duty, tol_freq, tol_duty, max_jitter)` | A steady square wave: frequency (relative tolerance), duty (absolute), period spread |
+| `level(pin, value)` | The pin does not move |
+| `starts({pin: v})` / `ends({pin: v})` | The level at the first / last sample |
+| `only_moving([pins])` | No other captured pin moves |
+| `pulses(pin, count, period_s, tol)` | Number of rising edges and their period |
+| `i2c(scl, sda, transactions, hz, tol_hz, released)` | Transactions (address, direction, bytes, ACK, `complete`), SCL rate, and a released bus at the end |
+| `spi(clk, mosi, miso, cs, mode, mosi_bytes, miso_bytes, hz)` | Mode, bytes on both lines, SCK rate, and CS high at the end |
+| `uart(pin, baud, data, tol_baud, idle, bits, parity, stop, max_errors)` | Bit rate measured from the edges, data, idle level, and framing / parity errors. `baud=None` only measures |
+
+Pins and roles are given, so these checks are verification, not discovery. `docs/capture-test-guide.ja.md` explains how to choose capture windows and tolerances, with examples from real runs.
+
+If a capture has the meta `time_base_slipped: true` (the probe knows some samples were taken late), the verdict does not change, but a failure's reason says so.
+
+### Python API
+
+```python
+from wireskein.verify import verify, junit, dumps, lines, summary_line
+
+report = verify("out/run1")          # dict: results (with measured values), summary, log
+xml = junit(report)                  # JUnit XML
+text = dumps(report)                 # JSON
+print(summary_line(report), *lines(report), sep="\n")   # NG and unchecked lines, as the CLI prints them
+```
+
+For pytest, [pytest-embedded-wireskein](https://github.com/Open-Embedded-Probe/pytest-embedded-wireskein) gives each test a `ws_run` recorder and runs `verify` after the test.
+
+## Decoding a capture
+
+```sh
+wireskein analyze capture.sr                              # sigrok .sr, or a fixture directory
+wireskein analyze capture.sr --hint '{"protocols": ["i2c"]}'
+wireskein analyze capture.sr --mode all --out result.json
+wireskein segments capture.sr --results                   # a capture with marker lines on a UART
+```
+
+`--hint` restricts what is tried. It can name protocols, or give pins with their roles and baud rates. The result is still scored by the decoders' own checks.
+
+```python
+from wireskein.analyze import load, analyze, export
+
+cap = load("capture.sr")
+res = analyze(cap, {"protocols": ["spi"]})
+doc = export(res, cap)
+```
+
+## Stability
+
+| Part | Promise during the beta |
+| --- | --- |
+| `wireskein.runlog` (names, arguments and meaning of `Recorder` and the check helpers) | Stable. New arguments get defaults that keep the old meaning |
+| Run format (`run.json`, `FORMAT = "wireskein-run/0"`) | Stable. An incompatible change raises `FORMAT`, and `verify` refuses older runs with a clear error |
+| `wireskein.verify.verify` / `junit`, `wireskein verify` | Stable. Report fields may be added |
+| `wireskein.analyze`, `wireskein analyze` / `segments` output | May change |
+| `wireskein._engine` | Internal |
+
+## Repository layout
+
+```text
+src/wireskein/          the package (runlog, verify, analyze, cli, _engine, decl/ data)
+tests/                  pytest
+research/               evaluation scripts, benchmarks and findings (not packaged)
+corpus/                 real and synthetic fixtures for research/
+docs/                   design notes (Japanese)
+```
+
+To run the research scripts: `uv sync --group research`, then `uv run python research/evaluate.py --synth 200 --engine staged`. See `research/README.ja.md`.
+
+## Development
+
+```sh
+uv run pytest
+uv build
+```
+
+## Release
+
+Releases use GitHub Actions, the same way as pytest-embedded-arduino-cli.
+
+1. Update the `## Unreleased` section of `CHANGELOG.md`.
+2. Run the `Release` workflow manually and enter the version, for example `0.1.0b1`.
+3. The workflow does the rest. It updates the version in `pyproject.toml` and `src/wireskein/__init__.py`, moves the changelog entries under the new version, runs the tests, builds, commits, tags `v<version>`, creates a GitHub Release, and publishes to PyPI.
+
+PyPI publishing uses Trusted Publishing.
+
+## License
+
+MIT

wireskein-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wireskein"
+version = "0.0.1"
+description = "Logic-analyzer captures to protocol decodes, and waveform checks of recorded hardware test runs"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [
+  { name = "TANAKA Masayuki" },
+]
+dependencies = [
+  "numpy>=2.0",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+  "Topic :: Software Development :: Testing",
+]
+
+[project.scripts]
+wireskein = "wireskein.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Open-Embedded-Probe/wireskein"
+Repository = "https://github.com/Open-Embedded-Probe/wireskein"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+research = ["mini-racer>=0.14.1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wireskein"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/wireskein", "tests", "README.md", "README.ja.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wireskein-0.0.1/src/wireskein/__init__.py

@@ -0,0 +1,10 @@
+"""WireSkein: logic-analyzer captures to protocol decodes, and checks of recorded test runs.
+
+Public modules: wireskein.runlog (recording, standard library only),
+wireskein.verify (checking a recorded run), wireskein.analyze (decoding a
+capture). Everything under wireskein._engine may change between versions.
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.1"

wireskein-0.0.1/src/wireskein/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

wireskein-0.0.1/src/wireskein/_engine/analyzers/i2c.py

@@ -0,0 +1,101 @@
+"""I2C decoder: (scl, sda) edges -> transactions. Proposals: every ordered pair."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .. import kernels as K
+from ..stack import Context, Stream, pairs
+
+
+class I2c:
+    name = "i2c"
+    consumes = "capture"
+    produces = "i2c.transactions"
+
+    def propose(self, ctx: Context, parent):
+        for scl, sda in pairs(ctx.active):
+            yield {"scl": scl, "sda": sda}
+
+    def probe_channels(self, p):
+        return [p["scl"], p["sda"]]
+
+    def run(self, ctx: Context, parent, p):
+        cap = ctx.capture
+        scl, sda = cap.channel(p["scl"]), cap.channel(p["sda"])
+        roles = {"scl": p["scl"], "sda": p["sda"]}
+        ev = K.merge_events(scl.edges, sda.edges)
+        if len(ev) == 0:
+            return roles, None, {"starts": 0}
+        c, d = scl.initial, sda.initial
+        txs, cur, bits = [], None, []
+        starts = stops = 0
+        seg_total = seg_ok = 0
+        scl_rise_in = 0
+        sda_explained = 0
+        misc_sda = 0
+
+        def close_segment(end_sample, stop):
+            nonlocal seg_total, seg_ok
+            if cur is None:
+                return
+            if bits:  # START immediately followed by START/STOP carries no bits to check
+                seg_total += 1
+                seg_ok += len(bits) % 9 == 0
+            nbytes = len(bits) // 9
+            vals = [int("".join(map(str, bits[i * 9:i * 9 + 8])), 2) for i in range(nbytes)]
+            acks = [bits[i * 9 + 8] == 0 for i in range(nbytes)]
+            if vals:
+                cur.update(addr=vals[0] >> 1, rw="read" if vals[0] & 1 else "write", addr_ack=acks[0],
+                           bytes=vals[1:], acks=acks[1:])
+            cur.update(end=int(end_sample), stop=stop, bits=len(bits))
+            txs.append(dict(cur))
+
+        pending = None  # a bit is committed on the SCL fall; a rise followed by START/STOP is not data
+        for t, which in ev.tolist():
+            if which == 0:
+                c ^= 1
+                if cur is not None:
+                    scl_rise_in += c == 1
+                    if c == 1:
+                        pending = d
+                    elif pending is not None:
+                        bits.append(pending)
+                        pending = None
+            else:
+                d ^= 1
+                if c == 1:
+                    pending = None
+                    if d == 0:  # START / repeated START
+                        if cur is not None:
+                            close_segment(t, False)
+                        starts += 1
+                        cur, bits = {"start": int(t)}, []
+                    else:       # STOP
+                        if cur is not None:
+                            close_segment(t, True)
+                            stops += 1
+                        cur, bits = None, []
+                    sda_explained += 1
+                elif cur is not None:
+                    sda_explained += 1
+                else:
+                    misc_sda += 1
+        n_rise = int(np.sum((scl.initial ^ ((np.arange(len(scl.edges)) + 1) & 1)) == 1))
+        with_addr = [x for x in txs if "addr" in x]
+        addrs = [x["addr"] for x in with_addr]
+        top_addr = max((addrs.count(a) for a in set(addrs)), default=0)
+        metrics = {
+            "starts": starts,
+            "stops": stops,
+            "transactions": len(txs),
+            "bytes": sum(1 + len(x["bytes"]) for x in with_addr),
+            "segment_ok_rate": seg_ok / seg_total if seg_total else 0.0,
+            "scl_coverage": scl_rise_in / n_rise if n_rise else 0.0,
+            "sda_explained": sda_explained / len(sda.edges) if len(sda.edges) else 0.0,
+            "addr_ack_rate": float(np.mean([x["addr_ack"] for x in with_addr])) if with_addr else 0.0,
+            "distinct_addr": len(set(addrs)),
+            "top_addr_share": top_addr / len(addrs) if addrs else 0.0,
+            "clk_role_score": ctx.features[p["scl"]].scores.get("clock", 0.0),
+        }
+        return roles, Stream("i2c.transactions", txs), metrics