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

+1 -1
View File
@@ -43,7 +43,7 @@ providers).
| R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **In progress** | `KernelRegistry` external providers; complete-name plugin export routing; `CapabilityBroker` with vendor policy; static `check --plugin` signatures; multi-export C test; provider tests. Isolated worker and handle table still pending |
| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking |
| R4 Analysis/Trace v1 | Not started | — |
| R4 Analysis/Trace v1 | **Done** | `check --emit` Analysis v1; `run/call --trace-file` Trace v1; deterministic schema tests; independent Python consumer; stale-artifact removal; value redaction |
| R5 environment/isolation | Not started | — |
| R6 release/consumers | Not started | — |
+75
View File
@@ -0,0 +1,75 @@
# ADR-0015: Public Analysis v1 and Trace v1
Status: **Accepted**
Date: 2026-11-20
## Context
Knowledge/Proof/View must consume semantic data without linking private Rust
crates or reverse-engineering `inspect --ir`. M0.5 has no stable projection and
the internal IR may change freely. At the same time tracing execution must not
become a second interpreter or leak values/secrets.
## Decision
### Analysis v1
`marqdo check <file> --emit <path>` writes `spec/analysis-v1.md`:
* read-only, static, no execution/plugin dlopen/foreign spawn;
* package-aware module identity, source digests, units, function signatures,
normalized body nodes, imports, resolved/unresolved/external references,
call edges and diagnostics;
* deterministic byte-for-byte output, atomic write, no artifact on error;
* `schema_version` is a major version; additive optional fields are allowed,
removals/changes require a bump;
* normalized nodes (`literal`, `variable`, `binary`, `call`, `assign`,
`branch`, `loop`, `return`, ...) are the contract, not Rust enum serde.
### Trace v1
`marqdo run/call --trace-file <path>` writes `spec/trace-v1.md`:
* optional, versioned, atomic; only execution produces it;
* semantic events from the interpreter and effect events from the host share a
global sequence; function ids are canonical;
* values, secrets and handles are never recorded; effect detail is only a
result summary;
* a failed run records its terminal status; it is never marked successful;
* `source.analysis_digest` lets consumers detect a stale trace;
* existing `--trace` human/JSON effect output is unchanged.
## Alternatives
1. Expose `marqdo-ir` serde directly. Rejected: locks external repos to Rust
implementation details and private optimization.
2. Make View call `run` in read-only mode to derive structure. Rejected:
read-only rendering must not execute; use Analysis.
3. Put arguments/values in traces. Rejected by default privacy policy.
4. Add `analyze`/`trace` top-level commands. Rejected: `check --emit` and
`--trace-file` are flags on existing paths.
## Compatibility
New optional CLI flags and new spec files. No existing language semantics
change. Internal IR changes must keep the protocol tests green; breaking the
public schema requires Analysis/Trace v2 and version negotiation.
## Security
Both exporters are subject to the static/execution boundary: Analysis never
executes; Trace only observes an already-authorized run. Knowledge/Proof/View
gain no capability from reading either artifact. A trace is evidence of an
observed run, not a proof of purity or correctness.
## Testing
`crates/cli/tests/analysis_trace.rs` checks determinism, identity, semantic
nodes, stale-artifact removal, trace sequencing/status and value redaction.
`tests/consumers/analysis_consumer.py` is an independent Python consumer.
## Migration & rollout
R4 implements both protocols for the current language subset. Proof-specific
extensions or richer View events are additive optional fields or a v2 ADR; the
core does not add Knowledge/Proof/View business logic.
+4 -2
View File
@@ -18,7 +18,7 @@ marqdo-cli/
│ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6
│ ├── STATUS.md implementation matrix (P0–P7)
│ ├── contributor-guide.md this file
│ └── adr/0001..0014-*.md accepted decisions
│ └── adr/0001..0015-*.md accepted decisions
├── spec/
│ ├── markdown-profile.md frozen parser profile `marqdo.md.v1`
│ ├── mapping.md AST → program roles
@@ -31,7 +31,9 @@ marqdo-cli/
│ ├── plugin-abi.md C ABI v1, SDK, host lifecycle
│ ├── math.md Formula subset and math.* semantics
│ ├── foreign.md Python/Node kernel protocol
│ └── tool-v1.md proposed generic external Tool Protocol
│ ├── tool-v1.md generic external Tool Protocol v1
│ ├── analysis-v1.md public Analysis v1 projection
│ └── trace-v1.md public Trace v1 event stream
├── crates/
│ ├── marqdo-span/ Span, LineCol, LineIndex (leaf)
│ ├── marqdo-value/ Value, diagnostics, errors, wire encoding