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
+1
-1
@@ -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 | — |
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user