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:
1 parent
25a1faa6ef
commit
b5a28a9825
16 files changed
+1365
-13
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user