feat: Add Hardcore Integrity Keeper (HIK) MVP subsystem

README.md

@@ -0,0 +1,35 @@
+# TruthSystems Mod
+
+See [GITHUB_README.md](GITHUB_README.md) for the full project overview.
+
+## Hardcore Integrity Keeper (HIK)
+
+HIK is the fifth subsystem of TruthSystems — a cryptographic enforcement layer that makes Hardcore mode **truly permanent**.
+
+### What it does
+
+| Feature | Mechanism |
+|---|---|
+| **Death sealing** | SHA-256 checksummed death records in `<world>/soulbind/<uuid>.json` |
+| **Spectator lock** | Locked players are held in spectator mode and cannot change game mode via commands |
+| **Archive countdown** | Grace period (`spectator_grace_minutes`) before world is flagged for archival |
+| **level.dat tamper detection** | SHA-256 of `level.dat` compared on every server start |
+| **Rollback detection** | Game tick persisted every 30 s; backwards tick = rollback flag |
+| **LAN cheat blocking** | Mixin disables "Allow Cheats" on `ShareToLanScreen` for Hardcore worlds |
+| **Read-only enforcement** | Block-break/place cancelled when world integrity ≠ CLEAN |
+| **HUD overlay** | Green `HIK: CLEAN` / red `HIK: <FLAG>` rendered in the top-left corner |
+
+### Configuration
+
+Config file: `config/truthsystems-hik.toml` (auto-generated on first run).
+
+See [docs/HIK_ARCHITECTURE.md](docs/HIK_ARCHITECTURE.md) for full architecture documentation and
+[docs/MODPACK_COMPATIBILITY.md](docs/MODPACK_COMPATIBILITY.md) for the LAN-screen mixin compatibility notes.
+
+### Subsystems
+
+- `com.truthsystems.hardcore.soulbind` — death seals & event handling
+- `com.truthsystems.hardcore.integrity` — level.dat watching & HUD overlay
+- `com.truthsystems.hardcore.backup` — session IDs & rollback detection
+- `com.truthsystems.hardcore.spectator` — lock enforcement, countdown, command interception
+- `com.truthsystems.hardcore.lan` — LAN mixin, cheat watcher, read-only enforcer

VERIFICATION_HASHES.txt

@@ -2,24 +2,43 @@
 # Covenant: SIGMA_LORA_COVENANT v1.0
 # Generated: 2026-02-04
 
-B98012CC51C79489E657D0F50DE25E4D9DBE2A6A23206A02C438A928D36A56CB  build.gradle
+7C0B010B82D2EE34B4CEBBC1CD14747038742ECDA88B38A7F3DECE20ACA50C15  build.gradle
 58A820524B1197F432CC0720F670689FA7F634B2FB68554C581B8685A7AE50FC  gradle.properties
 A5B8EEE8C2B7A9C124348F51C42C47DCFE5A9A1F625BF8E3A8436D737F77FA8E  settings.gradle
