refactor(ocap-kernel): extract relay store methods, make caps configurable, fix review issues

Extract relay and remote identity store methods from store/index.ts into
store/methods/relay.ts following the existing methods pattern. Make
MAX_URL_RELAY_HINTS and MAX_KNOWN_RELAYS configurable via
RemoteCommsOptions (defaults: 3 and 20), threaded through the full RPC
handler -> Kernel -> initRemoteIdentity options flow.

Address all review findings: add write-path validation with superstruct
RelayEntryStruct, wrap JSON.parse with contextual error, log migration
and eviction events, warn when bootstrap count exceeds pool cap, document
Date.now() SES assumption and default value rationale, add missing tests
for sorting stability, bootstrap-exceeds-cap, mixed legacy format, and
configurable caps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sirtimid

packages/ocap-kernel/src/remotes/kernel/remote-comms.test.ts

@@ -8,8 +8,8 @@ import {
   initRemoteIdentity,
   initRemoteComms,
   parseOcapURL,
-  MAX_URL_RELAY_HINTS,
-  MAX_KNOWN_RELAYS,
+  DEFAULT_MAX_URL_RELAY_HINTS,
+  DEFAULT_MAX_KNOWN_RELAYS,
 } from './remote-comms.ts';
 import { createMockRemotesFactory } from '../../../test/remotes-mocks.ts';
 import { makeMapKernelDatabase } from '../../../test/storage.ts';
