Skip to content

refactor: split routing authority - #665

Merged
lthibault merged 1 commit into
masterfrom
arch13-routing-regression-docs
Aug 25, 2026
Merged

refactor: split routing authority#665
lthibault merged 1 commit into
masterfrom
arch13-routing-regression-docs

Conversation

@lthibault

Copy link
Copy Markdown
Contributor

Summary

ARCH-13 intentionally replaces the broad guest-visible Routing capability during the alpha stage. The old interface and routing graft are deleted outright. No compatibility adapter remains.

The new authority surface has two independently grantable Cap'n Proto capabilities:

  • routing::Finder grants bounded provider discovery through findProviders.
  • routing::Announcer grants authority to announce the Wetware host PeerID through provide.

Pure canonical routing-key derivation is separate from object-capability authority. Guests can opt into wetware:routing/key@0.1.0, whose host implementation derives CIDv1/raw/BLAKE3 routing keys.

Authority and lifecycle

Finder applies the following host contract:

  • count == 0 returns no peers and launches no query.
  • Each query returns at most min(count, 16) unique providers.
  • WAN and LAN results are deduplicated by PeerID.
  • Internal retention, address-resolution fan-out, and guest delivery use fixed bounds.
  • Sink closure, stale Cell epochs, and the 30-second deadline cancel remaining host work.
  • The deadline starts before swarm-command admission.
  • Cancellation does not depend on capacity in the shared SwarmCommand channel.

Announcer binds every provider assertion to the Wetware host PeerID and the granting Cell epoch. Duplicate claims from one owner are idempotent. Multiple epochs can own one CID. Final-owner teardown calls stop_providing on both libp2p Kademlia behaviours, which removes the local source for future republication. Previously propagated remote records expire naturally.

Breaking removals

This PR removes the broad Routing interface, the routing graft, Routing.hash, guest IPNS resolution and publication, persistent MFS authoring, caller-selected Kubo publication keys, and guest reprovide loops.

Host Phase 3-IPNS resolution and publication remain unchanged. This PR does not add a guest publisher, resolver, content workspace, or compatibility layer.

Finder and Announcer use fresh interface IDs. Regression tests pin both IDs and prove that raw calls using the removed Routing ID 0xa7c3e8f1d4b29065 are rejected by each new capability.

First-party migration

  • The Oracle provider receives Announcer only; the Oracle consumer receives Finder only.
  • Chess and Discovery receive explicit Finder and Announcer grants plus the optional routing-key import.
  • Authority probes grant Finder and Announcer independently.
  • Trusted PID0 uses independent routing-finder and routing-announcer grafts.
  • Ordinary children receive only explicitly delegated references.

No convenience object recombines Finder and Announcer.

Validation

The following checks passed:

  • cargo fmt --all -- --check
  • cargo check --workspace --all-targets
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace --no-fail-fast
  • git diff --check
  • cargo test -p rpc routing::tests::legacy_routing_interface_id_is_rejected_by_new_capabilities --no-default-features -- --exact
  • cargo test -p wetware-authority wire_type_id_tests::split_schema_type_ids_are_pinned_for_wire_compat -- --exact
  • WASIP2 builds for the routing-key wrapper and migrated first-party guests
  • make std
  • generated ww init scaffold WASIP2 build
  • cargo package -p routing-key --allow-dirty
  • architecture-map generation and validation

The full workspace suite included RPC, provider lifecycle, authority confinement, Cell, Membrane, 13 PID0 end-to-end, and Kademlia/IPFS/IPNS interoperability tests. Kademlia integration used an isolated disposable Kubo instance, which was removed after validation.

@lthibault
lthibault merged commit d1c597e into master Aug 25, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant