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.
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.
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.
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).
-
No compiler needed: run the first experiment.
cd testbeds python tb_shipped_streams_chain.py -
Test beds only (Python, any OS):
cmake --preset testbeds-only ctest --preset testbeds-only -
Everything on Windows (engine, game, PCH):
cmake --preset vs2026 cmake --build --preset vs2026-release ctest --preset vs2026-releaseOr, on any platform,
python tools/build.py(configure, build and test). -
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_DIRexport PCH_WEIGHTS_DIR="$HOME/my models/r1"3 "weights_dir"inpch.config.jsonin PCH_CONFIG,./pch.config.jsonor the per-user config folder4 default folder models/weights/in the repo (gitignored)pch_weights.pyprints which folder was chosen and why, and exits 1 with the expected files (config.jsonplus*.safetensors) if it is missing or incomplete. This is separate fromPCH_SPECIMEN_DIR, which points at the specimen's Python code (vendored inthird_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.
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_storageandengine_assetsskip their symlink checks when Windows can't create symlinks (turn on Developer Mode; see BUILDING.md);pch.weights_localskips 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.ymlandnightly.yml. Every push and pull request runs Windows and Linux, Release and Debug, on Python 3.10 and 3.12: build, full ctest,check_docsand 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 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.
- 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
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.
- 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, 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.
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 |
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 commit9b4e978with its MITLICENSE-CODEand attribution (UPSTREAM.md), so one clone has everything except model weights.PCH_SPECIMEN_DIRstill overrides it.
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.md · SECURITY.md · CITATION.cff
MIT License, Copyright (c) 2026 JaydeeWetwork / Wet Wafer Works Games Incorporated. See LICENSE. Third-party components keep their own licenses (see Acknowledgements).


