Files
marqdo-cli/spec/trace-v1.md
T
cflmy b5a28a9825 feat(m0.6-r4): public Analysis v1 and Trace v1
- add check --emit with a deterministic, read-only semantic projection:
  package-aware modules, signatures, normalized bodies, refs, calls,
  diagnostics and source digests
- remove stale analysis artifacts on compile errors; atomic writes
- add run/call --trace-file with interpreter call/branch/loop/return events
  and host effect events under one sequence; redact values and record error
  status
- add Analysis/Trace v1 specs, ADR-0015 and an independent Python consumer
- add contract tests for determinism, stale artifacts, trace ordering/status
  and secret redaction
2026-11-20 11:46:37 +08:00

3.1 KiB

Marqdo Trace v1

Status: implemented by marqdo run/call --trace-file <path> (M0.6 R4).

1. Invariants

  • Tracing is observation, not execution. Only run/call can produce a trace; check, inspect and tool list never execute a document.
  • Events come from the interpreter (call.*, branch.eval, loop.iteration, return) and the host (effect).
  • The writer is atomic: a failed run does not leave a partially written JSON file; an error run still records the terminal status if execution started.
  • No argument values, secrets, plugin handles or file contents are recorded. Effect detail is a result summary (ok or a stable error code).
  • --trace keeps its existing human/JSON effect output; --trace-file is the versioned artifact and does not redefine --trace.

2. Shape

{
  "schema": "marqdo.trace",
  "schema_version": 1,
  "run": {"id": "pid-nanos", "entry": "root:default::index.mq.md::main", "status": "ok"},
  "source": {"root_id": "sha256:...", "analysis_digest": "sha256:..."},
  "events": [
    {"seq": 0, "kind": "call.enter", "function_id": "root:default::index.mq.md::main", "span": null, "detail": null},
    {"seq": 1, "kind": "effect", "module": "root:default::index.mq.md", "span": {"start": 40, "end": 52}, "detail": "ok", "operation": "print", "duration_micros": 3},
    {"seq": 2, "kind": "call.exit", "function_id": "root:default::index.mq.md::main", "span": null, "detail": "ok"}
  ]
}

seq is globally increasing within one run (semantic and effect events share the counter). run.status is ok or a stable runtime error code. Span fields use UTF-8 byte offsets into the source identified by source.root_id and source.analysis_digest.

3. Event kinds

kind detail Meaning
call.enter null function entry; function_id is canonical
call.exit ok / return / error code function exit
return value type name explicit Emph return; no value content
branch.eval true / false ordered-list branch condition
loop.iteration continue / exit bullet-list loop condition
effect result summary a HostOp effect; operation names it

Future event kinds are additive. Consumers must ignore unknown kinds rather than guessing their semantics.

4. Staleness

source.analysis_digest is the digest of the Analysis v1 projection built from the same loaded project. If a consumer compares it with a newer analysis and the digest differs, the trace is stale and must not be presented as the current document's execution.

5. Privacy and limits

  • Values and secrets are never serialized into a trace.
  • Foreign/plugin effects record only the operation and success/error summary.
  • A trace file can be large for long loops; the current implementation has no event-count cap, but consumers must stream/limit. A future version may add a bounded mode.
  • A failed/aborted run records the status it reached; it is never marked successful.

6. Not included

Interactive breakpoints, a debug server, time travel, notebook sessions, WebSocket streaming and full argument-value capture are out of scope for v1.