Files
marqdo-cli/docs/adr/0027-print-migration-compat-a.md
cflmy 1377af1601 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.
2026-11-20 21:43:14 +08:00

104 lines
4.7 KiB
Markdown

# ADR-0027: CM-A07 print-migration staging and the Compat-A `.mq.md` stdlib prototype
Status: **Accepted (Compat-A only; Compat-B/C pending)**
Date: 2026-11-20
Relates to: `docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md`
(CM-A07, CM-A10, P3), ADR-0023, ADR-0024, ADR-0025, ADR-0026
Specs: `spec/evaluation.md`
Evidence: `docs/evidence/2026-11-20-stdlib-print-compat-a.md`
## Context
RFC-CM-0002 §5.4 and CM-A07 require `打印` to stop being a hidden Rust
`Value::display()` path. The migration has three compatibility stages:
* **Compat-A**: a real `.mq.md` print implementation exists and is callable
through explicit imports; the legacy builtin remains the default.
* **Compat-B**: the `print/打印` name routes to the stdlib implementation
(or an alias table maps it), while old behavior is comparison-tested.
* **Compat-C**: the legacy `HostOp::Print` formatting path is removed from the
public builtin implementation.
This ADR freezes the staging policy and implements **Compat-A only**. It does
not change `打印` resolution, does not remove `HostOp::Print`, and does not
claim CM-A07 complete.
## Decision
### 1. Stage policy
* A stage is only complete when its comparison evidence exists:
* A: explicit stdlib functions exist and their output is compared with the
builtin for the covered value set;
* B: name resolution tests prove a single implementation is selected and old
callers still behave;
* C: all old goldens pass with no `HostOp::Print` formatting path.
* Stages are additive; no stage may silently make a second implementation
reachable for the same name.
* `strict` behavior is unchanged by stdlib-only code; a stdlib print still
needs the console/resource grant.
### 2. Compat-A implementation
Add a normal `.mq.md` module package (later moved to the bundled `stdlib/` tree by ADR-0028):
```text
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` →
`resource.open("stdio","stdout",["write"])` → `resource.write` → `close`.
This uses only the public core/resource contracts; it is ordinary imported
`.mq.md` code, not a new builtin.
Covered value types: `Unit`, `None`, `Bool`, `Int`, `Float`, `Text`, `List`,
`Map`, `Table`. Formatting matches the builtin `Value::display()` for the
checked corpus, including Text quoting/escaping inside collections, canonical
map key order and table layout.
**Not covered yet**: `Formula`, `Code`, `FunctionRef`, `PluginHandle`. The
language currently has no public observation for the module/name/handle
identity needed to reproduce `Value::display()`/`repr()` for those types.
Adding such observation would be a CM-A04 extension and is out of scope.
### 3. Compatibility rules
* `打印` remains the default builtin in this slice. `io.写值` is only reachable
through an explicit import alias; there is no implicit module, bundled stdlib
resolution or global name shadowing.
* No `HostOp` is added or removed. Both paths write through the console/output
budget; the stdlib path additionally goes through the resource ABI.
* Stdlib modules are ordinary Markdown documents: no special parser, no
embedded Rust formatter, no direct formatting syscall.
* A future Compat-B ADR must define name precedence, bundled module lookup,
stdlib version/digest (CM-A10) and failure behavior; this ADR does not.
### 4. Non-goals
* No `print` alias routing, no removal of `HostOp::Print`.
* No bundled stdlib install/version/digest or offline distribution.
* No formatting of Formula/Code/FunctionRef/PluginHandle.
* No locale-aware, width-aware or float-format changes.
* No change to Markdown rendering, `strict`, or the wire/ABI.
* No claim that the examples directory is the shipped standard library.
## Consequences
* The target call chain (`format.display` → `utf8_encode` → `write_all` →
`resource.write`) is exercised end to end in `.mq.md` and can be compared to
the builtin.
* The missing observation for `Formula/Code/FunctionRef/PluginHandle` is now an
explicit, documented blocker for Compat-B rather than an implicit assumption.
* Because the stdlib is not bundled, ordinary users still get the builtin; the
prototype does not yet reduce the runtime's formatting surface.
## Verification
`docs/evidence/2026-11-20-stdlib-print-compat-a.md` records the side-by-side
demo (`io.写值` vs `打印` for a nested list and a table), the CLI test asserting
byte-identical lines, and the full workspace gate. It also records the covered
and uncovered value types.