RTP Requirements Traceability Matrix¶
This document connects each requirement to the design decision that motivated it and the source code that implements it. Where automated tests exist, they are linked as well.
How to read this table - Req ID — unique identifier from the relevant
REQUIREMENTS.mdfile. - Design Ref — section inDESIGN.mdorARCHITECTURE.mdthat describes the decision. - Implementing Class(es) — primary source file(s) that satisfy the requirement. - Test(s) — automated test(s) that verify the requirement, if any.
Root / System Requirements¶
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-RTP-F-001 | 0–2 tick response | DESIGN.md section 1 | RegionQueueManager |
SLATest, RegionPipelineTest |
| REQ-RTP-F-002 | Geometry (Circle/Square/Rect) | DESIGN.md section 3, ADR-085, ADR-001 | Circle, Square, Rectangle, Ellipse, Polygon, SquareOptimizedDualLayer, CircleOptimizedDualLayer, SegmentedKeyRunTable, PointEdgeSelector; shared selection in MemoryShape.rand() (template: adjustRange / sample / postProcess) |
MemoryShapeTest, MemoryShapeSelectionParityTest, OptimizedShapesRegistrationTest, ADR085ProductionIntegrationTest, ShapeSubParameterTabCompleteTest, SpiralMathPropertyTest, MemoryShapeBinArithmeticPropertyTest |
| REQ-RTP-F-003 | Distributions (Flat/Normal) | DESIGN.md section 3 | Circle_Normal, Square_Normal; shared gaussian draw in NormalMemoryShape.sample() |
MemoryShapeTest, MemoryShapeSelectionParityTest, NormalDistributionFidelityRegressionTest |
| REQ-RTP-F-004 | Multi-region management | DESIGN.md section 5 | Region, RegionQueueManager |
RegionConfigLoaderTest |
| REQ-RTP-F-005 | O(log n) complexity | DESIGN.md section 3 | MemoryShape; floorRunIndex (binary-search run lookup behind isKnownBad / causeAt), maybeFlushAndRebuild (batched learned-state merge so rand() does not pay a full re-merge per selection), absorbIntoAdjacentRun (in-place run extension for marks within spatialResolution) |
MemoryShapeTest, MemoryShapeAmortizedLearningTest, MemoryShapeSelectionThroughputTest |
| REQ-RTP-F-006 | No unbounded rerolling | DESIGN.md section 3 | MemoryShape |
RegionPipelineTest, MemoryShapeSelectionThroughputTest |
| REQ-RTP-F-007 | Uniform distribution | DESIGN.md section 3; ADR-088 section 10 | Circle, Square; AbstractDualLayerShape.sampleCellSpaced / cellSpacedKeyForCounter (REROLL cell-slot spacing keeps the even spread by area) |
DeterministicShapeTest, MemoryShapeSelectionParityTest, CellSlotSpacingTest |
| REQ-RTP-F-008 | Non-blocking execution | DESIGN.md section 1 | RTPTaskPipe, adapters |
RTPArchitectureTest |
| REQ-RTP-F-009 | Redundancy elimination | DESIGN.md section 3 | MemoryTracker; MemoryShape.absorbIntoAdjacentRun (a mark already covered by a learned run is discarded rather than re-queued) |
MemoryShapeTest, MemoryShapeAmortizedLearningTest |
| REQ-RTP-F-010 | External API hooks | ARCHITECTURE.md | SelectionAPI |
— |
| REQ-RTP-F-011 | Claim integrations | ADR-069 (supersedes ADR-019), ADR-118 | GlobalRegionVerifiers, LeafRTPClaimAddon |
MinePlotsCheckerS003Test, ClaimSetupBitTest |
| REQ-RTP-F-012 | Admin scan lifecycle | DESIGN.md section 1 | ScanCmd, ScanTask |
ScanCmdTest |
| REQ-RTP-F-013 | Configurable messages | ARCHITECTURE.md | ConfigParser, MessagesKeys, LanguageCmd, SystemMessages, ReloadCmd, SubReloadCmd, ConfigSearchResultsBuilder, FuzzySearchEngine, SearchThesaurus, OnlineQueryExpander, ThesaurusIndex, TeleportPipelineTask#finishTeleport / #completeDeathTeleport (success messages formatted after landing bookkeeping); menu reject paths preserved across the concrete-command surface (ADR-050 Stage 1a) by routing MenuConcreteCommandLeaves into the existing MenuRedeemSubcommand.dispatch* helpers |
ConfigParserLanguageTest, LanguageCmdTest, ReloadCmdReloadFailureTest, SubReloadCmdTest, FuzzySearchEngineTest, ConfigSearchResultsBuilderTest, ThesaurusIndexTest, ReqRtpMenuConcreteCommandsTest (ADR-050 Stage 1a: 24 cases - registration / routing / permission gating across /rtp menu open / admin / front / visualizations and the root /rtp visualization sibling), ReqRtpMenuRedeemCoverageTest, ReqRtpMenuBuildersAndHandlersTest, ReqRtpSubConfigCmdCoverageTest, MenuActionToCommandTest, MenuConcreteCommandLeavesBTest, InfoBookBuilderTest, VisualizationDispatchTest, CommandTreeMenuBuilderTest, MenuRedeemAnvilAndBookResponseTest, ReqRtpF013TeleportMessagePostStateTest |
| REQ-RTP-F-014 | Foreign configuration & permission import (/rtp config import <plugin>) |
ADR-066 | ForeignConfigImporter, ForeignConfigImporterRegistry, BetterRtpConfigImporter, JustRtpConfigImporter, EzRtpConfigImporter, JakesRtpConfigImporter, PermissionMigrationService, ConfigImportCmd; AbstractForeignConfigImporter#resolveSafeChild (imported world/region/zone names cannot write outside the target directory); PermissionSourceResolver (without source=, the generic permission mapper only runs for plugin folders that look like an rtp plugin; rtp.* / rtp.admin / rtp.reload require a named source=) |
ConfigImporterTest, PermissionMigrationTest, ForeignImporterPathContainmentTest, ReqRtpF014PermissionSourceResolverTest |
| REQ-RTP-F-015 | Landing-spot slope limit (maxSlope / slopeRadius vert keys; layer-following, in-chunk, live/probe parity; unset = unchanged selection and cache key) |
ADR-119 | AbstractVerticalAdjustor.slopeOk / SlopeCheck, LinearAdjustor, JumpAdjustor, GenericVerticalAdjustorKeys, JumpAdjustorKeys |
ReqRtpSlopeLandingTest, LinearAdjustorTest + LinearAdjustorProbeTest + JumpAdjustorTest + JumpAdjustorProbeTest (REQ-RTP-F-015 display names), RegionCacheKeyTest.slopeKeys_changeCacheKeyOnlyWhenSet |
| REQ-RTP-F-015 | Mountainside and cliff-edge limit (maxHillAngle vert key; 8-direction rule with threshold scaled to measured directions plus +-8 plane fit over the 3x3 square; readable samples only; provisional probe verdict from same-file neighbours fetched on demand after the prefilters, authoritative live recheck over resident chunks without loads (S-005); rejects through the existing reschedule paths (S-004); memory marks only for 8-of-8 verdicts; shipped "off" default with suggested 30/45/60; unset or "off" = unchanged selection and cache key) |
ADR-120 | TerrainShapeCheck (evaluate, rule, planeGrade, probeSquare, chunkSquare, residentSquare), AbstractVerticalAdjustor.maxHillAngle / hillAngleOf, RegionCacheKey, TerrainShapeCheck.SQUARE_RADIUS / within, PregenTask (startProbeTerrain, recheckTerrain, evaluateTerrain), FailTypes.terrain / prefilterTerrain, ColumnProbeCoalescer.submitSquare, ChunkSquare, AnvilPrefilter.squareJobAsync, AnvilReader.readTerrainProbe, RTPWorld.probeChunkSquare |
TerrainShapeCheckTest, TerrainShapeCheckReadersTest, PregenTaskTerrainRecheckTest, RegionCacheKeyTest.maxHillAngle_changesCacheKeyOnlyWhenSet / maxHillAngle_offMatchesAbsent, PregenTaskTerrainRecheckTest.liveRecheckReadsInnerSquareOnly, AnvilSectorReaderTest.squareJobs_decodeOnDemand / terrainProbe_matchesColumnProbeInWindow; evidence LandingTerrainCheckMeasurementTest, ChunkDecodeCostBenchmarkTest, TerrainSquareProbeBenchmarkTest |
| REQ-RTP-F-015 | Conditional chunk-ticket radius for enabled hill checks | ADR-120 | TicketFootprint, NeoForge version adapters |
TicketFootprintTest |
| REQ-RTP-F-016 | Runtime-read duration settings accept explicit units, preserve their bare unit, and surface invalid values through the owning config contract | ADR-020 | DurationParser, TemporalUnit (units-api); ConfigParser.getDuration; duration readers in rtp-core, Bukkit/Folia adapters, proxy-common and Velocity |
ConfigParserTimeTest, PvPGateTest, TickBudgetTest, TeleportPipelineTaskMutationTest, NetworkConfigTest, LoadBalancerConfigYamlTest |
| REQ-RTP-NF-001 | Persistent state | DESIGN.md section 4 | DatabaseAccessor, AbstractSQLDatabaseAccessor.flush() / processQueries() (pooled connection release) |
CachedLocationRoundTripTest, SqlPooledConnectionReleaseTest |
| REQ-RTP-NF-002 | Thread safety | DESIGN.md section 2 | RTPTaskPipe, BukkitEffectsInitializer |
RTPArchitectureTest, BukkitRunEffectNoInlineFallbackTest |
| REQ-RTP-NF-003 | Logic isolation | ADR-003 | RTPBukkitPlugin |
RTPArchitectureTest |
| REQ-RTP-SYS-001 | Java 17+ (ADR-113) | build.gradle (java17Modules) |
plugin.yml api-version, fabric.mod.json java; units-api; V1_20_R1FabricVersionAdapter / V1_21_R1FabricVersionAdapter / V1_21_R5FabricVersionAdapter / V1_21_R11FabricVersionAdapter chunk-future binding and result unwrap (S-004, S-005) |
BukkitServerProviderVersionResolutionTest, AnvilLegacyChunkLayoutTest, V1_20_R1ChunkFutureMethodSelectionTest, V1_21_R1ChunkFutureMethodSelectionTest, V1_21_R5ChunkFutureMethodSelectionTest, V1_21_R11ChunkFutureMethodSelectionTest |
| REQ-RTP-SYS-002 | Platform compatibility | ARCHITECTURE.md | rtp-bukkit, rtp-paper, rtp-folia |
TestApiCompatCmdTest |
| REQ-RTP-S-001 | No lethal destination | DESIGN.md section 3 | SafetyCheck, SafetyScan, AnvilPrefilter (malformed or truncated block/biome palette data fails closed to UNKNOWN, preventing misreading corrupt data as safe terrain); TeleportPipelineTask#finishTeleport / #failArrivalFooting (the arrival teleport runs only after the destination-region schematic paste or platform; a failing footing task aborts the teleport with a message) |
RTPArchitectureTest (core_and_api_must_not_depend_on_platform_apis enforces platform-neutral safety checks without leaked platform states), SafetyScanTest, AnvilCorruptedRegionHardeningTest, TeleportPipelineTaskMutationTest (runTeleport_setLocation_runs_after_schematic_paste, runTeleport_failing_footing_task_fails_closed) |
| REQ-RTP-S-002 | No chunk leaks | DESIGN.md section 6 | ChunkReservation, MemoryTracker; RegionQueueManager#demoteToUnkept (sole hot-to-cold disposal path: closes the reservation before offering the bare coordinate, shared by releaseToNetworkKept, disableLoginCache, closePersonalQueue); CacheStage, SimpleCacheStage, RingCacheStage, KeyedCacheStage, HotSink, HotBudgetAllocator (ADR-078 phase 1 & 3: disposal is the single terminal release path, so overflow, down-size, and teardown all release through one handler; budget allocator moves hot entries with zero ticket leaks); GroupSubspaceHotSink, GroupColdToHotTransition (ADR-078 phase 6: multi-chunk footprint reservations closed on overflow/failure); TeleportPipelineTask#holdArrivalReservation / #flushArrivalReservations (post-arrival hold of the landing ticket for ARRIVAL_HOLD_TICKS so the arrived player never sync-loads it, REQ-RTP-S-005; released once by the delayed task or RTP.stop, immediately on a failed teleport; MemoryTracker counts and keeps held chunks); Region#promotionChecks (a cold-to-hot promotion that fails border, biome, safety or claims closes its reservation before dropping the location); RegionCacheTask#processResult (a fill result not handed off to a queue or the preload callback, including one without coordinates or one that throws before handoff, closes its reservation) |
ChunkTicketLifecycleTest, RegionCacheTaskInFlightLeakTest (reqRtpS002_publicFill_coordlessPinnedResult_closesReservation, reqRtpS002_playerFill_coordlessPinnedResult_closesReservation), ReqRtpS002PipelineLeakAssertionTest (full pipeline run, cancellation, failure, and GC sweep leak assertions), ReqRtpS005ArrivalChunkHoldTest (hold window, failed-teleport release, shutdown flush without double release, overlapping holders, no-scheduler fallback), RegionQueueManagerNetworkReservedLifecycleTest (5 demotion/hand-back ticket-hygiene cases), RegionQueueManagerTicketValidationTest, CacheStageContractTest, KeyedCacheStageTest, HotSinkTransferEligibilityTest, HotBudgetAllocatorTest, GroupSubspaceCacheTest, SubReloadCmdTest, FuzzySearchEngineTest, RTPArchitectureTest (only_ChunkReservation_and_RTPWorld_may_call_setForceLoaded, only_RTPWorld_may_call_setForceLoadedImpl) |
| REQ-RTP-S-003 | Respect claims | ADR-019, ADR-058 (schematic-paste footprint guard), ADR-028 (amendment 2026-10-13, item 8) | GlobalRegionVerifiers; Region#promotionChecks (every cold-to-hot promotion runs the verifier registry, so backlog-drained and stored locations cannot reach a player unchecked); TeleportPipelineTask#schematicFootprintClearAsync / #footprintVerdictClear (region schematic paste runs the whole footprint through the verifier registry and suppresses the paste on any claim intersection, falling back to the default platform; the verdict is started off-thread in runLoad and read non-blocking on the region thread, where a pending or failed verdict also suppresses the paste); ClaimCheckFailure (LeafRTPClaimAddon: while the claim plugin is enabled every checker failure rejects the location; a missing/incompatible claim API is logged once at SEVERE, per-call errors are throttled; ADR-118); ClaimPlugins and the reflective checkers (UltimateClaimsChecker, ResidenceChecker, CrashClaimChecker, HuskClaimsChecker, HuskTownsChecker, PlotSquaredChecker, KingdomsXChecker, SaberFactionsChecker, FactionsBridgeChecker: exact plugin.yml names, exact-signature method lookup, fail open only when the plugin is not enabled); MinePlotsChecker (compiled against minePlots plugin-api, PlotServiceApi#getPlot(Location) only; enabled-but-unregistered service or a throwing lookup rejects the location); ModClaimCheckFailure / NeoForgeClaimCheckFailure with ModClaimIntegrations / NeoForgeModClaimIntegrations (FTB Chunks and Open Parties and Claims on Fabric/NeoForge: same failure policy; verifiers register the negated "in a claim" verdict); ClaimAnchoredRegionTracker#encapsulateClaim / #ingestMemoryFromRegion (claim envelopes and inherited hazards are keyed in chunk units) |
ReqRtpS003SchematicFootprintClaimTest (incl. pendingVerifierDoesNotBlockAndSuppressesPaste, failedVerdictIsNotClear), RegionPromotionChecksTest (claimedLocationIsDropped), ClaimCheckFailureRuleS003Test, ModClaimCheckFailureRuleS003Test, MinePlotsCheckerS003Test (runs the checker against mocks of the published plugin-api 4.6.2 types), DirectApiClaimCheckersS003Test (HuskClaims, HuskTowns, PlotSquared, Residence and SaberFactions checkers against mocks of test-source stand-ins carrying the published class names and call shapes; the checkers themselves compile against the real APIs), ReflectiveClaimCheckerApiShapeS003Test (runs each remaining reflective checker against stubs of its plugin's published class names and overload sets), ClaimPluginStandInLifecycleS003Test (all 16 integrations registered through ClaimIntegrations.setup on the mock server, against test-source stand-ins or, for GriefPrevention, Towny, WorldGuard and minePlots, mocks of the published classes: rejection attributed to the checker, admission of open land, flag-off registers nothing, rejection stored as safetyExternal with the per-verifier ttl.yml expiry across save/load, expiry readmits to probation and a fresh rejection restores it), ClaimAnchoredRegionTrackerTest, RTPArchitectureTest (core_and_api_must_not_depend_on_platform_apis gates claim calls from leaking into core/api) |
| REQ-RTP-S-004 | No silent failure | DESIGN.md section 1 | TeleportPipelineTask (a null generation result halts silently only for a player in queuedPlayers, and the halted task is untracked so the leak sweep never force-closes the wait; any other null result messages the player, refunds and releases processingPlayers); RTPCmd.compute (the sender's processingPlayers entry is released on the PvP refusal and whenever no pipeline is submitted for the sender themself); ProcessingLockSweeper via MemoryTracker.runDiagnostics (a processingPlayers entry with no owner - queue, death hold, live tracked pipeline or TeleportData, network status or lobby retry - on two consecutive 60 s sweeps is released with a WARNING naming the player; a stalled TeleportData is kept while its warm-up delay or an owned wait is still running); EditorSessionManager.applyPayload / exportLocalEditorHtml (Hot-Apply .bak / .tmp siblings must resolve inside the plugin folder and are created fresh, never written through an existing link; local HTML exports write a fresh UUID-named CREATE_NEW sibling .tmp; a refusal fails the apply visibly); GlobalRegionVerifiers (a throwing sync or async region verifier is logged at WARNING and the location is rejected/fail-safe, never silently accepted); StageTransition, TransitionOutcome, RejectionReason (ADR-078 phase 1: a declined promotion carries a stated cause instead of a bare empty result); GroupBacklogToColdTransition, GroupColdToHotTransition (ADR-078 phase 6: explicit TransitionOutcome rejections across group cache tiers); GroupPlacementDispatcher; DefaultRtpDispatcher (one in-flight dispatch per player), TransportRequestTriggerSource (requests for players not connected to this proxy are refused and logged); FabricMenuRenderer / NeoForgeMenuRenderer (classic-teleport fallback reports failures to player and log); LcaGoldenFixtureExporter (leafanvil-ADR-004: deterministic CBIT T1..T8 tripwire rejection and 4-tier SEC-DED self-healing vector suite) |
FailureModeTest, RegionPipelineTest, ReqRtpS004VerifierFailSafeTest, RTPCmdBranchTest (testComputeSelfAlreadyTeleportingSkipReleasesSenderLock, testComputeCrossPlayerSkipReleasesSenderLock, testFreePermissionBypassesBalanceFloorCheck, testToggleTargetPermsTargetCannotAffordRefundsSender), EditorSessionManagerCoverageTest, EditorUndoRedoPageTest, SpongeSchematicDecoderTest, RTPCmdPvPGateTest (inCombat_refusalReleasesOuterLock), TeleportPipelineTaskPhaseTest (setup_null_result_not_queued_fails_visibly, setup_null_result_queued_halts_silently, processGenerationResult_null_result_when_player_queued_halts), ProcessingLockSweeperTest, MemoryTrackerTest (runDiagnostics_purgesStalledTeleportDataAndReleasesProcessingPlayer), EditorSecurityHardeningTest (tmpSymlinkRefused, bakSymlinkRefused, staleTmpAndBakReplaced), TransitionOutcomeTest, GroupSubspaceCacheTest, GroupPlacementDispatcherTest, QueueTaskTest, DefaultRtpDispatcherDispatchGateTest, TransportRequestTriggerSourcePresenceGateTest, TransportRequestTriggerSourceForeignPlayerTest (a shared-queue entry for a player held by another proxy is handed back, not cancelled), ActionSyntaxAndGateEvaluationTest, RTPArchitectureTest (no_print_stack_trace_in_core_or_api, no_system_out_or_bukkit_getlogger_in_core_or_api enforce structured logging via RTP.log(Level.WARNING, ...) rather than silent drops or raw stderr dumps), ScanTaskAdvancedCoverageTest (nullProbeOnGeneratedChunk_loadsChunkWithoutMarkingBad: an UNKNOWN region-file probe loads the chunk and leaves it unmarked; allAirProbe_marksBadWithoutLoad), AnvilFixtureParityTest (realFixtureDecodesTerrain: every real fixture decodes non-air blocks; realProtoChunksAreUnknown: real 26.3 proto-chunks are UNKNOWN to the probe and the prefilter), AnvilModernPaletteAndStatusTest, LcaFaultInjectionAndEdgeCaseTest, LcaGoldenFixtureTest |
| REQ-RTP-S-005 | No sync chunk I/O | ADR-015/016, ADR-077, leafanvil-ADR-004 |
RTPTaskPipe, adapters, BukkitRTPWorld (primary-thread biome reads skip unloaded chunks), BiomeActivityTracker (skips unloaded player chunks), RegionFileReader, AnvilReader, AnvilChunkView (#getHeightmapTopY), LinearRegionReader (ADR-077: canonical Linear v1/v2 reader, raw NBT slicing, 64-bit bounds), DynamicZstdBinding (PBIT micro-canary startup verification, host MethodHandles binding with zero shaded jars), RegionFormatDetector (lazy survey with mtime-aware profile cache), Lz4BlockDecoder (ADR-016 section 15: in-house mode-4 decode, size cap checked before allocation, malformed input fails closed to CorruptRegionEntryException), Nbt (512-level depth limit; array/list counts checked against remaining input before allocation; malformed NBT fails closed to IOException), RegionFormatRegistry (.mca built in, .linear registered dynamically when host Zstd available), RegionFileResolver (resolveExisting: window-bounded existence memo; direct fast-path routing to active format), AnvilRegionScanner, PregenBiomeExtractor (read only .mca and registered extensions); AnvilSectorReader, AnvilRegionHeaderCache, AnvilRegionChannelCache (probes share one ref-counted read handle per region file; mtime-keyed reopen, idle close, released by RTP.stop and world unload), AnvilPrefilter#probeColumn (single-chunk .mca probes on every adapter read only the location table and the chunk's own sectors, off-tick; a stale table is detected by chunk position and re-read, corrupt runs fail closed per REQ-RTP-S-004); AnvilRegionByteCache.Lease (whole-file reads reuse pooled buffers with an explicit file length); HotSink#accepts / HotSink#transferEligible, HotBudgetAllocator#rebalance (ADR-078 phase 1 & 3: transfer eligibility and rebalancing operate as pure in-memory rechecks against the entry's already-resident chunk, moving entries between sinks with zero chunk load/unload I/O); GroupBacklogToColdTransition, GroupColdToHotTransition (ADR-078 phase 6: off-tick candidate screening and async chunk loading); SubReloadCmd (asynchronous /rtp reload YAML lexing and ConfigCandidateGate evaluation off the main thread); OnlineQueryExpander (non-blocking TTL-cached online query expansion off-thread); LcaGoldenFixtureExporter (leafanvil-ADR-004: deterministic .lca Mode A/B golden bundles and 5-axis performance proof gates) |
AnvilPrefilterTest (prefilterReadsOnlyChunkSectors), AnvilSectorReaderTest (clusteredProbes_reuseOneFileHandle), AnvilRegionChannelCacheTest, AnvilRegionByteCacheTest (lease pinning, oversized-buffer reuse), RegionFormatRegistryTest (testLinearRegistrationState, testUnregisteredLinearIgnored, testRegisteredLinearPreferredOverMca), LinearRealDataParityTest (ground-truth differential parity across real fixtures), LinearDynamicRegistrationTest, LinearRegionReaderTest, DynamicZstdBindingTest, RegionFormatDetectorTest, RegionFileResolverTest (listRegionCoordsAcrossFormats, resolveDefaultsToLinearInLinearWorld, fastPathPureMcaDirectory), AnvilRegionScannerTest (unregisteredFormatIsSkipped, registeredFormatIsScanned), PregenBiomeExtractorTest (unregisteredFormatIgnored, registeredFormatPreferred), AnvilCorruptedRegionHardeningTest (incl. testUnregisteredFormatFailsClosed), Lz4BlockDecoderTest (differential vs lz4-java, truncation/forged-header/checksum rejection), AnvilLz4CompressionTest, AnvilRegionFuzzTest#fuzzLz4BlockDecoder, NbtUntrustedInputTest (depth boundary 512/513, 16M declared counts rejected with bounded allocation), AnvilRegionFuzzTest#fuzzNbtReaders, RTPArchitectureTest (no_blocking_future_calls_in_core_or_api, no_thread_instantiation_or_executors_outside_carveouts, no_synchronous_chunk_io_on_platform_world), ReqRtpMap002NoChunkIoTest, HotSinkTransferEligibilityTest, HotBudgetAllocatorTest, GroupSubspaceCacheTest, AnvilChunkViewTest (offTickRegionReadLayoutParseAndHeightmapTopYDecode, boundedMemoryUnderContinuousAllocationWithRetainedHeightmap), BukkitRTPWorldSyncFallbackTest, BiomeActivityTrackerTest, SubReloadCmdTest, LcaGoldenFixtureTest |
| REQ-RTP-S-006 | No undefined behaviour on early API access | ARCHITECTURE.md — rtp-api | RTPAPI.hooks(), RTPAPI.teleport(), RTPAPI.setServerAccessor() (contract surface). Shape/vert registration moved to RTP.addShape()/RTP.addVerticalAdjustor() extension tier (ADR-051) |
RTPAPIGuardTest (write-once guard), RtpApiTeleportSurfaceTest (pre-init ISE), RtpApiMenuDataSurfaceTest (menu-data reads: pre-init ISE, null-arg rejection, safe non-null degradation), RTPArchitectureTest (core_and_api_must_not_depend_on_platform_apis prevents early-access platform linkage errors) |
| REQ-RTP-S-007 | Configurable busy and invalid command messages | REQ-RTP-F-013, ARCHITECTURE.md | ConfigParser, MessagesKeys, BukkitBaseRTPCmd |
ReqRtpMenuConcreteCommandsTest, ConfigParserLanguageTest, RTPArchitectureTest (no_system_out_or_bukkit_getlogger_in_core_or_api guarantees command responses and audits route through configurable messaging and RTP.log) |
| REQ-RTP-S-004 (non-failure outcomes) | Completed, delayed, queued and cooldown/cost/usage-refused requests message the player; no log entry required; a blank configured message complies | REQUIREMENTS.md section 3 | PlayerMessages keys teleportMessage (TeleportPipelineTask), delayMessage, cooldownMessage, lockedAfterUses and notEnoughMoney (RTPCmd), queueUpdate (QueueTask, Region, ActionCommand) |
ReqRtpF013TeleportMessagePostStateTest (completed teleport), RTPCmdBranchTest (testFreePermissionBypassesBalanceFloorCheck, testToggleTargetPermsTargetCannotAffordRefundsSender) |
| REQ-RTP-MAP-001 | Require-by-contract MapBinding (extends REQ-RTP-S-006 to maps surface) |
ADR-046, maps-api-ADR-001 | NoopMapBinding (maps-api) |
ReqRtpMap001RequireByContractTest (Stage 1) |
| REQ-RTP-MAP-002 | No chunk I/O / no blocking .get() / .join() in ChartRenderer (extends REQ-RTP-F-008, REQ-RTP-S-005 to maps surface) |
ADR-046 | ChartRenderer, HeatmapRenderer (maps-api) |
ReqRtpMap002NoChunkIoTest (Stage 1; ArchUnit) |
| REQ-RTP-MAP-003 | MemoryTracker release on cancel / viewer disconnect / plugin disable |
ADR-046 | MapBindingLifecycle (maps-api, Stage 2.2, live), BukkitMapBinding (Stage 2.1/2.2, live; implements MapBindingLifecycle), MapDispatch.registerLifecycle / firePlayerQuit / fireDisable + MemoryTracker.track/untrack pair around paint() (rtp-core, Stage 2.2, live), OnPlayerQuit bridge + RTPBukkitPlugin#onDisable fireDisable call (rtp-plugin, Stage 2.2, live); FoliaMapBinding (rtp-folia-common, Stage 2.3, live; extends BukkitMapBinding, overrides bindLive with Folia-specific message, adds dispatchToViewerRegion hook for Stage 3 live-chart EntityScheduler dispatch). RTPBukkitPlugin#onEnable installs FoliaMapBinding on Folia and plain BukkitMapBinding elsewhere via isFolia() branch |
BukkitMapBindingTest (10 cases incl. onPlayerQuit / unknown-quit no-op / onDisable refusal), MapDispatchTest (10 cases incl. setMapBinding auto-register, firePlayerQuit fan-out + exception isolation, fireDisable clears registry); FoliaMapBindingTest (5 cases: type-hierarchy, Folia-specific bindLive message, offline-viewer dispatch no-op, null-arg rejection, unknown-quit no-op) |
| REQ-RTP-MAP-004 | Lite assembly ships the platform-backed MapBinding (map rendering is not excluded from Lite); NoopMapBinding is the fallback only |
ADR-046 (Amendment 2026-06-04), ADR-024 | BukkitMapBinding installed unconditionally by RTPBukkitPlugin#onEnable; FabricMapBinding (RTPFabricMod) and NeoForgeMapBinding (RTPNeoForgeMod) on their platforms; NoopMapBinding (maps-api) fallback only when no platform binding is installed |
liteJarStructureCheck (asserts mapsapi/** is not excluded from the lite jar); RTPBukkitPlugin#onEnable install |
| REQ-RTP-MAP-005 | Mermaid subset acceptance + no external runtime / scripting / layout library | ADR-046 Mermaid output | MermaidRenderer, MermaidParser, MermaidLayout, MermaidRasterizer (Stage 4) |
MermaidParserTest, MermaidRasterizerTest (Stage 4) |
| REQ-RTP-MAP-006 | Declarative chart composition bridge (ChartSpec + ChartSpecResolver + MapDispatch; extends REQ-RTP-F-008 / REQ-RTP-S-005 to chart-composition surface; failure paths under REQ-RTP-F-013 / REQ-RTP-S-004) |
ADR-047 | ChartSpec (rtp-api, Stage 1.A); ChartSpecResolver, ChartSpecResolvers, BadPointsHeatmapResolver, MapDispatch (rtp-core, Stage 1.B); ChartSpecTokens, MenuAction.OpenMap (sealed-record permit), MenuRedeemSubcommand.dispatchOpenMap, InfoBookBuilder map row, BookMenuRenderer OpenMap case arm (Stage 2 landed 2026-05-21) |
ChartSpecSurfaceTest (Stage 1.A); BadPointsHeatmapResolverTest, MapDispatchTest, ReqRtpMap006CoreNoPlatformImportTest (Stage 1.B); ChartSpecTokensTest (Stage 2.B, 21/21 green); MenuActionOpenMapBackcompatTest (Stage 2.A, deferred — sealed-record shape guarantees back-compat structurally) |
| REQ-RTP-OBS-001 | Non-blocking metrics snapshot (extends REQ-RTP-F-008 to metrics surface; M2 adds FoliaRegionSample per-region detail, RegionQueueRow and RegionQueueStatus per-region queue and cache status) |
METRICS_PLAN.md, metrics-api-ADR-001 | Metrics, MetricsSnapshot, MetricsBinding, FoliaRegionSample, MetricsExtension, RegionQueueRow, RegionQueueStatus (all in metrics-api, io.github.dailystruggle.metrics.api.*); CoreMetrics, RTPMetricsExtension (rtp-core) |
ReqRtpObs001CoreMetricsTest, ReqRtpObs001MetricsSnapshotTest, FoliaRegionSampleTest, RegionQueueRowTest, ReqRtpObs001RegionQueueStatusTest, InfoCmdTest (Folia-table render/suppress cases) |
| REQ-RTP-OBS-002 | Single-sample pipeline recording (one sample per TeleportPipelineTask on every exit path) |
METRICS_PLAN.md | PipelineHistogram, TeleportPipelineTask.runCleanup |
ReqRtpObs002PipelineHistogramTest, TeleportPipelineTaskPhaseTest#runCleanup_records_one_sample_into_pipeline_histogram |
| REQ-RTP-OBS-003 | Bounded heap / TPS / MSPT sampling cost (M2 extends to Folia per-region samplers and the Fabric / NeoForge server-tick samplers; bStats Runtime health charts consume the same snapshot). On the vanilla single-loop runtimes MSPT is sourced from the server's own average in-tick work duration, never from the sleep-padded tick interval (see Vanilla MSPT Source in METRICS_PLAN.md) | METRICS_PLAN.md, metrics-api-ADR-001, bstats-api-ADR-001 | HeapSampler (rtp-core), PaperMetricsBinding, BukkitTpsSampler, FoliaMetricsBinding, FoliaRegionTpsSampler, FabricMetricsBinding, NeoForgeMetricsBinding (platform adapters, implementing metrics-api MetricsBinding); tick-work sources wired at install: RTPFabricMod.reflectTickWorkNanos, RTPNeoForgeMod (MinecraftServer#getAverageTickTimeNanos); MetricsBindingDispatcher, RtpBStatsCatalogue + RtpBStats (rtp-core; bStats Runtime health chart group, sent via the bstats-api client) |
ReqRtpObs003HeapSamplerTest, PaperMetricsBindingTest, BukkitTpsSamplerTest, FoliaMetricsBindingTest, FabricMetricsBindingTest (incl. mspt_reports_work_duration_not_tick_interval, mspt_decreases_after_a_spike_subsides), NeoForgeMetricsBindingTest, RuntimeHealthBucketsTest, RtpBStatsTest, BStatsServiceTest, BStatsPlatformTest |
| REQ-RTP-OBS-004 | Pipeline-latency percentile readout (P50/P75/P90/P95/P99, on-demand, non-mutating, bounded cost) | ADR-053, METRICS_PLAN.md | PipelineHistogram.percentile/percentiles/Percentiles (rtp-core); PlaceholderProvider ([pipelineMsP50..P99], [pipelineSampleCount]); InfoCmd infoPipelinePercentiles |
ReqRtpObs004PipelinePercentilesTest |
| REQ-RTP-OBS-005 | Slow-teleport audit (immediate/unqueued only; opt-out threshold; WARN + cumulative slowPipelineCount) |
ADR-053 section 2a, METRICS_PLAN.md | CoreMetrics.auditImmediateTeleport/slowPipelineCount/slowPipelineThresholdMs, TeleportPipelineTask (immediateTeleport flag + runCleanup audit call), PerformanceKeys.slowPipelineThresholdMs, RTPMetricsExtension.slowPipelineCount/slowPipelineThresholdMs; InfoCmd infoSlowPipeline |
ReqRtpObs005SlowTeleportAuditTest |
| REQ-RTP-OBS-006 | Queue-growth audit (edge-triggered on queueDepth; opt-in threshold; WARN + cumulative queueGrowthWarnCount) |
ADR-053 section 2b, METRICS_PLAN.md | CoreMetrics.evaluateQueueGrowth/queueGrowthWarnCount/queueGrowthWarnThreshold, PerformanceKeys.queueGrowthWarnThreshold, RTPMetricsExtension.queueGrowthWarnCount/queueGrowthWarnThreshold; InfoCmd infoQueueGrowth |
ReqRtpObs005SlowTeleportAuditTest (queue-growth disabled-by-default + snapshot wiring cases) |
| REQ-RTP-OBS-007 | Generation-outcome operator surface (success/failure rate + per-cause rejection breakdown in /rtp info; the analogue of a competitor's /rtp unsafe-stats) |
ADR-052, METRICS_PLAN.md M1 | RtpOutcomeStats (rtp-core, process-global accumulator); PlaceholderProvider ([genSuccessRate]/[genFailureRate]/[genOutcomeTotal]/[genFailureBreakdown]/[genTopRejectionCause]/[genTopRejectionShare]); InfoCmd infoFailureRate/infoTopRejectionCause/infoFailureBreakdown |
RtpOutcomeStatsInfoPlaceholderTest, RtpOutcomeStatsAndCauseTaggingTest |
| REQ-RTP-METTS-001 | Publisher writes one row per (backend_id, metric_key, window_start_epoch) and re-publication is a no-op |
ADR-040 | AbstractSQLDatabaseAccessor, SQLiteDatabaseAccessor, H2DatabaseAccessor, MySQLDatabaseAccessor, PostgreSQLDatabaseAccessor, RedisMetricBucketAccessor, SqlMetricBucketStore, RedisMetricBucketStore, InMemoryMetricBucketStore, NetworkMetricTimeSeriesPublisher |
MetricBucketIdempotentInsertTest |
| REQ-RTP-METTS-002 | Publisher writes only from the configured published tier (24h@1m default) on promotion; per-sample and per-tick writes never occur |
ADR-040 | MetricsSnapshotRing, CoreMetrics, NetworkMetricTimeSeriesPublisher, NetworkTimeSeriesConfig |
MetricBucketTierPromotionOnlyTest |
| REQ-RTP-METTS-003 | Row payload carries (count, mean, min, max) and optional p95; mean-only and max-only payloads are rejected at construction and publisher boundary (plus S-006 pre-init guard on MetricTimeSeriesPublisher) |
ADR-040 | MetricBucketRow, MetricTimeSeriesPublisher (rtp-api), NetworkMetricTimeSeriesPublisher (rtp-core) |
MetricBucketHybridPayloadTest |
| REQ-RTP-METTS-004 | Per-pass batch cap (perPassWriteCap, default 64) is honored; overflow defers without silent drop and emits a structured S-004 warning |
ADR-040 | NetworkMetricTimeSeriesPublisher, NetworkTimeSeriesConfig, NetworkConfigCheck (advanced/network.yml) |
MetricBucketBatchCapAndOverflowTest |
| REQ-RTP-METTS-005 | Retention sweep deletes rows older than metrics.networkTimeSeries.retentionDays (default 7) for the local backend_id only |
ADR-040 | AbstractSQLDatabaseAccessor.purgeExpiredMetricBuckets, RedisMetricBucketAccessor.purgeExpiredMetricBuckets, NetworkMetricTimeSeriesPublisher.flushPass |
MetricBucketRetentionSweepTest |
| REQ-RTP-METTS-006 | Reader range-scan returns rows ordered by window_start_epoch and is consumed by ChartSnapshotAssembler off-thread without copying on the main/region thread (S-005) |
ADR-040, ADR-039 | AbstractSQLDatabaseAccessor.queryMetricBuckets, RedisMetricBucketAccessor.queryMetricBuckets, NetworkMetricTimeSeriesPublisher.rangeScan, ChartSnapshotAssembler |
MetricBucketReaderRangeScanTest |
| REQ-RTP-METTS-007 | Writer is dormant when metrics.networkTimeSeries.publish=false or when ADR-036 network mode is disabled (one structured startup warning in the mismatch case, zero writes otherwise) |
ADR-040 | NetworkMetricTimeSeriesPublisher.evaluateStartupGate, NetworkTimeSeriesConfig |
MetricBucketWriterDormantTest |
| REQ-RTP-METTS-008 | rtp_metric_bucket schema bootstrap is idempotent across PostgreSQL, MySQL, H2, and SQLite drivers and Redis sorted-set layout matches rtp:metric:<backend_id>:<metric_key> with EXPIRE and ZRANGEBYSCORE |
ADR-040 | AbstractSQLDatabaseAccessor.ensureMetricBucketSchema, SQLiteDatabaseAccessor, H2DatabaseAccessor, MySQLDatabaseAccessor, PostgreSQLDatabaseAccessor, RedisMetricBucketAccessor |
MetricBucketSchemaBootstrapTest |
| REQ-RTP-OPS-001 | Working defaults: the shipped config teleports safely on every Tested platform; setup is the artifact plus QUICK_START.md prerequisites; features needing more setup default off |
REQUIREMENTS.md section 1.9; ADR-036 (network mode off by default) | Shipped baseline configuration (rtp-plugin/src/main/resources/) |
Partial: devstack/run-versions-smoke.sh --fresh (Paper 26.3 and Fabric 26.3 boot on shipped defaults, rtp test accessor passes and queues fill, but no teleport is asserted); devstack/run-acceptance.sh teleports bots but seeds network.yml and demo regions. No run yet covers every Tested cell with unedited defaults |
| REQ-RTP-OPS-002 | Explained backpressure: tick-health gate, heap gate, per-region circuit breaker and load-driven budget reductions report cause and configured value on an operator surface, rate-limited | REQUIREMENTS.md section 1.9; ADR-087 section 6 (governor reductions) | ServerHealthGate#shouldPause / #warnStalled (WARN with readings and minTPS / maxMSPT, at most every 30 s; INFO on recovery); HeapPressureMonitor#underPressure (WARN with usage and maxHeapPercent, at most every 30 s; INFO on recovery); ComputeGovernor#logTransitionsIfNeeded (INFO on reason transition with 60 s cooldown and recovery log), GovernorBitComponent (GOVERNOR_KNOB_REDUCED, GOVERNOR_KNOB_AT_FLOOR, GOVERNOR_SIGNAL_STALE, GOVERNOR_EVALUATION_FAILED). Gap: ServerHealthGate#regionUnhealthy (per-region breaker) reports nothing |
ServerHealthGateTest, HeapPressureMonitorTest, ComputeGovernorTest (section8DesignTests), AnvilLiveParityAndCbitTest |
rtp-api Requirements¶
| Req ID | Summary | Design Ref | Implementing Class | Test(s) |
|---|---|---|---|---|
| REQ-API-F-001 | Shape registration | ARCH.md | SelectionAPI | - |
| REQ-API-F-002 | Vertical adjustors | ARCH.md | VerticalAdjustor | - |
| REQ-API-F-003 | Validation hooks | DESIGN.md section 2 | GlobalRegionVerifiers, ClaimBoundaryRegistry / ClaimBoundaryProvider | ClaimBoundaryRegistryTest, ClaimBoundaryProviderContractTest |
| REQ-API-F-004 | Agnostic models | ARCH.md | RTPLocation | - |
| REQ-API-F-005 | Command contract | commands-api-ADR-001 | commands-api | TreeCommandTabCompleteBranchTest |
| REQ-API-F-006 | Bare-/rtp root action | ADR-056 | RootActionRegistry / DefaultRTPHooks / RTPCmd | ReqApiF006RootActionTest |
| REQ-API-F-007 | Declarative command parameters, per-parameter permissions, and authoritative defaults (naming a specific player requires the declared parameter permission - closing the arbitrary-teleport hole; the declared default self/any/literal is the single source for the no-argument case; invalid symbolic defaults fail fast at load) |
ADR-098 (extends ADR-093) | ParameterType, ParameterSpec, ActionDefinition.CommandSpec (rtp-api); ActionConfigLoader.parseParameters, ActionCommand (rtp-core); RTPCommandSender.isRtpAdmin |
DeclarativeParameterTest (rtp-api), ActionCommandTest (testDeclarativeTargetPermissionDenied, testDeclarativeTargetPermissionAllowed, testDeclarativeDefaultSelfUnrestricted), ActionManagerTest (open-matchmaking vs targeted reciprocity) |
| REQ-API-F-008 | Addon web editor extensions (namespaced <id>.<type> messages routed, budgeted and rate-limited by core; protocol / extensions negotiation in the snapshot and hello-reply; tier 1 tabs rendered by the page from declarative widgets with no addon code in the page origin; declared addon YAML written only by Hot-Apply after the addon's validate, errors in apply_ack per REQ-RTP-S-004; extension calls isolated; registry fails closed per REQ-RTP-S-006) |
ADR-107 (extends ADR-106), DESIGN.md Web Editor Extensions | EditorExtension, EditorSession, EditorMessage, EditorDelivery, EditorTab / EditorWidget / EditorFrame (rtp-api, api.editor); EditorExtensionRegistry, RTPHooks.editorExtensions(); EditorExtensions, EditorChannel (namespace, delivery classes, extension shares), EditorChannelWiring, EditorSessionManager.collectCurrentConfigs / applyPayload, EditorLiveFeed (rtp-core); EditorChannelClient, EditorExtensionTabs, yamlSetScalar (docs/editor/index.html) |
EditorExtensionsTest, EditorExtensionConfigFilesTest, EditorExtensionTabsPageTest, EditorChannelPageContractTest |
| REQ-API-F-009 | BIT findings use registered stable int <-> key codes; action PBIT reports structural errors with file, key path, allowed values and suggestions; /rtp test registers the eight SAFE probes, exposes all, tier= and subsystem= selectors, optional JSON output and cached status; chat begins with worst-status component counts and lists only distinct FAIL/WARN/INFO findings; full uses fresh component health when available; SAFE startup PBIT runs action and anvil checks on Bukkit, Fabric and NeoForge |
ADR-121 | bit-api (BitFinding, BitReport, BitCode, BitCodeRegistry, BitCodeNamespace, BitRunner, BitComponent, BitResult, BitOutput, BitOutputs, BitTable); RtpBitCodes, RtpBitCodeCatalog, RtpBit, RtpBitComponents, RtpBitStartup, ProbeBitReport, BitTableOutput, TestAllCmd, TestApiCompatCmd, TestSchedulerCmd, TestEventsCmd, TestAccessorCmd, TestChunkTicketCmd, TestStatusCmd (rtp-core); BukkitBitCodeOwners, BitCodeCatalogExport, TestCmd, TestCommandsCmd, EconomyIsolationTestJob, DisconnectTestJob, NetworkSimulationTestJob, SafetyVerifierTestJob, TestFullCmd (rtp-plugin); platform startup hooks (rtp-plugin, rtp-neoforge-common) |
ActionDefinitionValidatorTest, RtpBitCodeOwnersTest, RtpBitComponentsTest, ProbeBitReportTest, ProbeComponentsTest, TestAccessorCmdTest, TestChunkTicketCmdTest, TestStatusCmdTest, BitTableOutputTest, TestApiCompatCmdTest, TestJsonParameterSyntaxTest, BitRunnerTest, BitTableTest (rtp-core); PluginProbeComponentsTest, TestCommandsCmdAuditTest, BitCodeCatalogTest, SafetyVerifierIsolationTest, TestCmdSelectorSyntaxTest, TestFullCmdTest, TestCmdPlatformSplitTest, NetworkSimulationTestJobTest (rtp-plugin); BitApiContractTest, BitCodeRegistryTest, BitLevelsTest, BitApiEdgeCaseTest, DriftCheckTest, BitApiBoundaryArchTest (bit-api) |
| REQ-API-F-009 (headless PBIT) | :rtp-core:bit runs the shared tier:pbit selector with strict action policy, emits schema-versioned JSON, and fails on any ERROR; -Paction=<id> also runs the selected action simulation; invalid action YAML is reported as BIT_PBIT_FAILED |
ADR-121 sections 8 and 11 | BitCli (bit-api); RtpBitCli, ActionConfigLoader#loadActionsDirectory, RtpBitComponents, ActionSimulator (rtp-core); agent-gate.py |
BitRunnerTest, RtpBitCliTest (rtp-core / bit-api) |
| REQ-API-F-009 (action self-test and simulation) | Bundled definitions run through the real parser, GateEvaluator and ActionSessionImpl; command mismatches fail the action subsystem; /rtp test action reports gate reasons and substituted commands without dispatching |
ADR-121 sections 4, 8 and 11; REQ-RTP-S-004/S-005 | ActionEngineSelfTest, ActionSimulator, GateTrace, TestActionCmd (rtp-core); RTPActionAddon (LeafRTPActionAddon) |
ActionEngineSelfTestTest, ActionSimulatorTest, TestActionCmdSyntaxTest, RtpBitCliTest (rtp-core); ActionEngineSelfTestAddonTest (LeafRTPActionAddon) |
| REQ-API-F-009 (teleport probe) | /rtp test teleport (IBIT, HEAVY, namespace TEST) teleports registered rtp-bit-* mock players through the real pipeline; server accessors resolve registered mocks first and never list them online; mocks leave no teleport history, usage-cap count, shared last-teleport time, LandingHeatmap landing, economy charge or refund, command event or Bukkit pipeline event; mock landings are kept in a bounded in-memory log; every report carries INFO TEST_TELEPORT_MOCKED |
ADR-121 section 11, ADR-104, REQ-RTP-S-002, REQ-RTP-S-004 | MockPlayerSession, SyntheticSideEffects, BitTeleportLog, MockTeleportRecord, RuntimeMockRTPPlayer, TeleportPipelineTask, EconomyGate, RTPTeleportCancel, RTPCommandEvents, TestTeleportCmd (rtp-core); AbstractServerAccessor (rtp-bukkit-common), AbstractFoliaServerAccessor (rtp-folia-common), FabricServerAccessor (rtp-fabric-common), NeoForgeServerAccessor (rtp-neoforge-common); BukkitEffectsHandler, TestCmd (rtp-plugin) |
MockPlayerSessionTest, MockPlayerRegistryTest, SyntheticSideEffectsTest, TeleportPipelineSinkSourceTest, EconomyGateMockPayerTest, RTPTeleportCancelRefundMockTest, RTPCommandEventsMockTest, TestTeleportCmdTest, ProbeBitReportTest, TestCmdPlatformSplitTest (rtp-core); BukkitServerAccessorTest, FoliaServerAccessorMockLookupTest, FabricServerAccessorPlayerLookupTest, NeoForgeServerAccessorMockLookupTest; BukkitEffectsHandlerMockEventsTest (rtp-plugin) |
| REQ-API-F-009 (runtime probe suite) | /rtp test stress, queue-starvation, disconnect-midflight, folia-ownership, async-reply and hologram register in the PROBE namespace; mock paths use MockPlayerSession, player-only paths use player=<name>, all async completions are cached, and every timeout maps to BIT_COMPONENT_TIMEOUT |
ADR-121 section 11; REQ-RTP-S-004/S-005 | ProbeVerdict, MockProbeWorld, TestStressCmd, QueueStarvationTestJob, TestDisconnectMidflightCmd, FoliaOwnershipTestJob, AsyncReplyTestJob, TestHologramCmd, TestFullCmd (rtp-plugin); RtpBitCodes (rtp-core) |
MockProbeComponentsTest, MockProbeSyntaxTest, PluginProbeComponentsTest, TestDisconnectMidflightCmdTest, TestStressCmdClampTest, TestHologramCmdTest, TestFullCmdTest (rtp-plugin) |
| REQ-API-F-009 (teleport heatmap probe) | /rtp test teleport-heatmap [region=<name>] [samples=N] is a named HEAVY IBIT component in namespace HEATMAP; it bins BitTeleportLog results to CSV/PNG without writing ADR-104 LandingHeatmap, performs real async selection chunk I/O, and reports BIT_COMPONENT_TIMEOUT plus INFO HEATMAP_MOCKED |
ADR-121 sections 10 and 11; REQ-RTP-S-002/S-004/S-005 | TestTeleportHeatmapCmd (rtp-plugin); BitLandingBins, BitHeatmapExport, BitTeleportLog (rtp-core) |
TestTeleportHeatmapCmdTest, MockProbeSyntaxTest (rtp-plugin); BitLandingBinsTest, BitHeatmapExportTest (rtp-core) |
| REQ-API-F-009 (action definition severity) | advanced/bit.yml configures structural action findings, per-code severity overrides, and registration rejection for effective errors; action PBIT checks placeholder scope, gate fields/expressions, scoreboard objectives, placement references, and vanilla payloads with source paths |
ADR-121 sections 4, 7 and 10; REQ-RTP-S-004 | BitSeverityPolicy, ActionConfigLoader, ActionDefinitionValidator, ActionPlaceholderSanitizer, ActionSessionImpl, GateEvaluator, GateExpressionParser, RtpBitComponents (rtp-core); RTPServerAccessor.hasScoreboardObjective, AbstractServerAccessor (rtp-api, rtp-bukkit-common) |
BitConfigYamlTest, BitSeverityPolicyTest, ActionConfigLoaderStrictActionsTest, ActionDefinitionValidatorTest, GateExpressionParserTest, BitApiContractTest |
| REQ-API-F-009 (action runtime CBIT) | Lock-free action counters identify missing objective reads, consistently passing/failing gates, unresolved placeholders, unknown runtime actions, and sessions active past the reaper window; /rtp test status and metrics expose live snapshots |
ADR-121 section 5; ADR-093 | ActionCbitCounters, GateEvaluator, ActionSessionImpl, TestStatusCmd, RTPMetricsExtension, CoreMetrics (rtp-core) |
ActionCbitCountersTest, TestStatusCmdTest, MetricsExtensionParityTest |
| REQ-API-F-009 (BIT code catalog) | Code identity is namespace-local (namespace, id, key); retirements remain reserved; the release lock rejects identity drift and severity changes; a prefix reserved by two owners is a startup BIT_NAMESPACE_CONFLICT ERROR; Markdown/JSON stay synchronized; class initialization does not register components |
ADR-121 section 10 | BitCodeRegistry, RetiredBitCode (bit-api); RtpBitCodes, RtpBitCodeCatalog, RtpBitCodeLock (rtp-core); RTPBukkitPlugin, BukkitBitCodeOwners, BitCodeCatalogExport (rtp-plugin) |
BitCodeRegistryTest, BitTableTest (bit-api); RtpBitCodeLockTest, RtpBitComponentBootstrapTest, RtpBitComponentsTest, RtpBitCodeOwnersTest, RtpBitCodeCatalogTest (rtp-core); BitCodeCatalogTest, PluginProbeComponentsTest, TestCmdPlatformSplitTest (rtp-plugin) |
| REQ-API-F-009 (addon setup BIT) | Action and Claim addons report setup and registration outcomes through separate SAFE PBIT components and per-addon, append-only namespace catalogs; first-boot overrides survive until addon code registration | ADR-121 sections 9-10 | ActionSetupBit, RTPActionAddon (LeafRTPActionAddon); ClaimSetupBit, ClaimIntegrations, RTPClaimAddon (LeafRTPClaimAddon); BitSeverityPolicy, RtpBitCodeCatalog, RtpBitCodeLock (rtp-core) |
ActionSetupBitTest, ActionSetupBitCatalogTest (LeafRTPActionAddon); ClaimSetupBitTest, ClaimSetupBitCatalogTest (LeafRTPClaimAddon); BitSeverityPolicyTest, RtpBitCodeNamespaceFilterTest (rtp-core) |
| REQ-API-F-009 (config PBIT) | YAML snapshots retain parser message keys; startup records YAML findings before parser recovery; reload, Hot-Apply, config-set, partial-reload, prefab, and setup candidates are checked before swap or write | ADR-121 sections 6-7; ADR-037 contract 7 | ConfigSnapshot, ConfigPbit, Configs#recordStartupYamlFindings, ConfigCandidateGate, SubConfigCmd, SubReloadCmd, ReloadSupport, PrefabDiskIO, PrefabConfirmCmd, SetupConfirmCmd |
ConfigSnapshotVaultYamlTest, ConfigsTest#initialLoadRecordsYamlFindingBeforeParserRecovery, ConfigCandidateGateTest, SubConfigCmdPbitGateTest, SubReloadCmdTest, PrefabDiskIOTest#render_returnsPendingYamlWithoutWritingFile, ConfigBitApiExtendedCoverageTest |
| REQ-API-F-009 (platform api-compat, anvil-live-parity, and pipeline CBIT) | TestApiCompatCmd supplies platform-family probe suites across Bukkit, Paper, Folia, Fabric, and NeoForge; anvil-live-parity validates real on-disk .mca/.linear chunk NBT palettes and heightmaps off-thread (S-005); PlatformHookBitComponent (PBIT) and PipelineCbitCounters (CBIT) emit structured findings for hook fallbacks, prefilter bailouts, stale-chunk trips, and ticket high-water marks |
ADR-121, ADR-015, ADR-016, ADR-077, ADR-113 | TestApiCompatCmd, TestBitCodes, PlatformHookBitComponent, PipelineCbitCounters, MenuBindingSupport, MenuRendererDiscovery, PregenTask, QueueTask, MemoryTracker (rtp-core); AnvilPrefilter, AnvilPrefilterMetrics, DataVersionSupport (anvil-api); AbstractServerAccessor, AbstractFoliaServerAccessor, FabricVersionAdapterRegistry, NeoForgeVersionAdapterRegistry |
AnvilLiveParityAndCbitTest, TestApiCompatCmdTest, RtpBitCliTest (rtp-core); BitCodeCatalogTest (rtp-plugin) |
| REQ-API-NF-001 | Semantic versioning | build.gradle version declarations |
— | — |
| REQ-API-NF-002 | Decoupling | ARCH.md, ADR-116 | ServerAccessor, PlatformFamily, ServerAccessors (server-api); RTPServerAccessor (rtp-api) |
ServerAccessorsTest, RtpApiStaticHubTest, BootstrapLogBufferTest, RTPArchitectureTest |
| REQ-API-ARCH-001 | Thread-safe API | DESIGN.md section 2 | FactoryValue | FactoryValueCoverageTest |
| REQ-API-ARCH-002 | Non-blocking API | DESIGN.md section 1 | ILocationGenerator | RTPArchitectureTest |
| REQ-API-ARCH-003 | API exception handling | DESIGN.md section 6 | TeleportPipelineTask | RTPAPIGuardTest |
| REQ-API-ARCH-004 | Lock-free reads | DESIGN.md section 1 | ConfigParser | ConfigParserLanguageTest, ConfigParserAndMultiConfigParserTest, ConfigLoaderAndLanguageBootstrapTest |
| REQ-API-ARCH-005 | Brigadier boundary | commands-api-ADR-001 (+ Addendum 2026-05-06, incl. Silent-failure isolation follow-up) | BrigadierCommandAdapter, BrigadierBridgeContext (commands-api); RTPCmdFabric (rtp-fabric-common) |
ReqApiArch005BrigadierBridgeTest (4 tests), BrigadierTreeShapeTest (9 tests — recursion + sibling-chain + cycle-guard + per-subcommand/parameter/suggestion/requires throw isolation, 2026-05-06), BrigadierArgsSuggestionEdgeCaseTest (greedy-argument suggestion and permission edge cases) |
rtp-core Requirements¶
| Req ID | Summary | Design Ref | Implementing Class | Test(s) |
|---|---|---|---|---|
| REQ-CORE-F-001 | Async queue | DESIGN.md section 1 | RegionQueueManager | FailureModeTest |
| REQ-CORE-F-002 | Bounded refill | DESIGN.md section 1 | RegionCacheTask, Region, GenerationBudget |
GenerationBudgetTest, RegionTickBudgetTest |
| REQ-CORE-F-003 | Uniform distribution | DESIGN.md section 3 | MemoryShape | MemoryShapeTest |
| REQ-CORE-F-004 | Deterministic execution | DESIGN.md section 3 | MemoryShape | RegionPipelineTest |
| REQ-CORE-F-005 | Spatial memory (a mark inside the shape's addressable annulus [centerRadius, radius) is retained exactly; one outside it is counted by getOutOfDomainMarkCount() and logged rather than dropped unrecorded, per REQ-RTP-S-004) |
DESIGN.md section 3 | MemoryShape; MemoryShape.addBadLocation / reportOutOfDomainMark; Square.xzToLocation; TtlConfig.isTransient (ADR-079: timeout / nullChunk / ungenerated marks are not stored by the cause-TTL overloads, and ttl.yml overrides for them are ignored) |
MemoryShapeTest, SquareRetentionTest, Adr079CauseTtlAndStagedExpirationTest (testTransientCausesAreNotStored, testTransientCauseOverrideIgnored) |
| REQ-CORE-F-006 | DB integration | DESIGN.md section 4 | DatabaseAccessor | - |
| REQ-CORE-F-007 | Task lifespan | DESIGN.md section 6 | MemoryTracker | - |
| REQ-CORE-F-008 | Orphaned chunk recovery | DESIGN.md section 6 | ChunkUnloadProcessor | - |
| REQ-CORE-F-009 | Backlog cache (order-preserving FIFO; head-blocking promotion on UNVERIFIED and UNKNOWN; head-drop on INVALIDATED; region-file bins pre-filtered off the pulse thread with no chunk load; VALIDATED entries drain into cold with no load; UNKNOWN entries are taken one at a time by the cold fill; refill bounded by the pulse budget less 20% headroom; cold fills in flight capped by the cache deficit and paced by each fill's wall time from dispatch to slot release, with no single-flight gate; a fill unfinished after 600 ticks releases its slot and charges at least that deadline to the pacer, and a later result is dropped with its reservation closed; a failed per-player fill releases its slot; cold-to-hot promotion runs border, biome, safety and claims after the vertical adjustor). Named L3 by ADR-028; the vocabulary is retired to hot/cold/backlog by ADR-078 phase 2 |
DESIGN.md section 1.1, ADR-028 (amendment 2026-10-13), ADR-110 | BacklogLocationBuffer (#pollOldest), BacklogBinVerifier, WorldBacklogBinIndex, RegionFileCoord, RegionQueueManager.backlogLocations, Region.processBacklog / #drainValidatedToCold / #refillDeadline / #promotionChecks / #execute (cache deficit), RegionCacheTask (implements CompletionPaced; FILL_DEADLINE_TICKS), CompletionPaced, PregenTask (PregenState.backlog) |
BacklogLocationBufferTest, RegionCacheFillPacingTest (pendingFillDoesNotSerialiseRegion, completionWallTimeFeedsPacer, slowFillsSlowNewStarts, neverCompletingFillReleasesAtDeadline, lateResultAfterDeadlineIsDropped), WorldBacklogBinIndexTest, RegionFileCoordTest, BacklogBinVerifierTest, RegionLifecycleAndBranchTest (pre-filter outcomes route entries; the backlog never loads or tickets a chunk; time-bounded refill), PregenTaskLoadPurposeTest (cold fill checks UNKNOWN entries), RegionPromotionChecksTest, RegionBacklogOutcomeStatsTest, CacheNomenclatureGuardTest (ADR-078 phase 2: production sources and the shipped rtp-plugin yml config/locale tree carry no L1/L2/L3 tier vocabulary) |
| REQ-CORE-F-010 | Emergency-platform block-restoration timeout (chunk-loaded countdown, no force-load per REQ-RTP-S-005; DB-persisted resume; row removed on completion; restore failure audited per REQ-RTP-S-004) | ADR-060 | PlatformRestoreManager, PlatformRestoreSqlStore (rtp-core); BlockDelta, PendingPlatformRestore, RTPWorld.restoreBlocks (rtp-api); BukkitRTPWorld.platform/restoreBlocks, FoliaRTPWorld.platform/restoreBlocks; SafetyKeys.platformRestoreSeconds |
ReqRtpAdr060PlatformRestoreTest (7 cases) |
| REQ-CORE-F-011 | Cost-governed on-demand chunk reads & thread-weighted deduplication (three-tier resolution, zero-decode MCA occupancy check, empirical deduplication threshold bypassing Anvil when acceptance is high, hazard shedding off-thread when unsafe; native-load cost recorded on failure and ticket-apply timeout as well as success) | ADR-114 | ImmediateLoadGovernor, ImmediateGovernorRow, PregenTask (#requestChunkImmediate, #loadChunk), CoreMetrics, RTPMetricsExtension |
ImmediateLoadGovernorTest, OnDemandChunkReadBenchmarkTest, ImmediatePermitScopeTest, SpatialDistributionFidelityTest |
| REQ-CORE-F-012 | Adaptive compute governance (autoTune: per-pulse credit-bucket refill with water-filled demand allocation, overrun carry-forward debt $d_A$/$d_S$, shared pulse/tick background deadline ranAnyBg/ranAnyBgSync, MiscTasks.backgroundSync(), player-facing playerQueue shortfall protection, lag-aware AimdLimiter with stale hold, and compute-governor CBIT probe; invariants I2–I8, I10–I12) |
ADR-087 | ComputeGovernor, ComputeBudget, ComputeSignals, GovernorReason, RuntimeSignalSource, GovernorBitComponent, AimdLimiter, AsyncTaskProcessing, SyncTaskProcessing, MiscTasks, TickBudget, Region (#executePlayerFacing, #execute), SelectionAPI (#computeUrgent, #computeStandard), LiveLoadGate, GenerationBudget, ImmediateLoadGovernor |
ComputeGovernorTest, AimdLimiterTest, RegionTickBudgetTest, AsyncTaskProcessingTest, SyncTaskProcessingTest, RTPInstanceStateHoldersTest, RTPArchitectureTest (governor_package_must_not_create_threads_or_use_locks, governor_package_must_not_depend_on_selection_tasks_or_tools) |
| REQ-PRED-F-001 | Unified EWMA Estimator (dual fractional alpha and 7/8 integer decay with bitwise parity and Welford variance) | unified-predictive-cost-modeling | EwmaEstimator |
EwmaEstimatorTest, TimeBoundTaskPipeCharacterizationTest |
| REQ-PRED-F-002 | Bernoulli Outcome Estimator (binary success/rejection/failure probability tracking with bounded smoothing) | unified-predictive-cost-modeling | BernoulliEstimator |
BernoulliEstimatorTest |
| REQ-PRED-F-003 | Predictive Budget Pacer (forward progress guarantee on positive budget, overrun halting on zero/negative budget) | unified-predictive-cost-modeling | BudgetPacer |
BudgetPacerTest, TimeBoundTaskPipeCharacterizationTest, TimeBoundTaskPipeTest |
| REQ-PRED-F-004 | Comparative Cost Governor & AIMD Limiter (domain-agnostic branch selection, variance-gated hysteresis, coalesced cost linear fit, and lag-aware AIMD limiter) | unified-predictive-cost-modeling, ADR-087, ADR-109, ADR-114 | ComparativeCostGovernor, CostContext, EwmaLinearFit, WorkAttributionLedger, AimdLimiter |
ComparativeCostGovernorTest, AimdLimiterTest, ProbeFirstGovernorTest, ImmediateLoadGovernorTest, EwmaLinearFitTest, WorkAttributionLedgerTest |
| REQ-PRED-F-005 | Characterization-Backed Refactoring (TimeBoundTaskPipe, DatabaseAccessor, Region backlog, ImmediateLoadGovernor) | unified-predictive-cost-modeling | TimeBoundTaskPipe, CompletionPaced, DatabaseAccessor, Region, ImmediateLoadGovernor |
TimeBoundTaskPipeCharacterizationTest, ImmediateLoadGovernorTest, RegionTickBudgetTest, RegionCacheFillPacingTest |
| REQ-CORE-ARCH-001 | Lock-free config | DESIGN.md section 1 | FactoryValue | ConfigParserLanguageTest |
| REQ-CORE-ARCH-002 | Data access pattern | DESIGN.md section 1 | FactoryValue.getData() | MultiConfigParserIsolationTest |
| REQ-CORE-ARCH-003 | Fault encapsulation | DESIGN.md section 6 | TeleportPipelineTask, Configs#reload, SubReloadCmd, EffectDispatch, SpongeSchematicDecoder, AbstractFileSchematicPaster |
ConfigsReloadFailureTest, SubReloadCmdTest, EffectDispatchTest, FoliaDispatchTest, SpongeSchematicDecoderTest, AbstractFileSchematicPasterCacheTest, RegionSchematicServiceTest |
| REQ-CORE-ARCH-004 | runCleanup() | DESIGN.md section 6 | TeleportPipelineTask | - |
| REQ-CORE-ARCH-005 | Pulse maintenance | DESIGN.md section 1, ADR-087, ADR-112 | AsyncTaskProcessing (credit-ordered region turns per pulse when autoTune is active, or one region turn per period ticks when disabled; sole cancelTasks drainer), TickBudget (backgroundAsyncNanos, backgroundSyncNanos, backgroundPeriodTicks), ComputeGovernor, ComputeBudget, RuntimeSignalSource, ServerHealthGate (minTPS / maxMSPT pause of background refill; mean across regions when MetricsBinding#regionalTicking; #regionUnhealthy per region via MetricsBinding#regionTps1m/#regionMspt), Region#execute (ComputeBudget#promotionsPerTurn(), ComputeBudget#hotCap(region), ComputeBudget#unitsPerTurn(region); candidates in regions reported by RTPScheduler#isRegionSaturated stay cold) |
ComputeGovernorTest, AsyncTaskProcessingTest, TickBudgetTest, ServerHealthGateTest, RegionTickBudgetTest (saturatedRegionCandidatesStayCold, executePlayerFacingPromotesForWaitingPlayerWhenBackgroundThrottled), SparkMetricsBindingTest |
| REQ-CORE-ARCH-006 | Time-bounded tasks | DESIGN.md section 1 | TimeBoundTaskPipe (zero budget runs nothing; positive budget runs at least one; a CompletionPaced task is bound to the pipe's pacer and reports its own completion cost instead of its run() time), CompletionPaced, SyncTaskProcessing (commands and actions charged before the misc pipe), SelectionAPI#compute(long) |
SyncTaskProcessingTest, TimeBoundTaskPipeTest, RegionTickBudgetTest, RegionCacheFillPacingTest (completionWallTimeFeedsPacer, slowFillsSlowNewStarts) |
| REQ-CORE-ARCH-007 | Tracker registration | DESIGN.md section 6 | MemoryTracker | - |
| REQ-CORE-ARCH-008 | Max lifespan | DESIGN.md section 6 | MemoryTracker | - |
| REQ-CORE-ARCH-009 | Accessor injection | ARCH.md | RTP.java | RTPArchitectureTest |
| REQ-CORE-ARCH-010 | No platform imports | ARCH.md | rtp-core package | RTPArchitectureTest |
| REQ-CORE-ARCH-011 | In-flight native generation admission bounds & tick damping (regional semaphore max 1, global semaphore governed by ComputeBudget#generationCap() and knee ComputeBudget#cpuTarget(), bounded FIFO queue with 1200ms timeout failing to msgBusy per S-004/S-007; applies to ungenerated chunks only, loads of chunks already on disk take no permit) |
ADR-087, ADR-114, ADR-110 | ImmediateLoadGovernor, GenerationBudget, LiveLoadGate, PregenTask#admitNativeLoadWithPermit |
ImmediateLoadGovernorTest, ComputeGovernorTest, OnDemandChunkReadBenchmarkTest (concurrent generations stay under the permit limit), ImmediatePermitScopeTest (generatedChunkLoadDoesNotWaitForPermit, ungeneratedChunkLoadWaitsForPermit) |
| REQ-CORE-NF-001 | Shutdown flush | DESIGN.md section 4 | RTP.stop() | MemoryShapeShutdownTest |
| REQ-CORE-MIG-001 | Foreign config import and migration seam (/rtp config import <plugin>) |
ADR-066 | ForeignConfigImporter, ForeignConfigImporterRegistry, BetterRtpConfigImporter, JustRtpConfigImporter, EzRtpConfigImporter, JakesRtpConfigImporter, PermissionMigrationService, ConfigImportCmd |
ConfigImporterTest, PermissionMigrationTest |
rtp-bukkit Requirements¶
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-SPIGOT-F-001 | Synchronous chunk loading | DESIGN.md section 2 — rtp-bukkit | rtp-bukkit adapter (Bukkit chunk API), BukkitRTPPlayer#setLocation |
BukkitSchedulerImplTest (runTask_onPrimaryThread_executesImmediately, runTaskAsynchronously_dispatchesTask_andCompletes), BukkitRTPPlayerSetLocationTest |
| REQ-SPIGOT-F-002 | Rate-limited sync tasks | DESIGN.md section 1 — Bounded Computation Overhead | TimeBoundTaskPipe (spigot binding) |
Manual verification required (TimeBoundTaskPipe core logic covered by SLATest) |
| REQ-SPIGOT-F-003 | Platform event routing | ARCHITECTURE.md — rtp-bukkit | Spigot event listeners → rtp-core handlers |
Manual verification required |
| REQ-SPIGOT-ARCH-001 | addPluginChunkTicket over setForceLoaded |
DESIGN.md section 6 — Chunk Allocation Management | rtp-bukkit chunk reservation impl |
ChunkTicketLifecycleTest (ticket_is_held_during_reservation_and_released_on_close) |
| REQ-SPIGOT-ARCH-002 | Plugin-owned ticket leak prevention | DESIGN.md section 6 — Chunk Allocation Management | rtp-bukkit chunk reservation impl |
Manual verification required |
| REQ-SPIGOT-ARCH-003 | TimeBoundTaskPipe for main-thread ops |
DESIGN.md section 1 — Bounded Computation Overhead | TimeBoundTaskPipe |
BukkitSchedulerImplTest (runTask_onPrimaryThread_executesImmediately) |
| REQ-SPIGOT-ARCH-004 | Wall-clock time bounding | DESIGN.md section 1 — Bounded Computation Overhead | TimeBoundTaskPipe (nanosecond budget) |
BukkitSchedulerImplTest (runTaskTimer_returnsNonNullBukkitTaskHandle, cancelTask_preventsScheduledTaskFromRunning) |
| REQ-SPIGOT-ARCH-005 | Ticket lifecycle pairing | DESIGN.md section 6 — Chunk Allocation Management | rtp-bukkit removePluginChunkTicket call sites |
ChunkTicketLifecycleTest (ticket_is_held_during_reservation_and_released_on_close, ticket_is_released_even_when_validator_throws) |
| REQ-SPIGOT-ARCH-006 | Forced reclamation on disconnect | DESIGN.md section 6 — Orphaned Allocation Recovery | MemoryTracker + spigot cleanup listener |
Manual verification required |
rtp-paper Requirements¶
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-PAPER-F-001 | Non-blocking chunk load and async entity teleport (teleportAsync) |
DESIGN.md section 2 — rtp-paper | rtp-paper async chunk impl, PaperRTPPlayer#setLocation |
PaperRTPPlayerSetLocationTest |
| REQ-PAPER-F-002 | Callback/future-only, no sync waits | DESIGN.md section 2 — rtp-paper | rtp-paper async chunk impl; BukkitRTPWorld#loadChunkFuture / #requestChunkAsync (no synchronous getChunkAt fallback: a missing, failing or null async load rejects the candidate, REQ-RTP-S-005); BukkitRTPWorld#keepChunkAt (async load only; cache and ticket follow a successful load) |
RTPArchitectureTest (no_blocking_future_calls_in_core_or_api), BukkitRTPWorldSyncFallbackTest (6 tests, incl. keepChunkAtUsesAsyncLoadOnly, keepChunkAtFailedLoadKeepsNothing) |
| REQ-PAPER-F-003 | Paper-specific API prioritization | DESIGN.md section 2 — rtp-paper | rtp-paper adapter |
ServerAccessorImplTest (getBiomes_returnsNonEmptyUpperCaseSet — asserts Registry.BIOME path) |
| REQ-PAPER-ARCH-001 | addPluginChunkTicket over setForceLoaded |
DESIGN.md section 6 — Chunk Allocation Management | rtp-paper chunk reservation impl |
ChunkTicketLifecycleTest (ticket_is_held_during_reservation_and_released_on_close) |
| REQ-PAPER-ARCH-002 | Plugin-owned ticket leak prevention | DESIGN.md section 6 — Chunk Allocation Management | rtp-paper chunk reservation impl |
— |
| REQ-PAPER-ARCH-003 | TimeBoundTaskPipe for main-thread ops |
DESIGN.md section 1 — Bounded Computation Overhead | TimeBoundTaskPipe (paper binding) |
ServerAccessorImplTest (paperScheduler_runTask_executesOnPrimaryThread) |
| REQ-PAPER-ARCH-004 | Wall-clock time bounding | DESIGN.md section 1 — Bounded Computation Overhead | TimeBoundTaskPipe (nanosecond budget) |
— |
| REQ-PAPER-ARCH-005 | Ticket lifecycle pairing | DESIGN.md section 6 — Chunk Allocation Management | rtp-paper removePluginChunkTicket call sites |
ChunkTicketLifecycleTest (ticket_is_held_during_reservation_and_released_on_close, ticket_is_released_even_when_validator_throws) |
| REQ-PAPER-ARCH-006 | Forced reclamation on disconnect | DESIGN.md section 6 — Orphaned Allocation Recovery | MemoryTracker + paper cleanup listener |
— |
rtp-folia Requirements¶
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-FOLIA-F-001 | Regional thread isolation | DESIGN.md section 2 — rtp-folia | rtp-folia regional task dispatcher |
— |
| REQ-FOLIA-F-002 | RegionScheduler / EntityScheduler usage |
DESIGN.md section 2 — rtp-folia | rtp-folia scheduler impl |
RTPArchitectureTest (scheduler_implementations_must_not_reside_in_core) |
| REQ-FOLIA-F-003 | Concurrent state mutation safety | DESIGN.md section 2 — rtp-folia | rtp-folia adapter, LockFreeLocationBuffer, RegionQueueManager |
LockFreeLocationBufferConcurrencyStressTest, RegionQueueManagerConcurrencyStressTest |
| REQ-FOLIA-F-004 | Cross-region teleport pipelining | DESIGN.md section 2 — rtp-folia | TeleportPipelineTask + folia scheduler |
— |
| REQ-FOLIA-ARCH-001 | isOwnedByCurrentRegion pre-check |
DESIGN.md section 2 — rtp-folia | rtp-folia regional dispatcher |
— |
| REQ-FOLIA-ARCH-002 | Immediate execution if region owned | DESIGN.md section 2 — rtp-folia | rtp-folia regional dispatcher |
— |
| REQ-FOLIA-ARCH-003 | RegionScheduler.run() only when not owned |
DESIGN.md section 2 — rtp-folia | rtp-folia regional dispatcher |
— |
| REQ-FOLIA-ARCH-004 | Per-region-thread budget (syncAllottedTime per region tick, no accumulation) |
DESIGN.md section 2 — rtp-folia, ADR-112 | RegionThreadBudget, FoliaSchedulerImpl slices |
RegionThreadBudgetTest, FoliaSchedulerRegionSliceTest |
| REQ-FOLIA-ARCH-005 | CountBoundTaskPipe for iterative ops |
DESIGN.md section 2 — rtp-folia | rtp-folia queue replenishment; CountBoundTaskPipe (delays, cancellation, per-task isolation) |
CountBoundTaskPipeTest |
| REQ-FOLIA-ARCH-006 | Count-based task slicing | DESIGN.md section 2 — rtp-folia, ADR-112 | rtp-folia CountBoundTaskPipe binding (regional dispatches count toward the slice; also time-bound with a one-task floor); FoliaSchedulerImpl regional limiter (atomic permits, FIFO deferred queue, ADR-087) |
CountBoundTaskPipeTest, FoliaSchedulerLimiterTest, FoliaSchedulerGovernanceTest |
| REQ-FOLIA-ARCH-013 | Per-region work division: one budgeted FIFO slice per region cell, leftovers re-queued behind other regions, inline only within budget, slow or late regions paced to one task per slice | ADR-112, ADR-087 sections 3.4 and 3.6 | FoliaSchedulerImpl (cells, slices, #isRegionSaturated), RegionThreadBudget (syncAllottedTime per region thread) |
FoliaSchedulerRegionSliceTest, RegionThreadBudgetTest |
| REQ-FOLIA-ARCH-014 | Chunk-future continuations leave the region thread | ADR-112 | FoliaRTPWorld#OFF_REGION (loadLiveChunk, getChunkAtAsync); PregenTask (#anySafetyChunkLoaded live safety scan dispatched to the centre region whenever any chunk in safetyRadius is resident); TeleportPipelineTask#continueOffRegion; BukkitHandles (cached IS_FOLIA probe and player-targeted effect entity-scheduler dispatch) |
FoliaRTPWorldChunkTicketTest (chunkFutureContinuationsLeaveTheRegionThread, chunkFutureCompletesInlineWithoutPlugin), PregenTaskSafetyTest, FoliaDispatchTest |
| REQ-FOLIA-ARCH-007 | No Vault calls on region threads | DESIGN.md section 2 — rtp-folia | rtp-folia economy delegation |
— |
| REQ-FOLIA-ARCH-008 | Economy delegated to GlobalRegionScheduler |
DESIGN.md section 2 — rtp-folia | rtp-folia economy delegation |
— |
| REQ-FOLIA-ARCH-009 | Async economy result pipelining | DESIGN.md section 2 — rtp-folia | rtp-folia economy delegation |
— |
| REQ-FOLIA-ARCH-011 | Chunk tickets applied on the owning region | DESIGN.md section 2 — rtp-folia, REQ-RTP-S-002 | FoliaRTPChunk#keep (latest wanted state, single release) |
FoliaRTPChunkKeepTest |
| REQ-FOLIA-ARCH-012 | Per-region tick health for load shedding | ADR-087, ADR-112, REQ-CORE-ARCH-005 | FoliaMetricsBinding#observeRegion, #worstTps1m, #worstMspt, #regionTps1m, #regionMspt, #regionalTicking |
FoliaMetricsBindingTest |
| REQ-FOLIA-ARCH-010 | Native Folia async chunk APIs | DESIGN.md section 2 — rtp-folia | rtp-folia chunk impl; FoliaRTPWorld#setForceLoadedImpl (async preload, ticket applied on the owning region, release cancels a pending add, REQ-RTP-S-002/S-005); FoliaRTPWorld#keepChunkAt (async load only) |
FoliaRTPWorldChunkTicketTest (9 tests) |
rtp-fabric Requirements¶
Fabric is in-scope per rtp-fabric-ADR-002 (Accepted; renumbered from ADR-022). Requirements defined in platforms/rtp-fabric/REQUIREMENTS.md.
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-FABRIC-F-001 | Server Accessor Implementation | rtp-fabric-ADR-002 | FabricServerAccessor |
ReqRtpFabricServerAccessorNoChatTypesTest |
| REQ-FABRIC-F-002 | World Adapter | rtp-fabric-ADR-002, rtp-fabric-ADR-005 | FabricRTPWorld, FabricRTPChunk |
ReqRtpS005FabricAnvilChunkTest |
| REQ-FABRIC-F-003 | Player Adapter | rtp-fabric-ADR-002, rtp-fabric-ADR-011 | FabricRTPPlayer, FabricRTPPlayerUnobf, V26_*FabricRTPPlayer, FabricEffectivePermissionsResolver, common.commands.SenderTimings |
FabricDefaultPermissionsParityTest, FabricEffectivePermissionsTest, SenderTimingsTest |
| REQ-FABRIC-F-004 | Scheduler Implementation | rtp-fabric-ADR-002 | FabricScheduler |
FabricSchedulerTimerTest |
| REQ-FABRIC-F-005 | Co-located Metadata | rtp-fabric-ADR-002 section 2 | rtp-plugin distribution assembly, fabric.mod.json |
PluginPlatformPackageBoundaryArchTest |
| REQ-FABRIC-F-006 | Disjoint Entry Points | rtp-fabric-ADR-002 section 2 | RTPFabricMod, FabricRTPCommonEntry, RTPBukkitPlugin |
PluginPlatformPackageBoundaryArchTest, RtpFabricCarriersDisjointTest |
| REQ-FABRIC-F-007 | Server Lifecycle Wiring | rtp-fabric-ADR-002 | FabricEventBridge, RTPFabricMod |
FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-F-008 | Tick-Driven Scheduling | rtp-fabric-ADR-002 | FabricScheduler (end-of-tick drain bounded by syncAllottedTime, bounded async pool, non-overlapping async timers), FabricEventBridge |
FabricSchedulerTimerTest, FabricSchedulerBudgetTest |
| REQ-FABRIC-F-009 | World Cache Maintenance | rtp-fabric-ADR-002 | FabricEventBridge, FabricServerAccessor |
FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-F-010 | Player Session Tracking | rtp-fabric-ADR-002, ADR-049 | FabricPlayerLifecycleHook, FabricEventBridge |
FabricPlayerLifecycleHookTest, FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-F-011 | Login reserve cache wiring (ADR-023): default-world bootstrap + Disconnect refill + Join consumption (firstjoin via playerdata/<uuid>.dat) |
ADR-023 | FabricEventBridge.initLoginReserveCache / refillLoginReserveOnQuit / dispatchJoinRtp; FabricOnEventTeleports.onJoin / primeFromLoginCache / hasPlayedBefore; perm gate via FabricRTPPlayer.hasPermission |
ReqFabricAdr023HasPlayedBeforeTest (6 tests — covers the first-join branch of the consumption path; promotion + region attachment paths are exercised via rtp-core's RegionPipelineTest) |
| REQ-FABRIC-ARCH-001 | No Bukkit Imports | rtp-fabric-ADR-002 section 4 | platforms/rtp-fabric/** |
RTPArchitectureTest (core_and_api_must_not_depend_on_platforms), PluginPlatformPackageBoundaryArchTest |
| REQ-FABRIC-ARCH-002 | No Core Pollution | rtp-fabric-ADR-002 section 4 | rtp-core, rtp-api |
RTPArchitectureTest (core_and_api_must_not_depend_on_platforms), ReqRtpMap006CoreNoPlatformImportTest |
| REQ-FABRIC-ARCH-003 | Loom Plugin Scope | rtp-fabric-ADR-002 section 4, effects-api-ADR-003 |
Gradle build configuration (platforms/rtp-fabric/build.gradle, rtp-plugin/build.gradle) |
PluginPlatformPackageBoundaryArchTest |
| REQ-FABRIC-ARCH-004 | Asynchronous Chunk Loading (S-005) | ADR-015/016, rtp-fabric-ADR-005, REQ-RTP-S-005 | FabricRTPWorld#getChunkAt, FabricRTPChunk |
ReqRtpS005FabricAnvilChunkTest |
| REQ-FABRIC-ARCH-005 | Failure Attribution (S-004) | DESIGN.md section 1, REQ-RTP-S-004 | FabricRTPWorld, FabricRTPPlayer |
ModClaimCheckFailureRuleS003Test, FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-ARCH-006 | Memory Hygiene | DESIGN.md section 6, REQ-RTP-S-002 | FabricEventBridge, FabricPlayerLifecycleHook, FabricServerAccessor |
FabricPlayerLifecycleHookTest, FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-ARCH-007 | Fail-Loud on Unimplemented Surface | ARCHITECTURE.md, REQ-RTP-S-006 | FabricServerAccessor, FabricVersionAdapter |
FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-ARCH-008 | Pre-Init Guard | ARCHITECTURE.md, REQ-RTP-S-006 | FabricVersionAdapterRegistry#require, FabricServerAccessor |
FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-ARCH-009 | Config Directory Resolution | rtp-fabric-ADR-002 section 3 | FabricServerAccessor#getPluginDirectory, FabricDatabaseHandler |
FabricEventBridgeAdapterDispatchTest |
| REQ-FABRIC-ARCH-010 | Database Delegation | rtp-fabric-ADR-002 | FabricDatabaseHandler, DatabaseProcessing |
DatabaseProcessing core test suite |
rtp-neoforge Requirements¶
NeoForge is in-scope per ADR-033 and rtp-neoforge-ADR-001 (Accepted). Requirements defined in platforms/rtp-neoforge/REQUIREMENTS.md. Functional parity and architectural compliance are fully implemented and verified.
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-NEOFORGE-F-001 | Server Accessor Implementation | ADR-033, rtp-neoforge-ADR-001 | NeoForgeServerAccessor |
NeoForgeServerIntVersionTest, ReqRtpNeoforgeS006ApiBeforeCoreTest |
| REQ-NEOFORGE-F-002 | World Adapter | ADR-033, rtp-neoforge-ADR-001 | NeoForgeRTPWorld, NeoForgeRTPChunk |
ReqRtpNeoforgeS005ChunkLoadingTest |
| REQ-NEOFORGE-F-003 | Player Adapter | ADR-033, rtp-neoforge-ADR-001 | NeoForgeRTPPlayer, NeoForgeEffectivePermissionsResolver, common.commands.SenderTimings |
NeoForgeDefaultPermissions, LuckPermsNeoForgeEnumerator, SenderTimingsTest |
| REQ-NEOFORGE-F-004 | Scheduler Implementation | ADR-033, rtp-neoforge-ADR-001 | NeoForgeScheduler |
NeoForgeSchedulerTimerTest |
| REQ-NEOFORGE-F-005 | Mod Metadata | ADR-033, rtp-neoforge-ADR-001 | RTPNeoForgeMod, META-INF/neoforge.mods.toml |
rtp-plugin build merge gate |
| REQ-NEOFORGE-F-006 | Disjoint Entry Points | ADR-033, rtp-neoforge-ADR-001 | RTPNeoForgeMod, RTPFabricMod, RTPBukkitPlugin |
PluginPlatformPackageBoundaryArchTest |
| REQ-NEOFORGE-F-007 | Server Lifecycle Wiring | ADR-033, rtp-neoforge-ADR-001 | NeoForgeEventBridge, RTPNeoForgeMod |
NeoForgeTestUmbrellaWiringTest |
| REQ-NEOFORGE-F-008 | Tick-Driven Scheduling | ADR-033, rtp-neoforge-ADR-001 | NeoForgeScheduler (end-of-tick drain bounded by syncAllottedTime, bounded async pool, non-overlapping async timers), RTPNeoForgeMod |
NeoForgeSchedulerTimerTest, NeoForgeSchedulerBudgetTest |
| REQ-NEOFORGE-F-009 | World Cache Maintenance | ADR-033, rtp-neoforge-ADR-001 | NeoForgeEventBridge, NeoForgeServerAccessor |
NeoForgeTestUmbrellaWiringTest |
| REQ-NEOFORGE-F-010 | Player Session Tracking | ADR-033, rtp-neoforge-ADR-001 | NeoForgePlayerLifecycleHook, NeoForgeEventBridge |
NeoForgeTestUmbrellaWiringTest |
| REQ-NEOFORGE-F-011 | Command Registration | commands-api-ADR-001, ADR-033 | NeoForgeCommandRegistrar, RTPCmdNeoForgeRoot, NeoForgeBrigadierSourceBridge |
NeoForgeTestUmbrellaWiringTest |
| REQ-NEOFORGE-ARCH-001 | No Bukkit/Fabric Imports | rtp-neoforge-ADR-001 section 7 | platforms/rtp-neoforge/** |
RTPArchitectureTest (core_and_api_must_not_depend_on_platforms), PluginPlatformPackageBoundaryArchTest |
| REQ-NEOFORGE-ARCH-002 | No Core Pollution | rtp-neoforge-ADR-001 section 7 | rtp-core, rtp-api |
RTPArchitectureTest (core_and_api_must_not_depend_on_platforms), ReqRtpMap006CoreNoPlatformImportTest |
| REQ-NEOFORGE-ARCH-003 | Mod Plugin Scope | rtp-neoforge-ADR-001 section 4 | Gradle build configuration (platforms/rtp-neoforge/build.gradle) |
PluginPlatformPackageBoundaryArchTest |
| REQ-NEOFORGE-ARCH-004 | Version Carrier Isolation | rtp-neoforge-ADR-001 section 3 | rtp-neoforge-common, rtp-neoforge-v1_21_R1, rtp-neoforge-v26_1_R1 |
RtpFabricCarriersDisjointTest pattern, :rtp-neoforge:rtp-neoforge-common:test |
| REQ-NEOFORGE-ARCH-005 | Asynchronous Chunk Loading (S-005) | ADR-033 section 3.4; rtp-neoforge-ADR-001 section 6; REQ-RTP-S-005 | NeoForgeRTPChunk (anvil dual-mode dispatch); NeoForgeVersionAdapter#requestFullChunkAsync (async path) |
ReqRtpNeoforgeS005ChunkLoadingTest (6 tests: anvil-mode flags, null-view rejection, view-routed block queries, isSafe short-circuit + delegation, keep/unload no-ops) |
| REQ-NEOFORGE-ARCH-006 | Failure Attribution (S-004) | DESIGN.md section 1, REQ-RTP-S-004 | NeoForgeRTPWorld, NeoForgeRTPPlayer |
NeoForgeClaimCheckFailure, NeoForgeTestUmbrellaWiringTest |
| REQ-NEOFORGE-ARCH-007 | Non-Persistent Chunk Tickets (S-002) | rtp-fabric-ADR-003, REQ-RTP-S-002 | NeoForgeRTPChunk, NeoForgeRTPWorld, V1_21_R1NeoForgeVersionAdapter (radius-based addRegionTicket + 30-second rtp_load ticket type) |
ReqRtpNeoforgeS005ChunkLoadingTest, NeoForgeVersion121R1Test |
| REQ-NEOFORGE-ARCH-008 | Memory Hygiene | DESIGN.md section 6, REQ-RTP-S-002 | NeoForgeEventBridge, NeoForgePlayerLifecycleHook, NeoForgeServerAccessor |
NeoForgeTestUmbrellaWiringTest |
| REQ-NEOFORGE-ARCH-009 | Fail-Loud on Unimplemented Surface | ARCHITECTURE.md, REQ-RTP-S-006 | NeoForgeServerAccessor, NeoForgeVersionAdapter |
ReqRtpNeoforgeS006ApiBeforeCoreTest |
| REQ-NEOFORGE-ARCH-010 | Pre-Init Guard | ADR-033 section 3.4; rtp-neoforge-ADR-001 section 6; REQ-RTP-S-006 | NeoForgeVersionAdapterRegistry#require; NeoForgeServerAccessor#getLocationGenerator |
ReqRtpNeoforgeS006ApiBeforeCoreTest (3 tests: registry not-installed, require() throws, getLocationGenerator() throws pre-core) |
| REQ-NEOFORGE-ARCH-011 | Config Directory Resolution | rtp-neoforge-ADR-001 section 6 | NeoForgeServerAccessor#getPluginDirectory, NeoForgeDatabaseHandler |
NeoForgeTestUmbrellaWiringTest |
| REQ-NEOFORGE-ARCH-012 | Database Delegation | rtp-neoforge-ADR-001 | NeoForgeDatabaseHandler, DatabaseProcessing |
DatabaseProcessing core test suite |
| REQ-NEOFORGE-ARCH-013 | Reflection-Gated Claim Hooks (S-003) | ADR-026, REQ-RTP-S-003 | NeoForgeModClaimIntegrations, NeoForgeFTBChunksChecker, NeoForgeOpenPartiesAndClaimsChecker |
NeoForgeModClaimCheckersTest |
Network / Proxy Requirements¶
Most rows below are unimplemented; the multi-server / proxy subsystem is governed by the ratified umbrella ADR-036 (Accepted 2026-05-14) and ten subproject ADRs under platforms/rtp-proxy/docs/adr/ (Phase 1 set rtp-proxy-ADR-001..004 Accepted; 005..010 Proposed). Design source: MULTI_SERVER_PLAN.md. Phase 1 D3 plumbing (network-state member of AbstractSQLDatabaseAccessor) and the parity-when-disabled gate landed 2026-05-18 (REQ-RTP-NET-002, REQ-RTP-NET-013).
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-RTP-NET-001 | Optional network mode (disabled by default; cooldown command and placeholder views honor the effective local/shared last-teleport time per ADR-068) | MULTI_SERVER_PLAN.md — Config Surface; ADR-036; ADR-068 | RTP.getEffectiveLastTeleportTime, RTPCmd, PlaceholderProvider (cooldown views; broader network mode remains partial) |
RTPCmdBranchTest#cooldownGuardUsesNewerSharedTimestampThanLocalPrior, PlaceholderProviderTest#cooldownPlaceholdersUseSharedTimestampWithoutLocalData |
| REQ-RTP-NET-002 | Behavioural parity when disabled | MULTI_SERVER_PLAN.md Non-Goals (v1), Phase 1 no-op test; ADR-036 | AbstractSQLDatabaseAccessor.networkStateBinding (default null); NetworkStateBinding marker |
ReqRtpNet002NetworkDisabledNoOpTest (3 tests: default-null, no network-named threads on construction, setter plumbing) |
| REQ-RTP-NET-003 | Single distribution artifact (backend / proxy role auto-select) | MULTI_SERVER_PLAN.md — Intended Usage & Deployment Model; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-004 | Safety preservation across the network (S-001…S-006 end-to-end) | MULTI_SERVER_PLAN.md — Coordinate Resolution Timing; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-005 | Authoritative world state on backends | MULTI_SERVER_PLAN.md — Architecture Overview, Non-Goals (v1); ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-006 | Configurable network messaging (extends REQ-RTP-F-013) | MULTI_SERVER_PLAN.md — Network Wait Queue, Reservation Tokens; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-007 | Non-blocking network I/O (extends REQ-RTP-F-008, REQ-RTP-S-005) | MULTI_SERVER_PLAN.md — Backend Telemetry Publication, Risk & Pitfall Inventory; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-008 | Cross-network fairness (UUID-keyed wait queue, bypass permission semantics) | MULTI_SERVER_PLAN.md — Network Wait Queue; ADR-036 | NetworkQueueEntryReaper (configured expiry for stale queue entries; broader fairness contract remains partial) |
NetworkQueueEntryReaperTest (stale/fresh/terminal/zero timestamps; cancellation failures) |
| REQ-RTP-NET-009 | Authenticated, versioned inter-server data relay | MULTI_SERVER_PLAN.md — Sufficiency Audit, Risk & Pitfall Inventory; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-010 | Proxy load-balancing policy (configurable, with disable option) | MULTI_SERVER_PLAN.md — Load-Balancing Heuristics; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-011 | Reservation token deterministic expiry; no orphaned allocations | MULTI_SERVER_PLAN.md — Reservation Tokens — Lifecycle ownership matrix; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-012 | Exactly-once reservation claim across the network | MULTI_SERVER_PLAN.md — Reservation Tokens — Lifecycle ownership matrix; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-013 | Multi-flavour persistence compatibility (any shipped SQL accessor) | MULTI_SERVER_PLAN.md Storage - Reuse AbstractSQLDatabaseAccessor; ADR-036 section D3 |
AbstractSQLDatabaseAccessor.networkStateBinding slot is inherited by every concrete accessor (H2, SQLite, MySQL, PostgreSQL) |
(covered transitively by accessor tests; binding plumbing exercised by ReqRtpNet002NetworkDisabledNoOpTest) |
| REQ-RTP-NET-014 | Multi-proxy concurrency and reanimation (no singleton proxy assumption) | MULTI_SERVER_PLAN.md — Multi-Proxy Deployment; ADR-036 | — (unimplemented) | — |
| REQ-RTP-NET-015 | Shared network waitlist for cross-server /rtp (parks unservable enrolments, per-player point-remove, batch drain sized by per-backend networkKeptCount) |
rtp-proxy-ADR-015-shared-network-waitlist-and-dynamic-batched-dispatch; CHECKLIST-network-waitlist.md |
io.github.dailystruggle.rtp.proxy.common.spi.NetworkWaitlist (SPI); InMemoryNetworkWaitlist (reference impl, Slice 1) |
InMemoryNetworkWaitlistTest (15/15: lifecycle, idempotency, duplicate-player rejection, full-capacity rejection, FIFO drain, per-backend cap, global cap, point-remove, TTL reap) |
rtp-proxy Requirements (umbrella module)¶
All rows below are unimplemented. Umbrella: ADR-036 (Accepted). Subproject ADRs: platforms/rtp-proxy/docs/adr/.
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-RTP-PROXY-001 | Adapter SPI Conformance | ADR-036 section 7; platforms/rtp-proxy/REQUIREMENTS.md |
— (unimplemented) | — |
| REQ-RTP-PROXY-002 | No World State | ADR-036 section 2 Non-Goals; platforms/rtp-proxy/REQUIREMENTS.md |
— (unimplemented) | — |
| REQ-RTP-PROXY-003 | Non-Blocking Event Loop | ADR-036 section 7; platforms/rtp-proxy/REQUIREMENTS.md |
— (unimplemented) | — |
| REQ-RTP-PROXY-004 | Reservation Claim Idempotency | ADR-036 section 5; platforms/rtp-proxy/REQUIREMENTS.md |
InMemoryNetworkStateBinding (reference) |
InMemoryNetworkStateBindingTest (claim atomicity / per-player idempotency) |
| REQ-RTP-PROXY-005 | Proxy Heartbeat Publication | ADR-036 section 5; platforms/rtp-proxy/REQUIREMENTS.md |
— (unimplemented) | — |
| REQ-RTP-PROXY-006 | Configurable Messaging | ADR-036 section 3 Locked-In; platforms/rtp-proxy/REQUIREMENTS.md |
— (unimplemented) | — |
| REQ-RTP-PROXY-007 | Authenticated Transport | ADR-036 section 3 D4; rtp-proxy-ADR-010 (Proposed) |
HmacVerifier; CanonicalEnvelopes (token v2 covers regionKey, queue envelope, shared waitlist entry; delimiter-bearing fields rejected); RedisNetworkStateBinding, SqlNetworkStateBinding (redeem verifies stored HMAC), RedisNetworkRequestQueue, SqlNetworkRequestQueue, RedisNetworkWaitlist (unverified entries purged on drain); PluginMessageEnvelope, AbstractPluginMessageNetworkBinding, VelocityProxyCacheListener (signed heartbeats / snapshots); ProxyDirectWire (frame v2: signed opcode, timestamp and nonce; responses bound to their request; unknown opcodes and other frame versions rejected), ProxyDirectReplayCache (bounded nonce cache, fails closed when full), ProxyDirectListener (freshness window and replay checks after the MAC verifies), ProxyDirectNetworkBinding, ProxyDirectTlsConfig, ProxyDirectAllowlist; DefaultRtpDispatcher (reservation token IDs logged redacted via ProxyDirectWire.redactToken); RespProtocol, RespEndpoint (TLS, ACL user, reply limits); NetworkConfig, NetworkBindings (weak or missing secret fails closed) |
CanonicalEnvelopesTest, RedisSharedStoreSigningUnitTest, SqlSharedStoreSigningH2Test, PluginMessageHmacSecurityTest, VelocityProxyCacheHmacTest, ProxyDirectWireTest (incl. signedPayload_opcodeSwapRejected, signedPayload_responseBoundToRequest, list_rowReorderAndCountTamperRejected, requestHeader_v1FrameRejected), ProxyDirectReplayCacheTest, ProxyDirectAllowlistTest, ProxyDirectTlsConfigTest, ProxyDirectListenerTest (incl. unknownOpcodeRejected, v1FrameRejected, replayedNonceRejected, staleTimestampRejected), ProxyDirectNetworkBindingTest (incl. replyBoundToOtherRequestDropped), DefaultRtpDispatcherEdgeTest#tokenIdsAreRedactedInLogs, RespProtocolLimitsTest, NetworkConfigTest, NetworkBindingsTest, NetworkBindingsEdgeTest |
| REQ-RTP-PROXY-008 | Disabled-Mode No-Op | ADR-036 section 1 (REQ-RTP-NET-002 release gate) | — (unimplemented) | — |
| REQ-RTP-PROXY-009 | Single-Artifact Activation | ADR-036 section 7; rtp-fabric-ADR-002 precedent |
— (unimplemented) | — |
| REQ-RTP-PROXY-010 | Adapter Isolation | ADR-036 section 7 | — (unimplemented) | — |
| REQ-RTP-PROXY-011 | Bounded Tab-Completion Cost | ADR-036 section 3 Locked-In (Brigadier reuse) | — (unimplemented) | — |
rtp-proxy-common Requirements¶
All rows below are unimplemented. Phase 1 subproject ADRs rtp-proxy-ADR-001..004 are Accepted (2026-05-14).
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-RTP-PROXY-COMMON-001 | Host-Independent SPI | rtp-proxy-ADR-001-spi-shape (Accepted) |
io.github.dailystruggle.rtp.proxy.common.spi.* (5 SPI ifaces + 8 records/enums) |
NoVendorImportsTest |
| REQ-RTP-PROXY-COMMON-002 | Pure-Function Selector | rtp-proxy-ADR-004-weighted-average-selector (Accepted) |
WeightedAverageBackendSelector |
WeightedAverageBackendSelectorTest (purity, lowest-score wins, tie-break) |
| REQ-RTP-PROXY-COMMON-003 | Snapshot Freshness Filter | rtp-proxy-ADR-004 section scoring; ADR-036 section 6 |
WeightedAverageBackendSelector#qualifies |
WeightedAverageBackendSelectorTest (stale filter, all-stale ⇒ empty) |
| REQ-RTP-PROXY-COMMON-004 | Capped Retry Chain | ADR-036 section 6 Fallback chain | — (unimplemented) | — |
| REQ-RTP-PROXY-COMMON-005 | Trigger Source Plurality | ADR-036 section 3 D1; MULTI_SERVER_PLAN.md Phase 1 item 1 (amended 2026-05-18; promoted to rtp-api 2026-05-19) |
io.github.dailystruggle.rtp.api.network.RtpTriggerSource (producer-side abstraction in rtp-api with Kind/Trigger and start/stop lifecycle); io.github.dailystruggle.rtp.proxy.common.trigger.CommandTriggerSource (Phase 2c-β / Phase 2d concrete producer); consumer-side RtpDispatcher lives in rtp-proxy-common/spi/ |
CommandTriggerSourceTest (6/6: lifecycle, fire-before-start, double-start rejection, stop idempotency, null guard) |
| REQ-RTP-PROXY-COMMON-006 | Single Config Schema | rtp-proxy-ADR-002-network-yml-schema (Accepted) |
— (unimplemented) | — |
| REQ-RTP-PROXY-COMMON-007 | Transport Binding Pluggability | rtp-proxy-ADR-003-in-memory-binding (Accepted); -005/-007/-009 (Proposed) |
NetworkTransport SPI + InMemoryNetworkStateBinding (reference) |
InMemoryNetworkStateBindingTest (snapshot, subscribe, lifecycle) |
| REQ-RTP-PROXY-COMMON-008 | Hot-Spot Counter Locality | ADR-036 section 5 Local state is advisory | — (unimplemented) | — |
rtp-proxy-velocity Requirements¶
Subproject ADR rtp-proxy-ADR-006-velocity-bootstrap Accepted 2026-05-18. REQ-RTP-PROXY-VELOCITY-001 is implemented (Phase 2a no-op shell); the remaining rows are unimplemented and land in Phase 2b - 2f.
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-RTP-PROXY-VELOCITY-001 | Velocity Runtime | rtp-proxy-ADR-006 (Accepted 2026-05-18) |
platforms/rtp-proxy/rtp-proxy-velocity/src/main/java/io/github/dailystruggle/rtp/proxy/velocity/RtpVelocityPlugin.java (Phase 2a no-op shell) |
platforms/rtp-proxy/rtp-proxy-velocity/src/test/java/io/github/dailystruggle/rtp/proxy/velocity/ReqRtpProxyVelocity001SmokeTest.java |
| REQ-RTP-PROXY-VELOCITY-002 | Brigadier Command Hosting | commands-api-ADR-001; ADR-036 section 3 Locked-In; MULTI_SERVER_PLAN.md Phase 2d (2026-05-19) |
RtpVelocityPlugin#registerRtpCommand (Velocity BrigadierCommand for /rtp with optional <world> literal; player-only; fires CommandTriggerSource); RtpVelocityPlugin#onCommandTrigger (selector -> transport.claim -> player.createConnectionRequest, with ServerPreConnectEvent redeeming at the connect boundary) |
RtpVelocityPluginPhase2dTest (3/3: registerRtpCommand shape, onCommandTrigger shape, test-accessor presence); behavioural pipeline covered indirectly by RtpVelocityPluginPhase2cTest + CommandTriggerSourceTest |
| REQ-RTP-PROXY-VELOCITY-003 | Server Rewrite via ServerPreConnectEvent |
rtp-proxy-ADR-006; MULTI_SERVER_PLAN.md Coordinate Resolution Timing, Phase 2 - Velocity adapter (Phase 2c-α 2026-05-19) |
RtpVelocityPlugin#onServerPreConnect (rewrites target via NetworkTransport#findReservation, transitions CLAIMED -> CONSUMED, S-004 fall-through on miss/expiry/unknown-server); NetworkTransport#findReservation SPI default + InMemoryNetworkStateBinding/SqlNetworkStateBinding overrides |
RtpVelocityPluginPhase2cTest (4/4: disabled-no-op, no-reservation-fallthrough, active-reservation-rewrites, unknown-target-fallthrough); SqlNetworkStateBindingH2Test#findReservationCrossesInstances |
| REQ-RTP-PROXY-VELOCITY-004 | Player Session Continuity | ADR-036 section 1 Headline Goals | — (unimplemented) | — |
| REQ-RTP-PROXY-VELOCITY-005 | Tab-Completion Routing | REQ-RTP-PROXY-011; commands-api-ADR-001 |
— (unimplemented) | — |
| REQ-RTP-PROXY-VELOCITY-006 | Telemetry Scheduling | ADR-036 section 5 Proxy heartbeat | — (unimplemented) | — |
| REQ-RTP-PROXY-VELOCITY-007 | Plugin Identity and Version Coupling | REQ-RTP-NET-009 schemaVersion negotiation | — (unimplemented) | — |
rtp-proxy-bungee Requirements¶
All rows below are unimplemented. Subproject ADR rtp-proxy-ADR-008-bungee-bootstrap (Proposed; Phase 3).
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-RTP-PROXY-BUNGEE-001 | BungeeCord and Waterfall Runtime | rtp-proxy-ADR-008 (Proposed) |
— (unimplemented) | — |
| REQ-RTP-PROXY-BUNGEE-002 | Server Rewrite via ServerConnectEvent |
rtp-proxy-ADR-008 |
— (unimplemented) | — |
| REQ-RTP-PROXY-BUNGEE-003 | No Brigadier Dependency | commands-api-ADR-001 (non-Brigadier path) |
— (unimplemented) | — |
| REQ-RTP-PROXY-BUNGEE-004 | Scheduler Discipline | ADR-036 section 7 Adapter isolation | — (unimplemented) | — |
| REQ-RTP-PROXY-BUNGEE-005 | Plugin-Message Transport Eligibility | ADR-036 section 3 D2 (dev-only) | — (unimplemented) | — |
| REQ-RTP-PROXY-BUNGEE-006 | Tab-Completion Parity | REQ-RTP-PROXY-011 | — (unimplemented) | — |
| REQ-RTP-PROXY-BUNGEE-007 | Fork Compatibility Statement | rtp-proxy-ADR-008 (Proposed) |
— (unimplemented) | — |
leaf-video Requirements¶
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-LCV-F-001 | Lossless bit-exact RGBA / YCoCg-R cube reconstruction (PSNR = infinity) |
leaf-video-ADR-001 |
lcv_accel, lcv_codec_system_plugins, leafvideo |
lcv_cli_and_test, lcv_proof_report |
| REQ-LCV-F-002 | Wire-compatible distance-scaled d_merge RLE run coalescing |
leaf-video-ADR-001 |
lcv_accel, lcv_codec_system_plugins |
lcv_cli_and_test, lcv_proof_report |
| REQ-LCV-F-003 | Append-only superblock tail truncation survival, multi-track LCV_A001 (.lca) audio stems & O(1) seekability |
leaf-video-ADR-001 |
lcv_accel, lcv_codec_system_plugins, obs_leafvideo_plugin |
lcv_cli_and_test |
| REQ-LCV-F-004 | Extended Hamming (72, 64) SEC-DED pointer self-healing & CBIT quarantine |
leaf-video-ADR-001 |
lcv_accel, lcv_codec_system_plugins |
lcv_cli_and_test |
| REQ-LCV-F-005 | Zero-decode compressed-domain on-disk transforms (cropSubRegion, stripLsbPlanes, coalesceRunsByDistance, wrapZstdPools) |
leaf-video-ADR-001 |
lcv_accel, lcv_cli_and_test, obs_leafvideo_plugin |
lcv_cli_and_test, lcv_proof_report |
| REQ-LCV-DB-001 | Content-addressed DecodeMapPacket (LCV_MAP1) & O(1) extractSingleFrame pointer-directory hop |
leaf-video-ADR-003 |
lcv_accel, lcv_codec_system_plugins |
lcv_cli_and_test, lcv_proof_report |
| REQ-LCV-DB-002 | Cross-superblock Zstd dictionary conditioning & CompactSignatureIndex deduplication |
leaf-video-ADR-003 |
lcv_accel, lcv_proof_report |
lcv_cli_and_test, lcv_proof_report |
| REQ-LCV-DB-003 | Unflattened multi-layer (layer, x, y, t) RGBA recording & O(1) UNIFORM_INLINE sparse compositing |
leaf-video-ADR-003 |
lcv_accel, obs_leafvideo_plugin |
lcv_cli_and_test, lcv_proof_report |
| REQ-LCV-DB-004 | Wait-free growing-stream tail reading, .lcv.branch sidecar timeline cuts & Hot-NVMe / Cold-HDD tiered split |
leaf-video-ADR-003 |
lcv_accel, lcv_codec_system_plugins, obs_leafvideo_plugin |
lcv_cli_and_test |
| REQ-LCV-HW-001 | SWAR 64-bit branchless YCoCg-R lifting & 8x8 bit-matrix transpose kernels |
leaf-video-ADR-004 |
lcv_accel, lcv_cube_kernel |
lcv_cli_and_test |
| REQ-LCV-HW-002 | Compressed-domain hardware DMA scatter-gather & inline recode checkpointing | leaf-video-ADR-004 |
lcv_accel, lcv_cube_kernel, obs_leafvideo_plugin |
lcv_cli_and_test |
| REQ-LCV-HW-003 | Rolling strip (K=1) zero-lookahead framing & in-flight UEP LSB shedding |
leaf-video-ADR-004 |
lcv_accel, obs_leafvideo_plugin |
lcv_cli_and_test |
LeafMap Remote .lca Stream & Bounded LRU Pool Requirements¶
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-MAP-STREAM-001 | Full .lca chunk batch (LCAB 0x4C434142) at < 1/5 .mca byte size and incremental section patch delta (LCAS 0x4C434153) encoding & ingestion |
leafmap-ADR-004, leafanvil-ADR-003, anvil-api-ADR-003 |
LcaRemoteStreamCodec, LcaBoundedSlabPool, LcaWireStreamProtocol, LeafMapWorldIndexer, LeafMapHttpServer |
LcaBoundedSlabPoolAndCodecTest, LeafMapWorld3DAndPacketFeedTest |
| REQ-MAP-STREAM-002 | Extended Hamming (72, 64) SEC-DED-64 baseline/payload verification and HTTP 409 NEEDS_FULL_CHUNK_REFILL reporting (S-004) |
leafmap-ADR-004, leafanvil-ADR-003 |
LcaRemoteStreamCodec, LcaBoundedSlabPool, LeafMapHttpServer |
LcaBoundedSlabPoolAndCodecTest, LeafMapWorld3DAndPacketFeedTest |
| REQ-MAP-LRU-001 | Two-tier byte-budgeted LRU slab pool (maxMemoryCacheBytes L1 RAM + optional maxDiskCacheBytes L2 .lca disk spillover, 0 = pure RAM mode) |
leafmap-ADR-004, anvil-api-ADR-003 |
LcaBoundedSlabPool, LeafMapConfig, LeafMapRuntime |
LcaBoundedSlabPoolAndCodecTest, LeafMapWorld3DAndPacketFeedTest |
| REQ-MAP-LRU-002 | Pinned spawn regions and LOD-3 (10,990 B) surface horizon headers per (serverId, world) |
leafmap-ADR-004, leafmap-ADR-003 |
LcaBoundedSlabPool, LeafMapSubChunkPacketCodec |
LcaBoundedSlabPoolAndCodecTest, LeafMapWorld3DAndPacketFeedTest |
| REQ-MAP-MULTI-001 | Multi-server serverId:world composite namespace, per-server BlockState dictionary isolation, and /api/servers + /api/server/{serverId}/world/{world}/... routes |
leafmap-ADR-004, maps-api-ADR-003 |
WorldBlockFeed, LcaBoundedSlabPool, LeafMapWorldIndexer, LeafMapHttpServer, LeafMapRuntime, LeafMapWorld3DEngine |
LcaBoundedSlabPoolAndCodecTest, WorldBlockFeedRegistryTest, LeafMapWorld3DAndPacketFeedTest |
| REQ-MAP-EMBED-001 | Nested multi-server webpage (?embed=1&server=<serverId>&world=<world>), Multi-Server Selector UI, and window.postMessage bridge |
leafmap-ADR-004 |
LeafMapSubChunkPacketCodec, LeafMapRuntime, LeafMapHttpServer |
LeafMapWorld3DAndPacketFeedTest |
LeafShard Distributed .lca World-Sharding Mesh Requirements¶
| Req ID | Summary | Design Ref | Implementing Class(es) | Test(s) |
|---|---|---|---|---|
| REQ-SHARD-001 | .lca 32x32 region lease authority, monotonic leaseEpoch split-brain fencing, and lockless 3D proximity peer mode |
leafshard-ADR-001 |
RegionCoord, RegionLeaseRecord, ShardLeaseControlPlane, InMemoryShardLeaseControlPlane, LeafShardCoordinator, LeafShardRuntime |
LeafShardCoordinatorAndMeshTest, PaperLeafShardPluginTest, VelocityLeafShardPluginTest |
| REQ-SHARD-002 | 10-chunk Halo subscription, SECDED-64 syndrome-verified LCAS (0x4C434153) delta streaming, and self-healing EntryFullChunk refills |
leafshard-ADR-002 |
LeafShardCoordinator, LeafShardRuntime, LeafShardPeerFrameCodec |
LeafShardCoordinatorAndMeshTest, PaperLeafShardPluginTest |
| REQ-SHARD-003 | 2-chunk (32-block) border hysteresis deadband and idempotent session handoff locking |
leafshard-ADR-002, leafshard-ADR-003 |
BorderHysteresisEvaluator, LeafShardCoordinator, PlayerBorderHandoffEnvelope |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest |
| REQ-SHARD-004 | Live cross-shard container slot/viewer sync (ITEM_ACTION_CONTAINER_SYNC), optional single-owner seam container guard, and SavedTick forwarding (0x05) |
leafshard-ADR-003 |
LeafShardCoordinator, LeafShardRuntime, PaperLeafShardPlugin, FabricLeafShardMod, NeoForgeLeafShardMod |
LeafShardCoordinatorAndMeshTest, PaperLeafShardPluginTest |
| REQ-SHARD-005 | Brokerless embedded LSHD (0x4C534844) control ring (0x06) and N:M WAN proxy Halo subscription bitmaps |
leafshard-ADR-004 |
ShardLeaseControlPlane, InMemoryShardLeaseControlPlane, LeafShardCoordinator, VelocityLeafShardPlugin |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest |
| REQ-SHARD-006 | Stateless-clamped 24-byte FRAME_PROXY_KINEMATIC_MULTICAST (0x07), partitioned high-bit haloEntityId, and FRAME_KINEMATIC_SETBACK (0x08) |
leafshard-ADR-004 |
LeafShardPeerFrameCodec, LeafShardCoordinator, LeafShardRuntime, VelocityLeafShardPlugin |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest |
| REQ-SHARD-007 | Epoch-pinned VarInt symbol table, Zstd shared dictionary delta sync, and causal single-voxel micro-deltas |
leafshard-ADR-004 |
LeafShardPeerFrameCodec, LeafShardCoordinator, LeafShardRuntime |
LeafShardCoordinatorAndMeshTest |
| REQ-SHARD-008 | Bounded crowd visibility (maxLiveHaloPlayersPerObserver = 40), local-crowd Halo tapering (localProximatePlayerCount), and bounded peer fanout (maxProximatePeerShards = 4) |
leafshard-ADR-004, leafshard-ADR-005 |
LeafShardCoordinator, LeafShardRuntime, ShardNodeHeartbeat, ShardLeaseControlPlane, PaperLeafShardPlugin, FabricLeafShardMod, NeoForgeLeafShardMod |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest, PaperLeafShardPluginTest |
| REQ-SHARD-009 | Receiving-shard ShadowPlayerState projection, on-demand interactive border handoff, and zero-flicker in-place shadow promotion |
leafshard-ADR-004 |
LeafShardCoordinator, LeafShardRuntime, PaperLeafShardPlugin, FabricLeafShardMod, NeoForgeLeafShardMod |
LeafShardCoordinatorAndMeshTest, PaperLeafShardPluginTest |
| REQ-SHARD-010 | Two-regime composite load-balanced shard selection (computeLoadScore, co-location below soft cap, spillover when saturated) and PoP localeGroup lease migration |
leafshard-ADR-005 |
ShardNodeHeartbeat, ShardLeaseControlPlane, InMemoryShardLeaseControlPlane, LeafShardCoordinator, VelocityLeafShardPlugin |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest, PaperLeafShardPluginTest |
| REQ-SHARD-011 | Unified Zstd player state & per-UUID file bundle codec (PSBD 0x50534244), PlayerStateContributor SPI, and ShadowHitboxHistoryRing (<= 200 ms rewind) |
leafshard-ADR-003, leafshard-ADR-004, leafshard-ADR-005 |
PlayerStateBundleCodec, PlayerStateContributor, PlayerUuidFileBundler, LeafShardCoordinator, LeafShardRuntime, PaperLeafShardPlugin, FabricLeafShardMod, NeoForgeLeafShardMod |
LeafShardCoordinatorAndMeshTest, PaperLeafShardPluginTest, VelocityLeafShardPluginTest |
| REQ-SHARD-012 | Lazy Supplier<byte[]> border handoff state evaluation, pre-switch player.saveData() flush, and victim-shard Defense-Cancel combat arbitration (0x09/0x0A) |
leafshard-ADR-003, leafshard-ADR-005 |
LeafShardCoordinator, LeafShardRuntime, PaperLeafShardPlugin, FabricLeafShardMod, NeoForgeLeafShardMod |
LeafShardCoordinatorAndMeshTest, PaperLeafShardPluginTest |
| REQ-SHARD-013 | Immediate UDP FRAME_PLAYER_HANDOFF (0x04) pre-join disk staging of bundled <uuid> files with strict path-traversal rejection |
leafshard-ADR-003, leafshard-ADR-004 |
PlayerUuidFileBundler, LeafShardRuntime |
LeafShardCoordinatorAndMeshTest, PaperLeafShardPluginTest, VelocityLeafShardPluginTest |
| REQ-SHARD-014 | Arbitrary cross-server & cross-world handoff routing (/leafshard send, LeafShardRuntime#initiateCrossServerTransfer, VelocityLeafShardPlugin#onServerPreConnect, and PlayerBorderHandoffEnvelope#keepDestinationLocation) |
leafshard-ADR-003, leafshard-ADR-004 |
PlayerBorderHandoffEnvelope, LeafShardRuntime, LeafShardCommand, VelocityLeafShardPlugin, PaperLeafShardPlugin, FabricLeafShardMod, NeoForgeLeafShardMod |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest, PaperLeafShardPluginTest |
| REQ-SHARD-015 | Multi-world <uuid> discovery and primary world folder remapping (PlayerUuidFileBundler#primaryWorldFolder, server.properties level-name=) |
leafshard-ADR-003, leafshard-ADR-004 |
PlayerUuidFileBundler |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest, PaperLeafShardPluginTest |
| REQ-SHARD-016 | Automatic DEATH and QUIT lifecycle .psbd snapshots and all-platform staged offline restore on join (consumeStagedRestorePayload) |
leafshard-ADR-003, leafshard-ADR-004 |
PlayerSnapshotStore, LeafShardRuntime, PaperLeafShardPlugin, FabricLeafShardMod, NeoForgeLeafShardMod |
LeafShardCoordinatorAndMeshTest, VelocityLeafShardPluginTest, PaperLeafShardPluginTest |
Coverage Summary¶
| Module | Total Reqs | Automated Test Coverage |
|---|---|---|
| Root / System | 25 | 13 (REQ-RTP-F-001 SLATest+RegionPipelineTest, REQ-RTP-F-006/007 RegionPipelineTest, REQ-RTP-F-008, REQ-RTP-F-012 ScanCmdTest+ScanTaskProcessingTest, REQ-RTP-F-013 ConfigParserLanguageTest, REQ-RTP-F-015 ReqRtpSlopeLandingTest, REQ-RTP-NF-002, REQ-RTP-NF-003 via RTPArchitectureTest, REQ-RTP-SYS-001 via build, REQ-RTP-S-004 FailureModeTest+RegionPipelineTest+AsyncTaskProcessingTest (pulse non-overlap guard)+FactoryValueGetNumberConcurrencyTest (lock-free config reads), REQ-RTP-S-005, REQ-RTP-S-006 RTPAPIGuardTest) |
| rtp-api | 10 | 4 (REQ-API-NF-002, REQ-API-ARCH-002, REQ-API-ARCH-003 RTPAPIGuardTest, REQ-API-ARCH-004) |
| rtp-core | 20 | 13 (REQ-CORE-F-001 FailureModeTest+RegionPipelineTest, REQ-CORE-F-003–005, REQ-CORE-F-009 BacklogLocationBufferTest+WorldBacklogBinIndexTest, REQ-CORE-ARCH-001–002, REQ-CORE-ARCH-009–010, REQ-CORE-NF-001 MemoryShapeShutdownTest+CachedLocationRoundTripTest; REQ-CORE-F-003/004 also covered end-to-end by RegionPipelineTest) |
| rtp-bukkit | 9 | 4 (REQ-SPIGOT-F-001, REQ-SPIGOT-ARCH-001/005 via ChunkTicketLifecycleTest, REQ-SPIGOT-ARCH-003/004 via BukkitSchedulerImplTest) |
| rtp-paper | 9 | 5 (REQ-PAPER-F-002 via architecture rule, REQ-PAPER-F-003 and REQ-PAPER-ARCH-003 via ServerAccessorImplTest, REQ-PAPER-ARCH-001/005 via ChunkTicketLifecycleTest) |
| rtp-folia | 14 | 1 (REQ-FOLIA-F-002 via architecture rule) |
| rtp-fabric | 1 | 1 (REQ-FABRIC-F-011 via ReqFabricAdr023HasPlayedBeforeTest) |
| Network / Proxy | 14 | 0 (subsystem unimplemented; umbrella ADR-036 Accepted, implementation pending) |
| rtp-proxy | 11 | 1 (REQ-RTP-PROXY-004 via InMemoryNetworkStateBindingTest#concurrentClaimsAreIdempotent) |
| rtp-proxy-common | 8 | 4 (REQ-RTP-PROXY-COMMON-001 via NoVendorImportsTest; -002, -003 via WeightedAverageBackendSelectorTest; -007 via InMemoryNetworkStateBindingTest) |
| rtp-proxy-velocity | 7 | 0 (Phase 2 — pending rtp-proxy-ADR-005/-006) |
| rtp-proxy-bungee | 7 | 0 (Phase 3 — pending rtp-proxy-ADR-008) |
| Total | 123 | ~49 |
Deterministic RNG seam:
MemoryShape.setRng(Random),LocationGenerator.setRng(Random), andRTPCmd.setRng(Random)allow any test to inject a seededjava.util.Randomand eliminate RNG as a source of flakiness.DeterministicShapeTest(12 tests) exercises this seam forCircle,Square, andRectangle. The biome-recall path inLocationGeneratoruses the same seam.Real-region pipeline tests (
RegionPipelineTest, 12 tests): Exercises the fullLocationGenerator.getLocation(Region, biomeNames)pipeline using actualRegion/MockRTPWorld/MockRTPChunkmock components — noMockLocationGeneratorstub. Covers: queue promotion (unkeptLocations→keptLocations),hasLocationstate transitions, queue-length APIs, biome filter acceptance (PLAINS) and rejection (DEEP_OCEAN), coords-inside-shape bounds assertion, and end-to-end determinism (same/different seed).RTPTestSetup.install()now callsConfigs.reloadConfigs()so all core parsers (SafetyKeys,PerformanceKeys,LoggingKeys) are available to every test that needs them.MockRTPChunk(new testFixture) provides an all-safe, all-air chunk;MockRTPWorldnow encodes chunk coords into the cache key sogetCachedChunk()returns the correct chunk at any (cx, cz).MockRTPServerAccessor.getWorldBorder()now returns an always-insideWorldBorderand exposessetLocationGenerator()to swap in the real pipeline.Gap: The adapter modules (spigot, paper, folia) have low but growing automated test coverage. MockBukkit is now integrated into
rtp-bukkit-commonandrtp-paper-v1_20_R1; the mock support classes have been promoted to a sharedjava-test-fixturessource set inrtp-core. The remaining highest-value automation steps are: 1. ~~Automate chunk ticket lifecycle (REQ-SPIGOT-ARCH-001/005, REQ-PAPER-ARCH-001/005)~~ Done —ChunkTicketLifecycleTest(2 tests) usesTrackedMockWorldto assert tickets are held during validation and released (including on exception) viaChunkReservationtry-with-resources. 2. Extend MockBukkit coverage tortp-bukkit-v1_20_R1,rtp-paper-v1_21_R1, andrtp-paper-v26_1_R1using the sametestFixturespattern. 3. Folia mock infrastructure and economy delegation (REQ-FOLIA-ARCH-007–009) require a dedicated Folia mock server or a Folia-compatible MockBukkit fork.