Module types 

Core runtime type definitions.

This module defines the primitive types used by LOGOS programs at runtime. These are type aliases that map LOGOS types to their Rust equivalents.

Type Mappings

LOGOS Type	Rust Type	Description
Nat	u64	Natural numbers (non-negative)
Int	i64	Signed integers
Real	f64	Floating-point numbers
Text	String	UTF-8 strings
Bool	bool	Boolean values
Unit	()	The unit type
Char	char	Unicode scalar values
Byte	u8	Raw bytes
Seq<T>	LogosSeq<T>	Ordered sequences (reference semantics)
Set<T>	HashSet<T>	Unordered unique elements
Map<K,V>	LogosMap<K,V>	Key-value mappings (reference semantics)

Structs

LogosComplex

An exact complex number re + im·i — the AOT mirror of the interpreter’s Complex. complex(0, 1) compiles to LogosComplex::new(..); + − × ÷ stay exact and closed (i·i = −1). NOT ordered. Display shows 3+4i / i / -2i, matching the interpreter.

LogosDecimal

An exact base-10 fixed-point number — money’s runtime type on the compiled-to-Rust path, the AOT mirror of the interpreter’s Decimal. decimal("19.99") compiles to LogosDecimal::parse("19.99"); + − × stay exact Decimal (scale preserved), and ÷ widens to the exact LogosRational (base-10 division need not terminate). Display shows the scale faithfully (19.99, 20.00), matching the interpreter.

LogosDenseI64Map

Direct-addressed i64 → i64 map — the densest representation of a Map of Int to Int, emitted when the compiler PROVES every key ever inserted or queried lands in a statically bounded window [lo, lo + slots) whose width is ≤ the map’s own with capacity hint. Keys index a flat value array (data[key - lo]); a parallel presence bitset distinguishes a stored value from an absent slot, so get returns None for an in-range key that was never inserted. No hashing, no probing, no sparse table — both build and scan phases are sequential array accesses, which the backend vectorizes and the prefetcher loves. This is perfect hashing for dense integer keys: it removes the random-access hash table that costs LogosI64Map its cache locality.

LogosDenseI64MapNoPresence

The presence-elided sibling of LogosDenseI64Map, emitted ONLY when the compiler additionally proves the get/contains key domain is a subset of a CONTIGUOUSLY FULLY-COVERED insert range — i.e. every key the program reads was definitely written first. With that proof the presence bit is invariably set, so it is dropped: get is a bare Some(data[key - lo]) load, byte-identical to a C array read, and no presence bitset is allocated. The gate forbids this type for any map with a contains use (there is no way to answer membership without presence), so contains_key/LogosContains are intentionally absent — a generated contains on this type would fail to compile, surfacing a gate bug loudly rather than silently miscompiling.

LogosDenseI64Set

Direct-addressed i64 SET — the keys-only, value-free sibling of LogosDenseI64Map (the dense analogue of LogosI64Set). Membership lives in a presence bitset over the proven window [lo, lo + slots); insert sets a bit, contains tests one. No value array → 1 bit per key, the smallest footprint of any map/set representation.

LogosDivU64

Precomputed unsigned division by a loop-invariant runtime divisor — the magic-multiply that replaces a hardware div/idiv once the divisor is pinned. Codegen emits LogosDivU64::new(n) in a loop’s preheader (computed ONCE) and rewrites each in-loop x % n / x / n to .rem(x) / .div(x), turning a ~20–40-cycle division into a multiply-high plus a shift. gcc and rustc both leave a runtime-invariant divisor as a real div (neither synthesizes this), so it is a strict win over the C baseline on division-hot loops (graph_bfs’s % n adjacency build).

LogosI32Map

i32-narrowed open-addressing i64 → i64 map — the same probe-table shape as LogosI64Map but with 8-byte (i32, i32) slots, emitted when the compiler PROVES every key AND value stays in i32 range. Halving the slot width halves the table’s memory traffic — the dominant cost of this random-access workload — for maps the dense gate cannot capture (no proven contiguous key window). The call surface is i64 (keys/values widen at the boundary; the proof makes the narrowing cast lossless), so codegen emits it identically to LogosI64Map.

LogosI32Set

i32-narrowed open-addressing set — the keys-only sibling of LogosI32Map (the i32 analogue of LogosI64Set). One flat Vec<i32>: 4 bytes per slot, a quarter of LogosI64Map’s footprint. Emitted for a set-usage Int → Int map whose keys are all proven to fit i32. The empty-slot sentinel is 0 (the real key 0 tracked separately) so vec![0; slots] allocates via alloc_zeroed — lazily-zeroed, no eager memset of the table.

LogosI64Map

A specialized open-addressing i64 → i64 map with VALUE semantics and no Rc<RefCell> indirection.

LogosI64Set

Open-addressing i64 SET — the keys-only sibling of LogosI64Map, emitted for a Map of Int to Int the alias analysis proves is used ONLY as a set (insert + contains; the value is never read — two_sum’s seen). ONE flat Vec<i64> with linear probing and a 0 empty-slot sentinel (the real key 0 tracked separately for full key-space correctness). With no value array it has HALF the store traffic and footprint of the map — 8 bytes/slot, smaller than C’s struct Entry { long key; int occupied; }.

