WO-01 — Refracting Light C++20 library

7 October 2026 · Implementation and local checks passed. Awaiting Claude’s independent review and owner approval; not merged.

Delivered

  • e46/include/e46/rl.hpp, e46/src/rl.cpp: rl_v3_128, rl_v3_unfolded, length-declared streaming and a 120-byte header PoW helper.

  • Legacy v2 entry points for matching the existing reference vectors.

  • CMake static target E46::rl / librl.a, strict warnings, sanitizer builds, command-line verifier, benchmark and fuzz harness.

  • Python-generated golden JSON, 1,000 random messages plus published/edge cases.

  • ENV documentation and the owner’s UNC brace style in .clang-format: opening function brace on its own line, four-space body indentation, closing brace aligned with the declaration; underscores retained.

Scope follows RL-V3-PAPER.md §1, REFRACTING-LIGHT-SPEC.md §8 and the concrete PoW comparison in CHAIN-DESIGN.md §2b. No SHAKE/KMAC, Rad engine, transactions, ASERT, QTL port or successor hash was built. No research reference or historical experiment evidence was edited by this work order.

Evidence and exact revision

Primary evidence for the formatted final source: final-style.json. It records SHAKE256 fingerprints of the source, build configuration and style configuration, final differential results, benchmark samples and fuzz results.

summary.json records the earlier pre-format full build, golden regeneration and tool versions. Its source hashes predate the owner’s style request. Use the final manifest for source identity. Build/test logs in that directory are retained with final-* labels for the post-format checks. These are local implementation measurements, not an independent cryptographic audit.

Measured results

Gate

Result

Published vectors

All six v2 and six v3 folded/unfolded vectors and both nonce vectors reproduced

Golden corpus

1,107 message cases, including 1,000 seeded random messages

C++ versus Python golden

11,070 message comparisons: both versions, both digest forms, one-shot and streaming chunks 1/7/64/4096; zero mismatches

Original C reference

2,184 folded comparisons across both versions; zero mismatches; reference supports inputs <=256 bytes

Step arithmetic

328 Python/C++ comparisons, including negative-clamp inputs, maximum words and near-limit counters; zero mismatches

Padding / larger messages

Zero/FF/counting patterns and shard boundaries through 4,096 bytes, compared to Python

Release CTest after formatting

2/2 passed

ASan + UBSan CTest after formatting

2/2 passed, sanitizer recovery disabled

Malformed hex cases

Eight fixed malformed cases rejected; also checked by fuzzing

Final libFuzzer run

157,463 executions in 31 seconds, seed 20261007, one worker, input cap 1,024 bytes; no sanitizer errors, crashes or mismatches

Formatting

All eight new C++ headers/sources pass clang-format 22.1.8 --dry-run --Werror

Golden reproducibility

Regenerated from Python and matched the committed JSON byte-for-byte

Unit checks also exercise incomplete/excess updates, retry after rejected input, repeat finalization, update after finalization, independent state snapshots, length/version rejection, negative floor divmod, equality/below/above PoW target boundaries and rejection of incorrectly sized headers. The checks remain active in release builds; the C++ tests do not rely on disabled assert() calls.

Measured single-worker throughput

Host: macOS 26.3 arm64, Apple Clang 21.0.0, Release -O3. Five samples per size, each approximately 0.35 seconds; input varies and the digest is consumed.

Message size

Median hashes/second

4 bytes

550,622

12 bytes

306,007

120-byte header

43,492.2

The 12-byte benchmark clears WO-01’s 250,000 short hashes/second/core gate by about 22%. These are host-specific measurements, not a promise on other machines or evidence of cryptographic security. Full samples are in the final manifest.

API and implementation decisions to review

  1. Byte order: RL record length and output arrays are big-endian, preserving the published hash. This is separate from little-endian chain fields.

  2. Streaming contract: total input length is declared at construction. The API stores two parity shards (2*ceil(n/4) bytes), not the whole message. Unknown-length constant-memory streaming cannot silently replace this record format. Memory allocation failures propagate as exceptions.

  3. Arithmetic: signed 128-bit intermediates, unsigned modular lane arithmetic, floor division for negatives, all lanes read the old state, safe rotations and exactly eight v3 blank steps. Input length bounds prevent counter overflow.

  4. PoW helper: accepts exactly 120 bytes and compares the digest inclusively with the top 128 bits of a big-endian 256-bit target, per §2b. It does not implement compact-target decoding or ASERT. Section 2’s shorter description should be reconciled with §2b in the separate consensus review; this work does not choose an additional rule.

  5. Portability: currently 64-bit compilers with __int128. Tested on Apple Clang 21 and Homebrew Clang 22 on this Mac. GCC/Linux and Windows/MSVC were not run. No portable 128-bit fallback is claimed.

  6. Dependencies: the library contains no SHA-2 or floating-point arithmetic. The historical C comparison tool has its labelled SHA-256 control and Apple’s CommonCrypto dependency; neither is linked into the C++ library.

Environment issues and resolution

Apple Clang’s ASan/UBSan worked, but its libFuzzer link failed because its runtime archive was absent. The existing Homebrew LLVM 22.1.8 supplied libFuzzer. Nothing was downloaded or installed. The final fuzz run used that compiler with the same ASan/UBSan checks. All runs were under ten minutes; compile jobs were capped at four and test/benchmark/fuzz workers at one.

During construction the owner maps acquired new directory/branch requirements. The new code was moved under e46/ and the branch renamed wo-01-librl before the final checks. Existing map edits were preserved rather than rewritten.

Reproduce and review

See ENV.md, README.md and the API/reproduction guide for exact commands. The branch preserves the remote license commit; 47236cd is the reference baseline before C++ work. Implementation and map snapshots are kept separate for review.

Claude must also run the newly required surprise exam: fresh random inputs from an unpublished seed, checked against Python. That independent exam is pending; the published golden corpus is frozen and was not edited to make tests pass.

Claude must independently re-run vectors/tests, check the formula and PoW/API contracts, examine length and state-handling limits, and review the benchmark and sanitizer evidence. The owner then approves a merge. Local checks passed does not mean WO-01 is independently reviewed or Refracting Light is secure.