Skip to content

README.md

Latest commit

 

History

History
292 lines (217 loc) · 11 KB

README.md

File metadata and controls

292 lines (217 loc) · 11 KB
Raw

Decimal Conformance Data

The public evidence summaries are split between decimal IEEE conformance and decimal_gda conformance. This page owns corpus manifests, execution options, and failure triage.

The repository uses the native MoonBit gda_expr interpreter for all General Decimal Arithmetic conformance execution. Generated MoonBit test packages and the former JavaScript executor are no longer supported.

The authoritative testcase sources are:

The official corpora are not vendored. Their URLs, checksums, destinations, and expected file counts are pinned in corpora.json.

IEEE 754 decimal32/64/128 corpus

The independent IEEE gate lives in testdata/decimal/ieee. It is separate from the GDA decTest corpus and contains fixed-width DPD and BID witnesses, arithmetic/flag rows, and a compact exhaustive 1,024-code DPD declet fixture. manifest.json records the IEEE encoding and exact-arithmetic fixture schema; no implementation-specific source archive is downloaded during a test run.

IEEE permits either tininess policy. The public context defaults to after-rounding and exposes an explicit before-rounding option; GDA always uses before-rounding. NaN payload and sign selection follow the public API contract.

The checked-in runner validates all 1,024 DPD declets and the fixed-width BID and DPD cases directly from the IEEE formulas, then executes the same public MoonBit API tests on every supported target.

The runner also executes a 42-row excerpt from the pinned dd* and dq* concrete-format files in dectest.zip. Those rows are useful boundary and rounding witnesses, but decTest is a General Decimal Arithmetic corpus and its own notice says that it is beta, non-exhaustive, and not proof of IEEE compliance. They are never used to override the clause-derived oracle.

vector_plan.json defines the next fixed-seed expansion: every oracle family targets at least 100,000 rows across decimal32/64/128, five IEEE rounding directions, both tininess policies, 14 boundary classes, nine coefficient-size classes, and balanced/sparse/dense/unbalanced shapes. Generate a stream without committing a multi-gigabyte artifact with:

just ieee-vectors mandatory-decimal 100000 .tmp/mandatory.jsonl

The committed elementary oracle adds 2,784 executable rows. MPFR 4.2.2 computes 768-bit directed dyadic enclosures; exact integer conversion rounds both endpoints to decimal32/64/128 under all eight Decimal rounding modes and rejects non-unique value/flag witnesses. RDFP and Arb routes remain optional secondary evidence and are never counted when unavailable. The larger 100,000-per-family plan remains an optional generated stress matrix rather than a multi-gigabyte committed artifact.

Run the IEEE runner through the shared conformance entry point:

just conformance plan decimal
just conformance run decimal --run-target native
just conformance run decimal --run-target native --run-target wasm --run-target wasm-gc --run-target js --json

The Python runner remains available for internal debugging. Run the implementation gate on native, Wasm, Wasm-GC, and JavaScript (LLVM is intentionally not part of this gate) with just gate decimal. The decimal_gda backend and just gate decimal_gda remain the separate GDA suite.

Which Command To Use

just conformance smoke decimal_gda
just conformance fetch decimal_gda official
just conformance fetch decimal_gda official0
just conformance plan decimal_gda --jobs 8
just gate decimal_gda 8
just conformance run decimal_gda --jobs 8 --phase arithmetic
just conformance run decimal_gda --jobs 8 --strict-supported --json
just decimal-kernel-ci
  • just conformance smoke decimal_gda runs the checked-in smoke.decTest fixture directly.
  • just conformance fetch decimal_gda installs the selected official corpus.
  • just conformance plan decimal_gda prints the staged file assignment without executing cases.
  • just gate decimal_gda executes both pinned GDA corpora through the native interpreter.
  • just pr runs the complete repository gate; just decimal-kernel-ci runs the focused Decimal white-box test file.

Use just conformance smoke decimal_gda while changing parser or interpreter wiring. Use a targeted just conformance run decimal_gda command while fixing GDA semantics. Run plain just pr before opening or updating a pull request. Do not treat just decimal-kernel-ci as full validation; it is deliberately a small and fast CI gate.

Recommended Workflow

1. Run the checked-in smoke fixture

just conformance smoke decimal_gda

This does not download anything. It executes all cases in smoke.decTest in a single interpreter process and is the fastest end-to-end parser/backend check.

To run one smoke case or a small smoke range:

just conformance smoke decimal_gda --cases lfquant001
just conformance smoke decimal_gda --cases lfnextp001,lfnextm001
just conformance smoke decimal_gda --cases lfnextp001..lfnextp002 --json

2. Inspect or install the official corpus

just conformance fetch decimal_gda official
just conformance plan decimal_gda --jobs 8

just conformance fetch decimal_gda verifies the pinned SHA-256 digest and expected file count. The runner also fetches a missing corpus automatically, but explicit fetching makes network and corpus failures easier to distinguish from semantic failures.

Use the legacy corpus only when investigating old subset behavior:

just conformance fetch decimal_gda official0
just conformance plan decimal_gda --corpus official0 --jobs 4

