refactor(store-contracts): Extract neutral store contracts leaf

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

@@ -19,9 +19,15 @@ Use this skill when you need to:
 - The root project still owns `buildJar`, `run`, `runLauncher`, distribution/jpackage tasks, the
   strongly coupled core packages, and all tests.
 - Leaf subprojects:
-  - `:foundation-config` → `network.crypta.config`, `network.crypta.l10n`, the main l10n
-    resources, and the current minimal config/l10n helper closure under
-    `network.crypta.support*` plus `network.crypta.node.FSParseException`
+  - `:foundation-support` → the current stable generic subset of `network.crypta.support`,
+    `network.crypta.support.api`, `network.crypta.support.io`,
+    `network.crypta.support.compress`, `network.crypta.support.math`, plus
+    `network.crypta.node.FSParseException`
+  - `:foundation-store-contracts` → neutral `network.crypta.store` contracts
+    `BlockMetadata`, `GetPubkey`, `StorableBlock`
+  - `:foundation-config` → `network.crypta.config`, `network.crypta.l10n`, and the main l10n
+    resources; public config APIs re-export `:foundation-support` and `:foundation-fs` where they
+    expose shared types
   - `:foundation-fs` → `network.crypta.fs`
   - `:foundation-compat` → `network.crypta.compat`
   - `:runtime-spi` → `network.crypta.runtime.spi` (JDK-only runtime/config boundary)
@@ -43,8 +49,8 @@ Use this skill when you need to:
 - The large cyclic daemon core still lives in the root project:
   `network.crypta.node` (except the transitional `FSParseException` move),
   `network.crypta.io`, `network.crypta.client`, `network.crypta.clients`,
-  most of `network.crypta.support`, `network.crypta.crypt`, `network.crypta.keys`,
-  `network.crypta.store`, and `network.crypta.tools`.
+  the remaining daemon-coupled support code, `network.crypta.crypt`, `network.crypta.keys`,
+  most store implementations under `network.crypta.store`, and `network.crypta.tools`.
 - `:foundation-config` is the current home for all main `network.crypta.config` and
   `network.crypta.l10n` sources. Their unit tests still live in the root test tree and are run by
   the root project.
@@ -53,9 +59,8 @@ Use this skill when you need to:
   package/resource moves, because stale non-owner aggregated outputs from earlier builds or branch
   switches can still shadow leaf outputs while `buildJar` packages aggregated main outputs first.
 - Update that metadata whenever a leaf starts owning additional main classes/resources that root
-  used to compile/package. If the split under `network.crypta.support*` keeps growing, prefer a
-  future extraction such as `:foundation-support`, but keep the metadata accurate until the build
-  no longer has that stale non-owner aggregated output shadowing risk.
+  used to compile/package. This applies to existing leaves such as `:foundation-support` and
+  `:foundation-store-contracts` just as much as any future extraction.
 
 ## Architecture overview (by package)
 ### Core network layer (`network.crypta.node`)
@@ -69,6 +74,8 @@ Use this skill when you need to:
 - Storage abstractions: `FreenetStore`
 - CHK/SSK stores: `CHKStore`, `SSKStore`
 - Caching: `SlashdotStore`
+- Neutral contracts `BlockMetadata`, `GetPubkey`, and `StorableBlock` now live in
+  `:foundation-store-contracts`; store implementations still remain in the root project.
 
 ### Cryptography (`network.crypta.crypt`)
 - Encryption: block cipher / AES streams
@@ -185,19 +192,22 @@ Use this skill when you need to:
 
 ### Supporting infrastructure (`network.crypta.support`)
 - Logging, data structures, threading, helpers
