[PR #2339] [MERGED] feat(signals): decode recordings with bounded sigrok output #5172

Closed
opened 2026-10-31 01:04:32 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2339
Author: @N0zoM1z0
Created: 10/12/2026
Status: ✅ Merged
Merged: 10/12/2026
Merged by: @N0zoM1z0

Base: main ← Head: feat/sigrok-analysis-2126-20261012


📝 Commits (2)

  • 3064691 feat(signals): decode recordings with bounded sigrok output
  • 507ecd2 refactor(process): share recorded-analysis resource ownership

📊 Changes

50 files changed (+2715 additions, -252 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+7 -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 (+20 -19)
📝 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 (+20 -19)
📝 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 30 more files

📄 Description

Summary

Decode selected protocols from an existing logic recording through shared CLI/MCP Evidence. This replaces #2126, credited to Olorinm, with current-main integration, bounded output, selector budgets and cleanup regressions. There is no linked issue.

Problem and expected behavior

An analyst with a recorded UART/I2C/SPI signal needs explicit decoder/channel/options and useful output without hardware acquisition. A real nine-bit UART recording produced 6,540 display lines and 171,827 bytes of response text. The default now returns 50 literal lines with explicit coverage, while later pages and full output remain available.

Change and scope

Linux-only sigrok-cli 0.7.2 with libsigrokdecode and trusted util-linux prlimit; caller supplies absolute REA_SIGROK_COMMAND. Preserve decoder stack/channel/options, input-format autodetection or explicit format, annotation-class selection, producer warnings and source/tool identity.

Page output after complete decoding. line_offset defaults to 0, line_limit to 50; MCP line_limit: null / CLI --all_lines returns all remaining output. Preserve exact selected text, sample ranges, CRLF/LF, blank lines and UTF-16 code units. Window counts refer to literal LF-separated display lines, not annotations or samples. Do not parse frontend display text into a lossless protocol payload. Partial windows own a copied string so retained Evidence does not retain the entire producer string.

Reuse existing process supervision, artifact descriptor ownership and shared MCP admission/Evidence delivery. TShark and sigrok now share one ArtifactAnalysisResources owner for admission, descriptors, producer/workspace cleanup, retained partial observations and interpretation of owned-command failure facts. Superseded provider-local maps, queues and error-mapping copies are removed. One decode at a time; excess requests fail with retryable capacity errors before acquisition. Shutdown closes admission and drains accepted work. Failed descriptor/process/workspace cleanup remains owned for retry and completed observations remain available after cancellation/cleanup errors.

Contract and boundary impact

  • Semantic owner: shared domain contracts/text-window semantics and SignalRecordingService; adapter owns sigrok arguments, execution, artifact identity and diagnostics.
  • Contribution scope: offline analysis of caller-selected existing recordings, explicitly requested by the maintainer. Target execution/injection/mutation/protection-recovery decision is not applicable.
  • CLI/MCP: additive decode-signal-recording / decode_signal_recording, no binary target required. Required recording path and decoder selection; output includes { total_lines, returned_lines, has_more } and exact selections.
  • Compatibility: Linux with sigrok-cli 0.7.2 / libsigrokdecode and util-linux. Unsupported hosts fail before workspace allocation; unavailable configuration has actionable discovery diagnostics.
  • Evidence/provenance: source path/digest/size, exact decoder selections, configured/resolved executable and limiter identities, full library-version banner, argv, stderr, effective limits and explicit hardware-acquisition status.
  • Authority/cleanup: read source; launch owned local analyzer; write private read-only copy/temporary workspace. No device acquisition or communication. Ambient environment is not serialized.
  • Metadata/install: authored skill/guides, CLI/capability/catalog sources and translated capability rows updated; ignored generated catalogs/builds remain uncommitted. No npm dependency or installer change.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process (owned analyzer).
  • Change files or configuration (private temporary workspace only).

Evidence and regression coverage

  • Six regressions failed against the imported provider before fixes: admission after shutdown, excess queued admission, and lost ownership of recording/executable/limiter/kernel-report descriptors after close failure. New tests prove refusal of further acquisition and successful retained cleanup retry.

  • Seven focused provider/CLI/MCP/kernel/text-window files: 42 passed. Three integrated capability/effect/SDK-schema files: 32 passed. Literal text tests cover blank lines, CRLF, missing final newline, huge offsets and source code-unit preservation.

  • Real compiled CLI/MCP verifier: 9 cases, including known UART bytes, autodetection/filtering, default/later/full windows, advertised schemas, Evidence IDs/persistence, errors, source identity and cleanup. CLI rejects conflicting full/page options and oversized encoded selectors before invoking the service.

  • Public sigrok-dumps recordings pinned to 0ad13477: STM32 UART hello-world, ATmega328P nine-bit counter, MAX7219 SPI LED traffic and Samsung monitor I2C/EDID. Git blob identities and SHA-256 verified. Independent UART checks recover Hello World!\r\n three times and the complete 0–511 counter cycle. Direct sigrok output and REA output match exactly; full output and source identity remain identical after optimization.

  • Fifteen baseline and thirty optimized/full real-data MCP calls, three repetitions per case, all passed. Physical acquisition and additional decoder/format/platform combinations remain unverified; these tests analyze published recordings and synthesized UART VCDs.

  • Observed, derived and inferred claims remain distinguishable.

  • Artifact identity, provenance and failed attempts remain preserved.

  • Unsupported/incomplete outcomes remain visible.

Validation performed

  • npm run check, npm run docs:check, npm run verify:test-discovery — passed on refreshed main.
  • npm run test:focused -- the files above — 42 provider cases and 32 integrated schema/capability/effect cases passed.
  • REA_SIGROK_COMMAND=/usr/bin/sigrok-cli node scripts/verify-signal-recording.mjs — 9 real CLI/MCP cases passed again with final runtime (Debian 12, sigrok-cli 0.7.2, libsigrok 0.5.2, libsigrokdecode 0.5.3).
  • Shared-owner regression run: 86 cases across 13 TShark/sigrok/kernel/CLI/MCP files passed; both real verifiers passed again (15 TShark / 9 sigrok cases).
  • npm run jscpd — passed at 2.99%, without changing the 3% gate. The initial own-PR failure at 3.03% was fixed by removing duplicated ownership/failure interpretation.
  • git diff --check — passed; no recordings, binaries, dependency/build outputs or private lab artifacts committed.

Performance on the nine-bit UART: default text 171,827 → 5,171 bytes; annotation text 161,331 → 1,028 bytes / 50 lines. Explicit full output exactly retains 6,540 lines (171,971 response bytes including new metadata). Default-call latency 0.42–0.63 s in the latest run; baseline 0.29–0.38 s. Earlier local paged runs measured 0.25–0.42 s; no decoding-speed improvement is claimed. An alternating same-host A/B ran eight calls per version with identical reports; excluding the first warm-up pair, medians were 288.49 ms before and 289.18 ms after sharing the owner. Those measurements do not establish a meaningful speedup or an equivalent slowdown to the earlier between-run difference. EDID text 37,855 → 5,175 bytes. Warm MCP processes, fresh native decoder processes, no filesystem-cache flushing, two CPU cores and an 8 GiB family-RSS guard. The latest 30-call optimized/full run peaked at 543.41 MiB family RSS; all guarded local work remained below 8 GiB.

For inspecting the first 50 UART output lines, o200k_base estimates include one actually advertised tool definition, one request and response text: 83,315 → 5,738 tokens (definition overhead 3,054 → 3,769). Estimates are not billed usage; other catalog tools, prompt conversion, reasoning and subsequent calls are unmeasured. Paging does not avoid native decoding; later calls recheck the source and rerun the producer. No cache claim is made.

Compatibility, safety, and release

New feature; no previously released signal-tool call changes. Input <=32 MiB, combined command stdout/stderr <=4 MiB, 30-second deadlines. Enforce both soft/hard ceilings of at most 1 GiB address space, 64 MiB per file, 30 CPU seconds and no core dumps, preserving stricter inherited limits. Selectors are limited to 8,192 UTF-16 units each and 32 KiB total encoded arguments before expansion/launch.

Caller-supplied tools, limiter, libraries and decoder modules remain trusted and are not fully fingerprinted. This is not an OS sandbox or an aggregate memory/filesystem quota. Output paging does not bypass producer-output limits; annotation-class selection can reduce native output. Display annotations remain decoder interpretations, not independently verified protocol facts.

Before merge

  • Agreed enhancement and resolved material scope.
  • Focused outcome and Conventional Commit title.
  • Original PR linked; no linked issue exists.
  • Observable behavior and meaningful failure paths covered.
  • Owning docs/contracts/generated sources updated.
  • Representative CLI/MCP behavior included.
  • Final diff checked for secrets, unrelated changes and unsupported claims.
  • Applicable CI and review findings checked.

Final CI: all 39 checks passed for 507ecd28818426675fff7e69d01b15198419ea0a, including required CI, real sigrok/TShark, static/duplication/docs checks, all test shards, coverage and native packages. The own duplication failure was corrected by shared resource/failure ownership. Automatic Codex review could not execute because repository review credits were exhausted; no code findings were supplied. Own source inspection, reproduced regressions, real-provider verification and performance A/B were completed.

Merged as 91b8f587cd495c509946e69076525eb19dc1ca65.

Post-merge verification on 91b8f587cd495c509946e69076525eb19dc1ca65: runtime build passed; SQLite public/runtime suite 105 passed / 2 expected skips; real TShark verifier 15 cases passed; real sigrok verifier 9 cases passed. All 50 feature files exactly match the tested PR head; concurrently merged main changes are included in this verification. No guard stop; final verification peaked at 1,753.20 MiB family RSS.


🔄 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/2339 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/12/2026 **Status:** ✅ Merged **Merged:** 10/12/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `feat/sigrok-analysis-2126-20261012` --- ### 📝 Commits (2) - [`3064691`](https://github.com/morluto/rea/commit/3064691155880d6550745b6360880d08dc0e18f5) feat(signals): decode recordings with bounded sigrok output - [`507ecd2`](https://github.com/morluto/rea/commit/507ecd28818426675fff7e69d01b15198419ea0a) refactor(process): share recorded-analysis resource ownership ### 📊 Changes **50 files changed** (+2715 additions, -252 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+7 -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` (+20 -19) 📝 `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` (+20 -19) 📝 `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 30 more files_ </details> ### 📄 Description ## Summary Decode selected protocols from an existing logic recording through shared CLI/MCP Evidence. This replaces #2126, credited to Olorinm, with current-main integration, bounded output, selector budgets and cleanup regressions. There is no linked issue. ## Problem and expected behavior An analyst with a recorded UART/I2C/SPI signal needs explicit decoder/channel/options and useful output without hardware acquisition. A real nine-bit UART recording produced 6,540 display lines and 171,827 bytes of response text. The default now returns 50 literal lines with explicit coverage, while later pages and full output remain available. ## Change and scope Linux-only sigrok-cli 0.7.2 with libsigrokdecode and trusted util-linux `prlimit`; caller supplies absolute `REA_SIGROK_COMMAND`. Preserve decoder stack/channel/options, input-format autodetection or explicit format, annotation-class selection, producer warnings and source/tool identity. Page output after complete decoding. `line_offset` defaults to 0, `line_limit` to 50; MCP `line_limit: null` / CLI `--all_lines` returns all remaining output. Preserve exact selected text, sample ranges, CRLF/LF, blank lines and UTF-16 code units. Window counts refer to literal LF-separated **display lines**, not annotations or samples. Do not parse frontend display text into a lossless protocol payload. Partial windows own a copied string so retained Evidence does not retain the entire producer string. Reuse existing process supervision, artifact descriptor ownership and shared MCP admission/Evidence delivery. TShark and sigrok now share one `ArtifactAnalysisResources` owner for admission, descriptors, producer/workspace cleanup, retained partial observations and interpretation of owned-command failure facts. Superseded provider-local maps, queues and error-mapping copies are removed. One decode at a time; excess requests fail with retryable capacity errors before acquisition. Shutdown closes admission and drains accepted work. Failed descriptor/process/workspace cleanup remains owned for retry and completed observations remain available after cancellation/cleanup errors. ## Contract and boundary impact - Semantic owner: shared domain contracts/text-window semantics and `SignalRecordingService`; adapter owns sigrok arguments, execution, artifact identity and diagnostics. - Contribution scope: offline analysis of caller-selected existing recordings, explicitly requested by the maintainer. Target execution/injection/mutation/protection-recovery decision is not applicable. - CLI/MCP: additive `decode-signal-recording` / `decode_signal_recording`, no binary target required. Required recording path and decoder selection; output includes `{ total_lines, returned_lines, has_more }` and exact selections. - Compatibility: Linux with sigrok-cli 0.7.2 / libsigrokdecode and util-linux. Unsupported hosts fail before workspace allocation; unavailable configuration has actionable discovery diagnostics. - Evidence/provenance: source path/digest/size, exact decoder selections, configured/resolved executable and limiter identities, full library-version banner, argv, stderr, effective limits and explicit hardware-acquisition status. - Authority/cleanup: read source; launch owned local analyzer; write private read-only copy/temporary workspace. No device acquisition or communication. Ambient environment is not serialized. - Metadata/install: authored skill/guides, CLI/capability/catalog sources and translated capability rows updated; ignored generated catalogs/builds remain uncommitted. No npm dependency or installer change. Expected effects: - [x] Read existing files or captured data. - [x] Launch or attach to a process (owned analyzer). - [x] Change files or configuration (private temporary workspace only). ## Evidence and regression coverage - Six regressions failed against the imported provider before fixes: admission after shutdown, excess queued admission, and lost ownership of recording/executable/limiter/kernel-report descriptors after close failure. New tests prove refusal of further acquisition and successful retained cleanup retry. - Seven focused provider/CLI/MCP/kernel/text-window files: 42 passed. Three integrated capability/effect/SDK-schema files: 32 passed. Literal text tests cover blank lines, CRLF, missing final newline, huge offsets and source code-unit preservation. - Real compiled CLI/MCP verifier: 9 cases, including known UART bytes, autodetection/filtering, default/later/full windows, advertised schemas, Evidence IDs/persistence, errors, source identity and cleanup. CLI rejects conflicting full/page options and oversized encoded selectors before invoking the service. - [Public sigrok-dumps recordings pinned to `0ad13477`](https://github.com/sigrokproject/sigrok-dumps/tree/0ad13477abc959d37fc9a5acbd23901c371c9c76): STM32 UART hello-world, ATmega328P nine-bit counter, MAX7219 SPI LED traffic and Samsung monitor I2C/EDID. Git blob identities and SHA-256 verified. Independent UART checks recover `Hello World!\r\n` three times and the complete 0–511 counter cycle. Direct sigrok output and REA output match exactly; full output and source identity remain identical after optimization. - Fifteen baseline and thirty optimized/full real-data MCP calls, three repetitions per case, all passed. Physical acquisition and additional decoder/format/platform combinations remain unverified; these tests analyze published recordings and synthesized UART VCDs. - [x] Observed, derived and inferred claims remain distinguishable. - [x] Artifact identity, provenance and failed attempts remain preserved. - [x] Unsupported/incomplete outcomes remain visible. ## Validation performed - `npm run check`, `npm run docs:check`, `npm run verify:test-discovery` — passed on refreshed main. - `npm run test:focused --` the files above — 42 provider cases and 32 integrated schema/capability/effect cases passed. - `REA_SIGROK_COMMAND=/usr/bin/sigrok-cli node scripts/verify-signal-recording.mjs` — 9 real CLI/MCP cases passed again with final runtime (Debian 12, sigrok-cli 0.7.2, libsigrok 0.5.2, libsigrokdecode 0.5.3). - Shared-owner regression run: 86 cases across 13 TShark/sigrok/kernel/CLI/MCP files passed; both real verifiers passed again (15 TShark / 9 sigrok cases). - `npm run jscpd` — passed at 2.99%, without changing the 3% gate. The initial own-PR failure at 3.03% was fixed by removing duplicated ownership/failure interpretation. - `git diff --check` — passed; no recordings, binaries, dependency/build outputs or private lab artifacts committed. Performance on the nine-bit UART: default text 171,827 → 5,171 bytes; annotation text 161,331 → 1,028 bytes / 50 lines. Explicit full output exactly retains 6,540 lines (171,971 response bytes including new metadata). Default-call latency 0.42–0.63 s in the latest run; baseline 0.29–0.38 s. Earlier local paged runs measured 0.25–0.42 s; no decoding-speed improvement is claimed. An alternating same-host A/B ran eight calls per version with identical reports; excluding the first warm-up pair, medians were 288.49 ms before and 289.18 ms after sharing the owner. Those measurements do not establish a meaningful speedup or an equivalent slowdown to the earlier between-run difference. EDID text 37,855 → 5,175 bytes. Warm MCP processes, fresh native decoder processes, no filesystem-cache flushing, two CPU cores and an 8 GiB family-RSS guard. The latest 30-call optimized/full run peaked at 543.41 MiB family RSS; all guarded local work remained below 8 GiB. For inspecting the first 50 UART output lines, `o200k_base` estimates include one actually advertised tool definition, one request and response text: 83,315 → 5,738 tokens (definition overhead 3,054 → 3,769). Estimates are not billed usage; other catalog tools, prompt conversion, reasoning and subsequent calls are unmeasured. Paging does not avoid native decoding; later calls recheck the source and rerun the producer. No cache claim is made. ## Compatibility, safety, and release New feature; no previously released signal-tool call changes. Input <=32 MiB, combined command stdout/stderr <=4 MiB, 30-second deadlines. Enforce both soft/hard ceilings of at most 1 GiB address space, 64 MiB per file, 30 CPU seconds and no core dumps, preserving stricter inherited limits. Selectors are limited to 8,192 UTF-16 units each and 32 KiB total encoded arguments before expansion/launch. Caller-supplied tools, limiter, libraries and decoder modules remain trusted and are not fully fingerprinted. This is not an OS sandbox or an aggregate memory/filesystem quota. Output paging does not bypass producer-output limits; annotation-class selection can reduce native output. Display annotations remain decoder interpretations, not independently verified protocol facts. ## Before merge - [x] Agreed enhancement and resolved material scope. - [x] Focused outcome and Conventional Commit title. - [x] Original PR linked; no linked issue exists. - [x] Observable behavior and meaningful failure paths covered. - [x] Owning docs/contracts/generated sources updated. - [x] Representative CLI/MCP behavior included. - [x] Final diff checked for secrets, unrelated changes and unsupported claims. - [x] Applicable CI and review findings checked. Final CI: all 39 checks passed for `507ecd28818426675fff7e69d01b15198419ea0a`, including required CI, real sigrok/TShark, static/duplication/docs checks, all test shards, coverage and native packages. The own duplication failure was corrected by shared resource/failure ownership. Automatic Codex review could not execute because repository review credits were exhausted; no code findings were supplied. Own source inspection, reproduced regressions, real-provider verification and performance A/B were completed. Merged as `91b8f587cd495c509946e69076525eb19dc1ca65`. Post-merge verification on `91b8f587cd495c509946e69076525eb19dc1ca65`: runtime build passed; SQLite public/runtime suite 105 passed / 2 expected skips; real TShark verifier 15 cases passed; real sigrok verifier 9 cases passed. All 50 feature files exactly match the tested PR head; concurrently merged main changes are included in this verification. No guard stop; final verification peaked at 1,753.20 MiB family RSS. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-31 01:04:32 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#5172
No description provided.