Replace the Strong/Emph/List/Quote mapping in place with the single @exec/@knowledge heading-mode model, unified payload carriers and keyword control flow. - add the authoritative RFC, ADR-0052 and a historical ADR index - rewrite spec/mapping.md and spec/expression.ebnf as the normative mapping/statement grammar; update evaluation, references, math, foreign, package-format, plugin-abi, security and schema notes - rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking language change; update the architecture index/overview and active docs - mark superseded planning docs, compute RFCs, evidence and syntax-role ADRs as historical/superseded without rewriting their decisions - add migration guide, per-file inventory and dev-only audit scripts The frontend/stdlib migration is completed in the following commits; this commit contains documentation only.
9.1 KiB
ADR-0007: Arbitrary-precision Int and the typed wire encoding (S-08)
Historical syntax note. The numeric model and typed wire-encoding decisions remain current. The phrase "code spans/plain text of
strong/emph/conditions" below describes the pre-RFC-LANG-0002 payload/condition mapping; under RFC-LANG-0002 / ADR-0052, payloads are carried byStrong,Emphor inlineCodeand control flow is keyword based.
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.