-- Most support code still lives in the root project, but `:foundation-config` now carries the
-  current minimal config/l10n closure from `network.crypta.support`,
-  `network.crypta.support.api`, and `network.crypta.support.io` so that config/l10n can compile as
-  a leaf without depending back on root main sources.
+- `:foundation-support` now owns the stable generic support subset across `network.crypta.support`,
+  `network.crypta.support.api`, `network.crypta.support.io`,
+  `network.crypta.support.compress`, and `network.crypta.support.math`.
+- The root project still owns daemon-coupled support code and higher-level wiring that is not yet
+  stable enough to extract cleanly.
 
 ### Launcher/Desktop leaf module (`:launcher-desktop`)
 - Swing launcher: `network.crypta.launcher`
 - Desktop theme detection: `com.jthemedetecor`
 - Vendored OSHI annotations and launcher resources
 
 ### Foundation leaf modules
-- `:foundation-config`: `network.crypta.config`, `network.crypta.l10n`, selected
-  `network.crypta.support*` helpers, and `network.crypta.node.FSParseException`
+- `:foundation-support`: stable generic `network.crypta.support*` subset plus
+  `network.crypta.node.FSParseException`
+- `:foundation-store-contracts`: neutral `network.crypta.store` contracts
+- `:foundation-config`: `network.crypta.config`, `network.crypta.l10n`
 - `:foundation-fs`: `network.crypta.fs`
 - `:foundation-compat`: `network.crypta.compat`
 - `:runtime-spi`: `network.crypta.runtime.spi`

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

@@ -18,12 +18,17 @@ Use this skill when you need to:
 ## Build layout
 - Cryptad now uses a partial multi-project Gradle build.
 - Use root-project tasks by default; the root project remains the daemon/application target.
-- Current leaf projects are `:foundation-config`, `:foundation-fs`, `:foundation-compat`,
-  `:runtime-spi`, `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`.
+- Current leaf projects are `:foundation-support`, `:foundation-store-contracts`,
+  `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:runtime-spi`,
+  `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`.
 - The extracted leaf projects compile separately, but `buildJar`, `run`, `runLauncher`,
   `assembleCryptadDist`, and jpackage tasks are still rooted at `:cryptad`.
-- `:foundation-config` owns the main `network.crypta.config` and `network.crypta.l10n` sources,
-  plus the minimal support/node compile closure they currently need.
+- `:foundation-support` owns the current stable generic support subset under
+  `network.crypta.support*` plus `network.crypta.node.FSParseException`.
+- `:foundation-store-contracts` owns the neutral `network.crypta.store` contracts
+  `BlockMetadata`, `GetPubkey`, and `StorableBlock`.
+- `:foundation-config` owns the main `network.crypta.config` and `network.crypta.l10n` sources.
+  Its public APIs now re-export `:foundation-support` and `:foundation-fs` where needed.
 - 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,
@@ -65,7 +70,12 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9
 ## Compile-only / quick checks
 - Compile only:
   - `./gradlew compileJava`
-- Compile the config/l10n leaf when you touched extracted config, l10n, or their helper closure:
+- Compile the support leaf when you touched extracted generic support classes:
+  - `./gradlew :foundation-support:classes`
+- Compile the neutral store-contracts leaf when you touched `BlockMetadata`, `GetPubkey`, or
+  `StorableBlock`:
+  - `./gradlew :foundation-store-contracts:compileJava`
+- Compile the config/l10n leaf when you touched extracted config or l10n sources:
   - `./gradlew :foundation-config:classes`
 - Compile only the runtime SPI leaf when you touched just that JDK-only API surface:
   - `./gradlew :runtime-spi:compileJava`

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

@@ -20,12 +20,14 @@ Use this skill when working on:
 - Packaging remains root-owned.
 - The root project `:cryptad` still owns `buildJar`, `assembleCryptadDist`, `dist*`, `run`,
   `runLauncher`, and jpackage tasks.
-- Current contributing leaf modules are `:foundation-config`, `:foundation-fs`,
-  `:foundation-compat`, `:runtime-spi`, `:thirdparty-onion`, `:thirdparty-legacy`, and
-  `:launcher-desktop`.
+- Current contributing leaf modules are `:foundation-support`, `:foundation-store-contracts`,
+  `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:runtime-spi`,
+  `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`.
 - Extracted leaf modules contribute jars and resources through the root runtime classpath.
