archy/docs/dht-RESUME.md

DHT work — RESUME HERE

Last updated: 2026-06-16 · Branch: agent-trust-wip · Worktree: ~/Projects/archy-dht

This file is the single source of truth for resuming the DHT / peer-distribution work after a restart. Read it top to bottom, run the Verify state block, then continue at Next step.

---

⚠️ CRITICAL — where to work (do not skip)

• Work ONLY in the worktree ~/Projects/archy-dht on branch agent-trust-wip.
• NEVER run git checkout / branch-switch / commit in the shared tree ~/Projects/archy. Another agent cuts releases on main there. Git branch state is global to one working tree, so a checkout in the shared tree drags every session onto that branch and can clobber uncommitted work. That already happened once — the worktree exists specifically to prevent it. See memory feedback_concurrent_agent_tree.
• The shared tree stays on main for the release agent. Leave it alone.

Build facts (so you don't get surprised)

• It's a binary crate: test with cargo test --bin archipelago -- <filter> (there is no lib target).
• The test profile is opt-level=3 → every incremental test rebuild of the archipelago crate is ~5 min; a cold build of the iroh feature tree is ~19 min. Budget for it. Run builds in the background and poll.
• Default build = no iroh. The iroh swarm engine is behind the iroh-swarm Cargo feature (off by default): cargo build --features iroh-swarm.
• Plain cargo build (no feature) is the fleet build and is unaffected by any DHT work.

Verify state (run these first on resume)

cd ~/Projects/archy-dht
git branch --show-current            # → agent-trust-wip
git log --oneline -7                 # see the commit list below
git status --short                   # should be clean (or your in-progress edits)
git worktree list                    # archy-dht → agent-trust-wip; archy → main
# sanity compile (default, fast-ish):
cargo build --bin archipelago 2>&1 | tail -3

---

What is DONE (committed on agent-trust-wip)

Design doc: docs/dht-distribution-design.md (the full plan).

Commit	Phase	Summary
0fef8086	base	parked trust module + seed::derive_release_root_ed25519 (pre-existing)
27f11bf8	0	signed-catalog authenticity wired: trust/ module verifies the release-root detached signature in app_catalog::fetch_one; release-root KAT pinned
f0cb91ed	1	BLAKE3 alongside SHA-256: content_hash.rs, ComponentUpdate.blake3, BlobMeta.blake3
2523c9e3	2 seam	swarm/mod.rs — BlobProvider + fetch_content_addressed (verify peer bytes, origin-always-wins); iroh-swarm flag; wired into update.rs
082946aa	2 engine	real swarm/iroh_provider.rs over iroh 1.0 + iroh-blobs 0.103 (optional deps). Dep tree proven to resolve+compile against the pinned stack
9fa56a82	3 core	swarm/seed_advert.rs — signed Nostr seed-advertisement protocol (NIP-33 kind 30081, d-tag=blake3)

All tests green at each step. Total new modules: trust/, content_hash.rs, swarm/.

task #12 — Phase 3 glue + wiring — DONE (2026-06-17, NOT yet committed)

Implemented in the worktree, uncommitted (release in flight — do not commit/merge until the user says so). Verified: default cargo build clean, cargo build --features iroh-swarm clean, cargo test --bin archipelago -- swarm:: → 8/8 pass.

1. NostrSeedDiscovery (swarm/iroh_provider.rs) — ProviderDiscovery made async (#[async_trait]); impl queries relays via the new seed_advert::fetch_seed_endpoint_ids and parses each string with EndpointId::from_str (EndpointId = PublicKey, has FromStr/Display), skipping unparseable. try_fetch now .awaits discovery.
2. Publish path — dep-free seed_advert::fetch_seed_endpoint_ids + publish_seed_advert (reuse now-pub(crate) build_nostr_client / load_or_create_nostr_keys); IrohProvider::seed_and_advertise imports the blob into the FsStore (blobs().add_path → TagInfo) with a defensive hash-match, then publishes. Scope: releases/catalog only.
3. Wiring — swarm::init() builds the IrohProvider once at startup into a OnceLock<SwarmRuntime> (keeps endpoint/router alive → keeps seeding); providers() returns the registered provider; announce_held_blob() is called from update.rs after each release component passes both hash gates. New config swarm_enabled (ARCHIPELAGO_SWARM_ENABLED, default false); server.rs calls swarm::init. All iroh code stays behind iroh-swarm; default build inert.

iroh-blobs paid-serving spike (open Q#1) — RESOLVED: BlobsProtocol::new(&store, Some(EventSender)) + EventMask intercept gives native per-request allow/deny (RequestMode::Intercept → Result<(), AbortReason>), connection-level reject (ConnectMode::Intercept), and per-request throttle/meter (ThrottleMode::Intercept).

NEW: Phase 4+ plan (paid streaming / relay / IndeeHub) — docs/phase4-streaming-ecash-plan.md

Design for: (1) ecash-paid swarm transport, (2) networking through nodes / relay, (3) IndeeHub "Archipelago" content source (signed Nostr film catalog, kind 30082). Headline: ~80% already exists (Cashu wallet, streaming/ payment gate + metering, 4-tier transport, the swarm above). Also shipped this session: a Networking Profits → Settings UI in neode-ui (new views/web5/Web5NetworkingProfitsSettings.vue + route + button in Web5QuickActions.vue + common.settings i18n) that drives the existing streaming.list-services/configure-service RPCs; free-everything is the default (all services ship enabled:false). Frontend typechecks clean (pre-existing Web5ConnectedNodes.vue .did errors are NOT ours). neode-ui deps were npm installed to complete a partial install.

After Phase 3

• Phase 4 — IndeeHub films on the same blob layer (Blossom catalog + iroh swarm; MinIO origin). Each HLS .ts segment = a content-addressed blob.
• Phase 0 GO-LIVE (needs the user) — the catalog/manifest signature anchor trust::anchor::RELEASE_ROOT_PUBKEY_HEX is still None; the pinned KAT is the TEST mnemonic, not the real key. Going live = signing ceremony with the real release master seed (only the user has it) → derive release-root → bake its pubkey into anchor.rs → sign the real releases/app-catalog.json. Until then verification is advisory (verify-if-present, anchor not enforced).

Mergeability

As of last check we were only ~4 commits diverged from main; the only shared-file overlap is seed.rs + update.rs. Do NOT merge to main while the release is in flight — that's the user's call. Sync (merge main → agent-trust-wip) once the release lands and main is clean.

Background build logs from the last session (may be stale)

/tmp/dht-*.log — phase test/build outputs. Safe to ignore/delete on resume.