docs(cloudcraft): define runtime evidence and parity plan - #2488
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ca45a92ba8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `worldSurface.tick`, Gruppen- und Punktzahl | Snapshot-Antwort | Prüft denselben worldSurface-Faktensatz in beiden Clients | | ||
| | POI-, Ressourcen- und Camp-NPC-Zahl | Snapshot-Antwort und sichtbare Projektion | Prüft Discovery-Parität ohne Identitätsgleichheit der Darstellung | | ||
|
|
||
| Die Screenshot-Zeitpunkte müssen höchstens einen Polling-Zyklus vom protokollierten Snapshot entfernt liegen. Abweichende Icons, Farben oder 2D-/3D-Geometrie sind erlaubt; abweichende Datenquellen, eigene Discovery-Berechnung oder ein vom Snapshot abweichender Faktensatz sind es nicht. |
There was a problem hiding this comment.
Require the readback to identify the response actually consumed by each renderer rather than any response within one polling cycle. The 3D bridge polls every five seconds and its production subscriber forwards only the derived markers and status to the minimap (client/src/networking/websocketClient.ts:589-593), discarding serverTick and revisionHash; during an active runtime, a separate GET taken within that window can therefore contain a newer tick and different facts even though the screenshot still shows the previous poll. Export or visibly render the bridge/store revision used for the frame so the evidence cannot pair a screenshot with an unconsumed snapshot.
Useful? React with 👍 / 👎.
|
|
||
| ## Aktueller Entscheidungsstatus | ||
|
|
||
| Die Unit-, Guard- und Build-Nachweise aus PR #2484 sind vorhanden. Authentifizierte Browser-Sessions und serverseitige Snapshot-Readbacks stehen in der aktuellen Arbeitsumgebung nicht bereit. Deshalb lautet der Status **build-only**; die Issue-Abnahme darf erst nach den oben beschriebenen realen Runtime-Nachweisen erfolgen. |
There was a problem hiding this comment.
Do not attribute the build-only status solely to unavailable browser sessions: the current production 3D path calls buildMinimapMarkersFromOverlay, which includes only POIs, resources, and camp NPCs, while overlaySurfacePointsTo3D has no non-test caller, so no Babylon world object can appear when worldSurface.points arrives. The designated project status and roadmap documents also still mark 3D lineage worldSurface rendering as open under #2046; add that implementation prerequisite to this plan/todo before suggesting evidence capture alone can complete the gate.
AGENTS.md reference: AGENTS.md:L12-L16
Useful? React with 👍 / 👎.
| | Git-Revision | getesteter Server-/Client-Head | Bindet die Evidence an einen unveränderten Stand | | ||
| | `serverTick` | Snapshot-Antwort | Ordnet Darstellung einer autoritativen Simulationstaktung zu | | ||
| | `revisionHash` | Snapshot-Antwort | Bindet Client-Faktensatz an Serverrevision | | ||
| | `sourceEvidence` | Snapshot-Antwort | Zeigt, welcher reale Serverprovider die Fakten geliefert hat | |
There was a problem hiding this comment.
Describe sourceEvidence as a payload digest rather than proof of which real provider supplied the facts. In server/src/routes/gameplaySnapshot.ts, moduleEvidence() always returns only { status: "live", hash }, and the route contains no provider identifier or fallback/health metadata; consequently this field cannot establish the claimed provenance and may label an empty or fallback-derived value as live. The acceptance protocol needs an actual provider identity/health readback if provider provenance is required.
Useful? React with 👍 / 👎.
| | Unit | Shared-Overlay-Derivation, 2D-Adapter, Babylon-Adapter und Snapshot-Bridge-Tests | Beide Clients verarbeiten denselben `WorldOverlayModel`-Vertrag; `blocked` und `waiting` erzeugen keine erfundene Wahrheit | Nein | | ||
| | Guard | Architektur- und Determinismus-Guard | Keine neue clientseitige Discovery-Wahrheit, kein entkoppelter Chunk-/Kappa-Vertrag | Nein | | ||
| | Build | 2D- und 3D-Produktionsbuild | Aktive Entrypoints und Adapter lösen auf dem getesteten Head auf | Nein | | ||
| | Browser | Authentifizierte reale 2D- und 3D-Session gegen denselben Serverstand | Sichtbarer Zustand für denselben autoritativen Faktensatz; keine statische Demo und keine Fixture-Truth | Ja, nur zusammen mit Readback | |
There was a problem hiding this comment.
Add authentication wiring as a prerequisite for this authenticated browser/readback step. In locked production, GET /api/gameplay/snapshot rejects identities that are not authenticated, but ServerBootstrap mounts the router without auth middleware, resolveHttpPlayerIdentity() does not inspect bearer tokens, and the 3D bridge sends neither an Authorization header nor a player ID; therefore a successfully authenticated WebSocket session still gets a 401 from the bridge when guest/dev fallbacks are disabled. The documented production auth controls make that the relevant acceptance environment, so evidence capture alone cannot satisfy this row.
AGENTS.md reference: AGENTS.md:L62-L71
Useful? React with 👍 / 👎.
|
|
||
| | Feld | Quelle | Zweck | | ||
| |---|---|---| | ||
| | Git-Revision | getesteter Server-/Client-Head | Bindet die Evidence an einen unveränderten Stand | |
There was a problem hiding this comment.
Require runtime readback of the server and both client build hashes instead of recording only the checkout believed to be under test. revisionHash hashes the dynamic gameplay payload and contains no Git/build identifier, so a stale server or independently deployed 2D/3D bundle can still produce internally valid snapshot hashes that are then mislabeled with the local head. The deployment already exposes build identity through /client-config.json and client build stamps; capture those runtime values and compare them with the intended revision.
Useful? React with 👍 / 👎.
| | Guard | Architektur- und Determinismus-Guard | Keine neue clientseitige Discovery-Wahrheit, kein entkoppelter Chunk-/Kappa-Vertrag | Nein | | ||
| | Build | 2D- und 3D-Produktionsbuild | Aktive Entrypoints und Adapter lösen auf dem getesteten Head auf | Nein | | ||
| | Browser | Authentifizierte reale 2D- und 3D-Session gegen denselben Serverstand | Sichtbarer Zustand für denselben autoritativen Faktensatz; keine statische Demo und keine Fixture-Truth | Ja, nur zusammen mit Readback | | ||
| | Snapshot-/Hash-Readback | Rohantwort von `GET /api/gameplay/snapshot` derselben Session plus Revision und Hash | `serverTick`, `revisionHash`, `sourceEvidence` und die vom Client gezeigten Fakten lassen sich zuordnen | Ja, nur zusammen mit Browser | |
There was a problem hiding this comment.
Do not require the raw response to be stored unchanged while also prohibiting personal data. For a real authenticated session, this endpoint returns the player ID plus character, inventory, quest, guild, and other player-scoped state, so saving the raw body directly violates the later no-personal-data requirement. Define an allowlisted evidence extract containing only the tick, hashes, source-evidence digests, and aggregate world counts, or explicitly specify a verified redaction step.
Useful? React with 👍 / 👎.
|
|
||
| | Schicht | Nachweis | Akzeptanzkriterium | Gilt allein als Runtime-Erfolg? | | ||
| |---|---|---|---:| | ||
| | Unit | Shared-Overlay-Derivation, 2D-Adapter, Babylon-Adapter und Snapshot-Bridge-Tests | Beide Clients verarbeiten denselben `WorldOverlayModel`-Vertrag; `blocked` und `waiting` erzeugen keine erfundene Wahrheit | Nein | |
There was a problem hiding this comment.
Do not use these unit results to claim that both clients process the same contract. The 3D bridge imports WorldOverlayModel and deriveWorldOverlayModelFromSnapshot from @wasd/shared, while the 2D hook imports a separate local implementation from apps/client-2d/src/game/WorldOverlayModel.ts; the implementations already disagree because the 2D version returns live whenever the snapshot says live, whereas the shared derivation returns blocked without worldSurface and empty for a live snapshot with no overlay entries. Move 2D onto the shared derivation or add cross-client equivalence tests before treating this row as parity evidence.
Useful? React with 👍 / 👎.
| | Browser | Authentifizierte reale 2D- und 3D-Session gegen denselben Serverstand | Sichtbarer Zustand für denselben autoritativen Faktensatz; keine statische Demo und keine Fixture-Truth | Ja, nur zusammen mit Readback | | ||
| | Snapshot-/Hash-Readback | Rohantwort von `GET /api/gameplay/snapshot` derselben Session plus Revision und Hash | `serverTick`, `revisionHash`, `sourceEvidence` und die vom Client gezeigten Fakten lassen sich zuordnen | Ja, nur zusammen mit Browser | |
There was a problem hiding this comment.
Update the executable evidence verifier to match the new requirement that Browser and Snapshot/Hash-Readback pass only together. buildEvidenceChain() in packages/shared/src/world/RuntimeEvidenceChain.ts:55-63 currently sets the overall status to pass when any single browser or snapshot-readback entry passes, so a browser screenshot with a skipped readback—or a readback with no browser smoke—can still be recorded as a successful chain despite these rows explicitly forbidding that. Require successful entries for both runtime layers before returning pass.
Useful? React with 👍 / 👎.
|
|
||
| ## Geltungsbereich | ||
|
|
||
| Dieser Plan bezieht sich auf den Integrationsstand `12ee850e7264c60d60c14bbf4a05af46e4003d2d` aus [PR #2484](https://github.com/OuroborosCollective/Wasd/pull/2484). Er definiert die Mindestkette für die dort ergänzten Discovery- und `worldSurface`-Slices. Bis zu einem realen Browser- und Snapshot-Readback bleibt jeder erfolgreiche Unit-, Guard- oder Build-Lauf ausdrücklich **build-only**. |
There was a problem hiding this comment.
Replace this PR/head attribution with the revisions that actually introduced the slices. The reviewed #2484 change contains only this plan and todo.md, while the 2D truth path, shared/3D bridge, chunk contract, and evidence verifier were merged in #2475, #2476, #2477, and #2479 respectively; describing #2484 as the integration stand that added those slices makes the evidence trace point to a documentation-only change and obscures which code was tested. List the relevant merged revisions, plus the final combined deployment revision if needed.
Useful? React with 👍 / 👎.
…me-evidence-plan # Conflicts: # todo.md
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
1 participant
Scope\n- defines the required Unit, Guard, Build, Browser, and Snapshot/Hash-Readback chain for #2469\n- binds evidence to the exact PR #2484 integration head\n- distinguishes build-only proof from a real runtime pass\n\n## Decision\nRuntime browser and authenticated snapshot evidence remain pending; this PR does not claim the integration issue complete.\n\nNo client truth, snapshot data, runtime behavior, or simulation invariant is changed.