refactor(kernel-routing): Extract phase-1 routing helper leaf (#1230)

Add the new :kernel-routing leaf module and move the compile-neutral routing helper slice out of :runtime-node.

Update ownership metadata, direct dependencies, boundary documentation, and the filesystem-based routing boundary test so the partial extraction is enforced without introducing runtime-node cycles.

Author: leumor

.agents/skills/cryptad-architecture/SKILL.md

@@ -52,11 +52,15 @@ Use this skill when you need to:
     `network.crypta.io`, `network.crypta.io.comm`, and `network.crypta.io.xfer` helpers such as
     address matchers, allow-list parsing, listener abstractions, I/O statistics collection,
     throttling, and partially received block assembly
+  - `:kernel-routing` → the compile-neutral phase-1 routing/helper slice across selected
+    `network.crypta.node` value, exception, callback, and request-item helper types such as
+    `BaseRequestThrottle`, `LowLevelGetException`, `LowLevelPutException`, `RequestClient`,
+    `PeerStatusCounts`, `RecentlyFailedReturn`, and `SendableRequestItem*`
   - `:runtime-spi` → `network.crypta.runtime.spi` (JDK-only runtime/config boundary)
   - `:runtime-node` → extracted daemon runtime body across the remaining cyclic/high-level
-    `network.crypta.client` body, large `network.crypta.node` and `network.crypta.runtime.*`
-    slices, the retained node-coupled transport/message execution code in `network.crypta.io*`,
-    and the remaining daemon-coupled
+    `network.crypta.client` body, the remaining peer/request/routing-engine and transport-heavy
+    `network.crypta.node` / `network.crypta.runtime.*` slices, the retained node-coupled
+    transport/message execution code in `network.crypta.io*`, and the remaining daemon-coupled
     `network.crypta.support` / `network.crypta.support.io` / `network.crypta.support.api` subset
   - `:adapter-fcp` → `network.crypta.clients.fcp`, including
     `network.crypta.clients.fcp.bridge`
@@ -89,6 +93,7 @@ Use this skill when you need to:
 - The daemon runtime body now spans extracted leaves plus a thin root composition layer:
   `:kernel-content` owns the compile-neutral phase-1 client/content slice,
   `:kernel-transport` owns the compile-neutral phase-1 transport helper slice,
+  `:kernel-routing` owns the compile-neutral phase-1 routing/helper slice,
   `:runtime-node` owns the remaining runtime/node/client/support body, `:adapter-fcp` owns the
   FCP adapter tree, `:adapter-http-legacy-admin` owns the legacy HTTP adapter tree and resources,
   and the root project keeps tests, packaging, tool entrypoints, and remaining composition glue.
@@ -112,16 +117,19 @@ Use this skill when you need to:
   `:foundation-store-contracts` just as much as any future extraction.
 - Root boundary tests now freeze the extracted layout. In particular,
   `RuntimeNodeKernelSplitPrepBoundaryTest`, `KernelContentBoundaryTest`,
-  `KernelTransportBoundaryTest`, and `HttpLegacyAdminBoundaryTest` guard leaf ownership/import
-  rules, and the runtime/kernel-content tests require `package-info.java` in every production
-  package under those leaves.
+  `KernelTransportBoundaryTest`, `KernelRoutingBoundaryTest`, and
+  `HttpLegacyAdminBoundaryTest` guard leaf ownership/import rules, and the runtime/kernel-content
+  tests require `package-info.java` in every production package under those leaves.
 
 ## Architecture overview (by package)
 ### Core network layer (`network.crypta.node`)
 - Node coordination: `Node.java`
 - Peer management: `PeerNode`, `PeerManager`
 - Network transport: `PacketSender`, `FNPPacketMangler`
 - Request orchestration: `RequestStarter`, `RequestScheduler`
+- `:kernel-routing` now owns the compile-neutral phase-1 helper/value slice inside
+  `network.crypta.node`, including request client metadata, low-level routing exceptions,
+  lightweight peer-status summaries, and sendable-request item helper interfaces.
 - Updates now bootstrap through `network.crypta.runtime.updater.NodeUpdateManager`
 
 ### Runtime orchestration packages (`network.crypta.runtime.*`)
@@ -169,9 +177,13 @@ Use this skill when you need to:
   `network.crypta.io`, `network.crypta.io.comm`, and `network.crypta.io.xfer` classes such as
   `AllowedHosts`, `NetworkInterface`, `IOStatisticCollector`, `SocketHandler`,
   `PortForwardSensitiveSocketHandler`, `PacketThrottle`, and `PartiallyReceivedBlock`.
+- `:kernel-routing` owns the compile-neutral phase-1 `network.crypta.node` helper/value slice,
+  including `BaseRequestThrottle`, `LowLevelGetException`, `LowLevelPutException`,
+  `RequestClient`, `PeerStatusCounts`, `RecentlyFailedReturn`, and `SendableRequestItem*`.
 - `:runtime-node` keeps the node-coupled transport-facing code such as `PeerContext`,
-  `MessageCore`, packet filters, active socket handlers, transfer send/receive code, and runtime
-  helpers like `network.crypta.runtime.core.SSL`.
+  `MessageCore`, packet filters, active socket handlers, transfer send/receive code, and the
+  remaining peer/request/routing-engine side of `network.crypta.node`, plus runtime helpers like
+  `network.crypta.runtime.core.SSL`.
 
 ### Client APIs
 - High-level client: `network.crypta.client`
@@ -328,11 +340,13 @@ Use this skill when you need to:
   classes plus `network.crypta.support.MediaType`
 - `:kernel-transport`: compile-neutral phase-1 transport slice across selected
   `network.crypta.io*` helpers
+- `:kernel-routing`: compile-neutral phase-1 routing/helper slice across selected
+  `network.crypta.node` helper/value types
 - `:runtime-spi`: `network.crypta.runtime.spi`
 - `:runtime-node`: extracted daemon runtime body across the remaining cyclic/high-level
-  `network.crypta.client` body, large `network.crypta.node` / `network.crypta.runtime.*` slices,
-  the retained node-coupled transport/message execution code, and the remaining daemon-coupled
-  support helpers
+  `network.crypta.client` body, the remaining peer/request/routing-engine
+  `network.crypta.node` / `network.crypta.runtime.*` slices, the retained node-coupled
+  transport/message execution code, and the remaining daemon-coupled support helpers
 - `:adapter-fcp`: `network.crypta.clients.fcp`
 - `:adapter-http-legacy-admin`: `network.crypta.clients.http`
 

.agents/skills/cryptad-build-test/SKILL.md

@@ -21,7 +21,7 @@ Use this skill when you need to:
 - Current leaf projects are `:foundation-support`, `:foundation-store`,
   `:foundation-store-contracts`, `:foundation-crypto-keys`, `:interop-wire`,
   `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:kernel-content`,
-  `:kernel-transport`, `:runtime-spi`,
+  `:kernel-transport`, `:kernel-routing`, `:runtime-spi`,
   `:runtime-node`, `:adapter-fcp`, `:adapter-http-legacy-admin`, `:thirdparty-onion`,
   `:thirdparty-legacy`, and `:launcher-desktop`.
 - The extracted leaf projects compile separately, but `buildJar`, `run`, `runLauncher`,
@@ -55,6 +55,10 @@ Use this skill when you need to:
   `network.crypta.io`, `network.crypta.io.comm`, and `network.crypta.io.xfer` helpers such as
   allow-list parsing, listener abstraction, I/O statistics collection, throttling, and partially
   received block assembly.
+- `:kernel-routing` owns the compile-neutral phase-1 routing/helper slice across selected
+  `network.crypta.node` value, exception, callback, and request-item helper types such as
+  `BaseRequestThrottle`, `LowLevelGetException`, `LowLevelPutException`, `RequestClient`,
+  `PeerStatusCounts`, `RecentlyFailedReturn`, and `SendableRequestItem*`.
 - Every extracted internal leaf must keep leaf-owned aggregated-output metadata in sync at
   `<leaf>/gradle/owned-output-patterns.txt`, even for structurally separate package/resource
   moves. Non-clean builds and branch switches can leave stale non-owner aggregated outputs behind,
@@ -63,16 +67,18 @@ Use this skill when you need to:
   leaf's `owned-output-patterns.txt` and validate with
   `./gradlew verifySelectiveLeafOwnershipMetadata buildJar`.
 - Root boundary tests now freeze the current extracted layout. `RuntimeNodeKernelSplitPrepBoundaryTest`,
-  `KernelContentBoundaryTest`, `KernelTransportBoundaryTest`, and `HttpLegacyAdminBoundaryTest`
-  are the focused regression checks for leaf ownership/import boundaries, and the
+  `KernelContentBoundaryTest`, `KernelTransportBoundaryTest`, `KernelRoutingBoundaryTest`, and
+  `HttpLegacyAdminBoundaryTest` are the focused regression checks for leaf ownership/import
+  boundaries, and the
   runtime/kernel-content tests enforce `package-info.java` coverage for production packages in
   those leaves.
 - `:runtime-spi` is the JDK-only runtime/config API leaf. Its focused unit tests still live in the
   root test tree and run through the root build.
 - `:runtime-node` is the extracted daemon runtime leaf. It now owns the remaining cyclic/high-level
-  `network.crypta.client` body, `network.crypta.node`, the retained node-coupled transport/message
-  execution code in `network.crypta.io*`, `network.crypta.runtime.*`, and the remaining
-  daemon-coupled support helpers.
+  `network.crypta.client` body, the remaining peer/request/routing-engine side of
+  `network.crypta.node`, the retained node-coupled transport/message execution code in
+  `network.crypta.io*`, `network.crypta.runtime.*`, and the remaining daemon-coupled support
+  helpers.
 - `:adapter-fcp` owns `network.crypta.clients.fcp`, including
   `network.crypta.clients.fcp.bridge`.
 - `:adapter-http-legacy-admin` owns the current legacy `network.crypta.clients.http` tree and the
@@ -108,7 +114,7 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9
 - Run one test method:
   - `./gradlew test --tests *TestClassName.methodName`
 - For extracted-leaf or boundary work, run the focused boundary tests:
-  - `./gradlew test --tests *KernelTransportBoundaryTest --tests *KernelContentBoundaryTest --tests *RuntimeNodeKernelSplitPrepBoundaryTest --tests *HttpLegacyAdminBoundaryTest`
+  - `./gradlew test --tests *KernelTransportBoundaryTest --tests *KernelContentBoundaryTest --tests *KernelRoutingBoundaryTest --tests *RuntimeNodeKernelSplitPrepBoundaryTest --tests *HttpLegacyAdminBoundaryTest`
 
 ## Compile-only / quick checks
 - Compile only:
@@ -137,6 +143,9 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9
 - Compile the phase-1 kernel-transport leaf when you touched extracted compile-neutral transport
   helpers:
   - `./gradlew :kernel-transport:compileJava`
+- Compile the phase-1 kernel-routing leaf when you touched extracted compile-neutral routing/helper
+  classes:
+  - `./gradlew :kernel-routing:compileJava`
 - Compile only the runtime SPI leaf when you touched just that JDK-only API surface:
   - `./gradlew :runtime-spi:compileJava`
 - Compile the extracted runtime-node leaf when you touched daemon runtime, node, client, xfer, or

README.md

@@ -201,13 +201,19 @@ Cryptad now uses a partial multi-project Gradle build.
   address matching, allow-list parsing, listener abstraction, I/O statistics collection, transfer
   throttling, and partially received block assembly that stay free of `:runtime-node`, adapters,
   and root-composition dependencies.
+- `:kernel-routing` owns the compile-neutral phase-1 routing/helper slice across selected
+  `network.crypta.node` value, exception, callback, and request-item helper types such as
+  `BaseRequestThrottle`, `LowLevelGetException`, `LowLevelPutException`, `RequestClient`,
+  `PeerStatusCounts`, and `SendableRequestItem*` that stay free of `:runtime-node`, adapters, and
+  root-composition dependencies.
 - `:runtime-spi` owns `network.crypta.runtime.spi` and the JDK-only runtime/config boundary used
   by higher layers, including detached FCP peer management plus the admin-HTTP config,
   connectivity, connections, queue, security-levels, shared page-chrome, core-update action,
   first-time-wizard, symlinker, and welcome-page slices.
 - `:runtime-node` owns the remaining daemon runtime body across the still-cyclic
   `network.crypta.client` async/request engine and high-level client APIs, large slices of
-  `network.crypta.node`, the retained node-coupled transport/message execution code in
+  `network.crypta.node` after the phase-1 routing/helper move, the retained node-coupled
+  transport/message execution code in
   `network.crypta.io`, `network.crypta.io.comm`, and `network.crypta.io.xfer`,
   `network.crypta.runtime.*`, and the remaining daemon-coupled
   `network.crypta.support` / `network.crypta.support.io` / `network.crypta.support.api` subset
@@ -235,7 +241,7 @@ Cryptad now uses a partial multi-project Gradle build.
 - Higher-level infrastructure now crosses a narrower boundary through
   `network.crypta.runtime.spi.RuntimePorts`, the minimal wire-side `MessageSource` seam used by
   leaf-owned messages, the new phase-1 `:kernel-content` content slice, the phase-1
-  `:kernel-transport` helper slice, client-owned seams such as
+  `:kernel-transport` helper slice, the phase-1 `:kernel-routing` helper slice, client-owned seams such as
   `network.crypta.client.async.alerts` and `network.crypta.client.async.persistence`, and
   runtime-owned seams such as
   `network.crypta.runtime.alerts.feed`, `network.crypta.runtime.fcp`,
@@ -280,7 +286,7 @@ For extraction and boundary work, run the focused root boundary tests that freez
 ownership and import rules:
 
 ```bash
-./gradlew test --tests *KernelTransportBoundaryTest --tests *KernelContentBoundaryTest --tests *RuntimeNodeKernelSplitPrepBoundaryTest --tests *HttpLegacyAdminBoundaryTest
+./gradlew test --tests *KernelTransportBoundaryTest --tests *KernelContentBoundaryTest --tests *KernelRoutingBoundaryTest --tests *RuntimeNodeKernelSplitPrepBoundaryTest --tests *HttpLegacyAdminBoundaryTest
 ```
 
 Those tests also enforce the current extracted-leaf documentation convention that production
@@ -551,12 +557,17 @@ Root build also includes:
   `network.crypta.io`, `network.crypta.io.comm`, and `network.crypta.io.xfer` helpers such as
   allow-list parsing, listener abstraction, statistics collection, throttling, and partially
   received block assembly.
+- `:kernel-routing`: compile-neutral phase-1 routing/helper leaf spanning selected
+  `network.crypta.node` value, exception, callback, and request-item helper types such as
+  `BaseRequestThrottle`, `LowLevelGetException`, `LowLevelPutException`, `RequestClient`,
+  `PeerStatusCounts`, and `SendableRequestItem*`.
 - `:runtime-spi`: JDK-only runtime ports plus immutable config snapshot/value types used by FCP
   and other infrastructure code.
 - `:runtime-node`: extracted daemon runtime body across the remaining cyclic/high-level
-  `network.crypta.client` body, large `network.crypta.node` and `network.crypta.runtime.*`
-  slices, the retained node-coupled transport/message execution code in `network.crypta.io*`, and
-  the remaining daemon-coupled support helpers.
+  `network.crypta.client` body, the remaining peer/request/routing-engine and transport-heavy
+  `network.crypta.node` / `network.crypta.runtime.*` slices, the retained node-coupled
+  transport/message execution code in `network.crypta.io*`, and the remaining daemon-coupled
+  support helpers.
 - `:adapter-fcp`: extracted `network.crypta.clients.fcp` adapter code, including
   `network.crypta.clients.fcp.bridge`.
 - `:adapter-http-legacy-admin`: extracted legacy `network.crypta.clients.http` adapter code plus
@@ -614,7 +625,7 @@ Tip: Keep the Spotless formatter at the intended version (currently `googleJavaF
   - Leaf subprojects are `:foundation-support`, `:foundation-store`,
     `:foundation-store-contracts`, `:foundation-crypto-keys`, `:interop-wire`,
     `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:kernel-content`,
-    `:kernel-transport`, `:runtime-spi`,
+    `:kernel-transport`, `:kernel-routing`, `:runtime-spi`,
     `:runtime-node`, `:adapter-fcp`, `:adapter-http-legacy-admin`, `:thirdparty-onion`,
     `:thirdparty-legacy`, and `:launcher-desktop`.
 - Core network (`network.crypta.node`): `Node`, `PeerNode`, `PeerManager`, `PacketSender`, `RequestStarter`, `RequestScheduler`, `NodeUpdateManager`.
@@ -634,9 +645,13 @@ Tip: Keep the Spotless formatter at the intended version (currently `googleJavaF
   compile-neutral transport helper slice across selected `network.crypta.io`,
   `network.crypta.io.comm`, and `network.crypta.io.xfer` classes such as `AllowedHosts`,
   `NetworkInterface`, `IOStatisticCollector`, `SocketHandler`, `PacketThrottle`, and
-  `PartiallyReceivedBlock`. `:runtime-node` keeps the node-coupled transport/socket/filter and
-  transfer-execution side of `network.crypta.io*`, and `Message` now depends on the minimal
-  `MessageSource` seam rather than directly on `PeerContext`.
+  `PartiallyReceivedBlock`. `:kernel-routing` now owns the compile-neutral phase-1
+  `network.crypta.node` helper/value slice, including `BaseRequestThrottle`,
+  `LowLevelGetException`, `LowLevelPutException`, `RequestClient`, `PeerStatusCounts`,
+  `RecentlyFailedReturn`, and `SendableRequestItem*`. `:runtime-node` keeps the node-coupled
+  transport/socket/filter side of `network.crypta.io*` plus the remaining peer, scheduler,
+  request-sender, and routing-engine side of `network.crypta.node`, and `Message` now depends on
+  the minimal `MessageSource` seam rather than directly on `PeerContext`.
 - Clients: `network.crypta.client`, FCP (`network.crypta.clients.fcp`), HTTP
   (`network.crypta.clients.http`). `:kernel-content` now owns the compile-neutral phase-1 content
   slice: selected client value/archive/helper classes, immutable client event values, a
@@ -720,11 +735,14 @@ Tip: Keep the Spotless formatter at the intended version (currently `googleJavaF
 - Runtime boundary leaves: `:kernel-content` provides the compile-neutral phase-1 content slice
   across selected `network.crypta.client*` classes plus `network.crypta.support.MediaType`;
   `:kernel-transport` provides the compile-neutral phase-1 transport slice across selected
-  `network.crypta.io*` helpers; `:runtime-spi` provides `network.crypta.runtime.spi`;
-  `:runtime-node` provides the extracted daemon runtime body across the remaining cyclic/high-level
-  `network.crypta.client` body, large `network.crypta.node` / `network.crypta.runtime.*` slices,
-  the retained node-coupled transport/message execution code, and the remaining daemon-coupled
-  support helpers; `:adapter-fcp` provides `network.crypta.clients.fcp`; and
+  `network.crypta.io*` helpers; `:kernel-routing` provides the compile-neutral phase-1
+  `network.crypta.node` helper slice across selected request/routing value, exception, callback,
+  and request-item types; `:runtime-spi` provides `network.crypta.runtime.spi`; `:runtime-node`
+  provides the extracted daemon runtime body across the remaining cyclic/high-level
+  `network.crypta.client` body, the remaining peer/request/routing-engine
+  `network.crypta.node` / `network.crypta.runtime.*` slices, the retained node-coupled
+  transport/message execution code, and the remaining daemon-coupled support helpers;
+  `:adapter-fcp` provides `network.crypta.clients.fcp`; and
   `:adapter-http-legacy-admin` provides the current legacy `network.crypta.clients.http` classes
   and resources.
 - Vendored libraries: `:thirdparty-onion` provides `com.onionnetworks`,

adapter-fcp/build.gradle.kts

@@ -12,6 +12,7 @@ dependencies {
   implementation(project(":interop-wire"))
   implementation(project(":kernel-content"))
   implementation(project(":kernel-transport"))
+  implementation(project(":kernel-routing"))
   implementation(project(":runtime-spi"))
   implementation(project(":runtime-node"))
 

adapter-http-legacy-admin/build.gradle.kts

@@ -14,6 +14,7 @@ dependencies {
   implementation(project(":interop-wire"))
   implementation(project(":kernel-content"))
   implementation(project(":kernel-transport"))
+  implementation(project(":kernel-routing"))
   implementation(project(":runtime-spi"))
   implementation(project(":runtime-node"))
   implementation(project(":thirdparty-onion"))

build.gradle.kts

@@ -26,6 +26,7 @@ val internalLeafProjects =
     project(":foundation-compat"),
     project(":kernel-content"),
     project(":kernel-transport"),
+    project(":kernel-routing"),
     project(":runtime-spi"),
     project(":runtime-node"),
     project(":adapter-fcp"),
@@ -53,6 +54,7 @@ dependencies {
   implementation(project(":foundation-compat"))
   implementation(project(":kernel-content"))
   implementation(project(":kernel-transport"))
+  implementation(project(":kernel-routing"))
   implementation(project(":runtime-spi"))
   implementation(project(":runtime-node"))
   implementation(project(":adapter-fcp"))