Files
marqdo-cli/docs/adr/0059-runtime-observability-and-execution-events.md
T

148 lines
8.0 KiB
Markdown

# ADR-0059: Runtime observability and Execution Events v1
- **Status:** Accepted
- **Date:** 2026-11-22
- **Decision owners:** CLI, runtime and host maintainers
- **Inputs:** [RFC-OBS-0001](../architecture/RFC-OBS-0001-runtime-observability.md)
(issue `#1` of `cflmy/marqdo-cli`), [Trace v2](../../spec/trace-v2.md),
[Analysis v2](../../spec/analysis-v2.md), [Tool Protocol v1](../../spec/tool-v1.md)
## Context
Marqdo has two public, versioned machine-readable artifacts: Analysis v2
(static, never executes) and Trace v2 (one complete document published
atomically after a run). Neither can stream program stdout/stderr while a task
is still running, and Trace v2 deliberately has no argument or local-variable
values.
External tools (`marqdo-view`, agents, IDEs, Knowledge/Prove) therefore had two
bad options: parse human terminal output, or embed/link private runtime types
and build a second execution path. Both break the repository boundary this
project exists to maintain: **the CLI is the only runtime**.
## Decision
1. **A third, independent public protocol exists: Execution Events v1.**
* `schema = "marqdo.execution-events"`, `schema_version = 1`.
* It is a one-way NDJSON (JSON Lines) stream over the CLI's protocol stdout.
* It is **not** Trace v2, not Analysis v2 and not Tool Protocol v1. Each has
its own version axis. Adding optional events/fields is allowed in v1;
changing required field meaning, ordering, redaction promises or the
source-digest definition requires a new major.
* The CLI implements no HTTP, SSE, WebSocket, browser session or
View/Agent/IDE-specific branch. Consumers convert the stream themselves.
2. **The stream is opt-in and never changes semantics.**
`marqdo run/call --event-stream jsonl` turns the CLI stdout into a pure
JSONL channel. Without the option, stdout, stderr, exit codes, Trace and
Analysis behavior are byte-for-byte unchanged. Observation is not a
capability grant and cannot widen `pure/project/strict` authorization.
3. **`--event-stream jsonl` and `--json` are mutually exclusive.**
`--trace-file` may be combined; Trace v2 keeps its atomic, post-run,
low-sensitivity contract. Program stdout/stderr are encapsulated as
`stdout.chunk`/`stderr.chunk` events and are never written raw to the
protocol stdout.
4. **Events are emitted at real commit points, not from final buffers.**
Stdout/stderr chunks originate in `StdHost::resource_write` immediately
after the host accepts and commits bytes, inside the same budget path. The
final `take_output()` buffer is never split into fake "live" chunks.
Selected local-variable events originate after the assignment has been
committed to `Frame.locals`; a rejected memory write never produces a
success event.
5. **The host owns the observation facade.**
`marqdo-host::observe` defines typed internal events (`ObservationEvent`),
the `ObservationSink` trait, `ObservationConfig`, frame identity
(`FrameId`) and the observation budget. The runtime emits borrowed events
through default `Host` methods; it never hands the sink `Frame.locals`,
the whole `MemoryStore`, or raw OS handles. The CLI owns only JSONL
encoding and the public envelope. No new crate is introduced.
6. **Call instances get an opaque identity.**
Each entered frame gets a run-unique `frame_id` (`f1`, `f2`, ...) and a
`parent_frame_id` (`null` at the top level). Frame IDs exist only in
Execution Events v1; Trace v2 is not given a new field. Argument binding
happens before a frame is announced, so a failed binding never produces a
dangling frame.
7. **Values are selected, bounded and off by default.**
* Default event mode publishes types/status only (`value_state:
not_requested`).
* `--observe-variable NAME` / `--observe-parameter NAME` are exact-name,
repeatable selections. There is no wildcard, regex, path expression or
`--dump-all-locals`.
* Supported value types are the scalars `Int`, `Float`, `Bool`; `Text`
additionally requires `--observe-text-values`. Lists, maps, tables,
formulas, code, memory, resources and plugin handles report
`unsupported` and are never expanded or serialized by `Debug`.
* Every value is capped by `--observe-max-value-bytes` (default 256) and
reports `not_requested`, `redacted`, `truncated`, `unsupported` or
`observed` distinctly. A text truncation never splits a UTF-8 scalar.
* Observation lowers confidentiality: it is an explicit developer action.
It is never enabled from a project manifest, never recorded in Trace v2
or Analysis v2, and never automatically enabled by View.
8. **Budgets, ordering and failure are defined.**
* One dispatcher assigns `seq` from 0; stdout/stderr, structural and value
events share the observable order of admission.
* Structural/value events have a bounded budget (default 100 000 events /
16 MiB). Exhaustion emits one `observation.truncated` and stops only
non-critical events; stdout/stderr and the terminal event still flow.
* `stream.opened` (seq 0), `run.started`, stdout/stderr and the terminal
`run.completed`/`run.failed`/`run.rejected` are not dropped by the
structural budget.
* Writes are bounded and synchronous: a slow consumer applies IO
backpressure instead of growing an unbounded queue. A write failure
aborts the run with `observe.transport_failed`; the CLI must not keep
executing a program with side effects after its event pipe broke, and it
must not write a half JSON line.
* A killed/crashed process may have no terminal event. Consumers must
report `incomplete`, never synthesize success.
9. **`run.rejected` covers pre-execution failure in event mode.**
After the writer is open, prepare/authorization/compile failures produce a
structured terminal `run.rejected` with the existing stable error code and
phase, a non-zero exit, and no `run.started`. CLI option parsing errors
still use the ordinary clap stderr path before the protocol exists.
10. **The source binding is the Analysis digest.**
`run.started.payload.source` carries `root_id` and
`analysis_digest` = `sha256:` plus the SHA-256 of the exact Analysis v2
bytes for the same project/projection configuration. A changed source
makes old events stale; consumers must not render them onto new source.
11. **The Trace v2 run identity is shared, without changing Trace v2.**
In a combined run the CLI composition root creates one opaque `run_id` and
passes it to both writers, so `trace.run.id == execution stream run_id`.
Trace v2 keeps `schema_version: 2` and gains no frame/value fields.
## Consequences
- External tools can consume live output with a released binary and a
documented schema; they still need no private Rust crate.
- The runtime gains observation hooks at existing commit points. The default
(no option) path installs no sink and does not clone `Value`s or serialize
observation data.
- The value policy is intentionally smaller than a debugger. Breakpoints,
stepping, time travel, raw memory snapshots, memory-byte events and a
bidirectional Debug Protocol remain a separate future RFC.
- Memory metadata events (`memory.region.*`, `memory.budget`) are P2 in
RFC-OBS-0001 and are **not** part of this decision's implemented scope; no
raw memory content or handle is ever exposed.
## Rejected alternatives
- **Stream Trace v2 while running.** Breaks existing complete-file consumers
and cannot naturally carry live stdout/stderr or reject-before-run events.
- **Make events a flag of `--json`.** Mixes a complete result envelope with a
line stream on one channel and violates the clean-stdout guarantee.
- **Emit stdout by splitting the final buffer.** It is not real-time and
defeats the purpose; the RFC explicitly forbids it.
- **Put JSONL/SSE/HTTP in the CLI.** Adds transport and product concerns to
the composition root; View's SSE belongs to the View repository.
- **Publish all locals as a default debugging dump.** Unbounded
confidentiality loss and no stable value encoding; rejected in favour of
exact, bounded selections.