Files
marqdo-cli/spec/trace-v1.md
T
cflmy 49835424ee docs(spec): adopt RFC-LANG-0002 unified language semantics
Replace the Strong/Emph/List/Quote mapping in place with the single
@exec/@knowledge heading-mode model, unified payload carriers and keyword
control flow.

- add the authoritative RFC, ADR-0052 and a historical ADR index
- rewrite spec/mapping.md and spec/expression.ebnf as the normative
  mapping/statement grammar; update evaluation, references, math,
  foreign, package-format, plugin-abi, security and schema notes
- rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking
  language change; update the architecture index/overview and active docs
- mark superseded planning docs, compute RFCs, evidence and syntax-role
  ADRs as historical/superseded without rewriting their decisions
- add migration guide, per-file inventory and dev-only audit scripts

The frontend/stdlib migration is completed in the following commits; this
commit contains documentation only.
2026-11-21 12:24:19 +08:00

3.2 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 return statement; no value content
branch.eval true / false if condition for an if/else/end group
loop.iteration continue / exit while condition for a while/end group
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.