# Analysis v2 and Trace v2 consumers Both are public, versioned JSON artifacts. A consumer must read them as files, never link Marqdo's Rust internals or depend on `inspect --ir`. ## Analysis v2 (static) ```bash marqdo check index.mq.md --emit ./analysis.json ``` - Write atomically; only publish after `check` exits 0. `--refs` is an independent Markdown-link check and can make `check` fail; on failure the emit target is removed. Do not generate a consumer artifact with `check --refs --emit` without checking the exit code. - `schema: "marqdo.analysis"`, `schema_version: 2`. - Top level: `producer` (`name`, `version` = product version, `markdown_profile`), `project`, `modules`, `diagnostics`. - `project`: `root_id` (`root:@` for manifest projects), `identity_kind`, `lock_digest` (`""` without a lock), `stdlib` (`version`, `digest`, `instance_id`; may be null). - `modules[]`: `id`, `package_instance_id`, `relative_path`, `source_digest`, `units`, `functions`, `imports`, `references`, `calls`, `resources`. Diagnostics are top-level, not per-module. - Byte offsets are UTF-8 source offsets. Stable index keys are logical package instance ids, never absolute paths. - `check` does not load plugin libraries, start kernels/providers or execute the program. - Schemas: `spec/schemas/analysis-v2.schema.json`; contract: `spec/analysis-v2.md`; consumers: `tests/consumers/analysis_consumer.py`, `tests/consumers/validate_protocols.py`. View must render the **original Markdown** and use Analysis only to correlate source offsets/heading units/callable mapping. Knowledge must use heading anchors, links, resources, package identity and source digests; it must not assume a `@knowledge` unit has runtime effects. Prove must map only the public proveable subset and distinguish `proved / disproved / unknown / unsupported`; a proof certificate needs matching source digest, semantics and contract identity. ## Trace v2 (dynamic) ```bash marqdo run index.mq.md --trace-file ./trace.json ``` - `schema: "marqdo.trace"`, `schema_version: 2`. - `source.analysis_digest` must equal SHA-256 of the **Analysis JSON bytes** for the same project/projection configuration. A mismatch means the trace is stale; do not bind it to the new source. `run --trace-file` does not emit Analysis itself. - Event kinds: `call.enter`, `call.exit`, `branch.eval`, `loop.iteration`, `return`, `effect`, and possibly `trace.truncated`. Sourced events carry a module id and a UTF-8 span. - Defaults are 100,000 events / 32 MiB; `--trace-max-events` and `--trace-max-bytes` adjust them (`0` = unlimited). A consumer must tolerate truncation and must not assume the trace is complete. - Trace records no argument values, secrets or file contents. - Contract: `spec/trace-v2.md`; schema: `spec/schemas/trace-v2.schema.json`; consumer: `tests/consumers/trace_consumer.py`. ## Execution Events v1 (live) ```bash marqdo run index.mq.md --event-stream jsonl marqdo call index.mq.md main --arg n=5 --event-stream jsonl marqdo run index.mq.md --event-stream jsonl --trace-file ./trace.json ``` - `schema: "marqdo.execution-events"`, `schema_version: 1`. This is a separate protocol from Analysis/Trace and has its own version axis. - While active, the CLI stdout is a **pure NDJSON channel**: one JSON object per line, `seq` starts at 0 and is strictly increasing. Program stdout/stderr are only `stdout.chunk`/`stderr.chunk` events with `encoding: "base64"`, `data_base64` and a matching `byte_count`. Concatenated decoded bytes equal a normal run's output; invalid UTF-8/NUL/binary bytes are preserved. - `stream.opened` is always seq 0. A run then has at most one `run.started` and exactly one terminal event (`run.completed`, `run.failed`, `run.rejected`) on a complete stream. An EOF without a terminal event is `incomplete` (SIGKILL/crash/broken pipe); never synthesize success. - `run.started.source` contains `root_id` and the `sha256:` digest of the exact Analysis v2 bytes. `--trace-file` may be combined; both writers share one opaque run id, and Trace v2 remains atomic and value-free. - Structural events: `call.enter`/`call.exit` (`frame_id`, `parent_frame_id`), `return`, `branch.eval`, `loop.iteration`, `effect`. Frames identify call instances, not functions; a failed argument binding creates no frame. - Values are off by default (`value_state: not_requested`). `--observe-variable NAME` and `--observe-parameter NAME` are exact-name selections. `Int`/`Float`/`Bool` are bounded by `--observe-max-value-bytes` (default 256); selected `Text` is `redacted` until `--observe-text-values` is also passed. Containers, `Memory`, resources and plugin handles are `unsupported`; handles are never serialized. - Structural/value events have a separate budget (`--observe-max-events`, `--observe-max-bytes`; defaults 100 000 / 16 MiB). Exhaustion emits one `observation.truncated` and still delivers stdout/stderr and the terminal event. A broken output pipe fails the run with `observe.transport_failed`; it never keeps executing side effects silently. - `--event-stream` is mutually exclusive with `--json`, rejected by `check`/`inspect`/`fmt`/`tool`, and currently rejected by `--mode strict` (fail-closed, no downgrade). It is not a capability grant. - Contract: [`../../spec/execution-events-v1.md`](../../spec/execution-events-v1.md); schema: `spec/schemas/execution-events-v1.schema.json`; consumer: `tests/consumers/execution_events_consumer.py`; fixtures and Rust gate: `tests/consumers/fixtures/execution-events/` and `crates/cli/tests/execution_events.rs`. ## Consumer rules 1. Reject unknown schema majors; there is no silent "use latest" fallback. 2. Verify `source.analysis_digest` against the actual Analysis file bytes. 3. Verify `source.root_id`/package identity; do not key on absolute paths. 4. Be deterministic and offline; never execute `.mq.md` yourself, never invent host effects, and never inherit Marqdo grants. 5. Report an unsupported/stale artifact explicitly; do not silently downgrade.