# Executive Report: Reticulum Specification Project

Date: 2026-06-09

## Executive conclusion

The project has moved from a useful but uneven Claude-assisted specification
bootstrap into an evidence-controlled Reticulum/LXMF interoperability
specification.

The foundational protocol scope is complete against Mark Qvist's GitHub heads:
`Reticulum@422dc055` (`RNS 1.3.5`) and `LXMF@fab12ad` (`LXMF 1.0.1`).
The repository now contains source audits,
executable runtime evidence, deterministic vectors, chronological flow
documents, an anomaly ledger, and a repeatable migration process.

The older `RNS 1.2.4` / `LXMF 0.9.7` baseline remains preserved as historical
regression evidence. All 28 current verifiers pass at the exact GitHub-head
pins. Three important version-specific
state-behavior changes have already been promoted:

1. per-interface path-request ingress/egress limiting;
2. announce-ingress changes, including an RNS 1.3.4 fix that prevents
   invalid-signature announces from consuming held-announce state.
3. Channel send/retry synchronization that removes several stale-state and
   delivery-race hazards present in RNS 1.2.4.

A reconciliation with the separate LXMF extraction confirmed that its
checked-in Mark source is the same `LXMF@fab12ad` now pinned here. Core
LXMessage bytes remain consistent. LXMF 1.0.1 standardizes reply, reaction,
comment, and continuation fields and emits compression capability signalling.

The project should continue building on the inherited work. Replacing it
would discard substantial useful research and would not improve confidence.
The current three-tier method supplies the missing confidence layer.

## Provenance and method

The inherited repository baseline is commit `cafb288`, dated 2026-05-03,
from `thatSFguy/reticulum-specifications`. It was bootstrapped from two
reverse-engineering efforts with Claude assistance.

This fork adopted a three-tier evidence model:

1. **Source analysis:** answer a narrow protocol question from pinned upstream
   code and record exact evidence.
2. **Executable verification:** reproduce the behavior against upstream,
   adding deterministic vectors where bytes are involved.
3. **Specification promotion:** update normative prose only after the
   behavior is supported by evidence.

This method preserves inherited findings that survive verification, corrects
claims that do not, and leaves explicit markers where evidence remains
external or application-defined.

## Current project state

| Measure | Current state |
|---|---:|
| Commits after inherited baseline | 75 |
| Executable protocol verifiers | 28 |
| Deterministic vector regenerators | 13 |
| Deterministic JSON vector domains | 13 |
| Chronological protocol flow documents | 18 |
| Detailed Tier 1 audit reports | 11 |
| Historical completed baseline | RNS 1.2.4 / LXMF 0.9.7 |
| Current GitHub-head pin | RNS 1.3.5 / LXMF 1.0.1 |
| Exact upstream commits | Reticulum `422dc055`; LXMF `fab12ad` |
| Current-suite result | 28/28 pass |

The pinned baseline covers identity and destination hashes, packet headers,
Token cryptography, announces, all major LXMF delivery forms, Link setup and
traffic, Resource transfer, REQUEST/RESPONSE, transport relay behavior,
tunnels, shared-instance framing, path discovery, stamps, and RNode split
framing.

## Material corrections found

The work has found and corrected claims that would cause interoperability,
security, or operational failures if implemented literally. The most
important include:

- the packet flag byte's bit 7 is IFAC, not part of `header_type`;
- Resource integrity hashing excludes the throwaway four-byte prefix and uses
  a distinct advertisement random value;
- Link REQUEST/RESPONSE authorization constants were reversed in earlier
  prose;
- propagated-LXMF transient IDs are full 32-byte hashes, and `/get` response
  framing and error constants differed from the inherited description;
- transport-relayed Link forwarding, Link proof routing, ordinary DATA final
  hop conversion, reverse-PROOF timeout, announce rebroadcast, path state,
  tunnel entries, and shared-instance framing all required corrections;
- direct LXMF's PACKET/Resource boundary is based on computed content size at
  319/320 bytes;
- the replay-defense key is announce `random_blob`, not a
  `(destination_hash, ratchet_pub)` tuple.

The README's **Spec corrections** section is the implementer-facing errata
index. Detailed evidence is preserved under `audits/`.

## Upstream migration status

The exact GitHub heads were promoted on 2026-06-09. Old behavior remains
reproducible through historical audits and version-aware verifiers.

The initial `RNS 1.3.4` / `LXMF 0.9.9` candidate comparison found:

- all 13 deterministic vector domains retain identical protocol bytes;
- regenerated files differ only in generation-version metadata;
- all 28 current verifiers pass in both environments;
- LXMF 0.9.9 source changes examined so far are operational rather than
  wire-format changes;
- RNS 1.3.4 introduces path-request traffic control, changes announce
  ingress-control behavior and defaults, and hardens Channel send/retry state
  against failure and concurrency races.

The final GitHub-head promotion to RNS 1.3.5 / LXMF 1.0.1 found:

- all 28 verifiers pass;
- LXMF delivery announces now emit the live 3-element form containing
  `[SF_COMPRESSION]`;
- reply, reaction, comment, and continuation field allocations are upstream;
- all other deterministic protocol bytes remain unchanged from the prior
  candidate, apart from regenerated version metadata.

### Authentication status

The official canonical Reticulum repository and release signer are recorded:

- repository:
  `rns://7649a50d84610232d1416b41d2896aff/reticulum/reticulum`
- signer: `bc7291552be7a58f361522990465165c`

The signed RNS 1.3.4 release retrieval was attempted, but this host could not
resolve a Reticulum path to the canonical repository. Exact GitHub commit
hashes are now pinned and reproducible. Canonical Reticulum-network
signed-release authentication remains useful independent provenance work.

## Risk assessment

### Low risk

- Current tested wire formats are stable through the GitHub-head pins except
  for the promoted LXMF announce capability element.
- The current target is repeatable from a fresh virtual environment and has
  no dependency on a specific user's `specenv`.
- Deterministic regeneration protects vector integrity.

### Active risk

- Historical line-number citations may refer to their audited version rather
  than the current head.
- GitHub heads are moving targets; each advancement requires a new exact
  commit pin and complete-suite run.
- Line-number citations will drift as upstream evolves; behavioral verifiers
  reduce but do not eliminate this maintenance burden.

### Deliberately unresolved

Five `UNVERIFIED` callouts remain for third-party deviations,
application-defined values, or ecosystem extensions without upstream
allocations. They do not block the core Reticulum/LXMF baseline and should not
be promoted without external evidence.

## Recommended path

Maintain the GitHub-head target:

1. periodically query Mark's GitHub heads;
2. add version-aware executable evidence for each meaningful change;
3. preserve versioned behavior in the specification;
4. authenticate the signed RNS 1.3.4 artifact when this host has a path to
   the canonical repository;
5. advance exact commit pins only after all verifiers pass.

The Channel send/retry cluster is now complete. It confirmed unchanged wire
bytes, corrected inherited prose that incorrectly said receivers request
retransmission for sequence gaps, documented that upstream treats the
declared Channel payload length as informational, and reproduced five RNS
1.2.4 stale-state or concurrency hazards corrected in RNS 1.3.4. The next
migration cluster should continue through the remaining cited `Transport.py`,
`Link.py`, `Identity.py`, and interface deltas.