feat(stdlib): ship a verified bundled stdlib with std: imports

- Move the Compat-A print prototype into stdlib/ as the official offline
  bundle with stdlib.json (version 0.1.0 + sha256 content digest).
- Add std:<relative> import resolution in the loader with bundle path
  confinement, extension inference and fail-closed digest verification.
- Record the verified version/digest/instance_id in Analysis v2
  project.stdlib; stdlib modules get a std:name@version#digest instance id.
- Add CLI tests: std:io execution, digest-tamper rejection, missing manifest,
  Analysis identity, no foreign/plugin calls, and frozen binary hash equality.
- Update ADR-0028, specs, status, changelog and evidence.

Gate: fmt, clippy -D warnings, 415 tests passed.
This commit is contained in:
cflmy committed 2026-11-20 21:43:14 +08:00
1 parent 1a978c7a42
commit 1377af1601
28 files changed
+879 -23

No files matched your search

+5 -5
View File
@@ -40,13 +40,13 @@ claim CM-A07 complete.
### 2. Compat-A implementation
Add a normal `.mq.md` module package under `examples/stdlib/`:
Add a normal `.mq.md` module package (later moved to the bundled `stdlib/` tree by ADR-0028):
```text
examples/stdlib/format.mq.md # 显示 / 列表显示 / 映射显示 / 表格显示 / 转义文本
examples/stdlib/text.mq.md # utf8编码 (Memory bytes)
examples/stdlib/io.mq.md # 写文本 / 写值 (resource.open stdout + write/close)
examples/stdlib/demo.mq.md # side-by-side comparison with 打印
stdlib/format.mq.md # 显示 / 列表显示 / 映射显示 / 表格显示 / 转义文本
stdlib/text.mq.md # utf8编码 (Memory bytes)
stdlib/io.mq.md # 写文本 / 写值 (resource.open stdout + write/close)
stdlib/demo.mq.md # side-by-side comparison with 打印
```
`io.写值(值)` = `format.显示(值) + "\n"` → `text.utf8编码` → `Memory` →
@@ -0,0 +1,142 @@
# ADR-0028: Bundled standard library, `std:` imports and digest verification (CM-A10)
Status: **Accepted**
Date: 2026-11-20
Relates to: `docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md`
(CM-A10, CM-A07, P2/P3), ADR-0027
Specs: `spec/analysis-v2.md`, `spec/references.md`
Evidence: `docs/evidence/2026-11-20-bundled-stdlib-cm-a10.md`
## Context
CM-A07 Compat-A put a real `.mq.md` print chain under `examples/stdlib/`, but it
was reachable only by relative path from a demo in the same directory. A
standard library that ordinary projects can use offline needs:
* a fixed bundle shipped with the CLI;
* an explicit import spelling that cannot be shadowed by a project file;
* a content identity so a different bundle with the same version cannot
masquerade;
* no network, Git or package installation required at run time.
The RFC requires the official distribution to carry a tested stdlib version
offline, while allowing independent releases. This ADR freezes the **bundled
first slice**; it does not create the external `cflmy/marqdo-stdlib`
repository or a public publishing workflow.
## Decision
### 1. Bundle location
The official bundle is the `stdlib/` tree shipped next to the CLI (or vendored
at the repository root during development). Discovery order:
1. `MARQDO_STDLIB_DIR` — explicit override; if set and invalid, loading fails
hard (no silent fallback);
2. `<executable-dir>/stdlib` if it exists;
3. the development tree `<repo>/stdlib` for source builds.
If no bundle is found, a project that uses `std:` fails with a clear error; a
project that does not use `std:` is unaffected. No network, Git or package
manager is consulted for a bundled stdlib.
### 2. Explicit `std:` imports only
Front-matter imports may name a stdlib module as:
```yaml
import:
io: "std:io"
fmt: "std:format"
parser: "std:data/json"
```
The target after `std:` is a **package-relative** path inside the bundle.
`..`, absolute paths and `std:` targets that escape the bundle are rejected;
`.mq.md` is appended when the target has no extension. `std:` is resolved
before relative/alias imports and never searches the project or dependencies.
There is no implicit `std` namespace, no global name, and no auto-import.
Module ids use a stable package instance:
```text
std:marqdo-stdlib@<version>#<sha256-hex>
```
so the same logical module from a different bundle is a different instance.
### 3. Content digest
`stdlib/stdlib.json` carries the name, version and digest. The digest is:
```text
sha256( for each sorted *.mq.md relative path:
path_utf8, NUL, file_bytes, NUL )
```
It excludes `stdlib.json`, README files and non-`.mq.md` files. The loader
recomputes it before loading any stdlib module and fails closed on mismatch or
a missing manifest. A bundle is therefore identified by **name + version +
exact markdown bytes**, not by a path or a version string alone.
### 4. Visibility and analysis
Analysis v2 records the verified bundle identity under `project.stdlib`:
```json
{"version":"0.1.0","digest":"sha256:<hex>",
"instance_id":"std:marqdo-stdlib@0.1.0#<hex>"}
```
It is `null` when no bundle was available. A project that imports `std:` always
has a non-null identity. Trace/diagnostics keep the real stdlib source spans;
the bundle is normal Markdown, not a special-cased module type.
### 5. Frozen-CLI closure lane
The first closure test builds the CLI once, hashes the executable, runs a
project importing `std:io`, then re-hashes the executable and asserts equality.
It also asserts:
* the project uses only `.mq.md` and standard imports, no `foreign`/`plugin`
calls;
* a tampered bundle fails the digest check before any module executes;
* Analysis records the verified digest.
This is a local gate, not a replacement for a remote CI lane.
### 6. Versioning
The bundle version is `0.1.0` for this slice. A CLI may load a bundle whose
version is declared compatible by this ADR; the RFC's full SemVer/digest
contract and independent release workflow remain CM-A10 follow-up. A future
core feature that the bundle requires must be reflected in both the bundle
version and the CLI's compatibility table before release.
## Non-goals
* Creating/publishing the external `cflmy/marqdo-stdlib` repository or a
package registry entry.
* Automatic download/update, Git fetching, or manifest-driven stdlib
installation.
* A second plugin/provider system or a second module search path.
* Compat-B/C name routing of `打印` (ADR-0027) — the bundle does not change
builtin resolution.
* Windows/macOS packaging layout; only the source-tree/executable-adjacent
layout is exercised locally.
## Consequences
* Any project can `import: {io: "std:io"}` and use the print prototype
offline; `打印` remains the default builtin.
* A changed stdlib file without a digest update is rejected before execution.
* The bundle is still an in-repo vendored package. Independent repository
release and CI signing are explicitly tracked as remaining CM-A10 work.
* Analysis artifacts and a frozen binary can be tied to the exact stdlib
digest, which is the prerequisite for Compat-B and reproducible releases.
## Verification
`docs/evidence/2026-11-20-bundled-stdlib-cm-a10.md` records the `std:` import
test, digest-tamper rejection, Analysis identity assertion, no-foreign policy
scan and frozen binary hash equality.