diff --git a/crates/cli/tests/examples_r6.rs b/crates/cli/tests/examples_r6.rs index 25a7499..11ad9ab 100644 --- a/crates/cli/tests/examples_r6.rs +++ b/crates/cli/tests/examples_r6.rs @@ -133,7 +133,12 @@ fn unknown_tool_name_installs_and_dispatches() { #[test] fn public_schemas_are_valid_json_and_versioned() { - for name in ["analysis-v1", "trace-v1", "tool-v1"] { + for name in [ + "analysis-v1", + "trace-v1", + "tool-v1", + "execution-events-v1", + ] { let path = repo() .join("spec/schemas") .join(format!("{name}.schema.json")); diff --git a/docs/adr/0059-runtime-observability-and-execution-events.md b/docs/adr/0059-runtime-observability-and-execution-events.md new file mode 100644 index 0000000..9f01d15 --- /dev/null +++ b/docs/adr/0059-runtime-observability-and-execution-events.md @@ -0,0 +1,147 @@ +# ADR-0059: Runtime observability and Execution Events v1 + +- **Status:** Accepted +- **Date:** 2026-11-22 +- **Decision owners:** CLI, runtime and host maintainers +- **Inputs:** [RFC-OBS-0001](../architecture/RFC-OBS-0001-runtime-observability.md) + (issue `#1` of `cflmy/marqdo-cli`), [Trace v2](../../spec/trace-v2.md), + [Analysis v2](../../spec/analysis-v2.md), [Tool Protocol v1](../../spec/tool-v1.md) + +## Context + +Marqdo has two public, versioned machine-readable artifacts: Analysis v2 +(static, never executes) and Trace v2 (one complete document published +atomically after a run). Neither can stream program stdout/stderr while a task +is still running, and Trace v2 deliberately has no argument or local-variable +values. + +External tools (`marqdo-view`, agents, IDEs, Knowledge/Prove) therefore had two +bad options: parse human terminal output, or embed/link private runtime types +and build a second execution path. Both break the repository boundary this +project exists to maintain: **the CLI is the only runtime**. + +## Decision + +1. **A third, independent public protocol exists: Execution Events v1.** + * `schema = "marqdo.execution-events"`, `schema_version = 1`. + * It is a one-way NDJSON (JSON Lines) stream over the CLI's protocol stdout. + * It is **not** Trace v2, not Analysis v2 and not Tool Protocol v1. Each has + its own version axis. Adding optional events/fields is allowed in v1; + changing required field meaning, ordering, redaction promises or the + source-digest definition requires a new major. + * The CLI implements no HTTP, SSE, WebSocket, browser session or + View/Agent/IDE-specific branch. Consumers convert the stream themselves. + +2. **The stream is opt-in and never changes semantics.** + `marqdo run/call --event-stream jsonl` turns the CLI stdout into a pure + JSONL channel. Without the option, stdout, stderr, exit codes, Trace and + Analysis behavior are byte-for-byte unchanged. Observation is not a + capability grant and cannot widen `pure/project/strict` authorization. + +3. **`--event-stream jsonl` and `--json` are mutually exclusive.** + `--trace-file` may be combined; Trace v2 keeps its atomic, post-run, + low-sensitivity contract. Program stdout/stderr are encapsulated as + `stdout.chunk`/`stderr.chunk` events and are never written raw to the + protocol stdout. + +4. **Events are emitted at real commit points, not from final buffers.** + Stdout/stderr chunks originate in `StdHost::resource_write` immediately + after the host accepts and commits bytes, inside the same budget path. The + final `take_output()` buffer is never split into fake "live" chunks. + Selected local-variable events originate after the assignment has been + committed to `Frame.locals`; a rejected memory write never produces a + success event. + +5. **The host owns the observation facade.** + `marqdo-host::observe` defines typed internal events (`ObservationEvent`), + the `ObservationSink` trait, `ObservationConfig`, frame identity + (`FrameId`) and the observation budget. The runtime emits borrowed events + through default `Host` methods; it never hands the sink `Frame.locals`, + the whole `MemoryStore`, or raw OS handles. The CLI owns only JSONL + encoding and the public envelope. No new crate is introduced. + +6. **Call instances get an opaque identity.** + Each entered frame gets a run-unique `frame_id` (`f1`, `f2`, ...) and a + `parent_frame_id` (`null` at the top level). Frame IDs exist only in + Execution Events v1; Trace v2 is not given a new field. Argument binding + happens before a frame is announced, so a failed binding never produces a + dangling frame. + +7. **Values are selected, bounded and off by default.** + * Default event mode publishes types/status only (`value_state: + not_requested`). + * `--observe-variable NAME` / `--observe-parameter NAME` are exact-name, + repeatable selections. There is no wildcard, regex, path expression or + `--dump-all-locals`. + * Supported value types are the scalars `Int`, `Float`, `Bool`; `Text` + additionally requires `--observe-text-values`. Lists, maps, tables, + formulas, code, memory, resources and plugin handles report + `unsupported` and are never expanded or serialized by `Debug`. + * Every value is capped by `--observe-max-value-bytes` (default 256) and + reports `not_requested`, `redacted`, `truncated`, `unsupported` or + `observed` distinctly. A text truncation never splits a UTF-8 scalar. + * Observation lowers confidentiality: it is an explicit developer action. + It is never enabled from a project manifest, never recorded in Trace v2 + or Analysis v2, and never automatically enabled by View. + +8. **Budgets, ordering and failure are defined.** + * One dispatcher assigns `seq` from 0; stdout/stderr, structural and value + events share the observable order of admission. + * Structural/value events have a bounded budget (default 100 000 events / + 16 MiB). Exhaustion emits one `observation.truncated` and stops only + non-critical events; stdout/stderr and the terminal event still flow. + * `stream.opened` (seq 0), `run.started`, stdout/stderr and the terminal + `run.completed`/`run.failed`/`run.rejected` are not dropped by the + structural budget. + * Writes are bounded and synchronous: a slow consumer applies IO + backpressure instead of growing an unbounded queue. A write failure + aborts the run with `observe.transport_failed`; the CLI must not keep + executing a program with side effects after its event pipe broke, and it + must not write a half JSON line. + * A killed/crashed process may have no terminal event. Consumers must + report `incomplete`, never synthesize success. + +9. **`run.rejected` covers pre-execution failure in event mode.** + After the writer is open, prepare/authorization/compile failures produce a + structured terminal `run.rejected` with the existing stable error code and + phase, a non-zero exit, and no `run.started`. CLI option parsing errors + still use the ordinary clap stderr path before the protocol exists. + +10. **The source binding is the Analysis digest.** + `run.started.payload.source` carries `root_id` and + `analysis_digest` = `sha256:` plus the SHA-256 of the exact Analysis v2 + bytes for the same project/projection configuration. A changed source + makes old events stale; consumers must not render them onto new source. + +11. **The Trace v2 run identity is shared, without changing Trace v2.** + In a combined run the CLI composition root creates one opaque `run_id` and + passes it to both writers, so `trace.run.id == execution stream run_id`. + Trace v2 keeps `schema_version: 2` and gains no frame/value fields. + +## Consequences + +- External tools can consume live output with a released binary and a + documented schema; they still need no private Rust crate. +- The runtime gains observation hooks at existing commit points. The default + (no option) path installs no sink and does not clone `Value`s or serialize + observation data. +- The value policy is intentionally smaller than a debugger. Breakpoints, + stepping, time travel, raw memory snapshots, memory-byte events and a + bidirectional Debug Protocol remain a separate future RFC. +- Memory metadata events (`memory.region.*`, `memory.budget`) are P2 in + RFC-OBS-0001 and are **not** part of this decision's implemented scope; no + raw memory content or handle is ever exposed. + +## Rejected alternatives + +- **Stream Trace v2 while running.** Breaks existing complete-file consumers + and cannot naturally carry live stdout/stderr or reject-before-run events. +- **Make events a flag of `--json`.** Mixes a complete result envelope with a + line stream on one channel and violates the clean-stdout guarantee. +- **Emit stdout by splitting the final buffer.** It is not real-time and + defeats the purpose; the RFC explicitly forbids it. +- **Put JSONL/SSE/HTTP in the CLI.** Adds transport and product concerns to + the composition root; View's SSE belongs to the View repository. +- **Publish all locals as a default debugging dump.** Unbounded + confidentiality loss and no stable value encoding; rejected in favour of + exact, bounded selections. diff --git a/docs/adr/README.md b/docs/adr/README.md index f59529f..b775cfb 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -43,4 +43,7 @@ Files: `0001`–`0050`, plus: * `0057-capability-handler-registration.md` — declared capability vs installed handler vs audit; * `0058-stdlib-public-alias.md` — verified stdlib `public_aliases` replace - print magic. + print magic; +* `0059-runtime-observability-and-execution-events.md` — typed host + observation facade, Execution Events v1 JSONL boundary, frame identity and + selected-value policy. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index c939634..30430a8 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -21,6 +21,7 @@ input and evidence. It is not a second running-status page. |---|---|---| | [Unified semantics RFC-LANG-0002](RFC-LANG-0002-unified-semantics.md) | **Adopted and implemented** | Single syntax: heading modes, unified payloads, keyword control flow, breaking migration and acceptance gates. | | [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) | **Review input (historical)** | Responsibility convergence, stdio/file/stream correctness, CLI/Host split and the migration order at the time. Its language examples predate RFC-LANG-0002. | +| [Runtime observability RFC-OBS-0001](RFC-OBS-0001-runtime-observability.md) | **Adopted and implemented (P0/P1)** | Typed host observation, Execution Events v1 NDJSON, frame identity, selected bounded values; P2 memory metadata remains deferred. | | [Compute machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) | **Proposed** | Opaque `Memory`, addressable regions, wire/host rejection. Compute semantics are unchanged by the syntax rewrite; its `.mq.md` examples are historical spelling. | | [Core and stdlib migration RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) | **Proposed** | Minimum core, `.mq.md` stdlib and system-capability migration. The stdlib source migration is complete; current status is recorded in ../STATUS.md. | @@ -65,6 +66,7 @@ The implemented first slices of these RFCs are recorded in `CURRENT.md` and | gzip compression operations | [0049](../adr/0049-compression-resource-operations.md) | Accepted (bounded byte-list gzip) | | Host regex extension | [0050](../adr/0050-host-regex-extension.md) | Accepted (project-mode groups/alternation/captures) | | Byte-exact HTTP framing | [0051](../adr/0051-byte-exact-http-framing.md) | Accepted (byte-list HTTP/1.1) | +| Runtime observability / Execution Events v1 | [0059](../adr/0059-runtime-observability-and-execution-events.md) | Accepted and implemented (P0/P1); memory metadata P2 deferred | | Table physical storage (T1/T2/T3), strict stdin/stderr/file/network resources | — | **Not decided**; do not implement by implication | ## Evidence and status diff --git a/docs/architecture/RFC-OBS-0001-runtime-observability.md b/docs/architecture/RFC-OBS-0001-runtime-observability.md new file mode 100644 index 0000000..8124afe --- /dev/null +++ b/docs/architecture/RFC-OBS-0001-runtime-observability.md @@ -0,0 +1,814 @@ +# RFC-OBS-0001: Runtime observability and real-time execution events + +> **Status:** Accepted and implemented at the level recorded in +> [`docs/STATUS.md`](../STATUS.md); this file is the frozen design input. +> The normative protocol contract is +> [`spec/execution-events-v1.md`](../../spec/execution-events-v1.md). +> +> **Source:** issue `#1` of `cflmy/marqdo-cli`, filed 2026-11-22 against +> `master@eeea01d672c07b6be7d6444031d1619309dc88ab`. It is reproduced here so +> the design is reviewable without the issue tracker. Where this document and +> `spec/execution-events-v1.md` disagree on the wire format, the spec is +> normative. + +--- + +# RFC-OBS-0001:Marqdo 3.x 运行时可观测性与实时执行事件协议 + +> **建议 Issue 标题**:`[RFC][P0/P1] Runtime Observability & Execution Events v1:实时输出、调用帧、可选变量观测和外部工具解耦` +> +> **状态**:历史设计输入;实现范围与证据以 [`docs/STATUS.md`](../STATUS.md) +> 和 [`spec/execution-events-v1.md`](../../spec/execution-events-v1.md) 为准。 +> 本文中的 `PROPOSED` 命名保留为设计决策记录,不再表示“未实现”。 +> +> **目标仓库**:[`cflmy/marqdo-cli`](https://github.com/cflmy/marqdo-cli);旧产品 [`cflmy/marqdo`](https://github.com/cflmy/marqdo) 只用作历史参照,不能作为 3.x 的语义或 API 依据。 +> +> **源码审查基线**:`master@eeea01d672c07b6be7d6444031d1619309dc88ab`(2026-11-22)。已发布基线:`v3.0.0-beta.1@2c7c4f31e7a388d3fcfa717a77067e696ed13854`。 +> +> **读者**:CLI、Runtime、Host、View、Agent、Knowledge、Prove、IDE、第三方扩展库开发者。**本文自足;无需阅读任何历史对话**。文中明确标出的 `spec/` 和 `docs/` 是实际开发时必须共同更新的仓库文件,而非理解本文的前置条件。 +> +> **核心目标**:使外部仓库仅使用**发布版 `marqdo` 二进制 + 公开版本化协议**即可实时获取计算输出和经授权的运行观测信息,不重编译 CLI、不链接其私有 crate、不实现第二套解释器。 + +--- + +## 0. 决策摘要(先读此节即可确定工作范围) + +本 RFC 作出以下架构决策: + +1. **需要修改 CLI 的通用观测基础设施**,不是为 `marqdo-view` 加专用 API。`run/call` 可选输出 **Execution Events v1**;`check`、`inspect` 等静态命令仍绝不执行。 +2. **CLI → 外部工具用单向 NDJSON/JSON Lines 流**;`marqdo-view` 后端接收 JSONL 并转换为浏览器 **SSE**。CLI 不实现 HTTP、SSE、WebSocket、浏览器会话或 Token/Agent 专用协议。 +3. **Trace v2 保持兼容**:不改变 `marqdo.trace` `schema_version:2` 的既有字段语义,不在默认 Trace 中添加参数、变量值、内存字节。实时协议具有独立 Schema、独立版本与独立预算。 +4. **优先实现实时 stdout/stderr 和任务生命周期**;紧接着实现可靠的调用实例标识、分支/循环事件;之后才实现**显式授权、精确选择且有界**的变量/参数值观测。 +5. **内存统计与写入元数据可以增量实现**,但本 RFC 不引入原始内存读取、任意地址快照、断点、单步、时间旅行和 Jupyter 式持久内核。它们属于以后独立的 Debug Protocol RFC。 +6. **观测默认关闭且不改变语言含义、执行结果、权限判定与预算**;除了有定义的输出背压/观测开销外,不允许将“启用观测”变成改变分支或修复运行错误的行为。 +7. 外部开发者的主验证方式是**冻结 CLI 二进制后的黑盒消费者测试**。View、Agent 和第三方消费者使用相同协议,不得出现 `if consumer == view` 一类特殊分支。 + +### 0.1 优先级定义 + +| 优先级 | 内容 | 对发布的影响 | +|---|---|---| +| **P0 / OBS-01~03** | 协议、观测边界、实时 stdout/stderr、终态、`run/call` JSONL 模式、黑盒验证 | 建议在下一个 3.x Beta 实施;对交互 View/Agent 的价值最高 | +| **P1 / OBS-04~05** | 调用实例及父子关系、变量写入元数据、**显式**参数/变量值观测、源位置关联 | 建议稳定 3.x 前完成并验证;可拆分提交 | +| **P2 / OBS-06** | 内存区域/预算统计及变更元数据、采样、性能优化 | 可以放到后续 3.x;禁止牵连 P0 | +| **非目标** | 通用调试器、内存转储、逐指令暂停、SSE server、UI、AI Token 专用协议 | 不得为了本 Issue 一并开发 | + +`P0/P1/P2` 代表项目规划优先级,不等同于当前仓库已有的 CI 门禁编号。 + +--- + +## 1. 背景:为什么现在必须补齐观测边界 + +Marqdo 3.x 把 Markdown 源、语言映射、IR、独立解释执行、Capability Host 及第三方工具协议分开了。`.mq.md` 的 H2 `@exec` 函数可以由 `marqdo run/call` 执行;外部 `marqdo-view`、`marqdo-knowledge`、`marqdo-prove`、Agent、IDE 则应当通过公开协议消费静态/动态信息。 + +已公开的两类机器可读信息是: + +- **Analysis v2**:`marqdo check index.mq.md --emit analysis.json`。它描述模块、函数、语句结构、引用、代码资源、UTF-8 源码区间及静态诊断;**不执行**。 +- **Trace v2**:`marqdo run/call ... --trace-file trace.json`。它记录 `call.enter`、`call.exit`、`return`、`branch.eval`、`loop.iteration`、`effect` 及可能的截断事件;在运行结束时原子写入,**不包含调用实参、秘密、句柄或文件内容**。 + +CLI 还提供 `run/call --json`,但它在执行结束后一次性打印返回值、捕获的 stdout/stderr、错误等 JSON。以上能力能支持静态阅读及事后执行展示,却无法让外部工具在一个长时间运行的任务中即时看到输出,也不足以恢复多次/递归调用的完整调用实例与局部变量变化。 + +### 1.1 具体用户场景 + +- **View**:用户在文档旁点击“调用函数”,希望实时看到正常程序输出,并在完成后把调用、分支和返回结果关联至原文;不希望 View 内置第二个 Marqdo 解释器。 +- **Agent/SKILL**:需要以低延迟消费长任务的阶段性输出,得知任务是否仍执行,并能中止已无必要的工作。 +- **科研/计算工具**:需要计算进度与调用轨迹,之后依据源版本比对结果,不能等数分钟后才一次性获得日志。 +- **IDE**:需要知道某次函数调用、某个赋值事件属于哪个运行帧;当前仅有函数标识、没有稳定的“调用实例”身份。 +- **Knowledge/Prove**:可能用运行事实生成经验记录或反例,但必须区分“运行中观察到”和“通用证明成立”。**不为这两类工具把推理/证明逻辑塞进 CLI。** + +### 1.2 仅把 Trace 文件边写边读为什么不够 + +现有 Trace v2 是**完整记录文件协议**,由 CLI 在运行结束时原子发布;其协议承诺了安全摘要和容量规则。把它改成一边执行一边追加 JSON,不但会破坏现有消费者对完整文件的假设,还不能自然支持实时 stdout/stderr、执行前错误、管道背压和“主动订阅但不保存文件”的工具。因此需要一个**并存而非取代**的事件传输协议。 + +### 1.3 不实现这些能力会造成什么长期成本 + +不增加公共观测协议,独立工具将被迫采取以下错误方案:解析面向人的终端日志、读取私有 Host 结构、在 View 中重写解释器、从 Trace 中猜测变量值、为了一个工具额外改一条 CLI 私有接口。它们都会使 3.0 的仓库解耦退化。因此本 Issue 的成功不是“View 看起来会动”,而是“任意消费者使用一个稳定的观测接口都能做同类工作”。 + +--- + +## 2. 已核实的现状与缺口(EXISTING,不是提案) + +| 当前源码/规范 | 已有行为 | 缺口/注意事项 | +|---|---|---| +| `crates/marqdo-runtime/src/interpreter.rs` `call_function` / `bind_args` | 调用期间有带 `locals` 的 `Frame`;`call.enter` / `call.exit` 已记录 | 事件只有函数身份、尚无每次调用的 `frame_id`/`parent_frame_id`;值留在内部 | +| 同文件 `exec_stmts_inner` | 成功赋值写入 `frame.locals`;记录返回类型、分支真假、循环 continue/exit | 不发布每次赋值事件/值;不能用最终变量值倒填历史语句 | +| `crates/marqdo-runtime/src/memory.rs` `MemoryStore` | 持有区域和提交字节统计;`MemoryHandle` 非原始主机指针 | 不存在公开的通用运行时内存观测协议;不应导出原始字节 | +| `crates/marqdo-host/src/host.rs` `Host`、`StdHost` | Host 处理副作用;`output`、`stderr` 为缓冲字节数组;`resource_write` 对 stdio 写入缓冲 | 想获得**真实的**增量 stdout/stderr 必须在 Host 输出路径上挂钩,而不是事后拆分 | +| `crates/marqdo-host/src/trace.rs` | `SemanticEvent` 含 `seq/kind/function_id/module_id/span/detail`;Host 有 `TraceBudget` | 没有公共调用实例 ID;现有安全摘要协议有意不提供参数值 | +| `crates/cli/src/commands/run.rs` | `run/call --json` 完成后组合 stdout/stderr/返回值;`--trace-file` 结束时调用写入 | 不提供实时事件通道;`--json` 不可和流式协议混作同一 stdout | +| `crates/cli/src/trace.rs` | Trace v2 原子写完整文档,并与 Analysis digest 关联 | 修改已有 v2 的隐私/完整性含义是破坏性行为 | +| `spec/analysis-v2.md`、`spec/trace-v2.md` | 公共版本化静态/动态合同 | 新增协议必须独立命名/版本,说明如何与其对齐 | +| `spec/tool-v1.md`、`docs/developers/tools.md` | 独立工具通过 `MARQDO_BIN` 调用已发布 CLI,不依赖私有 Rust 类型 | 新协议需要按工具协议方式向外公开与声明兼容性 | + +**证据基线**:上述结论仅依据已检查的 SHA;后续实现前必须重新确认 HEAD,不能假定未检查的后续提交仍维持同样行为。文中设计决策均标记为 **PROPOSED**。当前发布版**没有** `--event-stream`、`--observe-values` 或 `marqdo.execution-events`。 + +### 2.1 必须保留的既有保证 + +1. `check`/`inspect` 不执行;`run`/`call` 通过统一预备流程和能力 Host 执行。 +2. `--json` 仍是**完整、非混杂**的单次执行结果;不能把 JSONL 事件插入其 stdout。 +3. `--trace-file` 仍在完成后形成符合 Trace v2 的完整 JSON,含合法的 `source.analysis_digest`。 +4. `pure/project/strict` 及插件、Foreign、Provider 的授权规则保持原样;观测开关不是额外 capability grant,也不是绕过安全策略的方法。 +5. 默认 Trace 继续不包含参数值、原始内存、敏感数据。即使 Events v1 未来可显式输出选定值,也不意味着 Trace v2 变成高敏快照。 +6. 语言 `.mq.md` 的 `@exec/@knowledge`、语句载体和控制流映射**不修改**。这是运行时观测项目,不是 RFC-LANG 重构。 + +--- + +## 3. 最终架构与职责边界(PROPOSED) + +```text + marqdo-cli (唯一运行时) + .mq.md ──> Frontend / PreparedProgram ──> Runtime Interpreter + │ │ + │ 运行中事件(借用数据) + │ ▼ + │ Observation Facade + │ ┌─────────┴──────────┐ + │ Metadata/Frame Value Policy + │ └─────────┬──────────┘ + │ ▼ + │ Event Dispatcher + │ ┌──────────┼───────────┐ + ▼ ▼ ▼ ▼ + Analysis v2 JSONL Sink Trace v2 Null Sink + (静态文件) (实时stdout) (已有完整文件) (默认无开销) + │ + ┌─────────────────┼──────────────────┐ + ▼ ▼ ▼ + marqdo-view Agent / SKILL 其他 CLI Tool + │ + 转换为 HTTP SSE + │ + 浏览器 +``` + +### 3.1 模块划分:哪里能增加代码、哪里不该增加 + +**Runtime (`crates/marqdo-runtime`)** +- 仍是计算、函数调用、局部变量赋值、内存读写的**唯一语义来源**。 +- 在已经成功完成的状态变化边界提供可选观测钩子;不能仅为输出“赋值事件”再次执行表达式。 +- 函数调用实例 ID 在进入帧时生成;递归/异常退出也必须配对和归属正确。 +- 不认识 View、HTTP、SSE、JSONL、HTML,也不负责隐藏/展示参数输入框。 + +**Host (`crates/marqdo-host`)** +- 继续作为所有被支持的 stdout/stderr 和副作用的汇聚位置。 +- 定义**内部 typed observation interface**、可选 `EventSink` 和受预算约束的分发;Host 接收 Runtime 提交的纯语义事件,再根据策略编码成对外数据。 +- 不为了观测对插件/Foreign/Provider 放宽权限,也不自动把外部子进程的 stdout 当成 Marqdo 程序的受控 stdout。 +- 编码/写出时禁止在全局锁下等待一个不可信外部消费者;先解决锁与背压的线程安全边界。 + +**CLI (`crates/cli`)** +- 只负责选项解析、协议版本协商、观测配置、JSONL writer、稳定错误映射、退出状态和原有 Trace 文件写入。 +- `--event-stream jsonl` 使用**专有机器输出通道(CLI stdout)**;程序 stdout/stderr 是事件,不能再原样写到同一个 stdout。 +- CLI 没有 HTTP 监听、浏览器 session、SSE 编码、View 专用功能分支。 + +**独立 `marqdo-view`** +- 使用 Tool Protocol v1 的 `MARQDO_BIN` 启动 CLI 子进程,消费 JSONL。 +- View Server 负责 `POST` 发起、通过 SSE 转发并支持取消;不改变事件语义,不补造内部变量值,不读取 CLI 私有数据。 +- View 仍默认只读;只有用户显式确认才执行。View 的 SSE 和 CLI 的 JSONL **属于不同传输层**。 + +### 3.2 是否需要新 Rust crate? + +**首选不新增**只为观测而存在的多层框架或十几个 crate。将类型定义放在 `marqdo-host` 的有界模块(例如 `observe/{mod.rs,event.rs,policy.rs,sink.rs}`),在 `marqdo-runtime` 以轻量 Host 方法或明确 trait 传入只读事件,在 CLI 内维护 `execution_events.rs`(公共 JSONL 序列化)。 + +如果编译期依赖图迫使 Host↔Runtime 环依赖,则可建立**一个**只含 `Event`/`Policy`/`Span`、无 IO/CLI 的 `marqdo-observe` 内部基础 crate;必须附 ADR 说明为什么现有边界不足。**不得因为“未来也许要 IDE”先创建通用插件总线、会话管理器或所有业务通用 EventBus。** + +### 3.3 三种不同对象,不能混淆 + +- `RuntimeEvent`:内部 typed 事件,允许只读借用 `Value`、`Span` 等,以便延迟序列化。不是公共协议。 +- `ExecutionEventV1`:经过过滤/预算/转码后写到 stdout 的**公开**单行 JSON 对象。是第三方消费者所依赖的协议。 +- `TraceV2`:事后落盘、独立的公共证据对象。运行时可复用部分事件来源,但**不承诺每一种 RuntimeEvent 都写进 Trace v2**。 + +--- + +## 4. 外部协议:Execution Events v1(PROPOSED) + +### 4.1 命名和传输 + +建议协议 ID:`schema = "marqdo.execution-events"`;主版本:`schema_version = 1`;媒体类型文档可记为 `application/x-ndjson`。每行是一个完整 UTF-8 JSON 对象,以 `\n` 终止;一条事件内不得出现未转义换行;事件超过大小限额必须拒绝/裁剪并明确标记。 + +提议 CLI 使用: + +```bash +# 下列命令是提议 API,当前 3.0.0-beta.1 不支持 +marqdo run index.mq.md --event-stream jsonl +marqdo call index.mq.md main --arg n=5 --event-stream jsonl +marqdo call index.mq.md main --arg n=5 \ + --event-stream jsonl --trace-file trace.json +``` + +选项决策: +- `--event-stream jsonl` **仅** `run/call` 可用,表示整个 stdout 都属于 JSONL;普通程序输出必须封装成事件。 +- `--event-stream` 与已有 `--json` **互斥**,不混合两种 JSON 输出;`--trace-file` 可共存(保留 Trace v2 原子语义)。 +- 普通人类可读 `run/call` 不启用事件、行为和 stdout 字节保持不变。 +- `check`、`inspect`、`fmt`、`tool` 等命令不接收该选项;不将静态检查伪装成运行。 +- CLI 选项错误(clap 在命令分发前拒绝)仍走普通 stderr 与非零退出;一旦进入事件模式且成功初始化 writer,预备/授权错误须使用结构化 `run.rejected` 终态,**不输出半行 JSON 或人类可读文字到 stdout**。 + +### 4.2 公共事件信封(提议) + +所有正常输出的事件必须包含: + +```json +{ + "schema": "marqdo.execution-events", + "schema_version": 1, + "run_id": "run-opaque-01", + "seq": 2, + "kind": "call.enter", + "payload": {} +} +``` + +- `run_id`:CLI 生成的**本次运行**不透明字符串;不是 OS PID,不得被误用作跨机器持久身份。 +- `seq`:从 0 开始的全局、严格递增整数;一个运行内不重复、不倒退;由统一分发者赋值。语义事件与 stdout/stderr 的**可观察**顺序按进入该分发者的顺序定义,不能保证其他操作系统子进程内独立流的真实物理先后顺序。 +- `kind`:稳定、带命名空间的事件名;未来新事件种类是**加法扩展**。消费者可以忽略未知 `kind`,但必须拒绝未知 `schema_version` major。 +- `payload`:与 kind 对应的有界对象。每类的 required 字段由 JSON Schema 约束;未知可选字段可以忽略。 +- 为避免无关冗余,不强制每条事件重复完整 `project` 元信息;建立时通过 `stream.opened` 提供协议、生产者和观测配置;**成功准备项目后**,由 `run.started` 提供 `source` 身份和摘要;后续事件可带 `module_id`、`span`。预备失败时 `run.rejected` 可没有 `source`。 + +### 4.3 最小公共事件表 + +| 事件 | 何时发出 | 必需信息 | 观测级别 | +|---|---|---|---| +| `stream.opened` | JSONL writer 成功初始化,**第 0 条** | `producer`、`protocol`、预算、观测范围(无须已有 `source`) | base | +| `run.started` | 校验、授权通过,解释器准备真正执行 | `entry`、`mode`、`source`(`root_id` / `analysis_digest`)、`started`(仅诊断用途) | base | +| `stdout.chunk` | Host 真正接受一段程序 stdout | `encoding`、`data_base64`、`byte_count` | base | +| `stderr.chunk` | Host 真正接受一段程序 stderr | 同上 | base | +| `call.enter` | 参数已成功绑定、创建本次函数帧 | `frame_id`、`parent_frame_id`、`function_id`、`module_id`、`span` | structural | +| `call.exit` | 某次已进入的函数帧结束(含失败) | `frame_id`、`status`、`module_id`、`span` | structural | +| `return` | return 语句实际执行完 | `frame_id`、`value_type`、`module_id`、`span` | structural | +| `branch.eval` | 实际求值某条条件 | `frame_id`、`result`、`module_id`、`span` | structural | +| `loop.iteration` | 条件实际求值完成 | `frame_id`、`decision`、`module_id`、`span` | structural | +| `effect` | Host 已完成受控副作用尝试 | `operation`、`result_code`、`module_id`、`span` | structural | +| `variable.assigned` | 成功提交局部变量赋值 | `frame_id`、`name`、`value_type`、`module_id`、`span` | selected values / metadata | +| `observation.truncated` | 仅观察事件达预算 | `reason`、`limit`、`written`、`dropped`(若已知) | any | +| `run.completed` | 正常成功退出 | `status:ok`、`value`(公开 wire 值,遵循既有返回规则) | base;终态 | +| `run.failed` | 已开始执行但运行失败 | `status:error`、稳定 `error.code`、安全消息 | base;终态 | +| `run.rejected` | 进入 event mode 后、运行前校验/授权拒绝 | 结构化错误及阶段 | base;终态 | + +**状态一致性**:进入 event mode 且 writer 存活时,协议应有恰好一条 `stream.opened`、最多一条 `run.started`,以及恰好一条终态 `run.completed/failed/rejected`。对于 OS 强制终止、进程崩溃、SIGKILL、断管,此保证不成立;消费者必须按“未收到终态 + 进程非正常退出/EOF”标记为 **incomplete / unknown**,不能补造成功事件。 + +### 4.4 输出数据的字节安全 + +stdout/stderr 可能包含无效 UTF-8、跨写操作分裂的多字节字符、NUL 和二进制数据。**规范载荷统一使用 `data_base64`,按字节保真;不把 `String::from_utf8_lossy` 当作协议原始数据。** UI 需要人类文本时自行使用增量 UTF-8 解码,并定义无效字节替换或十六进制展示策略。 + +```json +{ + "schema": "marqdo.execution-events", + "schema_version": 1, + "run_id": "r1", + "seq": 2, + "kind": "stdout.chunk", + "payload": {"encoding":"base64","data_base64":"5byA5aeL5paH5pysCg==","byte_count":13} +} +``` + +上面的 `data_base64` 对应 UTF-8 字符串 `开始文本\n`(13 字节);实现时必须逐字节回读验证,`byte_count` 必须与解码后长度一致。`stderr.chunk` 同理。 + +`stdout.chunk`/`stderr.chunk` 是 **Marqdo Host 接受的程序流**;第三方插件或外语内核若绕过 Host 直接写 OS fd,其输出可能逃逸或与事件流混杂,属于安全/完整性风险,必须在 OBS-03 中测试并禁止。对无法截获的外部 stdout/stderr,**要么隔离/重定向并单独标注来源,要么禁止该组合使用 event mode**,不能默默将其解释为可信程序 stdout。 + +### 4.5 完整的最小示例 + +```jsonl +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"r1","seq":0,"kind":"stream.opened","payload":{"producer":{"name":"marqdo","version":"3.x"},"observation":{"level":"structural","values":false}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"r1","seq":1,"kind":"run.started","payload":{"entry":"root:demo@0.1.0::index.mq.md::main","mode":"pure","source":{"root_id":"root:demo@0.1.0","analysis_digest":"sha256:"}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"r1","seq":2,"kind":"call.enter","payload":{"frame_id":"f1","parent_frame_id":null,"function_id":"root:demo@0.1.0::index.mq.md::main","module_id":"root:demo@0.1.0::index.mq.md","span":null}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"r1","seq":3,"kind":"stdout.chunk","payload":{"encoding":"base64","data_base64":"T0sK","byte_count":3}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"r1","seq":4,"kind":"call.exit","payload":{"frame_id":"f1","status":"return","module_id":"root:demo@0.1.0::index.mq.md","span":null}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"r1","seq":5,"kind":"run.completed","payload":{"status":"ok","value":{"type":"int","value":"10"}}} +``` + +示例中的源版本、`source` 内容、`value` wire 格式应以最终协议 Schema 与实际 `marqdo_value::to_wire` 的一致性测试为准;占位的 `` 不是有效 SHA-256,**不能直接作为 JSON Schema 测试 fixture**。 + +### 4.6 与 Analysis v2 和 Trace v2 的一致性 + +`run.started.payload.source` 至少包含:`root_id`、`analysis_digest`;若需要还可包含锁文件 digest、入口 module id。`stream.opened` 在预备之前发出,因此**不得要求它携带尚未计算的 source**;预备失败时的 `run.rejected` 同样不要求携带 source。`analysis_digest` **必须等于与当前执行相同 prepare/projection 配置下 Analysis v2 文件原始字节**的 SHA-256,而不是随手重新序列化 JSON 后的摘要。源变化后必须标记旧事件为 stale。 + +- 建议在现有 Trace v2 的 `run.id` 字符串字段中重用本次 CLI 生成的 `run_id`;**不新增字段、不改变其类型**。如果现有内部生成路径不同,应在 CLI composition root 统一创建 run ID,再分别交给两种 writer。 +- Trace v2 仍在执行完成后原子生成;JSONL 可以在运行中消费。两者只共享运行身份、来源摘要与可信事件来源,**不要求事件逐条同构**。 +- 需要识别调用实例的是 Events v1;不能宣称 Trace v2 已经具有 frame_id。 +- 消费者拒绝未知 Schema major、来源不匹配、非法 span 和无终态事件,不能误把旧事件渲染到新源码上。 + +### 4.7 版本与兼容规则 + +采用独立协议主版本 **v1**,不与 CLI 产品版本或 Trace v2 混淆。增加可选事件、可选字段可在 v1 允许;改变必填字段含义、事件排序语义、脱敏承诺、源摘要定义或将私密数据改为默认公开,必须发新 major。`--help` 和 `docs/developers/compatibility.md` 应列出该协议、支持范围和 feature flags;Tool Protocol v1 的 `tool.json` 目前只协商 Analysis/Trace,**不能悄悄加入一个未经 Tool v1 规范确认的 `events` 字段并当作自动协商**。初期工具通过调用 `MARQDO_BIN` 的已定义 `--event-stream jsonl` 并核对 `stream.opened` 协商协议;若将来扩展 `tool.json.compatibility`,需单独更新 Tool Protocol 的 Schema、实现和测试。 + +--- + +## 5. 内部事件机制:既要实时,又不能重建 EventBus + +### 5.1 最小类型和调用方向 + +建议实现可替换的内部接口(伪 Rust,具体命名可在 PR 中调整,但语义不可改变): + +```rust +// 内部接口;不是公共 SDK。借用 Value 以避免无谓 clone/序列化。 +trait ObservationSink { + fn emit(&mut self, event: RuntimeEventRef<'_>) -> Result<(), ObservationError>; +} + +struct ObservationConfig { + enabled: bool, + structural: bool, + selected_variables: Vec, // 精确名称选择,不自动全量输出 + selected_parameters: Vec, + allow_text_values: bool, + max_observation_events: u64, + max_observation_bytes: u64, + max_value_bytes: usize, +} + +// RuntimeEventRef 包含 typed 事件、源身份及可选 &Value, +// 绝不将所有 Frame.locals 或整个 MemoryStore 交给 sink。 +``` + +运行正常流程: + +1. CLI 根据选项创建 `ObservationConfig`;无观测选项时使用 **Null/None sink**。 +2. Runtime/Host 在已有状态提交点发出轻量 typed 通知;**先完成原始语义**,再形成不会影响业务结果的只读观测资料。 +3. 分发层先执行级别、变量名精确选择、数据敏感度、事件/字节预算判断。 +4. 通过的事件才做序列化并同步写入 CLI 所持有的**独立协议 stdout writer**。 +5. `--trace-file` 仍走现有 Trace Writer;内部可以共享事件创建,但不能因为打开 JSONL 就自动在 Trace v2 输出变量值。 + +如果已有 `Host::record_semantic(...)` 不返回错误,不能据此把 IO 异常吞掉。开发者必须采取以下两者之一:① 新增明确可传播的 fallible emission 方法并在解释器安全点传播错误;② 在 sink 保存错误,解释器的下一次预算/控制边界与最终返回路径强制检查。**不得让 JSONL 管道已损坏而 CLI 继续无限执行有副作用的程序。** + +### 5.2 输出产生点与正确的实时性 + +真正的实时流必须在 `StdHost::resource_write` 记录 stdout/stderr 的同一条授权/预算路径上送出 `stdout.chunk` / `stderr.chunk`。**严禁**把 `take_output()` 得到的最终字符串按行切碎,再声称“实时”。 + +行为要求: + +- 写出的字节恰好等于 Host 已接受的字节;如果 Host 的输出预算拒绝一次写入,则不能先推送该未提交字节。 +- 原有 `--max-output` 语义仍有效;stream 不能绕开 Budget。 +- 行缓冲只能影响吞吐,不能把短小增量积累到运行结束;每次成功的 Host 程序输出写入应在合理有界延迟内可读取(见验收)。 +- 输出事件不必等待 Trace/Analysis 文件,也不要求所有扩展原生支持流。Foreign/Plugin 调用若本身阻塞直到结果返回,不得宣称内核可以神奇地实现中间 Token 流。 +- 允许有界 chunk 合并,但顺序和字节精确性必须保持;不同设备返回的字节不能冒充主程序 stdout。 + +### 5.3 预算、背压与失败策略 + +**需要分别管理三类资源**: + +1. **原有执行预算**:`--fuel`、`--timeout`、`--max-output` 等。观测不得扩权或改变其含义。 +2. **可丢弃的结构化观测预算**:例如建议 `100_000` 条、`16 MiB`,达到上限后只停止**非关键结构事件**,发一条 `observation.truncated`,继续运行和真实 stdout/stderr。值大小默认限制(例如 `256 B`),未观察的值不序列化;常规执行不分配大量事件缓冲。 +3. **不可静默丢弃的关键事件**:`stream.opened`、`run.started`、stdout/stderr、最终终态。它们不受“结构事件条数”预算截断;stdout/stderr 仍受原有输出预算。若其传输不可继续,必须明确导致**观测传输失败**,不能伪造完整成功流。 + +背压策略:**首版优先使用有界、同步写入**;下游不读时可使执行等待,属于可解释的 IO 背压,而不是无界增加内存。避免新建全局异步队列和大量线程。若后续引入专用有界队列,必须分别定义关键输出阻塞与非关键结构事件截断的策略;不能静默丢失 stdout 字节。 + +断管/写失败:JSONL sink 写失败需使 `run/call` 返回非零;在可以恢复的条件下打印仅到 OS stderr 的 `observe.transport_failed` 诊断,不得向坏掉的 stdout 再写半条 JSON。**对于此前已经发生的副作用不能声称回滚**,消费者记录为“观察失败、运行状态可能不完整”;强制取消或 SIGKILL 同样不能凭空补完终态。 + +### 5.4 输出顺序和线程安全 + +- 同一运行使用一个分发序号源,EventSink 写入过程对外形成全序。 +- 调用帧栈、局部变量数据仅在正确的解释器安全点采样;禁止后台线程无同步地遍历 `Frame.locals`。 +- 插件/外语进程如果同时写流,必须使用经验证的 Host 接口或一个区分来源的受控转发器;不能让第三方 fd 原始输出污染 JSONL。 +- 不在持有 MemoryStore 内部互斥锁/全局运行状态锁时等待阻塞 IO;先形成有界摘要再执行发送。 + +--- + +## 6. 调用帧身份与结构化执行事件(P1) + +### 6.1 需要 `frame_id` 的理由 + +同一个函数可以多次被调用、递归调用,两个分支/循环的源位置也可能相同。现有 `function_id` 只能说明**哪个函数**,不能说明**哪一次调用**。没有调用实例身份,外部 View 即使知道某条赋值发生过,也无法可靠附着到具体调用。 + +### 6.2 Frame identity 规则 + +- `frame_id`:本次运行内唯一、不透明、不可复用。建议 `f1, f2, ...` 或整型字符串;只用于展示和事件关联,不暴露内存指针。 +- `parent_frame_id`:顶层 `null`,其余指向进入当前函数时的直接调用者;必须存在或有明确表示“外部入口”的规则。 +- `function_id`:复用现有全限定函数标识和 module identity。 +- 在 `bind_args` 成功后进入新帧、发 `call.enter`;一旦进入帧,即使提前 return 或异常,也必须发对应 `call.exit`(若事件传输未截断/中断)。 +- 参数绑定失败时尚未进入函数帧:可以发 `call.bind_failed` 非终态摘要或由 `run.failed` 报告;**不能生成一个永远不会退出的虚假 frame**。 +- 每次 `return`、`branch.eval`、`loop.iteration`、`variable.assigned` 都带当前 `frame_id`,且源码区间属于声明的 module。 +- 调用序号与事件序号不同;不能拿 `seq` 代替 `frame_id`(一个帧有许多事件)。 +- 建议为实际循环增加 `iteration_index` 或唯一 loop occurrence 标识,但需要先明确是循环条件求值次数还是 body 执行次数,不能用模糊的次数误导 UI。第一阶段可维持逐次 `loop.iteration` 事件,不保证完整 iteration frame。 + +### 6.3 例子:递归与重复调用 + +`main -> f(2) -> f(1)`,然后 `main -> f(3)`,应产生三个不同的 f 调用实例。消费者能够由 `frame_id,parent_frame_id` 构造树;无论函数名是否重复、源位置是否相同,都不发生归属混淆。 + +### 6.4 同一函数遇到错误和提前 return + +- 显式 `return` 时先形成 return 事件,再形成 `call.exit(status=return)`。 +- 抛运行错误时形成 `call.exit(status=)`,再最终 `run.failed`;必要时沿栈逐帧退出,顺序和错误归属一致。 +- 观察项达到上限时可缺少结构化事件,消费者明确显示“部分调用轨迹”,不得重建不存在的调用帧。 + +--- + +## 7. 变量与参数值:必须“可选择且有界”,不是默认调试转储(P1) + +### 7.1 先做元数据,后做具体值 + +变量赋值应在**实际成功提交**后发布元数据事件:变量名、类型、帧身份、准确源位置、是否发生写入等。不得重新计算 RHS,不得使用最终局部变量值填充历史赋值,更不能在失败的内存写入后伪造“已成功”。 + +```json +{ + "schema":"marqdo.execution-events", + "schema_version":1, + "run_id":"r1", + "seq":15, + "kind":"variable.assigned", + "payload":{ + "frame_id":"f2","name":"result","value_type":"int", + "module_id":"root:demo@0.1.0::index.mq.md", + "span":{"start":120,"end":141}, + "value_state":"not_requested" + } +} +``` + +### 7.2 值观测授权模型 + +本 RFC **不**接受 `--dump-all-locals` 作为默认开发接口。建议提供下列显式参数(命名为拟议): + +```bash +# 都是拟议命令;首版可先只实现结构事件,再实现选定值 +marqdo call index.mq.md main --arg n=5 \ + --event-stream jsonl \ + --observe-variable result \ + --observe-parameter n \ + --observe-max-value-bytes 256 +``` + +具体契约: + +1. 默认 `--event-stream` **只允许类型/状态**,不含任何实参或局部变量原始值。 +2. 用户必须显式列出允许观察的参数名/变量名;首版只接受**精确名称匹配**,不支持 `*`、正则、路径表达式或“全部变量”,以免范围失控。 +3. 可观测值类型在第一阶段仅允许简单标量:整数、浮点、布尔;**字符串 Text 默认不输出**,需要另一个明确的 `--observe-text-values` 同意选项。列表/Map/Table/Formula/Code、Memory、Resource、PluginHandle 默认仅记录类型与安全摘要,不自动递归展开。 +4. 观测值由同一个 `Value` 安全编码策略处理,不得使用 Rust `Debug`、随意序列化嵌套引用或打印 MemoryHandle 内部字段。 +5. 每个值有 `max_value_bytes`、截断和失败状态;将“值未请求”“被规则遮蔽”“超过限额”“类型不支持”分别表示为 `not_requested/redacted/truncated/unsupported`,不能都显示空字符串。 +6. 即使是 Int、Float、Bool 也可能表示敏感数据。观测值的权限意味着**由用户显式同意写入该输出通道**,协议不能承诺凭变量名自动正确识别秘密。 +7. 文档中明确指出:值观测降低数据机密性;CLI 允许的是开发者主动的调试泄露,View 不可默认勾选,更不能从项目 manifest 自动开启。 +8. 不在普通 Trace v2、普通 `--json` 的 effect trace 或 Analysis v2 中偷偷新增这些值。 + +### 7.3 `call.enter` 上的参数值 + +- 默认仅有 `function_id/frame_id` 等身份和可公开的参数签名;实际参数值不出现。 +- 通过 `--observe-parameter` 选择后,可单独附加 `parameter.observed` 事件,按相同脱敏/值类型/预算策略处理。 +- 函数绑定默认值也视为真实运行参数,但事件必须注明来源为 `provided/default`,不能把源码默认表达式误当做用户传参;不允许将第三方插件收到的所有原始请求自动拷贝到观测流。 + +### 7.4 对 View 的呈现原则 + +- 默认显示“变量 `result` 已赋值(Int)”,不显示 `result = ...` 的猜测值。 +- 获得明确观测值时显示“本次调用 f2 在源位置 x/y 写入 42”,并能切换 f1/f2。 +- 缺少值时显示“未请求/受保护”,而不是误导性的 `null/0/None`。 +- 不能把运行时观测值称为形式证明。 + +--- + +## 8. 内存观测:只做元数据,保留未来的 Debug Protocol(P2) + +当前 `MemoryStore` 的页、容量、已提交字节及区域概念适合提供**非内容型指标**。建议以后允许以下只读事件: + +| 事件 | 允许的内容 | 禁止内容 | +|---|---|---| +| `memory.region.created` | 本次运行内不透明区域 ID、逻辑大小、容量限制 | 操作系统地址、裸指针、初始内存字节 | +| `memory.region.grown` | 旧/新提交字节数,是否成功 | 原始内存数据 | +| `memory.region.written` | 区域 ID、偏移/长度、来源 span、操作结果 | 写入字节的内容 | +| `memory.budget` | 总已提交字节数、区域数量、预算 | 进程地址空间映射 | + +`MemoryHandle` 当前是带运行生命周期的内部能力,不应被事件流序列化为可在下一次调用使用的句柄。区域 ID 仅供同一次运行内展示,与 CLI 用户可操作的资源句柄无关。 + +**明确不开发**:随时从外部读取 MemoryStore、逐字节 dump、任意读写、设置断点、暂停线程、时间旅行。这些需要安全模型、快照一致性、会话协议与可重放语义,应另立 Debug Protocol RFC。 + +--- + +## 9. 安全、隐私与可信边界 + +### 9.1 威胁模型 + +至少考虑:不可信 `.mq.md`、不可信 Plugin/Provider/Foreign 子进程、恶意或慢速 JSONL 消费者、意外重定向到日志服务器、循环大量打印/写变量值、内存中的 Token/密码、跨源浏览器请求、源码变更产生的错位展示。 + +**本 RFC 不提供 OS 沙箱**。现有 `pure/project/strict` 能力与隔离承诺按照当前产品文档执行;Worker 是进程故障隔离,不等于对所有敌意扩展的 OS 级安全边界。观测模式不能改变安全级别、临时扩大权限或强制载入 Plugin。 + +### 9.2 强制约束 + +- 观测开关只改变**允许输出的信息**,不能授权网络、文件、进程、Foreign、Provider 或插件。 +- 观测输出与普通程序 stdout **严格分离**;stderr 中的诊断也不得偷偷泄露被隐藏的变量/密钥。 +- 用户有意识地打印的内容属于程序 stdout;该内容可能包含秘密,事件协议对此只保证字节保真、**不自动替用户脱敏 stdout**。 +- `Value` 观测默认关闭;不输出资源句柄、内存字节及未经明确允许的文本值。 +- 禁止将变量值记录到 CI artifacts、Issue、公开诊断中作为测试失败的默认附带信息。测试使用合成哨兵并断言其不出现。 +- 与外部扩展组合使用时,应确保其原始 fd 不污染 JSONL;不能保证该点时明确标记组合不支持并 fail-closed。 +- 不向浏览器直接暴露 CLI 机器管道:View Server 仅在用户明确运行后启动子进程并将受限事件转换为 SSE;其 HTTP 授权与 CSRF 防护属于 View 仓库,不要求 CLI 实现。 + +### 9.3 特殊模式与流输出边界 + +- 即使 `--mode pure`,读取 stdout 流/传事件的行为属于调用者对 CLI 进程 stdout 的消费,**不得扩大 Marqdo 程序本身的 capability grants**。 +- `strict` 模式依赖平台/隔离环境;若已支持进程 stdout 管道,事件流应经过同样的隔离 preflight 验证,不能绕过 strict;不支持时显式拒绝。 +- 若项目声明插件而 `pure/strict` 拒绝激活,则 event mode 也必须以相同原因拒绝,不能为了 UI 可观测性自动退回 project。 + +--- + +## 10. 执行生命周期与故障处理 + +```text +CLI 参数解析 + │ ├─ 无效参数 → stderr + 非零(尚未进入事件协议) + ▼ +初始化 JSONL Writer → stream.opened(seq=0) + ▼ +准备项目 / 静态诊断 / 安全预检 + ├─ 失败 → run.rejected + EOF + 非零 + ▼ +run.started + ▼ +Runtime 真实执行 + ├─ stdout/stderr → *.chunk(已提交输出) + ├─ call/branch/loop → structural(有界) + ├─ selected Value → observed(显式授权、有界) + ├─ Runtime 失败 → run.failed + EOF + 非零 + ├─ 成功 → run.completed + EOF + 0 + └─ OS 强杀/断管/崩溃 → 可能无终态;消费者标 incomplete +``` + +### 10.1 正确的终态和退出码 + +- `run.completed(status=ok)` 只表示解释器实际成功返回,不代表所有 stdout 已被浏览器消费;必须在关键输出**成功写入**协议通道后发出。 +- `run.failed` 的 `error.code` 应尽量复用现有稳定错误族,不在新协议中另创造一套语言错误分类。 +- `run.rejected` 区分 preflight/compilation/authorization;不提供不存在的返回值。 +- 观测流断开后不能继续写半条 JSON;若产生副作用后出错,禁止伪称事务回滚。 +- 取消由外部 Tool 管理 OS 子进程(或未来明确的 CLI 取消机制),SIGTERM/SIGKILL 后无终态是合法边界;外部消费者必须以 EOF、退出状态和超时综合判断。 +- 多次运行具有不同 `run_id`;不能跨运行复用 `frame_id` 或将 A 的 `source_digest` 绑定给 B。 + +### 10.2 stdout 完整性与任务终态次序 + +成功运行必须满足:先观察到全部已接受的 `stdout.chunk` 和 `stderr.chunk`,之后才可以出现 `run.completed`。拼接 base64 解码字节应与同一个 fixture 在普通运行模式下的原始输出一致(前提是相同参数与能力配置)。不得因为 UTF-8 chunk 边界将中文变乱码,也不得因为换行将一条事件误拆成多条。 + +### 10.3 复杂外部扩展的输出 + +Host 管辖的 `resource.write("stdio")`、`打印` 正常路径必须覆盖;Foreign/Plugin/Provider 若在自己的子进程 stdout 打印,输出默认视作**外部进程数据**,必须由受控 transport 收集或拒绝该组合,不能透传到 CLI 协议 stdout。提议为可归属外部进程的输出保留未来 `external.stdout.chunk` 事件,但**不在本 Issue 假定所有第三方扩展已经具备该能力**。 + +--- + +## 11. 对既有公开协议和外部仓库的影响 + +### 11.1 各协议边界 + +| 接口 | 当前/建议 | 需要承担的职责 | +|---|---|---| +| Analysis v2 | **保持** | 静态结构、模块/函数身份、源码位置和 digest | +| Trace v2 | **保持** | 一次执行结束后的低敏、完整的受限轨迹文件 | +| Execution Events v1 | **新增** | 在线 stdout/stderr、生命周期、调用帧身份、选定可观测值 | +| CLI Tool Protocol v1 | **保持**,必要时另立兼容性扩展 | 启动独立工具、定位 `MARQDO_BIN`,不得硬编码 View | +| View SSE | **View 仓库实现** | POST 执行、GET SSE 推送、取消、页面状态与结果呈现 | +| Debug Protocol | **以后另议** | 断点、单步、状态快照、内存字节等高风险双向操作 | + +### 11.2 View 无需重新实现执行引擎 + +`marqdo-view` 先按 RFC-VIEW-0002 已公开 `--json`/Trace v2 完成独立安装、默认不执行、显式运行和 SSE 生命周期。一旦新 Events v1 发布,**只替换一个 CLI output adapter**: + +```text +现有:CLI --json 结束结果 + Trace v2 → View Execution Controller → SSE +新增:CLI --event-stream jsonl(增量)+ 可选 Trace v2 → 同一 Controller → SSE +``` + +不调整文档渲染核心、不生成 HTML 的第二条路径、不引入 Host 私有依赖,也不在 CLI 里判断“是不是 View 进程”。View 应对没有新协议的旧版 Beta CLI 采用明确降级/提示,不假装实时 stdout。 + +### 11.3 Agent、Prove、Knowledge 的边界 + +- Agent 能消费 stdout.chunk、状态与终态,但是否有 LLM Token 流仍取决于模型扩展是否**实际**增量输出;事件协议不生产 AI 内容。 +- Prove 可消费实验观测/反例;不能把 `variable.assigned` 作为通用证明证书。 +- Knowledge 可记录来源一致的执行观测;必须显式区分动态观察、人工确认与形式证明。 +- 任何第三方仓库都只能依赖公开 CLI、Schema、Release Artifact,不得通过 Cargo path 依赖 Runtime 内部类型。 + +--- + +## 12. 分阶段开发任务(可直接拆分 PR) + +### OBS-00:基线、ADR 与 Protocol Skeleton(P0) + +**为什么**:不在不确定的源码/规范之上新增互不兼容的事件格式。 + +**要开发**:在 `docs/architecture/` 或 Issue 留存此 RFC;新增架构 ADR(建议下一可用编号),固定现有 `--json`、Trace v2、Host 输出语义;新增 `spec/execution-events-v1.md` 和 `spec/schemas/execution-events-v1.schema.json` 初始合同;建立 `tests/consumers/execution_events_consumer.py` 或等价独立消费者骨架。 + +**验收**:代码尚未实现也能针对 Schema 校验正反向 fixtures;独立文档明确 `CURRENT/PROPOSED`;不修改旧 Trace v2 Schema 的私密字段保证。 + +### OBS-01:Host 与 Runtime 的观测挂钩(P0) + +**可能修改**:`crates/marqdo-host/src/host.rs`、`crates/marqdo-host/src/host/effects.rs`、`crates/marqdo-host/src/trace.rs`、`crates/marqdo-runtime/src/interpreter.rs`(仅观测钩子)、可能新增 `crates/marqdo-host/src/observe/`。 + +**要开发**:Null/Enabled Sink;Run 生命周期事件的内部表示;统一序号与安全来源身份;在 stdio 真实写入路径上发出只读字节事件;预算/IO 错误传播;兼容既有 Trace 收集。 + +**验收**:默认未启用时不序列化、不为每次变量赋值 clone `Value`;已有普通运行的返回、stdout、stderr、Trace/错误/权限测试全部不变;内部可对写入时刻的事件进行测试(不能事后分片)。 + +### OBS-02:JSONL CLI 参数与真实实时流(P0) + +**可能修改**:`crates/cli/src/main.rs`、`crates/cli/src/commands/run.rs`、`crates/cli/src/output.rs`,新增 `crates/cli/src/execution_events.rs`;`spec/` + 开发者文档。 + +**要开发**:`--event-stream jsonl`;writer;`stream.opened`/`run.started`/`stdout.chunk`/`stderr.chunk`/`run.completed|failed|rejected`;与 `--json` 互斥、`--trace-file` 并存;严格的 stdout 纯净性和失败退出。 + +**验收**:长任务在结束前可读到前置输出;二进制字节可重组;不同渠道无 JSON 污染;事件行逐条合法;故障/超时/拒绝均有明确定义;无需改 View 或核心语言语法。 + +### OBS-03:独立消费者与发布验证(P0) + +**要开发**:Linux x86_64 release 构建的已发布二进制,冻结 SHA-256;在独立 Python/Rust/Go fixture 项目读取 stdout JSONL,解析、验证 schema、重组字节,确认与终态;一个最小 View adapter JSONL→SSE 的端到端演示(属于 `marqdo-view` 仓库,不移入 CLI)。 + +**验收**:二进制不重新编译、不变化;独立消费者在正常/失败/断开情形均按规范完成;`marqdo --help`、README、CHANGLEOG、COMPATIBILITY、STATUS、Release Notes 明确声明新协议及适用版本。 + +### OBS-04:调用实例 ID 与结构事件(P1) + +**可能修改**:`crates/marqdo-runtime/src/interpreter.rs`、Host 观测类型、Schema;现有 Trace v2 仅能做不破坏的内部身份对齐。 + +**要开发**:`frame_id`/`parent_frame_id`、enter/exit 配对、递归/多次调用归属;return/branch/loop/Host effect 与调用帧关联;`run.failed` 异常路径收束。 + +**验收**:递归/多调用 fixture 100% 正确归属;不存在相同帧 ID 的重复进入;传输未截断时帧完整闭合;嵌套调用与错误回卷不悬空。 + +### OBS-05:受控值观测(P1) + +**可能修改**:Runtime 的 `bind_args`、局部写入、Host 观测过滤器、CLI 参数和 Schema。 + +**要开发**:精确的 `--observe-variable`、`--observe-parameter` 选择;类型摘要;标量有界序列化、文字的二次 opt-in;有据可查的 `redacted/truncated/unsupported`;**不读 MemoryStore 原始内容**。 + +**验收**:默认运行和只开启结构事件都不会泄露哨兵值;未选择变量绝不输出;中文字符串跨字节/超长值正确截断;无效选择和不支持的嵌套类型有明确定义;启用后每个值的帧和源码坐标正确;关闭观测时基准性能满足门禁。 + +### OBS-06:内存元数据(P2,可延期) + +**可能修改**:`crates/marqdo-runtime/src/memory.rs` 和 Host 事件类型。 + +**要开发**:创建、增长、成功写入和预算统计;不透明区域标识;禁用裸指针与字节读取。 + +**验收**:内存区域/总提交量与真实 Store 一致;扩容失败不能产生“成功增长”;权限、类型和 budget 均不受观测影响。 + +### OBS-07:正式门禁、文档治理与跨平台(P0/P1) + +**要开发**:在原有 Linux 主通道以及平台声明范围内运行 CI;Perf 追加 disabled/metadata/values 三档;严格隔离的组合测试,不用本次改动推断未验证平台已经受支持;更新协议版本矩阵和源码状态文档。 + +**验收**:见第 13/14 节。对于稳定 3.x,性能和安全门禁不能因 Beta 阶段允许 WARN 而永久免检。 + +--- + +## 13. 最小测试项目与验收矩阵 + +### 13.1 可执行 fixture A:真实输出与返回 + +```markdown +# @knowledge Stream protocol example + +## @exec main + +`打印("START")` + +`n = 10` + +`打印("DONE")` + +`return n` +``` + +**验收**:普通 `marqdo run` 与 `--event-stream jsonl` 两条运行结果一致;JSONL 前置输出发生于 run.completed 之前;输出 chunk 重组为相同字节;返回值保持官方 wire 编码;运行结果不混入原始输出文本行。此 fixture 只测试输出事件的时间顺序,不能充当“有时间延迟”测试;延迟由下面的独立 fixture 测量。 + +### 13.2 实时性 fixture B:长任务中段输出 + +选取**当前语言已经支持**的确定性长任务:程序先打印 `READY`,再进行可测量的大量计算/循环,最后打印 `FINISH`。测试进程在读取到 `READY` 时必须仍处于运行中;如果本机任务太快,则使用受控、可重复且经授权的 `process.run` fixture 或测试用 Host 延迟,避免依赖未被正式支持的 `sleep` 关键字。**严禁仅靠 run.completed 之后 replay 的字符串伪造 PASS。** + +验收标准(建议 CI):在固定测试机上,`READY` 事件的可观察到达时间必须明显早于最终退出(例如与后续受控延迟 ≥ 300ms 之间至少有 100ms 可辨窗口),在负载波动时保留 timing 诊断,不把共享 CI 的单次偶然卡顿视为核心失败证据。可用同步闸门 fixture 做确定性测试:子进程收到 READY 后测试方才释放后续计算。 + +### 13.3 结构 fixture C:递归、重复调用、嵌套循环 + +编写合法 3.0 RFC-LANG-0002 的 `main`、`f`、`g`,至少有 `main→f→g`、两次 `f`、一次递归调用、一条真假分支和循环两次。测试断言:不同 `frame_id`、正确 `parent_frame_id`、`function_id`、源位置、事件排序和真实循环次数;提前返回与深层异常均能形成可归属的失败事件。 + +### 13.4 变量 fixture D:默认不泄露 / 精确启用 + +```markdown +## @exec main + +`secret_token = "DO_NOT_LEAK_SENTINEL_1"` + +`visible_count = 42` + +`return visible_count` +``` + +注意:这是测试值泄露策略的 fixture,**不要同时打印 secret_token**,否则 stdout 按程序意图包含它,不能拿来证明观察系统泄露。 + +- 默认普通运行/默认 event mode / metadata mode / Trace v2:均不应包含 `DO_NOT_LEAK_SENTINEL_1`。 +- `--observe-variable visible_count`:在该事件收到 42(若整数值被允许)。 +- `--observe-variable secret_token` **但未显式开启文本值选项**:仅显示 `redacted`,不出现哨兵。 +- 即使允许文本,也只输出被精确选择且未超预算的值;不得连带输出其他变量。 + +### 13.5 负面与边界验收表(每项都须可自动测试) + +| 编号 | 测试 | 预期结果 | +|---|---|---| +| T01 | 不加 `--event-stream` | stdout、错误、退出码、Trace v2 与当前版本一致 | +| T02 | `--event-stream jsonl --json` | usage 错误,无混合输出 | +| T03 | `check`/`inspect` 请求 event mode | 拒绝;不执行 | +| T04 | 每条 JSONL 行 Schema v1 验证 | 全部通过;seq 从 0 单调递增 | +| T05 | 未知 Schema major 的独立消费者 | 明确拒绝、不静默当 v1 | +| T06 | stdout 中文多字节跨 chunk | base64 重组原始字节完全一致 | +| T07 | stderr 非 UTF-8 / NUL | 无数据损坏、无输出混杂 | +| T08 | 长任务中段输出 | 可在执行仍未退出时观测到 | +| T09 | `run --trace-file` 同时使用 JSONL | Trace v2 正常原子写入,digest 对应 | +| T10 | 预备失败、语义错误、授权拒绝 | event mode 有 `run.rejected`,非零退出,无 `run.started` | +| T11 | 运行错误 | `run.failed`,无 `run.completed` | +| T12 | SIGKILL / 进程崩溃 | 消费者判 incomplete,不凭空补成功 | +| T13 | 断管 / JSONL writer IO 错误 | 非零退出或已终止,不能继续无限副作用 | +| T14 | 慢消费者 | 背压有界、内存不无限增长、无静默输出丢失 | +| T15 | 结构事件预算耗尽 | 有 `observation.truncated`,后续 stdout/终态仍可传输 | +| T16 | stdout 执行预算耗尽 | 与旧 Budget 一致,不绕过限制 | +| T17 | 重复/递归调用 | `frame_id` 唯一、parent 正确、来源正确 | +| T18 | 参数绑定失败 | 不出现悬空的假调用帧 | +| T19 | return / error | enter/exit 正确配对(未截断前提下) | +| T20 | `variable.assigned` | 只在真实提交后发,源 span 精确 | +| T21 | 默认观测 | 不包含未选择的局部变量/参数值 | +| T22 | 显式选中整数变量 | 值可用且有预算限制 | +| T23 | 文本值未二次授权 | 哨兵字节不存在 | +| T24 | 不支持的复杂类型/MemoryHandle | 仅安全类型/遮蔽状态,不序列化句柄 | +| T25 | 观测打开/关闭同一程序 | 原业务结果与权限判定一致 | +| T26 | 不可信插件原生 stdout | 不污染 JSONL,必要时 fail-closed | +| T27 | `pure/project/strict` 模式 | 授权、拒绝和已声明的支持矩阵不变 | +| T28 | 源文档更改后回放旧事件 | digest 失效提示,不贴到新源码 | +| T29 | 多次运行 | 不共享 run/frame 身份 | +| T30 | 冻结发布 CLI 二进制的外部 Python/Go/Rust 消费者 | 不改 CLI 源码、不重编译、成功消费新协议 | +| T31 | 旧 Analysis v2/Trace v2 消费者回归 | 无行为/Schema 回归 | +| T32 | CI 性能对照:关闭、metadata、values | 记录可重复 p50/p95、分配和内存,异常回归阻止发布 | +| T33 | 值观测写入现有 `--json`/Trace v2 | 不允许出现新增秘密字段 | +| T34 | 错误的 `module_id/span` | 独立消费者拒绝/明确告警,不能装饰错误源码 | +| T35 | `stdout.chunk` 与 run.completed 顺序 | 全部已提交输出先于终态;逐字节保真 | +| T36 | 外部工具按 `MARQDO_BIN` 调用发布版 | 不需要私有 Cargo crate 或 Rust Host 嵌入 | + +### 13.6 性能与容量验收原则 + +不要不经测量地宣称“零开销”。至少固定三个等级:`disabled`、`structural`、`selected values`,在相同 SHA、同工具链、同硬件节点上对循环、递归、输出密集、内存密集和 Foreign/Plugin 典型负载记录时间分布、峰值 RSS、输出字节、事件字节与丢弃计数。**未启用时不应发生 Value 序列化、长驻事件队列或全帧 clone**。任何目标百分比阈值须先通过基线验证后写入正式 release gate,不能用主观“无明显影响”代替数据。 + +--- + +## 14. 文档、CI、版本与发布完成标准 + +实现过程中必须同步更新: + +- `spec/execution-events-v1.md`:**规范真相**,包含每类事件 required 字段、序号、终态、版本/未知字段、值策略与错误边界。 +- `spec/schemas/execution-events-v1.schema.json`:Draft 2020-12;配套正负 fixture。 +- `docs/developers/analysis-trace.md`:加入 Execution Events v1 的精确 CLI 使用示例、Analysis/Trace 绑定规则和禁用边界。 +- `docs/developers/tools.md`、第三方手册:新增外部消费者指南;若 Tool 协商改变,必须升级对应协议规范和测试。 +- `docs/developers/compatibility.md`、`COMPATIBILITY.md`:明确该协议与 Marqdo 产品/Analysis/Trace/Tool 各自独立的版本轴。 +- `README.md`、`CHANGELOG.md`、`docs/STATUS.md`、`docs/architecture/CURRENT.md`、`docs/releases/`:明确已实现、已验证、已发布和限制,**不能将本 Issue 的 Proposed 描述当成已实现**。 +- `crates/cli/tests/`、`crates/marqdo-host/tests/`、`crates/marqdo-runtime/tests/`、`tests/consumers/`:增加上述测试。 +- 适用平台的 CI:`cargo fmt --check`、clippy、workspace tests、JSON schema 正负验证、独立 frozen-binary contract、必要的 strict/安全与性能 lane;发布结论以同 SHA 证据为准。 + +### 14.1 Definition of Done(完全完成的判定) + +必须同时满足: + +- [ ] `marqdo run/call` 真实增量输出 Events v1,至少具备 P0 事件、严格 NDJSON 和终态/错误行为。 +- [ ] 事件来自**实际的 Host 输出提交点**,不是最终缓冲拆包;持续运行时消费者能读到先发出的 stdout/stderr。 +- [ ] 现行 `--json`、Trace v2、Analysis v2、授权模式、语言语义及普通 CLI stdout 保持原样。 +- [ ] P1 若作为本 Issue 完成范围:正确 frame identity 和变量/参数观测,默认不泄露值且显式选择严格生效;否则在发布记录明确 `OBS-04/05 pending`,不对外宣称已支持。 +- [ ] 禁止原始句柄/内存、未获同意的文本值和外部插件 fd 污染 JSONL。 +- [ ] 慢消费者、终端断开、预算截断、取消/崩溃、严格模式均有负面测试;无伪造成功或无限缓冲。 +- [ ] 使用发布版二进制与独立第三方消费者完成黑盒验证,二进制 SHA-256 测试前后不变。 +- [ ] 文档、Schema、fixtures、版本矩阵和同 SHA 的 CI/性能/安全证据一起提交并更新,避免文档与代码脱节。 + +--- + +## 15. 反模式与禁止事项(适用于所有 PR) + +**禁止**: + +1. 在 CLI 增加 `view` 专用命令/模块或只在 View 进程启动时才启用的私有路径。 +2. 在核心引入 HTTP server、SSE、WebSocket、前端、Notebook、Agent 会话、Knowledge/Prove 业务逻辑。 +3. 把普通 stdout 和 JSONL 事件写到同一物理 stdout;把最终字符串拆成“实时”chunk。 +4. 将 `Frame.locals`、整个 MemoryStore、原始 C ABI/OS 指针或任意 `Value` 的 Rust `Debug` 输出给外部消费者。 +5. 修改 Trace v2 的“不包含敏感值”承诺而仍维持 `schema_version:2`。 +6. 以强行重写 JSONL 或自定义解析 Markdown 语义方式绕过原来的 Analysis digest。 +7. 允许消费者拖慢时分配无界 Vec、队列或后台线程;静默丢 stdout 或伪造已完成。 +8. 观测失败后继续无限运行带副作用任务而不回报错误。 +9. 依赖私有 `inspect --ir`、`marqdo-ir` Cargo path 或宿主内存布局来实现第三方工具。 +10. 将多次运行的某个值当作通用定理的证明,或把“本次未观察到”当作“本次没有发生”。 + +--- + +## 16. Issue 可以直接拆出的执行清单 + +- [ ] **OBS-00**:确认最新 SHA / 审批 RFC / ADR / 公共 Schema / fixtures。 +- [ ] **OBS-01**:实现内部 typed sink、Null/Enabled 配置、Host stdout/stderr 原位事件与可传播 IO 故障。 +- [ ] **OBS-02**:`run/call --event-stream jsonl`、Lifecycle、base64 Chunk、预算与既有 `--json` 兼容。 +- [ ] **OBS-03**:真正独立的 frozen-binary 消费者和 live-output gate;更新 CLI 版本文档。 +- [ ] **OBS-04**:Frame ID / Parent ID / 递归调用及分支、循环事件正确归属。 +- [ ] **OBS-05**:显式选择、预算受限的参数/局部变量值观测;默认隐私 gate。 +- [ ] **OBS-06(可后移)**:Memory metadata(仅大小、区域、写入范围)。 +- [ ] **OBS-07**:覆盖所有负面测试、安全、性能、同 SHA 证据和 Release Notes。 + +**建议合并策略**:先交付 P0,可供 View/Agent 消费;再交付 P1 的帧身份与值观测;P2 不阻塞。P0 结束后,即使 P1 未完成,也应能真实改善实时输出体验。任何实施中发现的语言语义缺口要记录为**独立 issue**,不能把本项扩展成全能调试器。 + +--- + +## 17. 参考源码与权威文档(便于接手开发者逐文件定位) + +**当前 CLI(审查 SHA `eeea01d`)**: + +- [`crates/cli/src/main.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/cli/src/main.rs) — 参数定义与 `run/call` 分发。 +- [`crates/cli/src/commands/run.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/cli/src/commands/run.rs) — 预备、授权、Host 配置、执行、完成后 JSON/Trace。 +- [`crates/cli/src/trace.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/cli/src/trace.rs) — Trace v2 完整文件 Writer。 +- [`crates/cli/src/analysis.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/cli/src/analysis.rs) — Analysis v2 / digest。 +- [`crates/cli/src/output.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/cli/src/output.rs) — 当前 `--json` 诊断与最终 envelope。 +- [`crates/marqdo-runtime/src/interpreter.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/marqdo-runtime/src/interpreter.rs) — 调用帧、参数绑定、赋值/分支/循环及来源。 +- [`crates/marqdo-runtime/src/memory.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/marqdo-runtime/src/memory.rs) — MemoryStore 的区域和预算边界。 +- [`crates/marqdo-host/src/host.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/marqdo-host/src/host.rs) — Host Trait、StdHost、stdio 缓冲与 resource 写入。 +- [`crates/marqdo-host/src/host/effects.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/marqdo-host/src/host/effects.rs) — 现有 Host effect/sequence 记录。 +- [`crates/marqdo-host/src/trace.rs`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/crates/marqdo-host/src/trace.rs) — 现有语义事件/预算类型。 +- [`spec/analysis-v2.md`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/spec/analysis-v2.md);[`spec/trace-v2.md`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/spec/trace-v2.md);[`spec/tool-v1.md`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/spec/tool-v1.md) — 现行公共协议边界。 +- [`docs/developers/analysis-trace.md`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/docs/developers/analysis-trace.md)、[`docs/developers/tools.md`](https://github.com/cflmy/marqdo-cli/blob/eeea01d672c07b6be7d6444031d1619309dc88ab/docs/developers/tools.md) — 第三方消费接口。 + +**关联产品需求(不是 CLI 接口真相)**:`marqdo-view` 的 RFC-VIEW-0002 定义“默认静态、显式执行、SSE 实时任务状态、交互只通过 CLI 子进程”,但本 Issue **不依赖**该文件才能实现;CLI 只需提供以上通用 JSONL 流。旧 `cflmy/marqdo` 的 View 功能和源码仅能辅助回归 UI 体验,不得迁移旧私有 Host/Notebook API。 + +--- + +### 结语:应从“View 要变量面板”转为“语言提供可信可观测性” + +这次改动的价值不在于让某个旧页面复活,而在于:**Marqdo 的执行语义由 CLI 唯一负责,所有外部工具获得同一份可验证、可限制、可授权、可版本化的运行事件。** 默认运行不泄密、不改变既有程序;需要更深观测时用户明确选择且能看到风险;每条可见结果都有来源、身份和失败语义。这样才能在后续开发 `marqdo-view`、`marqdo-knowledge`、`marqdo-prove`、Agent 和扩展库时继续保持真正的仓库解耦。 diff --git a/spec/execution-events-v1.md b/spec/execution-events-v1.md new file mode 100644 index 0000000..54b29cb --- /dev/null +++ b/spec/execution-events-v1.md @@ -0,0 +1,326 @@ +# Execution Events v1 + +Status: **implemented by `marqdo run/call --event-stream jsonl`** (P0 and P1 of +RFC-OBS-0001). It is an independent public protocol: it is not Analysis v2, +not Trace v2 and not Tool Protocol v1. The decision record is +[ADR-0059](../docs/adr/0059-runtime-observability-and-execution-events.md); the +design input is [RFC-OBS-0001](../docs/architecture/RFC-OBS-0001-runtime-observability.md). + +## 1. Transport and negotiation + +* Media type: `application/x-ndjson` (JSON Lines). One complete UTF-8 JSON + object per line, terminated by `\n`; no unescaped newline occurs inside an + event. +* The stream uses the CLI stdout as a **dedicated machine channel**. While + `--event-stream jsonl` is active, the program's `stdout` and `stderr` are + carried only as `stdout.chunk` / `stderr.chunk` events and are not written + raw to stdout. Human diagnostics may still go to OS stderr. +* `--event-stream jsonl` is available only on `run` and `call`. It is + mutually exclusive with `--json`; `check`, `inspect`, `fmt`, `tool` and the + other static commands reject the option. `--trace-file` may be combined. +* The consumer checks the negotiated protocol from `stream.opened` + (`schema` + `schema_version`). Consumers **must reject unknown major + versions**, and must not silently treat another major as v1. +* A consumer that cannot read the stream (slow, closed pipe, killed process) + may see a truncated final line or no terminal event. It must report + `incomplete`; it must never synthesize a successful terminal event. + +## 2. Envelope + +Every normal line has exactly these top-level fields: + +```json +{ + "schema": "marqdo.execution-events", + "schema_version": 1, + "run_id": "12345-1700000000000000000", + "seq": 2, + "kind": "call.enter", + "payload": {} +} +``` + +| Field | Type | Meaning | +|---|---|---| +| `schema` | string | Always `marqdo.execution-events`. | +| `schema_version` | integer | Major version; currently `1`. | +| `run_id` | string | Opaque identity of this one run. Never an OS PID used as a cross-run identity. Different for every invocation, including repeated runs in one process. | +| `seq` | integer | Global, strictly increasing, starts at 0, assigned by one dispatcher. `seq` is the event sequence, not a frame or iteration identity. | +| `kind` | string | Stable namespaced event name. New kinds are additive; consumers ignore unknown kinds. | +| `payload` | object | Kind-specific object defined below. Unknown optional fields are ignored. | + +Event ordering is the order of admission to the single dispatcher. Independent +OS streams (for example a foreign subprocess writing its own fd) do not have a +portable physical ordering and are not part of this protocol. + +## 3. Lifecycle and event kinds + +Exactly one `stream.opened` is written when the JSONL writer is initialized, +before project preparation. At most one `run.started` is written. On success or +failure there is exactly one terminal event, and no event is written after it. +The normal order is: + +```text +stream.opened (seq 0) + -> run.rejected (prepare/authorization/compile failure) + or run.started -> ... -> run.completed | run.failed +``` + +`run.completed`, `run.failed` and `run.rejected` are the only terminal events. +`SIGKILL`, a crash or a broken pipe may leave the stream without a terminal +event; that is a legitimate `incomplete` boundary. + +### 3.1 `stream.opened` (base, seq 0) + +Required payload fields: + +```json +{ + "producer": {"name": "marqdo", "version": "3.0.0-beta.1"}, + "protocol": {"name": "marqdo.execution-events", "schema_version": 1}, + "observation": { + "level": "structural", + "values": false, + "selected_variables": [], + "selected_parameters": [], + "allow_text_values": false + }, + "limits": { + "max_observation_events": 100000, + "max_observation_bytes": 16777216, + "max_value_bytes": 256 + } +} +``` + +`observation.level` is `base`, `structural` or `values`. It reports what the +producer is willing to publish, not a security grant. `stream.opened` does not +carry a source identity because no project has been prepared yet. + +### 3.2 `run.started` (base) + +Required payload fields: `entry`, `mode`, `source`; optional +`started_unix_ms` for diagnostics only. + +```json +{ + "entry": "root:demo@0.1.0::index.mq.md::main", + "mode": "project", + "source": { + "root_id": "root:demo@0.1.0", + "analysis_digest": "sha256:<64 lowercase hex>" + }, + "started_unix_ms": 1763800000000 +} +``` + +`source.analysis_digest` is `sha256:` plus the SHA-256 of the **exact bytes** +of the Analysis v2 file produced for the same project and projection +configuration (not a re-serialization of the in-memory IR). If the source +changes, existing events become stale; consumers must not render them onto the +new source. + +### 3.3 `stdout.chunk` / `stderr.chunk` (base) + +Required payload fields: + +```json +{"encoding": "base64", "data_base64": "5byA5aeL5paH5pysCg==", "byte_count": 13} +``` + +* `encoding` is `base64` (standard alphabet, padded). +* `data_base64` is the byte-exact data. Invalid UTF-8, NUL, binary bytes and + split multi-byte characters are preserved. +* `byte_count` equals the decoded byte length. A consumer must verify it. +* Chunks are bounded (implementation maximum 64 KiB before base64 encoding); + a larger host write is split into consecutive chunks in order. +* These events are emitted at the host's real commit point: bytes are exactly + those accepted by the host output budget. A rejected write emits nothing. +* All committed chunk events precede the terminal event. Concatenating the + decoded bytes must equal the bytes a normal run writes to stdout/stderr for + the same arguments and grants. + +### 3.4 Structural events (structural) + +| Kind | Required payload fields | +|---|---| +| `call.enter` | `frame_id`, `parent_frame_id`, `function_id`, `module_id`, `span` | +| `call.exit` | `frame_id`, `status`, `module_id`, `span` | +| `return` | `frame_id`, `value_type`, `module_id`, `span` | +| `branch.eval` | `frame_id`, `result`, `module_id`, `span` | +| `loop.iteration` | `frame_id`, `decision`, `module_id`, `span` | +| `effect` | `operation`, `result_code`, `module_id`, `span` | + +* `frame_id` is an opaque run-unique string (`f1`, `f2`, ...). It identifies + one call instance, not a function and not a source location. +* `parent_frame_id` is `null` for the entry frame, otherwise the direct + caller's `frame_id`. +* A frame is announced by `call.enter` only **after** argument binding + succeeded. A binding failure produces no frame. Every entered frame that is + not cut off by transport loss/truncation gets exactly one `call.exit`; + `return` (when present) precedes `call.exit`. +* `call.exit.status` is `ok`, `return`, or a stable runtime error code. +* `branch.eval.result` is a JSON boolean. `loop.iteration.decision` is + `continue` (body will execute) or `exit` (condition was false). The event is + emitted once per condition evaluation; iteration indices are not part of v1. +* `effect.result_code` is a non-sensitive result summary (for example `ok` or a + stable error code). It never carries effect arguments or file contents. +* `module_id` is a logical package module id; `span` is + `{"start": , "end": }` in UTF-8 source offsets, or `null`. A + span must belong to the declared module. + +Example: + +```json +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"r1","seq":3,"kind":"call.enter","payload":{"frame_id":"f1","parent_frame_id":null,"function_id":"root:demo@0.1.0::index.mq.md::main","module_id":"root:demo@0.1.0::index.mq.md","span":null}} +``` + +### 3.5 Value observation events (values) + +`variable.assigned` required payload fields: `frame_id`, `name`, +`value_type`, `module_id`, `span`, `value_state`; optional `value` when +`value_state` is `observed` or `truncated`. + +`parameter.observed` required payload fields: `frame_id`, `name`, `source`, +`value_type`, `module_id`, `span`, `value_state`; optional `value`. `source` +is `provided` or `default` (a source default is a real runtime value but not a +user-provided argument). + +`value_state` is one of: + +| State | Meaning | +|---|---| +| `not_requested` | The name was not selected for observation; no value is encoded. | +| `redacted` | The name was selected but policy hides the value (for example `Text` without `--observe-text-values`). | +| `truncated` | The value was encoded but exceeded `max_value_bytes`; `value` is the safe prefix. | +| `unsupported` | The value type is not a v1 scalar; only its type is reported. | +| `observed` | The scalar value is encoded normally. | + +Value encoding reuses the `marqdo.value.v1` wire representation of the value: +`{"type":"int","decimal":"42"}`, `{"type":"float","value":1.5}`, +`{"type":"bool","value":true}`, `{"type":"text","value":"..."}`. For a +truncated text the object also carries `"truncated": true` and +`"original_byte_count": `. Text truncation never splits a UTF-8 scalar. +Lists, maps, tables, formulas, code, memory, resources and plugin handles are +`unsupported`; they are never recursed into and handles are never serialized. +A text value is never published without the explicit +`--observe-text-values` consent, even when the name was selected. + +`variable.assigned` is emitted only after the assignment was actually +committed. It never re-evaluates the right-hand side and never back-fills the +final value of a variable into an earlier assignment. + +### 3.6 `observation.truncated` (any) + +Required payload fields: `reason`, `limit`, `written`, `dropped`. `reason` is +`event_budget` or `byte_budget`. It is emitted at most once per run, only when +the structural/value observation budget is exhausted. It does not stop +stdout/stderr events or the terminal event. `dropped` may be `null` when the +producer cannot know the exact count. + +### 3.7 Terminal events (base) + +`run.completed`: + +```json +{"status":"ok","value":{"type":"int","decimal":"10"}} +``` + +`run.failed`: + +```json +{"status":"error","error":{"code":"runtime.type","message":"safe diagnostic message","module_id":"root:demo@0.1.0::index.mq.md","span":{"start":120,"end":141}}} +``` + +`run.rejected`: + +```json +{"status":"rejected","phase":"prepare","error":{"code":"frontmatter.invalid","message":"safe diagnostic message"}} +``` + +* `run.completed.value` uses the same wire encoding as `run/call --json`. +* `run.failed.error.code` reuses the existing stable runtime error family; the + message is the same safe diagnostic text already printed to humans. It does + not add argument values, secrets, file contents or memory bytes. +* `run.rejected.phase` is `options`, `prepare`, `compile`, `authorization` or + `strict`. It distinguishes failures before execution started. +* A terminal event is written only after all committed chunk events. A + `run.completed` does not claim the consumer has read or displayed the bytes. + +## 4. Budgets, backpressure and failure + +Three separate resources exist and are never conflated: + +1. **Execution budgets** (`--fuel`, `--timeout`, `--max-output`, memory + budgets). Observation never widens them. A rejected host output write emits + no chunk event. +2. **Observable structural/value budget.** Defaults are 100 000 events and + 16 MiB, adjustable with `--observe-max-events` / `--observe-max-bytes` + (`0` = unlimited). Exhaustion truncates only these events and emits + `observation.truncated`. +3. **Critical transport events.** `stream.opened`, `run.started`, stdout/stderr + chunks and the terminal event are not dropped by the structural budget. + +Writes are synchronous and bounded. A slow consumer exerts IO backpressure on +the run; the CLI must not accumulate an unbounded queue or spawn an unbounded +event thread. If the JSONL writer fails (closed pipe, write error), the run +must fail with `observe.transport_failed`, return a non-zero exit status and +stop a program that would otherwise keep producing side effects. The CLI must +not write a partial JSON line after a failure. Side effects that already +happened are not rolled back and must not be claimed as rolled back. + +If event transport is truncated but still writable (structural budget), the +program's language behavior, return value, output bytes and capability +authorization are unchanged. + +## 5. Value policy and security + +* Event mode is not a capability grant and cannot enable network, filesystem, + process, foreign, provider or plugin access. `pure`, `project` and `strict` + keep their documented policy; if a project extension is rejected in a mode, + event mode is rejected for the same reason. +* Observation is off by default. Type/status metadata is the default; raw + values require an explicit exact-name selection. Text requires a second + explicit consent. Selection is not automatic from a manifest, View setting + or environment. +* Program stdout/stderr may contain secrets by the program's own intent; the + protocol preserves bytes and does not promise automatic redaction of program + output. +* Trace v2 and Analysis v2 never gain argument/local values, handles, memory + bytes or new secret-bearing fields through this protocol. +* A third-party extension's raw OS stdout/stderr must not pollute the JSONL + channel. Such output remains external process data: it is either captured by + the controlled host transport or the combination is unsupported/fail-closed. +* Tests use synthetic sentinel values and assert that unselected values never + appear in the stream, Trace or `--json`. + +## 6. Relation to Analysis v2 and Trace v2 + +| Artifact | Relation | +|---|---| +| Analysis v2 | Static only. `run.started.source` binds to its exact bytes via `analysis_digest`. Events never replace it. | +| Trace v2 | Unchanged schema/version and privacy promise. In a combined run both writers share the CLI-generated `run_id`; Trace v2 gains no frame/value fields and is still published atomically after the run. | +| Tool Protocol v1 | Unchanged. A consumer invokes the released binary via `MARQDO_BIN` and negotiates by reading `stream.opened`; `tool.json` does not implicitly advertise an `events` field. | +| View SSE | Implemented by the View repository by adapting this JSONL stream. The CLI implements no HTTP/SSE. | + +## 7. Versioning and compatibility + +* Independent major version `1`, not tied to the product version or Trace v2. +* Additive optional fields and new event kinds are allowed in v1. Changing a + required field's meaning, ordering guarantees, redaction promise, source + digest definition or making private data public by default requires a new + major. +* Consumers must ignore unknown `kind` and unknown optional fields, and must + reject unknown `schema_version` majors. +* `--help`, `docs/developers/analysis-trace.md`, + `docs/developers/compatibility.md` and `COMPATIBILITY.md` list the protocol + and its exact option names. + +## 8. Test fixtures and consumers + +* Schema: [`schemas/execution-events-v1.schema.json`](schemas/execution-events-v1.schema.json). +* Independent consumer: `tests/consumers/execution_events_consumer.py`. +* Fixtures: `tests/consumers/fixtures/execution-events/`. +* Rust gate: `crates/cli/tests/execution_events.rs` runs the real binary and + checks envelope, sequence, base64 byte fidelity, terminal behavior, + redaction, frames, traces and output purity. diff --git a/spec/schemas/execution-events-v1.schema.json b/spec/schemas/execution-events-v1.schema.json new file mode 100644 index 0000000..236ea74 --- /dev/null +++ b/spec/schemas/execution-events-v1.schema.json @@ -0,0 +1,274 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://marqdo.dev/schemas/execution-events-v1.schema.json", + "title": "Marqdo Execution Events v1", + "description": "One line of the marqdo.execution-events v1 NDJSON stream.", + "type": "object", + "required": ["schema", "schema_version", "run_id", "seq", "kind", "payload"], + "properties": { + "schema": {"const": "marqdo.execution-events"}, + "schema_version": {"const": 1}, + "run_id": {"type": "string", "minLength": 1}, + "seq": {"type": "integer", "minimum": 0}, + "kind": {"type": "string", "minLength": 1}, + "payload": {"type": "object"} + }, + "additionalProperties": true, + "allOf": [ + { + "if": {"required": ["kind"], "properties": {"kind": {"const": "stream.opened"}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["producer", "protocol", "observation", "limits"], + "properties": { + "producer": { + "type": "object", + "required": ["name", "version"], + "properties": { + "name": {"const": "marqdo"}, + "version": {"type": "string", "minLength": 1} + }, + "additionalProperties": true + }, + "protocol": { + "type": "object", + "required": ["name", "schema_version"], + "properties": { + "name": {"const": "marqdo.execution-events"}, + "schema_version": {"const": 1} + }, + "additionalProperties": true + }, + "observation": { + "type": "object", + "required": ["level", "values", "selected_variables", "selected_parameters", "allow_text_values"], + "properties": { + "level": {"enum": ["base", "structural", "values"]}, + "values": {"type": "boolean"}, + "selected_variables": {"type": "array", "items": {"type": "string"}}, + "selected_parameters": {"type": "array", "items": {"type": "string"}}, + "allow_text_values": {"type": "boolean"} + }, + "additionalProperties": true + }, + "limits": { + "type": "object", + "required": ["max_observation_events", "max_observation_bytes", "max_value_bytes"], + "properties": { + "max_observation_events": {"type": "integer", "minimum": 0}, + "max_observation_bytes": {"type": "integer", "minimum": 0}, + "max_value_bytes": {"type": "integer", "minimum": 0} + }, + "additionalProperties": true + } + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"const": "run.started"}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["entry", "mode", "source"], + "properties": { + "entry": {"type": "string", "minLength": 1}, + "mode": {"enum": ["pure", "project", "strict"]}, + "source": { + "type": "object", + "required": ["root_id", "analysis_digest"], + "properties": { + "root_id": {"type": "string", "pattern": "^(root:|sha256:[0-9a-f]{64}$)"}, + "analysis_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"} + }, + "additionalProperties": true + }, + "started_unix_ms": {"type": "integer", "minimum": 0} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"enum": ["stdout.chunk", "stderr.chunk"]}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["encoding", "data_base64", "byte_count"], + "properties": { + "encoding": {"const": "base64"}, + "data_base64": {"type": "string", "contentEncoding": "base64"}, + "byte_count": {"type": "integer", "minimum": 0} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"const": "call.enter"}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["frame_id", "parent_frame_id", "function_id", "module_id", "span"], + "properties": { + "frame_id": {"type": "string", "pattern": "^f[0-9]+$"}, + "parent_frame_id": {"oneOf": [{"type": "null"}, {"type": "string", "pattern": "^f[0-9]+$"}]}, + "function_id": {"type": "string", "minLength": 1}, + "module_id": {"type": "string", "minLength": 1}, + "span": {"$ref": "#/$defs/span"} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"enum": ["call.exit", "return", "branch.eval", "loop.iteration", "effect"]}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["module_id", "span"], + "properties": { + "frame_id": {"type": "string", "pattern": "^f[0-9]+$"}, + "status": {"type": "string", "minLength": 1}, + "value_type": {"type": "string", "minLength": 1}, + "result": {"type": "boolean"}, + "decision": {"enum": ["continue", "exit"]}, + "operation": {"type": "string", "minLength": 1}, + "result_code": {"type": "string", "minLength": 1}, + "module_id": {"type": "string", "minLength": 1}, + "span": {"$ref": "#/$defs/span"} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"enum": ["variable.assigned", "parameter.observed"]}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["frame_id", "name", "value_type", "module_id", "span", "value_state"], + "properties": { + "frame_id": {"type": "string", "pattern": "^f[0-9]+$"}, + "name": {"type": "string", "minLength": 1}, + "source": {"enum": ["provided", "default"]}, + "value_type": {"type": "string", "minLength": 1}, + "module_id": {"type": "string", "minLength": 1}, + "span": {"$ref": "#/$defs/span"}, + "value_state": {"enum": ["not_requested", "redacted", "truncated", "unsupported", "observed"]}, + "value": {"type": ["object", "null"]} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"const": "observation.truncated"}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["reason", "limit", "written", "dropped"], + "properties": { + "reason": {"enum": ["event_budget", "byte_budget"]}, + "limit": {"type": "integer", "minimum": 0}, + "written": {"type": "integer", "minimum": 0}, + "dropped": {"type": ["integer", "null"], "minimum": 0} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"const": "run.completed"}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["status", "value"], + "properties": { + "status": {"const": "ok"}, + "value": {"type": "object"} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"const": "run.failed"}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["status", "error"], + "properties": { + "status": {"const": "error"}, + "error": {"$ref": "#/$defs/error"} + }, + "additionalProperties": true + } + } + } + }, + { + "if": {"required": ["kind"], "properties": {"kind": {"const": "run.rejected"}}}, + "then": { + "properties": { + "payload": { + "type": "object", + "required": ["status", "phase", "error"], + "properties": { + "status": {"const": "rejected"}, + "phase": {"enum": ["options", "prepare", "compile", "authorization", "strict"]}, + "error": {"$ref": "#/$defs/error"} + }, + "additionalProperties": true + } + } + } + } + ], + "$defs": { + "span": { + "oneOf": [ + {"type": "null"}, + { + "type": "object", + "required": ["start", "end"], + "properties": { + "start": {"type": "integer", "minimum": 0}, + "end": {"type": "integer", "minimum": 0} + }, + "additionalProperties": true + } + ] + }, + "error": { + "type": "object", + "required": ["code", "message"], + "properties": { + "code": {"type": "string", "minLength": 1}, + "message": {"type": "string"}, + "module_id": {"type": ["string", "null"]}, + "span": {"$ref": "#/$defs/span"} + }, + "additionalProperties": true + } + } +} diff --git a/tests/consumers/execution_events_consumer.py b/tests/consumers/execution_events_consumer.py new file mode 100644 index 0000000..f7487cd --- /dev/null +++ b/tests/consumers/execution_events_consumer.py @@ -0,0 +1,145 @@ +#!/usr/bin/env python3 +"""Black-box consumer for Marqdo Execution Events v1 (RFC-OBS-0001). + +This is an independent consumer: it imports only the Python standard library +and the `jsonschema` package, never the Rust workspace, and it consumes the +output of a released `marqdo` binary (or a checked-in fixture). + +Usage: + execution_events_consumer.py EVENTS.jsonl + execution_events_consumer.py - # read stdin + execution_events_consumer.py --schema-check FILE.jsonl + +Checks: + * every line is one JSON object validated against + `spec/schemas/execution-events-v1.schema.json`; + * `stream.opened` is first (seq 0), `run.started` occurs at most once, + exactly one terminal event on a complete stream, nothing follows it; + * `seq` is contiguous and strictly increasing; + * `run_id` and protocol/schema are consistent across lines; + * `stdout.chunk`/`stderr.chunk` base64 decodes and `byte_count` matches; + * an unknown schema major is rejected, never treated as v1. + +Exit status 0 means the stream validated. 2 means invalid input, 3 means an +incomplete stream (no terminal event; a legal boundary after SIGKILL/EOF). +""" +import base64 +import binascii +import json +import pathlib +import sys + +from jsonschema import Draft202012Validator + +ROOT = pathlib.Path(__file__).resolve().parents[2] +SCHEMA_PATH = ROOT / "spec" / "schemas" / "execution-events-v1.schema.json" +SCHEMA = json.loads(SCHEMA_PATH.read_text(encoding="utf-8")) +Draft202012Validator.check_schema(SCHEMA) +VALIDATOR = Draft202012Validator(SCHEMA) + +SCHEMA_NAME = "marqdo.execution-events" +SCHEMA_VERSION = 1 +TERMINALS = {"run.completed", "run.failed", "run.rejected"} + + +class Invalid(Exception): + pass + + +def parse_line(number, raw): + try: + event = json.loads(raw) + except json.JSONDecodeError as error: + raise Invalid(f"line {number}: not JSON: {error}") from error + if not isinstance(event, dict): + raise Invalid(f"line {number}: event is not a JSON object") + errors = sorted(VALIDATOR.iter_errors(event), key=str) + if errors: + raise Invalid(f"line {number}: schema: {errors[0].message}") + return event + + +def check_chunk(event): + payload = event["payload"] + if payload.get("encoding") != "base64": + raise Invalid(f"seq {event['seq']}: unsupported chunk encoding") + try: + data = base64.b64decode(payload["data_base64"], validate=True) + except (binascii.Error, ValueError) as error: + raise Invalid(f"seq {event['seq']}: data_base64 is not valid base64: {error}") from error + if len(data) != payload["byte_count"]: + raise Invalid( + f"seq {event['seq']}: byte_count={payload['byte_count']} but decoded {len(data)} bytes" + ) + return data + + +def consume(lines, require_terminal=True): + events = [parse_line(number, raw) for number, raw in enumerate(lines, start=1)] + if not events: + raise Invalid("empty stream") + + first = events[0] + if first["kind"] != "stream.opened": + raise Invalid("first event must be stream.opened") + if first["seq"] != 0: + raise Invalid("stream.opened must have seq 0") + if first["schema"] != SCHEMA_NAME or first["schema_version"] != SCHEMA_VERSION: + raise Invalid("stream.opened does not negotiate marqdo.execution-events v1") + + run_id = first["run_id"] + chunks = bytearray() + terminal = None + started = 0 + for index, event in enumerate(events): + seq = event["seq"] + if seq != index: + raise Invalid(f"seq {seq} at line {index + 1}; expected {index}") + if event["schema"] != SCHEMA_NAME or event["schema_version"] != SCHEMA_VERSION: + raise Invalid(f"seq {seq}: inconsistent schema negotiation") + if event["run_id"] != run_id: + raise Invalid(f"seq {seq}: run_id changed within one stream") + if terminal is not None: + raise Invalid(f"seq {seq}: event follows terminal {terminal}") + if event["kind"] == "run.started": + started += 1 + if started > 1: + raise Invalid("more than one run.started") + if event["kind"] in TERMINALS: + terminal = event["kind"] + if event["kind"] in ("stdout.chunk", "stderr.chunk"): + chunks.extend(check_chunk(event)) + + if require_terminal and terminal is None: + return 3, f"incomplete stream: {len(events)} events, no terminal event" + if terminal == "run.completed" and started != 1: + raise Invalid("run.completed requires exactly one preceding run.started") + if terminal == "run.failed" and started != 1: + raise Invalid("run.failed requires exactly one preceding run.started") + if terminal == "run.rejected" and started != 0: + raise Invalid("run.rejected must not be preceded by run.started") + return 0, ( + f"ok: {len(events)} events, terminal={terminal}, " + f"stdout+stderr bytes={len(chunks)}" + ) + + +def main(argv): + if len(argv) != 2: + raise SystemExit(__doc__) + target = argv[1] + if target == "-": + lines = [line for line in sys.stdin.read().splitlines() if line.strip()] + else: + text = pathlib.Path(target).read_text(encoding="utf-8") + lines = [line for line in text.splitlines() if line.strip()] + try: + status, message = consume(lines) + except Invalid as error: + raise SystemExit(f"execution events consumer: INVALID: {error}") + print(f"execution events consumer: {message}") + raise SystemExit(status) + + +if __name__ == "__main__": + main(sys.argv) diff --git a/tests/consumers/fixtures/execution-events/invalid/bad-chunk.json b/tests/consumers/fixtures/execution-events/invalid/bad-chunk.json new file mode 100644 index 0000000..2851bba --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/bad-chunk.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":3,"kind":"stdout.chunk","payload":{"encoding":"base64","byte_count":13}} diff --git a/tests/consumers/fixtures/execution-events/invalid/bad-span.json b/tests/consumers/fixtures/execution-events/invalid/bad-span.json new file mode 100644 index 0000000..31c0e72 --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/bad-span.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":4,"kind":"call.exit","payload":{"frame_id":"f1","status":"return","module_id":"m","span":{"start":1}}} diff --git a/tests/consumers/fixtures/execution-events/invalid/bad-terminal.json b/tests/consumers/fixtures/execution-events/invalid/bad-terminal.json new file mode 100644 index 0000000..17a5f6e --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/bad-terminal.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":5,"kind":"run.completed","payload":{"status":"ok"}} diff --git a/tests/consumers/fixtures/execution-events/invalid/empty-run-id.json b/tests/consumers/fixtures/execution-events/invalid/empty-run-id.json new file mode 100644 index 0000000..b32daa8 --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/empty-run-id.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"","seq":0,"kind":"stream.opened","payload":{"producer":{"name":"marqdo","version":"3.0.0-beta.1"},"protocol":{"name":"marqdo.execution-events","schema_version":1},"observation":{"level":"structural","values":false,"selected_variables":[],"selected_parameters":[],"allow_text_values":false},"limits":{"max_observation_events":100000,"max_observation_bytes":16777216,"max_value_bytes":256}}} diff --git a/tests/consumers/fixtures/execution-events/invalid/missing-payload.json b/tests/consumers/fixtures/execution-events/invalid/missing-payload.json new file mode 100644 index 0000000..df74bf3 --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/missing-payload.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":0,"kind":"stream.opened"} diff --git a/tests/consumers/fixtures/execution-events/invalid/missing-seq.json b/tests/consumers/fixtures/execution-events/invalid/missing-seq.json new file mode 100644 index 0000000..1985012 --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/missing-seq.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","kind":"stream.opened","payload":{"producer":{"name":"marqdo","version":"3.0.0-beta.1"},"protocol":{"name":"marqdo.execution-events","schema_version":1},"observation":{"level":"structural","values":false,"selected_variables":[],"selected_parameters":[],"allow_text_values":false},"limits":{"max_observation_events":100000,"max_observation_bytes":16777216,"max_value_bytes":256}}} diff --git a/tests/consumers/fixtures/execution-events/invalid/negative-seq.json b/tests/consumers/fixtures/execution-events/invalid/negative-seq.json new file mode 100644 index 0000000..e8a41ea --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/negative-seq.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":-1,"kind":"stream.opened","payload":{"producer":{"name":"marqdo","version":"3.0.0-beta.1"},"protocol":{"name":"marqdo.execution-events","schema_version":1},"observation":{"level":"structural","values":false,"selected_variables":[],"selected_parameters":[],"allow_text_values":false},"limits":{"max_observation_events":100000,"max_observation_bytes":16777216,"max_value_bytes":256}}} diff --git a/tests/consumers/fixtures/execution-events/invalid/unknown-major.json b/tests/consumers/fixtures/execution-events/invalid/unknown-major.json new file mode 100644 index 0000000..34045ec --- /dev/null +++ b/tests/consumers/fixtures/execution-events/invalid/unknown-major.json @@ -0,0 +1 @@ +{"schema":"marqdo.execution-events","schema_version":2,"run_id":"run-fixture-1","seq":0,"kind":"stream.opened","payload":{"producer":{"name":"marqdo","version":"3.0.0-beta.1"},"protocol":{"name":"marqdo.execution-events","schema_version":1},"observation":{"level":"structural","values":false,"selected_variables":[],"selected_parameters":[],"allow_text_values":false},"limits":{"max_observation_events":100000,"max_observation_bytes":16777216,"max_value_bytes":256}}} diff --git a/tests/consumers/fixtures/execution-events/valid/full.jsonl b/tests/consumers/fixtures/execution-events/valid/full.jsonl new file mode 100644 index 0000000..006fd80 --- /dev/null +++ b/tests/consumers/fixtures/execution-events/valid/full.jsonl @@ -0,0 +1,14 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":0,"kind":"stream.opened","payload":{"producer":{"name":"marqdo","version":"3.0.0-beta.1"},"protocol":{"name":"marqdo.execution-events","schema_version":1},"observation":{"level":"values","values":true,"selected_variables":["visible_count"],"selected_parameters":["n"],"allow_text_values":false},"limits":{"max_observation_events":100,"max_observation_bytes":1048576,"max_value_bytes":256}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":1,"kind":"run.started","payload":{"entry":"root:demo@0.1.0::index.mq.md::main","mode":"project","source":{"root_id":"root:demo@0.1.0","analysis_digest":"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"started_unix_ms":1763800000000}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":2,"kind":"call.enter","payload":{"frame_id":"f1","parent_frame_id":null,"function_id":"root:demo@0.1.0::index.mq.md::main","module_id":"root:demo@0.1.0::index.mq.md","span":null}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":3,"kind":"parameter.observed","payload":{"frame_id":"f1","name":"n","source":"provided","value_type":"Int","module_id":"root:demo@0.1.0::index.mq.md","span":null,"value_state":"observed","value":{"type":"int","decimal":"5"}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":4,"kind":"variable.assigned","payload":{"frame_id":"f1","name":"visible_count","value_type":"Int","module_id":"root:demo@0.1.0::index.mq.md","span":{"start":80,"end":100},"value_state":"observed","value":{"type":"int","decimal":"42"}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":5,"kind":"variable.assigned","payload":{"frame_id":"f1","name":"secret_token","value_type":"Text","module_id":"root:demo@0.1.0::index.mq.md","span":{"start":110,"end":150},"value_state":"redacted"}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":6,"kind":"branch.eval","payload":{"frame_id":"f1","result":true,"module_id":"root:demo@0.1.0::index.mq.md","span":{"start":160,"end":170}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":7,"kind":"loop.iteration","payload":{"frame_id":"f1","decision":"continue","module_id":"root:demo@0.1.0::index.mq.md","span":{"start":180,"end":190}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":8,"kind":"effect","payload":{"operation":"print","result_code":"ok","module_id":"root:demo@0.1.0::index.mq.md","span":{"start":200,"end":210}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":9,"kind":"stderr.chunk","payload":{"encoding":"base64","data_base64":"AA==","byte_count":1}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":10,"kind":"return","payload":{"frame_id":"f1","value_type":"Int","module_id":"root:demo@0.1.0::index.mq.md","span":{"start":220,"end":230}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":11,"kind":"call.exit","payload":{"frame_id":"f1","status":"return","module_id":"root:demo@0.1.0::index.mq.md","span":null}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":12,"kind":"observation.truncated","payload":{"reason":"event_budget","limit":100,"written":100,"dropped":null}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":13,"kind":"run.completed","payload":{"status":"ok","value":{"type":"int","decimal":"42"}}} diff --git a/tests/consumers/fixtures/execution-events/valid/minimal.jsonl b/tests/consumers/fixtures/execution-events/valid/minimal.jsonl new file mode 100644 index 0000000..985e8a1 --- /dev/null +++ b/tests/consumers/fixtures/execution-events/valid/minimal.jsonl @@ -0,0 +1,6 @@ +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":0,"kind":"stream.opened","payload":{"producer":{"name":"marqdo","version":"3.0.0-beta.1"},"protocol":{"name":"marqdo.execution-events","schema_version":1},"observation":{"level":"structural","values":false,"selected_variables":[],"selected_parameters":[],"allow_text_values":false},"limits":{"max_observation_events":100000,"max_observation_bytes":16777216,"max_value_bytes":256}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":1,"kind":"run.started","payload":{"entry":"root:demo@0.1.0::index.mq.md::main","mode":"project","source":{"root_id":"root:demo@0.1.0","analysis_digest":"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"started_unix_ms":1763800000000}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":2,"kind":"call.enter","payload":{"frame_id":"f1","parent_frame_id":null,"function_id":"root:demo@0.1.0::index.mq.md::main","module_id":"root:demo@0.1.0::index.mq.md","span":null}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":3,"kind":"stdout.chunk","payload":{"encoding":"base64","data_base64":"5byA5aeL5paH5pysCg==","byte_count":13}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":4,"kind":"call.exit","payload":{"frame_id":"f1","status":"return","module_id":"root:demo@0.1.0::index.mq.md","span":{"start":10,"end":20}}} +{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":5,"kind":"run.completed","payload":{"status":"ok","value":{"type":"int","decimal":"10"}}}