obs(03-05): fixtures, black-box schema test, CI/consumer gate and protocol docs
This commit is contained in:
1 parent
e6e497e68b
commit
2d51f08340
21 files changed
+467
-13
No files matched your search
@@ -7,9 +7,9 @@ core checkout, or host memory layout. Adding a new domain function must not
|
||||
require a core commit.
|
||||
|
||||
Product version for these docs: **`3.0.0-beta.1`** (Linux x86_64 beta).
|
||||
Protocol versions are independent: Analysis v2, Trace v2, Tool v1, Plugin ABI
|
||||
v1, Foreign wire v1, Provider manifest v2, lock v4, markdown profile
|
||||
`marqdo.md.v1`.
|
||||
Protocol versions are independent: Analysis v2, Trace v2, Execution Events v1,
|
||||
Tool v1, Plugin ABI v1, Foreign wire v1, Provider manifest v2, lock v4,
|
||||
markdown profile `marqdo.md.v1`.
|
||||
|
||||
## Pick your entry point
|
||||
|
||||
@@ -33,7 +33,7 @@ v1, Foreign wire v1, Provider manifest v2, lock v4, markdown profile
|
||||
4. [extensions.md](extensions.md) — plugins, foreign kernels, resource
|
||||
providers, extension selection and lock v4.
|
||||
5. [analysis-trace.md](analysis-trace.md) — the public static/dynamic data
|
||||
contracts and digest binding.
|
||||
contracts, Execution Events v1 and digest binding.
|
||||
6. [compatibility.md](compatibility.md) — version axes, platform matrix and the
|
||||
prerelease policy.
|
||||
7. [release-limits.md](release-limits.md) — the honest beta limitations (this
|
||||
|
||||
@@ -60,6 +60,51 @@ marqdo run index.mq.md --trace-file ./trace.json
|
||||
`spec/schemas/trace-v2.schema.json`; consumer:
|
||||
`tests/consumers/trace_consumer.py`.
|
||||
|
||||
## Execution Events v1 (live)
|
||||
|
||||
```bash
|
||||
marqdo run index.mq.md --event-stream jsonl
|
||||
marqdo call index.mq.md main --arg n=5 --event-stream jsonl
|
||||
marqdo run index.mq.md --event-stream jsonl --trace-file ./trace.json
|
||||
```
|
||||
|
||||
- `schema: "marqdo.execution-events"`, `schema_version: 1`. This is a separate
|
||||
protocol from Analysis/Trace and has its own version axis.
|
||||
- While active, the CLI stdout is a **pure NDJSON channel**: one JSON object per
|
||||
line, `seq` starts at 0 and is strictly increasing. Program stdout/stderr are
|
||||
only `stdout.chunk`/`stderr.chunk` events with `encoding: "base64"`,
|
||||
`data_base64` and a matching `byte_count`. Concatenated decoded bytes equal a
|
||||
normal run's output; invalid UTF-8/NUL/binary bytes are preserved.
|
||||
- `stream.opened` is always seq 0. A run then has at most one `run.started` and
|
||||
exactly one terminal event (`run.completed`, `run.failed`, `run.rejected`) on
|
||||
a complete stream. An EOF without a terminal event is `incomplete`
|
||||
(SIGKILL/crash/broken pipe); never synthesize success.
|
||||
- `run.started.source` contains `root_id` and the `sha256:` digest of the exact
|
||||
Analysis v2 bytes. `--trace-file` may be combined; both writers share one
|
||||
opaque run id, and Trace v2 remains atomic and value-free.
|
||||
- Structural events: `call.enter`/`call.exit` (`frame_id`, `parent_frame_id`),
|
||||
`return`, `branch.eval`, `loop.iteration`, `effect`. Frames identify call
|
||||
instances, not functions; a failed argument binding creates no frame.
|
||||
- Values are off by default (`value_state: not_requested`).
|
||||
`--observe-variable NAME` and `--observe-parameter NAME` are exact-name
|
||||
selections. `Int`/`Float`/`Bool` are bounded by
|
||||
`--observe-max-value-bytes` (default 256); selected `Text` is `redacted` until
|
||||
`--observe-text-values` is also passed. Containers, `Memory`, resources and
|
||||
plugin handles are `unsupported`; handles are never serialized.
|
||||
- Structural/value events have a separate budget
|
||||
(`--observe-max-events`, `--observe-max-bytes`; defaults 100 000 / 16 MiB).
|
||||
Exhaustion emits one `observation.truncated` and still delivers stdout/stderr
|
||||
and the terminal event. A broken output pipe fails the run with
|
||||
`observe.transport_failed`; it never keeps executing side effects silently.
|
||||
- `--event-stream` is mutually exclusive with `--json`, rejected by
|
||||
`check`/`inspect`/`fmt`/`tool`, and currently rejected by `--mode strict`
|
||||
(fail-closed, no downgrade). It is not a capability grant.
|
||||
- Contract: [`../../spec/execution-events-v1.md`](../../spec/execution-events-v1.md);
|
||||
schema: `spec/schemas/execution-events-v1.schema.json`; consumer:
|
||||
`tests/consumers/execution_events_consumer.py`; fixtures and Rust gate:
|
||||
`tests/consumers/fixtures/execution-events/` and
|
||||
`crates/cli/tests/execution_events.rs`.
|
||||
|
||||
## Consumer rules
|
||||
|
||||
1. Reject unknown schema majors; there is no silent "use latest" fallback.
|
||||
|
||||
@@ -11,6 +11,7 @@ This page summarizes the public support policy. The authoritative matrix is
|
||||
| Product / CLI | `3.0.0-beta.1` | SemVer prerelease; breaking changes inside the 3.0 beta line are allowed and appear in `CHANGELOG.md`. |
|
||||
| Analysis | v2 | New major for incompatible changes; consumers reject unknown majors. |
|
||||
| Trace | v2 | New major for incompatible changes; binds to exact Analysis bytes. |
|
||||
| Execution Events | v1 | One-line NDJSON stream; new major for incompatible required-field/ordering/redaction changes. Consumers reject unknown majors. |
|
||||
| CLI Tool | v1 | Frozen manifest/negotiation/bundle contract for v1. |
|
||||
| Plugin ABI | v1 (`1.0`) | Frozen C layout and version negotiation. |
|
||||
| Foreign wire | v1 | One-shot request envelope. |
|
||||
@@ -35,6 +36,9 @@ ranges**. Beta cores require a prerelease range such as
|
||||
|
||||
Strict is Linux-only and probe-gated. Plugin/provider worker transports are not
|
||||
OS sandboxes. `pure`/`project` are execution modes, not security boundaries.
|
||||
Execution Events v1 is a live observation protocol: it is not a capability
|
||||
grant, values are off by default, and `--mode strict` currently refuses
|
||||
`--event-stream` explicitly (no downgrade).
|
||||
|
||||
## Language compatibility
|
||||
|
||||
|
||||
@@ -61,8 +61,10 @@ Even when available:
|
||||
* `3.0.0-beta.1` is a **prerelease**, not stable and not LTS. Breaking changes
|
||||
inside the 3.0 beta series are allowed and announced in the changelog.
|
||||
* The product version is independent of protocol versions: Analysis v2, Trace
|
||||
v2, Tool v1, Plugin ABI v1, Foreign wire v1, Provider manifest v2 and lock v4
|
||||
keep their own major numbers. Do not infer them from `3.0.0-beta.1`.
|
||||
v2, Execution Events v1, Tool v1, Plugin ABI v1, Foreign wire v1, Provider
|
||||
manifest v2 and lock v4 keep their own major numbers. Do not infer them from
|
||||
`3.0.0-beta.1`. Execution Events v1 is a post-beta addition and is not in the
|
||||
tagged beta archive.
|
||||
* The official bundled stdlib keeps its independent package version `0.1.0`.
|
||||
A plugin `.mq.md` package version such as `0.1.0` is also independent.
|
||||
* `project.marqdo` in `marqdo.yaml` is enforced in this release. SemVer
|
||||
@@ -80,6 +82,20 @@ Archives are accompanied by SHA256 checksums and `RELEASE_INFO.json`
|
||||
integrity only; they are **not** a publisher signature. A digest obtained from
|
||||
an untrusted Git URL does not make the code trustworthy.
|
||||
|
||||
## Execution Events v1 (post-beta addition)
|
||||
|
||||
* Implemented: live stdout/stderr chunks, lifecycle/terminal events, call
|
||||
instance ids, branch/loop/effect events, explicit bounded value observation.
|
||||
* Not implemented: memory region/budget metadata (OBS-06/P2), raw memory
|
||||
content, breakpoints/stepping/time travel, and a bidirectional debug
|
||||
protocol. Do not infer a debugger from this protocol.
|
||||
* `--mode strict` currently rejects `--event-stream` explicitly; there is no
|
||||
silent fallback to `project`.
|
||||
* The live lane is tested on Linux x86_64; macOS/Windows are unverified for
|
||||
this option like the rest of the beta CLI.
|
||||
* Observation lowers confidentiality when values are explicitly enabled. Text
|
||||
needs a second opt-in; View/agents must not enable these flags by default.
|
||||
|
||||
## Deliberately deferred
|
||||
|
||||
strict L2, Wasm plugins, macOS/Windows provider worker, automatic uv/npm
|
||||
|
||||
@@ -91,6 +91,20 @@ Dynamic input:
|
||||
"$MARQDO_BIN" run index.mq.md --trace-file ./trace.json
|
||||
```
|
||||
|
||||
Live dynamic input (Execution Events v1):
|
||||
|
||||
```bash
|
||||
"$MARQDO_BIN" run index.mq.md --event-stream jsonl
|
||||
"$MARQDO_BIN" call index.mq.md main --arg n=5 --event-stream jsonl
|
||||
```
|
||||
|
||||
Consume the stdout line stream as NDJSON; do not pass `--json` in the same
|
||||
invocation. Negotiate by reading `stream.opened` (`marqdo.execution-events`,
|
||||
`schema_version: 1`) and reject unknown majors. A tool server may convert the
|
||||
stream to its own SSE/websocket transport; the CLI never implements HTTP/SSE.
|
||||
This option is unavailable under `--mode strict` in the current tree and the
|
||||
tool must surface that refusal instead of pretending real-time support.
|
||||
|
||||
See [analysis-trace.md](analysis-trace.md) for fields and digest rules. Do not
|
||||
depend on `inspect --ir`: that JSON is not a frozen cross-repository protocol.
|
||||
The `view` tool renders the **original Markdown**, not the Analysis JSON; the
|
||||
|
||||
Reference in new issue
Block a user