Pleromatic Residual Atlas

This file is the falsifiability protocol for the Pleromatic Residual Atlas — the capture pipeline, dictionary build, and dict-mode encode contract that turn the bw-codec wire from a 3/4 word-pack into a workload-conditioned compressor. It is the prediction ledger, not a results document. Every empirical claim below is marked as a prediction (P*) or a falsification trigger (F*); nothing here is an observation.

Companion documents:

• BOWL_MESH_FALSIFIABILITY.md (same dir) — the canonical protocol pattern this file mirrors. Tone, structure, the *_runtime_oracle_* pentad discipline, the honesty boundary — inherited verbatim.
• AMPLITUHEDRON_BITWISE_WIRE.md (same dir) — the BWAH envelope that carries the dict-mode .bw blob. This protocol composes with the amplituhedron wire at the inner-payload boundary; the BWAH framing is untouched.
• ACKERMANN_CERTIFICATION_PROTOCOL.md (same dir) — the pentad discipline pattern.
• Gnosis/PleromaticResidualAtlas.lean (in open-source/gnosis-math/) — the six oracle theorems pinning BWMR record geometry, BWDC dictionary geometry, and the dict-flag bit semantics.
• Gnosis/AmplituhedronWireBitwiseContract.lean (in open-source/gnosis-math/) — the upstream wire contract the atlas imports.
• src/residual_capture.rs — the env-gated FileResidualSink that appends BWMR records on the hot path.
• src/residual_dict.rs — the BWDC encoder/decoder + loader.
• src/bin/build-residual-dict.rs — the offline tool that reads BWMR captures, clusters by frequency, and emits a .bwdict.

1. Headline

The bw-codec wire (open-source/bitwise/src/bw_codec/) ships with dict-mode capability already wired through EncodeBwOptions.dictionary, but no dictionary is loaded by default and no production residual corpus has been captured to build one from. Without a dictionary, the codec is a 3/4 word-pack + integrity fingerprint — fp48-packed bytes round-trip exactly but do not compress random f32 residuals. The predicted wire for a single qwen-coder-7b tail residual is 14370 bytes (AMPLITUHEDRON_BITWISE_WIRE.md §9 P1) — that is the no-dictionary ceiling and it does not improve as you ship more sessions.

The Pleromatic Residual Atlas is the missing data half of the wire. It captures real Luminary-basin residuals during inference into BWMR-format binary files, clusters them offline by frequency at fixed window length, and emits a .bwdict file the runtime loads at startup. dict-mode then exploits the cross-token / cross-session structural regularity that post-RMSNorm Luminary residuals carry (near-unit-norm Gaussian-ish but with strong prefix-conditioned modes), in the same way standard dictionary compressors exploit repeated byte motifs in text. Predicted shrink with a learned dictionary is 3.5×–10× on prefix-shared workloads; the lower bound is sized to the codec, not to wishful arithmetic.

The honesty boundary is sharp: without measurement, this is a corpus collection plan and a falsifiable compression hypothesis. Empirical clustering may not reveal exploitable regularity, in which case the atlas falsifies and the no-dictionary 14370-byte ceiling is the wire we ship.

2. The capture pipeline

src/residual_capture.rs defines FileResidualSink, an env-gated appender that writes BWMR records to a configured directory. Activation is by environment variable, default OFF:

• GNOSIS_RESIDUAL_CAPTURE=/path/to/dir — root directory for capture files. When unset (default), the sink is the no-op NullResidualSink and no allocation happens on the hot path.
• GNOSIS_RESIDUAL_CAPTURE_LAYERS=lo:hi — optional layer range filter (inclusive). Lets a single capture run target a slice of the model rather than every layer. Default: all layers.
• GNOSIS_RESIDUAL_CAPTURE_MAX_BYTES — optional soft cap; the sink closes its current file and rotates when the cap is hit. Default: unlimited (the operator is responsible for disk).

The capture call sites fire from inside the model forward path, at two points per layer:

