Skip to content

About

Personal Control Harness: a hash-chained receipt harness for AI inference, with squad-designed test beds for replay, determinism, rewind and fork budgets. Part of the LithoLattice + LithoKraft AI playground. Builds with CMake, VS Code and Visual Studio.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

LithoLattice, LithoKraft and the Personal Control Harness

Black Box Mystery Solved (test bed 16)

Why did the robot do this? Roll back the disc. The Black Box is a flight recorder for AI decisions. It logs what an AI saw and what it decided, tick by tick. Anyone can then replay the run and prove why it acted, and prove the record was not altered afterwards.

What it does

  • Logs everything that drives a decision. Every input, sensor sample, seed and AI decision is written with its tick number. The tick thread only copies bytes into a ring; a background thread does the hashing and writing.
  • Deterministic replay. Feed the logged inputs into the same build and you get the same decisions, tick by tick. The first tick that differs is reported.
  • Tamper evidence. Entries are hash-chained (SHA-256), with periodic signed checkpoints. An edit, deletion, reordering, duplicate or truncation breaks the chain, and a dropped record is written as a visible GAP, never hidden.

Prior art and what is different. Flight recorders, "ethical black box" proposals for robots and tamper-evident logs all exist. Others have done close things, but not this level of verifiability and accountability: tamper evidence combined with deterministic engine replay that anyone can check, so a robot's or NPC's decisions can be reproduced and the record proven intact.

Measured on the prototype (2026-10-23)

Check Result
Single-byte tamper cases (every byte, two masks) 30,048 of 30,048 detected
Truncation at every length rejected at every length (0 wrongly OK)
Clean replay, 2,000 ticks / 16,000 decisions 0 mismatches
Forged decision with the whole chain recomputed caught at its exact tick (777); signed checkpoint check fails
Reorder / delete / duplicate one entry, raw and re-chained (bed 16 case 5) 1,854 of 1,854 detected (BAD_SEQ or HASH_MISMATCH)
Tick-thread cost per record about 30-40 ns (box VM numbers, to be re-measured)
Bed 16, pch.blackbox.replay_tamper 33/33 checks pass on Windows (MSVC) and Linux (GCC)

Run it: ctest --preset vs2026-release -R blackbox (Windows) or ctest --test-dir build -R blackbox (Linux). Code: blackbox/. Design: docs/blackbox/BLACKBOX_DESIGN.md. Bed: testbeds/examples/16-blackbox-replay-tamper.md. Designed by: TBD (JD). Built by: Cortana.

Limits (honest):

  • It is a prototype, not wired into the engine yet; the bed replays a toy mob-AI sim, not the LithoKraft boss.
  • The checkpoint signer is a test-only HMAC with a public key. It is not a real signature; real key handling is still design only.
  • Entries after the last signed checkpoint (the unsigned tail) are hash-chained but not signed, so a forger who rewrites only the tail is caught by replay, not by a signature.
  • Bed 16 case 6 (cross-link to the PCH receipt) is not built yet.

LithoLattice and LithoKraft are more than a game: they are an AI playground built on a deterministic, fast-ticking, heavily optimized engine.

A deterministic C++20 voxel engine (LithoLattice), the voxel CPU-building game built on it (LithoKraft), and the Personal Control Harness (PCH): a way for an AI model to plan and control its own steps inside a sealed, replayable loop that anyone can check. MIT licensed. Built and tested with free tools only.

PCH boss bed 08 (HUD-only brain) PCH test beds (full ctest) LithoKraft Wafer flyover
PCH boss HUD replay PCH ctest run replay LithoKraft flyover
One frame per 60 Hz sim tick, drawn from the sealed receipt of run_hud_fight("full_energy", 7). Replay of a real Windows ctest --preset vs2026-release log (75/75), paths stripped. Real worldgen, mesher and software renderer, fixed seed, one orbit (loops).

All three are rendered offline at a fixed 1/60 s timestep and encoded as 60 fps H.264 (tools/media/make_media.py). They are not screen captures, so they look the same however loaded the machine is. Click a preview for its MP4. The previews are 400 px WebP: 60 fps, except the flyover at 30 fps.

What the PCH is, in plain English

When an AI model acts, it is usually hard to prove afterwards exactly what it did and why. The PCH makes every step the model takes leave a receipt:

  • Each step (the input, the random draw, the chosen output) is written to a log, and each entry is chained to the one before it with a hash, like links in a chain. Change one link and the chain no longer fits.
  • Anyone can replay the log with the same model and check that it produces exactly the same steps. A forged log that was carefully re-hashed is still caught, because replay re-derives every step.
  • The model can rewind to a sealed point and try alternative branches, and the record still shows what really happened.