@@ -99,7 +99,7 @@ describe('remote-comms', () => {
       const { oid, hints } = parseOcapURL(ocapURL);
       const knownRelayAddresses = mockKernelStore.getKnownRelayAddresses();
       expect(knownRelayAddresses).toStrictEqual(testRelays);
-      // URL should embed the relays (within MAX_URL_RELAY_HINTS cap)
+      // URL should embed the relays (within DEFAULT_MAX_URL_RELAY_HINTS cap)
       expect(hints).toStrictEqual(testRelays);
       const referenceURL = `ocap:${oid}@${peerId},${testRelays.join(',')}`;
       expect(ocapURL).toBe(referenceURL);
@@ -499,9 +499,9 @@ describe('remote-comms', () => {
       expect(stored).toStrictEqual(initialRelays);
     });
 
-    it('issueOcapURL caps relay hints to MAX_URL_RELAY_HINTS', async () => {
+    it('issueOcapURL caps relay hints to DEFAULT_MAX_URL_RELAY_HINTS', async () => {
       const relays = Array.from(
-        { length: MAX_URL_RELAY_HINTS + 3 },
+        { length: DEFAULT_MAX_URL_RELAY_HINTS + 3 },
         (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
       );
       const { identity } = await initRemoteIdentity(mockKernelStore, {
@@ -510,7 +510,7 @@ describe('remote-comms', () => {
 
       const ocapURL = await identity.issueOcapURL('ko1' as KRef);
       const { hints } = parseOcapURL(ocapURL);
-      expect(hints).toHaveLength(MAX_URL_RELAY_HINTS);
+      expect(hints).toHaveLength(DEFAULT_MAX_URL_RELAY_HINTS);
     });
 
     it('issueOcapURL prefers bootstrap relays over learned relays', async () => {
@@ -531,25 +531,25 @@ describe('remote-comms', () => {
 
       const ocapURL = await identity.issueOcapURL('ko1' as KRef);
       const { hints } = parseOcapURL(ocapURL);
-      expect(hints).toHaveLength(MAX_URL_RELAY_HINTS);
+      expect(hints).toHaveLength(DEFAULT_MAX_URL_RELAY_HINTS);
       // Bootstrap relays should be included ahead of learned relays
       for (const bootstrap of bootstrapRelays) {
         expect(hints).toContain(bootstrap);
       }
     });
 
-    it('addKnownRelays enforces MAX_KNOWN_RELAYS pool cap', async () => {
+    it('addKnownRelays enforces DEFAULT_MAX_KNOWN_RELAYS pool cap', async () => {
       const { identity } = await initRemoteIdentity(mockKernelStore);
 
       // Add more relays than the cap
       const relays = Array.from(
-        { length: MAX_KNOWN_RELAYS + 5 },
+        { length: DEFAULT_MAX_KNOWN_RELAYS + 5 },
         (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
       );
       identity.addKnownRelays(relays);
 
       const entries = mockKernelStore.getRelayEntries();
-      expect(entries).toHaveLength(MAX_KNOWN_RELAYS);
+      expect(entries).toHaveLength(DEFAULT_MAX_KNOWN_RELAYS);
     });
 
     it('addKnownRelays evicts oldest non-bootstrap relays when pool is full', async () => {
@@ -562,13 +562,13 @@ describe('remote-comms', () => {
 
       // Fill pool to the cap
       const fillerRelays = Array.from(
-        { length: MAX_KNOWN_RELAYS },
+        { length: DEFAULT_MAX_KNOWN_RELAYS },
         (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
       );
       identity.addKnownRelays(fillerRelays);
 
       const entries = mockKernelStore.getRelayEntries();
-      expect(entries).toHaveLength(MAX_KNOWN_RELAYS);
+      expect(entries).toHaveLength(DEFAULT_MAX_KNOWN_RELAYS);
       // Bootstrap relay must survive eviction
       expect(entries.some((entry) => entry.addr === bootstrapRelays[0])).toBe(
         true,
@@ -610,10 +610,10 @@ describe('remote-comms', () => {
       ).toBe(true);
     });
 
-    it('init enforces MAX_KNOWN_RELAYS pool cap', async () => {
-      // Pre-seed MAX_KNOWN_RELAYS learned relays
+    it('init enforces DEFAULT_MAX_KNOWN_RELAYS pool cap', async () => {
+      // Pre-seed DEFAULT_MAX_KNOWN_RELAYS learned relays
       mockKernelStore.setRelayEntries(
-        Array.from({ length: MAX_KNOWN_RELAYS }, (_, i) => ({
+        Array.from({ length: DEFAULT_MAX_KNOWN_RELAYS }, (_, i) => ({
           addr: `/dns4/learned${i}.example/tcp/443/wss/p2p-circuit`,
           lastSeen: 100,
           isBootstrap: false,
@@ -627,7 +627,7 @@ describe('remote-comms', () => {
       await initRemoteIdentity(mockKernelStore, { relays: bootstrapRelays });
 
       const entries = mockKernelStore.getRelayEntries();
-      expect(entries).toHaveLength(MAX_KNOWN_RELAYS);
+      expect(entries).toHaveLength(DEFAULT_MAX_KNOWN_RELAYS);
       // All bootstrap relays must survive
       for (const addr of bootstrapRelays) {
         expect(entries.some((entry) => entry.addr === addr)).toBe(true);
@@ -664,6 +664,117 @@ describe('remote-comms', () => {
       ).toBe(false);
     });
 
+    it('logs when bootstrap relay count exceeds maxKnownRelays', async () => {
+      const mockLogger = { log: vi.fn(), error: vi.fn() };
+      const relays = Array.from(
+        { length: 5 },
+        (_, i) => `/dns4/bootstrap${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      await initRemoteIdentity(
+        mockKernelStore,
+        { relays, maxKnownRelays: 3 },
+        mockLogger as unknown as Logger,
+      );
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'bootstrap relay count (5) exceeds maxKnownRelays (3)',
+        ),
+      );
+    });
+
+    it('logs eviction count when pool cap is exceeded during init', async () => {
+      const mockLogger = { log: vi.fn(), error: vi.fn() };
+      mockKernelStore.setRelayEntries(
+        Array.from({ length: 20 }, (_, i) => ({
+          addr: `/dns4/learned${i}.example/tcp/443/wss/p2p-circuit`,
+          lastSeen: 100,
+          isBootstrap: false,
+        })),
+      );
+      await initRemoteIdentity(
+        mockKernelStore,
+        {
+          relays: ['/dns4/bootstrap.example/tcp/443/wss/p2p-circuit'],
+          maxKnownRelays: 10,
+        },
+        mockLogger as unknown as Logger,
+      );
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining('evicted'),
+      );
+    });
+
+    it('sorts same-tier relays by lastSeen descending in URL hints', async () => {
+      mockKernelStore.setRelayEntries([
+        {
+          addr: '/dns4/relay-old.example/tcp/443/wss/p2p-circuit',
+          lastSeen: 100,
+          isBootstrap: false,
+        },
+        {
+          addr: '/dns4/relay-new.example/tcp/443/wss/p2p-circuit',
+          lastSeen: 300,
+          isBootstrap: false,
+        },
+        {
+          addr: '/dns4/relay-mid.example/tcp/443/wss/p2p-circuit',
+          lastSeen: 200,
+          isBootstrap: false,
+        },
+      ]);
+      const { identity } = await initRemoteIdentity(mockKernelStore);
+      const ocapURL = await identity.issueOcapURL('ko1' as KRef);
+      const { hints } = parseOcapURL(ocapURL);
+      expect(hints).toStrictEqual([
+        '/dns4/relay-new.example/tcp/443/wss/p2p-circuit',
+        '/dns4/relay-mid.example/tcp/443/wss/p2p-circuit',
+        '/dns4/relay-old.example/tcp/443/wss/p2p-circuit',
+      ]);
+    });
+
+    it('respects custom maxUrlRelayHints option', async () => {
+      const relays = Array.from(
+        { length: 10 },
+        (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      const { identity } = await initRemoteIdentity(mockKernelStore, {
+        relays,
+        maxUrlRelayHints: 5,
+      });
+      const ocapURL = await identity.issueOcapURL('ko1' as KRef);
+      const { hints } = parseOcapURL(ocapURL);
+      expect(hints).toHaveLength(5);
+    });
+
+    it('respects custom maxKnownRelays option', async () => {
+      const { identity } = await initRemoteIdentity(mockKernelStore, {
+        maxKnownRelays: 5,
+      });
+      const relays = Array.from(
+        { length: 10 },
+        (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      identity.addKnownRelays(relays);
+      expect(mockKernelStore.getRelayEntries()).toHaveLength(5);
+    });
+
+    it('addKnownRelays logs eviction when pool cap is exceeded', async () => {
+      const mockLogger = { log: vi.fn(), error: vi.fn() };
+      const { identity } = await initRemoteIdentity(
+        mockKernelStore,
+        { maxKnownRelays: 5 },
+        mockLogger as unknown as Logger,
+      );
+      const relays = Array.from(
+        { length: 10 },
+        (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      identity.addKnownRelays(relays);
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining('evicted'),
+      );
+    });
+
     it('throws with mnemonic when identity already exists', async () => {
       mockKernelStore.setRemoteIdentityValue('peerId', 'existing-peer-id');
       mockKernelStore.setRemoteIdentityValue(