• Post-RMSNorm in the attention forward path — after the input norm and before the QKV projection. This is the Luminary-basin residual the prefix cache and the bowl Q-filter both consume, so a dictionary built here transfers to those downstream codecs without re-derivation.
• Per-layer-out in the FFN exit — after the FFN residual add. This is the wire payload the amplituhedron capture endpoint ships (AMPLITUHEDRON_BITWISE_WIRE.md §2.2). A dictionary trained here directly conditions the wire on the workload the amplituhedron endpoint observes.

Both call sites pass through ResidualSink::record(layer_idx, seq_idx, hidden_dim, &residual). The default trait impl on NullResidualSink is a #[inline] fn record(...) {}, so when capture is off the call is fully elided by the optimizer. The non-null impl is one write_all per record into a buffered file handle keyed by (model_id, run_id); the buffer flushes on rotation or process exit.

The hot-path overhead claim is encoded in P3 below. The capture path does no work on the float buffer beyond a borrowed byte view; it does not copy or normalize, and it does not block on disk (the buffered writer is non-blocking, with backpressure surfaced as a dropped-record counter rather than a hot-path stall).

3. The dictionary build

src/bin/build-residual-dict.rs is the offline tool that reads BWMR capture files, slices the float payloads into fixed-length byte windows, counts window frequency, and emits the top-N as a .bwdict file. CLI shape:

build-residual-dict \
  --input  /path/to/captures/ \
  --output /path/to/dict.bwdict \
  --entry-len 64 \
  --max-entries 4096 \
  --layer-filter 10:30 \
  --model qwen-coder-7b

Knobs:

• --entry-len — byte width of each dictionary entry. Default 64 (16 f32 lanes — one cache line on x86, one SVE vector on ARM).
• --max-entries — top-N entries to keep. Default 4096. The BWDC format does not cap this; the cap is a memory/compression-ratio tradeoff the operator chooses.
• --layer-filter — optional inclusive layer range. Lets a single capture corpus produce per-layer-band dictionaries (early layers carry different residual structure than late layers; one dictionary per band may shrink the wire more aggressively than a single global dictionary).
• --model — annotation field stamped into the dictionary header comment. Not a hard contract; the runtime can load any .bwdict with any model, and P2 below predicts partial transfer.

The tool is deterministic on a fixed input set: identical capture files in identical order yield byte-identical dictionaries. This matters for reproducibility of the wire-size measurements that anchor P1.

4. Format specs

4.1 BWMR record

Each captured residual is one BWMR record:

byte 0-1   layer_idx     u16 LE
byte 2-5   seq_idx       u32 LE
byte 6-9   hidden_dim    u32 LE
byte 10-17 timestamp_ms  u64 LE
byte 18+   payload       f32[hidden_dim], LE

Header width: 18 bytes (bwmrHeaderLen). Total record width for hidden_dim = h: 18 + 4*h bytes.

For qwen-coder-7b (hidden_dim = 3584):

18 + 4 * 3584 = 18 + 14336 = 14354 bytes per record.

This is the Lean-anchored constant in bwmr_record_len_qwen_7b. The capture file is a flat concatenation of records — no per-record framing, no compression at capture time. The file is self-describing record-by-record via the hidden_dim header field, so capture from a mixed-architecture run (multiple models in the same directory) still decodes correctly.

4.2 BWDC dictionary

byte 0-3   magic         "BWDC"  (0x42 0x57 0x44 0x43)
byte 4-7   version       u32 LE  (1)
byte 8-11  entry_count   u32 LE
byte 12-15 entry_len     u32 LE
byte 16+   entries       entry_count × entry_len bytes

Header width: 16 bytes (bwdcHeaderLen). Total: 16 + entry_count * entry_len bytes.

For the default --max-entries 4096 --entry-len 64:

16 + 4096 * 64 = 262160 bytes ≈ 256 KiB.

