InterWeave

InterWeave is a generic peer-to-peer transport architecture for Claude Code Channels and first-party human clients. It combines payload-agnostic transport contracts, one-PeerId/many-EndpointId local routing, signed GossipSub broadcast, dedicated directed messaging, replaceable discovery, Kademlia peer routing, and mandatory Internet reachability through AutoNAT v2, Circuit Relay v2, and DCUtR.

Repository status: accepted architecture, Stages 0-10 complete, Stage 11 open for its spike only (stage-11-connectivity; SPIKE-004 has not run, so no AutoNAT/Relay/DCUtR package may be created yet). The design is under architecture/. Read [workspace].members in Cargo.toml for the active roster rather than a list written here; the crates/api/* contracts are types and validation only, no I/O and no backend. Stage 3 landed the first file I/O — the human store, the peer cache, the profile path layout, and the Ed25519 identity. Stage 4 added the authenticated transport substrate: TCP, Noise, Yamux and Identify, with every other libp2p behaviour left uncompiled. Stage 5 built the root connection and dial-admission funnel that every outbound dial passes through — no Kademlia, AutoNAT, Relay or DCUtR may be activated until it is green, because retrofitting admission policy under an autonomous behaviour is the one ordering the architecture refuses. Stage 6 carried /interweave/direct/2.0.0 end to end between real peers: frozen framing, endpoint routing, dedup and in-flight reservations, and per-peer and global ingress limits, routed to an in-process LocalDataSession with no IPC and no UI. Stage 7 carried signed GossipSub broadcast end to end between real peers under tests/pubsub — strict validation, the frozen mesh message identity, ChannelId-derived topics and the ADR-0029 verdict mapping — and broadcast and direct remain independently functional, neither substituting for the other. Stage 8 carried the endpoint directory, /interweave/endpoints/1.0.0, end to end between real peers: a trusted peer learns another's active, advertised, admissible routes, trust-gated and bounded, with the directory-response shape now active. It closed the obligation inherited from Stage 6 by binding a direct send's source endpoint to the caller's lease as an unforgeable capability — the EndpointLease claim_endpoint returns, its epoch verified against the live lease — so a caller sends only as an endpoint it claimed. It activated no new package; the protocol landed in crates/transport/libp2p. Stage 9 built the discovery framework excluding Kademlia and activated the first new packages since Stage 3 — crates/discovery/{static,cache,mdns}: three providers passing one shared conformance suite that is itself checked against a deliberately misbehaving provider, composed by a pure DiscoveryManager, with the exit gate proved over real sockets — a perfectly good discovered candidate for a reachable listener is neither remembered nor dialable by a node that does not trust it, against a positive control that connects. Its Met. block records what the stage did NOT prove: the mDNS multicast mechanism was never built, because enabling libp2p's mdns feature pulls a dependency carrying two RUSTSEC advisories with no upgrade available, so that crate ships its normalization half only and LAN discovery remains unproven. Stage 10 closed Kademlia, activating crates/api/kademlia-control-api and crates/discovery/kademlia with the Swarm-owned driver in crates/transport/libp2p. SPIKE-003's seventeen findings bound the work, the first being that the feature could not simply be switched on — every Kademlia query dial is behaviour-originated and the root gate refused every one until it learned to admit them under DialOrigin::KademliaQuery. Closing it amended its own exit gate: the first clause bundled a build capability with a shipping decision — "supports Kademlia and configured entries default on" — and no test in the stage could reach the second half, so the gate was one the stage could never pass. Shipping configured entries default-enabled now sits where the decision lives, ADR-0034's v1 release gate, blocked on Stage 12 composition and on SPIKE-004. Closing the stage cleared neither. The block also records that tests/kademlia/tests/overlay_health.rs is the only place the control port's two halves have ever run against each other, and what that test does not prove. apps/ and packaging/ are still empty of implementation; spikes/ holds evidence harnesses for SPIKE-002, SPIKE-003 and SPIKE-006.

What InterWeave is

InterWeave defines the transport and local-client boundary needed for multiple local applications to share one persistent peer identity without conflating routing with identity.

Desktop/server

  human-desktop -- data IPC --\
  claude-channel -- data IPC ---+--> interweave-transportd --> TransportRuntime --> libp2p
                                |         one PeerId
  settings/admin -- admin IPC --/         many EndpointIds

Android

  Slint UI --> LocalDataSession --> foreground Service --> TransportRuntime --> libp2p
                                   (same contracts, embedded deployment)

Network

  broadcast      -> signed GossipSub
  directed       -> /interweave/direct/2.0.0
  endpoint query -> /interweave/endpoints/1.0.0
  peer routing   -> private InterWeave Kademlia namespace
  reachability   -> AutoNAT v2 + Circuit Relay v2 + DCUtR

InterWeave is deliberately not an agent coordination framework, task protocol, Git workflow, social graph, human-identity system, read-receipt service, or durable transport mailbox. Higher layers may define those concepts without pushing them into the transport.

Core invariants

• One configured transport profile owns one persistent PeerId.
• Model B adds configured EndpointIds beneath that PeerId (human, claude, automation.build, ...). EndpointId is routing metadata, not an identity or authorization principal.
• Broadcast uses GossipSub only. Directed traffic uses the dedicated direct protocol and is never tunneled through GossipSub.
• Direct v2 routes to exactly one endpoint. Omitted destination resolves the receiver's configured default endpoint; it never means fan-out.
• AcceptedV2 means the remote endpoint's bounded local queue admitted the message. It does not mean a human or Claude processed/read it.
• Discovery is advisory and replaceable. It never grants trust.
• Data-plane trust is deny-by-default and PeerId-scoped; endpoint policy may narrow trust but never widen it.
• Kademlia is peer-routing only: no endpoint, channel, trust, membership, or application records.
• Root connection/dial admission exists before autonomous libp2p behaviours are activated.
• Standard v1 includes AutoNAT v2 client, Circuit Relay v2 client/reservations, and DCUtR.
• TransportRuntime never provides a durable offline mailbox.
• First-party human-client persistence is intentionally narrow: pending outbound, unread inbound, and inbound messages explicitly kept by the receiver after reading.

The accepted details live in the contracts and ADRs; this README is an orientation document, not a substitute for them.

Repository layout

Path	Role
architecture/	Normative ADRs, contracts, architecture, research, configuration schema/examples, and roadmap
apps/	Future thin executable/platform composition roots
crates/	Future reusable Rust crate boundaries
tests/	Cross-crate, conformance, real-network, security, desktop E2E, and Android E2E suites
fixtures/	Frozen normative protocol/crypto/config vectors
test-data/	Mutable non-normative scenario data
spikes/	Empirical implementation investigations; never production dependencies
packaging/	Future Linux/macOS/Windows/Android packaging
xtask/	Repository/test orchestration — cargo xtask checks / cargo xtask ci
tools/	Repository tooling — PR/review scripts and tree checks, each with a self-test beside it
.claude/	Committed agent configuration and task-scoped skills; per-developer overrides stay untracked
IMPLEMENTATION.md	Implementation landing-zone and activation rules

The root Cargo.toml is a virtual workspace, and [workspace].members is the authoritative list. It is deliberately not repeated here: the paragraph that used to name the members "for orientation" went stale across two stages while the manifest stayed correct, so the orientation it offered was a wrong one. workspace.metadata.interweave records the remaining planned members without making them buildable, and .status records the open stage. A crate/package is added only when its canonical implementation stage begins.

Canonical implementation order

The governing construction order is architecture/roadmap/BOTTOM-UP-IMPLEMENTATION-PLAN.md, adopted by ADR-0046.

The historical numbered phases remain scope/release labels. They are not permission to violate dependency order.

Stage 0   foundation + frozen fixtures
Stage 1   neutral contracts + config
Stage 2   pure policies/state machines
Stage 3   persistence
Stage 4   minimal authenticated libp2p substrate
Stage 5   root ConnectionManager/DialAdmissionGate + pre-auth limits
Stage 6   direct v2
Stage 7   GossipSub
Stage 8   endpoint directory
Stage 9   discovery framework
Stage 10  Kademlia
Stage 11  AutoNAT + Relay + DCUtR
Stage 12  TransportRuntime integration
Stage 13  daemon + IPC
Stage 14  human application core/UI
Stage 15  desktop human client
Stage 16  Claude Channel bridge
Stage 17  Android
Stage 18  adversarial/security gate
Stage 19  packaging/release

In particular, Kademlia, AutoNAT, Relay, and DCUtR may not be activated before Stage 5's root dial/security funnel is implemented and green.

Human message retention

The first-party human client is ephemeral by default. The durable store is not a conventional permanent conversation-history database.

Message state	Durable local state
Outgoing, pending/undelivered	Yes
Outgoing, transport-terminal	No
Incoming, unread	Yes
Incoming, read and not kept	No
Incoming, read and explicitly kept by receiver	Yes

The receiver-only Keep action is local application state; a remote sender cannot request or force persistence. See architecture/clients/human/RETENTION.md and ADR-0044.

Project and wire namespace

ADR-0047 freezes:

Display name:       InterWeave
Machine namespace:  interweave
Direct protocol:    /interweave/direct/2.0.0
Endpoint protocol:  /interweave/endpoints/1.0.0
Kademlia prefix:    /interweave/kad/1.0.0/<network-hash>
HumanChat media:    application/vnd.interweave-human-chat+json;v=2

Claude-specific names such as claude-channel remain integration names and are not project branding.

Start here

For a first architecture pass, read in this order:

1. architecture/docs/architecture/overview.md
2. architecture/docs/architecture/components.md
3. architecture/contracts/TRANSPORT.md
4. architecture/contracts/ENDPOINTS.md
5. architecture/contracts/LOCAL-CLIENT.md
6. architecture/contracts/CONNECTIVITY.md
7. architecture/contracts/DISCOVERY.md
8. architecture/docs/architecture/threat-model.md
9. architecture/adr/README.md
10. architecture/roadmap/BOTTOM-UP-IMPLEMENTATION-PLAN.md

Useful focused documents:

• Human cross-platform design: architecture/docs/architecture/human-client-cross-platform.md
• Desktop human client: architecture/docs/architecture/human-client-desktop.md
• Android human client: architecture/docs/architecture/human-client-android.md
• Android key custody: architecture/docs/architecture/android-key-custody.md
• Mandatory Internet reachability: architecture/transport/libp2p/CONNECTIVITY.md
• Kademlia design: architecture/discovery/KademliaDiscovery.md
• Security review: architecture/docs/architecture/SECURITY-REVIEW-2026-08-12.md
• Human/mobile review: architecture/docs/architecture/HUMAN-CLIENT-REVIEW-2026-08-12.md
• Retention amendment review: architecture/docs/architecture/MESSAGE-RETENTION-REVIEW-2026-08-12.md

Development policy

Implementation is under way, one canonical bottom-up stage at a time; [workspace].members in Cargo.toml is the authoritative roster and workspace.metadata.interweave.status records the open stage. Contributors and coding agents should follow CLAUDE.md and IMPLEMENTATION.md.

In every stage:

• activate only the package(s) required by the current canonical stage;
• keep application binaries as thin composition roots;
• keep neutral API crates free of libp2p, Slint, Android, SQLite, and Claude-specific dependencies;
• place tests at the lowest layer that completely proves the behavior;
• use real Swarms/processes/platform tests where the contract depends on real integration behavior rather than replacing them with mocks;
• keep frozen vectors in fixtures/ and mutable scenarios in test-data/;
• preserve architecture decisions by amending the relevant ADR/contract before intentionally diverging in code.

Cargo.lock is intentionally tracked for this application/workspace repository.

Security

Do not commit private transport identities, recovery phrases, Android signing material, Keystore exports, local profile state, or real credentials. The .gitignore is a guardrail, not a secret-management boundary.

Security-sensitive implementation changes should be checked against the threat model, resource limits, security review, and the permanent tests/security/ landing zone. Discovery, trust, connection admission, endpoint routing, and connectivity-infrastructure authorization are intentionally separate boundaries.

License

InterWeave first-party code and documentation are licensed under the Apache License, Version 2.0 (Apache-2.0). See LICENSE.

Third-party dependencies, copied fixtures, generated artifacts, and externally sourced material retain their own applicable licenses and notices; adding them to this repository does not relicense them as InterWeave code.