Torrent v2 1/8: Contracts, verification infrastructure and resource limits

[linroid]

Establishes capability/revision contracts and conformance gates, then bounds retained metadata, session state and payload file operations. Existing v1 behavior remains covered; this does not enable the public v2 runtime.

Part 1/8 of the consolidated stack for #162. Review and merge bottom-up. This PR targets main; its diff contains only this capability group.

Preservation and validation

Consolidates #163–#169. The consolidation snapshot matches original boundary f1a85687 exactly. Fresh CI then exposed a listener shutdown race: canceled accept() could escape as a socket exception. Foundation commit 2fdddd39 fixes cancellation classification and adds a deterministic regression test. This inherited fix and its test are the only file differences from that original boundary; all other contents are preserved. Original branches and discussions are retained.

Fresh CI runs on this replacement PR; historical checks and approvals are not transferred. The remaining production roadmap and release gates are still open.

Original PRs and frozen heads

PR	Original head
#163 — Torrent v2 01a: require executed conformance with pinned clients	24702a3c
#164 — Torrent v2 01b: define capability and revisioned inspection contracts	b1eadef5
#165 — Torrent v2 01c: prevent metadata starvation under transfer load	04bbde68
#166 — Torrent v2 01d: bound retained metadata and clean up cache ownership	f957d625
#167 — Torrent v2 01e: admit session state before storage allocation	1c7f7b25
#168 — test(torrent): isolate and stream the large-fixture TCP benchmark	7d271036
#169 — feat(torrent): bound aggregate payload file operations	f1a85687

Review carry-forward

These original discussions and their responses remain linked for review. Their unresolved status is preserved; consolidation does not imply reviewer approval.

• Torrent v2 01e: admit session state before storage allocation #167: KotlinTorrentSession.kt; latest response.

Consolidated stack

1. Torrent v2 1/8: Contracts, verification infrastructure and resource limits #231 — Contracts, verification infrastructure and resource limits
2. Torrent v2 2/8: V2 identity, metainfo and Merkle integrity #232 — V2 identity, metainfo and Merkle integrity
3. Torrent v2 3/8: V2 layout and verified storage #233 — V2 layout and verified storage
4. Torrent v2 4/8: V2 catalog, checkpoints and crash recovery #234 — V2 catalog, checkpoints and crash recovery
5. Torrent v2 5/8: V2 handshake, hash exchange and bounded transport #235 — V2 handshake, hash exchange and bounded transport
6. Torrent v2 6/8: V2 scheduling and download execution #236 — V2 scheduling and download execution
7. Torrent v2 7/8: Tracker lifecycle, editing and discovery privacy #237 — Tracker lifecycle, editing and discovery privacy
8. Torrent v2 8/8: V2 engine lifecycle, rate controls and restart recovery #238 — V2 engine lifecycle, rate controls and restart recovery

The listener regression failed before the fix and passed afterward on JVM and Android host. The foundation JVM suite also passed locally.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-20T07:46:15.890239Z	2fda412	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

Test Results

  481 files  +145    481 suites  +145   3m 54s ⏱️ +55s
2 328 tests + 70  2 328 ✅ + 70  0 💤 ±0  0 ❌ ±0 
2 944 runs  +686  2 944 ✅ +686  0 💤 ±0  0 ❌ ±0 

Results for commit 2fdddd3. ± Comparison against base commit 06e8e2c.

This pull request removes 4 and adds 74 tests. Note that renamed tests count towards both.

com.linroid.ketch.torrent.TorrentBenchmarkTest ‑ compareKotlinAndNativeDownloaders[jvm]
com.linroid.ketch.torrent.TorrentMetadataExchangeTest ‑ exchange_usesPerPeerIdAndAssemblesReorderedBlocks
com.linroid.ketch.torrent.TorrentMetadataExchangeTest ‑ exchange_usesPerPeerIdAndAssemblesReorderedBlocks[jvm]
iosSimulatorArm64Test.com.linroid.ketch.torrent.TorrentMetadataExchangeTest ‑ exchange_usesPerPeerIdAndAssemblesReorderedBlocks[iosSimulatorArm64]

com.linroid.ketch.api.torrent.TorrentContractsTest ‑ capabilities_unknownNamesSurviveButUnknownMajorDoesNotEnableCommands[jvm]
com.linroid.ketch.api.torrent.TorrentContractsTest ‑ completionRequiresVerifiedSelectionButDoesNotRequireWholeTorrent[jvm]
com.linroid.ketch.api.torrent.TorrentContractsTest ‑ deltaOrdering_gapsAndBackendRestartsRequireResync[jvm]
com.linroid.ketch.api.torrent.TorrentContractsTest ‑ malformedWireValuesAreRejected[jvm]
com.linroid.ketch.api.torrent.TorrentContractsTest ‑ snapshotOrdering_oldHttpResponseCannotReplaceNewerEvent[jvm]
com.linroid.ketch.torrent.TorrentBenchmarkFixtureTest ‑ streamingFixtureIncludesTheShortFinalPieceAndDistinctPieceContent[jvm]
com.linroid.ketch.torrent.TorrentBufferBudgetTest ‑ ceilingsRejectOverflowAndInsufficientMetadataHeadroom
com.linroid.ketch.torrent.TorrentBufferBudgetTest ‑ ceilingsRejectOverflowAndInsufficientMetadataHeadroom[jvm]
com.linroid.ketch.torrent.TorrentBufferBudgetTest ‑ childFailureRollsBackParentAndDoubleCloseDoesNotUnderflow
com.linroid.ketch.torrent.TorrentBufferBudgetTest ‑ childFailureRollsBackParentAndDoubleCloseDoesNotUnderflow[jvm]
…