That is the dictionary size the runtime memory-maps at startup. It is loaded once per worker process and shared across all inferences; the amortized per-request memory cost is zero on hot processes.

The magic bytes encode as decimal [66, 87, 68, 67] (the Lean oracle bwdc_magic_oracle uses the decimal form; both are the same byte sequence). The version byte is fixed at 1 in the current format.

4.3 Dict-flag semantics on the inner .bw blob

When a dictionary is loaded, the bw-codec version byte of the emitted .bw blob has the DICT_FLAG (0x80) bit set. The Lean theorem dict_flag_set_when_high_bit pins this: 0x81 & 0x80 ≠ 0 evaluates to true. The companion dict_flag_clear_when_low_bit pins the absence path: 0x01 & 0x80 = 0. The decoder side reads the flag and dispatches between dict-mode and plain-mode decompression accordingly.

This is the only signal on the wire that distinguishes a dict-mode payload from a plain-mode payload. The BWAH envelope flags byte (AMPLITUHEDRON_BITWISE_WIRE.md §2.4) is untouched — dict-mode is an inner-blob concern, not a framing concern.

5. Lean → runtime oracles

Gnosis/PleromaticResidualAtlas.lean exports six oracle theorems. The Rust kernel (residual_capture.rs, residual_dict.rs) MUST reproduce their value-level outputs on the same witnesses:

The pentad-plus-one shape mirrors the Bowl-Mesh and Ackermann pentad discipline (BOWL_MESH_FALSIFIABILITY.md §6, ACKERMANN_CERTIFICATION_PROTOCOL.md §3): the Lean values are not just documentation, they are the values the Rust kernel must hit on the same inputs. Oracles 1–5 are exact-Nat contracts; oracle 6 is the Bool dispatch contract. Any deviation is a primitive-level failure under F5 below.

Gnosis/PleromaticResidualAtlas.lean::pleromatic_residual_atlas_pentad bundles oracles 1–5 into a single ∧-chain so the certificate can be discharged as one term.

6. Predictions

All five are predictions, not observations. They will be falsified or upheld by build-residual-dict over real captures from PRIORITY #0 Gemma4 inference or the qwen-coder-7b smoke runs.

• P1. A 256-token system-prompt corpus, captured across 100 sessions on qwen-coder-7b, yields a dictionary of top 4096 entries × 64-byte windows that compresses the post-RMSNorm tail residual from 14336 raw LE bytes to ≤ 4000 bytes (≥ 3.5× shrink) on a fresh session drawn from the same prompt distribution. Justification: Luminary-basin residuals are near-unit-norm and prefix-conditioned; a 256-token shared prefix biases per-layer residuals toward a small number of modal byte motifs at 64-byte (16-lane) granularity. Standard dictionary compressors hit 3.5×–10× on prefix-shared workloads; 3.5× is the floor of that range.

• P2. Dictionary entries learned from qwen-coder-7b residuals provide ≥ 2× wire shrink when loaded against qwen-coder-13b inference, on the same prompt distribution. Justification: the two models share tokenizer and pretraining lineage, and their post-RMSNorm residuals should occupy overlapping regions of the Luminary basin even at different hidden dimensions. Cross-model transfer at < full-shrink but > no-shrink is the falsifiable predicate.

• P3. Capture overhead on the inference hot path is ≤ 5% wall-time when GNOSIS_RESIDUAL_CAPTURE is unset, and ≤ 20% wall-time when set (with default rotation thresholds and a buffered writer). Justification on the OFF path: the NullResidualSink impl is a #[inline] fn record() {} that the optimizer elides; the only cost is the dispatch through the trait object. Justification on the ON path: one borrowed byte view + one buffered write_all per record; no copy, no normalization, no synchronous flush.

• P4. Dict-loaded encode latency at the post-RMSNorm call site is ≤ 200 μs per residual at p50 on the qwen-coder-7b tail (3584 f32). The no-dictionary baseline is ~100 μs per residual (AMPLITUHEDRON_BITWISE_WIRE.md §9 P2 sized at ≤ 200 μs as a ceiling). A 2× latency overhead for a ≥ 3.5× wire shrink is the predicted tradeoff; if encode dominates we fall to F2 below.

