Complete the documentation set for the M0.5 toolchain, grounded in the code: - spec/references.md: import/reference/call edges, identities, loader rules, anchors, `ref` resolution/ambiguity, `check --refs` validation. - spec/value-wire.md: exact wire_version 1 typed encoding, integer-as-decimal string rule, special floats, limits and exact float round-trip. - spec/security.md: modes (strict refuses without OS isolation), capabilities, path rules, budgets, tracing, foreign process caveats, plugin trust. - spec/package-format.md: marqdo.yaml/lock formats, validation, lock/sync, unsupported registry/git/environment work. - spec/plugin-abi.md: ABI v1 layout/ownership/negotiation, manifest/artifact rules, wire envelopes, loader lifecycle, trust boundary, SDK/C demo, and the implemented CLI plugin-invocation flow with its limitations. - spec/math.md and spec/foreign.md: the implemented math subset and the foreign request/response/timeout/capability contract. - docs/adr/0001..0007: accepted decisions for the span foundation, inert executables outside function bodies, ref ambiguity (S-07), strict refusal, AST normalization, CLI contract and BigInt/typed wire (S-08). - docs/contributor-guide.md: repo map, workflow, fixture/golden updates, quality gate, ADR/commit policy. - docs/STATUS.md: P0-P7 matrix with evidence, open items and the blueprint §18 Alpha checklist (conclusion: not yet Alpha-complete), including known divergences rather than overclaims. - README.md rewritten from "design-only starter" to the working implementation with quickstart, implemented phases, deliberate limits and doc index. - AGENTS.md: updated pointers/workflow only; architectural rules unchanged. - Consistency fixes in spec/mapping.md/evaluation.md (inert emph outside functions, unsupported math.simplify/differentiate).
8.6 KiB
ADR-0007: Arbitrary-precision Int and the typed wire encoding (S-08)
Status: Accepted Date: 2026-11-20
Context
The blueprint (§3.1 and unresolved issue S-08) requires a numeric model
that does not silently lose precision at language, JSON/ABI and math
boundaries. It recommends arbitrary-precision integers for Int and type tags
plus string forms for large integers on the wire.
Three independent places could lose information:
- Language arithmetic. A fixed-width
i64would makeIntsilently overflow or wrap. Factorials, powers and scientific constants routinely exceed 64 bits. The expression grammar already has arbitrary-length integer literals (spec/expression.ebnf). - JSON / wire. JSON has one number type (IEEE-754 double in most parsers).
Encoding
12345678901234567890as a JSON number loses digits in JavaScript/Go consumers; encoding1as a number makesIntandFloatindistinguishable. - Math kernel. The exact-rational engine needs an integer type that is
the same type as
Value::Int, or every formula/binding crossing the host boundary needs a lossy conversion.
The chosen dependency set (Cargo.toml) is:
num-bigint = { version = "0.4", features = ["serde"] }
num-rational = { version = "0.4", features = ["serde"] }
num-traits = "0.2"
Decision
1. Int is arbitrary precision (num-bigint::BigInt)
Value::Int(BigInt)(crates/marqdo-value/src/value.rs) is the only integer representation in the runtime and the expression AST (crates/marqdo-expression/src/ast.rs).- Expression integer literals are arbitrary-precision decimal; there is no fixed-width parsing step.
- Arithmetic (
crates/marqdo-runtime/src/value_ops.rs):+ - *on twoIntare exactBigIntoperations;/always producesFloat(exact ratio converted to binary64), so there is no integer division surprise;//and%requireIntoperands; floor division is mathematical floor anda % b == a - b * (a // b), with the sign following the divisor;- mixed
Int/Floatarithmetic producesFloat; converting anIntlarger than 2^53 may lose precision (documented, not silently exported as anInt); Int/Floatcomparisons are exact: the float is treated as the exact binary rational it is (BigRational::from_float), so9007199254740993 > 9007199254740992.0istrue;**onIntis exact exponentiation, with a negative exponent rejected as a type error and guardsMAX_EXACT_EXPONENT = 100_000andMAX_POWER_BITS = 1_000_000(resource.exhausted).
- There is no truthiness and no implicit string↔number conversion;
整数/intperforms explicit conversions and rejects non-integral floats.
2. num-bigint 0.4 is pinned to match num-rational 0.4
num-rational's generic Ratio<T> is instantiated as
Ratio<num_bigint::BigInt> in crates/marqdo-math/src/ast.rs
(pub type Rational = Ratio<BigInt>). The two crates must resolve to the same
num-bigint version, otherwise BigInt values from the value model cannot be
passed to Ratio without conversion (or a duplicate type). The workspace pins
both at the 0.4 line and the lockfile resolves one num-bigint. Upgrading
either crate requires checking that this shared-type invariant still holds and
running the math + runtime test suites.
3. The wire encoding never sends an integer as a JSON number
Canonical encoding (crates/marqdo-value/src/wire.rs; full contract in
spec/value-wire.md):
{"type":"int","decimal":"12345678901234567890"}
- Every value is a JSON object with a
"type"tag. Intuses a base-10 string. All digits, sign and magnitude survive any JSON consumer including JavaScript.Floatuses a JSON number only when finite;NaN,Infinity,-Infinityuse explicit"special"tags.- JSON numbers appear only in non-value positions (
span.start/end,plugin_handle.id). - Decoding is validated: unknown tags, missing fields, invalid decimals, wrong
types and limits are
WireErrors, never coercions. - The same encoding is used for plugin ABI request/response values, foreign
kernel stdin
input, foreign typed return values andrun --jsonvalues.
4. Math results preserve exactness where possible
The math kernel keeps exact rationals and returns Value::Int exactly when the
exact result is an integer, otherwise Value::Float. Decimal literals are
exact rationals (0.25 = 1/4), and \frac{1}{3} * 3 is exactly 1. Constants
(\pi, \e) and non-perfect square roots introduce binary64 approximations and
the result is a Float (spec/math.md §3).
Alternatives
i64/u64integers with overflow errors. Rejected: common programs (factorials, powers) would need explicit bignum workarounds; the language would inherit fixed-width semantics not implied by its arithmetic.i128integers. Same problem, just a bigger ceiling; and the wire precision problem remains for values beyond 2^53.- Encode integers as JSON numbers and hope consumers use bignum JSON.
Rejected: the JSON standard/ecosystem does not guarantee it; JavaScript's
JSON.parseloses digits; this is the exact S-08 failure. - Encode every number as a string without type tags. Rejected: loses the
Int/Floatdistinction and makes all consumers parse strings; type tags are explicit and cheap. - Use
f64for all numbers. Rejected: contradicts exactIntsemantics, the math kernel's exact rational requirement, and the no-silent-precision-loss rule. - Different integer crates in value vs math. Rejected: forces lossy or string conversions at every kernel boundary and duplicates tests.
Markdown AST shape
No AST change. Numeric literals live inside executable payloads only (code
spans/plain text of strong/emph/conditions). A math node is inert LaTeX;
its numeric interpretation is the math kernel's job. The JSON inspection view
of IR/AST contains spans as JSON numbers, not user numeric values.
Compatibility
Intsemantics (arbitrary precision,/→Float, exact comparisons,///%sign rules) are frozen language behavior; changing them requires an ADR and conformance fixtures.wire_version = 1with typed tags and decimal-string integers is frozen. Changing the integer representation is a wire-breaking change and needs a newwire_versionplus plugin ABI considerations.- The dependency pin may move within
0.4for security fixes, providednum-bigintremains a single resolved version shared withnum-rational. - Package/lock formats are unaffected.
Security
- Untrusted wire data cannot trigger huge allocations through the integer
parser without also counting against value depth/string limits: a decimal
string is bounded by
max_string_bytes(16 MiB default) andBigIntparsing is linear. The current decoder does not separately cap the digit count of anInt; the envelope/string caps are the effective bound (open item). - Arithmetic can grow memory; the runtime bounds it with fuel and the
Intpower guards (MAX_EXACT_EXPONENT,MAX_POWER_BITS) and the math kernel bounds exact numerator/denominator bits (MAX_RESULT_BITS). - Exact
Int/Floatcomparison prevents a class of "looks equal but is not" authorization or verification bugs. - No new capabilities; numeric parsing is pure.
Testing
crates/marqdo-value/src/value.rs:big_integers_are_arbitrary_precision,float_to_bigint_requires_integral_value, display/format tests.crates/marqdo-value/src/wire.rs:big_integers_keep_all_digits,special_floats_are_tagged, scalar round trips, untrusted-input limits.crates/marqdo-runtime/src/value_ops.rs: exact integer arithmetic,/→Float, floor/mod sign rules, exact mixed comparisons, power guards, division-by-zero.crates/marqdo-math/tests/kernel.rs: exact big integer arithmetic, exact rational division, decimal literals as rationals,pi/sqrtapproximating toFloat,IntvsFloatresult typing.crates/marqdo-plugin-abi/src/wire.rs: request round trips preserving tags and refusing coercible-looking values beyondi64.crates/marqdo-foreign/tests/kernels.rs: typed foreign return values decode exactly.
Migration & rollout
No migration: the implementation has used BigInt and the typed wire format
since M0.5. For future dependency upgrades: run cargo test --workspace,
verify one resolved num-bigint (cargo tree -i num-bigint), and re-run wire
compatibility tests. For any change to the wire integer encoding, bump
wire_version, update spec/value-wire.md, the plugin ABI documentation and
the foreign protocol in one coordinated change.