+- `:foundation-support` and `:foundation-store-contracts` contribute shared runtime classes via
+  their leaf JARs like the other extracted modules.
 - `:foundation-config` contributes the config/l10n code and main l10n resources via its leaf JAR
-  like the other extracted modules.
+  and re-exports `:foundation-support` and `:foundation-fs` where public APIs expose those types.
 - The `:runtime-spi` JAR is packaged like the other leaf artifacts; packaging still produces one
   daemon distribution rooted at `:cryptad`.
 - Packaging does not have separate entrypoints per leaf project; it still assembles a single daemon

README.md

@@ -167,10 +167,16 @@ Cryptad now uses a partial multi-project Gradle build.
 
 - The root project remains the daemon/application project. It still owns the daemon JAR, tests,
   `run`, `runLauncher`, `assembleCryptadDist`, and jpackage task graph.
-- `:foundation-config` owns `network.crypta.config`, `network.crypta.l10n`, the main
-  `network/crypta/l10n/crypta.l10n.en.properties` resource, and the current minimal helper
-  closure those packages need from `network.crypta.support*` plus
+- `:foundation-support` owns the current stable generic support subset under
+  `network.crypta.support`, `network.crypta.support.api`, `network.crypta.support.io`,
+  `network.crypta.support.compress`, `network.crypta.support.math`, plus
   `network.crypta.node.FSParseException`.
+- `:foundation-store-contracts` owns the neutral `network.crypta.store` contracts
+  `BlockMetadata`, `GetPubkey`, and `StorableBlock`.
+- `:foundation-config` owns `network.crypta.config`, `network.crypta.l10n`, and the main
+  `network/crypta/l10n/crypta.l10n.en.properties` resource. Its public APIs now export
+  `:foundation-support` and `:foundation-fs` where config types expose `SimpleFieldSet` or
+  filesystem-facing value types.
 - `:foundation-fs` owns `network.crypta.fs`.
 - `:foundation-compat` owns `network.crypta.compat`.
 - `:runtime-spi` owns `network.crypta.runtime.spi` and the JDK-only runtime/config boundary used
@@ -182,7 +188,7 @@ Cryptad now uses a partial multi-project Gradle build.
 - `:launcher-desktop` owns `network.crypta.launcher`, `com.jthemedetecor`, `oshi`, and launcher
   resources.
 - The large cyclic daemon core remains in the root project for now, and all tests still live
-  there.
+  there. Most store implementations and daemon-coupled support code remain root-owned.
 - Higher-level infrastructure now crosses a narrower boundary through
   `network.crypta.runtime.spi.RuntimePorts`, implemented in the root project by
   `network.crypta.node.runtime.LegacyRuntimePorts`, plus HTTP-local wiring records and
@@ -462,8 +468,12 @@ cd build/jpackage/Crypta.app/Contents
     artifacts; use the commands in “Spotless + Dependency Verification” below.
 
 Root build also includes:
-- `:foundation-config`: extracted config/l10n code plus the minimal support/node closure needed
-  to compile it as a leaf.
+- `:foundation-support`: extracted stable support/api/io/compress/math subset plus
+  `network.crypta.node.FSParseException`.
+- `:foundation-store-contracts`: neutral store contracts used by `crypt`, `keys`, and `store`
+  code during extraction work.
+- `:foundation-config`: extracted config/l10n code and main l10n resources. Its public APIs
+  re-export `:foundation-support` and `:foundation-fs` where required.
 - `:launcher-desktop`: Swing launcher code and desktop/theme detection dependencies.
 - `:thirdparty-onion`: Onion FEC and related vendored sources/resources.
 - `:thirdparty-legacy`: Bitpedia, SevenZip, and Spaceroots vendored code.