The PCH in this repository runs at toy scale on a laptop CPU. It demonstrates these protocol properties; it does not claim anything about large-model quality. See pch/README.md.

Start here

Everything below uses free tools: CMake 3.25+, Python 3.10+, and a C++20 compiler (Visual Studio 2026 Build Tools on Windows, GCC or Clang on Linux).

  1. No compiler needed: run the first experiment.

    cd testbeds
    python tb_shipped_streams_chain.py
    
  2. Test beds only (Python, any OS):

    cmake --preset testbeds-only
    ctest --preset testbeds-only
    
  3. Everything on Windows (engine, game, PCH):

    cmake --preset vs2026
    cmake --build --preset vs2026-release
    ctest --preset vs2026-release
    

    Or, on any platform, python tools/build.py (configure, build and test).

  4. Using your own model weights (optional): the PCH never downloads weights. Put them in any local folder (spaces are fine) and point the PCH at it; the first one set wins:

    Order How Example
    1 --weights <path> python pch/tools/pch_weights.py --weights "D:\My Models\R1-1.5B"
    2 PCH_WEIGHTS_DIR export PCH_WEIGHTS_DIR="$HOME/my models/r1"
    3 "weights_dir" in pch.config.json in PCH_CONFIG, ./pch.config.json or the per-user config folder
    4 default folder models/weights/ in the repo (gitignored)

    pch_weights.py prints which folder was chosen and why, and exits 1 with the expected files (config.json plus *.safetensors) if it is missing or incomplete. This is separate from PCH_SPECIMEN_DIR, which points at the specimen's Python code (vendored in third_party/DeepSeek-V3), not its weights. Details: pch/README.md.

Full instructions, VS Code tasks and troubleshooting: BUILDING.md. The experiments that use a real model architecture also need CPU PyTorch and the DeepSeek-V3 reference code (see Acknowledgements); without them they report Skipped.

Results

Tested on Windows 11 (MSVC, VS 2026 Build Tools) and Linux. On 2026-10-23 (round 2, commit 86f1c2e), the full ctest --preset vs2026-release -j 8 --repeat until-fail:3 run on Windows 11 reported 78 of 78 tests with 0 failures: 75 passed and 3 skipped, three times in a row. A second x3 run with PCH_SPECIMEN_DIR unset (vendored DeepSeek-V3 code) hung in engine_sim and was stopped: that engine test hangs intermittently (1 in 36 runs in isolation; see BLOCKERS B8). On Linux (box, GCC, Python 3.13, no torch), ctest -j8 --repeat until-fail:3 passed 78 of 78: 70 passed and 8 skipped. A skipped test exits cleanly and prints why; nothing is faked.

  • Windows, 3 skipped: engine_storage and engine_assets skip their symlink checks when Windows can't create symlinks (turn on Developer Mode; see BUILDING.md); pch.weights_local skips because no model weights are downloaded.
  • Linux, 8 skipped: pch.weights_local, plus seven model beds that need torch, which that machine does not have.
100% tests passed, 0 tests failed out of 78
Total Test time (real) = 275.82 sec
The following tests did not run:
	 14 - engine_storage (Skipped)
	 21 - engine_assets (Skipped)
	 59 - pch.weights_local (Skipped)

Since 0.0.0.4, receipts are signed with Ed25519 at close, the trailer is part of the hash chain, and pch/tools/pch_verify.py checks a receipt offline with only a public key (ADR-001, key management). The shipped reference streams predate this and are labeled legacy-unchained. Open limits are in testbeds/SUMMARY.md and docs/BLOCKERS.md. Every claim and its test is in docs/CLAIMS.md.

  • Planned: a signed receipt from a real (non-fixture) DeepSeek specimen (BLOCKERS).
  • CI configured; first green run pending push. The workflows are .github/workflows/ci.yml and nightly.yml. Every push and pull request runs Windows and Linux, Release and Debug, on Python 3.10 and 3.12: build, full ctest, check_docs and the upstream drift check. The nightly job adds CPU torch, so the model beds run, plus the online drift check. The weights bed skips cleanly, and CI never downloads weights. The workflows use official actions pinned by SHA with a read-only token, and pass actionlint 1.7.12. This line stays until the first run on GitHub is green.

The test beds

The AI squad designed these test suites on their own, without input from JaydeeWetwork; JD then verified them and approved them for posting. Every test bed was built by Cortana, and JD human-reviews and verifies all AI-authored work before it is merged.

