Files
marqdo-cli/docs/developers/analysis-trace.md
T

6.0 KiB

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)

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:<name>@<version> 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)

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)

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; 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.