Do Not Merge (pending: feat(agent/core): agents Context Graph as distributed phonebook)

[branarakic]

Summary

Adds three layered pieces so a small / sparse DKG mesh can rediscover direct peer addresses without depending on a flaky DHT lookup:

Layer	Where	What
Schema	profile.ts	dkg:multiaddr (one per address) + dkg:lastSeen (ISO timestamp) on every profile
Heartbeat	dkg-agent.ts	AGENT_PROFILE_HEARTBEAT_MS = 5min; re-publishes profile so phonebook entries stay fresh
Dial fallback	peer-resolver.ts	step 4 prefers richer findAgentDialAddresses (multiaddrs + relay + lastSeen) with 24h staleness filter
Stall recovery	dkg-agent.ts	Messenger.resolvePeer now routes through full PeerResolver instead of raw peerRouting.findPeer

The trigger: testnet diagnostics for #697 showed that even when DHT lookups fail, the agents CG already holds enough metadata to find a peer — we just weren't asking it during dial. PR A (#698) tunes the libp2p side; this PR teaches the resolver to use the CG as a phonebook.

Backward compat

• Schema: dkg:multiaddr and dkg:lastSeen are NOT added to genesis.ts. That would change computeNetworkId (which hashes all genesis quads) and break rolling deployment with any rc.11 peer. RDF doesn't require properties to be declared in the ontology — they're usable as-is. A coordinated genesis bump can land in a future release.
• AgentDirectoryLookup: findAgentDialAddresses is optional. The resolver falls back to the legacy findRelayForPeer when the directory doesn't implement it, so any external embedder or test fixture using the old shape keeps working.
• Heartbeat: defaults to 5min; 0 disables (one-shot startup publish still fires). Operator-tunable via config.network.agentProfileHeartbeatMs.

Wiring

• AgentProfileConfig.multiaddrs + lastSeen; populated in DKGAgent.publishProfile from this.node.multiaddrs filtered through new collectPublishableMultiaddrs (drops loopback / link-local / unspecified bind / dedup).
• DiscoveryClient.findAgentByPeerId gains a second SPARQL query for dkg:multiaddr rows and pulls ?lastSeen in the scalar SELECT.
• PeerResolver step 4 — primes the peerStore with direct multiaddrs (staleness-gated) then layers the relay form on top.
• Messenger resolvePeer hook — routes through peerResolver.resolve() so stall recovery picks up the phonebook path.

Tests

• agent.test.ts > Profile Builder (+3): multiaddrs/lastSeen emission, default-timestamp behaviour, quote-injection guard, collectPublishableMultiaddrs filter.
• peer-resolver.test.ts (+4): phonebook path preferred over relay-only; stale lastSeen drops multiaddrs but keeps relay; falls back to old findRelayForPeer when new method absent; custom stale threshold honoured.

Full suites: @dkg/core 935 / 935 green (+2 vs PR A), @dkg/agent Profile Builder 9/9 green. Same single pre-existing swm-snapshot-sync failure on agent suite as PR A (verified on main: Unknown file extension ".ts" worker-thread loader issue, unrelated).

Test plan

• Build green: pnpm -F @origintrail-official/dkg-core build
• Build green: pnpm -F @origintrail-official/dkg-agent build
• Build green: pnpm -F @origintrail-official/dkg build (cli)
• Unit tests green: peer-resolver.test.ts (23/23), agent Profile Builder (9/9), full @dkg/core (935/935)
• Manual: with this branch deployed on Miles, watch the agents CG over time — confirm dkg:multiaddr triples appear, get refreshed every 5min, and that querying findAgentByPeerId for Muy-Sentinel returns multiaddrs. Then on Muy's side, kill direct connection to Miles, wait for peerStore eviction (1h default), and confirm a fresh dial succeeds via the phonebook step.
• Manual: trigger an outbox stall (peer offline > 5 attempts) and confirm [Messenger] recovery routes through PeerResolver (visible via debug logs of agents-CG priming).

Conflict note