@@ -516,10 +526,13 @@ Tip: Keep the Spotless formatter at the intended version (currently `googleJavaF
   - Root project `:cryptad` remains the daemon/application build and still owns the strongly
     coupled core packages, all tests, packaging/runtime tasks, and the current
     `LegacyRuntimePorts` bridge into the runtime SPI.
-  - Leaf subprojects are `:foundation-config`, `:foundation-fs`, `:foundation-compat`,
-    `:runtime-spi`, `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`.
+  - Leaf subprojects are `:foundation-support`, `:foundation-store-contracts`,
+    `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:runtime-spi`,
+    `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`.
 - Core network (`network.crypta.node`): `Node`, `PeerNode`, `PeerManager`, `PacketSender`, `RequestStarter`, `RequestScheduler`, `NodeUpdateManager`.
 - Storage (`network.crypta.store`): `FreenetStore`, `CHKStore`, `SSKStore`, `SlashdotStore`.
+  Neutral contracts such as `BlockMetadata`, `GetPubkey`, and `StorableBlock` now live in
+  `:foundation-store-contracts`; store implementations still remain in the root project.
 - Crypto (`network.crypta.crypt`): AES, DSA/ECDSA, SHA‑256, `RandomSource`/Yarrow.
 - Keys (`network.crypta.keys`): `ClientCHK`, `ClientSSK`, `FreenetURI`, USK.
 - Clients: `network.crypta.client`, FCP (`network.crypta.clients.fcp`), HTTP
@@ -549,19 +562,22 @@ Tip: Keep the Spotless formatter at the intended version (currently `googleJavaF
   `SecurityLevelsSnapshot`, `PageChromeSnapshot`, `FirstTimeWizardSnapshot`,
   `FirstTimeWizardCurrentBandwidthLimits`, `ToadletSymlinkEntry`, and `WelcomePageSnapshot`.
 - Config + localization leaf (`:foundation-config`): `network.crypta.config`,
-  `network.crypta.l10n`, the main l10n properties, and the current minimal compile closure they
-  need from `network.crypta.support`, `network.crypta.support.api`,
-  `network.crypta.support.io`, and `network.crypta.node.FSParseException`. Higher layers should
-  still prefer `RuntimePorts#config()` and the root `LegacyConfigPort` bridge instead of reaching
-  through daemon internals.
-- Support (`network.crypta.support`): logging, data structures, threading, and helpers remain
-  mostly in the root project; the config/l10n-specific compile closure is temporarily housed in
-  `:foundation-config` while package names stay unchanged.
+  `network.crypta.l10n`, and the main l10n properties. Its public APIs re-export
+  `:foundation-support` and `:foundation-fs` where config surfaces expose `SimpleFieldSet` or
+  filesystem-facing types. Higher layers should still prefer `RuntimePorts#config()` and the root
+  `LegacyConfigPort` bridge instead of reaching through daemon internals.
+- Support foundation leaf (`:foundation-support`): stable generic support, support-api,
+  support-io, support-compress, and support-math classes plus
+  `network.crypta.node.FSParseException`.
+- Support (`network.crypta.support`): logging, data structures, threading, and helpers are now
+  split between `:foundation-support` and the root project. Keep generic reusable utilities in the
+  foundation leaf; daemon-coupled support code still remains in root.
 - Launcher/Desktop: `:launcher-desktop` provides `network.crypta.launcher`,
   `com.jthemedetecor`, launcher resources, and desktop-theme integration.
-- Extracted foundations: `:foundation-config` provides config/l10n plus the minimal support/node
-  closure described above, `:foundation-fs` provides `network.crypta.fs`,
-  and `:foundation-compat` provides `network.crypta.compat`.
+- Extracted foundations: `:foundation-support` provides the stable generic support subset,
+  `:foundation-store-contracts` provides neutral `network.crypta.store` contracts,
+  `:foundation-config` provides config/l10n, `:foundation-fs` provides `network.crypta.fs`, and
+  `:foundation-compat` provides `network.crypta.compat`.
 - Runtime boundary leaf: `:runtime-spi` provides `network.crypta.runtime.spi`.
 - Vendored libraries: `:thirdparty-onion` provides `com.onionnetworks`,
   `:thirdparty-legacy` provides `org.bitpedia`, `org.sevenzip`, and `org.spaceroots`.

build.gradle.kts

@@ -1,5 +1,3 @@
-import java.io.File
-
 plugins {
   // Apply Gradle 9 convention plugins from the included build
   id("cryptad.java-kotlin-conventions")
@@ -19,6 +17,7 @@ version = "3"
 val internalLeafProjects =
   listOf(
     project(":foundation-support"),
+    project(":foundation-store-contracts"),
     project(":foundation-config"),
     project(":foundation-fs"),
     project(":foundation-compat"),
@@ -37,6 +36,7 @@ val internalLeafMainClassDirs =
 dependencies {
   // implementation
   implementation(project(":foundation-support"))
+  implementation(project(":foundation-store-contracts"))
   implementation(project(":foundation-config"))
   implementation(project(":foundation-fs"))
   implementation(project(":foundation-compat"))
@@ -145,10 +145,12 @@ val aggregatedMainOutputProducers =
   (listOf(project) + internalLeafProjects).map(::AggregatedMainOutputProducer)
 
 // Every extracted internal leaf declares aggregated main-output ownership metadata under
-// <leaf>/gradle/owned-output-patterns.txt. Structurally separated root -> leaf and leaf -> leaf
-// moves need this because stale outputs can survive in root or old leaf build directories on
-// non-clean builds or branch switches, while root packaging/runtime aggregation still consumes the
-// root main output and every internal leaf main output.
+// <leaf>/gradle/owned-output-patterns.txt.
+// We need this for structurally separated root -> leaf and leaf -> leaf moves.
+// Stale outputs can survive in root or old leaf build directories on non-clean builds or branch
+// switches.
+// Root packaging/runtime aggregation still consumes the root main output and every internal leaf
+// main output.
 val selectiveLeafOutputOwnerships =
   internalLeafProjects.map { leaf ->
     val metadataFile =
@@ -247,6 +249,7 @@ val selectiveLeafOutputPruneTasks =
           aggregatedMainOutputProducers
             .filter { producer -> producer.project != ownership.leaf }
             .flatMap { producer -> ownedOutputTreesFor(producer, ownership.patterns) }
+        group = "build"
         description =
           "Removes stale non-owner aggregated main outputs for paths owned by ${ownership.leaf.path} on non-clean builds"
         dependsOn(verifySelectiveLeafOwnershipMetadata)
@@ -257,6 +260,7 @@ val selectiveLeafOutputPruneTasks =
 
 val pruneSelectiveLeafOutputs by
   tasks.registering {
+    group = "build"
     description =
       "Removes stale aggregated main outputs claimed by selectively extracted leaf projects on non-clean builds"
     dependsOn(verifySelectiveLeafOwnershipMetadata)
@@ -305,12 +309,7 @@ tasks.named<org.gradle.jvm.tasks.Jar>("buildJar") {
   dependsOn(pruneSelectiveLeafOutputs)
   dependsOn(internalLeafProjects.map { "${it.path}:classes" })
   internalLeafProjects.forEach { leaf ->
-    from(
-      leaf.extensions
-        .getByType(org.gradle.api.tasks.SourceSetContainer::class.java)
-        .named("main")
-        .map { it.output }
-    )
+    from(leaf.extensions.getByType(SourceSetContainer::class.java).named("main").map { it.output })
   }
 }
 

foundation-store-contracts/build.gradle.kts

@@ -0,0 +1,6 @@
+plugins {
+  id("cryptad.java-kotlin-conventions")
+  id("cryptad.spotless")
+}
+
+version = rootProject.version

foundation-store-contracts/gradle/owned-output-patterns.txt

@@ -0,0 +1,6 @@
+# Aggregated main outputs that must be pruned on non-clean builds because :foundation-store-contracts owns them now.
+
+network/crypta/store/StorableBlock*
+network/crypta/store/BlockMetadata*
+network/crypta/store/GetPubkey*
+