jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

After 2nd prompt

Browse source
This commit is contained in:
John Poole 2026-06-08 12:47:32 -07:00
commit e15e8fd62e
7 changed files with 190 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

3
Codex_prompt_1.md Normal file
View file

@ -0,0 +1,3 @@
I have staged at /usr/local/src/reticulum/reticulum-specifications a fork from https://github.com/thatSFguy/reticulum-specifications which will be developed on https://salemdata.net/repo/jlpoole/reticiulum-specification
You previously performed a specification extraction of the LXMF protocol in three task steps for the project under /usr/local/src/reticulum/LXMF. Here in reticulum-specification, an extraction has already been performed by GitHub user thatSFguy using Claude AI. What I would like you to do is compare the analytical method you used for LXMF and then assess what Claude AI did (possibly preserved under /usr/local/src/reticulum/reticulum-specifications/.claude) and then report your findings. What I want to do is create a specification for Reticulum and I don't want to jetticson Claude's work, rather I'd like to build on it. I requested thatSFguy to identify himself to me confidentially and he ignored request; I do not want to develop something with a ghost, so I want to proceed in a way that will align with your approach and/or determine if you can adopt Claude's approach so we can move forward without a lot duplication.

109
Codex_response_1.md Normal file
View file

@ -0,0 +1,109 @@
**Assessment**
Do not jettison Claude’s work. It is a valuable and unusually extensive implementation-derived specification. However, it should be treated as a strong candidate specification undergoing verification, not yet as an authoritative specification.
I can adopt its approach. The best path is a hybrid: retain Claude’s corpus, workflows, vectors, and verifiers, while applying the narrower evidence discipline used for the LXMF extraction to each section before declaring it stable.
**Methods Compared**
The prior LXMF extraction followed three controlled stages:
1. **Source analysis**
- Answered one narrow question: exact serialized `LXMessage` structure.
- Recorded the exact upstream commit and source locations.
- Explicitly distinguished confirmed and unresolved behavior.
2. **Independent structural verification**
- Created deterministic Perl vectors and a separate MessagePack implementation.
- Verified field positions, payload types, message ID, and signature input.
- Explicitly did not claim signature validation because signatures were placeholders.
3. **Specification writing**
- Wrote only the evidence-supported section.
- Preserved unresolved questions.
- Avoided assigning normative requirements beyond the evidence.
See [LXMF/SPEC.md](/usr/local/src/reticulum/LXMF/SPEC.md:1) and [verify_examples.pl](/usr/local/src/reticulum/LXMF/tools/verify_examples.pl:1).
Claude’s Reticulum approach began with a broad 545-line bootstrap specification derived from working implementation notes, then iteratively:
- inspected upstream source;
- created upstream-runtime verifiers;
- generated deterministic wire vectors;
- added chronological protocol flows;
- corrected claims based on issues and interoperability incidents;
- documented maintenance and evidence rules.
The repository now contains approximately 11,000 lines of specification, verifier, vector, and flow material. All 59 commits identify Claude Opus as co-author.
**Where Claude’s Approach Is Stronger**
- The verifier scripts frequently exercise the actual upstream Python implementation rather than only an independent reconstruction.
- Deterministic vectors include real signatures, encryption, handshakes, and derived session keys.
- The repository records corrections instead of hiding mistakes.
- The flows explain complete operations, not merely individual byte layouts.
- The playbook captures important lessons about false-positive self-round-trip tests.
- The evidence policy in [agent.md](/usr/local/src/reticulum/reticulum-specifications/agent.md:1) is fundamentally sound.
Representative strong artifact: [verify_lxmf_opportunistic.py](/usr/local/src/reticulum/reticulum-specifications/tools/verify_lxmf_opportunistic.py:1) performs real identity, signing, encryption, decryption, parsing, and signature-validation operations.
**Where Claude’s Approach Is Weaker**
The broad initial extraction moved faster than its evidence could support. Several material claims were initially wrong:
- private-key on-disk order;
- packet flag bit layout;
- LRPROOF body order and link ID offsets;
- ratchet deduplication mechanism;
- Resource integrity hash;
- KEEPALIVE encryption and proof behavior;
- Link DATA proof signing key;
- `rrc.hub` encoding.
This is not a reason to discard the work. It demonstrates why broad source-derived prose must remain provisional until executable verification exists.
There are also maintenance inconsistencies:
- [SPEC.md](/usr/local/src/reticulum/reticulum-specifications/SPEC.md:3765) says announce, LXMF, and Link vectors are not populated, but all are present.
- [agent.md](/usr/local/src/reticulum/reticulum-specifications/agent.md:105) still describes completed verifier/vector tasks as outstanding.
- The repository is pinned to RNS 1.2.4/LXMF 0.9.7, but the available `rnsenv` contains RNS 1.1.3/LXMF 0.9.3. The verifier suite failed immediately on that mismatch.
- Some broad behavioral claims rely on source citations or implementation experience rather than direct upstream-runtime or cross-implementation tests.
**Recommended Direction**
Use the existing repository as the working foundation, with these governance rules:
1. **Preserve Claude’s specification, flows, vectors, and history.**
2. **Classify each section by evidence level:**
- source-derived;
- upstream-runtime verified;
- independently reconstructed;
- cross-implementation verified;
- unresolved or application extension.
3. **Require two forms of evidence for foundational wire claims.**
- Prefer upstream-runtime verification plus an independent decoder/reconstruction or interoperability test.
4. **Work section-by-section in narrow extraction tasks.**
- Question/report.
- Verifier and deterministic vector.
- Specification correction or promotion.
5. **Treat flows, failure guides, and implementation advice as informative rather than wire-normative.**
6. **Make verification status machine-checkable**, rather than relying only on prose markers.
7. **Require the exact pinned RNS/LXMF environment in CI** and run all verifiers there.
8. **Add negative vectors** proving malformed packets are rejected.
9. **Audit stale documentation automatically.**
**Regarding the Unidentified Contributor**
The Git history identifies the author as `Rob <rob@woodhousellc.com>` and Claude as co-author, but that does not authenticate the person behind the account. You do not need to depend on that identity to continue safely.
The sustainable trust boundary should be:
- not “trust the contributor”;
- not “trust Claude” or “trust Codex”;
- trust reproducible evidence, reviewed changes, exact upstream pins, and independently executable tests.
**Conclusion**
Claude’s work and the prior LXMF approach are compatible. Claude supplied breadth, operational experience, upstream-runtime tooling, and a substantial protocol map. The LXMF method supplies the stricter progression needed to turn that map into a defensible specification.
I recommend continuing from this repository, preserving its history, while treating each existing section as a candidate claim to be audited and promoted through the narrower three-stage LXMF process. No files were modified during this assessment.

10
README.md
View file

@ -15,6 +15,16 @@ This repo collects those findings in one place. The hope is that future client a
Each finding is grounded in upstream source citations (file + line) so it can be re-verified as RNS evolves.
## Method
This fork proceeds with a three-tier evidence model that preserves the existing Claude-assisted work while promoting claims only after verification:
1. **Source analysis report** — answer one narrow protocol question from pinned upstream source, with exact citations and unresolved cases.
2. **Executable verification** — add runnable evidence under `tools/` and deterministic vectors under `test-vectors/` where bytes are involved.
3. **Specification promotion** — update `SPEC.md` as normative prose only after the verifier/vector exists; add correction or incident notes when earlier text would mislead implementers.
See [`agent.md`](agent.md) §3 for the detailed rules.
## What's here
- [`SPEC.md`](SPEC.md) — the single combined spec document, organized by protocol layer

7
SPEC.md
View file

@ -1916,7 +1916,7 @@ The 32-byte `ratchet_pub` field in announces is meant to rotate periodically. Th
The actual replay-and-loop defence in upstream is keyed on **`random_hash`**, not on `ratchet_pub` — see §4.5 step 6.3 (path-table replacement check `not random_blob in random_blobs` at `RNS/Transport.py:1710, 1735, 1748`). Verified by `tools/verify_ratchet_dedup.py`: two announces sharing a `ratchet_pub` but differing in `random_hash[:5]` are both accepted by upstream's replay machinery.
> ⚠️ **Spec correction:** Earlier revisions of this section claimed transit nodes dedup announces on `(destination_hash, ratchet_pub)` tuples and that a non-rotating client becomes invisible to the mesh after one announce. That was wrong on the mechanism: upstream's `RATCHET_INTERVAL = 30 min` × `ANNOUNCE_INTERVAL = 5–15 min` means most upstream announces share a ratchet across 2–6 emissions, so if relays really dropped on `ratchet_pub` equality, upstream wouldn't function. The actual win observed in the bootstrap test (per `agent.md` §5) was incidental — the fix that rotated ratchets per announce also rotated `random_hash`, and it was the latter that mattered.
> ⚠️ **Spec correction:** Earlier revisions of this section claimed transit nodes dedup announces on `(destination_hash, ratchet_pub)` tuples and that a non-rotating client becomes invisible to the mesh after one announce. That was wrong on the mechanism: upstream's `RATCHET_INTERVAL = 30 min` × `ANNOUNCE_INTERVAL = 5–15 min` means most upstream announces share a ratchet across 2–6 emissions, so if relays really dropped on `ratchet_pub` equality, upstream wouldn't function. The actual win observed in the bootstrap test (per `agent.md` §6) was incidental — the fix that rotated ratchets per announce also rotated `random_hash`, and it was the latter that mattered.
#### 7.3.1 Rotation cadence
@ -3761,8 +3761,11 @@ RRC does **not** use opportunistic packets, Resource transfer (§10), REQUEST/RE
See [`test-vectors/`](test-vectors/). Currently populated:
- **`identities.json`** — Alice and Bob private-key inputs plus their derived `public_key`, `identity_hash`, and `lxmf.delivery` `destination_hash`. Verified by `tools/verify_destination_hash.py`; regenerated by `tools/regen_identities.py`. Covers SPEC.md §1.1 and §1.2.
- **`announces.json`** — signed announce packets, with and without ratchet material. Verified by `tools/verify_announce_roundtrip.py`; regenerated by `tools/regen_announces.py`. Covers SPEC.md §4.1, §4.2, and §4.5.
- **`lxmf.json`** — deterministic opportunistic LXMF plaintext and Token ciphertext vectors. Verified by `tools/verify_lxmf_opportunistic.py`; regenerated by `tools/regen_lxmf.py`. Covers SPEC.md §3 and §5.
- **`links.json`** — Link handshake and LRRTT vectors, including LINKREQUEST, LRPROOF, derived keys, and the activation packet. Verified by `tools/verify_link_handshake.py` and `tools/verify_link_lrrtt.py`; regenerated by `tools/regen_links.py`. Covers SPEC.md §6.1-§6.4 and §6.6.
> ⚠️ **UNVERIFIED:** The remaining vector categories — signed announce packets, encrypted opportunistic LXMF DATA, and Link handshake (LINKREQUEST + LRPROOF + derived session keys) — are not yet populated. See [`agent.md`](agent.md) §5 and [`todo.md`](todo.md) for the remaining bootstrap work.
Remaining vector work should focus on negative/rejection cases and link-delivered LXMF bodies rather than the original bootstrap categories.
An implementation that round-trips every test vector — both directions — should be wire-compatible with upstream Reticulum and LXMF for the covered operations.

83
agent.md
View file

@ -51,7 +51,44 @@ PRs must include the verifier scripts. Don't commit a "verified" claim without t
---
## 3. Required tools
## 3. Three-tier evidence model
This repository keeps the breadth of the existing Claude-assisted extraction, but promotes claims through the narrower three-tier process used for the LXMF extraction. Treat existing prose as useful candidate material until the relevant tier is satisfied.
### Tier 1 — Source analysis report
Use this tier to answer one narrow protocol question, not to rewrite a whole subsystem. The output is an analysis note, issue comment, or draft SPEC.md text that includes:
- The exact upstream RNS/LXMF version or commit inspected.
- The files, functions, constants, and line numbers that define the behavior.
- A byte layout or state-machine description precise enough to test.
- A clear list of unresolved cases and assumptions.
Tier 1 is enough to add an `⚠️ UNVERIFIED` claim with citations. It is not enough to remove a marker for a foundational wire-format claim.
### Tier 2 — Executable verification
Convert the Tier 1 claim into runnable evidence under `tools/` and, where byte-level data is involved, deterministic vectors under `test-vectors/`.
Prefer upstream-runtime verification: a Python script should exercise installed upstream RNS/LXMF and compare exact bytes, parsed fields, signatures, keys, or state transitions. For high-risk layouts, add an independent reconstruction or decoder as a cross-check. The LXMF extraction's Perl MessagePack verifier is a good example of this second form.
Tier 2 is enough to remove an `⚠️ UNVERIFIED` marker when the verifier is committed beside the claim and passes against the pinned upstream versions.
### Tier 3 — Specification promotion and maintenance
Only after Tier 2, update `SPEC.md` as normative prose:
- Add or correct the section text.
- Link the verifier or vector that backs the claim.
- Preserve version-specific behavior if upstream changed.
- Add a `README.md` spec-correction entry when earlier published text would mislead implementers.
- Add a `playbook.md` incident entry when the finding explains a non-obvious interoperability failure.
For foundational wire behavior, prefer two evidence forms before calling the result stable: upstream-runtime verification plus either an independent decoder/reconstruction or a live interop test. Flows and troubleshooting prose may be source-cited without this second form, but must not claim byte-level finality they do not have.
---
## 4. Required tools
Agents working on this repo should have access to:
@ -86,7 +123,7 @@ This spec is only as good as the upstream version it was checked against. **Befo
---
## 4. Marking convention
## 5. Marking convention
Use these GitHub-flavored Markdown blockquote forms so they render distinctly:
@ -100,7 +137,7 @@ When you verify a previously-marked claim, **delete the entire blockquote** and
---
## 5. Audit pass — initial state of `SPEC.md`
## 6. Audit pass — initial state of `SPEC.md`
The bootstrap `SPEC.md` was assembled from the working notes of two reverse-engineering efforts ([webclient](https://github.com/thatSFguy/reticulum-lora-webclient) and [mobile-app](https://github.com/thatSFguy/reticulum-mobile-app)). Some sections are already strongly verified by working code in those repos; some are source-cited but not directly tested in this spec repo's tools; some are observational claims that need formal verification.
@ -126,20 +163,20 @@ Initial confidence assessment (subjective, not authoritative — re-do this audi
| §8 KISS / HDLC framing | High — both work in production on the reference clients |
| §9.1–§9.8 Implementation gotchas | Each was a real bug that bit a real implementation. High confidence each is real; some lack formal test scripts. |
| §10 Resource fragmentation | Source-cited from `RNS/Resource.py` against RNS 1.2.4; not yet runtime-verified in this repo's `tools/`. |
| §11 Test vectors | The vectors themselves are verified; the test-vectors/ directory needs to be populated in this repo (currently partially populated). |
| §11 Test vectors | Historical bootstrap item. `test-vectors/` is now populated with identities, announces, opportunistic LXMF, and Link vectors. Future work should add negative vectors and link-delivered LXMF coverage. |
| §12 Source map | High |
**Concrete next-task list** for the agent picking this up:
**Historical bootstrap tasks from the initial audit, now mostly complete:**
1. Run the audit — re-evaluate the table above with your own reasoning, don't just trust it.
2. Populate `test-vectors/` with at least: identity material, a signed announce, an opportunistic-LXMF round-trip, a Link handshake.
3. Write `tools/verify_announce.py` that loads a test vector and verifies bytes against upstream RNS.
4. For each `> ⚠️` or `> 🔮` callout you add, write the verifier alongside.
5. Open issues for any claim you can't verify and tag them `needs-verification`.
1. Re-evaluate the table above with your own reasoning, not by copying it.
2. Keep completed vectors current: identities, signed announces, opportunistic LXMF, and Link handshake.
3. Maintain the verifier suite listed in `tools/README.md`; add focused scripts for new claims instead of broad catch-all verifiers.
4. For each new `> ⚠️` or `> 🔮` callout, track the Tier 2 verifier or issue needed to resolve it.
5. Open issues for claims that cannot be verified yet and tag them `needs-verification`.
---
## 6. PR rules
## 7. PR rules
For any PR touching `SPEC.md`:
@ -156,7 +193,7 @@ For PRs adding to `test-vectors/`:
---
## 7. What to do when upstream changes
## 8. What to do when upstream changes
RNS evolves. When a future RNS version changes the wire format (or the in-source behavior cited in this spec):
@ -169,7 +206,7 @@ The goal is for this spec to be useful even when run against an RNS version a ye
---
## 8. Don't
## 9. Don't
- Don't paste large blocks of upstream code into this repo (license & churn). Cite by file + line + small inline snippet only.
- Don't add claims based purely on what some other client does. Other clients have bugs too.
@ -179,7 +216,7 @@ The goal is for this spec to be useful even when run against an RNS version a ye
---
## 9. Repo layout (current and aspirational)
## 10. Repo layout
```
reticulum-specifications/
@ -188,15 +225,17 @@ reticulum-specifications/
├── agent.md This file
├── SPEC.md Combined spec (will be split into per-layer files as it grows)
├── tools/ Verifier scripts (Python, callable against upstream RNS)
│ ├── verify_announce.py (TODO)
│ ├── verify_packet_header.py (TODO)
│ ├── verify_lxmf_roundtrip.py (TODO)
│ └── verify_link_handshake.py (TODO)
│ ├── verify_announce_roundtrip.py
│ ├── verify_packet_header.py
│ ├── verify_lxmf_opportunistic.py
│ ├── verify_link_handshake.py
│ └── ...
└── test-vectors/ Known-good byte sequences
├── README.md (TODO — describe vector format)
├── identities.json (TODO)
├── announces.json (TODO)
└── ...
├── README.md
├── identities.json
├── announces.json
├── lxmf.json
└── links.json
```
Tools are Python because Python RNS is the reference. Verifiers should be self-contained scripts that print PASS/FAIL plus a diagnostic on mismatch. Exit code 0 on PASS, non-zero on FAIL.

2
test-vectors/README.md
View file

@ -13,7 +13,7 @@ Populated against RNS 1.2.4 / LXMF 0.9.7:
All four files are byte-deterministic across runs: regenerators pin every random source (ephemeral keys, IVs, `random_hash` prefix + timestamp, LXMF timestamp) so the output is reproducible against a fixed upstream RNS / LXMF version.
See [`../agent.md`](../agent.md) §5 and [`../todo.md`](../todo.md) for the remaining bootstrap task list.
See [`../agent.md`](../agent.md) §3 and [`../todo.md`](../todo.md) for the evidence model and remaining task list.
## Format (proposed)

2
tools/README.md
View file

@ -42,4 +42,4 @@ Populated against RNS 1.2.4 / LXMF 0.9.7:
| `regen_lxmf.py` | regenerates `test-vectors/lxmf.json` (deterministic opportunistic-LXMF plaintext + Token ciphertext) | ✅ |
| `regen_links.py` | regenerates `test-vectors/links.json` (deterministic LINKREQUEST + LRPROOF + derived session key) | ✅ |
See [`../agent.md`](../agent.md) §5 and [`../todo.md`](../todo.md) for the remaining priority order.
See [`../agent.md`](../agent.md) §3 and [`../todo.md`](../todo.md) for the evidence model and remaining priority order.