@@ -9,51 +9,69 @@ leave CI green.
99
1010## Assumed starting state (Phases 1–3 done)
1111
12- > ** Revision required before execution.** Reconcile every cross-phase reference (names,
13- > signatures, file locations) against the actually-merged Phases 1–3; where they differ,
14- > the landed code wins and this document should be updated first.
15-
16- This plan is written against the current ` main ` , but Phases 1–3 land first. Where the
17- current code differs from the assumed post-Phase-3 state, the difference is called out
18- as a ** DELTA** . The assumed state:
19-
20- - ** ` @metamask/netlayer ` exists** and owns the kernel-facing contract types
21- (` Netlayer ` , ` NetlayerFactory ` , ` NetlayerParams ` , ` NetlayerHooks ` , ` NetlayerSpecifier ` ,
22- ` NetlayerRegistry ` ), the channel seam (` NetworkChannel ` , ` ChannelProvider ` ), the
23- channel-session engine ` makeChannelNetlayer ` (refactored ` transport.ts ` ), the shared
24- machinery (` handshake.ts ` , ` peer-state-manager.ts ` , ` reconnection.ts ` ,
25- ` reconnection-lifecycle.ts ` , ` rate-limiter.ts ` , ` validators.ts ` , ` channel-utils.ts ` ,
26- the networking ` constants.ts ` ), and neutral Ed25519 identity helpers. Their tests moved
27- with them.
28- - DELTA: today these live in ` packages/ocap-kernel/src/remotes/platform/ ` and
29- ` transport.ts ` is a monolithic ` initTransport ` , not ` makeChannelNetlayer ` .
30- - ** ` @metamask/netlayer-loopback ` exists** (in-memory hub ` ChannelProvider ` /` Netlayer ` ),
31- used to replace some hand-rolled ` PlatformServices ` mocks in ocap-kernel tests.
32- - ** Identity is neutral.** ` remotes/kernel/remote-comms.ts ` derives the peerId via
33- ` @noble/curves ` + WebCrypto; ` @libp2p/crypto ` /` @libp2p/peer-id ` are gone from the kernel
34- identity path; the ` ocap: ` URL host is the neutral id; hints are opaque strings.
35- - DELTA: today ` remote-comms.ts ` uses ` @libp2p/crypto ` + ` @libp2p/peer-id ` , and
36- ` kernel-test/src/remote-comms.test.ts ` still imports them to derive the peerId.
37- - ** kernel-errors carries neutral error classes** (` ChannelResetError ` ,
38- ` IntentionalDisconnectError ` , ` MessageTooLargeError ` ) and no longer imports libp2p; the
39- libp2p→neutral error mapper lives in ` remotes/platform/ ` (created in Phase 1) as the
40- only remaining libp2p-aware error code.
41- - DELTA: today error classification is inline in ` transport.ts `
42- (` @libp2p/interface ` , ` @libp2p/utils ` imports) and in ` reconnection.ts `
43- (` PERMANENT_FAILURE_ERROR_CODES ` ), and ` isRetryableNetworkError ` in kernel-errors
44- still name-sniffs libp2p ` MuxerClosedError ` .
45- - ** ocap-kernel still physically hosts the libp2p implementation** : a libp2p
46- ` ChannelProvider ` (` remotes/platform/connection-factory.ts ` ), the libp2p error mapper,
47- ` utils/multiaddr.ts ` , ` utils/network.ts ` , and a thin ` initTransport ` that constructs the
48- provider and hands it to ` makeChannelNetlayer ` . It re-exports the netlayer types from
49- ` @metamask/netlayer ` . It still carries all libp2p deps.
50- - DELTA: today ` connection-factory.ts ` produces the old libp2p ` Channel `
51- (` { msgStream, stream, peerId } ` ), not ` NetworkChannel ` , and ` initTransport ` is the
52- monolith in ` transport.ts ` .
53-
54- Because of these deltas, the file-move maps below name the assumed post-Phase-3 files
55- (e.g. "connection-factory.ts, now a ` ChannelProvider ` "). If Phase 3 slipped, do that
56- extraction first — do not fold it into Phase 4.
12+ > ** Reconciled against landed Phases 1–3** (branches ` rekm/netlayer-1/2/3 ` ). The prior
13+ > DELTA notes are resolved; the state below is what actually merged. Read master.md's
14+ > "Phase 3 — Landed decisions" block for the exact ` @metamask/netlayer ` /
15+ > ` @metamask/netlayer-loopback ` surface. Cross-phase line numbers elsewhere are indicative;
16+ > the landed code wins.
17+
18+ Landed and true as of the start of Phase 4:
19+
20+ - ** ` @metamask/netlayer ` exists** (published, ` 0.1.0 ` , single ` . ` export) and owns the
21+ kernel-facing contract types (` Netlayer ` , ` NetlayerFactory ` , ` NetlayerParams ` ,
22+ ` NetlayerHooks ` , ` NetlayerSpecifier ` , ` NetlayerRegistry ` ), the channel seam
23+ (` NetworkChannel ` , ` ChannelProvider ` — the latter now carries ` readonly peerId ` ), the
24+ channel-session engine ` makeChannelNetlayer ` (` src/channel-netlayer.ts ` ), the shared
25+ machinery (` handshake.ts ` — now with a versioned message, ` peer-state-manager.ts ` ,
26+ ` reconnection.ts ` , ` reconnection-lifecycle.ts ` , ` rate-limiter.ts ` , ` validators.ts ` ,
27+ ` channel-utils.ts ` , the neutral engine ` constants.ts ` ), and the neutral Ed25519 identity
28+ helpers (` identity.ts ` : ` deriveNeutralPeerId ` /` neutralPeerIdToPublicKey ` /
29+ ` publicKeyToNeutralPeerId ` ). Tests moved with them.
30+ - ** ` makeChannelNetlayer ` signature (LANDED, use this — the §2.3/§2.6 sketches below
31+ predate it):** ` makeChannelNetlayer({ provider, hooks, options, logger, stopController }) `
32+ returning ` Netlayer ` (synchronous). It does ** not** take a bare ` incarnationId ` ; the
33+ local incarnation is ` options.localIncarnationId ` . ` stopController ` is a shared
34+ ` AbortController ` — ` stop() ` aborts it and it is the same signal the provider was
35+ constructed with. ` make-libp2p-netlayer.ts ` must construct that ` AbortController ` , pass
36+ ` signal ` to ` ConnectionFactory.make ` and the whole controller to ` makeChannelNetlayer `
37+ (this is exactly what ocap-kernel's thin ` initTransport ` does today — copy it).
38+ - ** ` @metamask/netlayer-loopback ` exists** (published, ` 0.1.0 ` ). It is ** not** a
39+ ` ChannelProvider ` — it implements ` Netlayer ` directly over an in-process ` LoopbackHub `
40+ (` makeLoopbackHub ` /` makeLoopbackNetlayer ` , config ` { hub } ` ). Used as the standard test
41+ fake; ` packages/ocap-kernel/test/loopback-platform-services.ts ` wraps it as a
42+ ` PlatformServices ` and ` packages/ocap-kernel/src/remotes/loopback.test.ts ` is a two-party
43+ in-process demonstration.
44+ - ** Identity is neutral (Phase 2, unchanged in 3).** ` remotes/kernel/remote-comms.ts `
45+ derives the peerId via ` deriveNeutralPeerId ` (now imported from ` @metamask/netlayer ` ) +
46+ WebCrypto for the ocap-URL oid; ` @libp2p/crypto ` /` @libp2p/peer-id ` are gone from the
47+ kernel identity path; the ` ocap: ` URL host is the neutral id; hints are opaque strings.
48+ - ** Still-open DELTA for Phase 4:** ` kernel-test/src/remote-comms.test.ts ` 's fake
49+ platform-services derives its peerId with ` deriveNeutralPeerId ` (from ` @metamask/ocap-kernel ` ),
50+ ** not** ` @libp2p/* ` — that was already fixed in Phase 2. Its ` initializeRemoteComms ` is
51+ still the positional signature; update it to the 4b options-bag shape.
52+ - ** kernel-errors is libp2p-free (Phase 2).** It exports the neutral error classes
53+ (` ChannelResetError ` , ` IntentionalDisconnectError ` , ` MessageTooLargeError ` ); the
54+ libp2p→neutral read-error mapper is ` mapLibp2pReadError ` /` isIntentionalDisconnect ` ,
55+ ** module-private functions in ` connection-factory.ts ` ** (not a standalone file yet).
56+ ` isRetryableNetworkError ` still name-sniffs ` MuxerClosedError ` /` Dial ` /` Transport ` /
57+ ` NO_RESERVATION ` ** by string** (annotated in kernel-errors to move to netlayer-libp2p's
58+ error mapper here in Phase 4).
59+ - ** ocap-kernel still physically hosts the libp2p implementation:** the libp2p
60+ ` ChannelProvider ` (` remotes/platform/connection-factory.ts ` , which now has a
61+ ` get peerId() ` returning ` deriveNeutralPeerId(fromHex(keySeed)) ` and imports
62+ ` NetworkChannel ` /` InboundChannelHandler ` /` PeerDisconnectHandler ` +
63+ ` DEFAULT_MAX_MESSAGE_SIZE_BYTES ` + the three identity helpers from ` @metamask/netlayer ` ),
64+ the module-private error mapper, ` utils/multiaddr.ts ` , ` utils/network.ts ` , a reduced
65+ ` constants.ts ` (** libp2p-only: ` SCTP_USER_INITIATED_ABORT ` , ` RELAY_RECONNECT_BASE_DELAY_MS ` ,
66+ ` RELAY_RECONNECT_MAX_DELAY_MS ` , ` RELAY_RECONNECT_MAX_ATTEMPTS ` ** — the engine constants
67+ moved to ` @metamask/netlayer ` in Phase 3), and a thin ` transport.ts ` whose
68+ ` initTransport ` constructs ` ConnectionFactory ` and delegates to ` makeChannelNetlayer ` . It
69+ re-exports the netlayer types and depends on ` @metamask/netlayer ` . It still carries all
70+ libp2p deps.
71+
72+ The file-move maps below assume this landed state. Where a sketch (esp. §2.3/§2.6) shows
73+ ` makeChannelNetlayer({ ..., incarnationId, ...engineOptions }) ` , use the landed signature
74+ above instead.
5775
5876---
5977
@@ -186,8 +204,18 @@ Notes:
186204 importer is ` connection-factory.ts ` .
187205- ` constants.ts ` is shared: the timeout/limit constants consumed by ` makeChannelNetlayer `
188206 already moved to ` @metamask/netlayer ` in Phase 3; only the libp2p-provider-only
189- constants (relay reconnect backoff, SCTP abort code) come to netlayer-libp2p. Import the
190- shared ones from ` @metamask/netlayer ` where the provider needs them.
207+ constants (` RELAY_RECONNECT_BASE_DELAY_MS ` , ` RELAY_RECONNECT_MAX_DELAY_MS ` ,
208+ ` RELAY_RECONNECT_MAX_ATTEMPTS ` , ` SCTP_USER_INITIATED_ABORT ` ) come to netlayer-libp2p.
209+ ` DEFAULT_MAX_MESSAGE_SIZE_BYTES ` stays in ` @metamask/netlayer ` — ` connection-factory.ts `
210+ already imports it (and the three identity helpers) from there, so those imports need no
211+ change when the file moves (netlayer-libp2p depends on netlayer).
212+ - The "libp2p error mapper (from Phase 1)" is not a standalone file today: it is the
213+ module-private ` mapLibp2pReadError ` + ` isIntentionalDisconnect ` functions at the top of
214+ ` connection-factory.ts ` (covered by ` connection-factory.test.ts ` , which stubs the
215+ identity helpers via ` vi.mock('@metamask/netlayer', ...) ` ). Extracting them to
216+ ` error-mapper.ts ` (+ a new test) is Phase-4 work; also fold in the
217+ ` MuxerClosedError ` /` Dial ` /` Transport ` /` NO_RESERVATION ` name-sniffing that still lives in
218+ kernel-errors' ` isRetryableNetworkError ` .
191219
192220### 2.3 Factory signatures
193221
0 commit comments