6.0 KiB
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
checkexits 0.--refsis an independent Markdown-link check and can makecheckfail; on failure the emit target is removed. Do not generate a consumer artifact withcheck --refs --emitwithout 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.
checkdoes 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_digestmust 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-filedoes not emit Analysis itself.- Event kinds:
call.enter,call.exit,branch.eval,loop.iteration,return,effect, and possiblytrace.truncated. Sourced events carry a module id and a UTF-8 span. - Defaults are 100,000 events / 32 MiB;
--trace-max-eventsand--trace-max-bytesadjust 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,
seqstarts at 0 and is strictly increasing. Program stdout/stderr are onlystdout.chunk/stderr.chunkevents withencoding: "base64",data_base64and a matchingbyte_count. Concatenated decoded bytes equal a normal run's output; invalid UTF-8/NUL/binary bytes are preserved. stream.openedis always seq 0. A run then has at most onerun.startedand exactly one terminal event (run.completed,run.failed,run.rejected) on a complete stream. An EOF without a terminal event isincomplete(SIGKILL/crash/broken pipe); never synthesize success.run.started.sourcecontainsroot_idand thesha256:digest of the exact Analysis v2 bytes.--trace-filemay 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 NAMEand--observe-parameter NAMEare exact-name selections.Int/Float/Boolare bounded by--observe-max-value-bytes(default 256); selectedTextisredacteduntil--observe-text-valuesis also passed. Containers,Memory, resources and plugin handles areunsupported; handles are never serialized. - Structural/value events have a separate budget
(
--observe-max-events,--observe-max-bytes; defaults 100 000 / 16 MiB). Exhaustion emits oneobservation.truncatedand still delivers stdout/stderr and the terminal event. A broken output pipe fails the run withobserve.transport_failed; it never keeps executing side effects silently. --event-streamis mutually exclusive with--json, rejected bycheck/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/andcrates/cli/tests/execution_events.rs.
Consumer rules
- Reject unknown schema majors; there is no silent "use latest" fallback.
- Verify
source.analysis_digestagainst the actual Analysis file bytes. - Verify
source.root_id/package identity; do not key on absolute paths. - Be deterministic and offline; never execute
.mq.mdyourself, never invent host effects, and never inherit Marqdo grants. - Report an unsupported/stale artifact explicitly; do not silently downgrade.