feat(rfc-cm): baseline P0-P3 compute machine, stdlib and resource slices
Implements the first vertical slices of RFC-CM-0001/0002 on top of a113d89:
- P1: opaque Memory regions (64 KiB pages, budgets, grow-only), byte
read/write, Memory-index place assignment, wire/host-boundary rejection.
- CM-A04/A05: value-semantics List/Map/Text/Table primitives and the
recoverable Result map convention.
- CM-A06: opaque Resource handles, resource.open/read/write/close, stdout
write, granted project-file read and buffered write, strict fail-closed.
- CM-A07 Compat-A: explicit .mq.md format/utf8/io chain matching builtin
print for the covered value types; builtin remains default.
- P2 fixtures: allocators, list/tree/graph/hash, integer codecs, UTF-8
encode/decode, CSV/JSON subsets, table filter/sort/join, bytecode VM.
- ADRs 0022-0027, spec updates, evidence reports and 68 semantic goldens.
Gate: cargo fmt --check, clippy -D warnings, 407 tests passed.
This commit is contained in:
1 parent
a113d89496
commit
92bfbf2568
127 files changed
+11351
-141
No files matched your search
+20
-1
@@ -1,6 +1,7 @@
|
||||
# Marqdo Analysis v2
|
||||
|
||||
Status: **implemented by `marqdo check --emit <path>` (S2).** Supersedes
|
||||
Status: **implemented by `marqdo check --emit <path>` (S2); ADR-0022 adds an
|
||||
additive index target shape.** Supersedes
|
||||
Analysis v1. v1 was never released; it is kept as history and is not written.
|
||||
|
||||
## 1. Invariants
|
||||
@@ -82,6 +83,24 @@ index, call). `imports`, `references` and `calls` remain static facts; a
|
||||
Markdown reference is not a call. `effects` remains `["unknown"]` (a
|
||||
conservative summary, not a purity proof).
|
||||
|
||||
An `assign` node keeps the v1 string `target` for a local rebinding. Addressable
|
||||
memory adds one additive target form (ADR-0022); consumers that only understand
|
||||
local assignments can ignore an object target:
|
||||
|
||||
```json
|
||||
{"kind":"assign",
|
||||
"target":{"kind":"index",
|
||||
"base":{"kind":"variable","name":"内存","span":{"start":23,"end":26}},
|
||||
"index":{"kind":"literal","type":"int","value":"0","span":{"start":27,"end":28}},
|
||||
"span":{"start":23,"end":29}},
|
||||
"value":{"kind":"literal","type":"int","value":"7","span":{"start":32,"end":33}},
|
||||
"span":{"start":18,"end":35}}
|
||||
```
|
||||
|
||||
`target.kind` is `"index"`; `base` and `index` use the same expression node
|
||||
shapes as every other expression. Analysis is static: it records the place but
|
||||
never allocates a region or executes the write.
|
||||
|
||||
## 4. Resources
|
||||
|
||||
`resources` is an array, not a count. v2 projects exactly the two resource
|
||||
|
||||
+170
-6
@@ -1,6 +1,7 @@
|
||||
# Marqdo Evaluation Semantics v1
|
||||
|
||||
Status: **frozen for M0.5**. Changes to observable behaviour require an ADR.
|
||||
Status: **frozen for M0.5; extended by ADR-0022 (`Memory`) and ADR-0024 (recoverable results)**.
|
||||
Changes to observable behaviour require an ADR.
|
||||
|
||||
## 1. Values
|
||||
|
||||
@@ -19,6 +20,8 @@ Status: **frozen for M0.5**. Changes to observable behaviour require an ADR.
|
||||
| `Code` | inert code fence + provenance; execution is explicit |
|
||||
| `FunctionRef` | reference to a named function in a module |
|
||||
| `PluginHandle` | opaque host-owned plugin export handle |
|
||||
| `Memory` | opaque runtime-owned addressable byte region (ADR-0022); copies share identity, offsets are region-relative |
|
||||
| `Resource` | opaque host-issued resource/stream handle (ADR-0025); not indexable, not wire-transferable, rendered as `Resource` |
|
||||
|
||||
There is no truthiness: `if`-like conditions accept `Bool` only. There are no
|
||||
implicit string↔number conversions; conversion builtins must be called.
|
||||
@@ -52,6 +55,15 @@ implicit string↔number conversions; conversion builtins must be called.
|
||||
* Assignment binds/updates a local slot in the current frame. It never writes
|
||||
an outer frame. There is no module-level assignment in v1: assignment
|
||||
outside a function body is an error.
|
||||
* The only other writable place is an index into a `Memory` region
|
||||
(`m[offset] = byte`, ADR-0022). List, Map and Table values keep their v1
|
||||
value semantics; `list[i] = value`, `map[key] = value` and `obj.field = value`
|
||||
are not defined and are rejected at run time or parse time rather than
|
||||
silently changing those values into shared mutable objects.
|
||||
* For `m[offset] = byte` the operands are evaluated exactly once in the order
|
||||
**base, offset, right-hand side**. The target must evaluate to `Memory`, the
|
||||
offset to a non-negative `Int` inside the region and the value to an `Int`
|
||||
in `0..=255`; otherwise the statement fails without writing anything.
|
||||
* `and`/`or` short-circuit and require `Bool` operands.
|
||||
* `Return` (an `emph` node) unwinds through branch/loop bodies to the
|
||||
enclosing function frame.
|
||||
@@ -62,6 +74,112 @@ implicit string↔number conversions; conversion builtins must be called.
|
||||
* Function calls recurse; recursion depth is bounded by the stack budget.
|
||||
Mutual recursion is allowed.
|
||||
|
||||
### 3.1 Addressable `Memory` (ADR-0022)
|
||||
|
||||
`Memory` is a separate storage domain from managed `List`/`Map`/`Table`
|
||||
values. It exists so `.mq.md` programs can construct allocators, encodings and
|
||||
data structures without a new Markdown node, keyword or host operation.
|
||||
|
||||
* **Creation.** `memory.new(initial_pages, max_pages)` creates a zero-filled
|
||||
region and returns its handle. Both arguments are non-negative `Int`s;
|
||||
`initial_pages <= max_pages`, and `max_pages` must fit the per-region
|
||||
budget. Rejection is atomic: no region or committed byte is created.
|
||||
* **Page size.** One logical page is 64 KiB (`PAGE_SIZE`). Print, trace and
|
||||
storage use bytes; page counts never mix with byte offsets.
|
||||
* **Size and growth.** `memory.size(memory)` returns committed pages.
|
||||
`memory.grow(memory, pages)` is grow-only and returns the **old** page
|
||||
count; old offsets keep their bytes, every new byte is zero. A failed grow
|
||||
(declared maximum, region budget or total budget) leaves the region and the
|
||||
budget unchanged. Growing by zero pages is a no-op returning the current
|
||||
count. Regions never shrink and there is no user-visible `free(region)`.
|
||||
* **Read/write.** `m[offset]` returns an `Int` in `0..=255`; `m[offset] = byte`
|
||||
writes one byte. Offsets are non-negative and region-relative; negative,
|
||||
out-of-range and unrepresentable `BigInt` offsets are `runtime.index`.
|
||||
Out-of-range byte values are `runtime.type`. No implicit truncation or
|
||||
wrapping occurs.
|
||||
* **Identity and equality.** Copying a `Memory` value, passing it to a
|
||||
function or storing it in a collection shares the same region. Two handles
|
||||
are `==` only when they designate the same region instance; `Memory` has no
|
||||
ordering comparison and no byte-content equality operator.
|
||||
* **Lifetime.** A region lives for one run and is dropped with the runtime.
|
||||
Block-level ownership (`malloc`/`free`) is a standard-library concern; the
|
||||
runtime only guarantees that a single access stays inside its region.
|
||||
* **Diagnostics.** Unknown, stale or cross-run handles are
|
||||
`runtime.memory`; budget failures are `resource.exhausted`; a non-`Memory`
|
||||
index-assignment base is `runtime.type`.
|
||||
* **Boundary.** A live handle never crosses the wire: `to_wire` emits only
|
||||
`{"type":"memory"}`, decoding that tag is a `WireError::Invalid`, and every
|
||||
host/plugin/foreign call rejects arguments containing `Memory`.
|
||||
* **Display.** `Value::display()` renders `Memory` without the internal
|
||||
region identity; `类型(m)` returns `"Memory"`.
|
||||
|
||||
### 3.2 Recoverable results (ADR-0024)
|
||||
|
||||
A recoverable failure is an ordinary `Map`, not a new value type or syntax:
|
||||
|
||||
```text
|
||||
success: {ok: true, value: <any Value>}
|
||||
failure: {ok: false, code: <Text>, message: <Text> [, details: <Map>]}
|
||||
```
|
||||
|
||||
`ok` is always a `Bool`. Success carries `value`; failure carries a stable
|
||||
dot-separated `code` and a human-readable `message`. Constructors such as
|
||||
`成功`/`失败` are ordinary `.mq.md` functions, not builtins.
|
||||
|
||||
* Expected conditions (no free block, malformed parser input, invalid byte
|
||||
sequence, and later EOF/short I/O results) should use this shape so a caller
|
||||
can branch on `ok`.
|
||||
* Language-invariant violations (wrong type, out-of-bounds, unknown/stale
|
||||
`Memory` handle, budget exhaustion, capability denial) remain fatal
|
||||
`RuntimeError`s. There is no catch mechanism and a library must not try to
|
||||
convert them into `Err`.
|
||||
* `map.get` returning `None` is a lookup result, not this convention; use
|
||||
`map.has` to distinguish a stored `None` (ADR-0023).
|
||||
* `code` is stable within its library; callers must not branch on `message`.
|
||||
Recommended prefixes include `alloc.*`, `parse.*`, `codec.*`, `table.*` and,
|
||||
later, `io.*`.
|
||||
* Stream EOF/partial semantics belong to the resource ABI (CM-A06); this
|
||||
section only reserves the shape `{ok: true, value: {count, eof, ...}}` for
|
||||
later, without defining it.
|
||||
|
||||
### 3.3 Resource streams (ADR-0025)
|
||||
|
||||
`Resource` is a host-issued opaque handle to an external stream, in a separate
|
||||
domain from `Memory`. It is not indexable, not a byte address and cannot be
|
||||
constructed from a number, document or wire value.
|
||||
|
||||
```text
|
||||
resource.open(kind: Text, descriptor: Text, rights: List) -> Resource
|
||||
resource.read(handle, memory: Memory, offset: Int, max_bytes: Int)
|
||||
-> {ok:true, value:{count:Int, eof:Bool}} | {ok:false, code, message}
|
||||
resource.write(handle, memory: Memory, offset: Int, length: Int)
|
||||
-> {ok:true, value:{count:Int}} | {ok:false, code, message}
|
||||
resource.close(handle)
|
||||
-> {ok:true, value:None} | {ok:false, code, message}
|
||||
```
|
||||
|
||||
* Providers: `stdio/stdout` with `["write"]` (pure/project, console grant);
|
||||
`file` with `["read"]` (project, `fs_read` grant, bounded by the 8 MiB file
|
||||
limit); `file` with `["write"]` (project, `fs_write` grant, 8 MiB buffered
|
||||
write flushed on `close`, ADR-0026). Mixed rights and other kinds are
|
||||
`resource.unsupported`.
|
||||
* `resource.read` checks the destination `Memory` range before calling the
|
||||
provider, caps the request to the remaining buffer, writes the returned bytes
|
||||
and reports the actual count plus `eof`. EOF is success, not an error.
|
||||
* `resource.write` copies bytes out of `Memory` for the call only; a short write
|
||||
is a count. stdout output is charged to the output budget and delivered to
|
||||
the program stdout channel. A project-file write stream appends to a bounded
|
||||
host buffer and does not touch the filesystem until `close`; a failed close
|
||||
leaves the handle open with its buffer, and an unclosed writer never creates
|
||||
the file.
|
||||
* Reading/writing/closing an already closed handle returns
|
||||
`{ok:false, code:"resource.closed"}`. Forged/cross-run/stale handles are
|
||||
fatal `runtime.resource`; unsupported kind/rights/direction are
|
||||
`resource.unsupported`; capability/path denial is `permission.denied`; a
|
||||
writer buffer above 8 MiB is `resource.exhausted` and appends atomically.
|
||||
* `Memory` arguments never cross the host boundary as handles: the interpreter
|
||||
copies bytes for the call. Resource handles never cross the value wire.
|
||||
|
||||
## 4. Errors
|
||||
|
||||
All failures are structured. Compile-time problems produce diagnostics
|
||||
@@ -69,7 +187,11 @@ All failures are structured. Compile-time problems produce diagnostics
|
||||
problems produce `RuntimeError { category, span, message, frames, cause }`
|
||||
with a stable category code. Runtime errors stop the current function and
|
||||
propagate with a call stack. A host/foreign/plugin failure never panics the
|
||||
interpreter; it becomes a structured error.
|
||||
interpreter; it becomes a structured error. Addressable-memory failures use
|
||||
the stable codes `runtime.memory` (unknown/stale handle, invalid page counts),
|
||||
`runtime.index` (offset outside the region, including negative or huge
|
||||
offsets), `runtime.type` (wrong operand type or byte value outside `0..=255`)
|
||||
and `resource.exhausted` (region or run budget).
|
||||
|
||||
## 5. Parameter inference (static, name based)
|
||||
|
||||
@@ -98,10 +220,17 @@ explicit signature paragraph allows positional arguments.
|
||||
|
||||
Every run has explicit limits (all configurable, all reported as
|
||||
`resource.exhausted`): evaluation fuel, call stack depth, total output bytes,
|
||||
wall-clock time, and host process count. Loops consume fuel per iteration and
|
||||
expressions per node so that a hostile document cannot hang the CLI. Strict
|
||||
mode additionally enforces limits at the OS level where available; if the
|
||||
platform cannot provide that, strict mode refuses to run (see `security.md`).
|
||||
wall-clock time, host process count, and addressable memory. Addressable
|
||||
memory has two independent budgets (ADR-0022): total committed bytes across
|
||||
all regions (`DEFAULT_MAX_TOTAL_BYTES = 64 MiB`) and committed bytes per
|
||||
region (`DEFAULT_MAX_REGION_BYTES = 16 MiB`, hence at most 256 pages of
|
||||
64 KiB), overridable with `--max-memory` and `--max-region-memory`. Memory is
|
||||
a pure computation: it needs no capability grant and is available in `pure`,
|
||||
`project` and `strict` modes, subject to these budgets.
|
||||
Loops consume fuel per iteration and expressions per node so that a hostile
|
||||
document cannot hang the CLI. Strict mode additionally enforces limits at the
|
||||
OS level where available; if the platform cannot provide that, strict mode
|
||||
refuses to run (see `security.md`).
|
||||
|
||||
## 7. Determinism
|
||||
|
||||
@@ -125,6 +254,41 @@ host boundary. Names are stable; adding one requires a spec update.
|
||||
| `小数` / `float` | `(x) -> Float` | from Int/Float/Text |
|
||||
| `表` / `table` | `(header: List, rows: List) -> Table` | validates row widths |
|
||||
| `ref` | `(target: Text) -> FunctionRef/Formula/Code` | resolves a document address; module-local, refuses ambiguous resource units (`ref.ambiguous`) |
|
||||
| `memory.new` | `(initial_pages: Int, max_pages: Int) -> Memory` | creates a zero-filled region; budgets are checked before allocation (ADR-0022) |
|
||||
| `memory.size` | `(memory: Memory) -> Int` | committed page count |
|
||||
| `memory.grow` | `(memory: Memory, pages: Int) -> Int` | grow-only; returns the previous page count, new bytes are zero |
|
||||
| `list.append` | `(list: List, value) -> List` | new list with one appended value; input unchanged (ADR-0023) |
|
||||
| `list.concat` | `(left: List, right: List) -> List` | new concatenated list; inputs unchanged |
|
||||
| `map.keys` | `(map: Map) -> List` | Text keys in canonical sorted order |
|
||||
| `map.has` | `(map: Map, key: Text) -> Bool` | key membership |
|
||||
| `map.get` | `(map: Map, key: Text) -> Value` | stored value or `None`; use `map.has` when `None` is a legal value |
|
||||
| `map.set` | `(map: Map, key: Text, value) -> Map` | new map with the key; input unchanged |
|
||||
| `map.remove` | `(map: Map, key: Text) -> Map` | new map without the key; missing key is a no-op |
|
||||
| `text.codepoints` | `(text: Text) -> List` | Unicode scalar values as `Int`, in order |
|
||||
| `text.from_codepoint` | `(codepoint: Int) -> Text or None` | `None` for a surrogate or a value outside `0..=0x10FFFF` |
|
||||
| `table.columns` | `(table: Table) -> List` | header names in column order |
|
||||
| `table.row` | `(table: Table, row: Int) -> List` | new list of row cells; non-negative coordinate |
|
||||
| `table.cell` | `(table: Table, row: Int, column: Int) -> Value` | cell value; non-negative coordinates |
|
||||
| `resource.open` | `(kind: Text, descriptor: Text, rights: List) -> Resource` | capability-checked stream open (ADR-0025) |
|
||||
| `resource.read` | `(handle, memory: Memory, offset: Int, max_bytes: Int) -> Result` | bounded chunk read into Memory; `{count,eof}` |
|
||||
| `resource.write` | `(handle, memory: Memory, offset: Int, length: Int) -> Result` | bounded byte write; `{count}` |
|
||||
| `resource.close` | `(handle) -> Result` | releases the host slot |
|
||||
| `math.parse/eval/substitute` | see `spec/math.md` | P5; `math.simplify`/`math.differentiate` are declared but return `math.unsupported` in this build |
|
||||
| `foreign.run/call` | see `spec/foreign.md` | P5, capability-gated |
|
||||
| `fs.read/write` | see `spec/security.md` | capability-gated |
|
||||
|
||||
The legacy `打印/print` builtin remains the default and still uses the host
|
||||
output path. `examples/stdlib/` contains an explicitly imported `.mq.md`
|
||||
`format/utf8/io` prototype (ADR-0027 Compat-A) whose output is comparison-tested
|
||||
against `打印` for Unit/None/Bool/Int/Float/Text/List/Map/Table; it does **not**
|
||||
replace the builtin, and Formula/Code/FunctionRef/PluginHandle formatting is not
|
||||
yet expressible in the standard library.
|
||||
|
||||
The `list.*`, `map.*`, `text.*` and `table.*` entries are observation and
|
||||
construction primitives, not algorithms (ADR-0023). They return new values and
|
||||
never mutate their arguments. Sorting, filtering, joining, grouping, JSON/CSV
|
||||
and table transformations remain standard-library work: adding one must not
|
||||
add a builtin. `map.get` returns `None` for a missing key; `map.has` is the
|
||||
unambiguous membership check when a stored `None` is possible. `table.row` and
|
||||
`table.cell` use non-negative coordinates, while `List` indexing keeps its v1
|
||||
negative-index rule.
|
||||
@@ -1,5 +1,6 @@
|
||||
(* Marqdo Expression Grammar v1
|
||||
Status: frozen for M0.5. This is the only grammar for executable payloads.
|
||||
Status: frozen for M0.5, extended by ADR-0022 with Memory-index assignment
|
||||
targets. This is the only grammar for executable payloads.
|
||||
It is a small independent language: it is NOT Markdown and NOT translated
|
||||
to Python. Markdown AST decides where a payload exists; this grammar
|
||||
decides what it means.
|
||||
@@ -10,9 +11,13 @@
|
||||
program = [ statement ] , EOF ;
|
||||
|
||||
statement = assignment | expression ;
|
||||
assignment = identifier , "=" , expression ;
|
||||
(* "=" is a single "=" token; "==" is a distinct token. Assignment targets
|
||||
are bare identifiers only: no member or index assignment in v1. *)
|
||||
assignment = assign_target , "=" , expression ;
|
||||
assign_target = identifier
|
||||
| postfix_expr , "[" , expression , "]" ;
|
||||
(* v1 left-hand sides are a local identifier or one index place. The index
|
||||
target writes one byte into an addressable Memory region; other base values
|
||||
are rejected at run time. Member assignment (`a.b = 1`) is a parse error.
|
||||
Chained assignment is a parse error. See ADR-0022. *)
|
||||
|
||||
expression = or_expr ;
|
||||
or_expr = and_expr , { "or" , and_expr } ;
|
||||
|
||||
+7
-5
@@ -27,8 +27,8 @@ Normative implementation:
|
||||
| Mode | Intended guarantee | Actual status in this build |
|
||||
|---|---|---|
|
||||
| `pure` | No external I/O; memory computation and budgets only. | **Enforced.** `Capabilities::pure()` = `console`, `math` only; every FS/foreign/plugin grant flag makes the CLI exit 2 with "pure mode prohibits external I/O grants". |
|
||||
| `project` | Operator-approved project resources under `CapabilityHost` + bounded resources. | **Enforced for the implemented operations.** Defaults equal `pure`; `--allow-read`, `--allow-write`, `--allow-foreign`, `--allow-plugin` add grants. Sandboxing is cooperative (in-process checks), not OS isolation. |
|
||||
| `strict` | Untrusted documents under real OS isolation. | **Linux: enforced when the runtime probe passes (ADR-0021).** `PlatformCapabilities::detect()` runs a real Bubblewrap smoke test; success reports `Available { mechanism }`, failure reports `Unavailable { reason }`. Strict L1 supports the interpreter, console and native Math only; `--allow-read/--allow-write/--allow-foreign/--allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file` are rejected with exit 2. macOS/Windows and Linux hosts without the mechanisms remain `Unavailable`; there is **no fallback** to an unrestricted process. |
|
||||
| `project` | Operator-approved project resources under `CapabilityHost` + bounded resources. | **Enforced for the implemented operations.** Defaults equal `pure`; `--allow-read`, `--allow-write`, `--allow-foreign`, `--allow-plugin` add grants. `resource.open` supports stdout write, granted project-file read and granted buffered project-file write (ADR-0025/0026); network/process remain unsupported. Sandboxing is cooperative (in-process checks), not OS isolation. |
|
||||
| `strict` | Untrusted documents under real OS isolation. | **Linux: enforced when the runtime probe passes (ADR-0021).** `resource.open` is **refused** in strict until a provider passes the isolation lane (CM-A11). `PlatformCapabilities::detect()` runs a real Bubblewrap smoke test; success reports `Available { mechanism }`, failure reports `Unavailable { reason }`. Strict L1 supports the interpreter, console and native Math only; `--allow-read/--allow-write/--allow-foreign/--allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file` are rejected with exit 2. macOS/Windows and Linux hosts without the mechanisms remain `Unavailable`; there is **no fallback** to an unrestricted process. |
|
||||
|
||||
`marqdo inspect <file> --platform` prints the detection report, for example:
|
||||
|
||||
@@ -55,10 +55,10 @@ set for one run:
|
||||
|
||||
| Field | Default (`pure`/`project`) | Used by |
|
||||
|---|---|---|
|
||||
| `console: bool` | `true` | currently **not checked** by `op_print`; print is always allowed and only bounded by the output budget (open item) |
|
||||
| `console: bool` | `true` | `op_print` and `resource.open("stdio","stdout",["write"])`; a missing grant is `permission.denied` and output is also bounded by the output budget |
|
||||
| `math: bool` | `true` | `math.*` host ops |
|
||||
| `fs_read: Vec<String>` | empty | `fs.read` |
|
||||
| `fs_write: Vec<String>` | empty | `fs.write` |
|
||||
| `fs_read: Vec<String>` | empty | `fs.read` and project `resource.open("file", path, ["read"])` |
|
||||
| `fs_write: Vec<String>` | empty | `fs.write` and project `resource.open("file", path, ["write"])` |
|
||||
| `net_hosts: Vec<String>` | empty | `Capabilities::check_net` exists, but no host op or builtin performs network access in this build |
|
||||
| `process: bool` | `false` | required together with `foreign` for `foreign.run`/`foreign.call` |
|
||||
| `foreign: bool` | `false` | foreign kernels |
|
||||
@@ -144,6 +144,8 @@ no host bypass for tests: tests use the same `StdHost`/`Capabilities` types.
|
||||
| call stack depth | `DEFAULT_STACK_LIMIT = 256` | checked before every function call → `resource.exhausted` |
|
||||
| program output bytes | `DEFAULT_OUTPUT_BYTES = 1 MiB` | `print` output and `fs.read` contents are charged; overflow → `resource.exhausted` |
|
||||
| wall clock | none by default | `--timeout <seconds>` sets a deadline; checked between statements/iterations and before loop conditions → `resource.exhausted`. It does **not** preempt a running host call. |
|
||||
| addressable memory | 64 MiB committed total, 16 MiB per region, 64 KiB pages; `--max-memory` / `--max-region-memory` override | Runtime-owned `MemoryStore` (ADR-0022); create/grow checks both budgets before allocation and failed growth is atomic → `resource.exhausted`. Memory is pure computation and needs no capability grant in any mode. |
|
||||
| resource streams | stdout writes charged to the existing output budget; file reads and writer buffers bounded by the 8 MiB per-file limit | Host-owned resource table (ADR-0025/0026); output budget is checked before a stdout write is buffered; a failed check produces no bytes; writer buffers flush only on `close`. No separate I/O byte budget yet. |
|
||||
|
||||
CLI overrides (`run`/`call`): `--fuel`, `--stack`, `--max-output`,
|
||||
`--timeout`. Additional fixed limits:
|
||||
|
||||
+15
-3
@@ -1,7 +1,9 @@
|
||||
# Marqdo Value Wire Format v1
|
||||
|
||||
Status: **frozen for M0.5**. Changes require an ADR, a `wire_version` bump and
|
||||
cross-ABI compatibility tests.
|
||||
Status: **frozen for M0.5; extended by ADR-0022 (non-transferable `Memory`)**.
|
||||
Changes require an ADR, a `wire_version` bump and cross-ABI compatibility
|
||||
tests. Adding a rejected tag is not a version bump; accepting a new value shape
|
||||
is.
|
||||
|
||||
Canonical implementation: `crates/marqdo-value/src/wire.rs`
|
||||
(`to_wire`, `from_wire`, `from_wire_with_limits`, `WireLimits`, `WireError`).
|
||||
@@ -14,12 +16,20 @@ documented in [`foreign.md`](foreign.md) and implemented in
|
||||
## 1. Why a typed wire format
|
||||
|
||||
JSON has one numeric type. Marqdo has arbitrary-precision `Int`, IEEE-754
|
||||
`Float` (including `NaN` and both infinities) and 13 distinct runtime value
|
||||
`Float` (including `NaN` and both infinities) and 15 distinct runtime value
|
||||
types (`crates/marqdo-value/src/value.rs`). Encoding an `Int` as a JSON number
|
||||
would silently lose digits above 2^53 and would make `Int(1)` and
|
||||
`Float(1.0)` indistinguishable after a round trip. The wire format is
|
||||
therefore **fully type-tagged** and is not plain JSON.
|
||||
|
||||
Addressable `Memory` and host `Resource` handles are deliberately **not
|
||||
transferable**. `to_wire` emits
|
||||
`{"type":"memory"}` only so that an accidental transfer is visible; decoding
|
||||
that tag is always `WireError::Invalid`, and the host boundary rejects any
|
||||
argument containing a live handle before an ABI call. Copying bytes requires an
|
||||
explicit standard-library snapshot to a managed value, not serializing a
|
||||
handle (ADR-0022).
|
||||
|
||||
The rules that follow from this:
|
||||
|
||||
1. Every value is a JSON **object** with a mandatory `"type"` string.
|
||||
@@ -81,6 +91,8 @@ The table is normative and mirrors `encode`/`decode` in
|
||||
| `Code` | `{"type":"code","language":"python","source":"...","content_hash":"<sha256 hex>"}` plus optional `"unit"` and `"span"` | `language` and `content_hash` default to `""` on decode when absent; `source` is required. |
|
||||
| `FunctionRef` | `{"type":"function_ref","module":"index.mq.md","name":"main"}` | Both fields required strings. |
|
||||
| `PluginHandle` | `{"type":"plugin_handle","plugin":"demo.solver","export":"solver.add","id":1}` | `id` must be a non-negative JSON integer (`as_u64`). |
|
||||
| `Memory` | `{"type":"memory"}` | **Never decodable.** No handle, address or bytes are encoded; a round trip is intentionally impossible (`wire::tests::memory_handles_are_not_transferable`). |
|
||||
| `Resource` | `{"type":"resource"}` | **Never decodable.** Host-private stream handle; `from_wire` rejects the tag (`resource_handles_are_not_transferable`, ADR-0025). |
|
||||
|
||||
Optional fields (`unit`, `span`, `display`, `language`, `content_hash`) are
|
||||
emitted only when present on the value. Encoders always emit `display` for
|
||||
|
||||
Reference in new issue
Block a user