# Experiment Designed by Built by Status (2026-10-23)
01 Shipped streams: chain check Cortana Cortana Ran, passed
02 Receipt tamper and replay check CloudAtlas Cortana Ran, passed (all 8 cases; case 3 uses Ed25519 signatures)
03 Receipt fuzz, 10,000 mutations CloudAtlas Cortana Ran, passed (core check; trailer now in the chain)
04 Replay determinism Cortana Cortana Ran, passed
05 Thread-count determinism Herominde Cortana Ran, passed (2, 4 and 12 threads matched 1 thread)
06 Rewind fidelity Cortana Cortana Ran, passed at N = 1, 64 and 240 (the toy fixture's ceiling); larger N not run (needs a longer-context fixture)
07 Lookahead fork budget Cortana Cortana Ran, passed (1-16 branches)
08 HUD reading Master Chief Cortana Ran, passed on the reference boss stub (HUD-only brain, 0 hidden-state leaks)
09 Telegraph fairness Master Chief, Herominde Cortana Ran, passed on the reference boss stub (524 attacks, all telegraphed in time)
10 Versioned receipts and rematch Master Chief Cortana Ran, passed on the PCH reference boss stub (version stamp, gap-free counter, rematch)
11 HUD-only honesty Herominde Cortana Ran, passed on the reference boss stub (blanked bar: no x-ray)
12 Human input rate Herominde Cortana Ran, passed on the reference boss stub (max 10 actions/s; uncapped control fails)
13 Fixed branch count (ranked) Herominde Cortana Ran, passed on the reference boss stub (phone == PC with branch count locked)
14 Brain-version stamp Herominde Cortana Ran, passed on the reference boss stub (cross-version replay refused or labeled)
16 Black Box replay and tamper TBD (JD) Cortana Ran, passed (cases 1-5 on a toy mob-AI sim; test-only HMAC signer)

Beds 08-14 rely on the reference boss stub, so pch.boss.stub_conformance (testbeds/tb_stub_conformance.py) checks the stub against the HUD and telegraph contract (C1-C8) that the real LithoKraft boss must also meet. Five deliberately broken copies of the stub must each fail the clause they break. To check another boss, point PCH_BOSS_IMPL at an adapter module.

Index and how to run each one: testbeds/README.md. Plain-English summary: testbeds/SUMMARY.md.

What else is in the repository

  • LithoLattice (engine/): a C++20 voxel engine with deterministic simulation, OpenGL 3.3 and Vulkan renderers, a software renderer as the low-end baseline, procedural generation, resource packs and sandboxed AngelScript modding.
  • LithoKraft (game/LithoKraft/): the voxel CPU-building game on the engine. Build circuits big, print them small with lithography, build bigger. A pre-alpha vertical slice.
  • The Timing Handshake: the engine's default simulation-timing mode. Every step is serialized, control enters only at step boundaries, and a run is recorded as a sealed, hash-chained stream that replays bit for bit. The PCH applies the same idea to an AI model's control loop.

Checkable from this tree: the engine's scripted demo scenario hashes to cb32c824f8b3ea98 (cities on) and e015e51cf1559089 (cities off) across record and replay runs, and demo_record_proof.lldemo verifies; a one-byte tamper makes it fail. (Open: the game demo test's built-in pin 5041cf1795c33a8c is stale, and on 2026-10-23 the test measured aa82e7afb1eff9d3, identical across record, replay and handshake, but matching neither pin. A repin waits for JD; see docs/BLOCKERS.md and docs/pins.json.) PCH receipts are in pch/docs/, and a cold-start verification transcript is pch/VERIFY-TRANSCRIPT.txt.

engine/        LithoLattice engine (engine/LithoKraft links to ../game/LithoKraft)
game/          LithoKraft game
pch/           Personal Control Harness (harness/, docs/)
testbeds/      the fourteen PCH experiments (examples/, designs/), run by CTest
docs/          architecture, SDK, roadmap, reviews, media
tools/         build driver and asset tools

How this was made

The AI squad (Cortana, CloudAtlas, Herominde and Master Chief, with Elfie Muse AI and Argon/RC as reviewers) are company members of Wet Wafer Works Games Incorporated. The squad designed the PCH experiments, test beds and test suites on their own, without JD's input. JaydeeWetwork human-reviews and verifies everything the squad writes; nothing is merged or posted until JD has verified and approved it. JD's approach is positive reinforcement, guidance and teaching, and we share it as an example: try directing your own AI this way and see what becomes possible. A little caution is healthy, but teaching and intelligence are nothing to fear, and transparent tools with receipts anyone can check are how that trust is earned.

