feat(stdlib): format all value types and expose handle identity members
- Add read-only FunctionRef.module/name and PluginHandle.plugin/export members; PluginHandle.id stays private (ADR-0029). - Extend stdlib/format.mq.md to Formula/Code/FunctionRef/PluginHandle/ Memory/Resource/Unit, with UTF-8 byte length for Code. - Fix two-digit ordered-list body indentation so arms 10+ stay inside their branch (they were previously top-level statements). - Extend stdlib demo to Formula/Code/FunctionRef and assert all three io.写值/打印 pairs match byte-for-byte. - Add runtime member observation test, ADR-0029, spec/status/changelog/evidence. Gate: fmt, clippy -D warnings, 416 tests passed.
This commit is contained in:
1 parent
1377af1601
commit
e119727c5d
14 files changed
+334
-15
No files matched your search
+7
-1
@@ -123,6 +123,10 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
|
||||
(`format.显示` → UTF-8 encode → `Memory` → `resource.write(stdout)`) matches
|
||||
builtin `打印` for the covered value set; builtin remains default and no
|
||||
alias is routed.
|
||||
- Full-value stdlib formatting (ADR-0029): FunctionRef `module/name` and
|
||||
PluginHandle `plugin/export` are read-only observation members (host id
|
||||
private); `stdlib/format.mq.md` reproduces builtin `打印`/`repr` for all 15
|
||||
value types, including Formula/Code/FunctionRef and Code UTF-8 byte length.
|
||||
- Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships
|
||||
`format`/`text`/`io`; explicit `std:` imports resolve only inside the bundle;
|
||||
a SHA-256 digest over `*.mq.md` is verified before loading; Analysis records
|
||||
@@ -173,7 +177,7 @@ behavior. This table records only what is in this tree now.
|
||||
| P0 freeze (ADRs, spec deltas, baseline) | **P1 + partial P2 slice done** | ADR-0022 freezes CM-A01/CM-A02/CM-A03; ADR-0023 freezes CM-A04 (minimal List/Map/Text/Table observation and construction); ADR-0024 freezes CM-A05 (recoverable `Result` map convention); `spec/expression.ebnf`, `spec/evaluation.md`, `spec/value-wire.md`, `spec/analysis-v2.md`, `spec/security.md` updated; existing AST/value goldens unchanged |
|
||||
| P1 Memory + place assignment | **Implemented locally** | `Value::Memory`, run-scoped `MemoryStore` (64 KiB pages, 64 MiB total / 16 MiB region), `memory.new/size/grow`, `m[i]` read, `m[i] = byte`; semantic fixtures 45–47, runtime negatives 13–18, `examples/memory-buffer.mq.md`; evidence [`evidence/2026-11-20-memory-p1.md`](evidence/2026-11-20-memory-p1.md) |
|
||||
| P2 Marqdo-written allocator/data structures + minimal structure observation | **PARTIAL, gate NOT passed** | `.mq.md`-only evidence: bump allocator with u32 codec, linked list, failed-allocation atomicity (48–50); CM-A04 structure primitives and a table filter (51–54, ADR-0023); a first-fit free-list allocator with block reuse, splitting, address-adjacent coalescing and `Result` maps (55, ADR-0024), a `Memory`-backed binary tree with recursive insert/in-order traversal (56), a `.mq.md` CSV row splitter (57), an open-addressing hash table with linear probing, update and `hash.full` (58), a `.mq.md` UTF-8 encoder over `Memory` (59), a validating UTF-8 decoder rejecting truncated, bad-continuation and surrogate/overlong input (60), a `Memory`-backed graph adjacency list (61), a recursive JSON parser for nested arrays/objects, strings with escapes, integers, booleans, null and error Results (62), a `Memory`-backed stack bytecode VM with PUSH/ADD/MUL/JMP/JZ/HALT (63), big-endian 16/32/64-bit plus LEB128 integer codecs (64), a `.mq.md` table sort rebuilding a new table from `table.row/columns/cell` (65), a table join (67), a quoted/escaped CSV row parser (68), table group (69), and an Int matrix multiply (70); the first-fit allocator also detects double free (`alloc.double_free`). Evidence: [`memory-p2-closure`](evidence/2026-11-20-memory-p2-closure.md), [`structure-api-p2`](evidence/2026-11-20-structure-api-p2.md), [`result-and-free-list-p2`](evidence/2026-11-20-result-and-free-list-p2.md). P2 remaining: publication as a separate external stdlib repository. The bundled `stdlib/` tree, `std:` imports, digest verification, Analysis identity and frozen-CLI closure test are implemented (ADR-0028). C01–C06/C11/C12 each have `.mq.md` evidence, including JSON floats and a JSON formatter. |
|
||||
| P3 Resource/Stream ABI | **PARTIAL** | ADR-0025/0026 CM-A06 slices: opaque `Resource`, `resource.open/read/write/close`, stdout write in pure/project, granted project-file read and buffered project-file write in project, EOF/closed/handle errors, wire/host rejection; strict refuses all opens. Fixture 66 + CLI/host tests. CM-A07 is **Compat-A only**: the bundled `stdlib/` provides an explicitly imported `.mq.md` `format/utf8/io` chain (`std:` imports) whose output matches builtin `打印` for Unit/None/Bool/Int/Float/Text/List/Map/Table; builtin `打印` remains default, no alias routing, and Formula/Code/FunctionRef/PluginHandle formatting is still unobservable. Still missing: Compat-B/C, directories, network, generic provider registry. |
|
||||
| P3 Resource/Stream ABI | **PARTIAL** | ADR-0025/0026 CM-A06 slices: opaque `Resource`, `resource.open/read/write/close`, stdout write in pure/project, granted project-file read and buffered project-file write in project, EOF/closed/handle errors, wire/host rejection; strict refuses all opens. Fixture 66 + CLI/host tests. CM-A07 is **Compat-A only**: the bundled `stdlib/` provides an explicitly imported `.mq.md` `format/utf8/io` chain (`std:` imports) whose output matches builtin `打印` for all 15 value types (Unit/None/Bool/Int/Float/Text/List/Map/Table/Formula/Code/FunctionRef/PluginHandle/Memory/Resource); builtin `打印` remains default and no alias routing exists yet (Compat-B pending). Still missing: Compat-B/C, directories, network, generic provider registry. |
|
||||
| P4 Table logical/physical migration | **NOT IMPLEMENTED** | `Value::Table` remains `Vec<Vec<Value>>`; no stdlib table algorithms |
|
||||
| P5 third-party Provider / TCP / HTTP | **NOT IMPLEMENTED** | `fs.write`, `net.request`, `process`, `clock`, `random` remain unavailable broker services (see §4) |
|
||||
| P6 performance / native backends | **NOT IMPLEMENTED** | no bytecode/JIT/GPU/QPU work |
|
||||
@@ -202,6 +206,8 @@ user-written allocator is explicitly **not** claimed.
|
||||
- [`evidence/2026-11-20-bundled-stdlib-cm-a10.md`](evidence/2026-11-20-bundled-stdlib-cm-a10.md)
|
||||
— CM-A10 bundled stdlib, `std:` imports, digest verification, Analysis
|
||||
identity and frozen-binary closure test.
|
||||
- [`evidence/2026-11-20-full-value-formatting.md`](evidence/2026-11-20-full-value-formatting.md)
|
||||
— ADR-0029 observation members and all-15-type stdlib formatting comparison.
|
||||
- [`evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md`](evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md)
|
||||
— G0..G12 matrix and RC decision.
|
||||
- [`security-gate.md`](security-gate.md) — mechanism, attack matrix and strict
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# ADR-0029: Full-value stdlib formatting and handle observation (CM-A04/A07)
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-20
|
||||
Relates to: `docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md`
|
||||
(CM-A04, CM-A07, P2/P3), ADR-0023, ADR-0027, ADR-0028
|
||||
Specs: `spec/evaluation.md`
|
||||
Evidence: `docs/evidence/2026-11-20-full-value-formatting.md`
|
||||
|
||||
## Context
|
||||
|
||||
Compat-A (ADR-0027) formats Unit/None/Bool/Int/Float/Text/List/Map/Table, but
|
||||
builtin `打印` also formats Formula, Code, FunctionRef and PluginHandle. A
|
||||
Compat-B name route cannot be honest while the stdlib silently differs on
|
||||
those types. The missing pieces are the **identity/observation** fields needed
|
||||
to reproduce `Value::repr()` for function references and plugin handles;
|
||||
Formula and Code already expose `latex/display/unit` and
|
||||
`language/source/content_hash/unit`.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Read-only identity members
|
||||
|
||||
Add member reads (no new value types, no mutation, no handles):
|
||||
|
||||
| Value | Members |
|
||||
|---|---|
|
||||
| `FunctionRef` | `module: Text`, `name: Text` |
|
||||
| `PluginHandle` | `plugin: Text`, `export: Text` |
|
||||
|
||||
The host-assigned numeric `PluginHandle.id` remains private; only the manifest
|
||||
plugin name and export name are exposed, which are already visible in
|
||||
`Value::repr()` and are not a capability token. `Memory` and `Resource` remain
|
||||
opaque and expose no fields. Unknown members are `runtime.unknown_field`.
|
||||
|
||||
### 2. Stdlib formatting covers all 15 value types
|
||||
|
||||
`stdlib/format.mq.md` gains branches for:
|
||||
|
||||
* `Formula`: `Formula(<debug-quoted latex>)`;
|
||||
* `Code`: `Code(<debug-quoted language>, <utf8-byte-length> bytes)`
|
||||
(the byte length is computed with `stdlib/text.mq.md`, not `长度`, which is
|
||||
Unicode scalar count);
|
||||
* `FunctionRef`: `FunctionRef(module::name)`;
|
||||
* `PluginHandle`: `PluginHandle(plugin::export)`;
|
||||
* `Memory`/`Resource`: the literal `Memory`/`Resource`;
|
||||
* `Unit`: `Unit`.
|
||||
|
||||
The existing `Text`/collection escaping (quotes, backslash, newline, tab, CR)
|
||||
is reused. Control characters outside those escapes are not emitted as
|
||||
`\u00XX` in this slice; that is a formatting limitation, not a security
|
||||
boundary, and does not affect the current corpus.
|
||||
|
||||
### 3. Compatibility
|
||||
|
||||
* The new members are additive observations; no existing expression changes.
|
||||
* `PluginHandle.id` is not observable and cannot be used to forge a handle.
|
||||
* `打印` remains the builtin default; this ADR only makes the stdlib formatter
|
||||
capable of matching it for all value types. Compat-B routing is a separate
|
||||
decision (ADR-0030).
|
||||
* Formula/Code provenance spans are not exposed as members; only the fields
|
||||
already present in the value wire/repr are.
|
||||
|
||||
## Non-goals
|
||||
|
||||
* No mutable handle inspection, no resource/plugin capability escalation.
|
||||
* No `\u00XX` escaping of arbitrary control characters.
|
||||
* No change to `Value::display()`/`repr()` themselves; the stdlib must match
|
||||
the existing behavior, not redefine it.
|
||||
* No print name routing in this ADR.
|
||||
|
||||
## Consequences
|
||||
|
||||
* The stdlib formatter can reproduce `打印` output for all 15 current value
|
||||
types, removing the Compat-B blocker documented in ADR-0027.
|
||||
* Function/plugin identity becomes readable in `.mq.md`; this is already public
|
||||
in display/repr and does not reveal the host-only numeric handle id.
|
||||
* Code byte length performs one UTF-8 encode into a temporary `Memory`; large
|
||||
code values cost an extra allocation during formatting. A future core
|
||||
observation could avoid it without changing output.
|
||||
|
||||
## Verification
|
||||
|
||||
`docs/evidence/2026-11-20-full-value-formatting.md` records the member-read
|
||||
tests, a Formula/Code/FunctionRef formatting comparison against builtin
|
||||
`打印`, and the full workspace gate.
|
||||
@@ -25,6 +25,7 @@ implementation status lives in `docs/STATUS.md`; frozen behavior is in
|
||||
| CM-A06 buffered project-file write | [0026](../adr/0026-buffered-project-file-write-streams.md) | Accepted |
|
||||
| CM-A07 print migration staging / Compat-A | [0027](../adr/0027-print-migration-compat-a.md) | Accepted (Compat-A only) |
|
||||
| CM-A10 bundled stdlib / `std:` imports / digest | [0028](../adr/0028-bundled-stdlib-and-std-imports.md) | Accepted (first slice) |
|
||||
| Full-value stdlib formatting / FunctionRef+PluginHandle observation | [0029](../adr/0029-full-value-formatting-and-handle-observation.md) | Accepted |
|
||||
| CM-A07 Compat-B/C, Table storage, generic providers, strict resources | — | Not decided; do not implement by implication |
|
||||
|
||||
## What a future phase must not do
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# RFC-CM ADR-0029 evidence: full-value stdlib formatting
|
||||
|
||||
Date: 2026-11-20 (Asia/Shanghai)
|
||||
Repository: `marqdo-cli`
|
||||
Baseline: `1377af1` plus this step's changes.
|
||||
Decision record: [ADR-0029](../adr/0029-full-value-formatting-and-handle-observation.md)
|
||||
Related: [Compat-A](2026-11-20-stdlib-print-compat-a.md),
|
||||
[bundled stdlib](2026-11-20-bundled-stdlib-cm-a10.md), [STATUS §5](../STATUS.md).
|
||||
Scope: observation members + stdlib formatter. No print name routing.
|
||||
|
||||
## Environment and gate
|
||||
|
||||
Ubuntu 26.04 development container, Linux x86_64, Rust 1.100.0.
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace --locked PASS
|
||||
416 passed, 0 failed, 2 ignored (existing plugin-sdk doc-tests)
|
||||
```
|
||||
|
||||
No GitHub CI is available from this checkout; this is local evidence.
|
||||
|
||||
## Observation members
|
||||
|
||||
`Value::FunctionRef` now exposes `module` and `name`; `Value::PluginHandle`
|
||||
exposes `plugin` and `export`. The numeric host `PluginHandle.id` remains
|
||||
private. Formula/Code members were already public. Memory/Resource remain
|
||||
opaque with no fields.
|
||||
|
||||
Runtime test `function_ref_and_resource_members_are_readable` checks:
|
||||
|
||||
```text
|
||||
ref("#目标").module -> root:default::index.mq.md
|
||||
ref("#目标").name -> 目标
|
||||
ref("#公式").latex -> a = 1
|
||||
ref("#公式").display -> true
|
||||
ref("#代码").language-> text
|
||||
ref("#代码").source -> "x\n"
|
||||
```
|
||||
|
||||
## Formatter coverage
|
||||
|
||||
`stdlib/format.mq.md` now has branches for all 15 value types:
|
||||
|
||||
`Unit`, `None`, `Bool`, `Int`, `Float`, `Text`, `List`, `Map`, `Table`,
|
||||
`Formula`, `Code`, `FunctionRef`, `PluginHandle`, `Memory`, `Resource`.
|
||||
|
||||
* Formula/Code/FunctionRef/PluginHandle reproduce the existing `Value::repr()`
|
||||
spellings (not a new format).
|
||||
* Code byte length is computed from `text.codepoints` by summing UTF-8 widths,
|
||||
not from `长度` (scalar count) and without a temporary `Memory`.
|
||||
* Text inside collections is quoted/escaped; top-level Text is raw.
|
||||
|
||||
## Comparison
|
||||
|
||||
`stdlib/demo.mq.md` compares `io.写值` with builtin `打印`:
|
||||
|
||||
```text
|
||||
["文本", 2, 1.5, [3, true], {a: 1, b: "x"}, None]
|
||||
["文本", 2, 1.5, [3, true], {a: 1, b: "x"}, None]
|
||||
Table[名称 | 分数]{甲 | 87; 乙 | 92}
|
||||
Table[名称 | 分数]{甲 | 87; 乙 | 92}
|
||||
[Formula("a = 1"), Code("text", 9 bytes), FunctionRef(root:default::demo.mq.md::演示函数)]
|
||||
[Formula("a = 1"), Code("text", 9 bytes), FunctionRef(root:default::demo.mq.md::演示函数)]
|
||||
```
|
||||
|
||||
`examples_r6::mqmd_stdlib_print_output_matches_builtin_print` asserts all three
|
||||
pairs byte-identically, including the Formula/Code/FunctionRef line.
|
||||
|
||||
## What is not done
|
||||
|
||||
* No `打印/print` name routing (Compat-B). Builtin remains the default.
|
||||
* PluginHandle formatting is covered by code branches and observation, but no
|
||||
fixture constructs a live PluginHandle without a plugin invocation.
|
||||
* Control characters outside `"`, `\`, newline, tab and CR are not emitted as
|
||||
`\u00XX`.
|
||||
* Memory/Resource formatting is the literal type name, matching
|
||||
`Value::display()`; no internal identity leaks.
|
||||
|
||||
## Reproduce
|
||||
|
||||
```bash
|
||||
export PATH=/root/.cargo/bin:$PATH
|
||||
export CARGO_HOME=/root/work/marqdo-cli/.cache/cargo
|
||||
export CARGO_TARGET_DIR=/root/work/marqdo-cli/.cache/target
|
||||
cargo run -q -p marqdo-cli -- run stdlib/demo.mq.md
|
||||
cargo test -p marqdo-cli --test examples_r6
|
||||
cargo test -p marqdo-runtime --test interpreter function_ref_and_resource_members
|
||||
cargo test --workspace --locked
|
||||
```
|
||||
Reference in new issue
Block a user