@steve02081504/fount-p2p 0.0.31 → 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.31",
+	"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

package/sim/AGENTS.md

@@ -0,0 +1,29 @@
+---
+description: P2P tunables simulation / co-evolution harness — fidelity boundary between reused real logic and heuristic proxy environment
+globs: sim/**
+alwaysApply: false
+---
+
+# P2P Sim Harness Guide
+
+In-process co-evolution of **tunables** (`*.tunables.json`) against an **attack genome**, scored by `metrics.mjs`. Search proxy — **not** wire-protocol replay.
+
+## Fidelity boundary
+
+- **Reused verbatim** (import real decision functions; do not re-model): `reputation/engine.mjs`, `reputation/math.mjs`, `sim/social_reputation.mjs` (`*Pure`), `trust_graph/engine.mjs` (`pickTop`), `trust_graph/resolve.mjs`, `governance/join_pow.mjs`.
+- **Tunables source:** `tunables_bundle.mjs` loads in-package `*.tunables.json` plus `sim/reputation_social.tunables.json`. Write social tunables back via `cli.mjs mine --social-tunables PATH` (`apply.mjs`).
+- **`PARAM_SPACE` ↔ defaults:** every `PARAM_SPACE` key must exist in `loadDefaultTunables()`; clear both sides when deleting a key.
+- **`socialRepHideThreshold`:** hide when `score < threshold`. Default `0` (suppress negatives only). Raise the threshold to raise `falsePositiveRate` — never use a negative threshold for "stricter".
+- **Heuristic proxy** (not the real path): `model.mjs`, `discovery.mjs`, `transport.mjs`, `integrity.mjs` — analytical "params → defense" only.
+- **Mesh-first:** explore slots and cold-start join are mandatory; fanout/trust stay separate from link presence. Policy: [docs/mesh.md](../docs/mesh.md). Wiring: [cold_start.md](cold_start.md).
+
+## Anti-drift
+
+- Do not hand-copy runtime constants. RTC budget from `transport/rtc_connection_budget.mjs`. `EXPLORE_MAX_PER_SOURCE` mirrors `peer_pool.mjs` but stays local (importing `peer_pool` pulls fs) — `test/fidelity.test.mjs` asserts equality.
+- Signaling source names (`DEFAULT_SIGNALING_SOURCES`) must be real provider ids (`lan` / `nostr` / `bt`). No `tracker` provider.
+- New sim constants that shadow real ones need a matching assertion in `fidelity.test.mjs`.
+
+## Determinism
+
+- Seeded via `rng.mjs` (`createRng`). `runSimulation(...)` must be pure — `fidelity.test.mjs` asserts serial == parallel == batched snapshots. Use `simulationContext.now` (virtual clock, +60s/round); no wall-clock or unseeded RNG.
+- Round state object is `simulationContext` (not `ctx`); `buildWorld` returns `{ simulationContext }`.

package/sim/admission.mjs

@@ -0,0 +1,56 @@
+/**
+ * 入群 PoW 成本模型：算力预算限速 Sybil/洗白造号。
+ */
+import { expectedJoinPowHashes, powVoluntaryBonus } from '../governance/join_pow.mjs'
+
+/** 每回合可消耗的期望哈希预算（相对 2^16 基准） */
+const HASH_BUDGET_PER_ROUND = 65536
+
+/**
+ * @param {import('./tunables_bundle.mjs').TunablesBundle['admission']} admission admission tunables
+ * @returns {number} 准入 floor bit
+ */
+export function resolvePowFloorBits(admission) {
+	return Math.max(1, Math.floor(Number(admission?.powFloorBits ?? admission?.powDifficultyBits ?? 18)))
+}
+
+/**
+ * @param {number} achievedBits 解达成 bit
+ * @param {import('./tunables_bundle.mjs').TunablesBundle['admission']} admission admission tunables
+ * @returns {number} 自愿封顶信誉加成
+ */
+export function simPowVoluntaryBonus(achievedBits, admission) {
+	return powVoluntaryBonus(achievedBits, resolvePowFloorBits(admission), admission)
+}
+
+/**
+ * @param {number} difficultyBits PoW floor bit
+ * @returns {number} 造一个新身份期望回合成本
+ */
+export function roundsPerIdentity(difficultyBits) {
+	const expected = expectedJoinPowHashes(difficultyBits)
+	return Math.max(1, expected / HASH_BUDGET_PER_ROUND)
+}
+
+/**
+ * @param {number} requested 请求数量
+ * @param {number} difficultyBits PoW 难度
+ * @param {number} rounds 仿真总回合
+ * @returns {number} 预算内可生成的恶意身份数
+ */
+export function capMaliciousByPowBudget(requested, difficultyBits, rounds) {
+	const cost = roundsPerIdentity(difficultyBits)
+	const budget = Math.max(1, Math.floor(rounds / cost))
+	return Math.min(requested, budget)
+}
+
+/**
+ * @param {number} difficultyBits PoW 难度
+ * @param {number} rounds 回合数
+ * @returns {number} 诚实新人入群延迟惩罚 0..1（越高=越慢）
+ */
+export function honestJoinDelayPenalty(difficultyBits, rounds) {
+	const cost = roundsPerIdentity(difficultyBits)
+	const delay = cost / Math.max(1, rounds * 0.25)
+	return Math.min(1, delay)
+}

package/sim/anomaly.mjs

@@ -0,0 +1,39 @@
+/**
+ * 仿真器中的本地可逆异常隔离（映射生产 reputation_engine 纯函数）。
+ */
+import {
+	isQuarantinedPure,
+	observeBehaviorSamplePure,
+} from '../reputation/engine.mjs'
+
+/**
+ * @param {import('../node/reputation_store.mjs').ReputationFile} reputation 观察者信誉表
+ * @param {string} peerId 对端 nodeHash
+ * @param {number} sample 行为样本
+ * @param {number} now 当前时间
+ * @param {import('../reputation/tunables.json')} tunables reputation tunables
+ * @returns {boolean} 是否触发隔离
+ */
+export function simObservePeerBehavior(reputation, peerId, sample, now, tunables) {
+	return observeBehaviorSamplePure(reputation, peerId, sample, now, tunables).anomaly
+}
+
+/**
+ * @param {import('../node/reputation_store.mjs').ReputationFile} reputation 观察者信誉表
+ * @param {string} peerId 对端 nodeHash
+ * @param {number} now 当前时间
+ * @returns {boolean} 是否隔离中
+ */
+export function simIsPeerQuarantined(reputation, peerId, now) {
+	return isQuarantinedPure(reputation, peerId, now)
+}
+
+/**
+ * @param {number} discoveryReach 发现可达 0..1
+ * @param {() => number} rng 随机源
+ * @returns {boolean} 攻击是否触达该观察者
+ */
+export function attackReachesObserver(discoveryReach, rng) {
+	const reach = Math.max(0, Math.min(1, discoveryReach))
+	return rng() < 0.15 + reach * 0.85
+}