@steve02081504/fount-p2p 0.0.31 → 0.0.33

package/AGENTS.md

@@ -0,0 +1,79 @@
+# P2P / Federation / Entity Files Guide
+
+## Package layers (`@steve02081504/fount-p2p`)
+
+| Layer | Directory | Role |
+|---|---|---|
+| L0 | `core/` | IDs, logical entity, canonical JSON, bytes |
+| L1 | `crypto/`, `wire/`, `schemas/` | Crypto, wire ingress, canonical validation |
+| L2 | `node/` | `initNode`, identity, entity store, denylist, reputation, storage plugins |
+| L3 | `discovery/`, `link/`, `transport/` | fount network (registry/rooms); `registerLinkProvider` via `./link` or facade |
+| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/`, `governance/`, `reputation/` | Federation, store-and-forward, DAG, EVFS, tunables |
+
+**Outside the package** (shell / frontend; p2p must not import): chat/social semantics, mention rendering, entity identity provisioning, etc. Standalone clients: `import { startNode } from '@steve02081504/fount-p2p'`.
+
+**Facade:** `index.mjs`; subpath exports mirror directories.
+
+Detail docs: [transports](docs/transports.md) · [mesh](docs/mesh.md) · [signaling](docs/signaling.md) · [runtime](docs/runtime.md) · [infra](docs/infra.md) · [wire](docs/wire.md) · [evfs](docs/evfs.md) · [reputation](docs/reputation.md)
+
+### Runtime: isomorphic vs Node
+
+| Surface | Runtime | Notes |
+|---|---|---|
+| `core/*` | Node + browser | No `node:*` builtins |
+| `crypto/crypto.mjs` | Node + browser | `@noble/hashes` + `@noble/curves` only — never `node:crypto` |
+| `crypto/key.mjs` / `crypto/channel.mjs`, disk I/O, LAN/BT, `ws`, CLI / `startNode` | Node (+ Deno bridge) | Do not load the whole package via esm.sh in the browser |
+
+Deno / native / BT: [runtime.md](docs/runtime.md).
+
+## Conventions
+
+- Prefer shared helpers under `utils/`, `core/`, `wire/subscribe`, `wire/adapter` — do not reimplement LRU/TTL/inflight/atomic-fs/shuffle.
+- **No pure-forward aliases:** do not add `fooText`/`fooAlias` that only `return foo(sameArgs)` when the callee already accepts those types (e.g. never wrap `sha256Hex` as `sha256TextHex`). Domain names must add logic or type narrowing, not just rename.
+- **Heterogeneous backends:** normalize at the load boundary (e.g. `link/rtc/ice_local_hostname.mjs` wraps W3C RTC backends); call sites speak one contract.
+- **File naming:** parent directory is scope — short child names. Tunables default `<dir>/tunables.json` (exception: `schemas/part_query.tunables.json`). Subpath `package.json` exports mirror filenames.
+- **Import boundary:** `test/integration/p2p_shell_import_guard.test.mjs`.
+- **No scattered `trim` / `toLowerCase`:** hex IDs must already be lowercase; `normalizeHex64` strips an optional `0x` only — mixed case / whitespace is rejected. Exceptions: JSONL blank lines, SDP fingerprint, CLI/`scripts` parsing.
+- **No `String(x)` / `x || ''` on typed `string`:** if `@param {string}`, use it directly; `String(...)` / `|| ''` / `?? ''` only at optional / `unknown` / disk / inbound boundaries, or number→string.
+- **Optional methods:** `if (fn) return await fn(...)` / `if (fn) …` — never `typeof x === 'function'`.
+
+## Tests / tools
+
+- `npm test` — pure + integration (Node; `--test-force-exit`)
+- `npm run test:live` — live link / LAN smoke
+- `npm run test:fount` — cross-repo Deno bridge (`test/fount/`); see [runtime.md](docs/runtime.md)
+- `npm run test:sim` — tunables co-evolution (dev-only; [sim/AGENTS.md](sim/AGENTS.md))
+- `node scripts/check-imports.mjs` — relative import check
+- `node scripts/find-unused-exports.mjs` — dead-export scan (`--fount <path>` optional)
+- Assertions: `test/helpers/assert.mjs`
+- Fixed-seed identity: `test/helpers/identity.mjs`
+- Mock discovery: `test/helpers/mock_discovery.mjs`
+
+## Hard rules
+
+### Trust / ingress
+
+- **Untrusted ingress only:** discovery adverts/signals, link/overlay envelopes, group federation frames, `remoteIngest`, `part_timeline_*` / `part_invoke`, `part_query_*`, public manifest (`fed_manifest_data`). Validate / `canonicalize*` / `verifySignedPublicManifest` **only** here.
+- **Trusted after disk:** from `events.jsonl`, only `stripDagEventLocalExtensions` — no re-canonicalization upstream.
+- **Fanout vs targeted / timed collect:** [wire.md](docs/wire.md).
+- **Channel encryption:** per-channel `K_ch`, scheme `channel-key` (`CHANNEL_KEY_SCHEME`); decrypted payloads are untrusted outside DAG Ed25519 context.
+- **Denylist vs personal lists:** node `denylist.json` vs per-entity `personal_block.json` / `personal_hide.json`.
+- **Manifest ACL / transfer owner:** shells register matchers; core does not hard-code chat/social types.
+
+### Node / network
+
+- **Node data:** `initNode({ nodeDir, entityStore? })` — `node.json`, `network.json`, `denylist.json`, `reputation.json`, `mailbox/`, `chunks/`. Default EntityStore: `{nodeDir}/entities/`. No `FOUNT_*` env knobs — subprocess IPC uses argv.
+- **fount network:** shells use `startNode` / `ensureLinkToNode` / `sendToNodeLink` / rooms — never import `link/` internals or pick a transport. Providers: `registerLinkProvider` from `./link` or facade.
+- **Link `level` vs discovery `priority`:** descending `level` picks data transport (`nostr` = −∞ last resort); ascending `priority` orders handshake/presence media only. [transports.md](docs/transports.md)
+- **Mesh first / no versioning:** ≥N links (K acquaintances + N−K explore); discovery API is `listVisibleNodeHashes` + `connectToNode` only; no topic on the fount-network surface; no version/compat fields. [mesh.md](docs/mesh.md)
+- **Room / registry:** `configureLinkRegistry(opts)` before first `getLinkRegistry`. `startNode` does not take registry options. `createGroupLinkSet` is the kernel; `createScopedLinkRoom` is a dial-all preset. Rooms call `registry.ensureRuntime()` before subscribe/advertise — [runtime.md](docs/runtime.md)
+- **Fetch ≠ apply:** `ingestEncryptedAdvert` vs `noteAdvertPeerHints`; reputation pull never writes — [reputation.md](docs/reputation.md). Public-manifest cache/fanout: [evfs.md](docs/evfs.md). Node-scope attaches: [infra.md](docs/infra.md).
+
+## Tunables JSON
+
+| File | Directory |
+|---|---|
+| `tunables.json` | `reputation/`, `trust_graph/`, `mailbox/`, `governance/`, `dag/` |
+| `part_query.tunables.json` | `schemas/` |
+
+Sim harness: `sim/tunables_bundle.mjs` (dev-only). See [sim/AGENTS.md](sim/AGENTS.md).

package/README.md

@@ -88,7 +88,7 @@ Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscovery
 | `user_room.mjs` / `group_link_set.mjs` / `node_scope/wire` + `node_scope/features` | rooms + composable node-scope wires (`registerNodeScopeWireHook`, attaches) |
 | `room_scopes.mjs` / `remote_user_room.mjs` | scope constants / remote user slot |
 
-`runtime_bootstrap`, `offer_answer` are **internal** (transport). Signal crypto / rendezvous live under `discovery/internal/signal_crypto.mjs` (used by discovery `nostr.mjs` / `adverts.mjs`; not a package export). The Nostr **link** provider (`link/providers/nostr.mjs`) reuses the same discovery signal path (`type: 'link'`) as a last-resort duplex pipe. `ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. `setSignalingRuntimeConfig` → `reloadDiscoveryRelays`. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
+`runtime_bootstrap`, `offer_answer` are **internal** (transport). Signal crypto / rendezvous live under `discovery/internal/signal_crypto.mjs` (used by discovery `nostr.mjs` / `adverts.mjs`; not a package export). The Nostr **link** provider (`link/providers/nostr.mjs`) reuses the same discovery signal path (`type: 'link'`) as a last-resort duplex pipe. `ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. Call `ensureChannelAvailable('bt')` to await BT discovery readiness. `setSignalingRuntimeConfig` → `reloadDiscoveryRelays`. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
 
 Root contains only the facade and package metadata; all modules live in layered subdirectories.
 

package/discovery/nostr.mjs

@@ -6,6 +6,8 @@ import WebSocket from 'ws'
 import { base64ToBytes, hexToBytes, bytesToBase64, bytesToHex } from '../core/bytes_codec.mjs'
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
 import { sha256Hex } from '../crypto/crypto.mjs'
+import { getNodeTransportSettings } from '../node/identity.mjs'
+import { getSignalingRuntimeConfig } from '../node/instance.mjs'
 import { nodeDebug, shortHash } from '../node/log.mjs'
 
 import { noteAdvertPeerHints } from './advert_peer_hints.mjs'
@@ -200,6 +202,15 @@ export function mergeSignalingRelayUrls(userRelayUrls) {
 	return merged.length ? merged : [...DEFAULT_RELAY_URLS]
 }
 
+/**
+ * 当前可用 nostr 中继：nostr 通道配置 relay（替换默认），否则节点默认 + 公共中继。
+ * @returns {string[]} relay URL 列表
+ */
+export function resolveNostrRelayUrls() {
+	const relay = getSignalingRuntimeConfig().channels?.nostr?.relay
+	return relay?.length ? relay : mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls)
+}
+
 /**
  * @param {number} kind 事件 kind
  * @param {string[][]} tags 事件标签

package/docs/evfs.md

@@ -0,0 +1,32 @@
+# EVFS public manifests & fetch
+
+Day-to-day package rules: [AGENTS.md](../AGENTS.md). Implementation: `files/` (`evfs`, `evfs_ref`, `chunk/*`, `manifest/*`).
+
+## Storage
+
+| What | Path |
+| --- | --- |
+| Ciphertext chunks (CAS) | `{nodeDir}/chunks/` |
+| Manifests | `{EntityStoreRoot}/{entityHash}/files/{path}.manifest.json` |
+
+## Public publish / verify
+
+- `publishPublicFile` signs with the recovery key.
+- Remote path: `fed_manifest_get` → `verifySignedPublicManifest` → cache.
+- Signature covers **content fields only**. After verify, drop incoming `meta` except `publicSig`.
+- Profile / avatar meaning belongs in the shell — not in this package.
+
+## `fetchPublicManifest`
+
+| Case | Behavior |
+| --- | --- |
+| Default options | No cache write |
+| Local hit with `publicSig` | Return immediately; fanout revalidates in the background. With `cache: true`, write only when remote `publishedAt` is newer |
+| Cold miss | Await fanout |
+| Same key in flight | Deduped via `utils/inflight_table` |
+
+Outer caller timeouts must **not** abort the in-flight work — background fill continues after the caller gives up.
+
+## ACL
+
+Shells register matchers via the ACL registry. Core does not hard-code chat/social entity types.

package/docs/infra.md

@@ -0,0 +1,25 @@
+# Infra relay & node-scope attaches
+
+Optional public-good overlay + mailbox. Day-to-day rules: [AGENTS.md](../AGENTS.md). Wire part attaches: [wire.md](wire.md).
+
+## `startInfra` / `stopInfra`
+
+Call after `initNode`. CLI: `npx @steve02081504/fount-p2p`.
+
+- **Connectivity debug:** CLI default on; `--quiet` off. Non-CLI: `setConnectivityDebug(true)`.
+- **Priority:** `setInfraPriority({ useLocalReputation })` reads local `reputation.json` only. `stopInfra` resets priority config so the next start does not inherit a ghost weight.
+- **Reputation pull/export is separate:** `pullReputationFromNode` → JSON; `setReputationTable` to apply. Infra does **not** attach `rep_sync`. Donor must `attachReputationSyncWire()` (+ export allowlist); pull side auto-attaches.
+- **`lockReputationMax` / `unlockReputationMax`:** unlock restores the pre-lock score.
+- **`stopInfra` scope:** releases only its own attach refs, restores `maxActive`, clears rate/debug/priority weight.
+
+## Node-scope attaches
+
+Composable attaches under `transport/node_scope/` — import concrete modules, no directory barrel:
+
+- `transport/node_scope/wire` — `ensureNodeScope`, `registerNodeScopeWireHook` (shell custom actions when wire is ready), helpers
+- `transport/node_scope/features` — `attachNodeScopeMailbox` / `Part` / `PartQuery` / `Chunks`, `attachNodeScopeDefaultFeatures`, `attachNodeScopeFeature`
+
+Each attach returns `dispose` and is **refcount-shared** (infra + default features can both hold mailbox without double handlers).
+
+- `ensureUserRoom` is **slot + runtime only** (default `attachDefaultWires: false`).
+- Full preset: `attachNodeScopeDefaultFeatures()` or `ensureUserRoom({ attachDefaultWires: true })`.

package/docs/mesh.md

@@ -0,0 +1,67 @@
+# Mesh policy
+
+A fount node's **first job is to join and stay on the fount network**. Link presence is not business trust: discovery and dialing stay aggressive; trust and fanout are constrained by reputation / TrustGraph / denylist.
+
+Do **not** treat "unrelated ⇒ no interconnect" or "no common group ⇒ no dial" as design premises. Nodes with no acquaintances, no shared groups, and no shell intro must still reach the network via discovery media.
+
+No versioning — see [transports.md](transports.md).
+
+## Discovery: no topic on the fount-network surface
+
+Each discovery / scannable medium exposes only:
+
+1. `listVisibleNodeHashes({ limit? })` → `nodeHash[]` visible on that medium
+2. `connectToNode(nodeHash)` → dial via registry (`ensureLinkToNode`)
+
+Scans with `roomSecret` return **only that group's visible pool**. Media without group semantics (LAN / BT) return `[]` — do not pour network/LAN nodes into group membership.
+
+Topic, relay tags, rendezvous keys, and signal crypto live **only** under `discovery/`. Group flows pass `roomSecret` and other business keys; transport only sees `nodeHash` / opaque bytes.
+
+Visible pools (Nostr / BT / LAN) only accept **signature-verified** adverts; forged `body.nodeHash` after decrypt alone does not enter the pool. BT scan also records `peripheralId` via `noteAdvertPeerHints` so `connectToNode` / `ble_gatt` can dial.
+
+Group presence / advert watch / signaling fan-in **all** providers that implement the methods — do not hard-bind `nostr` id.
+
+No discovery-layer mDNS. LAN UDP presence must carry signed+encrypted network `advertBytes`; unsigned `nodeHash` beacons are ignored. WebRTC ICE `.local` host-candidate filtering is `iceLocalHostnamePolicy` (unrelated to discovery).
+
+| Medium | Scan | Dial |
+| --- | --- | --- |
+| Nostr | Internal rendezvous; surface is hash list only | Internal signal + trigger link |
+| lan_tcp | Segment presence/beacon (not topic) | TCP dial |
+| BT | Near-field scan | GATT / near-field assist |
+
+## Keep-alive: N links, K + (N−K)
+
+After `ensureRuntime`, aim for at least **N** active peer links (subject to `maxActive` / routing profile — "no acquaintances" is never an excuse for N=0):
+
+| Slot | Count | Source | Selection |
+| --- | --- | --- | --- |
+| Acquaintance | **K** (`K ≤ N`) | `trustedPeers` / high reputation / recent stable peers | High confidence first |
+| Explore | **N−K** | `listVisibleNodeHashes` + PEX/hints | Continuous try; rotate on failure |
+
+Explore keeps the node reachable when acquaintances are offline. Stable explore peers (tunable `meshPromoteStableMs`) promote via `promoteExplorePeer` into `trustedPeers`.
+
+`transport/mesh_keepalive.mjs`: explore eviction when full; acquaintance rebalance may kick explore slots; proactive close does not sticky re-dial; inbound non-acquaintance peers are tagged explore.
+
+### K = 0 (new node / empty trust table)
+
+**N−K = N**: automatically `listVisibleNodeHashes` + `connectToNode` on each medium — do not idle waiting for the shell to inject friends.
+
+## Trust boundary (linked ≠ trusted)
+
+- **Dial / keep-alive / overlay:** connectivity first.
+- **Federation fanout, reputation seeding:** TrustGraph / reputation / denylist; explore slots default low trust.
+- **Inbound payloads:** untrusted ingress — see [AGENTS.md](../AGENTS.md).
+
+## Sparse group linking (orthogonal)
+
+Within a **known member set**, `group_link_set` dials sparsely for budget (`selectLinkTargetsFromMembers` within `resolveFederationPoolLimits`: top trusted + explore, denylist/quarantine filtered, **anchors always included**). Member discovery uses `listVisibleNodeHashes({ roomSecret })` + `connectToNode` — **not** `subscribe(groupTopic)`.
+
+`start()` dials once; membership changes debounce via `notePeerCandidate` (dial newly selected only; never proactive cut — `trimToBudget` is the backstop). This is a budget choice on the member graph, not a ban on linking outside the group.
+
+On a sparse group mesh, first-seen valid events forward to federation targets minus sender. Relaying is not a reputation penalty.
+
+## See also
+
+- [transports.md](transports.md)
+- [signaling.md](signaling.md)
+- [runtime.md](runtime.md)

package/docs/reputation.md

@@ -0,0 +1,22 @@
+# Subjective reputation
+
+Day-to-day package rules: [AGENTS.md](../AGENTS.md). Tunables: `reputation/tunables.json`. Sim co-evolution: [sim/AGENTS.md](../sim/AGENTS.md).
+
+## Storage
+
+One global score per peer at `{nodeDir}/reputation.json`.
+
+## Slash / anti-Sybil
+
+- **Subjective slash:** `subjectiveSlashPenalty` — influence scales with sender trust.
+- **Anti-Sybil:** `applyDecayCollusionAfterSlash` after slash / kick / ban.
+- **Safe penalties:** self-observed attributable signals only.
+
+## Do not add
+
+- Penalties for merely relaying invalid events
+- Penalties for RPC timeouts or empty responses
+
+## Fetch ≠ apply
+
+`pullReputationFromNode` returns JSON only — never writes. Apply via `setReputationTable` (or equivalent). Infra does not attach `rep_sync` by default — see [infra.md](infra.md).

package/docs/runtime.md

@@ -0,0 +1,74 @@
+# Runtime bootstrap & lifecycle
+
+`ensureRuntime`, startup/shutdown budgets, and Bluetooth hardware probe. Day-to-day shell rules: [AGENTS.md](../AGENTS.md). Providers: [transports.md](transports.md). Mesh N/K: [mesh.md](mesh.md).
+
+## `ensureRuntime` contract
+
+Returns after registering lan / nostr discovery providers (subject to the signaling `channels` whitelist), registering all enabled link providers (including `ble_gatt`), and scheduling background warm — does **not** await lan_tcp listen, Nostr relays, or BT availability.
+
+| Who waits | For what |
+| --- | --- |
+| Shells (`startNode` / `ensureUserRoom`) | Nothing beyond `ensureRuntime` itself — never read `lanTcpPort` or await public-signaling warm-up |
+| `buildLocalAdvert` / `whenListening` | Local lan_tcp listen only |
+| `ensureLinkToNode` | `whenSignalListening` (Nostr `listenNodeSignals` attached) before dial, so offer/answer does not drop the first signal |
+| `ensureChannelAvailable('bt')` | BT discovery provider registered and BT signal/presence fan-in restarted |
+
+Nostr / LAN hooks are progressive. The `bt` discovery provider is **not** registered by `ensureRuntime`; it is registered on demand via `ensureChannelAvailable('bt')`.
+
+## `ensureChannelAvailable(channel)` contract
+
+Await this to make a specific channel available:
+
+- `bt` — probes the Bluetooth runtime, registers the `bt` discovery provider if available, and restarts the signal/presence fan-in so BT participates.
+- `lan` — awaits `whenListening` (local lan_tcp listen).
+- `nostr` — awaits `whenSignalListening` (Nostr `listenNodeSignals` attached).
+- `webrtc` — awaits `whenSignalListening` (the shared signal medium WebRTC depends on).
+
+`startNode` does not call `ensureChannelAvailable` automatically; shells that need BT discovery should `await getLinkRegistry().ensureChannelAvailable('bt')` (or the top-level `ensureChannelAvailable('bt')` export) after `startNode`.
+
+### Fast-listen & dial path
+
+- Fast-listen skips providers with `caps.probe: 'native'` (webrtc/ble) — never call their `isAvailable()` on the startup path.
+- Dial path: `canReach` then `isAvailable` per provider (do not `await listAvailableLinkProviders()` first).
+
+### Regression budgets
+
+| Check | Bound | Test |
+| --- | --- | --- |
+| Cold `ensureRuntime` | ≤50ms | `test/pure/startup_budget.test.mjs` |
+| Warm `ensureRuntime` | ≤5ms | same |
+| init → shutdown → natural exit | ≤10s | `test/pure/shutdown_exit.test.mjs` |
+| 10s warm → shutdown → exit | ≤2s | same |
+
+Shutdown-exit tests use the production path (default public Nostr + lan). Do not use per-channel relay / dead-relay crutches there.
+
+## Nostr cleanup
+
+Use the `ws` package (not global `WebSocket`) — platform WebSocket lacks force-drop / unref needed for clean shutdown. Subscriptions share one WebSocket per relay URL (signal / network advert / per-node advert / group advert multiplex `REQ`s). Active subscriptions reconnect after drop (`NOSTR_RECONNECT_DELAY_MS`) and re-send `REQ`s. On intentional shutdown: `close()`, then `terminate()` after `NOSTR_CLOSE_GRACE_MS` (1s) if the socket is not yet `CLOSED`. Presence publish still uses short-lived sockets.
+
+Self presence echo from relays is filtered (`skipNodeHash`, same idea as LAN) and omitted from `listVisibleNodeHashes`. First-seen peer clues notify the link registry (`noteDiscoveryPeerClue`) so dial cooldown unlocks when a peer reappears.
+
+## Deno vs Node native addons
+
+| Surface | Node | Deno |
+| --- | --- | --- |
+| Package tests / production CLI | `node` / `npx @steve02081504/fount-p2p` | Not primary |
+| fount bridge (`npm run test:fount`) | — | `deno.json` keeps `"nodeModulesDir": "none"` |
+| WebRTC | `node-datachannel` when native loads; else pure-JS `node-rtc-connection` (Termux/Android skips native) | same; native needs local `node_modules` + scripts for **only** `node-datachannel` |
+| BLE (`noble` / `bleno`) | optionalDependencies; lazy-loaded | do **not** blanket `--allow-scripts` (optional native builds can abort the whole run) |
+
+Recommended Deno one-shot for the published CLI when you want native WebRTC:
+
+```bash
+deno run -A --minimum-dependency-age=0 --node-modules-dir=auto --allow-scripts=npm:node-datachannel npm:@steve02081504/fount-p2p
+```
+
+`deno.json` lists `"allowScripts": ["npm:node-datachannel"]` so project-local `deno install` does not try to compile noble/bleno.
+
+On Android/Termux, `node-datachannel` has no Bionic prebuild — loader skips it and uses `node-rtc-connection` (data-channel only; since ≥2.1.0 it exposes native W3C handlers and `bufferedAmount`/`bufferedamountlow` backpressure).
+
+## Bluetooth probe
+
+`canUseBluetoothRuntime` probes in-process: sysfs hint (Linux) → `loadNoble` → `waitPoweredOn` → `stop()`. Requires `@stoprocent/noble>=2.5.9` on Windows (safe teardown after probe). On failure, discovery/link fall back to other paths.
+
+Actual scan/GATT uses the same `loadNoble` / `loadBleno` path. Win defaults to scan-only. Shutdown does not await BT warm; a generation counter invalidates late side effects.

package/docs/signaling.md

@@ -0,0 +1,33 @@
+# Signaling
+
+Internal WebRTC (`needsOfferAnswer`) glare and handshake. Shells use the fount-network API only — [transports.md](transports.md). Discovery / mesh surface: [mesh.md](mesh.md).
+
+## Glare: connId dual-PC pick-one
+
+`node-datachannel` / `node-rtc-connection` cannot safely host two simultaneous glare dials on one PC. Resolution in `transport/offer_answer.mjs`: both sides dial with a random `connId`; on true glare each side builds an independent answer PC, then **keeps the link initiated by the smaller `nodeHash`** (`linkIsPreferred`). Only the canonical link fires `linkUp` / `linkDown`.
+
+- Outbound: `ensureDirectLinkToNode` → `dialOfferAnswer`.
+- Inbound offer with unknown `connId`: new answer PC via `accept` — **not** gated by per-`nodeHash` inflights.
+- One-way dial never builds a second PC.
+
+## Handshake: buffer early `auth`
+
+Frames: `hello` then `auth`. On simultaneous dial, peer `auth` can arrive before peer `hello` — buffer it (`pendingAuth` in `link/pipe.mjs`); never drop.
+
+## Windows / `trickleIceOff`
+
+When set: send final offer/answer after ICE gathering, dedupe remote signals, queue remote ICE until both descriptions are ready.
+
+## Runtime channels
+
+`setSignalingRuntimeConfig({ channels })` after `initNode` (or pass `signaling` once on first `startNode`). Changes emit `signaling-changed` and trigger `reloadDiscoveryRelays` (rebind discovery providers + node presence/signals).
+
+`channels` selects which discovery/link media are active — `nostr`, `lan`, `bt`, `webrtc`. Semantics per channel key: `false` **disables**; any other value (`undefined`, `true`, or an object) **enables** — an object is merged over that channel's default config. Channels not mentioned keep their default enabled state.
+
+Channel → components:
+- `nostr` (nostr discovery + nostr link) — config `relay` **replaces** the default public relay list (do not merge defaults back in).
+- `lan` (lan discovery + lan_tcp link)
+- `bt` (bt discovery + ble_gatt link)
+- `webrtc` (webrtc link data-transport fallback) — config `iceLocalHostnamePolicy` (`none` / `rewrite-loopback` / `drop`, Windows defaults `drop`) and `trickleIceOff` (send final offer/answer after ICE gathering).
+
+To run a node on only a few channels, use the `disableAllChannels` helper: `{ channels: disableAllChannels({ nostr: { relay: [...] } }) }` enables only `nostr` (with its per-channel relay) and disables the rest; use `true` to enable a channel with its default config (`disableAllChannels({ nostr: true, webrtc: true })`).

package/docs/transports.md

@@ -0,0 +1,92 @@
+# fount network vs internal transports
+
+Mesh keep-alive / discovery: [mesh.md](mesh.md). WebRTC glare / handshake: [signaling.md](signaling.md). Runtime lifecycle: [runtime.md](runtime.md).
+
+## No versioning
+
+Do **not** introduce version fields, constants, or suffixes (`v`, `version`, `FRAME_VERSION`, `:v1`, …). Changing a shape means changing it; no dual-read / backward-compat paths. Exception: npm `package.json` `version` is for package publish only.
+
+## Public contract (shell / L4)
+
+This package exposes a **fount network**: talk to `nodeHash` peers with envelopes.
+
+Typical entrypoints:
+
+- `startNode` / `getLinkRegistry().ensureRuntime()`
+- `ensureLinkToNode` / `sendToNodeLink` / `subscribeScope`
+- `createGroupLinkSet` / `createScopedLinkRoom` / `ensureUserRoom`
+
+`registerScopeAuthorizer` may be called before `initNode` / `getLinkRegistry` — it only buffers policy until the default registry is created.
+
+Callers do **not** choose WebRTC, BLE, ICE, or DataChannels. If a path is unavailable on the host, the registry tries the next internal provider; the API surface stays the same.
+
+**Public registration only:** `registerLinkProvider` / `registerDiscoveryProvider` from the package facade or `@steve02081504/fount-p2p/link` / `./discovery`. Provider *implementations* under `link/providers/*` remain package-internal — shells must not import them or pick transports.
+
+Public `./transport/*` subpaths: `link_registry`, `user_room`, `group_link_set`, `node_scope/wire`, `node_scope/features`, `room_scopes`, `remote_user_room`, `scoped_link`. There is no `transport/node_scope` barrel — import the concrete modules. Modules such as `offer_answer`, `runtime_bootstrap` are internal.
+
+Topic / rendezvous / signal crypto live under `discovery/` (`nostr.mjs`, `internal/signal_crypto.mjs`, `adverts.mjs`) — not in `transport/`, not a package export. Do not export `advertiseTopic` / `subscribeTopic` / `sendSignal(topic)` on the fount-network surface. ICE `.local` host-candidate filtering is `iceLocalHostnamePolicy` only.
+
+## Internal layers
+
+| Layer | Role |
+| --- | --- |
+| **Discovery** (`discovery/`) | Per medium: `listVisibleNodeHashes` + `connectToNode`. Encrypted adverts/signals via `adverts.mjs` + `index.mjs` helpers. |
+| **Link providers** (`link/providers/`) | Open a duplex pipe; sorted by **`level` (descending)** — not a shell import |
+| **Registry** (`transport/link_registry.mjs`) | fount-network facade: dial fallback, scope/overlay, one canonical link per peer |
+| **Bootstrap** (`transport/runtime_bootstrap.mjs`) | `ensureRuntime` register + progressive listen/discovery; `ensureChannelAvailable` for BT discovery; `reloadDiscoveryRelays` on `signaling-changed` |
+| **Offer/answer** (`transport/offer_answer.mjs`) | Discovery-signal glare path for `caps.needsOfferAnswer` (**internal**; uses `sendNodeSignalPacket`) |
+| **Mesh keepalive** (`transport/mesh_keepalive.mjs`) | N/K pool, explore eviction, stable promote to `trustedPeers` |
+
+LinkHandle for upper layers: `ready` / `nodeHash` / `send` / `onEnvelope` / `onDown` / `close` / `stats`. Transport-specific fields are for in-package scheduling only.
+
+Provider optional hooks (package-internal): `ensureListening`, `localEndpoint`, `canReach`, `caps.probe: 'sync' | 'native'` (`native` = skipped on ensureRuntime fast-listen). Discovery `connectToNode` / `sendNodeSignal` may return `false` when the path is unavailable; fan-out treats that as silent skip. Per-provider throw/false in discovery and link dial fallback are silent; only total failure of the abstraction surfaces to the caller.
+
+Each registry only calls `ensureListening` on **its own** `lan_tcp` / `ble_gatt` instances (unique registry ids like `lan_tcp:ab12cd34`). Never fan out listening to other registries' sockets.
+
+Chain `providerId` on the LinkHandle stays the short name (`lan_tcp` / `ble_gatt` / `webrtc` / `nostr`) for scheduling/stats.
+
+## Level table
+
+| id | level |
+| --- | --- |
+| `lan_tcp` | 80 |
+| `webrtc` | 70 |
+| `ble_gatt` | 40 |
+| `nostr` | −∞ |
+
+Constants: `link/providers/levels.mjs`. Discovery uses ascending **`priority`** (handshake / presence / signal media order — Nostr stays last at `100`). Link selection uses descending **`level`** (data transport); Nostr is −∞ so it is dialed only after LAN / WebRTC / BLE fail.
+
+## Fallback
+
+1. `canReach` false → skip (no dial)
+2. `isAvailable()` fails → skip (probed per provider on the dial path; never via `listAvailableLinkProviders()` first)
+3. dial/handshake fails or soft-fails (`null`) → next lower level
+4. races: higher `level` wins; same level → smaller `nodeHash` initiates
+
+`caps.needsOfferAnswer` providers use the shared discovery-signal glare path (`dial`/`accept` + signal session) — not hard-coded to `id === 'webrtc'`.
+
+Dial miss / exhausted peers get exponential cooldown so mesh ticks do not busy-loop on stale acquaintances. First-seen discovery peer clues (and `watchNodeAdvert` ingest) clear that peer's cooldown.
+
+## Providers (internal)
+
+### `lan_tcp` (80)
+
+Plain TCP on the LAN. Registry schedules listen in the background after `ensureRuntime`; `buildLocalAdvert` waits for local listen so signed adverts include `tcpPort`. Peers learn `{ host, port }` from discovery meta + advert `tcpPort`. Binding = shared `linkId`; length-prefix framing. No discovery signal / offer-answer. Shells never read `tcpPort`.
+
+### `webrtc` (70)
+
+Discovery signal + dual DataChannel; DTLS fingerprint as handshake binding; `needsOfferAnswer` glare path. Soft-fail (`null`) continues to lower-level providers. Backend: `node-datachannel` when the native addon loads, else pure-JS `node-rtc-connection` (Android/Termux skips native). See [runtime.md](runtime.md).
+
+### `ble_gatt` (40)
+
+GATT write/notify; binding = shared `linkId`; needs BT peer hint (`peripheralId` in discovery meta); optional noble/bleno. Per-registry instance like `lan_tcp`; `isAvailable` / `canReach` gate dial. On Win32, scan-only stacks cannot accept inbound BLE links. One BLE adapter cannot host two independent peripherals in-process — production is one node per process. Hardware probe: [runtime.md](runtime.md).
+
+### `nostr` (−∞)
+
+Last-resort duplex pipe over discovery signal packets (`type: 'link'`), demuxed from WebRTC `type: 'signal'`. Same node rendezvous encryption as signaling; not a second relay subscription. Longer handshake / heartbeat / idle than LAN. Discovery **`priority`** is unchanged (still handshake-last); only link **`level`** is −∞.
+
+### Bluetooth discovery signal
+
+`discovery/bt` carries short signal blobs on GATT so WebRTC can negotiate near-field when LAN/nostr are unavailable (package-internal).
+
+Discovery peripheral and `ble_gatt` both use bleno + name `fount-bt`. On one adapter they contend — last `setServices`/`startAdvertising` wins. Production: one node per process.

package/docs/wire.md

@@ -0,0 +1,21 @@
+# Wire part / fanout attaches
+
+Day-to-day trust rules: [AGENTS.md](../AGENTS.md). Node-scope presets: [infra.md](infra.md).
+
+## Fanout vs targeted (attach inventory)
+
+| Use | API | Notes |
+| --- | --- | --- |
+| Timeline / chunk exploration | `fanoutToTopNodes` | TrustGraph-ranked fanout |
+| Mailbox / targeted packets | `sendToNode` / User Room | Never fanout |
+| part_invoke RPC collect | `wire/part/fanout.collectPartInvokeResponses` | Requires `attachPartWire` already; `timeoutMs` bounds end-to-end |
+| Group-room part | `wire/part/group.attachGroupPartWire` | Group federation frames |
+| TrustGraph / group Trystero chunk | `files/chunk/responder.attachTrustGraphFedChunkResponder` | Chunk responder on trust/group path |
+
+Part query runtime lives under `federation/part_query/*`; wire attach only in `wire/part/query.mjs`.
+
+## Timed collect
+
+APIs with `timeoutMs` (e.g. `collectPartInvokeResponses`) must register the wait **first** and must **not** `await` fanout/send on the return path — a stuck `discoverRoute` / `link.send` otherwise defeats the timeout.
+
+Pattern: `beginFedFanoutFetch` / fire-and-forget fanout + `sent === 0 → finish()`.

package/index.mjs

@@ -36,6 +36,7 @@ import { getRoutingProfile, setRoutingProfile } from './node/routing_profile.mjs
 import { createGroupLinkSet } from './transport/group_link_set.mjs'
 import {
 	configureLinkRegistry,
+	ensureChannelAvailable,
 	ensureLinkToNode,
 	ensureOverlayRouter,
 	getLinkRegistry,
@@ -63,6 +64,7 @@ export {
 	configureLinkRegistry,
 	createGroupLinkSet,
 	createScopedLinkRoom,
+	ensureChannelAvailable,
 	ensureLinkToNode,
 	ensureNodeDefaults,
 	ensureNodeScope,

package/link/providers/nostr.mjs

@@ -4,9 +4,7 @@ import { randomBytes } from 'node:crypto'
 import { base64ToBytes, bytesToBase64 } from '../../core/bytes_codec.mjs'
 import { normalizeHex64 } from '../../core/hexIds.mjs'
 import { getDiscoveryProvider, sendNodeSignalPacket } from '../../discovery/index.mjs'
-import { mergeSignalingRelayUrls } from '../../discovery/nostr.mjs'
-import { getNodeTransportSettings } from '../../node/identity.mjs'
-import { getSignalingRuntimeConfig } from '../../node/instance.mjs'
+import { resolveNostrRelayUrls } from '../../discovery/nostr.mjs'
 import { ms } from '../../utils/duration.mjs'
 import { createLruMap } from '../../utils/lru.mjs'
 import { asLinkHandle } from '../pipe.mjs'
@@ -25,14 +23,6 @@ const NOSTR_HEARTBEAT_MS = ms('60s')
 /** Nostr 链空闲超时。 */
 const NOSTR_IDLE_TIMEOUT_MS = ms('3m')
 