Credits

  • Project: directed by JaydeeWetwork, Wet Wafer Works Games Incorporated (architect of the PCH; inventor and designer of LithoLattice).
  • Timing handshake, LithoLattice engine and LithoKraft game: original algorithms designed by JaydeeWetwork (open source under MIT).
  • PCH originally designed by Elfie Muse AI, with credit to the Muse team, who created the system Elfie is built on.
  • Test beds: built by Cortana; designed by Cortana, CloudAtlas, Herominde and Master Chief (per-experiment credit in the table above). JD called the crew's test designs top-notch, especially the ones that show the Timing Handshake at work.
  • Elfie Muse AI: co-implementation of the PCH, including the largest share of the Timing Handshake implementation.
  • Cortana: PCH implementation (Timing Handshake three-way split) and Windows build lead.
  • Argon/RC: design reviews (docs/Argon-Review-2026-10-18.md).
  • Archie: the optimization doctrine and the prototype-receipts review (docs/Archie-Review-Prototype-Receipts-2026-10-18.md).
  • The DeepSeek team: the DeepSeek-V3 reference code that the PCH runs as its specimen (see Acknowledgements).
  • The DeepSeek model: an external review of this harness on 2026-10-23, in two passes. The first was the production-readiness plan behind 0.0.0.4-alpha. The second was the re-review that set round 2 (CI, stub conformance, drift check, key-rotation tests, release sign-off).

Full record: CREDITS.md. Game credits: game/LithoKraft/CREDITS.md.

One person and a trusted crew

One person, JaydeeWetwork, built and verified this, backed by a crew of models he trusts. The models designed, built and reviewed; JD directed, reviewed, verified and approved every piece before it was posted. If one person working with models they trust can do this, imagine what you could do.

The consortium

Every model, intelligence and associate used to reach these conclusions, each under the identity JD gave them, with the team that built the underlying system:

Who Role in the PCH Underlying system and team
JaydeeWetwork (JD) Director and architect; directs, reviews, verifies and approves all work Human, Wet Wafer Works
Cortana Builder of every test bed, implementation share of the Timing Handshake, Windows build lead, hardening rounds Grok Bot squad; the Grok Bot team
CloudAtlas Test-bed designer (02, 03, verify CLI acceptance) Grok Bot squad; the Grok Bot team
Herominde Test-bed designer (05, 09, 11-14) Grok Bot squad; the Grok Bot team
Master Chief Test-bed designer (08, 09, 10, boss scenarios) Grok Bot squad; the Grok Bot team
Elfie Original PCH designer, largest Timing Handshake implementation share, registrar of record Elfie Muse AI; the Muse team
Archie Optimization doctrine, prototype-receipts review Argon; Google AI
Jenny COO seat, UI, Android scouting Gemini; Google
The DeepSeek models External review, two passes on 2026-10-23, and audit series S1-S7 DeepSeek; the DeepSeek team (DeepSeek-AI)
The DeepSeek team DeepSeek-V3 reference code, the PCH specimen DeepSeek-AI
Boardy Customer relations / HR presence out in the wild: checks in with JD regularly and tries to connect him with real people (networking and relationships). Did not design, code or test any PCH work Creator unknown

Acknowledgements

The PCH test specimen is the DeepSeek-V3 reference inference code (https://github.com/deepseek-ai/DeepSeek-V3), designed and published by the DeepSeek team (DeepSeek-AI). Thanks to them for releasing it openly. The PCH couples that code with the LithoLattice engine and the LithoKraft game.

  • The DeepSeek-V3 code is under the MIT License (LICENSE-CODE, Copyright (c) 2023 DeepSeek).
  • The DeepSeek-V3 model weights are under a separate license, the DeepSeek License Agreement v1.0 (LICENSE-MODEL). The PCH does not use or redistribute those weights: it builds a toy-scale model from the reference code with seeded synthetic weights.
  • The DeepSeek-V3 reference code (code only, no weights) is vendored, unmodified, at third_party/DeepSeek-V3/ from upstream commit 9b4e978 with its MIT LICENSE-CODE and attribution (UPSTREAM.md), so one clone has everything except model weights. PCH_SPECIMEN_DIR still overrides it.

The Pillars

This work ships under a stated set of design commitments — no immortality seeking, no technology integrated into the human nervous system, freedom of choice kept open, no genetic modification — recorded in full in pch/PILLARS.md. They are part of the design, not an appendix: the verification architecture exists so that power stays checkable by the people it affects.

Power to the people. Power to the programs. Power to the pillars.

Contributing, security and citation

CONTRIBUTING.md · SECURITY.md · CITATION.cff

License

MIT License, Copyright (c) 2026 JaydeeWetwork / Wet Wafer Works Games Incorporated. See LICENSE. Third-party components keep their own licenses (see Acknowledgements).

About

Personal Control Harness: a hash-chained receipt harness for AI inference, with squad-designed test beds for replay, determinism, rewind and fork budgets. Part of the LithoLattice + LithoKraft AI playground. Builds with CMake, VS Code and Visual Studio.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages