From e15e8fd62e359af6014b0363a21ff493bbb170d0 Mon Sep 17 00:00:00 2001 From: John Poole Date: Mon, 8 Jun 2026 12:47:32 -0700 Subject: [PATCH] After 2nd prompt --- Codex_prompt_1.md | 3 ++ Codex_response_1.md | 109 +++++++++++++++++++++++++++++++++++++++++ README.md | 10 ++++ SPEC.md | 7 ++- agent.md | 83 ++++++++++++++++++++++--------- test-vectors/README.md | 2 +- tools/README.md | 2 +- 7 files changed, 190 insertions(+), 26 deletions(-) create mode 100644 Codex_prompt_1.md create mode 100644 Codex_response_1.md diff --git a/Codex_prompt_1.md b/Codex_prompt_1.md new file mode 100644 index 0000000..78b96e2 --- /dev/null +++ b/Codex_prompt_1.md @@ -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. \ No newline at end of file diff --git a/Codex_response_1.md b/Codex_response_1.md new file mode 100644 index 0000000..50f1375 --- /dev/null +++ b/Codex_response_1.md @@ -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 ` 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. \ No newline at end of file diff --git a/README.md b/README.md index 314753e..f83eadd 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/SPEC.md b/SPEC.md index 73f4ba3..ff471ef 100644 --- a/SPEC.md +++ b/SPEC.md @@ -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. diff --git a/agent.md b/agent.md index 895194a..b8e1e8a 100644 --- a/agent.md +++ b/agent.md @@ -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. diff --git a/test-vectors/README.md b/test-vectors/README.md index bad4cfe..1309bd2 100644 --- a/test-vectors/README.md +++ b/test-vectors/README.md @@ -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) diff --git a/tools/README.md b/tools/README.md index 73932db..aee8419 100644 --- a/tools/README.md +++ b/tools/README.md @@ -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.