release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated Cargo.lock; project.marqdo is enforced against the running core with package.marqdo_range_invalid/package.marqdo_incompatible fail-closed diagnostics; Tool SemVer prerelease negotiation tests; init template and examples use the beta range. Verify init derives the project name from the target directory instead of falling back to 'example'. REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for the release evidence. REL-03: deterministic release packaging (tools/release/package.py) ships the CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json, known-limitations, specs, developer docs, examples incl. built plugin/provider artifacts and consumers; tools/release/smoke.py cold-install tests the archive. REL-04: docs/developers entry pages; corrected and self-contained third-party integration handbook; stale Proposed/native-only/informational spec claims fixed; release/status/compatibility/changelog/releasing docs updated. REL-05: release_evidence.py gains an explicit beta profile (BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build step now packages and smoke-tests the archive on every pipeline. Adds a runnable Resource Provider v2 example and corrects check --emit to Analysis v2.
This commit is contained in:
1 parent
56189b176c
commit
2c7c4f31e7
55 files changed
+3136
-453
No files matched your search
@@ -0,0 +1,70 @@
|
||||
# Analysis v2 and Trace v2 consumers
|
||||
|
||||
Both are public, versioned JSON artifacts. A consumer must read them as files,
|
||||
never link Marqdo's Rust internals or depend on `inspect --ir`.
|
||||
|
||||
## Analysis v2 (static)
|
||||
|
||||
```bash
|
||||
marqdo check index.mq.md --emit ./analysis.json
|
||||
```
|
||||
|
||||
- Write atomically; only publish after `check` exits 0. `--refs` is an
|
||||
independent Markdown-link check and can make `check` fail; on failure the emit
|
||||
target is removed. Do not generate a consumer artifact with
|
||||
`check --refs --emit` without checking the exit code.
|
||||
- `schema: "marqdo.analysis"`, `schema_version: 2`.
|
||||
- Top level: `producer` (`name`, `version` = product version,
|
||||
`markdown_profile`), `project`, `modules`, `diagnostics`.
|
||||
- `project`: `root_id` (`root:<name>@<version>` for manifest projects),
|
||||
`identity_kind`, `lock_digest` (`""` without a lock), `stdlib`
|
||||
(`version`, `digest`, `instance_id`; may be null).
|
||||
- `modules[]`: `id`, `package_instance_id`, `relative_path`, `source_digest`,
|
||||
`units`, `functions`, `imports`, `references`, `calls`, `resources`.
|
||||
Diagnostics are top-level, not per-module.
|
||||
- Byte offsets are UTF-8 source offsets. Stable index keys are logical package
|
||||
instance ids, never absolute paths.
|
||||
- `check` does not load plugin libraries, start kernels/providers or execute the
|
||||
program.
|
||||
- Schemas: `spec/schemas/analysis-v2.schema.json`; contract:
|
||||
`spec/analysis-v2.md`; consumers: `tests/consumers/analysis_consumer.py`,
|
||||
`tests/consumers/validate_protocols.py`.
|
||||
|
||||
View must render the **original Markdown** and use Analysis only to correlate
|
||||
source offsets/heading units/callable mapping. Knowledge must use heading
|
||||
anchors, links, resources, package identity and source digests; it must not
|
||||
assume a `@knowledge` unit has runtime effects. Prove must map only the public
|
||||
proveable subset and distinguish `proved / disproved / unknown / unsupported`;
|
||||
a proof certificate needs matching source digest, semantics and contract
|
||||
identity.
|
||||
|
||||
## Trace v2 (dynamic)
|
||||
|
||||
```bash
|
||||
marqdo run index.mq.md --trace-file ./trace.json
|
||||
```
|
||||
|
||||
- `schema: "marqdo.trace"`, `schema_version: 2`.
|
||||
- `source.analysis_digest` must equal SHA-256 of the **Analysis JSON bytes** for
|
||||
the same project/projection configuration. A mismatch means the trace is
|
||||
stale; do not bind it to the new source. `run --trace-file` does not emit
|
||||
Analysis itself.
|
||||
- Event kinds: `call.enter`, `call.exit`, `branch.eval`, `loop.iteration`,
|
||||
`return`, `effect`, and possibly `trace.truncated`. Sourced events carry a
|
||||
module id and a UTF-8 span.
|
||||
- Defaults are 100,000 events / 32 MiB; `--trace-max-events` and
|
||||
`--trace-max-bytes` adjust them (`0` = unlimited). A consumer must tolerate
|
||||
truncation and must not assume the trace is complete.
|
||||
- Trace records no argument values, secrets or file contents.
|
||||
- Contract: `spec/trace-v2.md`; schema:
|
||||
`spec/schemas/trace-v2.schema.json`; consumer:
|
||||
`tests/consumers/trace_consumer.py`.
|
||||
|
||||
## Consumer rules
|
||||
|
||||
1. Reject unknown schema majors; there is no silent "use latest" fallback.
|
||||
2. Verify `source.analysis_digest` against the actual Analysis file bytes.
|
||||
3. Verify `source.root_id`/package identity; do not key on absolute paths.
|
||||
4. Be deterministic and offline; never execute `.mq.md` yourself, never invent
|
||||
host effects, and never inherit Marqdo grants.
|
||||
5. Report an unsupported/stale artifact explicitly; do not silently downgrade.
|
||||
Reference in new issue
Block a user