• P5. Round-trip of a dict-mode .bw blob produced by encode_bw with a loaded BWDC dictionary, then decoded by decode_bw with the same dictionary, yields byte-exact f32 recovery on the captured residuals (N=1000 random + 100 real qwen-coder-7b tails). Justification: the dict-mode path is a substitution lookup, not a lossy quantization; the f32 → bytes step is unchanged, and the substitution is byte-for-byte exact when the dictionary entry matches.

7. Falsification triggers

• F1. A dictionary built from ≥ 1 GiB of captured residuals shrinks the wire by < 1.5× on a held-out fresh-session sample. Indicates the residual stream has no statistical regularity at the 64-byte-window granularity the dictionary builder is sized for. Falsification action: drop dict-mode entirely, ship the 14370-byte no-dictionary wire (AMPLITUHEDRON_BITWISE_WIRE.md §9 P1) as the production ceiling, and explore non-byte-window codecs (PCA, low-rank, residual-of-residual) before claiming any shrink beyond 1.0×.

• F2. Capture overhead exceeds 30% when ON. Indicates the buffered writer is blocking the hot path or the trait dispatch has unexpected cost. Falsification action: move capture to a separate thread with a bounded channel, accept dropped records under load, and re-measure. If the threaded variant still exceeds 30%, the capture pipeline is too expensive for production and we restrict it to offline replays.

• F3. Capture overhead exceeds 1% when OFF (i.e. the zero-cost claim is broken). Indicates the NullResidualSink dispatch is not actually inlining or the call site has non-trivial argument setup. Falsification action: move the call site behind a compile-time #[cfg(feature = "residual_capture")] gate so the call is fully removed in default builds. This is a worse developer ergonomic but a true zero-cost contract.

• F4. Cross-model transfer (P2) yields ≤ 1.0× shrink — the dictionary actually makes the sibling-model wire larger or leaves it unchanged. Indicates the dictionary is over-fit to the source model's residual distribution and does not generalize even across the same tokenizer family. Falsification action: ship per-model dictionaries (one BWDC per MODEL_CONFIG entry), accept the per-model build cost, and abandon the transfer-learning claim.

• F5. Dict-mode encode produces non-round-trippable bytes on the N=1000 random + 100 real residual harness — decode_bw returns BwError::Malformed or returns a byte sequence that differs from the input. The codec is supposed to be byte-exact; any drift is a real bug in the dictionary substitution path or the version-byte dispatch. Falsification action: file against open-source/bitwise/src/bw_codec/, pin the wire to plain-mode (no dict-flag) until the round-trip is restored, and re-discharge oracles 5 and 6 against the fixed implementation.

Any of F1–F5 reverts the atlas to "interesting collection" status. None of them by themselves invalidates the BWAH envelope, the amplituhedron prefix cache, or the bw-codec base wire — those sit structurally below the atlas and are not at stake here.

8. Composition with the existing wave

The Pleromatic Residual Atlas plugs into bw-codec's already-shipped dict-mode capability (EncodeBwOptions.dictionary in the TS source, EncodeBwOptions { dictionary, .. } in the Rust port). It does not change the BWAH wire format. The 14-byte BWAH header (AMPLITUHEDRON_BITWISE_WIRE.md §2.1) and the 16-byte capture suffix (§2.2) are byte-for-byte identical with or without a dictionary loaded; the only thing that changes is the inner .bw payload size and the inner version byte's DICT_FLAG bit.

The amplituhedron coordinator (distributed-inference-host/src/pipeline.ts), frame coalescing in the aeon-flow wire (flow_frame.rs), and the Pair X consume branches (COBORDISM_LM_HEAD_SPEEDUP.md) are all orthogonal to this protocol. They consume or emit .bw payloads through the encodeBw/decodeBw API and do not look at the version byte. A worker that has loaded a BWDC dictionary at startup will emit dict-mode payloads transparently; a worker that has not will emit plain-mode payloads. Both sides of the wire dispatch on the version byte, not on out-of-band state.

