obs(00): publish Execution Events v1 contract, ADR and consumer fixtures
This commit is contained in:
1 parent
eeea01d672
commit
d38736c0a0
18 files changed
+1746
-2
No files matched your search
@@ -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"));
|
||||
|
||||
@@ -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.
|
||||
+4
-1
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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:<digest>"}}}
|
||||
{"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` 的一致性测试为准;占位的 `<digest>` 不是有效 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<String>, // 精确名称选择,不自动全量输出
|
||||
selected_parameters: Vec<String>,
|
||||
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=<error-code>)`,再最终 `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 和扩展库时继续保持真正的仓库解耦。
|
||||
@@ -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": <byte>, "end": <byte>}` 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": <n>`. 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.
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
@@ -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}}
|
||||
@@ -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}}}
|
||||
@@ -0,0 +1 @@
|
||||
{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":5,"kind":"run.completed","payload":{"status":"ok"}}
|
||||
@@ -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}}}
|
||||
@@ -0,0 +1 @@
|
||||
{"schema":"marqdo.execution-events","schema_version":1,"run_id":"run-fixture-1","seq":0,"kind":"stream.opened"}
|
||||
@@ -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}}}
|
||||
@@ -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}}}
|
||||
@@ -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}}}
|
||||
@@ -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"}}}
|
||||
@@ -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"}}}
|
||||
Reference in new issue
Block a user