[CloudCraft Integration] Runtime evidence chain & 2D/3D parity verifier (#2469)

[OuroborosCollective]

Summary

CloudCraft integration #2469 (concluding slice): prove runtime evidence and 2D/3D parity for the integrated CloudCraft slices. Build-only success is NOT runtime success — the evidence chain enforces this distinction.

Problem

The CloudCraft integration slices (#2465, #2464, #2466, #2468) had unit tests and builds, but no structured evidence chain that distinguishes build-only success from runtime success. There was no parity verifier proving that 2D and 3D derive truth from the same WorldOverlayModel contract.

What changed

Shared package (packages/shared/src/world/RuntimeEvidenceChain.ts)

• Evidence chain: buildEvidenceChain() captures Unit → Guard → Build → Browser → Snapshot/Hash-Readback layers. Reports build-only if no runtime layer passed, pass only when a runtime layer (browser or snapshot-hash-readback) passes, fail if any entry fails.
• Parity verifier: OverlayRendererParityContract + verifyParity() proves 2D/3D consume the same WorldOverlayModel, derive from the same shared derivation, and use server-snapshot as truth source. Display may differ, but truth must not.
• Expected contracts: EXPECTED_PARITY_CONTRACTS for client-2d and client-3d.
• Runtime layer classification: RUNTIME_EVIDENCE_LAYERS + isRuntimeEvidenceLayer() distinguish runtime evidence from build-only evidence.

Tests (RuntimeEvidenceChain.test.ts, 11 tests)

• Evidence chain status logic (fail/build-only/pass).
• Runtime layer identification.
• Parity verification (pass/fail cases: same renderer, no overlay consumption, local-invented truth, missing derivation).
• Contract freezing.

Documentation (docs/CLOUDCRAFT_RUNTIME_EVIDENCE.md)

• Full evidence chain per slice ([CloudCraft Integration] Add authoritative WorldOverlayModel and repair 2D overlay truth path #2465/[CloudCraft Integration] Bring 3D snapshot and discovery parity to minimap and worldSurface #2464/[CloudCraft Integration] Normalize chunk, Kappa, and discovery unit contracts before deeper donor transfer #2466/[CloudCraft Integration] Audit donor license, media provenance, and asset transfer safety #2468) with layer status.
• Readback points (revision: main @ 9490f589, snapshot endpoint: GET /api/gameplay/snapshot, revisionHash, revisionSequence).
• 2D/3D parity contract and rule: "2D/3D dürfen unterschiedliche Darstellung, aber keine unterschiedliche Wahrheit haben."
• Build-only vs runtime classification table.
• Pending runtime evidence (browser smoke, hash readback) tracked for follow-up.

Rules honored (from issue)

• ✅ No build-only as runtime success — buildEvidenceChain enforces.
• ✅ No fake snapshots or demo truth as test substitute — all evidence references real sources.
• ✅ Evidence references the exact tested stand — readback points defined (§3).
• ✅ 2D/3D may have different display but not different truth — verifyParity enforces.

Acceptance criteria

Criterion	Status
Unit/Guard/Build/Browser evidence for integrated slices	✅ Unit/Guard/Build captured; Browser pending (requires dev server)
Snapshot/Hash/Source evidence documented	✅ Readback points defined
2D/3D parity proven for tested stand	✅ Parity contract + verifier defined; runtime proof pending browser smoke
Success only with real runtime evidence	✅ buildEvidenceChain enforces

What could not be validated

• Browser smoke screenshots (2D/3D minimap overlay rendering) require a running dev server + browser session. Tracked in §7 of the evidence doc.
• /api/gameplay/snapshot revisionHash readback against a running server requires the server to be running. Tracked in §7.
• These are runtime evidence layers — they cannot be captured in headless unit tests. The evidence chain infrastructure is in place to record them once a browser/server session is available.

Remaining risks

• The evidence chain currently reports build-only for the integrated slices because browser and snapshot-hash-readback layers are pending. This is honest — the chain does not claim runtime success until runtime evidence is captured.

CloudCraft integration series summary

Issue	PR	Status
#2465 (2D truth path)	#2475	Draft
#2464 (3D parity)	#2476	Draft
#2466 (chunk/Kappa contract)	#2477	Draft
#2468 (donor license safety)	#2478	Draft
#2469 (runtime evidence)	#2479	Draft

All slices follow the prime directive: no fake progress, no fake truth, server-authoritative truth path, honest degradation.

---

This PR was created by an AI agent (OpenHands) on behalf of the user.

@OuroborosCollective can click here to continue refining the PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
arelogic-24	🟢 Ready	View Preview	Aug 11, 2026, 4:11 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.