[PR #2126] [CLOSED] feat(signals): decode recorded logic signals through sigrok #5047

New issue

Closed

opened 2026-10-31 01:00:44 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:00:44 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2126
Author: @Olorinm
Created: 10/12/2026
Status: ❌ Closed

Base: main ← Head: feat/recorded-signals

📝 Commits (8)

dccb802 feat(signals): decode recorded logic signals through sigrok
619832f fix(signals): preserve completed observations on interruption
65cc391 fix(signals): enforce decoder resource limits and clarify workspace failures
ce6bc67 test(signals): make decoder fixtures independent of Node binary size
b52ca98 fix(signals): retain completed evidence and retry CLI cleanup
82d0f2c fix(signals): respect inherited producer resource ceilings
ac62a4e fix(signals): preserve producer diagnostics and classify identity failures
847c7cc fix(signals): finish integrity phase before validating report

📊 Changes

47 files changed (+2035 additions, -34 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+4 -0)
➕ .github/workflows/real-signal-recording.yml (+50 -0)
📝 README.md (+1 -0)
📝 README_ar.md (+1 -0)
📝 README_de.md (+1 -0)
📝 README_es.md (+1 -0)
📝 README_fa.md (+18 -17)
📝 README_fr.md (+1 -0)
📝 README_id.md (+1 -0)
📝 README_it.md (+1 -0)
📝 README_ja.md (+1 -0)
📝 README_ko.md (+1 -0)
📝 README_pl.md (+1 -0)
📝 README_pt-BR.md (+1 -0)
📝 README_ru.md (+18 -17)
📝 README_th.md (+1 -0)
📝 README_tr.md (+1 -0)
📝 README_uk.md (+1 -0)
📝 README_vi.md (+1 -0)
📝 README_zh-TW.md (+1 -0)

...and 27 more files

📄 Description

Summary

Add decode_signal_recording / decode-signal-recording for an analyst who already has a logic-analyzer recording and wants protocol-decoder annotations in REA Evidence. For example, a UART VCD plus uart:rx=RX:baudrate=9600 yields sample ranges and decoded display text through the same CLI/MCP workflow.

Problem and expected behavior

REA can investigate firmware but cannot currently interpret recorded digital signals. The separate packet-capture proposal #2130 is independent and can be reviewed or merged separately. This additive capability delegates decoding to caller-supplied sigrok-cli 0.7.2, preserves the selected decoder/channel/options and producer diagnostics, and works without opening a binary target. There is no linked issue; this PR proposes that focused enhancement for review.

Change and scope

One file-analysis tool, an optional sigrok adapter, shared application validation/Evidence, CLI/MCP registration, capability/catalog entries, a guide, canonical README capability rows in every translation, and authored skill guidance. No physical acquisition, device control, installer, native-analysis changes or automatic protocol guessing.

Contract and boundary impact

Semantic owner and earliest changed stage: strict signal-recording schemas; sigrok adapter owns producer arguments and output. The shared service validates artifact identity and exact selections before creating Evidence.
CLI and MCP/tool-catalog contract: additive named contract; required path and decoder selection; optional input format and annotation selector; inline typed Evidence.
Provider, bridge, target-format, or platform compatibility: absolute REA_SIGROK_COMMAND, sigrok-cli 0.7.2 with libsigrokdecode. Linux with util-linux prlimit is required; unsupported hosts fail before workspace allocation. REA_SIGROK_PRLIMIT_COMMAND can override /usr/bin/prlimit.
Evidence, artifact, provenance, or reconstruction contract: source digest/size/path, configured and resolved executable/limiter paths, digests and arguments, tool version, verbatim annotation text, decoding stderr and separate version-probe diagnostics. Sample ranges are not recast as timestamps or lossless binary payloads. Empty output does not prove no traffic.
Process execution, authorization, cleanup, or containment impact: private read-only input copy, owned process supervision, cancellation, 30-second command deadline, 32-MiB input and 4-MiB combined output bounds. Overflow fails; cleanup failure retains ownership and completed observations for retry. The one-shot CLI awaits a close retry without masking the original failure; MCP records completed partial Evidence before error delivery, and bounded post-run identity checks complete before honoring a late abort. Before launch, prlimit enforces soft and hard limits of at most 1 GiB address space, 64 MiB per file, 30 CPU seconds and no core dumps. Stricter inherited soft/hard limits are preserved and effective values are reported. These are per-process/per-file limits, not aggregate quotas or an OS sandbox; caller tools/modules and the limiter are trusted. Workspace failures are distinguished from invalid input. Post-run identity errors identify the private copy/tool/limiter involved and retain captured output. Resource-signal failures retain the signal and effective limits without claiming the signal proves its cause.
Generated metadata, package, or installation impact: source catalog registration only; generated outputs are ignored. No dependency, package or installation changes.

Evidence and regression coverage

Tests added: command-boundary coverage of warnings/options, immutable snapshot verification, nonzero exit, output overflow, cancellation, cleanup retry and pre-admission validation, and completed observations on late cancellation; workspace failures, unsupported hosts, advertised MCP schemas and unavailable-tool diagnostics. A Linux kernel test verifies inherited hard/soft limits and refused allocation with a synthetic producer; this is separate from real sigrok coverage. A second Linux process test confirms lower inherited file/CPU limits are preserved during the actual launch.
Executed real evidence: synthesized 9600-baud 8N1 UART recording carrying REA produces annotations for 52, 45, 41 with sample ranges. CLI/MCP return the same Evidence ID; stored Evidence and source identity are checked.
Real verifier also exercises format autodetection, annotation selection, invalid decoder, absent/malformed recording and rejected extra arguments. No remaining owned descendants.
Remaining proof gaps: other decoders/formats and physical hardware. macOS and Windows are explicitly unsupported. The real provider and Linux kernel-limit checks run in the linked fork workflow below; upstream CI remains visible under Checks; the links below are independently executed fork verification.
Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run check — passed (existing repository lint warnings remain).
npm run docs:check — passed.
npm run verify:test-discovery — all 920 test files discovered exactly once.
Focused provider/MCP, capability and product-catalog tests — 50 passed on macOS, two Linux-only kernel tests skipped.
Linux workflow on 847c7cc67 — passed: 26 provider/CLI/MCP/resource-limit tests, plus 6 real sigrok CLI/MCP cases on Ubuntu 24.04 (sigrok-cli 0.7.2, libsigrok 0.5.2, libsigrokdecode 0.5.3). Kernel tests verify refused oversized allocation and preservation of lower inherited file/CPU limits.
git diff --check and staged-diff Gitleaks scan — passed.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: no changes to those providers. This new adapter supports Linux only; earlier macOS verification does not establish the current bounded integration.
Package or release metadata impact: none.
Security/privacy/containment: the selected recording, producer/limiter identities and diagnostics enter Evidence; ambient environment is not serialized. Recordings may contain sensitive data and their selected content is preserved. Source is never passed to sigrok; libraries/modules remain trusted and uncontained.

Review checklist

Concrete enhancement; one focused outcome and Conventional Commit title.
Reason for no linked issue stated above.
Changed public behavior and meaningful failure paths covered.
Owning docs, contracts and catalog sources updated.
Representative CLI/MCP result and actual validation stated.
Final diff checked for secrets, unrelated changes and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2126 **Author:** [@Olorinm](https://github.com/Olorinm) **Created:** 10/12/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/recorded-signals` --- ### 📝 Commits (8) - [`dccb802`](https://github.com/morluto/rea/commit/dccb8024ce2e5bfbb0af419e98d344dfd34136e2) feat(signals): decode recorded logic signals through sigrok - [`619832f`](https://github.com/morluto/rea/commit/619832f9d06f5a27e1509fe943cb8580ec8baa7a) fix(signals): preserve completed observations on interruption - [`65cc391`](https://github.com/morluto/rea/commit/65cc391e851eaf4d6405558115e4202fa7e67d0a) fix(signals): enforce decoder resource limits and clarify workspace failures - [`ce6bc67`](https://github.com/morluto/rea/commit/ce6bc67e967121ea7a10000403948fd8edb45de3) test(signals): make decoder fixtures independent of Node binary size - [`b52ca98`](https://github.com/morluto/rea/commit/b52ca98bf7896c8bfac47628b5ef47bf781a5b74) fix(signals): retain completed evidence and retry CLI cleanup - [`82d0f2c`](https://github.com/morluto/rea/commit/82d0f2c67a57ddc952195e7aed33dfc9864ebc3f) fix(signals): respect inherited producer resource ceilings - [`ac62a4e`](https://github.com/morluto/rea/commit/ac62a4ec49eb5b52a9c2bcd0196b4726308fb45d) fix(signals): preserve producer diagnostics and classify identity failures - [`847c7cc`](https://github.com/morluto/rea/commit/847c7cc6733e6b5b4812c4ea16aabcc825863227) fix(signals): finish integrity phase before validating report ### 📊 Changes **47 files changed** (+2035 additions, -34 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+4 -0) ➕ `.github/workflows/real-signal-recording.yml` (+50 -0) 📝 `README.md` (+1 -0) 📝 `README_ar.md` (+1 -0) 📝 `README_de.md` (+1 -0) 📝 `README_es.md` (+1 -0) 📝 `README_fa.md` (+18 -17) 📝 `README_fr.md` (+1 -0) 📝 `README_id.md` (+1 -0) 📝 `README_it.md` (+1 -0) 📝 `README_ja.md` (+1 -0) 📝 `README_ko.md` (+1 -0) 📝 `README_pl.md` (+1 -0) 📝 `README_pt-BR.md` (+1 -0) 📝 `README_ru.md` (+18 -17) 📝 `README_th.md` (+1 -0) 📝 `README_tr.md` (+1 -0) 📝 `README_uk.md` (+1 -0) 📝 `README_vi.md` (+1 -0) 📝 `README_zh-TW.md` (+1 -0) _...and 27 more files_ </details> ### 📄 Description ## Summary Add `decode_signal_recording` / `decode-signal-recording` for an analyst who already has a logic-analyzer recording and wants protocol-decoder annotations in REA Evidence. For example, a UART VCD plus `uart:rx=RX:baudrate=9600` yields sample ranges and decoded display text through the same CLI/MCP workflow. ## Problem and expected behavior REA can investigate firmware but cannot currently interpret recorded digital signals. The separate packet-capture proposal #2130 is independent and can be reviewed or merged separately. This additive capability delegates decoding to caller-supplied sigrok-cli 0.7.2, preserves the selected decoder/channel/options and producer diagnostics, and works without opening a binary target. There is no linked issue; this PR proposes that focused enhancement for review. ## Change and scope One file-analysis tool, an optional sigrok adapter, shared application validation/Evidence, CLI/MCP registration, capability/catalog entries, a guide, canonical README capability rows in every translation, and authored skill guidance. No physical acquisition, device control, installer, native-analysis changes or automatic protocol guessing. ## Contract and boundary impact - Semantic owner and earliest changed stage: strict signal-recording schemas; sigrok adapter owns producer arguments and output. The shared service validates artifact identity and exact selections before creating Evidence. - CLI and MCP/tool-catalog contract: additive named contract; required path and decoder selection; optional input format and annotation selector; inline typed Evidence. - Provider, bridge, target-format, or platform compatibility: absolute `REA_SIGROK_COMMAND`, sigrok-cli 0.7.2 with libsigrokdecode. Linux with util-linux `prlimit` is required; unsupported hosts fail before workspace allocation. `REA_SIGROK_PRLIMIT_COMMAND` can override `/usr/bin/prlimit`. - Evidence, artifact, provenance, or reconstruction contract: source digest/size/path, configured and resolved executable/limiter paths, digests and arguments, tool version, verbatim annotation text, decoding stderr and separate version-probe diagnostics. Sample ranges are not recast as timestamps or lossless binary payloads. Empty output does not prove no traffic. - Process execution, authorization, cleanup, or containment impact: private read-only input copy, owned process supervision, cancellation, 30-second command deadline, 32-MiB input and 4-MiB combined output bounds. Overflow fails; cleanup failure retains ownership and completed observations for retry. The one-shot CLI awaits a close retry without masking the original failure; MCP records completed partial Evidence before error delivery, and bounded post-run identity checks complete before honoring a late abort. Before launch, `prlimit` enforces soft and hard limits of at most 1 GiB address space, 64 MiB per file, 30 CPU seconds and no core dumps. Stricter inherited soft/hard limits are preserved and effective values are reported. These are per-process/per-file limits, not aggregate quotas or an OS sandbox; caller tools/modules and the limiter are trusted. Workspace failures are distinguished from invalid input. Post-run identity errors identify the private copy/tool/limiter involved and retain captured output. Resource-signal failures retain the signal and effective limits without claiming the signal proves its cause. - Generated metadata, package, or installation impact: source catalog registration only; generated outputs are ignored. No dependency, package or installation changes. ## Evidence and regression coverage - Tests added: command-boundary coverage of warnings/options, immutable snapshot verification, nonzero exit, output overflow, cancellation, cleanup retry and pre-admission validation, and completed observations on late cancellation; workspace failures, unsupported hosts, advertised MCP schemas and unavailable-tool diagnostics. A Linux kernel test verifies inherited hard/soft limits and refused allocation with a synthetic producer; this is separate from real sigrok coverage. A second Linux process test confirms lower inherited file/CPU limits are preserved during the actual launch. - Executed real evidence: synthesized 9600-baud 8N1 UART recording carrying `REA` produces annotations for `52`, `45`, `41` with sample ranges. CLI/MCP return the same Evidence ID; stored Evidence and source identity are checked. - Real verifier also exercises format autodetection, annotation selection, invalid decoder, absent/malformed recording and rejected extra arguments. No remaining owned descendants. - Remaining proof gaps: other decoders/formats and physical hardware. macOS and Windows are explicitly unsupported. The real provider and Linux kernel-limit checks run in the linked fork workflow below; upstream CI remains visible under Checks; the links below are independently executed fork verification. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check` — passed (existing repository lint warnings remain). - `npm run docs:check` — passed. - `npm run verify:test-discovery` — all 920 test files discovered exactly once. - Focused provider/MCP, capability and product-catalog tests — 50 passed on macOS, two Linux-only kernel tests skipped. - [Linux workflow on `847c7cc67`](https://github.com/Olorinm/rea/actions/runs/38243877533) — passed: 26 provider/CLI/MCP/resource-limit tests, plus 6 real sigrok CLI/MCP cases on Ubuntu 24.04 (sigrok-cli 0.7.2, libsigrok 0.5.2, libsigrokdecode 0.5.3). Kernel tests verify refused oversized allocation and preservation of lower inherited file/CPU limits. - `git diff --check` and staged-diff Gitleaks scan — passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: no changes to those providers. This new adapter supports Linux only; earlier macOS verification does not establish the current bounded integration. - Package or release metadata impact: none. - Security/privacy/containment: the selected recording, producer/limiter identities and diagnostics enter Evidence; ambient environment is not serialized. Recordings may contain sensitive data and their selected content is preserved. Source is never passed to sigrok; libraries/modules remain trusted and uncontained. ## Review checklist - [x] Concrete enhancement; one focused outcome and Conventional Commit title. - [x] Reason for no linked issue stated above. - [x] Changed public behavior and meaningful failure paths covered. - [x] Owning docs, contracts and catalog sources updated. - [x] Representative CLI/MCP result and actual validation stated. - [x] Final diff checked for secrets, unrelated changes and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:00:44 +00:00