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
This commit is contained in:
cflmy committed 2026-11-20 11:46:37 +08:00
1 parent 25a1faa6ef
commit b5a28a9825
16 files changed
+1365 -13

No files matched your search

+138
View File
@@ -0,0 +1,138 @@
# Marqdo Analysis v1
Status: **implemented by `marqdo check --emit <path>` (M0.6 R4).** This is a
public, read-only projection; it is not a dump of `marqdo-ir`.
## 1. Invariants
`check --emit`:
* never executes the document, loads a plugin shared library, starts a foreign
kernel or imports a module implicitly;
* validates the loaded program first; on a compile error it writes no artifact
and removes a stale file at the target path;
* writes atomically (temporary file + rename) only after a successful check;
* is deterministic: the same source, tool version and project path produce
byte-identical JSON (no timestamps, no random ids);
* exposes no private Rust layout, optimization instruction or host pointer.
## 2. Top-level shape
```json
{
"schema": "marqdo.analysis",
"schema_version": 1,
"producer": {"name": "marqdo", "version": "0.1.0", "markdown_profile": "marqdo.md.v1"},
"project": {"root_id": "sha256:...", "lock_digest": "sha256:..."},
"modules": [],
"diagnostics": []
}
```
* `root_id` is a digest of the normalized project root used for this run.
* `lock_digest` is a digest of `marqdo.lock`, or `""` when absent.
* Modules are sorted by canonical `id`; arrays keep source order.
* `schema_version` is a major version. Additive optional fields are allowed;
removing/renaming fields or changing units/types requires a major bump.
## 3. Modules
```json
{
"id": "root:default::index.mq.md",
"package_instance_id": "root:default",
"relative_path": "index.mq.md",
"source_digest": "<sha256 hex>",
"units": [],
"functions": [],
"imports": [],
"references": [],
"calls": [],
"resources": 0
}
```
Module identity is the package-aware `ModuleId` from
`spec/references.md` §2.1. `source_digest` hashes the exact source bytes.
### 3.1 Units
Each unit has `id`, `kind` (`root`/`namespace`/`function`/`section`), `name`,
`level`, `span` (`{start,end}` byte offsets) and optionally `function`.
### 3.2 Functions and signatures
```json
{
"id": "root:default::index.mq.md::数学.阶乘",
"unit_id": "root:default::index.mq.md#数学/阶乘",
"local_name": "阶乘",
"namespace": "数学",
"span": {"start": 0, "end": 100},
"heading_span": {"start": 0, "end": 10},
"signature": {
"kind": "inferred",
"params": [{"name": "n", "required": true, "type": null, "default": null, "span": {"start": 0, "end": 0}}]
},
"effects": ["unknown"],
"body": []
}
```
`kind` is `explicit` or `inferred`. Inferred signatures only accept named
arguments. `effects` is a **conservative** summary; `unknown` is not a proof of
purity. Dynamic ABI/Foreign targets remain unknown unless a descriptor says
otherwise.
### 3.3 Normalized body nodes
Body nodes use a small stable language, never internal IR serialization:
* `literal` (`type`: `int`/`float`/`text`/`bool`/`none`, `value` when present);
* `variable`, `list`, `record`, `member`, `index`;
* `unary` (`not`/`neg`/`pos`) and `binary` (`or`, `and`, `eq`, `ne`, `lt`,
`le`, `gt`, `ge`, `add`, `sub`, `mul`, `div`, `floor_div`, `mod`, `pow`);
* `call` with `callee` and `args`;
* `assign`, `expression`, `call_site`, `branch` (ordered arms), `loop`,
`return`.
Every node carries a byte `span`. Nodes outside the supported public subset
must be marked `unsupported` (future extension), never silently given invented
semantics.
### 3.4 Imports, references and calls
* `imports[]`: `{alias, target, span, resolved}`; `resolved` is a module id or
null. Imports stay explicit.
* `references[]`: Markdown link edges with `{source, url, span, state,
target_module, target_unit}`. `state` is `resolved`, `unresolved` or
`external`; a failed resolution is never disguised as bound.
* `calls[]`: `{function, span, callee, state, target}` where `state` is
`function`, `builtin`, `plugin` or `unresolved`.
Reference edges never execute anything and grant no capability.
## 4. Diagnostics
`diagnostics[]` uses the same stable codes/JSON shape as `marqdo check --json`.
An analysis emitted after a successful check normally has no error diagnostics
(warnings may remain).
## 5. Consumer contract
An independent consumer (Python/Go/JavaScript, without linking Rust crates)
must be able to:
* find a function by `id` and read its signature/body;
* find recursive/forward calls and `ref` edges;
* map every body node back to `source_digest` + byte span;
* reject `schema_version` it does not understand.
`tests/consumers/analysis_consumer.py` is one such black-box consumer and
`crates/cli/tests/analysis_trace.rs` runs it when Python is available.
## 6. Not included
Internal optimization IR, host pointers, plugin handles, proof status and
execution results are deliberately absent. Analysis does not claim that a
document runs successfully or that any function is proved.
+73
View File
@@ -0,0 +1,73 @@
# 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
```json
{
"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.