Skip to content

Add the Nat type of rulean-nat - #23

Merged
tamnd merged 1 commit into
mainfrom
m1/nat
Nov 21, 2026
Merged

tamnd merged 1 commit into
mainfrom
m1/nat

Conversation

@tamnd

@tamnd tamnd commented Nov 21, 2026

Copy link
Copy Markdown
Owner

This PR adds the natural number type of spec 04.6 to rulean-nat.

  • Nat is Small(u64) or Large(Vec<u64>). The form is canonical, so the derived equality is the equality of numbers.
  • The 15 kernel operations of spec 05.8: succ, add, sub, mul, div, mod, gcd, beq, ble, land, lor, xor, shiftLeft, shiftRight and pow. Each operation has a fast path for two small values.
  • log2, bits, bit, and decimal conversion in the two directions.
  • Multiplication is schoolbook below 32 limbs and Karatsuba above. Division is algorithm D of Knuth.
  • Subtraction stops at 0. Division by 0 gives 0, and the remainder by 0 gives the dividend, as in Lean.
  • The size guards of 05.8 are not in this crate. The caller checks the size of a pow or a shiftLeft result before the call.

The code stays in the subset of spec 10.6: while loops with an index, no iterators, no closures, no ? and only the modelled Vec methods. The vec! macro is not modelled, so the crate allows the clippy lint vec_init_then_push. The tests are in tests/, so the subset lint does not read them.

The tests compare each operation with num-bigint on numbers from a fixed generator. Some limbs are 0 or all ones, to test the carries. One test makes the quotient estimate of algorithm D too large, so the add-back step runs. I checked this with a panic in that step.

This PR covers the two Nat items of the checklist. The twin and the R2 lemmas for Nat are a separate item.

Refers to #2

@tamnd tamnd added this to the M1 Store and parser milestone Nov 21, 2026
@tamnd tamnd added area/nat The big number type and the Nat operations type/feature New function labels Nov 21, 2026
@tamnd
tamnd merged commit 9e2a2ca into main Nov 21, 2026
16 of 17 checks passed
@tamnd
tamnd deleted the m1/nat branch November 21, 2026 15:35
@tamnd tamnd mentioned this pull request Nov 21, 2026
7 of 16 tasks
tamnd added a commit that referenced this pull request Nov 21, 2026
This PR adds the term store of spec 04 to `rulean-store`. It is on top
of #23, because the store keeps natural number literals as
`rulean_nat::Nat`.

What the store has:

- `ExprId` is a `u32` with the tier in bit 31, the kind in bits 27 to 30
and the index in bits 0 to 26 (spec 04.2.1). The kind needs no memory
load.
- One node array for each of the 10 kinds. An application node is 8
bytes.
- A side record of 8 bytes for each node: the hash, the loose bound
variable range (24 bits, saturated) and the flags (free variable, level
parameter, let, literal, projection). The store computes the record when
it makes the node.
- `Table`, the open-addressing table of 04.2.4. It maps a hash to `u32`
values, and the caller compares its own key on each value with the same
hash. So the table needs no closure and no trait, and a lookup never
trusts a hash alone. The table can carry epochs, so that `clear` is O(1)
for the scratch tier.
- Interning of strings, names, levels, level lists, natural number
literals and expressions. `NameId(0)` is the anonymous name and
`LevelId(0)` is zero, as in the export.
- The hash is a MurmurHash3 step with no random seed. It is structural:
a node hash mixes the hashes of its fields, not their handles. So the
same term in two stores has the same hash. The hash of a literal covers
all limbs.
- `Store::memory` gives the bytes of each part, for the measure of 04.9.

The store does not normalize levels. That is the job of the checker in
M2. The scratch tier comes with the checker too. This PR has only the
frozen tier, but the handle already has the tier bit.

**Capacity.** When the array of one kind has 2^27 nodes, the store sets
a flag and returns a handle to an old node. The terms are then wrong, so
the driver must check `Store::is_full` and decline before it gives a
verdict. The crate documentation says this.

**Subset.** The code stays in the subset of spec 10.6. The table method
is `put` and not `insert`, because the subset lint reports `.insert()`
on any receiver. `rotate_left`, `wrapping_mul` and `is_empty` are
outside the modelled functions, so the code has its own forms of them.

This PR covers the two store items of the checklist. The twin and the R2
lemmas for the store are a separate item.

Refers to #2
tamnd added a commit that referenced this pull request Nov 21, 2026
Refers to #2.

The `extract` job on main fails since #23. Aeneas binds its `Fuel` type
to the Lean name `Nat`, and the `Nat` type of `rulean-nat` gets the same
name. Aeneas then writes partial Lean files and stops with an error.

This change gives the type the Lean name `BigNat` with
`#[aeneas::rename]`. The attribute and the `register_tool` line are
behind `cfg(rulean_extract)`, and only `scripts/extract.sh` sets this
cfg, through `RUSTFLAGS`. So a normal build on stable Rust does not see
them, and the Rust name stays `Nat`. `RUSTFLAGS` goes to every crate of
the build, so `rulean-store` and `rulean-format` see the same name as
`rulean-nat`.

The workspace lints declare the cfg, so `unexpected_cfgs` does not warn.

Tests: a nightly build of `rulean-store` and `rulean-format` with `--cfg
rulean_extract` passes. The `extract` job of this PR is the real test.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/nat The big number type and the Nat operations type/feature New function

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant