Files
marqdo-cli/docs/adr/0007-arbitrary-precision-int-and-wire.md
cflmy 0116160399 docs: formal specs, ADRs, STATUS matrix, contributor guide and honest README
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).
2026-11-20 10:56:26 +08:00

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:

  1. Language arithmetic. A fixed-width i64 would make Int silently overflow or wrap. Factorials, powers and scientific constants routinely exceed 64 bits. The expression grammar already has arbitrary-length integer literals (spec/expression.ebnf).
  2. JSON / wire. JSON has one number type (IEEE-754 double in most parsers). Encoding 12345678901234567890 as a JSON number loses digits in JavaScript/Go consumers; encoding 1 as a number makes Int and Float indistinguishable.
  3. 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 two Int are exact BigInt operations;
    • / always produces Float (exact ratio converted to binary64), so there is no integer division surprise;
    • // and % require Int operands; floor division is mathematical floor and a % b == a - b * (a // b), with the sign following the divisor;
    • mixed Int/Float arithmetic produces Float; converting an Int larger than 2^53 may lose precision (documented, not silently exported as an Int);
    • Int/Float comparisons are exact: the float is treated as the exact binary rational it is (BigRational::from_float), so 9007199254740993 > 9007199254740992.0 is true;
    • ** on Int is exact exponentiation, with a negative exponent rejected as a type error and guards MAX_EXACT_EXPONENT = 100_000 and MAX_POWER_BITS = 1_000_000 (resource.exhausted).
  • There is no truthiness and no implicit string↔number conversion; 整数/int performs 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.
  • Int uses a base-10 string. All digits, sign and magnitude survive any JSON consumer including JavaScript.
  • Float uses a JSON number only when finite; NaN, Infinity, -Infinity use 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 and run --json values.

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

  1. i64/u64 integers 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.
  2. i128 integers. Same problem, just a bigger ceiling; and the wire precision problem remains for values beyond 2^53.
  3. Encode integers as JSON numbers and hope consumers use bignum JSON. Rejected: the JSON standard/ecosystem does not guarantee it; JavaScript's JSON.parse loses digits; this is the exact S-08 failure.
  4. Encode every number as a string without type tags. Rejected: loses the Int/Float distinction and makes all consumers parse strings; type tags are explicit and cheap.
  5. Use f64 for all numbers. Rejected: contradicts exact Int semantics, the math kernel's exact rational requirement, and the no-silent-precision-loss rule.
  6. 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

  • Int semantics (arbitrary precision, / → Float, exact comparisons, ///% sign rules) are frozen language behavior; changing them requires an ADR and conformance fixtures.
  • wire_version = 1 with typed tags and decimal-string integers is frozen. Changing the integer representation is a wire-breaking change and needs a new wire_version plus plugin ABI considerations.
  • The dependency pin may move within 0.4 for security fixes, provided num-bigint remains a single resolved version shared with num-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) and BigInt parsing is linear. The current decoder does not separately cap the digit count of an Int; the envelope/string caps are the effective bound (open item).
  • Arithmetic can grow memory; the runtime bounds it with fuel and the Int power guards (MAX_EXACT_EXPONENT, MAX_POWER_BITS) and the math kernel bounds exact numerator/denominator bits (MAX_RESULT_BITS).
  • Exact Int/Float comparison 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/sqrt approximating to Float, Int vs Float result typing.
  • crates/marqdo-plugin-abi/src/wire.rs: request round trips preserving tags and refusing coercible-looking values beyond i64.
  • 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.