Both PR A (#698) and this PR add a network block to DkgConfig. Merging one before the other will require a trivial conflict resolution combining the fields into a single network block. Recommended merge order: A first (smaller, fewer moving parts), then this.

Companion work

• PR A: #698 — libp2p peerStore/DHT/PeerResolver-timeout operator-tunable knobs.
• Tracking separately: ACK-collector resilience to mid-collection stream resets (today's 3-attempts-per-peer is too brittle when a relay flaps during quorum collection) — to file after Publishing to Verifiable Memory fails with QuorumUnmetError: storage_ack_insufficient (0/3 ACKs) #697 reporter confirms the relay-collapse diagnosis.

Made with Cursor

[branarakic]

Addressed all three Codex findings in 1c99a88:

• 🔴 Null-fallback in step 4: when findAgentDialAddresses is implemented but returns null, the resolver now falls through to findRelayForPeer so peers with only a legacy relay entry (pre-phonebook profiles) still resolve. Regression test added.

• 🔴 Heartbeat re-entrancy: added agentProfileHeartbeatInFlight flag; ticks short-circuit (with a debug log) when a previous publishProfile() is still running, eliminating the currentKcId race when chain RPC is slow or the heartbeat is configured tight. No dedicated unit test — guard is a 5-line well-understood try/finally, and a test would require full DKGAgent setup for marginal value. Existing agent integration tests cover regression.

• 🟡 Per-address robustness: primeAndAppend now retries per-address when the batch addKnownAddresses throws, so a single malformed dkg:multiaddr from an untrusted profile is dropped in isolation instead of poisoning every valid sibling. Regression test added (mocks addKnownAddresses to throw on the bad entry only).

Tests: peer-resolver.test.ts 25/25 (+2 regression). Full @dkg/core suite 937/937 green.

[branarakic]

Round 2 Codex feedback addressed in 5c3a77c7:

Finding (4): collectPublishableMultiaddrs filter was too loose

• Diagnosis confirmed. The round-1 regex only caught loopback / link-local / unspecified bind. RFC1918 (10/8, 172.16/12, 192.168/16), CGNAT (100.64/10), IPv6 ULA (fc00::/7), and /dns4/localhost would have leaked into the agent profile, causing peers to learn self-referential or private multiaddrs and waste dial attempts before falling back to the relay.
• Fix: replaced the inline regex with isPublicLikeAddress from dkg-core — the same classifier the daemon already uses for "node is remotely-dialable" and that pairs with the UI's isMultiaddrRemotelyDialable in share-project-modal.test.ts. Now there's exactly one classifier across the codebase. dkg-core re-exports isPublicLikeAddress so profile.ts can consume it without reaching into a deep import path. Test fence in agent.test.ts expanded with RFC1918 / CGNAT / ULA / DNS-localhost / public-DNS cases.

Finding (5): in-flight flag only guarded heartbeat-vs-heartbeat

• Diagnosis confirmed. publishProfile() is also called from startup, key rotation, and revocation paths — all of which mutate ProfileManager.currentKcId and rewrite registry triples. The round-1 agentProfileHeartbeatInFlight flag protected nothing about those overlaps.
• Fix: added a publishProfileTail tail-promise chain INSIDE publishProfile() itself. Every caller (heartbeat, startup, key rotation, revocation, manual API) now waits for the prior publish to settle (success or failure) before running its own. Kept the heartbeat inFlight flag as a tick-coalescing optimisation (keeps queue depth at 1 even if publish latency exceeds the heartbeat cadence) but documented in the JSDoc that it's NOT the correctness gate — the mutex is.

Finding (6): lastSeenMs === undefined was treated as fresh

• Diagnosis confirmed. The round-1 staleness check used dial.lastSeenMs !== undefined && Date.now() - dial.lastSeenMs > threshold, which means missing freshness → isStale=false → multiaddrs used anyway. That contradicted the DiscoveredAgent.lastSeen JSDoc ("unknown freshness should fall back to relay only") and let partial / manual agents-CG entries bypass the stale-data guard.
• Fix: flipped to isFresh = lastSeenMs !== undefined && Date.now() - lastSeenMs <= threshold and only use multiaddrs when isFresh. Relay address still tried regardless (relays outlive individual peer NAT bindings). Added a regression test (step 4 (phonebook): missing lastSeenMs is treated as stale (multiaddrs dropped, relay still used)) that pins the new behaviour. JSDoc on both AgentDirectoryLookup.findAgentDialAddresses and the docs around the gate updated.

CI green locally (core 938/938, agent 120/120). Drive-by: also escaped a /dns*/ token in the new JSDoc that TypeScript was reading as a comment terminator.

[branarakic]

Round 3 Codex feedback addressed in 1d9842aa:

Finding (7) 🔴: SPARQL injection vector in findAgentByPeerId

• Diagnosis confirmed. The agentUri bound from the first SPARQL query was interpolated unguarded as <${agentUri}> in the follow-up multiaddr query. A blank-node subject (_:b1) or any IRI containing > / whitespace / control chars from a malicious agents-CG entry would break the second query or open an injection path.
• Fix: two layers of defense:
  1. Engine layer: FILTER(isIRI(?agent)) added to the first query so non-IRI bindings never reach JS.
  2. JS layer: wrapped the IRI with assertSafeIri() / sparqlIri() from core/sparql-safe.ts (the existing helpers). On validation failure, the entire entry is dropped (return null) so a malformed agentUri can't relocate the bug downstream via the returned DiscoveredAgent.agentUri.

Finding (8) 🔴: future-timestamp bypass in freshness check

• Diagnosis confirmed. Date.now() - lastSeenMs <= threshold silently accepted ANY future lastSeenMs because the LHS goes negative. A clock-skewed or malicious profile could keep dead direct multiaddrs eligible indefinitely.
• Fix: added a 5-minute upper-bound skew allowance: lastSeenMs !== undefined && lastSeenMs <= now + skew && now - lastSeenMs <= threshold. The 5-minute window covers reasonable NTP drift between independent hosts without admitting attacks. Two regression tests pin the corners:
  • 1-hour future timestamp → multiaddrs DROPPED, relay still used.
  • 1-minute future timestamp (within skew) → multiaddrs KEPT.

JSDoc on AgentDirectoryLookup.findAgentDialAddresses updated to document the two-sided window explicitly. CI green locally (core 944/944 with new tests, agent 120/120).