morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #330] Add reactive scenario algebra for process capture #176

New issue

Closed

opened 2026-10-15 18:22:04 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:22:04 +00:00

Owner

Originally created by @morluto on GitHub (Jul 20, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/330

Extend Process Capture v4 with a reactive algebra for process, terminal, filesystem, HTTP, WebSocket, and shim triggers, including all/any/sequence composition.

Reconstruction use case

High-fidelity differential scenarios need to react to observed state rather than sleep for guessed durations. A scenario should be able to:

wait for a terminal predicate;
send bytes, resize the PTY, close stdin, or signal an owned process;
wait for an HTTP/WebSocket/filesystem/process predicate;
record a named checkpoint;
continue through a finite state machine;
settle descendants and export the complete transition journal.

This must work when the interesting output is produced during teardown or by descendants after the root process begins closing.

Proposed trigger families

raw terminal bytes and rendered terminal text;
root/descendant spawn, exec, exit, signal, and settlement;
filesystem create/write/rename/delete/content/hash predicates;
HTTP request/response method, path, headers, and approved body-shape/value predicates;
WebSocket connection/frame/close predicates;
shim invocation/output/exit predicates;
elapsed deadline only as an explicit timeout/failure boundary, not the normal synchronization mechanism;
conjunction, disjunction, ordered sequence, repetition, and bounded cardinality.

Actions

write terminal bytes;
resize PTY;
close stdin;
send an approved signal to an owned process/group;
release or answer a loopback HTTP/WebSocket replay gate;
create a named filesystem/process/protocol checkpoint;
transition to another state;
terminate the scenario with a typed outcome.

Determinism and evidence

Record every trigger evaluation, matched source record, transition, action, checkpoint, deadline, and settlement result in Evidence v2.
Preserve raw event order and event identities.
Reject ambiguous references to multiple matching descendants unless the scenario declares selection/cardinality.
A timeout reports the active state, unmet predicates, latest relevant events, and accepted budget ranges.
Cancellation must stop trigger evaluation, close loopback peers, and clean up only owned processes/resources.
Never run arbitrary callback code supplied by the caller.

Acceptance criteria

Schemas reject invalid, cyclic-without-bound, impossible, and unsupported compositions.
Reactive triggers integrate with scenario deadlines and descendant settle conditions.
Terminal, process, filesystem, HTTP, WebSocket, and shim triggers have real-runtime fixtures.
Actions cover input, resize, stdin close, owned signals, replay-gate release, and checkpoints.
A scenario can wait for Ready, send SIGINT, then wait for a descendant HTTP terminal event and complete socket close without a sleep.
Transition traces are deterministic and Evidence v2-backed.
Concurrent trigger matches have explicit deterministic arbitration or declared ambiguity.
Cancellation and timeout clean up all owned resources and retain diagnostic evidence.
CLI and MCP expose exact schemas, actionable limits, progress, and cancellation.
The algebra composes with the finite replay machine in #334 and partial-order comparison in #403 without conflating interaction with assertion.

Part of #57.

Suggested scenario model

The public contract should be declarative and serializable. A representative shape (names illustrative) is:

{
  "version": 1,
  "initial_state": "starting",
  "deadline_ms": 30000,
  "states": {
    "starting": {
      "on": [{
        "when": {"terminal_text": {"stream": "pty", "matches": "Ready"}},
        "actions": [{"send_signal": {"target": "root", "signal": "SIGINT"}}],
        "goto": "stopping"
      }]
    },
    "stopping": {
      "on": [{
        "when": {"all": [
          {"http": {"path": "/shutdown", "phase": "response_complete"}},
          {"process": {"selector": "descendant:worker", "phase": "settled"}}
        ]},
        "actions": [{"checkpoint": "shutdown-complete"}],
        "finish": "passed"
      }]
    }
  }
}

Selectors must resolve against stable capture identities, not transient array positions. Text matching must declare raw bytes versus decoded/rendered text, encoding, case sensitivity, and whether ANSI/control sequences participate.

Evaluation semantics

Evaluate predicates against an append-only normalized event journal while retaining links to raw records.
Give each source event a stable ID, source-local sequence, capture timestamp, process identity, and Evidence location.
Define whether a transition consumes an event. Default to non-consuming observation; explicit consumption prevents one event from satisfying repeated transitions accidentally.
Snapshot the eligible event frontier on state entry so callers can choose since: scenario_start, state_entry, checkpoint, or an explicit event ID.
For simultaneous matches, require declared priority, all, or an ambiguity failure. Do not let listener registration order decide behavior.
Bound every repetition and state revisit. Validation should reject reachable unbounded cycles.
Separate interaction success from behavioral assertion: scenario execution produces a trace; #403 decides whether that trace belongs to an allowed language.

Typed outcomes and diagnostics

The result should distinguish at least passed, predicate_timeout, scenario_deadline, ambiguous_match, invalid_scenario, action_rejected, target_lost, capture_incomplete, cancelled, and cleanup_failed.

For a wait failure, return:

active state and time spent there;
canonical unmet predicate tree;
closest candidate events and why they did not match;
current process/connection inventory;
last successful transition/checkpoint;
whether evidence truncation could have hidden the match;
cleanup result and retained artifact references.

Limits and compatibility

Publish exact maxima for states, transitions, nesting depth, predicates, retained candidate events, runtime, and action count in CLI help and MCP schemas.
Version the scenario schema and reject unknown major versions.
Delay-based v4 scripts may be translated into deadline-triggered states for compatibility, but the translation must remain visible in evidence and diagnostics.
Unsupported trigger families should fail during preflight, before launching the target.

Delivery slices

Terminal/process predicates plus input, signal, checkpoint, cancellation, and a transition journal.
Filesystem and shim predicates with stable object identities.
HTTP/WebSocket predicates and replay-gate actions.
Composite/repeated predicates, deterministic arbitration, and migration helpers.
Integration with #334, #403, MCP progress/cancellation, and portable conformance output.

Originally created by @morluto on GitHub (Jul 20, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/330 Extend Process Capture v4 with a reactive algebra for process, terminal, filesystem, HTTP, WebSocket, and shim triggers, including `all`/`any`/`sequence` composition. ## Reconstruction use case High-fidelity differential scenarios need to react to observed state rather than sleep for guessed durations. A scenario should be able to: 1. wait for a terminal predicate; 2. send bytes, resize the PTY, close stdin, or signal an owned process; 3. wait for an HTTP/WebSocket/filesystem/process predicate; 4. record a named checkpoint; 5. continue through a finite state machine; 6. settle descendants and export the complete transition journal. This must work when the interesting output is produced during teardown or by descendants after the root process begins closing. ## Proposed trigger families - raw terminal bytes and rendered terminal text; - root/descendant spawn, exec, exit, signal, and settlement; - filesystem create/write/rename/delete/content/hash predicates; - HTTP request/response method, path, headers, and approved body-shape/value predicates; - WebSocket connection/frame/close predicates; - shim invocation/output/exit predicates; - elapsed deadline only as an explicit timeout/failure boundary, not the normal synchronization mechanism; - conjunction, disjunction, ordered sequence, repetition, and bounded cardinality. ## Actions - write terminal bytes; - resize PTY; - close stdin; - send an approved signal to an owned process/group; - release or answer a loopback HTTP/WebSocket replay gate; - create a named filesystem/process/protocol checkpoint; - transition to another state; - terminate the scenario with a typed outcome. ## Determinism and evidence - Record every trigger evaluation, matched source record, transition, action, checkpoint, deadline, and settlement result in Evidence v2. - Preserve raw event order and event identities. - Reject ambiguous references to multiple matching descendants unless the scenario declares selection/cardinality. - A timeout reports the active state, unmet predicates, latest relevant events, and accepted budget ranges. - Cancellation must stop trigger evaluation, close loopback peers, and clean up only owned processes/resources. - Never run arbitrary callback code supplied by the caller. ## Acceptance criteria - [ ] Schemas reject invalid, cyclic-without-bound, impossible, and unsupported compositions. - [ ] Reactive triggers integrate with scenario deadlines and descendant settle conditions. - [ ] Terminal, process, filesystem, HTTP, WebSocket, and shim triggers have real-runtime fixtures. - [ ] Actions cover input, resize, stdin close, owned signals, replay-gate release, and checkpoints. - [ ] A scenario can wait for `Ready`, send SIGINT, then wait for a descendant HTTP terminal event and complete socket close without a sleep. - [ ] Transition traces are deterministic and Evidence v2-backed. - [ ] Concurrent trigger matches have explicit deterministic arbitration or declared ambiguity. - [ ] Cancellation and timeout clean up all owned resources and retain diagnostic evidence. - [ ] CLI and MCP expose exact schemas, actionable limits, progress, and cancellation. - [ ] The algebra composes with the finite replay machine in #334 and partial-order comparison in #403 without conflating interaction with assertion. Part of #57. ## Suggested scenario model The public contract should be declarative and serializable. A representative shape (names illustrative) is: ```json { "version": 1, "initial_state": "starting", "deadline_ms": 30000, "states": { "starting": { "on": [{ "when": {"terminal_text": {"stream": "pty", "matches": "Ready"}}, "actions": [{"send_signal": {"target": "root", "signal": "SIGINT"}}], "goto": "stopping" }] }, "stopping": { "on": [{ "when": {"all": [ {"http": {"path": "/shutdown", "phase": "response_complete"}}, {"process": {"selector": "descendant:worker", "phase": "settled"}} ]}, "actions": [{"checkpoint": "shutdown-complete"}], "finish": "passed" }] } } } ``` Selectors must resolve against stable capture identities, not transient array positions. Text matching must declare raw bytes versus decoded/rendered text, encoding, case sensitivity, and whether ANSI/control sequences participate. ## Evaluation semantics - Evaluate predicates against an append-only normalized event journal while retaining links to raw records. - Give each source event a stable ID, source-local sequence, capture timestamp, process identity, and Evidence location. - Define whether a transition consumes an event. Default to non-consuming observation; explicit consumption prevents one event from satisfying repeated transitions accidentally. - Snapshot the eligible event frontier on state entry so callers can choose `since: scenario_start`, `state_entry`, `checkpoint`, or an explicit event ID. - For simultaneous matches, require declared priority, `all`, or an ambiguity failure. Do not let listener registration order decide behavior. - Bound every repetition and state revisit. Validation should reject reachable unbounded cycles. - Separate interaction success from behavioral assertion: scenario execution produces a trace; #403 decides whether that trace belongs to an allowed language. ## Typed outcomes and diagnostics The result should distinguish at least `passed`, `predicate_timeout`, `scenario_deadline`, `ambiguous_match`, `invalid_scenario`, `action_rejected`, `target_lost`, `capture_incomplete`, `cancelled`, and `cleanup_failed`. For a wait failure, return: - active state and time spent there; - canonical unmet predicate tree; - closest candidate events and why they did not match; - current process/connection inventory; - last successful transition/checkpoint; - whether evidence truncation could have hidden the match; - cleanup result and retained artifact references. ## Limits and compatibility - Publish exact maxima for states, transitions, nesting depth, predicates, retained candidate events, runtime, and action count in CLI help and MCP schemas. - Version the scenario schema and reject unknown major versions. - Delay-based v4 scripts may be translated into deadline-triggered states for compatibility, but the translation must remain visible in evidence and diagnostics. - Unsupported trigger families should fail during preflight, before launching the target. ## Delivery slices 1. Terminal/process predicates plus input, signal, checkpoint, cancellation, and a transition journal. 2. Filesystem and shim predicates with stable object identities. 3. HTTP/WebSocket predicates and replay-gate actions. 4. Composite/repeated predicates, deterministic arbitration, and migration helpers. 5. Integration with #334, #403, MCP progress/cancellation, and portable conformance output.

bsakaguchi

2026-10-15 18:22:04 +00:00

closed this issue
added the
P0: critical

enhancement
labels

bsakaguchi commented

2026-10-15 18:22:05 +00:00

Author

Owner

@morluto commented on GitHub (Jul 25, 2026):

Completed on current main. The versioned reactive scenario contract now covers terminal, process, filesystem, HTTP, WebSocket, and shim observations; bounded all/any/sequence/repeat predicates; deterministic priority and ambiguity handling; serialized effects; checkpoints; typed terminal outcomes; and a replayable transition journal. The real multi-source fixture and focused scenario/runtime/coordinator suites are present, while the linked replay-machine and partial-order comparison work in #334 and #403 is also complete. The full validation run exercised these suites successfully.

@morluto commented on GitHub (Jul 25, 2026): Completed on current main. The versioned reactive scenario contract now covers terminal, process, filesystem, HTTP, WebSocket, and shim observations; bounded all/any/sequence/repeat predicates; deterministic priority and ambiguity handling; serialized effects; checkpoints; typed terminal outcomes; and a replayable transition journal. The real multi-source fixture and focused scenario/runtime/coordinator suites are present, while the linked replay-machine and partial-order comparison work in #334 and #403 is also complete. The full validation run exercised these suites successfully.

bsakaguchi referenced this issue

2026-10-15 18:28:32 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-16 21:11:51 +00:00

[PR #207] [MERGED] fix(native): harden command capture edge cases #1858

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:28:48 +00:00