Architecture

floating 0.7.1 is organized as explicit numerical domains surrounded by thin composition, parsing, and verification layers. The central architectural rule is that numerical semantics remain pure and explicit, while filesystem, process, corpus, and benchmark effects stay at the repository edge.

Layer Map

Layer	Packages	Responsibility
Shared vocabulary	def	classification, sign, partial order, arithmetic type reexports, minimal Floating trait
Scalar domains	bin_float, decimal, decimal_gda	binary, IEEE decimal, and GDA decimal values and context semantics
Interval domain	ball_float	bare/decorated outward-rounded real enclosures
Checked composition	*_checked	preserve each domain's error, flag, or trap state in a closed pipeline
Semantic projection	semantic	exact representation-independent observations
Syntax	numeric_expr	source spans, literals, primitive calls, callback evaluation
Format frontends	frontend/*	parse one corpus grammar and execute typed cases
Runtime adapters	internal/conformance, internal/runner_cli, cli/*	summaries, sharding, files, JSON/text, exit status
Evidence	consistency, doc_examples, bench/*, tools/, testdata/	laws, docs, conformance, performance, orchestration

Package boundaries come from moon.pkg. Files inside one package organize implementation concerns but do not create namespaces.

Standard Boundaries

The repository does not implement one universal “floating value.” Each standard surface retains its own observable state:

Domain	Normative model represented by 0.7.1	Operation result
bin_float	declared IEEE 754-2019 binary formats/operations	value + BinaryFlags
decimal	declared IEEE 754-2019 decimal/interchange boundary	value + DecimalFlags
decimal_gda	GDA Specification 1.70 scalar operation model	GdaOutcome with raised flags, sticky next context, optional trap
ball_float	declared IEEE 1788-2015 bare/decorated interval boundary	enclosure, decoration/NaI, optional BallFlags

This separation prevents lossy conversions such as treating a GDA trap as an IEEE flag, treating an IEEE defined infinity as a generic error, or treating Entire/Empty/NaI as interchangeable interval failures.

Numeric Core Pipeline

All scalar cores use the same architectural decomposition even though their representations and standards differ:

public immutable value(s) + explicit context
  -> special-state/domain classification
  -> exact coefficient or certified interval computation
  -> one domain-owned finalization
  -> public value + explicit effect data

BinFloat stores sign, non-negative binary coefficient, exponent, precision, and special state. Decimal and GDA Decimal independently store sign, package-owned base-10^9 coefficient, exponent/quantum, precision, and special state. BallFloat stores two outward-rounded binary endpoints plus Empty/Entire state; decorated intervals add decoration and NaI without changing the bare representation.

Finalization is the semantic firewall. Coefficient kernels may compute exact products, quotients, roots, or guards, but they do not decide standard flags, cohorts, traps, decorations, or endpoint direction.

Algorithm Selection Architecture

Large integer kernels use a staged selector instead of committing to one algorithm:

size + shape + target + proof preconditions
  -> inline / schoolbook / Comba
  -> Karatsuba
  -> Toom-3
  -> NTT + exact CRT reconstruction
  -> exact fallback if an advanced precondition fails

Division likewise moves from word and Knuth D to Burnikel-Ziegler and reciprocal Newton where target measurements justify it. Sparse and unbalanced shapes have separate paths because an algorithm selected only by maximum length can waste more work on padding than it saves asymptotically.

Switch boundaries are private, target-specific policy. They are measured with the Maremark hierarchy across dense, sparse, square, balanced, and unbalanced datasets; boundary tests compare exact results below, at, and above every cutoff. Native, LLVM, Wasm, Wasm-GC, and JavaScript therefore may select different algorithms while returning the same public result.

Certified Elementary Architecture

Elementary functions share a proof contract across the binary, decimal, and interval stacks:

1. produce directed lower and upper enclosures at a working precision;
2. round both endpoints to the target domain;
3. accept only if target values and observable flags agree;
4. otherwise increase precision by max(32, work / 2);
5. stop after 12 refinements with structured certification detail.

bin_float owns the scalar dyadic certificates. ball_float lifts these certificates over endpoints, critical points, poles, and domains. decimal and decimal_gda convert exact decimal inputs to directed dyadic bounds and convert certified endpoints back through exact integer arithmetic.

Total interval APIs may widen to a mathematically safe range such as [-1,1] or Entire. try_* APIs expose the proof/resource failure instead. Scalar convenience APIs use the same certified path and never substitute a host transcendental approximation.

Context And Effect Flow

No numerical package relies on an ambient rounding mode.

• Binary and IEEE decimal contexts are immutable inputs; flags are explicit outputs that callers combine.
• decimal_gda returns a new context whose status includes current flags, then chooses a trap in fixed precedence.
• BallContext controls outward endpoint precision/exponent bounds and returns interval flags.
• Binary/interval checked wrappers retain the first ArithmeticError.
• DecimalChecked preserves defined IEEE results and accumulates flags while retaining certification errors separately.
• GdaDecimalChecked threads one outcome, stops on Trapped, and resumes only through an explicit defined-result transition.

These wrappers compose existing semantics; they do not invent another arithmetic algorithm or merge incompatible effect channels.

Parsing And Execution

numeric_expr contains syntax data and post-order callback evaluation. It performs no IO and selects no numeric backend.

Each frontend/* package owns one external grammar:

• gda_expr parses .decTest directives/cases and executes GDA outcomes;
• testfloat_expr parses TestFloat vectors and binds format, rounding, tininess;
• mpfr_expr parses pinned MPFR square-root, power, and elementary witnesses;
• itl_expr parses interval test rows and classifies the declared support set.

Frontends return typed summaries. CLI packages own files, filters, shards, rendering, and exit codes. Python tools fetch checksum-pinned data, plan tasks, run isolated targets/processes, and aggregate results; they do not replace the MoonBit numerical implementation.

Stable And Internal Boundaries

The application-facing release surfaces are def, the concrete numeric packages, and checked wrappers. semantic and numeric_expr are provisional integration surfaces. Frontends are public so repository runners can compose them, but compatibility is limited to declared corpora and generated interfaces.

internal/*, CLI packages, bench/*, consistency, and doc_examples are implementation/verification infrastructure. A symbol may appear in pkg.generated.mbti without becoming a long-term application contract; read the package design page before depending on it.

Invariants

• coefficient signs are independent from non-negative magnitudes;
• finite binary normalization removes only powers of two;
• decimal parsing preserves quantum until normalization/reduction is explicit;
• context finalization is the only bounded rounding/status decision point;
• interval lower bounds round downward and upper bounds round upward;
• Empty, Entire, NaI, NaN, signed zero, and infinities remain explicit states;
• fast-path/fallback selection cannot change public values or effect data;
• conformance summary counts partition selected cases and sharding is deterministic;
• IO, downloads, process state, and parallel scheduling stay at tooling edges.

Extension Rule

Add behavior to the package that owns its semantics. Reuse existing arithmetic capability traits before creating an umbrella trait. Keep kernels private, contexts/effects explicit, and external-format parsing outside numeric values unless the format is a stable interchange contract.

Extending a conformance surface requires coordinated parser, executor, support classification, CLI schema, manifest, test, generated-interface, and localized documentation changes. Parsing a new operation is not support until strict execution has a defined comparison and reproducible evidence.