3. Run a focused official case

Case selectors are passed with --cases:

# One exact case ID
just conformance run decimal_gda --phase arithmetic --cases quax1010

# Several exact IDs, separated by commas
just conformance run decimal_gda --phase arithmetic --cases quax1010,quax1013,quax1015

# Inclusive ID range
just conformance run decimal_gda --phase arithmetic --cases quax1010..quax1015

# Legacy corpus case
just conformance run decimal_gda --corpus official0 --phase arithmetic --cases add011

Selectors may be combined in one comma-separated expression, for example --cases quax1010..quax1015,quax1020. Whitespace around comma-separated selectors is ignored. A range is inclusive and only matches IDs whose length equals both endpoints. Matching is lexicographic, so keep the same ID prefix and zero-padding on both sides.

Case IDs are normally unique in the corpus. Add --phase ... to avoid scanning unrelated phases and to make the intended operation family explicit.

4. Run one phase

just conformance run decimal_gda --phase arithmetic --jobs 8
just conformance run decimal_gda --phase elementary --jobs 4
just conformance run decimal_gda --phase interchange --jobs 4
just conformance run decimal_gda --phase remaining --jobs 8

The configured phases are:

  • arithmetic: add, subtract, multiply, divide, FMA, remainder, quantize, rescale, and related integer operations.
  • elementary: exp, ln, log10, power, and square root.
  • interchange: decimal32, decimal64, and decimal128 ds/dd/dq files.
  • remaining: every file not claimed by an earlier phase.

Pass --phase ... more than once to select multiple phases explicitly.

5. Run the full pre-PR gate

just gate decimal_gda 8

The command stops at the first failed stage:

  1. decimal_gda package tests;
  2. GDA frontend tests;
  3. staged official corpus execution;
  4. staged official0 corpus execution.

Use --strict-supported as a guard against accidentally adding unsupported or legacy classifications; the pinned legal GDA corpus has none:

just conformance run decimal_gda --jobs 8 --strict-supported

The only intentionally non-executable rows in the official corpus are # placeholder/non-scalar invalid inputs. They are classified as diagnostics and excluded from the legal GDA conformance denominator; every legal executable row must pass.

Run One .decTest File Directly

Use the interpreter CLI when file isolation matters more than the standard pre-PR checks:

sh tools/run_moon_clean_exec.sh run --release --target native src/cli -- \
  --backend gda \
  testdata/decimal/official/quantize.decTest

sh tools/run_moon_clean_exec.sh run --release --target native src/cli -- \
  --backend gda --cases quax1010..quax1015 --json \
  testdata/decimal/official/quantize.decTest

The CLI accepts multiple files or directories after its options. Direct CLI runs do not execute moon check or moon info; use just pr for the final gate.

Run White-Box Tests

CI intentionally runs only:

just decimal-kernel-ci

That command executes src/decimal/coeff_kernel_wbtest.mbt. To reproduce one MoonBit white-box test by name:

sh tools/run_moon_clean_exec.sh test \
  src/decimal/coeff_kernel_wbtest.mbt \
  --filter 'decimal coefficient exact power-of-ten division uses unit shifts' \
  --no-parallelize

Use Moon's --filter glob syntax when selecting several named tests. These white-box tests complement the interpreter corpus; they do not replace it.

Execution Model

interpreter_stages.json assigns every corpus file to one sequential phase. Within a phase, the runner starts deterministic native interpreter shards in parallel. Per-shard JSON and the aggregate summary.json are written under .tmp/dectest-interpreter/.

The runner accepts regular options such as --jobs, --corpus, --phase, --cases, --strict-supported, and --json.

--jobs controls deterministic interpreter shards inside each phase. Start with --jobs 1 when reproducing a failure and increase it for full runs. Use --no-build only after the native interpreter has already been built and no relevant MoonBit source has changed.

Results And Failure Triage

The staged runner writes:

  • .tmp/dectest-interpreter/summary.json: aggregate run result.
  • .tmp/dectest-interpreter/<phase>/shard-NNN.json: per-shard result and timing.
  • failedIds: case IDs that produced semantic mismatches.
  • counts for executable, passed, failed, skipped, diagnostic, legacy, and unsupported cases. In the pinned corpus, diagnostic rows are only # placeholders; legacy and unsupported counts are zero.

Use JSON output when another tool needs to consume the result:

just conformance run decimal_gda --phase arithmetic --cases quax1010..quax1015 --json

Interpret failures in this order:

  1. A failure during moon check or moon info is a compile/interface problem; no conformance case ran.
  2. Runner exit code 2 indicates setup, corpus, build, process, or JSON failure.
  3. Runner exit code 1 with failedIds indicates semantic case mismatches.
  4. Strict mode returns 1 if a future change introduces legacy or unsupported classifications; it does not turn invalid # placeholders into arithmetic cases.
  5. Re-run failed IDs with --jobs 1, one phase, and --json before changing code.

Example focused rerun:

just conformance run decimal_gda --jobs 1 --phase arithmetic --cases quax1010,quax1013 --json