-F8F171F9A1E0907C6640F037DCA4FA6D7EDCA3D68D65B945EB760D5A969F5A6E  src\main\java\com\truthsystems\TruthSystems.java
-AF9C015572F763564AD67C0150A939709F3A5D165CF6088CD7A32A66EBE5CA5A  src\main\java\com\truthsystems\audit\BlacklistManager.java
-CD8E926930EC95AE43BB9A57CB35A3EDD17EEFB779E2566000074A2FBA1D11BF  src\main\java\com\truthsystems\audit\CovenantCompliant.java
-9D4FAB098F563BA09CCD9DC8999D13E42EFD49AB7B891D456A473F55DF8DFE04  src\main\java\com\truthsystems\audit\CovenantVerifier.java
-888B311B3F0C0BFE88B3C19A41F0B8326E268EAB1A75EB815397EEEE3DA0EBAF  src\main\java\com\truthsystems\audit\ErrorLogger.java
-7C8DB103908C0FC8B5669AD190D831CB32CA19593D389B218776EC00851D8A6C  src\main\java\com\truthsystems\causality\RedstoneGraph.java
-8B5093F44D2E0863A77DFA2D1803D44B4800735579EA636FBBEDCFD304C22B64  src\main\java\com\truthsystems\debugger\DebugMetrics.java
-5724D41C31F4F2B4CD8CC2D8A05F7E9BB244F79DECC0369E3748C25972DFBA1A  src\main\java\com\truthsystems\inverter\InversionLogic.java
-0F97E73A29E5B01E3C0106FD71A74BA213359C6D2D481DBC8154D6F0A506CEAA  src\main\java\com\truthsystems\inverter\InverterBlock.java
-1F17C29CF19C931615E3E7B542C7E4659FB026FA1C28CC46C230DDF866611FB6  src\main\java\com\truthsystems\merkle\ChunkHasher.java
-C2978A5D9512FC97D6A16E5E14BE35FB290513CC64CE1B2D9786ABA047267291  src\main\java\com\truthsystems\merkle\NotaryBlock.java
-6804C8CE6E04BFB71AACC9B19B9BB4FEF89583E4C9FCA66623A4042D26FFA568  src\main\java\com\truthsystems\merkle\NotaryBlockEntity.java
-6089B437CE5EA855C0ED7EF17749D05DA5F31C1E6438A613FDC3478D84A755FD  src\main\java\com\truthsystems\registry\ModBlockEntities.java
-C3C3C65906DCC30B8294C8FB52EBDBF73DD4CEA3BC936D9AE395C06F65EC8DCF  src\main\java\com\truthsystems\registry\ModBlocks.java
-400ECEB7F6FE67114C0DCAE90E74C9260FE293C6B6EBC718A272237335888514  src\main\java\com\truthsystems\registry\ModEntities.java
-1EEA022A7698C3D1233FBB3A0EFF4DDA7494D0C99781845BF72BC4872A180C7B  src\main\java\com\truthsystems\registry\ModItems.java
-654B843C709CC026DED6AE3A32FB5731D16C37491D76E23933096659AD36AFEA  src\main\resources\META-INF\mods.toml
-7B25B64405B6844BD1557B34B15072CD9BEE7D5FC92EFCC9D230AD4EEB0E55C6  src\main\resources\pack.mcmeta
+FD2CB2BF70E8CBC253312500B088F65C221A0643D22B662C180D81FC149273A7  src/main/java/com/truthsystems/TruthSystems.java
+AF9C015572F763564AD67C0150A939709F3A5D165CF6088CD7A32A66EBE5CA5A  src/main/java/com/truthsystems/audit/BlacklistManager.java
+CD8E926930EC95AE43BB9A57CB35A3EDD17EEFB779E2566000074A2FBA1D11BF  src/main/java/com/truthsystems/audit/CovenantCompliant.java
+E70570A7103E0299BE7226D840C79178E7A7B97E9E9921F62317B40EBC7FC447  src/main/java/com/truthsystems/audit/CovenantVerifier.java
+9F4A5631D563F4C3F630320FF77DFA6FA6F6068B02F227013F3DFDCF913235D9  src/main/java/com/truthsystems/audit/ErrorLogger.java
+7C8DB103908C0FC8B5669AD190D831CB32CA19593D389B218776EC00851D8A6C  src/main/java/com/truthsystems/causality/RedstoneGraph.java
+8B5093F44D2E0863A77DFA2D1803D44B4800735579EA636FBBEDCFD304C22B64  src/main/java/com/truthsystems/debugger/DebugMetrics.java
+02EB8862C58D709EBA2AF55A24B485DBA84CB860954C454CA5C631D922F97B2A  src/main/java/com/truthsystems/hardcore/HikConfig.java
+FA5FC17087FF0FD9876D7B0B8E726D039741192BA779B80432024842BC0D7720  src/main/java/com/truthsystems/hardcore/HikCovenantCompliance.java
+3BFB892B91120B321C6807001B716B630C1A3B4BDDCFBD957F6DC64B3484B8ED  src/main/java/com/truthsystems/hardcore/backup/BackupDetector.java
+48607C09BCDD018C110E8396E38695C6173A0B51DAC80950EC07EAED01974901  src/main/java/com/truthsystems/hardcore/backup/SessionIdManager.java
+06C9F60E5A22EF995B09D5C8FD13EE1F74E3C526A2205E741B1DFB720808253D  src/main/java/com/truthsystems/hardcore/integrity/IntegrityOverlay.java
+0B9839DA39FDA3434757637BBAAAFF90D2B2B3A79F563E5EF393490351055C49  src/main/java/com/truthsystems/hardcore/integrity/LevelDatWatcher.java
+F67459326F42FC10D5DABB6093BCD67DDFB1375C1A3D7CFD97CD9D82B24BC8D1  src/main/java/com/truthsystems/hardcore/integrity/WorldChecksumValidator.java
+0A5A313AB4A7642DC215ABA4C8C68D002C946D3AD66FF66F6A0631B5AEA00F48  src/main/java/com/truthsystems/hardcore/lan/CheatFlagWatcher.java
+70B3E245D0FDF8C64B1C7F7435ADB2541C4798B32A6E4980300288884E58E42B  src/main/java/com/truthsystems/hardcore/lan/LanMenuMixin.java
+A0FB5C8800359200EDABDA044EF75C9286772A6AD7663120AE9FCCD2F46603CF  src/main/java/com/truthsystems/hardcore/lan/MixinConfigPlugin.java
+72C0A14F62B031E47AD32FBD083C9EFFA5535370C7A3B208BAC3EBB20A9F715A  src/main/java/com/truthsystems/hardcore/lan/ReadOnlyWorldEnforcer.java
+0761B57BBF9D34AA1BD41DA715A64CF70699CED6903E702EAFD29F7DC6A96F67  src/main/java/com/truthsystems/hardcore/soulbind/DeathLogEntry.java
+479CA767F46E46E587351681AFDC4FAD2D85042834AFD94410EE3A0DE13C3313  src/main/java/com/truthsystems/hardcore/soulbind/DeathSealManager.java
+1E3A87E4AA2967EF06F514DBD38E07C56FDEBA069929BEBC46029AE7D4F0485B  src/main/java/com/truthsystems/hardcore/soulbind/IntegrityFlag.java
+ABAAD58985A7A5BA9CAC2F2A0F09000949BCAA5A07DFDB2E0BEC935E05D8BC9B  src/main/java/com/truthsystems/hardcore/soulbind/SoulbindEventHandler.java
+481DAF1B7F60F0C3B619D3D27C485517DA1ADD5FDACBA0E4E5743C0B3F2461D5  src/main/java/com/truthsystems/hardcore/spectator/ArchiveCountdown.java
+C99B1F718BCFEDC806722CC1BE23E175AD84974BDFE5A98CF1AE767559D7464D  src/main/java/com/truthsystems/hardcore/spectator/CommandInterceptor.java
+436FC52F1F4B9975DD9989E65A66C33FB5962D01AC1A15645F930FBAB235ABA0  src/main/java/com/truthsystems/hardcore/spectator/SpectatorLockHandler.java
+5724D41C31F4F2B4CD8CC2D8A05F7E9BB244F79DECC0369E3748C25972DFBA1A  src/main/java/com/truthsystems/inverter/InversionLogic.java
+0F97E73A29E5B01E3C0106FD71A74BA213359C6D2D481DBC8154D6F0A506CEAA  src/main/java/com/truthsystems/inverter/InverterBlock.java
+1F17C29CF19C931615E3E7B542C7E4659FB026FA1C28CC46C230DDF866611FB6  src/main/java/com/truthsystems/merkle/ChunkHasher.java
+C2978A5D9512FC97D6A16E5E14BE35FB290513CC64CE1B2D9786ABA047267291  src/main/java/com/truthsystems/merkle/NotaryBlock.java
+6804C8CE6E04BFB71AACC9B19B9BB4FEF89583E4C9FCA66623A4042D26FFA568  src/main/java/com/truthsystems/merkle/NotaryBlockEntity.java
+6089B437CE5EA855C0ED7EF17749D05DA5F31C1E6438A613FDC3478D84A755FD  src/main/java/com/truthsystems/registry/ModBlockEntities.java
+C3C3C65906DCC30B8294C8FB52EBDBF73DD4CEA3BC936D9AE395C06F65EC8DCF  src/main/java/com/truthsystems/registry/ModBlocks.java
+400ECEB7F6FE67114C0DCAE90E74C9260FE293C6B6EBC718A272237335888514  src/main/java/com/truthsystems/registry/ModEntities.java
+1EEA022A7698C3D1233FBB3A0EFF4DDA7494D0C99781845BF72BC4872A180C7B  src/main/java/com/truthsystems/registry/ModItems.java
+E1E8ECF228D431318F871FEAD50730ABC1CF606290865725B93684193EF5E6C6  src/main/resources/META-INF/mods.toml
+7B25B64405B6844BD1557B34B15072CD9BEE7D5FC92EFCC9D230AD4EEB0E55C6  src/main/resources/pack.mcmeta
+265FC654B960FB245AA6E8D41C1C2AFF80B3C6AF141CDFB1DD32A5373372A216  src/main/resources/truthsystems.mixins.json

