Files
marqdo-cli/spec/trace-v2.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

4.8 KiB
Raw Permalink Blame History

Marqdo Trace v2

Status: implemented by marqdo run/call --trace-file <path> (S2). Supersedes Trace v1; v1 was never released and is kept as history.

1. Invariants

  • Tracing is observation, not execution. Only run/call 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). Both share one sequence.
  • The writer is atomic; an error run still records its terminal status.
  • No argument values, secrets, handles or file contents are recorded.
  • Trace capacity is a bounded observation budget. Reaching it truncates the trace; it never changes run.status or the program’s execution result. Execution budgets (--fuel, --timeout, ...) remain separate and still produce resource.exhausted.

2. Shape

{
  "schema": "marqdo.trace",
  "schema_version": 2,
  "run": {"id": "pid-nanos", "entry": "root:q@0.1.0::index.mq.md::main", "status": "ok"},
  "source": {"root_id": "root:q@0.1.0", "analysis_digest": "sha256:<64 hex>"},
  "limits": {"max_events": 100000, "max_bytes": 33554432},
  "truncated": null,
  "events": [
    {"seq": 0, "kind": "call.enter", "function_id": "root:q@0.1.0::index.mq.md::main",
     "module_id": "root:q@0.1.0::index.mq.md", "span": null, "detail": null},
    {"seq": 1, "kind": "effect", "module_id": "dep:p@0.1.0#<digest>::index.mq.md",
     "span": {"start": 40, "end": 52}, "detail": "ok", "operation": "print",
     "duration_micros": 3}
  ]
}

seq is globally increasing. run.status is ok or a stable runtime error code. Every span-bearing event has a module_id; the span is a UTF-8 byte offset range in that module. source only carries project identity and the Analysis digest; it does not identify the span owner.

source.root_id is the Analysis v2 project.root_id (root:<name>@<version> or sha256:<workspace snapshot>). source.analysis_digest is sha256: plus the SHA-256 of the exact Analysis v2 bytes produced for the same project with the same projection configuration. A consumer verifies it by hashing the Analysis file.

truncated is null or:

{"reason": "event_budget", "limit": 20, "written": 20}

reason is event_budget or byte_budget. When truncation occurs, the final event is {"kind":"trace.truncated","detail":<reason>,"module_id":null, "span":null,"seq":<one past the last written event>}.

3. Event kinds and span owners

kind detail module_id owner
call.enter null caller module (entry call: callee)
call.exit ok / return / error code caller module (entry call: callee)
return value type name current function’s module
branch.eval true / false current function’s module
loop.iteration continue / exit current function’s module
effect result summary module from ExecutionContext
trace.truncated event_budget / byte_budget null

function_id is always the canonical callee function id. Future kinds are additive; consumers must ignore unknown kinds. effect.operation names the HostOp (print, fs.read, ...).

4. Capacity

Defaults: 100 000 events and 32 MiB approximate serialized size. 0 means unlimited for either limit. run/call expose --trace-max-events and --trace-max-bytes; these are options on existing commands, not new commands. The host stops accepting events once a limit is reached; the writer also enforces the byte limit on the final serialized document, dropping trailing events and recording byte_budget. Semantic recording is disabled entirely when no trace was requested.

The trace array in run --json uses the same budget.

5. Staleness

A trace is stale when its source.analysis_digest differs from the digest of the Analysis emitted for the current document. Consumers must not present a stale trace as current. Moving a project does not change the manifest identity or digest; changing executable source does.

6. Worker transport limits

Plugin worker frames are a 4-byte big-endian length plus JSON, capped at 8 MiB (8 * 1024 * 1024). The wire request/result/capability caps are aligned to 8 MiB - 4096; error frames remain 1 MiB. A partial header, zero/oversized length, truncated payload or invalid JSON is a protocol error. A clean EOF is distinct from a protocol failure. The host marks a worker dead after a transport failure and never reuses its stdin.

7. Compatibility and tests

  • Consumers must reject unknown schema_version and validate module_id against Analysis modules.
  • JSON Schema: spec/schemas/trace-v2.schema.json.
  • tests/consumers/trace_consumer.py verifies identity, digest and event module references.
  • CLI tests cover call/effect events, no-secret redaction, error terminal status, and event-budget truncation without changing the run status.