Crate logicaffeine_system

Expand description

§logicaffeine-system

Platform IO and system services for LOGOS — console, clock, filesystem/VFS, and networking. The effectful counterpart to logicaffeine_data: where that crate holds pure, WASM-safe value types, this crate owns every interaction with the outside world and gates the heavy dependencies behind features so a lean (or wasm32) build pays only for what it uses.

Part of the Logicaffeine workspace. Tier 2 — depends on logicaffeine_base and logicaffeine_data. Provides the host primitives that AOT-compiled LOGOS programs lower to.

§Role in the workspace

The runtime library linked into compiled LOGOS programs (via logicaffeine-compile) and shared with the interpreter and the web app. A program’s Show, file access, Spawn, Sync/Connect, and persisted-CRDT verbs all bottom out in these primitives. The same surface compiles on native and wasm32 behind platform seams — get_platform_vfs() for files, net::Net for networking — so generated code is written once and runs on both. The networking and distributed story is covered in concurrency.md.

§Public API

Always available (native and wasm32):

io — console/stream IO (show, print, println, eprintln, read_line) and the Showable trait behind the LOGOS Show verb: primitives unquoted, collections [..], maps {..}, None as nothing, CRDTs as their logical value, Duration human-formatted.
temporal — clock-agnostic time arithmetic over injected timestamps: LogosDate (days since epoch, Hinnant to_ymd), LogosMoment (nanoseconds), LogosSpan (months + days kept incommensurable).
relay_proto — the RelayFrame WebSocket wire protocol (Subscribe/Unsubscribe/Publish/SubAck/Event), serde + bincode only, shared verbatim by the native and browser relay clients.
addr — multiaddr_to_ws_url: normalize a libp2p multiaddr (or raw ws:///wss://) to the URL the relay dials. Pure string logic, no libp2p.
net (when a relay client exists) — Net, the cross-target relay handle the interpreter holds: connect/subscribe/publish/drain over the native tokio-tungstenite client or the browser web-sys socket. Drained, not awaited, so Sync stays a sync point.

Native-only (cfg(not(target_arch = "wasm32")), no feature needed):

time — now() (ms since epoch), sleep(ms).
env — get(key), args().
random — randomInt(min, max), randomFloat() (thread-local RNG).
text — parseInt, parseFloat, chr (camelCase to match codegen builtins).

Feature-gated:

file (persistence) — synchronous read/write returning Result<_, String>, for callers that do not need the async VFS.
fs (persistence) — async Vfs trait (read/write/append/exists/remove/ rename/create_dir_all/list_dir) with VfsError/VfsResult/DirEntry. Backends: NativeVfs (tokio::fs, sandboxed paths, atomic write-then-rename), UringVfs (Linux io_uring worker), and on wasm32 OpfsVfs/WorkerOpfsVfs/ IndexedDbVfs behind a WebVfs enum (OPFS → IndexedDB fallback). get_platform_vfs() selects the best backend per target.
storage (persistence) — Persistent<T>: journal-based, crash-resilient CRDT storage (mount/get/mutate/compact/entry_count/maybe_compact) over an append-only WAL replayed entry-by-entry on mount.
relay (native, behind the relay feature) — the thin WebSocket relay server + client: serve (pure browser↔browser hub) and serve_bridged (cross-forwards the libp2p gossipsub mesh, so a browser dialing a native node joins the real mesh). Carries no libp2p into the browser.
relay_browser (wasm32) — RelayBrowserClient, a web-sys WebSocket speaking relay_proto: the browser’s door into a native node’s relay.
network (networking) — libp2p P2P: listen/connect/send, local_peer_id, PeerAgent, MeshNode, GossipSub gossip_publish/ gossip_subscribe, mDNS discovery, NetworkError; FileSipper chunked transfer (FileManifest/FileChunk/DEFAULT_CHUNK_SIZE).
crdt (networking) — Synced<T>, an auto-replicated (ephemeral) CRDT wrapper.
concurrency — spawn/TaskHandle, Go-like bounded Pipe channels, seeded_pick/deterministic_replay_enabled for replayable scheduling.
memory (concurrency) — Zone arena (heap via bumpalo, or zero-copy mmap), “Hotel California” bulk deallocation.
distributed (networking + persistence) — Distributed<T>, the mesh-journal bridge: local mutations go RAM → journal → network and remote updates go network → RAM → journal, with auto-compaction at 1000 entries.

§Post-quantum cryptography and runtime kernels

Always available (native and wasm32, no feature needed) — the symmetric/PQC primitives compiled LOGOS crypto lowers to, and validated bit-exact against the Logos-native implementations:

keccak — Keccak-f[1600] + FIPS-202 sponge (sha3_256/sha3_512/shake128/ shake256, multi-block squeeze), the hash/XOF layer everything below rides on.
ntt — the ML-KEM (Kyber) negacyclic NTT kernel: a verified scalar reference plus an AVX2 i16×16 path, with the byte-encode/decode, compression, and CBD samplers (mlkem_ntt/mlkem_inv_ntt/mlkem_base_mul/mlkem_byte_encode/… ) re-exported at the crate root.
mlkem — ML-KEM-768 (FIPS-203) keygen / encapsulation / decapsulation, the post-quantum key exchange for the channel handshake, composed from the NTT + Keccak kernels.
mldsa — ML-DSA-65 (FIPS-204 / Dilithium) keygen / sign / verify, the post-quantum signature complement to ML-KEM.
aead — ChaCha20-Poly1305 (RFC 8439), the symmetric seal that closes the post-quantum channel once the shared secret is established.
word_rt — runtime support for the Word8/Word16/Word32/Word64 ring types in compiled LOGOS (word32, rotl, and the Showable glue), the execution-side complement to logicaffeine_base::word.

The crate root re-exports the io/temporal items and the keccak/ntt kernels, plus tokio (native), and adds panic_with(reason) and a fmt helper module.

§Feature flags

Default is [] — lean: no networking, no persistence, no parallelism.

Feature	Pulls in	Adds / implies
`relay`	tokio-tungstenite, futures	thin WS relay (`relay`/`relay_browser`/`net`); no libp2p
`networking`	libp2p, futures	`network`, `crdt`; implies `relay`
`persistence`	memmap2, sha2	`file`, `fs` (VFS), `storage`
`concurrency`	rayon, bumpalo	`concurrency`, `memory`
`io-uring`	io-uring, crossbeam-channel	`UringVfs` (Linux only); implies `persistence`
`full`	the three below	`networking` + `persistence` + `concurrency`
`distributed`	networking + persistence	`Distributed<T>`

docs.rs documents with full.

§Dependencies

Internal: logicaffeine-base, logicaffeine-data.

Always-on external: serde, bincode, async-trait, once_cell, async-lock, crc32fast. Native targets also pull tokio, rand, getrandom, uuid; wasm32 targets pull wasm-bindgen(-futures), js-sys, web-sys, futures.

Feature-gated external: libp2p (networking), tokio-tungstenite + futures (relay), memmap2 + sha2 (persistence), rayon + bumpalo (concurrency), io-uring + crossbeam-channel (io-uring, Linux).

§License

Business Source License 1.1 — see LICENSE.md.

Docs index · Root README · Changelog

Re-exports§

pub use io::show;
pub use io::read_line;
pub use io::println;
pub use io::eprintln;
pub use io::print;
pub use io::Showable;
pub use temporal::LogosDate;
pub use temporal::LogosMoment;
pub use temporal::LogosSpan;
pub use temporal::LogosTime;
pub use word_rt::hsum_lanes4;
pub use word_rt::int_of_word16;
pub use word_rt::int_of_word32;
pub use word_rt::int_of_word64;
pub use word_rt::lanes16_word16;
pub use word_rt::lanes4_word64;
pub use word_rt::lanes8_word32;
pub use word_rt::montmul32;
pub use word_rt::mul32x32to64;
pub use word_rt::mulhi16;
pub use word_rt::splat4_word64;
pub use word_rt::and_not4;
pub use word_rt::rotl;
pub use word_rt::rotr;
pub use word_rt::word_and;
pub use word_rt::word_or;
pub use word_rt::word_not;
pub use word_rt::seq_of_lanes16;
pub use word_rt::seq_of_lanes4;
pub use word_rt::word32_shr;
pub use word_rt::word64_and;
pub use word_rt::word64_shl;
pub use word_rt::word64_shr;
pub use word_rt::seq_of_lanes8;
pub use word_rt::splat16_word16;
pub use word_rt::splat8_word32;
pub use word_rt::word16;
pub use word_rt::word32;
pub use word_rt::word64;
pub use word_rt::word8;
pub use word_rt::WordRotate;
pub use word_rt::lanes4_word32;
pub use word_rt::lanes4_of;
pub use word_rt::seq_of_lanes4w32;
pub use word_rt::sha1rnds4;
pub use word_rt::sha1msg1;
pub use word_rt::sha1msg2;
pub use word_rt::sha1nexte;
pub use word_rt::lanes16_word8;
pub use word_rt::seq_of_lanes16w8;
pub use word_rt::splat16_word8;
pub use word_rt::shuffle16;
pub use word_rt::shr_bytes16;
pub use word_rt::interleave_lo16;
pub use word_rt::interleave_hi16;
pub use word_rt::byte_add16;
pub use word_rt::maddubs16;
pub use word_rt::packus16;
pub use ntt::mlkem_base_mul;
pub use ntt::mlkem_byte_decode;
pub use ntt::mlkem_byte_encode;
pub use ntt::mlkem_cbd2;
pub use ntt::mlkem_cbd3;
pub use ntt::mlkem_compress;
pub use ntt::mlkem_decompress;
pub use ntt::mlkem_inv_ntt;
pub use ntt::mlkem_ntt;
pub use ntt::mlkem_sample_a;
pub use ntt::mlkem_sample_ntt;
pub use ntt::mlkem_to_mont;
pub use keccak::sha3_256;
pub use keccak::sha3_512;
pub use keccak::shake128;
pub use keccak::shake256;
pub use tokio;

Modules§

addr: Address normalization — libp2p multiaddr → WebSocket URL.
aead: ChaCha20-Poly1305 AEAD (RFC 8439) — the symmetric seal that closes the post-quantum channel: an ML-KEM-768 handshake establishes the shared secret, HKDF derives this 32-byte key, and every wire message is sealed here. ChaCha20 is a pure Word32 ARX cipher (the same primitive the assets/std/crypto.lg chacha20Block ships in Logos); Poly1305 is the one-time authenticator in constant-time 5×26-bit limbs (no bignum). Verified against the RFC 8439 §2.4.2 / §2.5.2 / §2.8.2 known-answer vectors. The tag compare is constant-time.
env: Environment Variable and Argument Access
file: Simple File I/O Operations
fmt: Formatting utilities
fs: Virtual File System Abstraction
io: I/O Operations for LOGOS Programs
keccak: Keccak-f[1600] + SHA-3 / SHAKE runtime kernels — the symmetric/hash layer ML-KEM is built on (SHA3-256/512 for hashing, SHAKE128 for matrix expansion, SHAKE256 for the PRF). Reached from compiled LOGOS via the sha3_256 / sha3_512 / shake128 / shake256 stdlib functions. Verified against the NIST FIPS-202 KATs (see the tests). Input/output are LOGOS Int bytes (0..255) carried in a Seq of Int.
mldsa: ML-DSA-65 (FIPS-204 / Dilithium) runtime kernels — the post-quantum SIGNATURE scheme that complements ML-KEM-768 in the channel. This module builds bottom-up: the length-256 NTT over the Dilithium prime q = 8380417 (a COMPLETE transform, unlike Kyber’s incomplete one — q ≡ 1 (mod 512), so X²⁵⁶+1 splits fully), with signed Montgomery reduction. Validated against the schoolbook negacyclic convolution.
mlkem: ML-KEM-768 (FIPS-203) keygen / encapsulation / decapsulation as a Rust composition of the verified native kernels in crate::ntt (NTT, base-multiply, CBD, compress, byte-encode, 4-way AVX2 matrix expansion) and crate::keccak (SHA3-256/512, SHAKE256). This is the exact same primitive set the assets/std/crypto.lg Logos ML-KEM orchestrates and that the logicaffeine-tests AOT gates prove bit-exact vs the FIPS-203 reference — here orchestrated in Rust so the post-quantum channel (logicaffeine_compile::concurrency::channel) can run the handshake. Coefficients ride the fast Word16 carrier throughout.
net: Net — the cross-target relay-backed network handle the interpreter holds.
ntt: ML-KEM (Kyber) negacyclic NTT runtime kernel — the verified scalar reference + AVX2 i16×16 path that compiled LOGOS reaches through the mlkemNtt stdlib function. Ported from the validated scripts/ntt_simd_proto.rs (round-trip + AVX2==scalar bit-identical). q = 3329, R = 2¹⁶, the incomplete 7-level transform over ℤ_q[X]/(X²⁵⁶+1). The Montgomery reduction it uses is kernel-certified (logicaffeine_kernel::field_algebra::montgomery_reduction_*).
random: Random Number Generation
relay: Thin WebSocket relay — the v1 browser↔mesh bridge.
relay_proto: The relay wire protocol — shared verbatim by the native server/client (super::relay) and the browser client (super::relay_browser). Both targets serialize the SAME RelayFrame with bincode, so a browser tab and a native node speak an identical language across the WebSocket.
storage: Persistent Storage with Journaling
temporal: Temporal types for Logicaffeine.
text
time: Time Utilities
word_rt: Runtime support for the Word8/Word16/Word32/Word64 ring types in COMPILED LOGOS.

Structs§

Lanes4Word32: Four lanes of Word32 = one 128-bit register (__m128i) — the SHA-1 state/message carrier. Unlike the arithmetic lane types, its vocabulary is the four Intel SHA operations (sha1rnds4/sha1msg1/ sha1msg2/sha1nexte), so SHA-1 WRITTEN in Logos over these compiles to the sha1rnds4 hardware sequence (AOT) and runs the byte-identical software spec [crate::sha_ops] on the interpreter. Lane i is bits [32i+31 : 32i] — index 0 low, index 3 high — matching _mm_loadu_si128.
Lanes4Word64: Four lanes of Word64 (one 256-bit SIMD register) — the Poly1305 accumulator lane vector. Carries [u64; 4]; ops have an AVX2 fast path proven byte-identical to the scalar lanes.
Lanes8Word32: Eight lanes of Word32 (one 256-bit SIMD register). Operations are lane-wise over the ℤ/2³² ring.
Lanes16Word8: Sixteen Word8 lanes = one 128-bit register (__m128i) — the BYTE-SHUFFLE carrier for SIMD text codecs (hex encode/decode). Its vocabulary is shuffle (pshufb, a 16-entry byte LUT), byte AND, per-byte shift, and the two byte interleaves — so a hex codec WRITTEN in Logos over it compiles to the pshufb sequence (AOT, when SSSE3 is statically enabled) and runs the byte-identical scalar spec on the interpreter. Lane i is byte i (index 0 low), matching _mm_loadu_si128.
Lanes16Word16: Sixteen lanes of Word16 (one 256-bit SIMD register) — the NTT coefficient lane vector. Carries [u16; 16]; the multiply-high is the SIGNED _mm256_mulhi_epi16 (the Montgomery butterfly’s mulhi). Ops have an AVX2 fast path proven byte-identical to the scalar lanes.
Word8: A 8-bit wrapping integer: the ring ℤ/2^8ℤ, where every operation is total and wraps modulo 2^8.
Word16: A 16-bit wrapping integer: the ring ℤ/2^16ℤ, where every operation is total and wraps modulo 2^16.
Word32: A 32-bit wrapping integer: the ring ℤ/2^32ℤ, where every operation is total and wraps modulo 2^32.
Word64: A 64-bit wrapping integer: the ring ℤ/2^64ℤ, where every operation is total and wraps modulo 2^64.

Functions§

panic_with: Panic with a custom message (used by generated LOGOS code)