Files
marqdo-cli/spec/trace-v1.md
T
cflmy d890686a2b feat(trace): Trace v2 identity, module-owned events and capacity bounds (B-16)
- bind traces to the logical project identity and the exact emitted Analysis
  digest; every span-bearing event carries module_id
- add host TraceState budgets (100k events / 32 MiB defaults), CLI
  --trace-max-events/--trace-max-bytes, terminal trace.truncated events, and a
  final serialized byte cap; budgets never change run.status
- disable semantic recording when no trace is requested
- cap worker frames at 8 MiB, align request/result/capability wire caps, make
  clean EOF distinct from protocol errors, and mark/kill a worker after a
  transport failure instead of reusing it
- add trace-v2 spec/schema, independent trace consumer, CI check and tests
- record the S2/C state in STATUS
2026-11-20 13:01:22 +08:00

3.1 KiB

Marqdo Trace v1

Status: superseded by Trace v2; never released, do not write v1. Kept as history.

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.