Merge pull request #365 from Offline-Protocol/docs/restructure-spec-threat-model-adrs

docs: replace the CLAUDE.md memory dump with a spec, threat model, ADRs and bridge contracts

Author: bahdotsh

CHANGELOG.md

@@ -213,6 +213,20 @@ See the [docs/](docs/) directory for detailed guides:
 - [Telemetry](docs/telemetry.md)
 - [iOS Integration](docs/ios-integration.md) / [Android Integration](docs/android-integration.md)
 
+Reference material for anyone implementing against the protocol or changing its
+behaviour:
+
+- [Protocol Specification](docs/spec/README.md), the wire and behaviour contract,
+  independent of this implementation
+- [Threat Model](docs/security/threat-model.md), including the residual risks
+  stated plainly
+- [State Machines](docs/state-machines/README.md) for delivery, retries,
+  sessions, groups, and transports
+- [Architecture Decision Records](docs/adr/README.md), why the non-obvious
+  choices are what they are
+- [Bridge Contracts](docs/bridges/README.md) for Swift, Kotlin, Python, and
+  TypeScript
+
 ## Development
 
 ```bash

CLAUDE.md

@@ -116,7 +116,7 @@ object MeshWakePolicy {
      * A drift here fails silently in the worst way: React Native logs "No task
      * registered for key" to the device log and resolves nothing, the app sees
      * an opt-in that does nothing, and both sides still compile. Pinned by
-     * `react_native_mesh_wake_task_key_matches_native` in the uniffi crate.
+     * `react_native_mesh_wake_wiring_is_present` in the uniffi crate.
      */
     const val TASK_KEY = "OfflineProtocolMeshWake"
 

README.md

@@ -67,7 +67,7 @@ export const ONE_SHOT_EVENT_TYPES = [
  * silently and in the worst possible way — React Native logs "No task
  * registered for key" to the device log, the app sees an opt-in that does
  * nothing, and both sides still compile — so it is pinned by a Rust guard
- * (`react_native_mesh_wake_task_key_matches_native` in
+ * (`react_native_mesh_wake_wiring_is_present` in
  * `crates/offline-protocol-uniffi`).
  */
 export const MESH_WAKE_TASK_KEY = 'OfflineProtocolMeshWake';

bindings/react-native/android/src/main/java/com/offlineprotocol/MeshWakePolicy.kt

@@ -93,9 +93,18 @@ pub enum AddressError {
 /// The two orders differ: the bech32 charset (`qpzry9x8gf2tvdw0s3jn54khce6mua7l`)
 /// is not monotonic in ASCII — value 4 renders as `y` (0x79) and value 5 as
 /// `9` (0x39) — and a string comparison would also weigh the checksum
-/// characters. Protocol tiebreakers (both-create session ownership, leave
-/// election, admin auto-promotion, fork leader) must therefore compare
-/// `Address` values, never their `Display` output.
+/// characters.
+///
+/// **Which order a tiebreaker uses is fixed per site, and the sites disagree.**
+/// Both-create session ownership compares `Address` values (hash bytes); group
+/// leave election, admin auto-promotion and fork leader election sort rendered
+/// strings. Each converges on its own, because every peer running that
+/// tiebreaker sorts the same way.
+///
+/// Do not "harmonize" one site onto the other order. Peers that changed and
+/// peers that did not would then elect different winners from identical input,
+/// with no way to detect the disagreement locally. Prefer hash-byte order for
+/// anything new. See `docs/adr/0003-self-certifying-addresses.md`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Address {
     hash: [u8; Address::HASH_LEN],

bindings/react-native/src/constants.ts

@@ -868,7 +868,7 @@ impl TransportSelector {
         //
         // The Internet baseline intentionally exceeds the 0–100 range of
         // offline transports so that the gap comfortably exceeds the default
-        // switch hysteresis (10). Increasing hysteresis beyond ~20 may
+        // switch hysteresis (15.0). Increasing hysteresis beyond ~20 may
         // prevent DORS from switching *to* Internet even when prefer_online
         // is set.
         //

crates/offline-protocol-core/src/address.rs

@@ -839,7 +839,8 @@ pub(crate) struct PendingGroupMessage {
     pub(crate) buffered_at: Instant,
     /// Transport the frame arrived on, recorded so the drain can send the
     /// deferred delivery ACK directly on it once the message finally decrypts
-    /// (see the deferred-ACK atom in CLAUDE.md). `None` for the relay path
+    /// (see the deferred-acknowledgement atom in
+    /// `docs/state-machines/delivery-and-acks.md`). `None` for the relay path
     /// (the relay sender is not ACK-gated) and for transport-less test enqueue
     /// — in both cases the drain ACK is a correct no-op.
     pub(crate) received_via: Option<TransportType>,

crates/offline-protocol-router/src/dors.rs

@@ -22,8 +22,10 @@ pub(crate) struct PendingDecryptMessage {
     pub(crate) sequence: u64,
     pub(crate) message: Message,
     /// Transport the frame arrived on, when the caller knew it. Recorded so the
-    /// drain can send the deferred delivery ACK directly (see the deferred-ACK
-    /// design in CLAUDE.md) instead of waiting for the sender's next resend to
+    /// drain can send the deferred delivery ACK directly (see the
+    /// deferred-acknowledgement atom in
+    /// `docs/state-machines/delivery-and-acks.md`) instead of waiting for the
+    /// sender's next resend to
     /// hit the duplicate re-ACK path. `None` when the message was enqueued from
     /// a context with no transport (tests, or a re-queue by the handler during a
     /// drain, which re-processes with no live arrival transport) — the drain

crates/offline-protocol/src/group_mesh.rs

@@ -27,8 +27,8 @@ impl OfflineProtocol {
     /// [`Self::enqueue_pending_decryption`] with the transport the frame arrived
     /// on, when the caller knows it. The transport is recorded on the pending
     /// entry so the drain can send the deferred delivery ACK directly instead of
-    /// relying on the sender's next resend (see the deferred-ACK design in
-    /// CLAUDE.md).
+    /// relying on the sender's next resend (see the deferred-acknowledgement
+    /// atom in `docs/state-machines/delivery-and-acks.md`).
     pub(super) fn enqueue_pending_decryption_via(
         &mut self,
         sender: &str,