LogosMap

Key-value mapping with reference semantics.

LogosModular

An element of the ring ℤ/nℤ — the AOT mirror of the interpreter’s Modular. modular(value, modulus) compiles to LogosModular::new(..); + − × wrap in the ring, pow is fast modular exponentiation, and ÷ multiplies by the modular inverse. NOT ordered.

LogosMoney

Money for the compiled tier — an exact amount in a currency, mirroring base::Money. + − require the SAME currency (a runtime-panic backstop; the type checker rejects mismatches first), × ÷ scale by an exact number, and a same-currency ÷ is the dimensionless ratio.

LogosQuantity

A physical quantity on the compiled-to-Rust path — the AOT mirror of the interpreter’s Quantity value. The magnitude rides the exact rational tower (no float drift) and the display unit travels with it so Show renders faithfully (42/127 ft). + − require the same dimension — the front-end’s type checker proves this, so a mismatch is a compile error, not a runtime one; the runtime check here is a defensive backstop. × ÷ combine dimensions, and a quantity may be scaled by a dimensionless number (unit preserved).

LogosRational

Exact rational number for compiled LOGOS programs — the AOT counterpart of the interpreter’s RuntimeValue::Rational.

LogosSeq

Ordered sequence with reference semantics.

LogosSeqIter

LogosUuid

A 128-bit UUID for the compiled tier (RFC 9562), mirroring logicaffeine_base::Uuid. A Copy newtype over [u8; 16] — no allocation, byte-ordered comparison (so v6/v7 sort by time), canonical text form.

Enums

LogosInt

The exact integer for GENERATED code: i64 on the fast path, spilling to a heap [logicaffeine_base::BigInt] the moment a value escapes 64 bits — the AOT’s mirror of the interpreter’s Int→BigInt promotion (and of the JIT’s overflow side-exit). Every operation NORMALIZES: a big result that fits i64 downsizes to Small, so representation never leaks into ==/Ord.

Value

Dynamic value type for heterogeneous collections.

Traits

FillClone

A FILL-SLOT copy: collections copy DEEP, so every slot of a fill (n copies of x, [x] * n) is an independent row — never n aliases of one row (the classic [[0]] * 3 footgun is designed out). Scalars copy plain. Mirrors the tree-walker’s recursive RuntimeValue::deep_clone.

IntoRate

An exchange rate accepted by set_rate — a plain integer (1), an exact LogosDecimal (1.10), or a LogosRational. All widen losslessly onto the Rational tower so normalisation stays exact, matching the interpreter’s set_rate builtin.

LogosContains

Unified containment testing for all collection types.

Functions

set_rate

Install (or replace) one exchange rate in the ambient rate context — 1 <code> = rate reference units. The compiled-tier mirror of the set_rate builtin; a fresh process starts with no rates, so a program installs them before any <money> in <currency> conversion.

set_rates

Bulk-install a whole exchange-rate table from a Map of Text to <number> (currency code → rate vs the reference) into the ambient rate context. The compiled-tier mirror of the set_rates builtin and the bridge a literal, network-synced, or fetched table feeds. Order-independent.

text_bytes

A Text’s UTF-8 bytes as a Seq of Int (the text_bytes builtin, AOT).

text_from_bytes

Rebuild a Text from a Seq of Int of UTF-8 bytes (the text_from_bytes builtin, AOT — the exact inverse of text_bytes). Inputs originate from text_bytes, so the bytes are always valid UTF-8; the lossy fallback only guards against a hand-built malformed Seq.

to_currency

Convert money to another currency via the ambient rate context — the <money> in <currency> surface. Panics (the typed-error backstop, like a currency-mismatch +) when no rates are in scope or the currency lacks a rate; the front-end / interpreter surface these as clean errors.

value_semantics_enabled

Whether Mutable Value Semantics is enabled for compiled (AOT) programs. The AOT binary is a separate process from the interpreter, so it reads the LOGOS_VALUE_SEMANTICS env var itself (inherited from the parent process), cached once. When on, collection Clone deep-copies (value semantics); when off it shares the Rc (the historical reference semantics — unchanged).

Type Aliases

Bool

Boolean truth values.

Byte

Raw bytes (0-255).

Char

Unicode scalar values.

FxIndexMap

The insertion-ordered map behind every LOGOS Map: IndexMap for the order contract (iteration, display, and serialization follow insertion, like a Python dict), Fx hashing for speed on the small keys LOGOS programs use (no DoS-resistance requirement).

FxIndexSet

Unordered collections of unique elements with FxHash. The insertion-ordered set behind every LOGOS Set: display and iteration follow first-insertion order, identical to the tree-walker’s Vec-backed sets and the direct-WASM linear sets. Fx hashing for speed. NOTE: removal must go through shift_remove (order-preserving), never swap_remove.

Int

Signed integers.

Map

Key-value mappings with reference semantics.

Nat

Non-negative integers. Maps to Peano Nat in the kernel.

Real

IEEE 754 floating-point numbers.

Seq

Ordered sequences with reference semantics.

Set

Text

UTF-8 encoded text strings.

Tuple

Tuple type: Vec of heterogeneous Values (uses LogosIndex from indexing module)

Unit

The unit type (single value).