Module pnp 

PNP — the information-theoretic true one-time pad tier, the last resort should computational cryptography fall (the P = NP scenario the name marks).

Every other suite in super::channel — Classic, Hybrid, PQ, PQ-Max — rests on a hardness assumption (a lattice, a factoring, a discrete-log problem). If those assumptions collapse, so does the secrecy. This tier does not: a Vernam one-time pad is perfectly secret by Shannon’s theorem, unconditionally, against a computationally unbounded adversary. The price Shannon exacts is exact and unavoidable — one truly random pad byte per plaintext byte, used once and never again — so this is a break-glass tier for crown-jewel traffic, not the bulk path.

Two constraints define the design:

1. A true pad, never a stream. The pad is not grown from a seed by a PRG — that would be a stream cipher (computationally secure, and so it would fall with P = NP, defeating the entire purpose). The pad is pre-provisioned, externally-sourced true randomness, shared out of band. “Rotation” is a synchronized cursor advancing through that pool, consuming a fresh, never-reused segment (a “cover”) per message.
2. No randomness at runtime. PnpSuite::seal / PnpSuite::open draw zero entropy — they are pure deterministic functions of (pad, cursor, plaintext). All randomness is the pad. This also makes sealed traffic replayable under the interpreter’s determinism model.

The pad is quality-gated at provisioning: a real pad is incompressible (K(pad) ≈ |pad|), so PadPool::shared rejects any pool the logicaffeine_proof::ait classifier can compress — a structured “pad” is a weak pad. (The connection is exact: a PRG-grown pad is by definition low-Kolmogorov-complexity, which is precisely what the classifier detects.)

Confidentiality alone is not enough: XOR is malleable — flip a ciphertext bit and the plaintext bit flips, undetected. So each cover carries a one-time Wegman–Carter MAC (Poly1305 keyed by fresh pad bytes, logicaffeine_system::aead::poly1305); because the key is one-time pad material, the authentication is also information-theoretic, not computational.

Speed. seal writes the plaintext straight into the frame buffer and XORs the pad in place (one pass, LLVM-vectorized), then MACs a single contiguous region — no intermediate ciphertext copy, one allocation. Throughput is therefore bounded by Poly1305 (which has an AVX2 path) plus a memcpy-speed XOR: a one-time pad is cheap when the codec never copies the payload twice.

The next pad. Net-new pad entropy cannot be produced inside the channel (Shannon), so the next pad is always fresh out-of-band randomness. What the codec provides is a seamless, authenticated handoff: each frame is tagged with its pad epoch; when a pool nears exhaustion a peer emits an authenticated roll cover (a kind-tagged cover, MAC’d by the current pad) committing to the next epoch’s id and a hash of the next pad, so both sides confirm they hold identical bytes before switching. The convergent catalog of epochs is a natural fit for the logicaffeine_data::crdt layer (an OR-Map of epoch → commitment, a version-vector consumption frontier per actor); the rule that keeps CRDTs safe here is that pad allocation stays partitioned (one writer per pad byte), so the CRDT only ever records a frontier, never arbitrates an allocation (which would be a two-time pad).

Frames ride the super::channel envelope:

[ CHAN_MAGIC | CHAN_VER | SUITE_PNP | kind:u8 | epoch:u32 | offset:u64 | len:u32 | ct(len) | tag:16 ]

Structs

FileLedger

A crash-safe file-backed ledger: the send cursor is written to a temp file, fsync’d, then renamed over the target, so a restart resumes past every offset ever handed to a caller and a crash leaves either the old cursor or the new one, never a torn value. Native-only (the relay path is native-only); a browser peer would journal the cursor through the OPFS VFS.

MemLedger

The default in-memory, non-durable ledger: a process-lifetime cursor. Correct for ephemeral sessions; for crash-safety across restarts install a durable store via PnpSuite::with_ledger.

PadPool

A shared, pre-provisioned pool of true random bytes for one pad epoch, split into two directional halves. Both peers build an identical pool from the same out-of-band material and split it the same way, so each direction is a private, agreed pad both sides index into.

PnpSession

A live bidirectional PNP session for the interpreter’s send/receive seam: it seals outbound covers with this peer’s send half and opens inbound covers with its receive half. Install it on the channel via super::channel::with_session / super::channel::install_session and every Send / receive on that thread is one-time-pad protected — fail-closed on exhaustion.

PnpSuite

A keyed one-time-pad channel over one directional half of a PadPool at one pad epoch. A peer seals with the suite for its send direction and opens with the suite for its receive direction; because the two directions are different pad halves, a peer never seals and opens over the same bytes.

Enums

PadError

Why a pad pool was refused at provisioning.

Role

Which end of the shared pool this peer is. The pool is split identically on both peers into two directional halves so the two directions never draw overlapping pad — the same reasoning behind super::channel::derive_aead_key’s i2r / r2i split, made physical.

Constants

MAC_KEY_LEN

The one-time Poly1305 MAC key length — 32 pad bytes are consumed per cover for authentication, on top of the len bytes consumed for the XOR keystream.

RECV_WINDOW_BYTES

The default receiver reorder/replay window, in pad bytes. A cover whose offset is older than newest_end - RECV_WINDOW_BYTES is refused: it is either a replay of long-consumed pad or so far out of order the window can no longer prove it was not already accepted. Forward jumps (a dropped cover skipped) are always fine — they consume fresh pad, never reused pad.

TAG_LEN

The authenticator tag length (Poly1305).

Traits

PadLedgerStore

The durable record of how far the send cursor has advanced — the single piece of state whose loss would be catastrophic, because reissuing a consumed offset is a two-time pad. An implementation must make PadLedgerStore::commit_cursor durable (fsync) before the caller emits the sealed frame, so a crash can only ever waste pad, never reuse it.

Functions

frame_kind

The cover kind of a PNP frame ([KIND_DATA] / [KIND_ROLL]), or None if it is not a well-formed PNP frame — lets a receive loop dispatch data vs. handoff without opening.

frame_offset

The half-local pad offset a PNP frame draws from, or None if it is not a well-formed PNP frame. Useful for monitoring the pad high-water mark without opening the cover.