The composition with the bowl Q-filter is the same as in BOWL_MESH_FALSIFIABILITY.md §9: capture fires post-RMSNorm, the filter runs on the live decode path. They observe the same Luminary-basin vector but at different stages — capture records the pre-filter residual, the filter shapes the post-filter residual. A dictionary trained on captured pre-filter vectors is the right shape for the wire (the wire ships pre-filter Luminary residuals); a dictionary trained on post-filter vectors would be wrong shape (the wire never ships post-filter residuals).

9. Honesty boundary

Nothing in §6 has been measured. The Lean theorems referenced in §4 and §5 exist and are kernel-checked under Init; the empirical predictions they motivate do not. The atlas survives or falls on the capture-and-build pipeline running against a real workload, not on the algebraic argument.

The dictionary build pipeline requires actually capturing residuals during real inference. The natural workload is PRIORITY #0 Gemma4 distributed inference once it produces correct output, or the qwen-coder-7b smoke runs that already pass on the distributed-inference mesh. Until the capture corpus exists, P1–P5 are claims about a corpus we have not built and a dictionary we have not measured. Empirical clustering on Luminary-basin residuals may not reveal exploitable regularity at 64-byte window granularity. The wire compression ceiling is whatever statistical structure exists in the residuals, not what we wish to be there.

The atlas is also blind to two things its compression hypothesis depends on: the prompt distribution the capture corpus is drawn from (a 100-session corpus dominated by one system prompt yields a narrow dictionary that overfits to that prompt; a diverse corpus yields a broader dictionary that may compress nothing well), and the post-RMSNorm amplitude scale (if the scale drifts session-to- session, fixed-width byte windows may straddle the modal motifs and the frequency count flattens). Both are empirical, not theoretical; the harness in build-residual-dict.rs exposes both knobs so the falsification path can drive them.

If F1 and F4 both fire, the atlas has been falsified at the operational level it was proposed at, and we report the result the same way BOWL_MESH_FALSIFIABILITY.md §11 prescribes: this file becomes the historical record, an addendum captures the falsification, and the wire reverts to the no-dictionary 14370-byte ceiling.

10. Pointers

Six implementation surfaces plus this doc — the doc is the falsifiability ledger, not a code surface:

• src/residual_capture.rs — ResidualSink trait, NullResidualSink, FileResidualSink, env-variable parsing, buffered writer, rotation logic. Cited by P3 / F2 / F3.
• src/residual_dict.rs — BwdcDictionary struct, BWDC header parse/emit, dict-flag set/clear, fixed-window slicing primitives used by both the runtime loader and the offline builder. Cited by oracles 3–6 and P5 / F5.
• src/bin/build-residual-dict.rs — offline CLI tool, frequency counter, top-N selector, .bwdict emitter. Cited by §3 and P1 / P2 / F1 / F4.
• Gnosis/PleromaticResidualAtlas.lean — the six oracle theorems (bwmr_header_len_oracle, bwmr_record_len_qwen_7b, bwdc_magic_oracle, bwdc_version_oracle, bwdc_header_len_oracle, dict_flag_set_when_high_bit) and the bundled pleromatic_residual_atlas_pentad. Cited by §5.
• scripts/capture-and-build-dict.sh — operator script that runs one capture session, validates the BWMR file headers, invokes build-residual-dict, and round-trips a held-out residual through the produced dictionary as a smoke test. Cited by §6 P5 / §7 F5.
• AMPLITUHEDRON_BITWISE_WIRE.md — the BWAH envelope the dict-mode .bw payload ships inside. Composition table in §8.
• This doc — open-source/gnosis/distributed-inference/PLEROMATIC_RESIDUAL_ATLAS.md.