build.gradle

@@ -1,8 +1,20 @@
-plugins {
-    id 'java'
-    id 'net.minecraftforge.gradle' version '6.0.18'
+buildscript {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+        maven { url = 'https://maven.minecraftforge.net/' }
+        maven { url = 'https://repo.spongepowered.org/repository/maven-public/' }
+    }
+    dependencies {
+        classpath 'net.minecraftforge.gradle:ForgeGradle:6.0.18'
+        classpath 'org.spongepowered:mixingradle:0.7-SNAPSHOT'
+    }
 }
 
+apply plugin: 'java'
+apply plugin: 'net.minecraftforge.gradle'
+apply plugin: 'org.spongepowered.mixin'
+
 group = 'com.truthsystems'
 version = '1.0.0'
 
@@ -42,12 +54,27 @@ repositories {
 
 dependencies {
     minecraft 'net.minecraftforge:forge:1.20.1-47.4.10'
+    annotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
+
+    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.1'
+    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.1'
+    testImplementation 'org.mockito:mockito-core:5.8.0'
+    testImplementation 'org.mockito:mockito-junit-jupiter:5.8.0'
 }
 
 tasks.withType(JavaCompile).configureEach {
     options.encoding = 'UTF-8'
 }
 
+mixin {
+    add sourceSets.main, "truthsystems.mixins.refmap.json"
+    config "truthsystems.mixins.json"
+}
+
+test {
+    useJUnitPlatform()
+}
+
 jar {
     manifest {
         attributes([

docs/HIK_ARCHITECTURE.md

@@ -0,0 +1,136 @@
+# HIK Architecture — Hardcore Integrity Keeper
+
+## What is HIK?
+
+The **Hardcore Integrity Keeper (HIK)** is a subsystem of the TruthSystems Forge mod that
+enforces the *permanence of death* in Minecraft Hardcore worlds.  It combines cryptographic
+sealing, tamper detection, spectator-lock enforcement, and cheat-flag watching to make
+Hardcore truly hardcore — even against external save-file manipulation or LAN cheat toggles.
+
+HIK operates under the Σ_LORA_COVENANT v1.0 and is governed by the **LOGOS** and
+**CHALCEDON** principles: every integrity state is explicitly named, every check is
+cryptographically falsifiable, and the infrastructure exists to serve the player's chosen
+challenge — not to override it.
+
+---
+
+## Config Keys (`truthsystems-hik.toml`)
+
+| Key | Default | Description |
+|---|---|---|
+| `enable_hik` | `true` | Master switch for the entire HIK subsystem |
+| `archive_path` | `"saves/archived"` | Directory for archived Hardcore world copies |
+| `spectator_grace_minutes` | `10` | Minutes before an archived world is flagged for archival |
+| `verification_api_port` | `0` | HTTP verification API port (0 = disabled, Phase 2) |
+| `allow_sealed_backups` | `true` | Allow server-side backups even after a death seal |
+| `strict_inventory_provenance` | `false` | Full inventory provenance tracking (Phase 2, no-op) |
+| `compromise_on_lan_cheats` | `true` | Mark world COMPROMISED when LAN cheats are enabled |
+| `read_only_on_external_cheat_flag` | `true` | Block block-break/place when world is not CLEAN |
+
+---
+
+## Architecture Overview
+
+HIK is organized into five subsystems under `com.truthsystems.hardcore`:
+
+### 1. `soulbind` — Death Sealing
+
+| Class | Role |
+|---|---|
+| `IntegrityFlag` | Enum of all possible world integrity states |
+| `DeathLogEntry` | POJO holding death record; self-checksums via SHA-256 |
+| `DeathSealManager` | Persists/loads death seals in `<worldDir>/soulbind/<uuid>.json` |
+| `SoulbindEventHandler` | Forge event handler: creates seals on death, enforces spectator on login |
+
+**Flow**: Player dies in Hardcore → `LivingDeathEvent` → `DeathLogEntry` created with
+`computeChecksum()` → written to disk → player set to SPECTATOR.  On next login,
+`PlayerLoggedInEvent` checks `isSealed()` and re-enforces spectator if necessary.
+
+### 2. `integrity` — World File Tamper Detection
+
+| Class | Role |
+|---|---|
+| `WorldChecksumValidator` | Computes SHA-256 of `level.dat`; persists to `hik_integrity.json` |
+| `LevelDatWatcher` | Listens to `ServerStartingEvent`; delegates to `WorldChecksumValidator` |
+| `IntegrityOverlay` | Client-side HUD overlay (green/red label showing integrity state) |
+
+**Flow**: Server starts → `LevelDatWatcher.onServerStarting` → `initOrValidate` reads
+`hik_integrity.json`; if hash differs, `markCompromised(TAMPERED_LEVEL_DAT)`.
+
+### 3. `backup` — Session Continuity & Rollback Detection
+
+| Class | Role |
+|---|---|
+| `SessionIdManager` | Generates/persists stable UUID per world in `hik_session.json` |
+| `BackupDetector` | Persists game tick every 600 ticks; rollback if tick goes backwards |
+
+**Flow**: Every 600 ticks (`≈30 s`), `BackupDetector.onLevelTick` persists the current
+game time.  If the recorded tick is *higher* than the current tick, a rollback is
+inferred and the world is marked `ROLLBACK_DETECTED`.
+
+### 4. `spectator` — Lock Enforcement & Archive Countdown
+
+| Class | Role |
+|---|---|
+| `SpectatorLockHandler` | In-memory set of locked UUIDs; per-tick spectator re-enforcement |
+| `ArchiveCountdown` | Countdown map (uuid → expiry ms); triggers archive-pending log |
+| `CommandInterceptor` | Blocks `gamemode`, `gm`, `give`, `tp`, `teleport`, `kill` for locked players |
+
+**Flow**: On death seal → `SpectatorLockHandler.lockPlayer(uuid)` +
+`ArchiveCountdown.startCountdown(uuid)`.  Per tick, spectator mode is re-applied.
+Commands are intercepted via `CommandEvent`.
+
+### 5. `lan` — LAN Cheat & Read-Only Enforcement
+
+| Class | Role |
+|---|---|
+| `LanMenuMixin` | Mixin on `ShareToLanScreen`; disables "Allow Cheats" button on Hardcore worlds |
+| `CheatFlagWatcher` | Server tick watcher; detects `getAllowCommands()` transition to `true` |
+| `ReadOnlyWorldEnforcer` | Cancels `BlockEvent.BreakEvent` / `EntityPlaceEvent` when integrity ≠ CLEAN |
+
+---
+
+## Integrity State Machine
+
+```
+UNKNOWN  ──(world load, hash matches)──▶  CLEAN
+CLEAN    ──(hash mismatch)─────────────▶  TAMPERED_LEVEL_DAT
+CLEAN    ──(death seal tampering)───────▶  TAMPERED_DEATH_LOG
+CLEAN    ──(tick rollback)──────────────▶  ROLLBACK_DETECTED
+CLEAN    ──(LAN cheats enabled)─────────▶  LAN_CHEAT_DETECTED
+*        ──(any of the above)───────────▶  COMPROMISED  (generic alias)
+```
+
+Once compromised, `ReadOnlyWorldEnforcer` prevents all block mutations if
+`read_only_on_external_cheat_flag = true`.
+
+---
+
+## Known Limitations / Deferred Items
+
+- **Verification API** (`verification_api_port`): HTTP endpoint for external audit queries
+  is not implemented in MVP.  Port config key is reserved for Phase 2.
+- **Ed25519 signing**: Death seals currently use SHA-256 checksums only.  Asymmetric
+  signing (Ed25519) is deferred to Phase 2 for non-repudiation.
+- **Full inventory provenance** (`strict_inventory_provenance`): Item-level tracking
+  (who crafted/picked up each item) is a no-op in MVP.
+- **Merkle tracking integration**: The existing `ChunkHasher` / `NotaryBlock` Merkle
+  system is not yet wired into HIK's per-chunk integrity checks.
+- **Archive automation**: `ArchiveCountdown` logs "archive pending" but does not yet
+  copy the world directory to `archive_path`.  Automation is Phase 2.
+- **`SpectatorLockHandler` persistence**: The in-memory lock set is rebuilt from
+  `DeathSealManager.isSealed()` checks on login; explicit startup hydration is Phase 2.
+
+---
+
+## MVP Scope
+
+The MVP delivers:
+1. Cryptographic death sealing with tamper-detectable checksums
+2. `level.dat` hash comparison on every world load
+3. Game-tick rollback detection (every 30 s)
+4. Per-tick spectator mode enforcement + command interception
+5. LAN cheat detection and read-only enforcement
+6. Client HUD overlay showing integrity state
+7. Forge config file with all tunable knobs
+8. Mixin to disable "Allow Cheats" on the LAN share screen for Hardcore worlds

docs/MODPACK_COMPATIBILITY.md

@@ -0,0 +1,26 @@
+# HIK Modpack Compatibility
+
+## LAN screen mixin
+
+HIK applies a single client-side mixin to `ShareToLanScreen` in order to disable
+the vanilla **Allow Cheats** toggle for Hardcore worlds.
+
+### Conflict strategy
+
+- `LanMenuMixin` uses `@Inject(at = @At("RETURN"))`, not `@Overwrite`
+- Mixin priority is lowered to `900` so other mods can build the final button list first
+- `MixinConfigPlugin` skips the mixin entirely if the target screen is unavailable
+
+### Button matching
+
+The filter is intentionally narrow and only disables labels containing both
+`allow` and `cheat` so unrelated LAN buttons remain untouched.
+
+### Manual compatibility checks recommended
+
+Before shipping a pack, verify LAN screen behaviour alongside any mod that also
+patches the pause/LAN UI, especially:
+
+- Essential
+- LAN World Plug-n-Play
+- Any custom menu overhaul mod

src/main/java/com/truthsystems/TruthSystems.java

@@ -6,14 +6,19 @@
  */
 package com.truthsystems;
 
+import com.mojang.logging.LogUtils;
+import com.truthsystems.hardcore.HikConfig;
 import net.minecraftforge.fml.common.Mod;
 import net.minecraftforge.eventbus.api.IEventBus;
 import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext;
+import net.minecraftforge.fml.ModLoadingContext;
 import com.truthsystems.registry.*;
+import org.slf4j.Logger;
 
 @Mod(TruthSystems.MODID)
 public class TruthSystems {
     public static final String MODID = "truthsystems";
+    private static final Logger LOGGER = LogUtils.getLogger();
 
     @SuppressWarnings("removal")
     public TruthSystems(FMLJavaModLoadingContext context) {
@@ -22,5 +27,14 @@ public TruthSystems(FMLJavaModLoadingContext context) {
         ModItems.REGISTER.register(bus);
         ModBlockEntities.REGISTER.register(bus);
         ModEntities.REGISTER.register(bus);
+
+        // Register HIK configuration
+        ModLoadingContext.get().registerConfig(
+            net.minecraftforge.fml.config.ModConfig.Type.COMMON,
+            HikConfig.SPEC,
+            "truthsystems-hik.toml"
+        );
+        HikConfig.load();
+        LOGGER.info("[HIK] Hardcore Integrity Keeper initialized. Version: 1.1.0-part1");
     }
 }