@steve02081504/fount-p2p 0.0.30 → 0.0.32

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/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,62 @@
+# 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 / bt discovery providers and scheduling background warm — does **not** await lan_tcp listen, Nostr relays, or BT.
+
+| 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 |
+
+Nostr / LAN / BT hooks are progressive. BT discovery / `ble_gatt` always warm in the background.
+
+### 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 `relayOverride` / 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,23 @@
+# 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 relay override
+
+`setSignalingRuntimeConfig({ relayOverride, iceLocalHostnamePolicy, trickleIceOff })` after `initNode` (or pass `signaling` once on first `startNode`). `relayOverride` **replaces** the default public relay list (do not merge defaults back in). Changes emit `signaling-changed` and trigger `reloadDiscoveryRelays` (swap Nostr provider + rebind node presence/signals).

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/BT warm; `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/link/providers/webrtc.mjs

@@ -68,8 +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()
-	// 纯 JS 后端只做 trickle（SDP 不含 candidate）；强制开启 trickle。
-	const trickleIceOff = !rtc.forcesTrickleIce && getSignalingRuntimeConfig().trickleIceOff === true
+	const trickleIceOff = getSignalingRuntimeConfig().trickleIceOff === true
 	const peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)
@@ -183,6 +182,10 @@ export async function createWebRtcLink(options) {
 		const deadline = Date.now() + handshakeTimeoutMs
 		while (peerConnection.iceGatheringState !== 'complete' && Date.now() < deadline)
 			await new Promise(resolve => setTimeout(resolve, 50))
+		if (peerConnection.iceGatheringState !== 'complete') {
+			await pipe.close('ice-gathering-timeout')
+			throw new Error(`p2p: ice gathering incomplete after ${handshakeTimeoutMs}ms`)
+		}
 	}
 
 	/**

package/link/rtc/ice_local_hostname.mjs

@@ -50,18 +50,12 @@ export function filterIceLocalHostnameCandidate(candidate, RTCIceCandidateCtor,
 export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidate, policy = 'drop') {
 	if (policy === 'none') return BaseRTC
 
-	const baseRoutesIce = !!BaseRTC.prototype.prepareIceCandidateEvent
-
 	return class IceLocalHostnameFilteredRTCPeerConnection extends BaseRTC {
 		/** @type {((event: RTCPeerConnectionIceEvent) => void) | null} */
 		#userIceHandler = null
-		/** @type {Set<(event: unknown) => void>} */
-		#iceListeners = new Set()
-		/** 去重：同一次 native 派发可能既走 attribute 又走 listener */
-		#lastIceEvent = null
 
 		/**
-		 * drop：不派发；rewrite：仅派发替换 candidate 后的事件。
+		 * drop：不派发；rewrite：构造仅携带替换 candidate 的派生事件。
 		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
 		 * @returns {RTCPeerConnectionIceEvent | { candidate?: unknown } | null} 规范化后的事件；drop 时为 null
 		 */
@@ -69,7 +63,10 @@ export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidat
 			if (!event?.candidate) return event
 			const filtered = filterIceLocalHostnameCandidate(event.candidate, RTCIceCandidate, policy)
 			if (!filtered) return null
-			return filtered === event.candidate ? event : { candidate: filtered }
+			if (filtered === event.candidate) return event
+			const rewritten = new event.constructor('icecandidate')
+			rewritten.candidate = filtered
+			return rewritten
 		}
 
 		/**
@@ -77,9 +74,6 @@ export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidat
 		 */
 		constructor(config) {
 			super(config)
-			if (baseRoutesIce) return
-
-			// native EventTarget：在派发前规范化，自管 listener，不依赖 stopImmediatePropagation。
 			Object.defineProperty(this, 'onicecandidate', {
 				configurable: true,
 				enumerable: true,
@@ -93,48 +87,22 @@ export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidat
 				 */
 				set: handler => { this.#userIceHandler = handler },
 			})
-			super.addEventListener('icecandidate', event => this.#deliverIce(event))
 		}
 
 		/**
-		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
-		 * @returns {void}
+		 * 先完成 candidate 转换，再走标准 EventTarget 派发（保留 once/AbortSignal/capture 语义）。
+		 * addEventListener / removeEventListener 交由基类，故 once / AbortSignal / capture 均保留。
+		 * drop：不派发；pass-through：派发原事件；rewrite：派发替换 candidate 后的派生事件。
+		 * @param {Event} event 待派发事件
+		 * @returns {boolean} 事件是否未被取消
 		 */
-		#deliverIce = event => {
-			if (this.#lastIceEvent === event) return
-			this.#lastIceEvent = event
+		dispatchEvent(event) {
+			if (event?.type !== 'icecandidate') return super.dispatchEvent(event)
 			const normalized = this.prepareIceCandidateEvent(event)
-			if (normalized == null) return
+			if (normalized == null) return true
 			this.#userIceHandler?.(normalized)
-			for (const listener of this.#iceListeners) listener(normalized)
-		}
-
-		/**
-		 * @param {string} type 事件名
-		 * @param {(event: unknown) => void} listener 回调
-		 * @param {boolean | AddEventListenerOptions} [options] 监听选项
-		 * @returns {void}
-		 */
-		addEventListener(type, listener, options) {
-			if (!baseRoutesIce && type === 'icecandidate') {
-				this.#iceListeners.add(listener)
-				return
-			}
-			return super.addEventListener(type, listener, options)
-		}
-
-		/**
-		 * @param {string} type 事件名
-		 * @param {(event: unknown) => void} listener 回调
-		 * @param {boolean | EventListenerOptions} [options] 监听选项
-		 * @returns {void}
-		 */
-		removeEventListener(type, listener, options) {
-			if (!baseRoutesIce && type === 'icecandidate') {
-				this.#iceListeners.delete(listener)
-				return
-			}
-			return super.removeEventListener(type, listener, options)
+			if (normalized === event) return super.dispatchEvent(event)
+			return super.dispatchEvent(normalized)
 		}
 	}
 }

package/link/rtc/polyfill.mjs

@@ -4,7 +4,6 @@ import { getRtcPolyfillCacheEpoch, getSignalingRuntimeConfig } from '../../node/
 import { nodeDebug } from '../../node/log.mjs'
 
 import { wrapRtcPeerConnectionForIceLocalHostname } from './ice_local_hostname.mjs'
-import { bridgePeerConnection } from './w3c_bridge.mjs'
 
 /** @type {boolean} */
 let exitCleanupHooked = false
@@ -20,11 +19,9 @@ let cachedDefaultPolyfillEpoch = -1
  *   RTCPeerConnection: typeof RTCPeerConnection,
  *   RTCIceCandidate: typeof RTCIceCandidate,
  *   backend: string,
- *   forcesTrickleIce: boolean,
  * }} LoadedRtcPolyfill
  * @typedef {{
  *   id: string,
- *   forcesTrickleIce?: boolean,
  *   load: () => Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>,
  * }} RtcBackend
  */
@@ -57,12 +54,9 @@ async function ensureNodeDatachannelExitCleanup() {
  * @returns {Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>} node-datachannel 构造器
  */
 async function loadNodeDatachannelBackend() {
-	const mod = await import('node-datachannel/polyfill')
+	const module = await import('node-datachannel/polyfill')
 	await ensureNodeDatachannelExitCleanup()
-	return {
-		RTCPeerConnection: mod.RTCPeerConnection,
-		RTCIceCandidate: mod.RTCIceCandidate,
-	}
+	return module
 }
 
 /**
@@ -70,17 +64,12 @@ async function loadNodeDatachannelBackend() {
  * @returns {Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>} node-rtc-connection 构造器
  */
 async function loadNodeRtcConnectionBackend() {
-	const module = await import('node-rtc-connection')
-	return {
-		RTCPeerConnection: /** @type {typeof RTCPeerConnection} */ bridgePeerConnection(module.RTCPeerConnection),
-		RTCIceCandidate: module.RTCIceCandidate,
-	}
+	return import('node-rtc-connection')
 }
 
 /** @type {RtcBackend} */
 const PURE_JS_BACKEND = {
 	id: 'node-rtc-connection',
-	forcesTrickleIce: true,
 	load: loadNodeRtcConnectionBackend,
 }
 
@@ -119,7 +108,6 @@ async function loadNodeRtcPolyfillUncached(options) {
 				),
 				RTCIceCandidate: mod.RTCIceCandidate,
 				backend: backend.id,
-				forcesTrickleIce: backend.forcesTrickleIce === true,
 			}
 		}
 		catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.30",
+	"version": "0.0.32",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -23,13 +23,6 @@
 		"test:live": "node --test --test-concurrency=1 --test-force-exit test/live/*.test.mjs",
 		"test:sim": "node --test --test-concurrency=1 --test-force-exit sim/test/*.test.mjs"
 	},
-	"files": [
-		"**/*.mjs",
-		"**/*.json",
-		"!test/**",
-		"!sim/**",
-		"!scripts/**"
-	],
 	"bin": {
 		"fount-p2p": "infra/cli.mjs"
 	},
@@ -82,7 +75,7 @@
 	"optionalDependencies": {
 		"@stoprocent/bleno": "latest",
 		"@stoprocent/noble": "latest",
-		"node-datachannel": "latest"
+		"node-datachannel": "0.33.0"
 	},
 	"allowScripts": {
 		"node-datachannel": true