-/**
- * @returns {string[]} 当前可用中继 URL
- */
-function resolveDefaultRelayUrls() {
-	return getSignalingRuntimeConfig().relayOverride
-		?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls)
-}
-
 /**
  * @param {string} remoteNodeHash 对端
  * @param {object} packet link 包
@@ -48,7 +38,7 @@ async function publishLinkPacket(remoteNodeHash, packet) {
  * @returns {import('./index.mjs').LinkProvider & { deliverPacket: (packet: object) => void }} provider
  */
 export function createNostrLinkProvider(options = {}) {
-	const resolveRelayUrls = options.getRelayUrls || resolveDefaultRelayUrls
+	const resolveRelayUrls = options.getRelayUrls || resolveNostrRelayUrls
 
 	/** @type {((link: import('./index.mjs').LinkHandle) => void) | null} */
 	let onInbound = null

package/link/providers/webrtc.mjs

@@ -68,7 +68,7 @@ export async function createWebRtcLink(options) {
 	const handshakeTimeoutMs = Number(options.handshakeTimeoutMs) || ms('10s')
 	const channelOpenTimeoutMs = Math.max(handshakeTimeoutMs, ms('30s'))
 	const rtc = options.rtc ?? await loadNodeRtcPolyfill()
-	const trickleIceOff = getSignalingRuntimeConfig().trickleIceOff === true
+	const trickleIceOff = getSignalingRuntimeConfig().channels.webrtc?.trickleIceOff === true
 	const peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)

package/link/rtc/polyfill.mjs

@@ -99,7 +99,7 @@ async function loadNodeRtcPolyfillUncached(options) {
 	for (const backend of backends)
 		try {
 			const mod = await backend.load()
-			const { iceLocalHostnamePolicy } = getSignalingRuntimeConfig()
+			const iceLocalHostnamePolicy = getSignalingRuntimeConfig().channels.webrtc?.iceLocalHostnamePolicy
 			return {
 				RTCPeerConnection: wrapRtcPeerConnectionForIceLocalHostname(
 					mod.RTCPeerConnection,

package/node/instance.mjs

@@ -83,9 +83,13 @@ export function setNodeLogger(logger) {
  */
 export function setSignalingRuntimeConfig(config) {
 	if (!runtime) throw new Error('p2p: setSignalingRuntimeConfig requires initNode')
-	const previousPolicy = runtime.signaling.iceLocalHostnamePolicy
-	runtime.signaling = resolveSignalingRuntimeConfig({ ...runtime.signaling, ...config })
-	if (runtime.signaling.iceLocalHostnamePolicy !== previousPolicy)
+	const previousPolicy = runtime.signaling.channels.webrtc?.iceLocalHostnamePolicy
+	runtime.signaling = resolveSignalingRuntimeConfig({
+		...runtime.signaling,
+		...config,
+		channels: { ...runtime.signaling.channels, ...config?.channels },
+	})
+	if (runtime.signaling.channels.webrtc?.iceLocalHostnamePolicy !== previousPolicy)
 		rtcPolyfillCacheEpoch++
 	emitNodeChange('signaling-changed', runtime.signaling)
 }