Compare commits

...
148 Commits
Author SHA1 Message Date
UnixNight 404b4b4d4a docs(01): verify bundled checker repair and restart pending UAT 2026-11-14 17:00:38 -05:00
UnixNight 2fe8b40ea5 fix(01): keep bundled Python commands from writing bytecode caches 2026-11-14 16:53:30 -05:00
UnixNight 23ee1c2e47 test(01): reproduce bundled checker creating immutable bytecode caches 2026-11-14 16:50:04 -05:00
UnixNight 07793af9fc docs(01): keep local-only API declaration within preflight limit 2026-11-14 16:33:42 -05:00
UnixNight 898aef7ffa docs(01): normalize final verification report whitespace 2026-11-14 00:41:11 -05:00
UnixNight f7e7033514 docs(01): persist final verification and pending combined-session UAT 2026-11-14 00:40:51 -05:00
UnixNight febb4a9d98 docs(01): express existing verification goal as required user story 2026-11-14 00:32:22 -05:00
UnixNight 08150c0199 docs(pause): preserve final verification continuation at quota reserve 2026-11-13 17:27:15 -05:00
UnixNight 71366e7d45 docs(01): close review and security gates with acceptance pending 2026-11-13 17:22:39 -05:00
UnixNight 02d182f35d fix(01-07): validate actual copy-state artifacts at scenario boundary 2026-11-13 17:18:39 -05:00
UnixNight 48fca0df52 test(01-07): reject copy-state identities without backing artifacts 2026-11-13 17:16:54 -05:00
UnixNight a821754b67 test(01): WR-01 verify readiness after transfer without Git 2026-11-13 17:08:10 -05:00
UnixNight 2608517c37 fix(01): WR-02 recover interrupted Windows runs without invented clocks 2026-11-13 17:07:44 -05:00
UnixNight 548c97aa58 fix(01): WR-01 preserve validated capability history in checkpoint viewer 2026-11-13 17:07:44 -05:00
UnixNight 6e5ee0bd25 fix(01): CR-03 bind lifetime continuity to named copy snapshots 2026-11-13 17:02:22 -05:00
UnixNight bda35e5bf5 fix(01): CR-02 bind original evidence to pristine inventory members 2026-11-13 17:01:42 -05:00
UnixNight 5569bc2b8b fix(01): CR-01 bind review digest to selected receipt bytes 2026-11-13 17:00:47 -05:00
UnixNight 5915128570 docs(01): record final code review findings and disposition 2026-11-13 16:58:55 -05:00
UnixNight 215d01e43e docs(01-07): track completed preparation and open acceptance gate 2026-11-13 16:49:31 -05:00
UnixNight 52a3e2d5ff docs(01-07): record verified preparation and pending human acceptance 2026-11-13 16:48:09 -05:00
UnixNight 472500bf4e test(01-07): integrate counted fidelity regressions and exact local results
Run existing fidelity Python, Node and observer checks with positive-count guards and explicit TAP output. Record the completed 782.05-second local suite and preserve human acceptance at 0/120.
2026-11-13 16:44:59 -05:00
UnixNight b732256751 docs(pause): save quota-guard checkpoint at 01-07 task3 2026-11-13 12:29:02 -05:00
UnixNight fc5e936fd7 docs(01-07): retain pending combined-session acceptance and diagnostic identity 2026-11-13 12:18:43 -05:00
UnixNight 026def9c5a feat(01-07): audit prepared fidelity materials and strict human acceptance 2026-11-13 12:17:46 -05:00
UnixNight d78b13566d test(01-07): specify strict final fidelity acceptance gates 2026-11-13 12:09:46 -05:00
UnixNight d18f551a26 docs(01-06): record reviewed Linux capture tooling and access limits 2026-11-13 12:06:50 -05:00
UnixNight ef021e79f0 docs(01-06): retain SDK planning-state companion 2026-11-13 12:05:41 -05:00
UnixNight 589481218d docs(01-06): advance completed capture plan tracking 2026-11-13 12:05:23 -05:00
UnixNight c60248dbfe docs(01-06): record Linux capture limits and complete open matrix 2026-11-13 12:04:22 -05:00
UnixNight 0172916ffd feat(01-06): preserve full Linux obligation matrix and capture history 2026-11-13 12:02:33 -05:00
UnixNight e17cfbebe3 test(01-06): require full Linux matrix continuity and resume history 2026-11-13 11:57:23 -05:00
UnixNight 16f5e126be feat(01-06): collect bounded Linux capture and honest failed preflight 2026-11-13 11:56:08 -05:00
UnixNight 9c59f60b50 test(01-06): require bounded Linux capture round trip 2026-11-13 11:52:12 -05:00
UnixNight 31ae6a6ab2 docs(01-05): record primary review and retain consumed handoff 2026-11-13 11:48:20 -05:00
UnixNight 1af5217e47 docs(01-05): advance verified checkpoint plan tracking 2026-11-13 11:46:26 -05:00
UnixNight 2d48ee5316 docs(01-05): complete offline Windows checkpoint plan 2026-11-13 11:45:36 -05:00
UnixNight aa4b862a12 fix(01-05): retain executable permissions in offline copies
Preserve source read/write/execute bits without privileged mode bits. Verify copied Linux apphost byte identity and permissions.
2026-11-13 11:43:51 -05:00
UnixNight 857466568d feat(01-05): complete offline Windows collection agenda and selftests
Prepare all session materials, explicit terminal outcomes and raw-media provenance while retaining open acceptance. Verify the package-free collector on synthetic fixtures without redistributing external tools.
2026-11-13 11:36:47 -05:00
UnixNight c9b9f2eba9 feat(workflow): checkpoint GSD before five-hour quota exhaustion 2026-11-13 11:24:53 -05:00
UnixNight 73954e675d docs(handoff): preserve quota-interrupted Windows bundle task 2026-11-13 11:07:44 -05:00
UnixNight 818191c90c test(01-05): require complete Windows session materials and open results 2026-11-12 23:48:52 -05:00
UnixNight 61123394e0 feat(01-05): assemble identified offline Windows checkpoint 2026-11-12 23:48:03 -05:00
UnixNight 446930d2a3 test(01-05): specify immutable offline checkpoint round trip 2026-11-12 23:40:08 -05:00
UnixNight de68796df1 docs(01-04): record reviewed wave two runtime regressions 2026-11-12 23:36:19 -05:00
UnixNight 4bf072d03c docs(01-04): advance sequential observation plan metadata 2026-11-12 23:23:27 -05:00
UnixNight 85e533b629 docs(01-04): complete passive port observation plan 2026-11-12 23:22:36 -05:00
UnixNight ea4dc9b5df feat(01-04): preserve observer identity through control and scene changes 2026-11-12 23:20:14 -05:00
UnixNight 6bccd47b9b test(01-04): require retained session and dialogue observation 2026-11-12 23:10:30 -05:00
UnixNight 72523eebb7 feat(01-04): observe accepted input with bounded passive output 2026-11-12 23:09:01 -05:00
UnixNight 773c228a30 test(01-04): specify passive port input observation 2026-11-12 23:05:18 -05:00
UnixNight e815534895 docs(01-03): verify resumed ledger and clear pause handoff 2026-11-12 23:01:12 -05:00
UnixNight f55ba8eae7 docs(01-03): advance sequential capability ledger progress 2026-11-12 23:00:00 -05:00
UnixNight 564b19ad03 docs(01-03): complete capability ledger plan 2026-11-12 22:59:25 -05:00
UnixNight 4d07d60e2f feat(01-03): reconcile full-game capability and checkpoint coverage
Map all 33 requirements across six groups and reconcile 33 hashed source rows. Preserve startup current/history, unimplemented work and open native/reference acceptance; bind imported receipt identities and generate navigation.
2026-11-12 22:57:22 -05:00
UnixNight fafbd05811 docs(pause): preserve phase one partial ledger continuation 2026-11-12 20:02:30 -05:00
UnixNight c21ed7d7a2 test(01-03): require complete game and checkpoint source coverage 2026-11-12 19:58:32 -05:00
UnixNight e6713ead48 feat(01-03): trace corrected TSK order through capability evidence 2026-11-12 19:57:35 -05:00
UnixNight ded848f78e test(01-03): specify capability applicability and review navigation 2026-11-12 19:53:52 -05:00
UnixNight be18d77ca4 docs(01-02): record sequential viewer progress 2026-11-12 19:48:50 -05:00
UnixNight a789bfa942 docs(01-02): complete local paired review plan 2026-11-12 19:48:18 -05:00
UnixNight 91da92f17d feat(01-02): preserve clocks exclusive audio and complete review tails 2026-11-12 19:46:04 -05:00
UnixNight 75d7ca4279 test(01-02): specify truthful timing audio and failure states 2026-11-12 19:35:57 -05:00
UnixNight 49f874e64c feat(01-02): export and serve validated local media pairs 2026-11-12 19:34:06 -05:00
UnixNight 488c904807 test(01-02): specify contained paired media review 2026-11-12 19:30:43 -05:00
UnixNight 6be8484802 docs(01-01): record reviewed wave one regression evidence 2026-11-12 19:26:58 -05:00
UnixNight f9f7a7277a docs(01-01): complete preserved session and scenario plan 2026-11-12 19:13:23 -05:00
UnixNight ac958e1962 docs(01-01): record preserved session and scenario implementation 2026-11-12 19:12:37 -05:00
UnixNight 32a72654e8 feat(01-01): enforce eight-cell scenario and native evidence completeness 2026-11-12 19:10:15 -05:00
UnixNight cc4a5a3e92 test(01-01): require complete journey and lifetime scenario matrix 2026-11-12 19:04:21 -05:00
UnixNight cd7783ba3a feat(01-01): stage preserved sessions and import typed hashed receipts 2026-11-12 19:02:34 -05:00
UnixNight 597caa0b49 test(01-01): cover preserved sessions and receipt trust boundaries 2026-11-12 18:58:00 -05:00
UnixNight 96c5f2c00f docs(state): retain generated planning state projection 2026-11-12 17:38:57 -05:00
UnixNight cf64b8ce18 docs(01): create verified fidelity baseline plans 2026-11-12 17:38:34 -05:00
UnixNight 36f24e4474 docs(phase-01): add research and validation strategy 2026-11-12 12:21:56 -05:00
UnixNight 29f8cb1714 docs(state): record phase 1 context session 2026-11-12 12:11:48 -05:00
UnixNight 661e7c3299 docs(01): capture phase context 2026-11-12 12:11:35 -05:00
UnixNight 9aa49970e4 docs: initialize eight-phase reconstruction roadmap 2026-11-12 11:52:43 -05:00
UnixNight ac60452db6 docs: define full reconstruction requirements 2026-11-12 11:49:22 -05:00
UnixNight a8dc07f9fc docs: research remaining full reconstruction 2026-11-12 11:47:41 -05:00
UnixNight dd7688bce9 chore: configure reconstruction workflow 2026-11-12 11:42:01 -05:00
UnixNight 7d56538d9f docs: initialize reconstruction project 2026-11-12 11:37:30 -05:00
UnixNight f2f3a805cd docs: map existing codebase 2026-11-12 11:06:58 -05:00
UnixNight bdca29d3aa Recover actor normal callbacks and late collision reads 2026-11-07 19:36:26 -05:00
UnixNight bf876e9c3c Match original collision rounding through populated dynamic reclip 2026-11-07 08:26:17 -05:00
UnixNight 135ff3642a Recover dynamic box shared-context ownership and kernel winding 2026-11-07 00:20:22 -05:00
UnixNight 346d350176 Trace VR04 physical registration and generated helper lifetimes 2026-11-06 22:56:38 -05:00
UnixNight 3794439d4e Record pair-contract package verification 2026-11-06 19:10:04 -05:00
UnixNight 924ad2f67b Recover ordered physical pair collision lifecycle 2026-11-06 19:07:09 -05:00
UnixNight 27d91ad697 Record clean cutscene-order package verification 2026-11-06 17:16:16 -05:00
UnixNight ea04210f52 Preserve retained Jimmy update order on initial story entry 2026-11-06 17:08:59 -05:00
UnixNight 4cd62d3627 Trace Carl lifecycle and add read-only original state observer 2026-11-06 10:27:10 -05:00
UnixNight c642b69849 Plan original lifecycle recovery and verified implementation checkpoints 2026-11-05 22:31:46 -05:00
UnixNight 68154dffce Trace post-skip tilt and gate gameplay changes on original lifecycle recovery 2026-11-05 22:14:49 -05:00
UnixNight a2e89c625a Record original rotation probes and standalone handoff package validation 2026-11-05 15:47:32 -05:00
UnixNight dae13ace73 Reset cutscene facing destination with original camera rotation handoff 2026-11-05 15:44:25 -05:00
UnixNight 7818cc8d64 Record authorization to push verified milestones to Gitea 2026-11-05 15:31:18 -05:00
UnixNight 7656bb69ad Record standalone turn and jetpack visual package validation 2026-11-05 15:30:20 -05:00
UnixNight f0be8504dd Restore turning clips and attach jetpack fire to full player transform 2026-11-05 15:25:50 -05:00
UnixNight fafb54730a Record body ownership regression and package validation 2026-11-05 11:12:30 -05:00
UnixNight c9d0c5be59 Preserve contact-owned roots and independent body modes 2026-11-05 11:06:13 -05:00
UnixNight 3845ea7114 Record airborne bridge regression and package verification 2026-11-05 10:28:10 -05:00
UnixNight 27be8ed630 Integrate source airborne tilt and logical-root rendering 2026-11-05 10:19:12 -05:00
UnixNight a61f1b0284 Record Jimmy movement integration and package validation 2026-11-05 09:56:25 -05:00
UnixNight acd1b287cf Accept original canonical angle at first Bubble replay step 2026-11-05 09:52:02 -05:00
UnixNight 0e2f426d42 Match Jimmy controller arithmetic and facing to original probes 2026-11-05 09:47:28 -05:00
UnixNight 42ea2b8cd5 Record Scooter feedback fix and standalone package verification 2026-11-04 22:48:20 -05:00
UnixNight fccc0b9d1b Restore Goddard leveling and Scooter positional pitch processing 2026-11-04 18:27:56 -05:00
UnixNight 74be19eb15 Record Scooter regression and standalone package verification 2026-11-04 18:09:09 -05:00
UnixNight 62c07a3d59 Implement source-backed Scooter vehicle in tutorial and outside 2026-11-04 18:06:09 -05:00
UnixNight 8df5e81070 Record Grappler regression native replay and package validation 2026-11-04 11:33:19 -05:00
UnixNight 43806fe862 Implement verified Grappler body camera and helpers in VR08 2026-11-04 11:27:03 -05:00
UnixNight ffea678e90 Recover Grappler aim gating and implement verified ray constraint components 2026-11-03 22:22:45 -05:00
UnixNight 0c913d15aa Implement Grappler scalar component with original-code references 2026-11-03 21:25:54 -05:00
UnixNight 70cba65c1f Correct orbit camera horizontal input direction 2026-11-03 21:13:34 -05:00
UnixNight 87381049da Record orbit camera runtime and package verification 2026-11-03 17:40:45 -05:00
UnixNight d8f1b51c86 Fix orbit camera mirroring by matching gameplay handedness 2026-11-03 17:38:48 -05:00
UnixNight 1b679c641a Record Rocketship impact correction package verification 2026-11-03 16:55:54 -05:00
UnixNight 62e908e26d Fix Rocketship wall damage flash misinterpreted as model scaling 2026-11-03 16:53:56 -05:00
UnixNight b5ef5b8b64 Record Rocketship standalone package and validation results 2026-11-03 16:44:54 -05:00
UnixNight e77add5fdf Implement evidence-backed VR02 Rocketship flight and ownership 2026-11-03 16:42:09 -05:00
UnixNight 312efccb77 Add Give All Gadgets to the F1 Player menu 2026-11-03 14:30:05 -05:00
UnixNight a274670fe8 Recover Rocketship flight components against original-code probes 2026-11-03 11:09:16 -05:00
UnixNight c6eb1861cd Assess supplied jn-engine research and capture evidence 2026-11-03 10:42:14 -05:00
UnixNight c0acf58d9c Record Baseball package and standalone validation 2026-11-02 22:57:55 -05:00
UnixNight d6ca417e9e Implement Baseball aiming, pooled projectiles and VR07 targets 2026-11-02 22:54:19 -05:00
UnixNight 50fcb87d90 Record Bubble package and standalone validation 2026-11-02 17:01:21 -05:00
UnixNight 1ae5f4251c Implement Bubble controller, sprite and VR01 body behavior 2026-11-02 16:57:54 -05:00
UnixNight 9ea578492d Record Invisible package and standalone verification 2026-11-02 09:24:08 -05:00
UnixNight 1897dd2b90 Implement timed Invisible gadget and shared energy warnings 2026-11-02 09:21:56 -05:00
UnixNight 3527d33810 Record clean gadget packages and standalone validation 2026-10-27 12:20:54 -04:00
UnixNight 7b5230ceb8 Implement original gadget panel and playable shrink ray 2026-10-27 12:18:45 -04:00
UnixNight 0272f7bef7 Record tutorial body release and standalone validation 2026-10-26 22:25:17 -04:00
UnixNight 35a2a66606 Compose source body physics and enable tutorial static response 2026-10-26 22:22:42 -04:00
UnixNight df0263b26e Recover and verify static collision traversal and body contracts 2026-10-26 21:45:57 -04:00
UnixNight 7c0d1a4b0c Record sphere and ceiling continuation release checks 2026-10-26 16:11:20 -04:00
UnixNight 57dfcc64bb Recover sphere response and correct Jimmy ceiling cancellation 2026-10-26 16:09:19 -04:00
UnixNight 6a7a53c90d Require REA for future original-binary investigations 2026-10-26 12:32:52 -04:00
UnixNight 4a4b1cfc1b Record control-phase package and standalone validation 2026-10-26 12:23:07 -04:00
UnixNight c285b57091 Run body and fire phases during scripted control locks 2026-10-26 12:21:25 -04:00
UnixNight 5876da112c Record retained-state package and standalone route validation 2026-10-26 04:04:07 -04:00
UnixNight 9ad5a8ef6b Recover retained route state and complete PostLoad availability tails 2026-10-26 03:58:52 -04:00
UnixNight 1dddfefc68 Record debug tools package verification 2026-10-25 20:35:53 -04:00
UnixNight d7838980fd Expand debug system pages and add noclip exploration 2026-10-25 20:34:27 -04:00
UnixNight b915a2c2e4 Record implementation package and standalone route validation 2026-10-25 19:59:41 -04:00
UnixNight 09cf1172bf Apply recovered player phases, static camera query and level availability 2026-10-25 19:56:44 -04:00
UnixNight 117db77c7b Clarify loader defaults provenance and record checkpoint packages 2026-10-25 12:59:09 -04:00
UnixNight 531883aaac Document architecture checkpoint and restore original task callback order 2026-10-25 12:56:17 -04:00
UnixNight 69d0187a21 Keep presentation alive across levels and scale UI for widescreen 2026-10-25 03:14:04 -04:00
635 changed files with 97996 additions and 366 deletions

No files matched your search

+65
View File
@@ -0,0 +1,65 @@
{
"description": "GamePort quota guard: stop new workers at 20%; checkpoint and pause at 15%.",
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"PreModelRequest": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
]
}
}
+69
View File
@@ -0,0 +1,69 @@
{
"version": "1.0",
"timestamp": "2026-11-13T22:26:46.798618+00:00",
"phase": "01",
"phase_name": "Reproducible Fidelity Baseline",
"phase_dir": ".planning/phases/01-reproducible-fidelity-baseline",
"plan": 7,
"task": 3,
"total_tasks": 3,
"status": "consumed",
"completed_tasks": [
{
"id": 1,
"name": "Readiness/audit tooling plus review closure",
"status": "done",
"commit": "026def9",
"fix_head": "02d182f"
},
{
"id": 2,
"name": "Actual combined session status projection",
"status": "partial",
"commit": "fc5e936",
"actual_acceptance": "0/120 OPEN"
},
{
"id": 3,
"name": "Suite integration and review",
"status": "done",
"commit": "472500b",
"review_docs": "71366e7"
}
],
"remaining_tasks": [
{
"id": 2,
"name": "Actual original/native combined session and strict acceptance",
"status": "human_pending"
}
],
"blockers": [
{
"type": "human_action",
"description": "Combined original/native session and ten named UAT checks remain pending; 0/120 accepted."
}
],
"background_processes": {
"tests": "finished",
"verifier": "finished human_needed",
"quota_watcher": "running; no automatic resume"
},
"async_jobs": [],
"human_actions_pending": [
{
"action": "AfterfinalreadinessverificationperformonecombinedWindowsDxWnd/nativeWindows/physicalLinuxreviewsession",
"blocking": true
}
],
"uncommitted_files": [
" M .planning/HANDOFF.json",
" M .planning/ROADMAP.md",
" M .planning/STATE.md",
" M .planning/phases/01-reproducible-fidelity-baseline/.continue-here.md",
" M .planning/phases/01-reproducible-fidelity-baseline/HANDOFF.md",
"?? tools.yaml"
],
"next_action": "Use $gsd-verify-work 1 and docs/evidence/checkpoint-session.md for one combined actual human session; do not repeat completed implementation/tests/review or advance Phase2 automatically.",
"context_notes": "Quota guard explicitly requested pause at15%. Resume completed task01-07-03 and recovered fullsuite exit0 (782.049626s), then reviewed/fixed allfive source-integrity findings. Do NOT redo implementation or tests. Source commits through02d182f, review/coverage/security documentation71366e7. Fullsuite556Python/180fidelity,27Node,23observer,2HUD,51managedentrypoints,36GPUrenderedreceipts,zeroVulkanvalidationerrors,SDLdummychecks,539originalhashes. Latertooling-onlyfixes: all191fidelityregressions PASS43.355s; focused26scenario,23capture,29acceptance,27Node,18LinuxhostedPowerShell. All539originals unchanged. No runtime changes afterfullsuite; no need13minGPUrerun forcurrentPython/collector fixes.\nHistoricalreview5915128: CR01selected-vs-reviewedpath,CR02originalinventory/executablebinding,CR03copy-stateidentity,WR01viewerledgerprojection,WR02interruptedWindowsfinalization. Fixes5569bc2,bda35e5,6e5ee0b,548c97a,2608517,a821754. Independentre-reviewcaughtremaininghash-onlycopy-statebypass; RED48fca0d/GREEN02d182f requiresactual_checked_artifactwithrootinside_scenario_observation; callersupdated. Finalindependentre-reviewallfiveFIXED in01-REVIEW-VERIFY.md; dispositionopen0. Securityauditorfinal22/22mitigated, threats_open0 in01-SECURITY.md. Nyquistautomationcoveragevalidatedall15taskbindings; manualacceptanceopen;191fidelityaggregate43.355sec exceeds30secquicktargethonestly. UIreviewdisabledconfigfalse. No remainingknowncode/securityblockers.\nCurrentfreshfinalbundle dist/fidelity/phase01 has11001immutableentries. Currenthashes/readinessreceipt artifacts/fidelity/verification/01-07-final-checkpoint.json. readyexit0true,strictauditexit1 errors[] accepted0/120,10humanpending; logs artifacts/fidelity/01-review-fixes/readiness-final.json,acceptance-final.json,python-fidelity-final.log. Oldbundlespreserved phase01-pre-review-48100025 andphase01-pre-copy-artifact-7ceebcb3. ActualLinuxfailedpreflightimportedcurrentbundle/results/imported. Runtimepackage source446930d dirty/diff90cef956 unchanged; source/docscommitsmustnotrelabelitsidentity. Original/nativeWindows+DxWnd andphysicalLinuxvisible/audible/browserreviewremainonecombinedhuman session pending. Humanonlycollects/observes/returns; agent-ownedexactnormalizationmapping incheckpoint-session.md. No capture request issued yet because finalphaseverification/handoffpending.\nFinal typed verifier phase01_final_verification was dispatched at21%; quota15% interrupted it, instructedfinishonlyboundedhuman_neededreport/fingerprint thenreturn. It had readall7musthaves/summaries, checked25capabilities/33requirements/0unmapped/6groups/33rows,16/16decisioncoverage,40sourcefilesnoskip/debtscan. A mandatoryMVPgoalformatguard exposed existingROADMAPMode:mvp plainproseGoal. Rootauthorizedformat-only identicalintentuserstory and modifiedROADMAP.md uncommitted: As a tester, I want to reproduce identified original/port comparison scenarios, so that I understand exactly what the current reconstruction proves on each native platform. Validatorvalidtrue; no scope/successcriteriamodified. OneverifiercommandusedwrongunittestclassFidelityAcceptance (loadererror,correctclassAcceptanceTests); twoothernamedbehaviorcheckspassed; don'tmislabelthatcommandassuccess. Priorfulltargeted29passestablishactualcoverage.\nNEXT: Reconcile currentverifier's 01-VERIFICATION.md and CLI verification.status; ifreport/fingerprintabsentfinishthat ONLY beforeanynewphase. FingerprintmustbeownerCLIgenerated, notmanual. Oncehuman_neededstatusvalid, persistUATfromnamedhumanitems, updateSTATE/consumedhandoffs, commitverifiedreport+goalmetadata+handoffdocs andpush verifiedsource/tooling toauthorizedGitea/main. Lastpushedhead remainsd18f551; later01-07/task3/reviewfix/auditcommits arelocalawaitingfinalverification. Preserveunrelatedtools.yaml. Do notadvancephase2orclaimPhase1accepted; allEVIDIDsPending0/120humanacceptance. No source changesuncommittedexceptROADMAPformatandpossiblynewverifierreport.\nNativeagents/sourcewritesallfinishedexceptverifierreportbeingclosed. Quota watcher runs and actual15%steeringworks. Noauto-resume; usermust $gsd-resume-workafterreset. Don'tspendquota rereadingmassiveGSDscriptbodies orrerunningfinished13minfullsuite. Existinglocalpackages/media/originalcopiesstaylocal, noCI/uploads. MaintracksGitea/main, scoped.gitwriteescalation; retainhistoricalhandoffsmarkconsumedratherthandelete (priorautomaticreviewrejecteddeletion).\nRootinterruptedverifieratfinalpause tostopallmodelwork. Reconcileactualreportfileifpresent; ifabsentfinishboundedreport/fingerprintafterreset.\n\n2026-11-14 final typed verifier completed: human_needed,29/42verified13uncertain,all10namedhumanitems saved01-UAT.md. Ownerstatusacceptedreport; verificationfingerprintrefreshedafterfinalstatusnotes. Goalformatfebb4a9committed. Remainingworkisactualcombinedhumanverification, notcoding/fulltests.\n"
}
+81
View File
@@ -0,0 +1,81 @@
# Neutron GamePort
## What This Is
A faithful reconstruction of the original Windows 98 Neutron game for native Linux x64 and Windows 10/11 x64, using shared C#/.NET 10 code, Vulkan 1.3+ through Silk.NET.Vulkan, and SDL3. It preserves the original game's identity and reuses recovered original assets. The current project already implements substantial playable content; this planning effort covers the remaining full reconstruction.
## Core Value
Match the original game's behavior and presentation as accurately as possible, using original evidence and explicit verification to govern every reconstruction decision.
## Requirements
### Validated
These are existing capabilities with bounded evidence, not claims that the whole game or all platforms are verified. See `docs/progress.md`, `docs/compatibility.md`, and the linked investigation reports for exact revisions and limits.
- ✓ Shared .NET 10 runtime with Vulkan rendering and SDL3 window/input/audio — existing code and recorded native Linux checks.
- ✓ Original inventory and hash verification, bounded asset parsers, offline preparation and original-format GAM/TSK reading — existing tools and regressions; 539 originals comprise the recorded baseline.
- ✓ Playable lab/tutorial/outside content, script and cutscene execution, original-derived geometry, actors, HUD, music and speech — existing bounded routes and runtime checks; full original fidelity remains open.
- ✓ Recovered movement/body/collision components with isolated original-code comparisons — existing component evidence; physical registration, derived callbacks and broad live admission remain incomplete.
- ✓ Bounded implementations of several gadgets and vehicles — existing per-scene reports; broader actor interactions, levels and retained lifetimes remain open.
- ✓ Local Linux and Windows self-contained publishing and package provenance — existing scripts and recorded checks; Windows cross-publishing and Wine evidence do not establish complete native Windows compatibility.
### Active
- [ ] Close remaining Jimmy movement, body/contact, animation, camera and retained scene-state gaps while preserving verified baseline behavior.
- [ ] Recover physical registration, activation, helper cleanup, real actor responses and shared collision context before expanding live source solver admission.
- [ ] Complete original gameplay systems, gadgets, enemies/AI, damage, interactions and level-specific mechanics from authoritative evidence.
- [ ] Complete all original levels and progression, menus, configuration, save/load and fresh/retained/RETURN lifetimes.
- [ ] Match original rendering, materials, lighting, fog, transparency, animation, camera framing and UI behavior as closely as evidence permits.
- [ ] Complete original audio playback, banks, positional effects, timing, attenuation and lifecycle behavior.
- [ ] Establish repeatable original-versus-port comparisons, document discrepancies and resolve them in dependency order.
- [ ] Verify integrated gameplay and local release packages on native Linux and native Windows, retaining explicit evidence and remaining limitations.
### Out of Scope
- Creative reinterpretation, replacement movement tuning or visual modernization that changes the original identity — fidelity takes precedence.
- New gadgets or broader gameplay expansion before the current movement/route checkpoint closes — preserve the current stabilization priority.
- Runtime online services, telemetry, cloud CI, and uploads of original assets or generated packages — local operation and evidence preservation are mandatory.
- Replacing authoritative evidence with third-party reconstruction behavior — external decompiler indexes provide investigation leads only.
## Context
The authoritative specification is `../prompt.MD`; `../AGENTS.md` and `AGENTS.md` provide project rules and current priorities. Original binaries and assets live in `../Original/` and must never be modified or executed in place. Use generated copies and separate analysis/extraction/build output.
The complete codebase map is in `.planning/codebase/`. Existing architecture composes a persistent presentation session with scene-local simulation, scripts, resources and audio. Recovered algorithms and isolated original-component probes coexist with bounded live adapters and explicitly modern compatibility paths. Lab/outside capsule collision must remain until the source replacement gate is satisfied.
`docs/checkpoint/next-work-plan.md`, `docs/checkpoint/coverage.md`, `docs/checkpoint/implementation-plan.md`, and `docs/gameplay/jimmy-movement-stabilization.md` preserve the current recovery sequence. The successful TSK-backed first-story retained-input ordering correction is already documented; it must not be planned as an untouched defect or replaced by an invented orientation reset. Remaining derived actor responses, helper lifetime, collision admission, animation and camera handoffs need their own evidence gates.
The user explicitly selected the remaining full reconstruction as the planning scope and emphasized that it must be as accurate as possible to the original. A complete playable scene is an intermediate checkpoint, not the final scope. Existing runtime and component tests do not prove complete original-game fidelity. Whole-original runtime reference capture and broader native Windows comparisons remain open according to current reports.
## Constraints
- **Technology:** C#/.NET 10, Silk.NET.Vulkan, Vulkan 1.3+, SDL3; one shared native Linux/Windows x64 implementation.
- **Fidelity:** Preserve original algorithms, control semantics, floating-point/store behavior where significant, timing, progression and asset identity. Record approximations and unresolved questions explicitly.
- **Evidence:** Use REA for original-binary investigations; preserve complete Evidence, addresses, file offsets, provider gaps and relevant byte cross-checks. Distinguish static recovery, inference, implementation, compilation, component execution and whole-game runtime verification.
- **Validation:** Compilation alone cannot establish completion. Require meaningful regressions and integrated runtime comparisons at the appropriate scope; native Windows verification remains distinct from cross-publish and Wine.
- **Preservation:** Verify original hashes against `docs/original-manifest.json`; keep generated data outside originals and source commits.
- **Workflow:** Local builds/tests/packages only. Commit and push completed, verified source/tools/docs to existing `Gitea/main`; do not add cloud CI or upload originals/generated packages.
- **Coordination:** At most three investigators alongside primary, exclusive file ownership, primary integration and verification. Preserve unrelated working-tree changes.
## Key Decisions
| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Plan the remaining full reconstruction | User selected full scope rather than a movement-only milestone | Confirmed |
| Make original fidelity the governing priority | User explicitly requires accuracy as high as possible | Confirmed |
| Stabilize movement and interacting lifetimes before expansion | Current project instructions and recovery dependencies | Existing policy |
| Reuse evidence and validated implementation with bounded claims | Avoid repeating solved investigations or overstating coverage | Existing policy |
| Require original comparison and native platform evidence for final completion | Component tests and cross-builds have narrower guarantees | Pending full verification |
## Evolution
This document evolves at phase transitions and milestone boundaries.
After each phase transition, move verified requirements to Validated with evidence references, record invalidated scope and new requirements, update decisions, and check that the project description remains accurate.
After each milestone, review every section, confirm the fidelity priority, revisit deferrals and update context with actual implementation and verification status. Keep full-game completion separate from intermediate scene and component checkpoints.
---
*Last updated: 2026-11-12 after initialization and user scope approval*
+127
View File
@@ -0,0 +1,127 @@
# Requirements: Neutron GamePort
**Defined:** 2026-11-12
**Core Value:** Match original behavior and presentation as accurately as possible, governed by authoritative evidence and explicit verification.
## v1 Requirements — Remaining Full Reconstruction
The release scope is the full original game. Existing bounded implementations are foundations; unchecked items represent their remaining full-scope acceptance, not absence of all implementation. Original means behavior established from authoritative binaries/assets and observed execution, including significant quirks. Approximation and unavailable comparison evidence must stay explicit; neither is silently counted as verified parity.
### Reference and Fidelity Baseline
- [ ] **EVID-01**: Every original file remains byte-identical to the recorded inventory throughout recovery, testing and release preparation; generated copies and outputs remain separate.
- [ ] **EVID-02**: Reviewers can reproduce identified original-game reference scenarios from an isolated generated installation, with input/event, visual and audio captures where applicable; unresolved execution limitations are recorded and leave comparison acceptance open.
- [ ] **EVID-03**: Reviewers can identify each capability's source evidence, implementation revision, runtime platform, current discrepancy and acceptance condition in a maintained full-game coverage ledger.
- [ ] **EVID-04**: Testers can repeat the baseline movement/route scenarios on native Linux and native Windows with revision-specific receipts; cross-publish, Wine, component execution and native gameplay remain separately labeled.
### Movement, Contacts and Scene Ownership
- [ ] **MOVE-01**: Jimmy's intended original keyboard/mouse/controller inputs, where supported by the original, produce source-faithful movement, facing, jumps, gravity and effect behavior across required movement modes and frame rates.
- [ ] **MOVE-02**: Jimmy and participating bodies resolve static/dynamic support, walls, ceilings and special contacts using evidenced real actor responses, live callback reads, ordered physical membership and helper lifetimes before broader scene admission.
- [ ] **MOVE-03**: Players retain the original action/animation acceptance, playback, interruption and completion behavior through movement, landing, conversation and control changes.
- [ ] **MOVE-04**: Players experience original camera/input/control handoffs through scripts, pause, fresh entry, LOAD and RETURN, preserving correct object/state ownership without invented orientation resets.
- [ ] **MOVE-05**: Players can complete lab → VR04 → lab → outside under fresh and retained entry with natural/skipped dialogue, banked jumping, landing, held input and gadget cleanup, preserving implemented startup-order corrections and legitimate landing bank.
### Actors, Hazards and Combat
- [ ] **ACT-01**: Original NPC/enemy classes exhibit their evidenced sensing, action transitions, movement, animation and RNG-dependent behavior in their intended scenes.
- [ ] **ACT-02**: Players and actors receive original health, damage, immunity, hazard, death and recovery behavior through real gameplay consumers.
- [ ] **ACT-03**: Enter/stay/leave and special actor interactions perform original task, score, control and class-specific side effects in the evidenced order.
### Gadgets, Vehicles and Inventory
- [ ] **GAD-01**: Players acquire and select all original gadgets/items through original gameplay paths with faithful inventory, energy and availability rules.
- [ ] **GAD-02**: Players can use every original gadget against its intended actors/objects with source-faithful aiming, firing, state, projectile and effect behavior; existing bounded gadget implementations retain their verified behavior.
- [ ] **GAD-03**: Players can summon, mount, drive/fly and dismount original vehicles through intended modes, inputs, camera, passenger, collision and cleanup behavior.
- [ ] **GAD-04**: Gadget/vehicle/companion state follows original interruption, death, script, LOAD/RETURN and save/resume lifetimes across intended scenes.
### Campaign and Authored Content
- [ ] **CAMP-01**: Players can enter and traverse every evidenced reachable original campaign and optional/practice level with its intended original assets and entry/exit rules.
- [ ] **CAMP-02**: Original missions, authored scripts/cutscenes, tasks, objectives, collectibles and level-specific mechanisms advance through ordinary gameplay in their intended order.
- [ ] **CAMP-03**: Players can complete every original campaign route and evidenced optional branch through original completion/win/loss outcomes without debug grants or warps.
- [ ] **CAMP-04**: The content ledger accounts for every supplied level/resource and distinguishes reachable content, unreachable/unused content and unresolved missing dependencies using evidence; absent assets are never silently substituted.
### Frontend, Configuration and Persistence
- [ ] **UI-01**: Players can use original startup, new-game, menu, pause, objective/HUD, prompt and ending flows through source-supported input and timing; modern diagnostics remain distinguishable.
- [ ] **UI-02**: Players can change and persist original-supported configuration, including relevant input/display/audio settings, with source-faithful defaults and bounds.
- [ ] **SAVE-01**: Players can save, load and resume through original player-facing workflows with faithful checkpoint, task, inventory, health/energy and progression state, preserving required original-format fields.
- [ ] **SAVE-02**: Fresh start, repeated load, scene return and resume reproduce correct retained/reset actor, helper, companion, gadget, script and camera state, verified by equivalent continued gameplay.
### Visual, Animation and Audio Fidelity
- [ ] **VIS-01**: Players see original geometry, textures, model hierarchy/pivots, morphs, sprites, animation and UI layout at faithful authored positions and playback timing.
- [ ] **VIS-02**: Original lighting, materials, fog, texture stages/sampling, blending, alpha/depth/culling and render-layer behavior are reproduced by Vulkan equivalents and compared against identified original references.
- [ ] **VIS-03**: Original gameplay/script cameras, projection, clipping, aspect behavior and transitions reproduce authored presentation without distorting the scene.
- [ ] **AUD-01**: Players hear original music, speech and contextual sound banks/events with faithful selection, timing, channel priority, looping and interruption through gameplay and transitions.
- [ ] **AUD-02**: Players hear faithful volume, panning, attenuation, positional/frequency behavior and listener ownership, validated through physical audible output as well as event/stream checks.
### Full-Game Acceptance and Local Delivery
- [ ] **REL-01**: Players can run clean, self-contained Linux x64 and Windows x64 packages offline with required SDL3/resources/shaders, without development tools, original installation paths or runtime online services.
- [ ] **REL-02**: Current packages pass integrated full campaign/optional-content, input, audio, window/focus/resize/fullscreen and resource-lifecycle checks on native Linux and native Windows, with exact source/package identities and recorded Vulkan diagnostics.
- [ ] **REL-03**: The final discrepancy audit compares the reconstructed game against original reference scenarios across gameplay, timing, visuals, audio and progression; unresolved differences and verification gaps remain explicit and prevent unsupported full-fidelity completion claims.
- [ ] **REL-04**: Maintainers can reproduce local builds/tests/packages and review current evidence, compatibility and known limitations; verified source/tools/docs are pushed to existing Gitea while originals, generated traces and packages stay local.
## Deferred Requirements
No original-required feature category is deferred outside the full reconstruction release. Phase-level deferral only establishes dependency order; unknown original behavior is investigated rather than invented. New-gadget expansion remains behind the current movement/route stabilization gate.
## Out of Scope
| Feature | Reason |
|---------|--------|
| Creative mechanics, replacement movement tuning or visual modernization | Original fidelity governs the reconstruction. |
| Online runtime services, telemetry, cloud CI | Shared native offline implementation and local builds/tests are mandatory. |
| Uploading originals, generated traces or release packages | Source-control authorization covers verified source/tools/docs only. |
| Treating third-party remakes as behavior authority | Only original evidence establishes faithful behavior. |
## Definition of Done
Each requirement requires evidence recovery, integrated implementation, appropriate regressions and runtime verification, and a verified source revision. Preserve source addresses/offsets and complete REA evidence for binary investigations. Native Windows execution is not replaced by Wine or cross-publishing. Component parity is not whole-original execution. Capture comparison tolerances per system with an evidence-backed reason; never assume blanket pixel/bit identity. All original-required content must be accounted for before full-game completion, and unresolved reference/platform access is an open acceptance dependency.
## Traceability
Every v1 requirement maps to exactly one accountable phase. Preservation, evidence capture and fidelity checks continue throughout later phases without duplicating requirement ownership. All statuses begin Pending; existing bounded implementations do not establish full-scope acceptance.
| Requirement | Phase | Status |
|-------------|-------|--------|
| EVID-01 | Phase 1 | Pending |
| EVID-02 | Phase 1 | Pending |
| EVID-03 | Phase 1 | Pending |
| EVID-04 | Phase 1 | Pending |
| MOVE-01 | Phase 2 | Pending |
| MOVE-02 | Phase 2 | Pending |
| MOVE-03 | Phase 2 | Pending |
| MOVE-04 | Phase 2 | Pending |
| MOVE-05 | Phase 2 | Pending |
| ACT-01 | Phase 3 | Pending |
| ACT-02 | Phase 3 | Pending |
| ACT-03 | Phase 3 | Pending |
| GAD-01 | Phase 4 | Pending |
| GAD-02 | Phase 4 | Pending |
| GAD-03 | Phase 4 | Pending |
| GAD-04 | Phase 4 | Pending |
| CAMP-01 | Phase 5 | Pending |
| CAMP-02 | Phase 5 | Pending |
| CAMP-03 | Phase 5 | Pending |
| CAMP-04 | Phase 5 | Pending |
| UI-01 | Phase 6 | Pending |
| UI-02 | Phase 6 | Pending |
| SAVE-01 | Phase 6 | Pending |
| SAVE-02 | Phase 6 | Pending |
| VIS-01 | Phase 7 | Pending |
| VIS-02 | Phase 7 | Pending |
| VIS-03 | Phase 7 | Pending |
| AUD-01 | Phase 7 | Pending |
| AUD-02 | Phase 7 | Pending |
| REL-01 | Phase 8 | Pending |
| REL-02 | Phase 8 | Pending |
| REL-03 | Phase 8 | Pending |
| REL-04 | Phase 8 | Pending |
**Coverage:** 33 v1 requirements; 33 mapped; 0 unmapped; 0 duplicate phase assignments.
---
*Last updated: 2026-11-12 after full-scope research, playable-slice selection and roadmap traceability*
+174
View File
@@ -0,0 +1,174 @@
# Roadmap: Neutron GamePort
## Overview
Complete the remaining original game as faithfully as possible, building on the existing runtime and bounded implementations. Eight delivery boundaries separate reference access, movement ownership, real actor consumers, gadget use, complete progression, player-facing persistence, presentation closure and native acceptance. Each phase uses playable slices: recover the source contract, integrate it into its intended scenario, and verify the resulting behavior. No original-required content is deferred outside this reconstruction.
## Delivery and Evidence Rules
- Preserve the original inventory throughout every phase; use separate generated copies for execution and analysis. Phase 1 owns the preservation baseline; all later phases keep checking it.
- Every acceptance receipt identifies source/package/resource revision and platform. Static recovery, inference, compilation, copied-original component execution, port runtime, Wine and whole-original/native Windows comparisons are distinct.
- Reference access and native Windows verification start in Phase 1 and continue throughout. If access is unavailable, keep EVID-02/EVID-04 and affected comparison criteria open. Phase 2 and other independently source-backed recovery may proceed on the available ledger/baseline; this exception does not mark Phase 1 complete or waive final acceptance.
- Movement stabilization precedes gameplay expansion. Before broader source collision admission, establish actual derived responses, ordered physical membership, helper activation/cleanup and shared mutable reclip. Preserve the lab/outside capsule until its replacement gate closes.
- The TSK-backed first-story startup-order correction is implemented. Preserve it and legitimate landing bank; do not invent orientation resets or substitute third-party movement tuning.
- Rendering, audio, menus and persistence needed by an earlier playable slice are integrated there. Their later owning phase closes full-game coverage rather than authorizing temporary invented behavior.
- Derive comparison tolerances from original evidence per system. Missing comparison evidence stays an acceptance dependency, not a parity claim. REA Evidence and authoritative bytes govern future binary investigations.
## Phases
Integer phases are planned work; decimal phases may be inserted for urgent recovered dependencies. Independent investigations may run in parallel with exclusive ownership, while integration follows the dependencies below.
- [ ] **Phase 1: Reproducible Fidelity Baseline** - Compare identified original and port routes with preserved assets and current native-platform receipts.
- [ ] **Phase 2: Faithful Movement and Scene Handoffs** - Stabilize Jimmy, real contacts, animation and retained ownership in the integrated lab/tutorial/outside route.
- [ ] **Phase 3: Original Actors, Hazards and Combat** - Make intended NPC/enemy encounters and their consequences playable.
- [ ] **Phase 4: Complete Gadget and Vehicle Use** - Acquire and use all original gadgets/vehicles against real consumers across intended lifetimes.
- [ ] **Phase 5: Complete Campaign and Optional Routes** - Traverse all original-required content and reach original outcomes through normal progression.
- [ ] **Phase 6: Original Frontend and Save/Resume** - Use original menus/options and resume equivalent gameplay through player-facing persistence.
- [ ] **Phase 7: Original Visual and Audible Presentation** - Close rendering, playback, camera and sound differences across complete gameplay.
- [ ] **Phase 8: Full-Game Native Acceptance and Delivery** - Verify standalone Linux/Windows packages against original journeys and publish verified source documentation.
## Phase Details
### Phase 1: Reproducible Fidelity Baseline
**Goal:** As a tester, I want to reproduce identified original/port comparison scenarios, so that I understand exactly what the current reconstruction proves on each native platform.
**Mode:** mvp
**Depends on:** Nothing (existing codebase and evidence are the starting point).
**Requirements:** EVID-01, EVID-02, EVID-03, EVID-04
**Success Criteria** (what must be TRUE):
1. A reviewer can verify every original against the recorded inventory and run investigation/reference copies without altering the original installation.
2. A tester can reproduce identified whole-original reference scenarios from an isolated generated installation and inspect corresponding input/events, images and audio where applicable; unavailable execution keeps this criterion open.
3. A reviewer can trace every full-game capability from original evidence through current implementation, platform receipts, discrepancies and its remaining acceptance condition.
4. Testers can repeat the same baseline movement/route scenarios on native Linux and native Windows with exact revision identities; Wine/cross-publish receipts remain separately labeled and cannot close missing native execution.
**Plans:** 7/7 autonomous preparation/reconciliation plans recorded; actual 01-07-02 capture/review and Phase 1 acceptance remain pending.
**Wave 1**
- [x] 01-01-PLAN.md
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 01-02-PLAN.md
- [x] 01-03-PLAN.md
- [x] 01-04-PLAN.md
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 01-05-PLAN.md
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 01-06-PLAN.md
**Wave 5** *(blocked on Wave 4 completion)*
- [x] 01-07-PLAN.md
Autonomous preparation is complete: 11,000 immutable files pass readiness and
the complete local suite passes in 782.05s. Actual task 01-07-02 capture/review
remains human_needed: 0/120 original/native obligations accepted and ten human
findings pending. All EVID requirements remain Pending; Phase 1 is not accepted.
The primary reviews readiness before one combined session. Retained quota
handoff files are historical until primary consumption; the final SUMMARY
records completed task 3 and pending human dependencies. No Phase 2 advancement.
### Phase 2: Faithful Movement and Scene Handoffs
**Goal:** Players move, contact the world and return from scripts/scenes with the original movement, animation, camera and state ownership intact.
**Mode:** mvp
**Depends on:** Phase 1 baseline/ledger and available reference evidence; independently source-backed work may proceed under the access exception above.
**Requirements:** MOVE-01, MOVE-02, MOVE-03, MOVE-04, MOVE-05
**Success Criteria** (what must be TRUE):
1. Players reproduce evidenced Jimmy movement/facing/jump/effect modes using original-supported input devices across tested frame rates without changing significant source arithmetic or timing.
2. Players and participating bodies experience evidenced static/dynamic support, walls, ceilings and special contacts through real responses; full state/event comparisons establish helper membership, live callback reads and shared reclip before any wider solver admission.
3. Movement, landing, talk and control changes accept, interrupt and complete actions/animations with the original clocks and outcomes.
4. Camera/input/control ownership and retained/reset state remain faithful across fresh entry, scripts, pause, LOAD and RETURN, including the implemented TSK startup order and original landing bank.
5. Players complete lab → VR04 → lab → outside with natural/skipped conversations, banked jumps, held input, landing/idle and gadget cleanup; integrated port/native receipts and available original comparisons identify remaining differences explicitly.
**Plans:** TBD
### Phase 3: Original Actors, Hazards and Combat
**Goal:** Players encounter original NPC/enemy behavior and receive the correct gameplay consequences through real scene interactions.
**Mode:** mvp
**Depends on:** Phase 2; actor-specific membership/response contracts must precede each live admission.
**Requirements:** ACT-01, ACT-02, ACT-03
**Success Criteria** (what must be TRUE):
1. Players encounter each original-required NPC/enemy class in its intended scenes with evidenced sensing, movement, action/RNG decisions and animation rather than generic placeholder policies.
2. Combat and hazards produce original health, damage, immunity, death and recovery outcomes for players and affected actors during normal play.
3. Real enter/stay/leave and special interactions produce the correct ordered task, score, control and class-specific effects, including callback mutations and repeated contacts.
**Plans:** TBD
### Phase 4: Complete Gadget and Vehicle Use
**Goal:** Players acquire and use every original gadget and vehicle through intended gameplay paths, consumers and scene lifetimes.
**Mode:** mvp
**Depends on:** Phases 2 and 3; required normal acquisition routes are integrated with each gadget slice before Phase 5 closes complete campaign coverage.
**Requirements:** GAD-01, GAD-02, GAD-03, GAD-04
**Success Criteria** (what must be TRUE):
1. Players acquire/select every original gadget/item through its evidenced normal gameplay path, with original availability, inventory and energy behavior; debug grants alone do not satisfy acquisition.
2. Every gadget can be aimed/activated/fired against its intended actor/object consumers with the evidenced states, projectiles and effects, while already verified bounded features keep working.
3. Players summon, mount, operate and dismount original vehicles in supported modes with faithful input, collision, passenger and camera behavior.
4. Interruptions, death, scripts, LOAD/RETURN and supported save/resume preserve or clear gadget, vehicle and companion state exactly at evidenced lifetime boundaries.
**Plans:** TBD
### Phase 5: Complete Campaign and Optional Routes
**Goal:** Players traverse all original-required campaign and optional content and reach original outcomes through ordinary progression.
**Mode:** mvp
**Depends on:** Phases 2–4; integrate any prerequisite frontend/persistence behavior within each route slice.
**Requirements:** CAMP-01, CAMP-02, CAMP-03, CAMP-04
**Success Criteria** (what must be TRUE):
1. Players enter/traverse every evidenced reachable campaign, optional and practice level using its original assets and correct entrance/exit rules.
2. Authored scripts/cutscenes, missions, tasks, objectives, collectibles and level mechanisms advance in the original order through normal play.
3. Players complete every original campaign route and evidenced optional branch through its original completion/win/loss outcome without debug grants, warps or substituted progression.
4. Reviewers can account for every supplied level/resource as reachable, evidenced unused/unreachable, or an unresolved dependency; missing archives are investigated for actual reachability rather than silently substituted or assumed fatal.
**Plans:** TBD
**UI hint:** yes
### Phase 6: Original Frontend and Save/Resume
**Goal:** Players use the original frontend/options and save/resume completed gameplay with equivalent progression and retained state.
**Mode:** mvp
**Depends on:** Phases 2–5; save/configuration callers needed by earlier slices are recovered and integrated earlier.
**Requirements:** UI-01, UI-02, SAVE-01, SAVE-02
**Success Criteria** (what must be TRUE):
1. Players use original startup, new-game, menu, pause, objective/HUD, prompt and ending flows with evidenced input/timing; modern diagnostics are distinguishable from original UI.
2. Players change and persist original-supported input/display/audio configuration with faithful defaults and bounds.
3. Players save/load/resume through original player-facing workflows with correct checkpoints, tasks, inventory, health/energy and progression, preserving required original-format fields.
4. Fresh start, repeated load, scene return and resumed play preserve the appropriate actor/helper/companion/gadget/script/camera state and produce equivalent continued gameplay, not merely matching serialized bytes.
**Plans:** TBD
**UI hint:** yes
### Phase 7: Original Visual and Audible Presentation
**Goal:** Players see and hear the original authored presentation across complete gameplay, with remaining visual/audio differences resolved through identified comparisons.
**Mode:** mvp
**Depends on:** Phases 2–6 and original reference access from Phase 1; blocking presentation contracts are integrated with earlier slices.
**Requirements:** VIS-01, VIS-02, VIS-03, AUD-01, AUD-02
**Success Criteria** (what must be TRUE):
1. Original geometry, textures, hierarchy/pivots, morphs, sprites, animation and UI appear at faithful authored positions and playback timing in matched gameplay/reference captures.
2. Lighting, materials, fog, texture stages/sampling, blend/alpha/depth/culling and render layers match the evidenced original behavior through Vulkan equivalents, using justified system-specific comparison tolerances.
3. Gameplay/script camera framing, projection, clipping, aspect handling and transitions preserve the authored scene without distortion.
4. Players hear the original music/speech/contextual banks and events with correct timing, priorities, loops and interruption through gameplay and scene changes.
5. Physical audible checks and matched event/listener observations confirm volume, panning, attenuation, positional/frequency behavior and camera/listener ownership; dummy streams alone do not establish fidelity.
**Plans:** TBD
**UI hint:** yes
### Phase 8: Full-Game Native Acceptance and Delivery
**Goal:** Players can run reproducible offline packages on native Linux and Windows and complete the original game with current full-game fidelity evidence.
**Mode:** mvp
**Depends on:** Phases 1–7; all original/native comparison acceptance dependencies must close for full completion.
**Requirements:** REL-01, REL-02, REL-03, REL-04
**Success Criteria** (what must be TRUE):
1. Clean self-contained Linux x64 and Windows x64 packages run offline without SDK/development paths or the original installation, carrying the required SDL3, resources and shaders.
2. Current packages complete integrated campaign/optional-content scenarios and physical input/audio/window/focus/resize/fullscreen/lifecycle checks on both native platforms with exact source/package identities and Vulkan diagnostics.
3. A final original-versus-port discrepancy audit covers gameplay, timing, visuals, audio and progression; unresolved original-required differences or unavailable comparisons remain visible and prevent unsupported full-fidelity completion claims.
4. Maintainers reproduce local builds/tests/packages and find current compatibility/evidence/limitations; verified source/tools/docs are pushed to existing Gitea while originals, generated traces and packages remain local, and original hashes still match.
**Plans:** TBD
## Progress
Execution follows 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8, subject to the explicit reference-access exception and earlier prerequisite integration. Full completion cannot bypass an open phase or acceptance dependency.
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Reproducible Fidelity Baseline | 7/7 preparation | Human acceptance pending (0/120) | - |
| 2. Faithful Movement and Scene Handoffs | 0/TBD | Not started | - |
| 3. Original Actors, Hazards and Combat | 0/TBD | Not started | - |
| 4. Complete Gadget and Vehicle Use | 0/TBD | Not started | - |
| 5. Complete Campaign and Optional Routes | 0/TBD | Not started | - |
| 6. Original Frontend and Save/Resume | 0/TBD | Not started | - |
| 7. Original Visual and Audible Presentation | 0/TBD | Not started | - |
| 8. Full-Game Native Acceptance and Delivery | 0/TBD | Not started | - |
**Coverage:** 33/33 v1 requirements assigned once; all phases have 3–5 observable success criteria. Existing bounded implementation is not counted as phase completion.
---
*Initialized: 2026-11-12 — remaining full reconstruction, playable slices*
+113
View File
@@ -0,0 +1,113 @@
---
gsd_state_version: "1.0"
current_phase: 01
current_phase_name: Reproducible Fidelity Baseline
status: awaiting_human_verification
stopped_at: Phase1 verified human_needed; ten UAT checks and combined actual session pending
last_updated: "2026-11-14T05:39:47.960Z"
last_activity: 2026-11-13
last_activity_desc: 01-07 autonomous preparation verified; actual human acceptance pending 0/120
state_head: febb4a9d98071b19998bcecfab4a236d9c0adfce
progress:
total_phases: 8
completed_phases: 0
total_plans: 7
completed_plans: 7
percent: 0
---
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 2026-11-12)
**Core value:** Match original behavior and presentation as accurately as possible, governed by authoritative evidence and explicit verification.
**Current focus:** Phase 01 — Reproducible Fidelity Baseline
## Current Position
Phase: 01 (Reproducible Fidelity Baseline) — HUMAN ACCEPTANCE PENDING
Plan: 7 of 7
Status: Preparation complete; actual original/native acceptance human_needed
Last activity: 2026-11-13 — Task 3 committed, complete local suite passed in 782.05s; final summary committed.
Progress: [░░░░░░░░░░] 0%
## Performance Metrics
- Autonomous preparation plans recorded: 7/7; accepted phases: 0/8
- Average duration: See per-plan metrics; elapsed intervals include pauses
- Total active execution time: Not continuously measured
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
Recent trend: All seven preparation/reconciliation records exist; actual task 01-07-02 and Phase 1/EVID acceptance remain open. Existing project work retains its documented bounded evidence.
**Per-Plan Metrics:**
| Plan | Duration | Tasks | Files |
|------|----------|-------|-------|
| Phase 01 P01 | 16 min | 2 tasks | 5 files |
| Phase 01 P02 | 16 min | 2 tasks | 6 files |
| Phase 01 P03 | 22 min | 2 tasks | 4 files |
| Phase 01 P04 | 16 min | 2 tasks | 5 files |
| Phase 01 P05 | 12h 4min | 2 tasks | 7 files |
| Phase 01 P06 | 14 min | 2 tasks | 4 files |
| Phase 01 P07 | 4h 36min elapsed incl quota pause; suite 782.05s | 2 tasks | 16 files |
## Accumulated Context
### Decisions
- Full remaining original game is in scope; fidelity governs behavior and presentation, including significant original quirks.
- Playable slices, standard granularity, autonomous mode and parallel independent plans; research, plan checking and verification enabled; models inherit this session.
- Preserve Jimmy movement and implemented TSK startup-order correction; movement/contact/helper/animation/camera stabilization precedes broader gameplay expansion.
- Cross-cutting checks continue throughout; each requirement has one accountable phase. No original-required category is deferred outside this release.
- Builds/tests/packages stay local; push verified source/tools/docs to existing Gitea. Preserve unrelated working-tree changes.
- [Phase 01]: Version 1 typed hashed receipts keep category, history and actual bytes separate from acceptance; structural readiness never substitutes for native/reference execution.
- [Phase 01]: All eight lifetime/dialogue/input cells require continuous plus four focused obligations on three original/native sides, totaling 120 independently audited obligations.
- [Phase 01]: Retained observations require one session, observed prerequisite departure/return and hashed copy state; each fresh run uses an independent launch/session identity.
- [Phase 01]: Paired review preserves actual speed, separate raw clocks, explicit event and playback drift, exclusive audio and complete recording tails; export never promotes runtime acceptance.
- [Phase 01]: Capability source links are normalized to contained tracked bounded UTF-8 text copies and activated only through exporter-validated local hrefs.
- [Phase 01]: Capability ledger maps all33 requirements and reconciles33 hashed checkpoint rows; documentary coverage, unimplemented work and exact historical content never promote actual original/native acceptance.
- [Phase 01]: One outer observer owns a unique launch/clock identity through Run continuations; simulation ticks remain scene-local and case/session IDs remain declared provenance.
- [Phase 01]: Accepted input means the existing binding's returned gate result, with separately identified post-step ownership; individual command dispatch and independent body/fire work are not inferred.
- [Phase 01]: Observer records are diagnostic source material for later collectors, not receipts or automatic original/native acceptance; fixture classification survives continuations.
- [Phase 01]: READY validates identified offline materials only; original-DxWnd/native Linux/native Windows acceptance remains open 0/120.
- [Phase 01]: Runtime package provenance retains actual completed publish source/dirty/diff identity; selected external tools are identified without redistributing executables.
- [Phase 01]: No display and only auto_null audio yields failed native preflight; all forty Linux obligations retain explicit physical/audible capture dependencies.
- [Phase 01]: Linux matrix history revalidates saved receipt hashes and requires new launch/session IDs; focused captures cannot replace continuous route lifetimes.
- [Phase 01]: Ready materials and local regressions never substitute for actual original/native acceptance; all 120 obligations and ten named human findings remain open.
- [Phase 01]: The integration agent reconciles returned collector records through specified artifact mappings; the tester collects, observes and returns one combined session.
### Pending Todos
Primary readiness review of final 01-07 source/materials, then the single combined human session in docs/evidence/checkpoint-session.md. All EVID requirements remain Pending. Do not launch Phase 2 from preparation counts.
### Blockers/Concerns
- Final 01-07 readiness passes 11,000 immutable files and local suite passes; strict audit still exits 1 with no structural errors, 0/120 accepted obligations and ten pending human findings. This is an actual evidence dependency, not a test failure or auto-approval gate.
- Phase 1: Working whole-original reference capture and current native Windows comparison remain unverified access dependencies. Record limitations; keep acceptance open while independent source-backed recovery continues.
- Phase 2: Real derived responses, helper membership/activation/cleanup, physical order and shared mutable reclip remain live admission gates. Lab/outside capsule stays until its replacement gate closes.
- Full-game completion requires current integrated native Linux/Windows and original-reference evidence. Compilation, copied-original probes and Wine have narrower scopes.
- Historical reports contain superseded narratives; prefer later continuation receipts with exact revision/platform identity. Carl startup ordering is already corrected, not an untouched defect.
### Evidence Pointers
- `.planning/research/SUMMARY.md`, `.planning/codebase/` — scope, dependencies and current architecture.
- `docs/progress.md`, `docs/compatibility.md`, `docs/tasks.md` — implementation/runtime receipts and open work.
- `docs/checkpoint/next-work-plan.md`, `coverage.md`, `implementation-plan.md` — recovery/admission sequence (latter two under the same directory).
- `docs/gameplay/main-menu-player-lifetime.md`, `jimmy-movement-stabilization.md` — preserved correction and movement priority (same directory).
- `../prompt.MD`, `AGENTS.md`, `../AGENTS.md` — authoritative specification/rules; original manifest at `docs/original-manifest.json`.
## Deferred Items
No original-required category deferred outside full reconstruction. Later phases express dependency order only.
## Session Continuity
Last session: 2026-11-14T05:39:45.079Z
Stopped at: Phase1 verified human_needed; ten UAT checks and combined actual session pending
Resume file: .planning/phases/01-reproducible-fidelity-baseline/01-UAT.md
+64
View File
@@ -0,0 +1,64 @@
---
schema_version: 1
open_count: 2
waived_count: 0
fixed_count: 1
total_count: 3
last_updated: 2026-11-13T17:20:49.885Z
---
# Broken Windows Ledger
> Cross-phase defect register. With `workflow.windows_enforce` enabled, `/gsd-ship` blocks while `open_count > 0`.
> Waive with `gsd-tools windows waive <id> "<reason>"` (reason required).
> Mark fixed with `gsd-tools windows fixed <id>`.
| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |
|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|
| 1 | 01 | deviation | tests/test_fidelity_sessions.py | | Task 2 also strengthens shared receipt security regressions in the task-1 test file; fixed and verified. | fixed | | 2026-11-13T00:12:34.143Z | 2026-11-13T00:13:04.410Z |
| 2 | 01 | unrun-verify | docs/evidence/linux-session.md | | Actual Linux display, physical-input and audible capture remains open: no display session and only auto_null audio; all 40 Linux obligations await the final combined session. | open | | 2026-11-13T17:02:56.623Z | |
| 3 | 01 | unmet-truth | docs/evidence/phase01-baseline.md | | Actual original-DxWnd/native Linux/native Windows capture and combined human review remain OPEN0/120; strict audit human_needed. | open | | 2026-11-13T17:20:49.885Z | |
````json
[
{
"id": 1,
"kind": "deviation",
"phase": "01",
"file": "tests/test_fidelity_sessions.py",
"line": null,
"description": "Task 2 also strengthens shared receipt security regressions in the task-1 test file; fixed and verified.",
"status": "fixed",
"reason": "",
"recorded_at": "2026-11-13T00:12:34.143Z",
"resolved_at": "2026-11-13T00:13:04.410Z",
"milestone": null
},
{
"id": 2,
"kind": "unrun-verify",
"phase": "01",
"file": "docs/evidence/linux-session.md",
"line": null,
"description": "Actual Linux display, physical-input and audible capture remains open: no display session and only auto_null audio; all 40 Linux obligations await the final combined session.",
"status": "open",
"reason": "",
"recorded_at": "2026-11-13T17:02:56.623Z",
"resolved_at": null,
"milestone": null
},
{
"id": 3,
"kind": "unmet-truth",
"phase": "01",
"file": "docs/evidence/phase01-baseline.md",
"line": null,
"description": "Actual original-DxWnd/native Linux/native Windows capture and combined human review remain OPEN0/120; strict audit human_needed.",
"status": "open",
"reason": "",
"recorded_at": "2026-11-13T17:20:49.885Z",
"resolved_at": null,
"milestone": null
}
]
````
+199
View File
@@ -0,0 +1,199 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
<!-- refreshed: 2026-11-12 -->
# Architecture
**Analysis Date:** 2026-11-12
## System Overview
```text
Read-only ../Original assets
-> tools/extractors/prepare.py -> artifacts/extracted manifests/buffers/WAV
-> src/GamePort/Assets + original GAM/TSK/ASE/PNG readers
-> Program.Run scene composition
Game simulation/scripts -> Application visuals/HUD -> VulkanRenderer
Game events -> SceneAudio -> SdlAudio -> SDL3
Program.Main -> persistent RenderSession -> SDL window + Vulkan instance/device
```
The desktop application is a single shared Linux/Windows C# executable (`GamePort.csproj`). `src/GamePort/Program.cs` composes concrete systems and owns scheduling. There is no runtime server, database, dependency-injection container, or external game engine.
## Component Responsibilities
| Component | Responsibility | File |
|-----------|----------------|------|
| Application entry | CLI, resource composition, input dispatch, fixed ticks, scene continuation | `src/GamePort/Program.cs` |
| Presentation session | Application lifetime window and renderer; replace scene resources | `src/GamePort/Application/RenderSession.cs` |
| Player simulation | Physics, input/apply order, facing, jump/effects, player camera | `src/GamePort/Game/LabSimulation.cs` |
| Script bridge | Raw control owner, authored transforms, gadget cleanup, vehicle/passenger phases | `src/GamePort/Game/PlayerSceneBinding.cs` |
| Scene director | GAM actors, CAM/MCA/AI chains, cutscene camera, control and issue reporting | `src/GamePort/Game/SceneDirector.cs` |
| Progression | Contacts, inventory, tasks, transitions and save snapshots | `src/GamePort/Game/SceneInteractions.cs`, `src/GamePort/Game/TaskStates.cs` |
| Resource readers | Original and prepared data decoding | `src/GamePort/Assets/` |
| Presentation adapters | Mutable geometry, morphs, sprites, UI and camera projection | `src/GamePort/Application/` |
| GPU backend | Vulkan resources, rendering, resizing, readback and disposal | `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs` |
| Audio | Independent music/speech/effects and SDL WAV stream ownership | `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Audio/SdlAudio.cs` |
## Pattern Overview
**Overall:** Explicit application composition with scene-local state, event-connected gameplay systems and a persistent native presentation owner.
**Key Characteristics:**
- Keep scheduling visible in `src/GamePort/Program.cs`; source ordering is behavior, not interchangeable service invocation order.
- Keep recovered arithmetic in focused `src/GamePort/Game/` modules and presentation in `src/GamePort/Application/`.
- Preserve the distinction between isolated recovered components and admitted live scene adapters (`src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`).
- Use local original-derived assets; Python preparation is a development/package stage (`tools/extractors/prepare.py`, `scripts/package.sh`).
## Layers
**Application composition and presentation:**
- Purpose: Connect input, simulation, scripts, visuals, audio and GPU submission.
- Location: `src/GamePort/Program.cs`, `src/GamePort/Application/`.
- Contains: `RenderSession`, debug interfaces, `SceneHud`, visual adapters and smoke fixtures.
- Depends on: Game, Assets, Audio, Platform and Rendering namespaces.
- Used by: Executable entry and managed regression projects.
**Game state and recovered algorithms:**
- Purpose: Own simulation and script/progression semantics.
- Location: `src/GamePort/Game/`.
- Contains: `LabSimulation`, `SceneDirector`, inventory/tasks, gadgets, vehicles, collision and numeric kernels.
- Depends on: `System.Numerics` and decoded asset types in `src/GamePort/Assets/`.
- Used by: Application orchestration and focused `tests/GamePort.*Tests/` executables.
**Asset decoding:**
- Purpose: Convert bounded original/prepared files into typed CPU resources.
- Location: `src/GamePort/Assets/`.
- Contains: `GamLevel`, `OriginalSave`, `Mesh`, `MorphAnimation`, `PngImage`, resource identities and path resolution.
- Depends on: Filesystem, binary primitives, JSON and numerics; no renderer ownership.
- Used by: Game systems and application/renderer initialization.
**Native platform, GPU and audio:**
- Purpose: Own unmanaged interoperability and device resources.
- Location: `src/GamePort/Platform/Sdl.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`, `src/GamePort/Audio/`.
- Contains: SDL3 imports, Vulkan offscreen/present paths, WAV streams and scene audio orchestration.
- Depends on: SDL3, Silk.NET.Vulkan, shaders and decoded meshes/textures.
- Used by: `src/GamePort/Application/RenderSession.cs` and `src/GamePort/Program.cs`.
**Offline evidence and preparation:**
- Purpose: Inspect source evidence and create reusable resources without modifying originals.
- Location: `tools/binary/`, `tools/extractors/`, `tools/levels/`, `tools/recon/`.
- Contains: Python parsers, extraction manifests, C component probes and observation tools.
- Depends on: Local original files and explicit analysis tooling; not part of the native runtime dependency graph.
- Used by: Tests, local preparation, research and `scripts/package.sh`.
## Data Flow
### Primary Request Path
1. `Program.Main` creates persistent presentation, energy, grappler memory and diagnostics, then invokes the scene runner (`src/GamePort/Program.cs:14`).
2. `Run` resolves originals, loads prepared geometry and original GAM/save data, constructs scene systems and binds the player (`src/GamePort/Program.cs:46`).
3. SDL polling updates held input; unpaused gameplay advances through a 60 Hz accumulator, while bounded fixtures use explicit steps (`src/GamePort/Program.cs:1057`, `src/GamePort/Game/FixedStepClock.cs`).
4. Each tick advances gadget/projectile bodies, player/vehicle binding, timers/targets, interactions/mechanisms, patrols, director and animation state (`src/GamePort/Program.cs:1271`).
5. Application visuals mutate mesh vertices/draw properties, update HUD and select gameplay/script/orbit camera; renderer uploads and renders (`src/GamePort/Program.cs:1371`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`).
### Player and cutscene phase ordering
1. `LabSimulation.Step` runs body physics before registry-style callbacks (`src/GamePort/Game/LabSimulation.cs:265`).
2. Fresh direct-scene input runs before ceiling/floor/facing and player apply. Retained input runs after player/effect updates. `Program` sets `InputAfterPlayerUpdate` for story entry or carried saves (`src/GamePort/Program.cs:361`).
3. Lack of Jimmy control gates input/player apply, not body, facing or owned effect clocks. `PlayerSceneBinding` receives director preparation/transform events and preserves vehicle control ordering (`src/GamePort/Game/PlayerSceneBinding.cs`).
4. Script preparation separates stop-motion, orientation flattening, gadget release and authored transforms; do not replace these with a generic player reset (`src/GamePort/Game/PlayerSceneBinding.cs`, `src/GamePort/Game/SceneDirector.cs`).
### Scene loading and retained state
1. Contact or practice logic requests a `LevelTransition`; application stages a departure/RETURN root through `RuntimeCheckpoint` (`src/GamePort/Program.cs:339`, `src/GamePort/Game/RuntimeCheckpoint.cs`).
2. Scene runner returns a continuation with destination arguments, original-format save snapshot and optional bounded `PlayerLevelState` (`src/GamePort/Program.cs`, `src/GamePort/Game/PlayerLevelState.cs`).
3. `Main` invokes a new scene run. GAM actors, bindings, visual resources and scene audio are rebuilt; `RenderSession.LoadScene` calls `ReplaceScene` on the existing renderer (`src/GamePort/Application/RenderSession.cs`).
4. Vulkan scene replacement waits for device idle and replaces scene GPU resources while retaining presentation identity (`src/GamePort/Rendering/Vulkan/VulkanRenderer.cs:101`).
### Source-to-extracted-assets pipeline
1. `tools/recon/inventory.py` provides original manifest verification against `docs/original-manifest.json`.
2. `tools/extractors/prepare.py` reads OMT/GAM/ASE/PNG and dispatches scene, entity, model, UI, effect and gadget resource extraction. `tools/extractors/omt.py` and `tools/levels/gam.py` retain format-specific parsing.
3. Generated `artifacts/extracted/` contains scene JSON, textures, animation buffers/manifests, entity/model resources, WAV and a scene catalog. Missing scene archives are reported rather than substituted (`tools/extractors/prepare.py`).
4. Runtime readers load prepared resources and original GAM/TSK/base assets; `scripts/package.sh` copies those into local package `scenes/` and `assets/` trees. Runtime packages do not need Python.
**State Management:**
- Application session: presentation, diagnostics preference, `PlayerEnergy` and `GrapplerMemory` are created outside the scene loop (`src/GamePort/Program.cs`).
- Scene: simulation, actors, tasks/inventory, mechanisms, animation meshes, audio and bindings are concrete objects recreated by `Run` (`src/GamePort/Program.cs`).
- Retained route scalars: `PlayerLevelState` supports LV1B/VR04/LEV1 with selected gadget -1 or 3; this is in-memory state, not an extension of TSK (`src/GamePort/Game/PlayerLevelState.cs`).
- Original save persistence: `OriginalSave` encodes TSK tasks/items/checkpoint state; save output uses a temporary file and move outside original assets (`src/GamePort/Assets/OriginalSave.cs`, `src/GamePort/Program.cs`).
## Key Abstractions
**Mesh and MeshDraw:**
- Purpose: CPU geometry, source collision polygons, textures and per-range material/presentation state.
- Examples: `src/GamePort/Assets/Mesh.cs`, `src/GamePort/Application/SceneActorVisuals.cs`.
- Pattern: Arrays plus mutable draw state; visual adapters append/update shared scene data rather than owning Vulkan objects.
**GamEntity and DirectorActor:**
- Purpose: Preserve serialized properties separately from live authored actor state.
- Examples: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/SceneDirector.cs`.
- Pattern: Bounded typed decoding followed by scene-specific actor/script execution; unknown behavior produces issues.
**Original collision components and live adapters:**
- Purpose: Express bounded source contracts without assuming a complete recovered physical registry.
- Examples: `src/GamePort/Game/OriginalBodyPhysics.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`.
- Pattern: Caller-owned state/accessors and explicit profiles. Pair callbacks and generic normal responses do not establish scene membership or Jimmy's override policy.
## Entry Points
**Native executable:**
- Location: `src/GamePort/Program.cs`.
- Triggers: `dotnet run`, local published executable or package launchers.
- Responsibilities: Scene/model preview, playable story, asset verification, audio/GPU/SDL fixtures and explicit CLI validation.
**Offline preparation:**
- Location: `tools/extractors/prepare.py`.
- Triggers: Local developer invocation and `scripts/package.sh`.
- Responsibilities: Original-derived resource production outside the source installation.
**Regression and build entry points:**
- Location: `scripts/test.sh`, `scripts/build-linux.sh`, `scripts/build-windows.sh`, `tests/GamePort.*Tests/Program.cs`, `tests/test_*.py`.
- Triggers: Local scripts or direct test projects.
- Responsibilities: Bounded source/algorithm/parser checks, GPU fixtures and native packaging inputs. A cross-publish is not native Windows runtime evidence.
## Architectural Constraints
- **Threading:** Gameplay and rendering are explicitly scheduled on the application loop; Vulkan submission/presentation waits synchronously (`src/GamePort/Program.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). SDL manages audio stream transport (`src/GamePort/Audio/SdlAudio.cs`).
- **Global state:** Native SDL state is process-level; managed session state is explicitly passed. Keep native resource disposal scoped through `RenderSession` and `SdlAudio` (`src/GamePort/Application/RenderSession.cs`, `src/GamePort/Audio/SdlAudio.cs`).
- **Circular imports:** No project-layer circular project-reference chain is detected: production source is compiled into one executable (`GamePort.csproj`). Events intentionally connect director/player/inventory lifetimes (`src/GamePort/Game/PlayerSceneBinding.cs`).
- **Live solver boundaries:** Lab/outside retain capsule compatibility. Original static body is admitted by explicit scene gates including VR01/VR02/VR04/VR07/VR08; VR04 is a bounded source-body scene, not a full dynamic registry (`src/GamePort/Program.cs:361`, `src/GamePort/Game/LabSimulation.cs`).
- **Recovery gates:** `OriginalPairCollision` and `OriginalNormalContacts` are isolated components, not live admission. Physical activation/helper lifetime, actual derived callbacks and shared reclip remain separate obligations (`src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `docs/checkpoint/next-work-plan.md`).
- **Movement priority:** Preserve Jimmy movement and caller-dependent retained cutscene state before gameplay expansion (`AGENTS.md`, `docs/gameplay/jimmy-movement-stabilization.md`).
- **References:** `../Original/` is immutable authoritative evidence; sibling JN-Engine research is a source lead, not a runtime service or replacement movement implementation (`AGENTS.md`, `docs/reviews/jn-engine-survey.md`).
## Anti-Patterns
### Treating component recovery as live scene coverage
**What happens:** Bounded pair/contact components coexist with separately gated runtime solvers (`src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Program.cs`).
**Why it's wrong:** Substituting them solely because component tests pass loses physical registration, activation and real derived callback policies.
**Do this instead:** Preserve explicit scene admission in `src/GamePort/Program.cs` and require the dependencies recorded in `docs/checkpoint/next-work-plan.md` before wiring new actors.
### Collapsing input, control and body phases
**What happens:** `LabSimulation` exposes both fresh and retained callback orders, while scripts independently gate raw control (`src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/PlayerSceneBinding.cs`).
**Why it's wrong:** A generic reset or input-first rewrite changes neutral cutscene return, facing and effect behavior.
**Do this instead:** Preserve named preparation events, retained scalar state and `InputAfterPlayerUpdate`; extend focused lifecycle regressions (`tests/GamePort.BodyOwnershipTests/Program.cs`, `tests/GamePort.DirectorTests/Program.cs`).
## Error Handling
**Strategy:** Reject invalid data and native failures explicitly; report unrecovered script behavior without inventing execution (`src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/SceneDirector.cs`).
**Patterns:**
- Top-level exception handling prints to stderr and returns 1; validation/fixture failures return 2 (`src/GamePort/Program.cs`).
- Bounded readers throw `InvalidDataException`; missing resources use explicit missing/ambiguous errors (`src/GamePort/Assets/AssetPath.cs`, `src/GamePort/Assets/PreparedEntityResources.cs`).
- SDL/Vulkan failure checks throw with native operation context; cleanup uses `IDisposable`/`finally` (`src/GamePort/Application/RenderSession.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`).
- Director bounded dispatch records unsupported behavior and blocks problematic chains (`src/GamePort/Game/SceneDirector.cs`).
## Cross-Cutting Concerns
**Logging:** Console diagnostics, unrecovered behavior lists and live debug overlays (`src/GamePort/Program.cs`, `src/GamePort/Application/DebugDiagnostics.cs`).
**Validation:** Explicit endian parsing, finite/count/size checks, resource identity validation and Vulkan validation/error counts (`src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/PreparedEntityResources.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`).
**Authentication:** Not applicable; local desktop runtime with no online identity service (`GamePort.csproj`, `src/GamePort/Program.cs`).
---
*Architecture analysis: 2026-11-12*
+143
View File
@@ -0,0 +1,143 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# Codebase Concerns
**Analysis Date:** 2026-11-12
Scope: tracked GamePort source and documented findings. Source HEAD is `bdca29d`; integrated SDL/GPU evidence belongs to `bf876e9`, while distributed local packages identify `924ad2f`. These are distinct validation targets, as recorded in `docs/progress.md` and `docs/compatibility.md`. This mapping performs no new builds, tests, binary execution or runtime comparison.
## Tech Debt
**Standalone collision contracts await supported live admission:**
- Issue: `OriginalPairCollision` requires caller-owned physical order and real callbacks; `OriginalNormalContacts` implements inherited response without providing Jimmy's override or scene admission. Dynamic/static composition remains test-only.
- Files: `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/DynamicSceneCollision.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/actor-normal-contacts.md`.
- Impact: passing component snapshots cannot establish general NPC interaction, live dynamic collision or game/task side effects. Replacing existing collision directly would skip unresolved owners.
- Fix approach: recover soldier complete174 and helper membership/order first; then bind a bounded response adapter to explicitly supported actor states. Preserve late inhibition, radius, geometry and42C reads. Do not cache pre-callback fields or apply inherited reflection to Jimmy ordinary374.
**Physical registration and retained helper lifecycle are incomplete:**
- Issue:72 serialized VR04 records/13 interfaces and21 helper edges establish source construction/registration contracts, not a full active body list. Common append permits duplicate pointers, Jimmy49E guards its whole bridge, and per-object Init/PostLoad visits newly appended tails.
- Files: `docs/checkpoint/physical-registration.md`, `docs/checkpoint/vr04-generated-bodies.md`, `docs/checkpoint/dynamic-context.md`, `tools/binary/physical_registration.py`, `tools/binary/helper_teardown.py`.
- Impact: constructor-only helpers, Jeep child cleanup, activation and LOAD/RETURN reuse can change physical order and contact effects. Counting serialized records or deduplicating registration would misrepresent the original.
- Fix approach: trace actual helper removal/re-entry/activation and cleanup mutations across fresh load, retained load and RETURN. Compare complete ordered registry snapshots before enabling additional physical members.
**Compatibility adapters remain explicit movement boundaries:**
- Issue: the lab/outside capsule, floor-derived visual sole correction and fixed60Hz scheduling are port policies. Bounded source-body integration does not cover every special material or dynamic actor path.
- Files: `src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/SceneCollision.cs`, `src/GamePort/Game/FixedStepClock.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`, `docs/gameplay/jimmy-movement-stabilization.md`, `docs/checkpoint/body-contact-implementation.md`.
- Impact: existing navigation/playability and recovered scalar motion are not full original-body or scheduler parity.
- Fix approach: retain the current Jimmy baseline while recovering successful hazard/FENCE/LADDER paths, support ownership, actor mode/facing and real callback publication. Use original evidence to replace one named adapter at a time; JN-Engine replacement movement is not authoritative.
**Partial camera/audio/UI/save ownership:**
- Issue: the coverage ledger identifies separate scripted/chase eyes, merged clip policy, independent file-based audio streams, a subset of objective/UI dispatch and a fresh-director save-load path that differs from original repeated task/entity callbacks.
- Files: `docs/checkpoint/coverage.md`, `src/GamePort/Application/OrbitCamera.cs`, `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Game/ObjectivePanel.cs`, `src/GamePort/Game/SceneDirector.cs`, `src/GamePort/Assets/OriginalSave.cs`.
- Impact: recovered route behavior does not establish arbitrary save/load, full camera handoff, audio bank/clock lifecycle or all UI flags.
- Fix approach: follow the ownership/probe gates in `docs/checkpoint/next-work-plan.md`; recover dispatcher transitions and repeated callbacks before expanding UI, progression or gadget behavior.
## Known Bugs
**No newly reproduced runtime bug in this source-only mapping:**
- Symptoms: current docs retain earlier failure narratives alongside resolved checkpoint entries. The post-Carl neutral-bank failure has a supported TSK startup ordering correction and documented first-input/300-idle regression results; it must not be listed as an unfixed current bug.
- Files: `docs/progress.md`, `docs/tasks.md`, `docs/compatibility.md`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/checkpoint/coverage.md`.
- Trigger: the corrected path is successful TSK story entry, whose retained background Jimmy precedes new level input; direct fresh-GAM ordering is a separate case.
- Workaround: preserve the correction and fresh/retained distinction. Ordinary landing residual bank is user-confirmed original behavior; do not add a universal leveling/reset workaround. Whole-original Carl comparison remains unverified.
## Security Considerations
**Preservation and generated-probe isolation:**
- Risk: extraction or instrumentation directed into originals could destroy authoritative evidence; incorrect relocation operands can invalidate a copied-code experiment.
- Files: `AGENTS.md`, `tools/binary/actor_contact.py`, `tools/recon/inventory.py`, `docs/original-manifest.json`, `docs/checkpoint/actor-normal-contacts.md`.
- Current mitigation: the actor-contact generator rejects overlapping original/output directories and generated symlinks; reviewed operands, complete source/probe identities and completion markers guard capture acceptance. The documented cross-instruction relocation failure affects an invalid private probe, not original behavior.
- Recommendations: retain operand-specific regression guards and hash verification; keep invalid partial captures excluded. Never execute or patch original files in place.
**Local asset parsing and path boundary:**
- Risk: malformed local assets require bounded decoding, and portable case lookup must reject ambiguous names rather than silently load another file.
- Files: `src/GamePort/Assets/AssetPath.cs`, `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/PngImage.cs`, `tests/GamePort.DataTests/Program.cs`, `tests/test_extractors.py`.
- Current mitigation: paths reject dot/parent components and require one case-insensitive match; GAM validates counts, remaining spans, finite scalars and duplicate properties; image parsing enforces supported formats and size limits.
- Recommendations: preserve these checks when adding formats and test malformed/truncated inputs. This source review identifies no reproduced exploit and makes no claim that these checks constitute a general filesystem sandbox.
## Performance Bottlenecks
**No measured bottleneck established by this mapping:**
- Problem: pair enumeration and source cell/FIFO traversal have scaling costs, but there is no new timing measurement here.
- Files: `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Application/DebugDiagnostics.cs`.
- Cause: `Step` enumerates an upper triangular body list, giving quadratic candidate growth; static traversal deliberately retains cell duplicates and retries. This is source complexity evidence, not a measured live slowdown; the pair component is not live.
- Improvement path: measure candidate counts, NodeVisits, TriangleTests and frame timings on supported scenes before optimizing. Preserve asymmetric exclusions, duplicate visits, tie order and callback timing; do not introduce an order-changing broadphase without equivalence evidence.
## Fragile Areas
**Callback-mutated context and late getters:**
- Files: `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/dynamic-reclip.md`, `docs/checkpoint/actor-normal-contacts.md`.
- Why fragile: callbacks can alter inhibition/radius/geometry/force state before reclip; retained last polygon can issue another callback; final local-root publication can overwrite callback root edits. Getter timing is observable behavior.
- Safe modification: retain accessor order, independent state channels, XYZ/full-Vec4 setter distinctions and explicit context ownership. Test full snapshots/event order rather than final root alone.
- Test coverage:30 normal-contact fixtures include synthetic mutations. They do not execute real soldier174/Jimmy204 policy or establish reentrant linked-list mutation.
**Source arithmetic and finite-domain boundaries:**
- Files: `src/GamePort/Game/OriginalSphereResponse.cs`, `src/GamePort/Game/OriginalHeading.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `docs/checkpoint/dynamic-reclip.md`.
- Why fragile: float-store boundaries, source triangle winding, heading wrap and strict comparisons affect complete state even where final positions agree. Double intermediates are not a universal x87 emulator.
- Safe modification: require original instruction/store evidence and exact fixture comparisons for arithmetic changes. Keep unsupported zero-horizontal normalization explicit instead of silently inventing a policy.
- Test coverage: populated reclip has14 complete observations/12 kernel steps; inherited normal response has30 bounded snapshots. Degenerate inputs, arbitrary normals and broad x87 equivalence are not certified.
**Story entry and ordinary landing:**
- Files: `src/GamePort/Program.cs`, `src/GamePort/Game/LabSimulation.cs`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/gameplay/jimmy-landing-rotation-source.md`.
- Why fragile: TSK-backed retained order and fresh direct-scene order differ; a generic neutral-angle reset would erase legitimate landing bank while masking scheduler errors.
- Safe modification: preserve first-story retained player-before-input classification and baseline movement algorithms. Recheck first resumed neutral frame, sustained idle, held input, Left/Right bank, natural completion/skip and repeated scenes after lifecycle changes.
- Test coverage: eight managed trajectories and integrated Linux evidence are documented; original full Carl runtime and current native Windows comparison remain separate gaps.
## Scaling Limits
**Bounded solver contracts:**
- Current capacity: `OriginalStaticCollision.Move` permits256 retries and throws beyond its verified finite-motion domain; `OriginalPairCollision.Step` requires a stable input list during the pass.
- Files: `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalPairCollision.cs`.
- Limit: source recursive retry behavior and callback-driven linked-list insertion/deletion are not fully represented by these bounded APIs. The256 guard is an implementation boundary, not measured original capacity.
- Scaling path: recover problematic repeated-contact cases and list-mutation semantics before widening the contract; preserve explicit failure rather than return an invented final position.
**Scene admission is deliberately restricted:**
- Current capacity: static route construction admits LV1B, VR01, VR02, VR04, VR05, VR07, VR08 and LEV1; this is not a claim of complete gameplay in those eight scenes. Prepared resources cover33 available scenes according to the project ledger.
- Files: `src/GamePort/Game/OriginalStaticCollision.cs`, `docs/tasks.md`, `docs/checkpoint/coverage.md`.
- Limit: asset availability and class binding do not establish live physics, AI or progression coverage in other scenes.
- Scaling path: recover scene-specific consumers and ownership before broadening admission; keep unsupported scenes on their documented compatibility path.
## Dependencies at Risk
**No package-specific obsolescence or migration risk established:**
- Risk: this mapping provides no evidence that .NET10, SDL3 or Silk.NET.Vulkan requires replacement. The material dependency is runtime/platform validation, not a speculative package migration.
- Files: `GamePort.csproj`, `scripts/build-windows.sh`, `scripts/package.sh`, `docs/compatibility.md`.
- Impact: a successful Windows cross-publish and resource match do not establish current native Windows execution, audible behavior or driver compatibility.
- Migration plan: not applicable. Run the same route/control/window/audio scenarios on native Windows and record exact source/package identity before claiming platform equivalence.
## Missing Critical Features
**Real derived actor response and game/task contact consumers:**
- Problem: soldier409590 mode10 calls complete174→4098C0, whose RNG/target/action policy is not executed by the bounded fixture; Jimmy204 is likewise a record-only endpoint. Enter/stay/leave gameplay consumers remain separate from normal response.
- Files: `docs/checkpoint/actor-normal-contacts.md`, `tools/binary/actor_contact.py`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/tasks.md`.
- Blocks: general dynamic actor admission and faithful enemy/contact behavior. Recover complete caller/callee state and RNG progression before wiring supported adapters.
**Full reconstruction beyond bounded playable routes:**
- Problem: animation playback/completion/interrupt timing, shared camera/input ownership, full audio bank lifecycle, arbitrary retained LOAD/save and broader progression remain open in the coverage ledger. New gadget expansion is paused behind movement/core-system gates.
- Files: `docs/checkpoint/coverage.md`, `docs/checkpoint/next-work-plan.md`, `docs/tasks.md`, `docs/gameplay/jimmy-movement-stabilization.md`.
- Blocks: full-game completion and blanket fidelity claims. Prioritize the interacting lab→VR04→lab→outside route and remove specific documented assumptions with original evidence.
## Test Coverage Gaps
**Whole-original gameplay comparison and native Windows:**
- What's not tested: current source as a complete original-game Carl sequence and native Windows equivalent of the integrated Linux route. Black-frame original Wine startup/allocation observations do not supply visual gameplay comparison; earlier Wine64 port evidence belongs to `ea04210`.
- Files: `docs/compatibility.md`, `docs/gameplay/original-startup-diagnostic.md`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/reference-testing.md`.
- Risk: component correctness and Linux replay success can coexist with differences in original timing, visuals, audio and Windows behavior.
- Priority: High. Capture a working copied-original banked-entry/skip/neutral-return interval and native Windows route evidence, identifying exact binaries and limitations.
**Real helper lifecycle and reentrant collision integration:**
- What's not tested: full fresh/retained active physical lists, helper cleanup/re-entry during LOAD/RETURN, real soldier RNG response, actual contact-driven task mutations and callback list mutation during a pair pass.
- Files: `tests/GamePort.PairLifecycleTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/physical-registration.md`, `docs/checkpoint/vr04-generated-bodies.md`, `docs/checkpoint/actor-normal-contacts.md`.
- Risk: synthetic endpoint and stable-list tests can pass while real admission produces incorrect order or side effects.
- Priority: High. Add original-supported complete ordered-state fixtures, then bounded integration regressions before enabling actors.
**Source/package evidence divergence:**
- What's not tested: latest standalone normal-contact source changes as a new SDL/GPU/native Windows package checkpoint. Current source `bdca29d`, integrated runtime `bf876e9` and packaged `924ad2f` must remain separately identified.
- Files: `docs/progress.md`, `docs/compatibility.md`, `scripts/package.sh`.
- Risk: citing earlier package readbacks as verification of later source overstates coverage.
- Priority: Medium. At the next authorized integration checkpoint, validate the complete intended source, rebuild clean packages and record identities, resource hashes and platform-specific execution receipts.
---
*Concerns audit: 2026-11-12*
+121
View File
@@ -0,0 +1,121 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# Coding Conventions
**Analysis Date:** 2026-11-12
## Naming Patterns
**Files:**
- Use PascalCase C# filenames matching the principal type: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`.
- Use snake_case Python modules and `test_*.py` regressions: `tools/extractors/sound_bank.py`, `tests/test_actor_contact.py`.
- Keep shell entry points under `scripts/`, using descriptive hyphenated names such as `scripts/test-window-transitions.sh`.
**Functions:**
- Use PascalCase C# methods (`ReadVelocity`, `GenericWall`) as in `src/GamePort/Game/OriginalNormalContacts.cs`.
- Use snake_case Python functions (`export_sound_bank`, `validate_output`) as in `tools/extractors/sound_bank.py` and `tools/extractors/omt.py`.
- Name Python test methods `test_<behavior>`; `tests/test_extractors.py` names invalid-input cases explicitly.
**Variables:**
- Use camelCase C# parameters and locals, with explicit role names such as `headingUnits`, `oldHeading`, `carriedPlayer` in `src/GamePort/Game/OriginalNormalContacts.cs` and `src/GamePort/Program.cs`.
- Private C# fields do not uniformly use underscore prefixes; match the surrounding module (`src/GamePort/Assets/GamLevel.cs`).
- Python locals use snake_case; module constants use uppercase (`ROOT`, `ORIGINAL`, `CALLBACK_OPERANDS` in `tests/test_actor_contact.py`).
**Types:**
- Use PascalCase C# classes/records and `I`-prefixed interfaces, exemplified by `OriginalNormalContacts` and `IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`.
- Python uses PascalCase classes and frozen dataclasses for resource identity (`Reader`, `Entry`, `FormatError` in `tools/extractors/omt.py`).
## Code Style
**Formatting:**
- No tracked formatter or `.editorconfig` is detected in the mapped repository. Follow each file's existing style rather than assuming an enforced formatter (`GamePort.csproj`, `src/GamePort/Assets/GamLevel.cs`).
- C# generally uses four spaces, file-scoped namespaces and braces on separate lines; short guards and expression-bodied helpers are common. Some numerical modules and console tests use compact spacing (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`).
- Python uses four spaces, type annotations where useful, and compact reader helpers; quotation style varies (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`).
**Linting:**
- Dedicated C#/Python lint configurations are Not detected. `GamePort.csproj` enables nullable references, implicit usings and unsafe blocks; it does not declare warnings-as-errors or a separate analyzer package.
- Preserve explicit compile globs and shader copy rules in `GamePort.csproj`; test projects can compile production source directly, as in `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`.
## Import Organization
**Order:**
1. C# explicit `System` namespaces precede project namespaces in `src/GamePort/Program.cs` and `tests/GamePort.ActorContactTests/Program.cs`.
2. Group runtime dependencies by namespace; implicit usings supply common base namespaces (`GamePort.csproj`).
3. Python standard library imports precede local tool imports. Tests insert the relevant tools directory into `sys.path` (`tests/test_extractors.py`, `tests/test_actor_contact.py`).
**Path Aliases:**
- No frontend-style aliases are applicable. Use `GamePort.Assets`, `GamePort.Game` and related C# namespaces; Python tool imports resolve from explicit local paths (`src/GamePort/Program.cs`, `tests/test_actor_contact.py`).
## Error Handling
**Patterns:**
- Fail malformed assets with contextual format exceptions, including offsets. Do not silently truncate or accept trailing bytes (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`).
- Reject unsupported recovered behavior explicitly with `NotSupportedException`; validate nonfinite values separately with argument exceptions (`src/GamePort/Game/OriginalNormalContacts.cs`).
- Keep entry-point failure reporting centralized: `src/GamePort/Program.cs` catches exceptions, writes to stderr and returns status 1.
- Resolve original asset names case-insensitively after direct lookup, reject `.`/`..`, and reject missing/ambiguous matches (`src/GamePort/Assets/AssetPath.cs`).
- Reject extraction output overlapping originals; preserve source hashes and archive identities in generated metadata (`tools/extractors/sound_bank.py`).
Representative bounded C# reader from `src/GamePort/Assets/GamLevel.cs`:
```csharp
public ReadOnlySpan<byte> Take(int length)
{
if (length < 0 || length > Remaining)
throw new InvalidDataException($"Truncated GAM at {Offset:x}");
var result = data.Slice(Offset, length);
Offset += length;
return result;
}
public uint U32() => BinaryPrimitives.ReadUInt32BigEndian(Take(4));
```
## Logging
**Framework:** Console output, with explicit application diagnostics; no hosted logging service is detected (`src/GamePort/Program.cs`, `src/GamePort/Application/DebugDiagnostics.cs`).
**Patterns:**
- Report fatal errors to `Console.Error`; expose inspection/smoke commands and readback paths through CLI options (`src/GamePort/Program.cs`).
- Tests print descriptive `PASS` messages and throw on failure (`tests/GamePort.ActorContactTests/Program.cs`).
- Persist verification scope and limitations in `docs/progress.md`, `docs/compatibility.md` and subsystem reports; console success alone does not establish whole-game equivalence.
## Comments
**When to Comment:**
- Explain original addresses, ownership, sampled field order and excluded behavior rather than restating arithmetic (`src/GamePort/Game/OriginalNormalContacts.cs`).
- Preserve concrete resource semantics: effect IDs are archive identities, and encoded audio preservation is separate from decoder support (`tools/extractors/sound_bank.py`).
- Keep recovered contracts distinct from approximations and runtime admission; `AGENTS.md` and `docs/checkpoint/actor-normal-contacts.md` make these evidence boundaries explicit.
**XML documentation / Python docstrings:**
- Use C# `/// <summary>` for bounded public contracts and interfaces (`src/GamePort/Game/OriginalNormalContacts.cs`).
- Use Python module/class docstrings for recovery purpose and failure semantics (`tools/extractors/omt.py`). JSDoc/TSDoc is Not applicable.
## Function Design
**Size:**
- Prefer focused components such as the ceiling/reflection helpers in `src/GamePort/Game/OriginalNormalContacts.cs`; no numerical line-count rule is detected. `src/GamePort/Program.cs` remains a substantial orchestration entry point.
**Parameters:**
- Use explicit vectors, typed state and named flags rather than hidden scene state in recovered algorithms (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`).
- Inject actor-owned accessors through interfaces where read order matters; do not cache values across callbacks without evidence (`IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`).
- Keep bounded readers over spans/bytes and explicitly choose endianness (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`).
**Return Values:**
- Return parsed records, typed state, or explicit metadata; throw for malformed/unsupported input (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/sound_bank.py`).
- Preserve float-store boundaries and intentional double intermediates in recovered math. Do not simplify formulas or clamp source values without evidence (`src/GamePort/Game/OriginalNormalContacts.cs`, `docs/checkpoint/dynamic-reclip.md`).
## Module Design
**Exports:**
- Keep asset decoding in `src/GamePort/Assets/`, recovered algorithms in `src/GamePort/Game/`, SDL interop in `src/GamePort/Platform/Sdl.cs`, and presentation in `src/GamePort/Application/`.
- Python tools expose importable parser/export functions as well as CLI-oriented modules (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`).
- Use `using`/disposal and explicit native ownership at runtime boundaries (`src/GamePort/Program.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`); follow the project requirement in `AGENTS.md`.
**Barrel Files:**
- Not detected / Not applicable. C# namespaces and project compile includes provide organization (`GamePort.csproj`).
- Project-local agent skill constraints: the configured agent-skill query is empty; the applicable project constraints are in `AGENTS.md`.
---
*Convention analysis: 2026-11-12*
+92
View File
@@ -0,0 +1,92 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# External Integrations
**Analysis Date:** 2026-11-12
## APIs & External Services
**Game runtime:**
- No hosted runtime service is required; offline operation and no telemetry are requirements in `AGENTS.md`. Runtime entry/configuration and resource loading reside in `src/GamePort/Program.cs`.
- Vulkan is a local native graphics API, accessed through Silk.NET.Vulkan/KHR/EXT `2.23.0` (`GamePort.csproj`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`). Authentication: not applicable.
- SDL3 is a local native window/input/audio API, accessed through project P/Invoke (`src/GamePort/Platform/Sdl.cs`, `src/GamePort/Audio/SdlAudio.cs`). Authentication: not applicable.
**Dependency acquisition (development only):**
- Microsoft SDK archives, SDL release archives and optional Ubuntu packages are downloaded by `scripts/bootstrap.sh`; the SDK and SDL archive hashes are pinned there.
- NuGet resolves managed packages through `dotnet restore` in `scripts/bootstrap.sh`, with direct versions in `GamePort.csproj` and resolved dependencies in `packages.lock.json`.
- These download sources are build-time inputs, not runtime asset storage or telemetry destinations (`scripts/bootstrap.sh`, `AGENTS.md`).
**Local reverse-engineering tools:**
- `scripts/rea.sh` launches local REA with Ghidra/full JDK prerequisites. `tools/binary/rea_decompile_batch.py` communicates using local stdio JSON-RPC and saves complete replies/Evidence separately from originals.
- Use generated target copies; the batch wrapper rejects original-directory targets and output (`tools/binary/rea_decompile_batch.py`). This is developer analysis infrastructure, not game networking.
## Data Storage
**Databases:**
- No database server, ORM or connection-string configuration is detected in the runtime/project manifest; assets and game data are read through local readers (`GamePort.csproj`, `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/OriginalSave.cs`).
**File Storage:**
- Local filesystem only: source assets are selected by `--assets` or discovery of `Original`/`original`/`assets` directories; use case-insensitive bounded path resolution in `src/GamePort/Assets/AssetPath.cs`.
- Local prepared scene/animation/entity JSON, binary mesh/texture data and WAV files are emitted by `tools/extractors/prepare.py`; its default output is `artifacts/extracted`.
- `scripts/package.sh` copies required original assets and prepared resources into local package `assets/`, `scenes/` and `audio/` directories. Original files remain separate and byte-identical (`AGENTS.md`).
- Original-format TSK checkpoint reads/writes are exposed through `--load-save` and `--write-save`; output is kept outside assets, with temporary-file replacement in `src/GamePort/Program.cs` and encoding in `src/GamePort/Assets/OriginalSave.cs`.
- Debug checkpoint defaults to `debug-checkpoint.tsk` beside the executable; the debug smoke path is separate in `src/GamePort/Program.cs`. These are checkpoint/progression snapshots, not arbitrary full live-game saves (`README.md`).
**Caching:**
- Local generated SDK/dependency/prepared-resource caches only: `scripts/env.sh` configures `.nuget/packages` and local SDK paths; `tools/extractors/prepare.py` manages prepared output.
- No distributed cache or hosted asset cache is declared in `GamePort.csproj` or `scripts/package.sh`.
## Authentication & Identity
**Auth Provider:**
- None for the game runtime; no account/login integration is configured in `src/GamePort/Program.cs` or `GamePort.csproj`.
- Gitea source-control authentication is outside runtime configuration. `AGENTS.md` authorizes pushing completed, verified source commits to existing `Gitea`, with `main` tracking `Gitea/main`; do not embed credentials in documentation.
## Monitoring & Observability
**Error Tracking:**
- No external error-tracking service is declared in `GamePort.csproj`. Top-level exceptions print to stderr and exit unsuccessfully in `src/GamePort/Program.cs`.
- Optional local Khronos validation output uses `VK_LAYER_KHRONOS_validation` and EXT debug utils; errors increment a renderer counter and messages print to stderr in `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`.
**Logs:**
- Console runtime/resource/audio/smoke diagnostics in `src/GamePort/Program.cs` and `src/GamePort/Audio/SdlAudio.cs`.
- In-process live diagnostics/debug overlay in `src/GamePort/Application/DebugDiagnostics.cs` and `src/GamePort/Application/DebugMenuOverlay.cs`; GPU readback screenshots are local outputs exposed by `src/GamePort/Program.cs`.
- Analysis evidence is written locally by `tools/binary/rea_decompile_batch.py`; current validation scope and provenance are recorded in `docs/compatibility.md` and `docs/progress.md`.
## CI/CD & Deployment
**Hosting:**
- Native local executables, not a hosted application: `scripts/build-linux.sh` and `scripts/build-windows.sh` publish self-contained platform binaries; `scripts/package.sh` assembles local packages and launchers.
- Native SDL is bundled; the host supplies a Vulkan 1.3 graphics loader/driver (`GamePort.csproj`, `scripts/package.sh`).
- Existing Gitea remote is for verified source commits only; original assets and generated packages must not be uploaded (`AGENTS.md`). Workspace `../.git` is reserved; project Git operations belong to `GamePort/` (`../AGENTS.md`).
**CI Pipeline:**
- Local scripts only: `scripts/test.sh`, `scripts/test-window-transitions.sh`, `scripts/build-linux.sh`, `scripts/build-windows.sh`, `scripts/package.sh`.
- No cloud CI is desired or authorized (`AGENTS.md`, `../prompt.MD`). This absence is intentional.
- Cross-publish success does not establish native Windows runtime behavior; retain the scope distinctions in `docs/compatibility.md`.
## Environment Configuration
**Required env vars:**
- No runtime service keys or credentials required (`AGENTS.md`, `src/GamePort/Program.cs`).
- Development shell setup exports `DOTNET_CLI_HOME`, `DOTNET_CLI_TELEMETRY_OPTOUT`, `DOTNET_SKIP_FIRST_TIME_EXPERIENCE` and `NUGET_PACKAGES`; conditionally sets `DOTNET_ROOT`, `PATH`, `LD_LIBRARY_PATH`, `VK_LAYER_PATH` (`scripts/env.sh`).
- Test audio can use `SDL_AUDIODRIVER=dummy` (`scripts/test.sh`).
- Local analysis launcher uses `GHIDRA_INSTALL_DIR`, `JAVA_HOME`, `NEUTRON_REA_JAVA_HOME`, `NEUTRON_REA_NODE` and `NEUTRON_REA_LAUNCHER` (`scripts/rea.sh`). These are developer tool selectors, not game configuration.
**Secrets location:**
- No runtime secret store is required (`AGENTS.md`). Source-control credentials remain external to runtime and this map.
- `scripts/rea.sh` optionally sources ignored `.tools/rea.env`; only the launcher reference is inspected, not the environment file contents.
## Webhooks & Callbacks
**Incoming:**
- No HTTP webhook endpoints are declared in `GamePort.csproj` or `src/GamePort/Program.cs`. SDL events and Vulkan validation callbacks are local API callbacks (`src/GamePort/Platform/Sdl.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`).
**Outgoing:**
- No runtime webhooks are declared in `src/GamePort/Program.cs` or `GamePort.csproj`. Development dependency downloads and source pushes are separate workflows (`scripts/bootstrap.sh`, `AGENTS.md`).
---
*Integration audit: 2026-11-12*
+91
View File
@@ -0,0 +1,91 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# Technology Stack
**Analysis Date:** 2026-11-12
## Languages
**Primary:**
- C# targeting `net10.0` for the shared executable and managed regression programs; no explicit `LangVersion` override is declared in `GamePort.csproj` or `tests/GamePort.DataTests/GamePort.DataTests.csproj`.
**Secondary:**
- Python 3 for local asset preparation, binary evidence tooling and unittest regressions in `tools/` and `tests/`; `docs/dependencies.md` records Python 3.12. These tools are not runtime requirements.
- Bash for local dependency setup, builds, tests and packaging in `scripts/`.
- GLSL vertex/fragment shaders compiled to SPIR-V in `src/GamePort/Rendering/Shaders/mesh.vert` and `src/GamePort/Rendering/Shaders/mesh.frag`.
- C for isolated original-component probes such as `tools/binary/actor_contact_probe.c`; do not treat probe code as the game runtime.
## Runtime
**Environment:**
- .NET 10 executable, with invariant globalization, nullable analysis, implicit usings and unsafe interop enabled in `GamePort.csproj`.
- SDK selection: `global.json` requests `10.0.100`, permits `latestFeature` roll-forward and disables prerelease SDKs. `scripts/bootstrap.sh` downloads SDK `10.0.402` with a pinned SHA-256.
- `docs/dependencies.md` records self-contained runtime pack `10.0.13`; verify generated publish metadata when establishing package provenance rather than equating SDK and runtime versions.
- Native Vulkan 1.3 minimum: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs` requests `Vk.Version13` and filters physical devices below it.
**Package Manager:**
- NuGet through the .NET SDK (`dotnet restore` in `scripts/bootstrap.sh`); no separately pinned NuGet client version.
- Lockfile present: `packages.lock.json`; `GamePort.csproj` enables `RestorePackagesWithLockFile`.
- Use `scripts/env.sh` to select the project-local SDK and `.nuget/packages` cache and disable .NET CLI telemetry.
## Frameworks
**Core:**
- Silk.NET.Vulkan, Silk.NET.Vulkan.Extensions.KHR and Silk.NET.Vulkan.Extensions.EXT `2.23.0` provide Vulkan bindings and extensions in `GamePort.csproj`.
- SDL3 `3.4.2` is provisioned by `scripts/bootstrap.sh`; window/input/Vulkan-surface and audio bindings are handwritten P/Invoke in `src/GamePort/Platform/Sdl.cs`.
- Game logic, binary formats, asset readers and UI are project C# modules under `src/GamePort/`; no general game engine is declared in `GamePort.csproj`.
**Testing:**
- Python standard-library `unittest`, invoked by `scripts/test.sh` against `tests/test_*.py` and the HUD checks.
- Standalone .NET 10 executable test projects, rather than a declared xUnit/NUnit dependency; `tests/GamePort.DataTests/GamePort.DataTests.csproj` links production source directly.
- `scripts/test.sh` also runs real Vulkan rendering checks and SDL dummy-audio checks; read `docs/compatibility.md` for recorded platform scope.
**Build/Dev:**
- MSBuild/.NET CLI solution and executable configuration: `GamePort.slnx`, `GamePort.csproj`, `global.json`.
- `glslangValidator` and `spirv-val` compile/validate Vulkan 1.3 shaders in `scripts/compile-shaders.sh`; distro package versions are not pinned there.
- CMake builds SDL locally in `scripts/bootstrap.sh`; curl, Python, and optional apt-get/dpkg-deb provision local dependencies without system installation.
- REA/Ghidra/JDK/Node are analysis-only tools selected by `scripts/rea.sh`; defaults reference Ghidra `12.1.4_PUBLIC` and a Java 21 JDK directory. Node and REA versions are not pinned in that launcher.
- Wine is an original-reference/preliminary compatibility tool, not a production dependency; `docs/dependencies.md` records Wine `11.0`.
## Key Dependencies
**Critical:**
- Silk.NET Vulkan/KHR/EXT `2.23.0`: native renderer access, swapchain/surface handling and validation messaging in `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`; direct pins in `GamePort.csproj`.
- SDL3 `3.4.2`: native window, input and audio backend, provisioned in `scripts/bootstrap.sh` and consumed through `src/GamePort/Platform/Sdl.cs` and `src/GamePort/Audio/SdlAudio.cs`.
- Host Vulkan loader and graphics ICD: required even for packaged self-contained builds; `scripts/package.sh` documents the Vulkan 1.3 prerequisite.
**Infrastructure:**
- Locked transitives in `packages.lock.json`: Silk.NET.Core `2.23.0`, Microsoft.DotNet.PlatformAbstractions `3.1.6`, Microsoft.Extensions.DependencyModel `9.0.9`.
- .NET built-ins supply numerics, compression, JSON and filesystem operations; examples are `src/GamePort/Game/RuntimeCheckpoint.cs`, `src/GamePort/Assets/PngImage.cs` and `src/GamePort/Assets/AssetPath.cs`.
- Local asset converters are project modules, such as `tools/extractors/prepare.py`, `tools/extractors/omt.py` and `tools/extractors/sound_bank.py`, not a hosted conversion service.
## Configuration
**Environment:**
- Runtime configuration uses CLI options in `src/GamePort/Program.cs`, including `--assets`, `--scene`, `--level`, `--load-save`, `--write-save`, dimensions, headless rendering and mute/debug switches.
- Native SDL lookup checks the executable directory, project-local native library directory and platform loader in `src/GamePort/Platform/Sdl.cs`.
- `scripts/env.sh` configures SDK/cache paths, optional native-tool paths, `LD_LIBRARY_PATH` and `VK_LAYER_PATH`; no runtime service credentials are required.
- Preserve originals and write prepared assets outside their root; `tools/extractors/prepare.py` rejects output inside the original installation.
**Build:**
- `GamePort.csproj` explicitly includes `src/GamePort/**/*.cs`, copies SPIR-V shaders and conditionally includes platform SDL binaries.
- `scripts/build-linux.sh` and `scripts/build-windows.sh` self-contained publish to `dist/linux-x64` and `dist/win-x64` and require the corresponding SDL library.
- `scripts/package.sh` assembles local assets/scenes/audio, runtime libraries, licenses, documentation and source provenance into both packages; generated packages are not source-control upload artifacts (`AGENTS.md`).
## Platform Requirements
**Development:**
- .NET 10 SDK; Python 3 for preparation/regressions; Vulkan-capable driver/loader and SDL backend dependencies for native checks (`README.md`, `scripts/test.sh`).
- Linux bootstrap additionally uses CMake and native build tooling for SDL and optional Ubuntu package extraction for shader/X11/audio/validation tools (`scripts/bootstrap.sh`).
- Read-only evidence work uses separate generated targets and local analysis tools (`tools/binary/rea_decompile_batch.py`, `scripts/rea.sh`); never execute or modify originals in place (`AGENTS.md`).
**Production:**
- Shared `linux-x64` and `win-x64` source implementation, with self-contained .NET and native SDL packaging declared in `GamePort.csproj` and `scripts/package.sh`.
- Native Linux and Windows 10/11 x64 are required by `../prompt.MD`; host Vulkan 1.3+ driver/loader remains necessary.
- Offline operation is intentional (`AGENTS.md`). Native Linux scene evidence, Windows cross-publish, Wine runs and native Windows gameplay are separate claims; `docs/progress.md` and `docs/compatibility.md` retain bounded verification and outstanding broader/native Windows comparisons.
---
*Stack analysis: 2026-11-12*
+195
View File
@@ -0,0 +1,195 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# Codebase Structure
**Analysis Date:** 2026-11-12
## Directory Layout
```text
GamePort/
├── GamePort.csproj / GamePort.slnx # Single runtime executable and solution
├── global.json / NuGet.Config # SDK/package configuration
├── src/GamePort/
│ ├── Program.cs # Composition, CLI, scheduling and transitions
│ ├── Application/ # Presentation session, visuals, UI, debug and fixtures
│ ├── Assets/ # Original/prepared readers and CPU resources
│ ├── Audio/ # Scene mixer policy and owned SDL streams
│ ├── Game/ # Simulation, scripts, progression, recovered kernels
│ ├── Platform/ # SDL3 native interop
│ └── Rendering/
│ ├── Vulkan/ # GPU backend
│ └── Shaders/ # GLSL and committed SPIR-V
├── tests/ # Python evidence/parser tests and C# executables
├── tools/
│ ├── binary/ # Static evidence extractors and component probes
│ ├── extractors/ # Archive/model/audio/UI preparation
│ ├── levels/ # GAM forensic parser
│ └── recon/ # Inventory and reference observation tools
├── scripts/ # Local dependency/build/test/package scripts
├── docs/
│ ├── analysis/ # Format, binary, graphics and gameplay findings
│ ├── checkpoint/ # Reconstruction gates, ledgers and continuation plan
│ ├── gameplay/ # Focused source contracts and live implementation evidence
│ └── reviews/ # Reference project reviews
└── .planning/codebase/ # GSD codebase maps
```
`../Original/` is a separate immutable evidence tree, not a source directory. The sibling JN-Engine reference is discussed in `docs/reviews/jn-engine-survey.md`; it is not linked into the runtime. Workspace `.git` is reserved; GamePort has the actual project repository (`AGENTS.md`).
## Directory Purposes
**`src/GamePort/Application/`:**
- Purpose: Translate game state into scene meshes, camera views, HUD/debug interfaces and native presentation lifetime.
- Contains: `*Visuals.cs`, overlays, preview helpers, explicit `*Smoke.cs` fixture drivers.
- Key files: `src/GamePort/Application/RenderSession.cs`, `src/GamePort/Application/SceneActorVisuals.cs`, `src/GamePort/Application/SceneHud.cs`, `src/GamePort/Application/UiViewport.cs`.
- Keep Vulkan device ownership in `RenderSession`/backend and expose mutable CPU scene data to visual adapters.
**`src/GamePort/Game/`:**
- Purpose: Stateful gameplay and focused recovered mathematical/source contracts.
- Contains: Player simulation, script director, tasks/inventory, collision, gadget/vehicle systems and route checkpoints. These are currently flat files, not speculative Entities/Physics/AI subtrees.
- Key files: `src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/PlayerSceneBinding.cs`, `src/GamePort/Game/SceneDirector.cs`, `src/GamePort/Game/SceneInteractions.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`.
- Keep source arithmetic in small named modules such as `src/GamePort/Game/JimmyGroundMotion.cs` and `src/GamePort/Game/JimmyOrientation.cs`.
**`src/GamePort/Assets/`:**
- Purpose: Bounded decoding and CPU representation; no native device lifetime.
- Contains: GAM/TSK, ASE/PNG, prepared JSON/buffers, morphs and portable lookup.
- Key files: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/OriginalSave.cs`, `src/GamePort/Assets/Mesh.cs`, `src/GamePort/Assets/PreparedEntityResources.cs`, `src/GamePort/Assets/AssetPath.cs`.
**`src/GamePort/Rendering/`, `src/GamePort/Platform/`, `src/GamePort/Audio/`:**
- Purpose: Native rendering, platform and audio boundaries.
- Contains: One Vulkan backend, shaders, SDL3 imports and independent WAV streams.
- Key files: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`, `src/GamePort/Rendering/Shaders/mesh.vert`, `src/GamePort/Rendering/Shaders/mesh.frag`, `src/GamePort/Platform/Sdl.cs`, `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Audio/SdlAudio.cs`.
**`tools/extractors/` and `tools/levels/`:**
- Purpose: Read-only source data interpretation and generated resource production.
- Contains: OMT, ASE, PNG, entity/model/UI/audio and gadget-specific extractors; lossless GAM reference parsing.
- Key files: `tools/extractors/prepare.py`, `tools/extractors/omt.py`, `tools/extractors/ase.py`, `tools/extractors/entities.py`, `tools/extractors/models.py`, `tools/levels/gam.py`.
- Route new resource preparation through `tools/extractors/prepare.py` so local package preparation uses the same path.
**`tools/binary/` and `tools/recon/`:**
- Purpose: Preserve reproducible source-contract evidence and original/reference observation tooling.
- Contains: Python instruction/structure guards, C copied-component probes, inventory and observation utilities.
- Key files: `tools/binary/physical_registration.py`, `tools/binary/dynamic_reclip.py`, `tools/binary/actor_contact.py`, `tools/recon/inventory.py`, `tools/recon/reference_capture.py`.
- These tools are research/test infrastructure, not executable game dependencies (`GamePort.csproj`).
**`docs/`:**
- Purpose: Evidence, confidence boundaries, implementation status and continuation instructions.
- Contains: `docs/analysis/`, `docs/gameplay/`, `docs/checkpoint/`, `docs/reviews/` and root status documents.
- Key files: `docs/progress.md`, `docs/tasks.md`, `docs/decisions.md`, `docs/compatibility.md`, `docs/architecture.md`, `docs/checkpoint/coverage.md`, `docs/checkpoint/next-work-plan.md`.
- Keep addresses/offsets, recovered versus inferred behavior and actual validation scope in the relevant report.
## Key File Locations
**Entry Points:**
- `src/GamePort/Program.cs`: Runtime CLI, scene composition, input loop, transitions and fixture invocation.
- `tools/extractors/prepare.py`: Original-to-prepared-assets pipeline.
- `tools/recon/inventory.py`: Original file inventory/hash verification.
- `scripts/test.sh`: Local consolidated regression/GPU checks.
- `scripts/package.sh`: Local self-contained package assembly and launchers.
**Configuration:**
- `GamePort.csproj`: net10.0, Linux/Windows x64, explicit production source glob, Silk.NET references and shader/native content.
- `GamePort.slnx`: Solution entry.
- `global.json`: SDK selection.
- `NuGet.Config`, `packages.lock.json`: Package configuration and dependency lock.
- `scripts/env.sh`: Local toolchain environment setup.
- `.gitignore`: Generated output/cache exclusions.
- `AGENTS.md`: Movement priority, recovery gates, platform requirements and coordination.
**Core Logic:**
- `src/GamePort/Game/LabSimulation.cs`: Player state and body/input/wrapper/apply/effect phase order.
- `src/GamePort/Game/PlayerSceneBinding.cs`: Director/actor/player control and preparation bridge; vehicle sequencing.
- `src/GamePort/Game/PlayerLevelState.cs`: Explicit retained route scalars outside TSK.
- `src/GamePort/Game/SceneDirector.cs`: Authored script/camera chains and live actor state.
- `src/GamePort/Game/RuntimeCheckpoint.cs`: Departure/RETURN context.
- `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`: Bounded source static/body path.
- `src/GamePort/Game/SceneCollision.cs`: Capsule compatibility geometry.
- `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`: Isolated recovered components, not live scene admission.
- `src/GamePort/Application/RenderSession.cs`: Persistent application-owned SDL/Vulkan lifetime.
**Testing:**
- `tests/test_extractors.py`, `tests/test_levels.py`, `tests/test_models.py`: Python format/preparation coverage.
- `tests/test_checkpoint_*.py`, `tests/test_jimmy_*.py`: Source-contract and lifecycle evidence guards.
- `tests/GamePort.DirectorTests/Program.cs`: Script/control regressions.
- `tests/GamePort.BodyOwnershipTests/Program.cs`: Body/control ownership checks.
- `tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.JimmyAirTests/Program.cs`: Focused managed movement comparisons.
- `tests/GamePort.PairLifecycleTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`: Isolated component fixtures.
- `src/GamePort/Application/CutsceneIdleSmoke.cs`, `src/GamePort/Application/WindowTransitionSmoke.cs`: Native runtime fixture drivers, distinct from isolated numeric tests.
## Naming Conventions
**Files:**
- Use PascalCase C# files matching primary types: `src/GamePort/Game/JimmyAirMotion.cs`.
- Use feature-specific suffixes for roles: `src/GamePort/Application/ScooterVisuals.cs`, `src/GamePort/Game/ScooterMotion.cs`, `src/GamePort/Application/ScooterSmoke.cs`.
- Prefix recovered source contracts with `Original` where established: `src/GamePort/Game/OriginalNormalContacts.cs`; the prefix does not assert live integration.
- Use snake_case Python modules and tests: `tools/binary/dynamic_reclip.py`, `tests/test_dynamic_reclip.py`.
- Use kebab-case documentation topics: `docs/checkpoint/actor-normal-contacts.md`.
**Directories:**
- Keep runtime namespaces grouped by concrete responsibility under `src/GamePort/`.
- Use `tests/GamePort.<Subject>Tests/` for executable managed test projects with `Program.cs` and matching `.csproj`.
- Keep root Python tests under `tests/` and reusable retained references under `tests/fixtures/` or focused project folders.
- Keep evidence-oriented reports in `docs/checkpoint/`, source/live feature reports in `docs/gameplay/`.
## Where to Add New Code
**New Feature:**
- Primary code: `src/GamePort/Game/`; coordinate explicit composition and supported scene gates in `src/GamePort/Program.cs`.
- Presentation: Add a focused adapter under `src/GamePort/Application/`; use `src/GamePort/Application/UiViewport.cs` for UI sizing/pointers.
- Tests: Add focused `tests/GamePort.<Subject>Tests/` numeric/state comparisons and source-evidence guards in `tests/test_<subject>.py` where appropriate.
- Evidence/status: Use `docs/gameplay/` or `docs/checkpoint/` and update `docs/progress.md`/`docs/tasks.md` when authorized gameplay work changes state.
- Preserve the current Jimmy stabilization priority and lab/outside capsule versus bounded source-body distinction (`AGENTS.md`, `src/GamePort/Program.cs`).
**New Component/Module:**
- Recovered arithmetic: `src/GamePort/Game/`, with explicit input/output state as in `src/GamePort/Game/JimmyGroundMotion.cs`.
- Script preparation/control bridge: `src/GamePort/Game/PlayerSceneBinding.cs` and `src/GamePort/Game/SceneDirector.cs`; retain fresh/retained ordering.
- New binary format reader: `src/GamePort/Assets/`; forensic/extraction counterpart in `tools/extractors/` or `tools/levels/`.
- New visual: `src/GamePort/Application/`; extend backend only when required by source rendering behavior (`src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`).
- New native interop: `src/GamePort/Platform/Sdl.cs`; keep allocation/release in the owning subsystem.
- New audio policy: `src/GamePort/Audio/SceneAudio.cs`; SDL stream mechanics belong in `src/GamePort/Audio/SdlAudio.cs`.
- New recovered collision callback: Focused `src/GamePort/Game/` component plus fixture first; do not wire `OriginalPairCollision` or `OriginalNormalContacts` into runtime without activation/order/derived-response evidence (`docs/checkpoint/next-work-plan.md`).
**Utilities:**
- Asset path handling: `src/GamePort/Assets/AssetPath.cs`; preserve case-insensitive lookup and root containment.
- Offline source guards/probes: `tools/binary/`; use documented REA evidence for original-binary investigation (`AGENTS.md`).
- Shared extraction helpers: `tools/extractors/` next to the owning format; connect to `tools/extractors/prepare.py`.
- Build/package operations: `scripts/`; use local output and existing Linux/Windows entry scripts.
## Special Directories
**`artifacts/`:**
- Purpose: Prepared resources, generated evidence and local fixture output; default preparation root is `artifacts/extracted/` (`tools/extractors/prepare.py`).
- Generated: Yes.
- Committed: No (`.gitignore`).
**`dist/`, `bin/`, `obj/`:**
- Purpose: Local self-contained packages and .NET build output (`scripts/package.sh`, `GamePort.csproj`).
- Generated: Yes.
- Committed: No (`.gitignore`).
**`.tools/`, `.nuget/`, `.dotnet-home/`:**
- Purpose: Local toolchain, native dependencies and caches (`scripts/env.sh`, `GamePort.csproj`).
- Generated: Yes/local provisioned.
- Committed: No (`.gitignore`).
**`src/GamePort/Rendering/Shaders/`:**
- Purpose: Source GLSL and packaged SPIR-V, compiled by `scripts/compile-shaders.sh`.
- Generated: `.spv` files are generated; `.vert`/`.frag` are source.
- Committed: Yes; `GamePort.csproj` copies SPIR-V to executable output.
**`../Original/`:**
- Purpose: Immutable evidence and runtime asset source (`AGENTS.md`, `tools/recon/inventory.py`).
- Generated: No.
- Committed: Outside this repository; never modify or execute in place.
**`.planning/codebase/`:**
- Purpose: Generated analysis maps for planning; current files are distinct from persistent authored `docs/architecture.md`.
- Generated: Yes, from tracked source/config/documentation inspection.
- Committed: Controlled by the mapping orchestrator; not excluded by `.gitignore`.
---
*Structure analysis: 2026-11-12*
+171
View File
@@ -0,0 +1,171 @@
---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# Testing Patterns
**Analysis Date:** 2026-11-12
## Test Framework
**Runner:**
- Python standard-library `unittest`; no pinned Python test framework package is detected (`tests/test_extractors.py`, `scripts/test.sh`).
- Standalone C# `net10.0` console applications, invoked using `dotnet run`, rather than xUnit/NUnit/MSTest (`tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`, `scripts/test.sh`).
- The comprehensive local sequence is `scripts/test.sh`; it sources `scripts/env.sh`, prepares assets and runs managed, Python, rendering, audio and hash checks.
**Assertion Library:**
- `unittest.TestCase` assertions and context managers (`tests/test_extractors.py`).
- C# local `Check`/`Near` functions or recursive JSON comparisons that throw exceptions (`tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`).
**Run Commands:**
Run from the GamePort repository root; these are recorded commands, not checks executed by this mapping.
```bash
source scripts/env.sh
python3 -m unittest discover -s tests -p 'test_*.py' -v
scripts/test.sh
dotnet run --project tests/GamePort.ActorContactTests
dotnet run --project tests/GamePort.JimmyGroundTests
dotnet run --project tests/GamePort.DataTests -- ../Original
python3 tests/GamePort.HudTests/test_ui.py
SDL_AUDIODRIVER=dummy dotnet run --project tests/GamePort.AudioPauseTests
NEUTRON_WINDOW_TEST=1 scripts/test.sh
scripts/test-window-transitions.sh
```
- No dedicated watch or coverage command is detected in `scripts/test.sh` or the inspected test projects. `scripts/test-window-transitions.sh` requires a prior build plus local Xvfb/Xfwm/session tools.
## Test File Organization
**Location:**
- Separate `tests/` directory; Python discovery sees root `test_*.py`, while HUD Python tests are invoked explicitly (`scripts/test.sh`).
- Each managed group has a project directory, `Program.cs` and optional JSON references (`tests/GamePort.ActorContactTests/`, `tests/GamePort.JimmyGroundTests/`).
**Naming:**
- `tests/test_<domain>.py`, `tests/GamePort.<Domain>Tests/Program.cs`, and descriptive `original-*-reference.json` or `expected.json` fixtures (`tests/test_actor_contact.py`, `tests/GamePort.DirectorTests/original-camera-rotation-reference.json`).
**Structure:**
```text
tests/
test_extractors.py
test_actor_contact.py
GamePort.ActorContactTests/
GamePort.ActorContactTests.csproj
Program.cs
expected.json
GamePort.JimmyGroundTests/
Program.cs
original-ground-reference.json
```
## Test Structure
**Suite Organization:**
Use deterministic inputs and assertions with descriptive failures. Actual Python pattern from `tests/test_extractors.py`:
```python
class BoundedReaders(unittest.TestCase):
def test_read_bounds_and_negative_size(self):
for size in (-1, 2):
with self.assertRaises(FormatError): Reader(b'x').take(size)
```
Actual C# comparison helper from `tests/GamePort.JimmyGroundTests/Program.cs`:
```csharp
static void Check(bool condition,string name)
{ if(!condition)throw new Exception(name); }
static void Near(float value,float expected,string name) =>
Check(float.IsFinite(value)&&Math.Abs(value-expected)<.02f,
$"{name}: {value} != {expected}");
```
**Patterns:**
- Top-level managed programs load JSON using `AppContext.BaseDirectory`, enumerate cases, compare every relevant field, check case counts and print `PASS` (`tests/GamePort.JimmyGroundTests/Program.cs`).
- Test projects copy saved fixtures into output and compile production files directly with explicit globs (`tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`).
- Some fixture filenames are output links rather than colocated tracked files: `tests/GamePort.JimmyGroundTests/GamePort.JimmyGroundTests.csproj` links `tools/binary/jimmy_landing_rotation_reference.json` as `original-landing-rotation-reference.json`. Check source availability when reproducing a suite.
- Use `TemporaryDirectory` for exports and symlink rejection fixtures; local-original integration cases can use `skipUnless(ORIGINAL.exists())` (`tests/test_extractors.py`, `tests/test_actor_contact.py`). Do not assume every original-dependent suite has a skip guard.
## Mocking
**Framework:** No general mocking library is detected in the inspected projects. Use explicit fixtures, interfaces and callbacks (`tests/GamePort.ActorContactTests/Program.cs`).
**Patterns:**
The actor-contact fixture implements `IOriginalNormalBody`, logs each accessor and deliberately changes state on a later read (`tests/GamePort.ActorContactTests/Program.cs`):
```csharp
public Vector4 ReadVelocity()
{
events.Add("Gv"); velocityGets++;
if(FreshY && velocityGets == 2) Velocity.Y = 99;
return Velocity;
}
```
**What to Mock:**
- Synthetic actor state, bounded callback endpoints, geometry and controlled getter mutations isolate original component behavior (`tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/actor-normal-contacts.md`).
- Dummy SDL audio drivers isolate lifecycle/consumption checks; they do not establish audible output (`scripts/test.sh`, `docs/compatibility.md`).
**What NOT to Mock:**
- Preserve real parser byte boundaries, production algorithms, archive identities and saved original observations; compare through the production implementation (`tests/test_extractors.py`, `tests/GamePort.ActorContactTests/Program.cs`).
- Do not replace live GPU validation with a managed-only assertion; real headless Vulkan paths write readbacks (`scripts/test.sh`, `src/GamePort/Program.cs`).
## Fixtures and Factories
**Test Data:**
- Build minimal byte fixtures with explicit endian packing, e.g. the RGB555 canvas case in `tests/test_extractors.py` uses `struct.pack('>H', len(row))` and a synthetic `OmCv`/`OmGW` header.
- Use `Fixture.Reset(kind)` to seed reproducible body state and clear event logs before each named observation (`tests/GamePort.ActorContactTests/Program.cs`).
- Preserve source-executed references rather than deriving all expectations from the port. `tests/GamePort.ActorContactTests/expected.json` contains complete saved observations; `--native <observations.json>` permits a fresh external observation comparison and `--dump` emits port states (`tests/GamePort.ActorContactTests/Program.cs`).
**Location:**
- Saved component references live beside managed projects (`tests/GamePort.DynamicReclipTests/expected.json`, `tests/GamePort.GrapplerTests/original-query-reference.json`).
- Original integration fixtures are external local `../Original`; never modify them (`AGENTS.md`, `tests/test_extractors.py`). Generated extraction/replay outputs belong under ignored `artifacts/`, as specified by `scripts/test.sh`; this map does not inspect those outputs.
- Binary tools validate complete original bodies, relocation operands, table bindings and generated-probe output separation (`tests/test_actor_contact.py`, `tools/binary/actor_contact.py`).
## Coverage
**Requirements:**
- No enforced percentage threshold or coverage collector is detected in `scripts/test.sh` or `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`.
- Use behavioral coverage: malformed lengths/counts/trailing bytes, coordinate/winding/UV identities, positive recovered behavior, explicit unsupported contracts, case completeness and callback read order (`tests/test_extractors.py`, `tests/GamePort.ActorContactTests/Program.cs`).
- `docs/progress.md` and `docs/compatibility.md` record 352 Python checks for the documented source checkpoint identified as `bdca29d` by the mapping task. This is an existing receipt, not a fresh run or independently recounted total.
- The same records distinguish integrated SDL/GPU evidence at `bf876e9` and unchanged packages at `924ad2f`. Do not attach the newest component counts to an older package or imply the latest component work reran graphics.
**View Coverage:** Not detected. Consult `docs/compatibility.md` and subsystem reports for evidence scope rather than treating test count as gameplay completeness.
## Test Types
**Unit Tests:**
- Bounded readers, PackBits/PNG operations, numerical movement/orientation, task transitions, UI and standalone collision components (`tests/test_extractors.py`, `tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`).
- Explicit unsupported-path checks require exceptions instead of silent admission; zero-horizontal reflection is rejected in `tests/GamePort.ActorContactTests/Program.cs`.
**Integration Tests:**
- Decode actual local archives and compare counts, models, materials, textures and exported references (`tests/test_extractors.py`, `tests/GamePort.DataTests/Program.cs`).
- `scripts/test.sh` prepares scenes/audio, verifies assets, runs save/load checks, SDL dummy audio lifecycle checks, Vulkan renders and original manifest verification.
- Differential component probes execute copied original instructions with synthetic state under Wine32, then compare port snapshots; complete-body/operand guards and provenance are described in `docs/checkpoint/actor-normal-contacts.md`. This is stronger than a port self-comparison but remains a bounded component experiment.
**E2E Tests:**
- Port smoke flows cover story/practice/RETURN routes, cutscenes, gadgets, input, windows and real GPU readbacks (`scripts/test.sh`, `src/GamePort/Application/WindowTransitionSmoke.cs`).
- Optional window checks are gated by `NEUTRON_WINDOW_TEST=1`; `scripts/test-window-transitions.sh` creates a private Xvfb session with Xfwm to support asynchronous fullscreen requests.
- Whole-original gameplay equivalence and native Windows runtime are separate open evidence gates (`docs/compatibility.md`). Windows cross-publishing is compiler/package evidence; Wine execution is preliminary compatibility evidence.
## Common Patterns
**Async Testing:**
- No general async test runner pattern is detected in the inspected console/Python suites. SDL/window progression is exercised through frame-driven smoke state and real window-manager acknowledgements (`src/GamePort/Application/WindowTransitionSmoke.cs`, `scripts/test-window-transitions.sh`).
**Error Testing:**
- Python uses `assertRaises` / `assertRaisesRegex`, including rejection of original-directory and symlink output (`tests/test_extractors.py`, `tests/test_actor_contact.py`).
- Managed tests call unsupported paths inside `try`, throw if accepted, and catch only the expected `NotSupportedException` (`tests/GamePort.ActorContactTests/Program.cs`).
**Numerical comparisons:**
- Use tolerances appropriate to the specific observed contract: `.02f` and finite checks for ground motion; decimal-place comparisons for exported ASE positions/UVs (`tests/GamePort.JimmyGroundTests/Program.cs`, `tests/test_extractors.py`).
- Actor-contact snapshots compare JSON field shapes, array counts, event order and `GetSingle()` values exactly; do not weaken exact float32 checks by borrowing another suite's tolerance (`tests/GamePort.ActorContactTests/Program.cs`).
- Preserve source float-store boundaries rather than declaring all double intermediates a universal x87 equivalent (`docs/checkpoint/dynamic-reclip.md`).
**Verification reporting:**
- State separately: compiler success, managed/Python assertions, copied-original component execution, port rendering/native SDL input, package provenance, whole-original comparison, and native Windows gameplay (`AGENTS.md`, `docs/progress.md`, `docs/compatibility.md`).
- No builds or tests are executed for this mapping; commands and evidence above describe the checked-in source and documented receipts.
---
*Testing analysis: 2026-11-12*
+72
View File
@@ -0,0 +1,72 @@
{
"model_profile": "inherit",
"commit_docs": true,
"parallelization": true,
"search_gitignored": false,
"brave_search": false,
"firecrawl": false,
"exa_search": false,
"tavily_search": false,
"ref_search": false,
"perplexity": false,
"jina": false,
"git": {
"branching_strategy": "none",
"create_tag": true,
"repo_tagging": "single",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}",
"quick_branch_template": null,
"allow_default_branch_commits": true
},
"workflow": {
"research": true,
"plan_check": true,
"verifier": true,
"nyquist_validation": true,
"auto_advance": false,
"node_repair": true,
"node_repair_budget": 2,
"ui_phase": true,
"ui_safety_gate": true,
"ai_integration_phase": true,
"api_coverage_gate": true,
"human_verify_mode": "end-of-phase",
"context_guard_mode": "warn",
"text_mode": false,
"compact_content": false,
"research_before_questions": false,
"discuss_mode": "discuss",
"skip_discuss": false,
"code_review": true,
"code_review_depth": "standard",
"code_review_command": null,
"pattern_mapper": true,
"plan_bounce": false,
"plan_bounce_script": null,
"plan_bounce_passes": 2,
"auto_prune_state": false,
"post_planning_gaps": true,
"security_enforcement": true,
"security_asvs_level": 1,
"security_block_on": "high",
"_auto_chain_active": false
},
"ship": {
"pr_body_sections": []
},
"hooks": {
"context_warnings": true
},
"project_code": null,
"phase_naming": "sequential",
"agent_skills": {},
"claude_md_path": "./.claude/CLAUDE.md",
"plan_review": {
"source_grounding": true,
"source_grounding_authority": "grep"
},
"resolve_model_ids": "omit",
"mode": "yolo",
"granularity": "standard"
}
+24
View File
@@ -0,0 +1,24 @@
# Onboarding Summary
## Project State
- PROJECT.md: present
- REQUIREMENTS.md: present
- ROADMAP.md: present
- STATE.md: present
## Codebase Context
- Brownfield repo: yes
- Map readiness: complete
- Codebase map: `.planning/codebase/` (complete codebase map)
- Fast map available: yes
## Docs Context
- Existing ADR/PRD/SPEC/RFC candidates detected by onboarding: 0
- Authoritative scope: [prompt.MD](../../../prompt.MD); see [PROJECT.md](../PROJECT.md) for specification and evidence pointers.
- Existing evidence reviewed in `.planning/research/`; prior runtime receipts remain bounded.
## Recommended Next Step
- `$gsd-manager` for project navigation.
- `$gsd-discuss-phase 1` to clarify Reproducible Fidelity Baseline, or `$gsd-plan-phase 1` to plan directly.
Initialization covers 8 playable-slice phases and 33 requirements. No reconstruction phase has executed under this roadmap.
@@ -0,0 +1,35 @@
<!-- CONSUMED: final verification completed human_needed on2026-11-14. Current next action: $gsd-verify-work 1 and combined actual human session; historical interrupted-verifier notes below are superseded. -->
---
context: phase
phase: 01-reproducible-fidelity-baseline
plan: "07"
task: 3
total_tasks: 3
status: consumed
last_updated: "2026-11-13T22:26:46.798618+00:00"
---
# Final verification quota checkpoint
Quota guard explicitly requested pause at15%. Resume completed task01-07-03 and recovered fullsuite exit0 (782.049626s), then reviewed/fixed allfive source-integrity findings. Do NOT redo implementation or tests. Source commits through02d182f, review/coverage/security documentation71366e7. Fullsuite556Python/180fidelity,27Node,23observer,2HUD,51managedentrypoints,36GPUrenderedreceipts,zeroVulkanvalidationerrors,SDLdummychecks,539originalhashes. Latertooling-onlyfixes: all191fidelityregressions PASS43.355s; focused26scenario,23capture,29acceptance,27Node,18LinuxhostedPowerShell. All539originals unchanged. No runtime changes afterfullsuite; no need13minGPUrerun forcurrentPython/collector fixes.
Historicalreview5915128: CR01selected-vs-reviewedpath,CR02originalinventory/executablebinding,CR03copy-stateidentity,WR01viewerledgerprojection,WR02interruptedWindowsfinalization. Fixes5569bc2,bda35e5,6e5ee0b,548c97a,2608517,a821754. Independentre-reviewcaughtremaininghash-onlycopy-statebypass; RED48fca0d/GREEN02d182f requiresactual_checked_artifactwithrootinside_scenario_observation; callersupdated. Finalindependentre-reviewallfiveFIXED in01-REVIEW-VERIFY.md; dispositionopen0. Securityauditorfinal22/22mitigated, threats_open0 in01-SECURITY.md. Nyquistautomationcoveragevalidatedall15taskbindings; manualacceptanceopen;191fidelityaggregate43.355sec exceeds30secquicktargethonestly. UIreviewdisabledconfigfalse. No remainingknowncode/securityblockers.
Currentfreshfinalbundle dist/fidelity/phase01 has11001immutableentries. Currenthashes/readinessreceipt artifacts/fidelity/verification/01-07-final-checkpoint.json. readyexit0true,strictauditexit1 errors[] accepted0/120,10humanpending; logs artifacts/fidelity/01-review-fixes/readiness-final.json,acceptance-final.json,python-fidelity-final.log. Oldbundlespreserved phase01-pre-review-48100025 andphase01-pre-copy-artifact-7ceebcb3. ActualLinuxfailedpreflightimportedcurrentbundle/results/imported. Runtimepackage source446930d dirty/diff90cef956 unchanged; source/docscommitsmustnotrelabelitsidentity. Original/nativeWindows+DxWnd andphysicalLinuxvisible/audible/browserreviewremainonecombinedhuman session pending. Humanonlycollects/observes/returns; agent-ownedexactnormalizationmapping incheckpoint-session.md. No capture request issued yet because finalphaseverification/handoffpending.
Final typed verifier phase01_final_verification was dispatched at21%; quota15% interrupted it, instructedfinishonlyboundedhuman_neededreport/fingerprint thenreturn. It had readall7musthaves/summaries, checked25capabilities/33requirements/0unmapped/6groups/33rows,16/16decisioncoverage,40sourcefilesnoskip/debtscan. A mandatoryMVPgoalformatguard exposed existingROADMAPMode:mvp plainproseGoal. Rootauthorizedformat-only identicalintentuserstory and modifiedROADMAP.md uncommitted: As a tester, I want to reproduce identified original/port comparison scenarios, so that I understand exactly what the current reconstruction proves on each native platform. Validatorvalidtrue; no scope/successcriteriamodified. OneverifiercommandusedwrongunittestclassFidelityAcceptance (loadererror,correctclassAcceptanceTests); twoothernamedbehaviorcheckspassed; don'tmislabelthatcommandassuccess. Priorfulltargeted29passestablishactualcoverage.
NEXT: Reconcile currentverifier's 01-VERIFICATION.md and CLI verification.status; ifreport/fingerprintabsentfinishthat ONLY beforeanynewphase. FingerprintmustbeownerCLIgenerated, notmanual. Oncehuman_neededstatusvalid, persistUATfromnamedhumanitems, updateSTATE/consumedhandoffs, commitverifiedreport+goalmetadata+handoffdocs andpush verifiedsource/tooling toauthorizedGitea/main. Lastpushedhead remainsd18f551; later01-07/task3/reviewfix/auditcommits arelocalawaitingfinalverification. Preserveunrelatedtools.yaml. Do notadvancephase2orclaimPhase1accepted; allEVIDIDsPending0/120humanacceptance. No source changesuncommittedexceptROADMAPformatandpossiblynewverifierreport.
Nativeagents/sourcewritesallfinishedexceptverifierreportbeingclosed. Quota watcher runs and actual15%steeringworks. Noauto-resume; usermust $gsd-resume-workafterreset. Don'tspendquota rereadingmassiveGSDscriptbodies orrerunningfinished13minfullsuite. Existinglocalpackages/media/originalcopiesstaylocal, noCI/uploads. MaintracksGitea/main, scoped.gitwriteescalation; retainhistoricalhandoffsmarkconsumedratherthandelete (priorautomaticreviewrejecteddeletion).
## Required Reading
AGENTS.md,parentinstructions,HANDOFF.json,01-07SUMMARY,01-REVIEW-VERIFY,01-SECURITY,01-VALIDATION,and01-VERIFICATIONifpresent.
## Critical Anti-Patterns
| Pattern | Description | Severity | Prevention Mechanism |
|---|---|---|---|
| Redo completed tests | Fullsuiteand191fidelitychecksfinished | advisory | Reconcile savedlogs first; rerunonlyafternewchanges |
| False phase completion | Preparedmaterialsfailactualstrictacceptance0/120 | advisory | KeepEVIDPending andhuman_needed; owner verification.status beforeadvance |
## Infrastructure State
Testsfinished; verifierinterruptedatpause; reportreconciliationpending; localquota watcher running. No sourceworkeractive.
## Next Action
Inspect01-VERIFICATION.md and owner verification.status; finish report/fingerprint/UAT ifneeded, commit/pushverified01-07reviewedwork; neverredo task3/fulltests orautoapprovehumanacceptance.
@@ -0,0 +1,126 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "01"
type: execute
wave: 1
depends_on: []
files_modified:
- tools/recon/fidelity.py
- tools/recon/fidelity_receipts.py
- tests/test_fidelity_sessions.py
- docs/evidence/scenarios.json
- tests/test_fidelity_scenarios.py
autonomous: true
requirements: [EVID-01, EVID-02, EVID-04]
estimate:
tokens: 34000
raw_tokens: 34000
tasks: 2
confidence: low
must_haves:
truths:
- "A reviewer can stage and identify a pristine generated original installation without altering any original byte (EVID-01, D-15)."
- "The protocol requires continuous lab → VR04 → lab → outside and focused dialogue-return, left/right banked-jump, landing and idle captures per D-01 and D-04."
- "Natural/skipped dialogue and fresh/retained entry are equally required, independently identified dimensions per D-02 and D-03."
- "Equal, nested, symlink-aliased and Windows case-aliased source/output paths fail before any staging write; sibling paths merely sharing a textual prefix remain distinct."
- "Empty/missing inventories fail; single-file fixtures round-trip, while changed, missing and added files invalidate identity."
- "Manifest order is canonical relative POSIX path order; case-colliding identities fail instead of acquiring filesystem-dependent order."
- "Interrupted staging/import leaves an explicit incomplete diagnostic and no completed receipt; simultaneous same-session allocation has one winner, and duplicate receipt imports are idempotent only for byte-identical content."
- "Typed receipt validation retains failures and missing evidence as open acceptance; D-13 Windows availability is not a runtime receipt."
artifacts:
- path: tools/recon/fidelity.py
provides: "Local stage, identify, import and validate CLI"
- path: tools/recon/fidelity_receipts.py
provides: "Versioned receipt, identity, containment and atomic publication contract"
- path: docs/evidence/scenarios.json
provides: "Required baseline matrix and observed-event protocol"
key_links:
- from: tools/recon/fidelity.py
to: tools/recon/inventory.py
via: "Recorded original inventory checked before staging and after collection"
- from: tools/recon/fidelity_receipts.py
to: docs/evidence/scenarios.json
via: "Stable case IDs and completeness rules"
prohibitions:
- statement: "MUST NOT sacrifice authoritative original bytes or execute the authoritative installation to make reference collection convenient."
status: unresolved
reason: "Spec-less recall: preservation is a project value; descriptor-less and flagged-unverified for review."
---
<objective>
**As a** tester, **I want to** reproduce identified original and port comparison scenarios and inspect their evidence, **so that** I can understand exactly what the current reconstruction proves on each native platform.
Roadmap-derived framing supplied by the orchestrator. Prove the local evidence workflow from immutable inventory through generated copy, actual package identity, imported bounded evidence and a readable receipt. Establish the complete scenario contract before parallel consumers begin.
Artifacts this phase produces in this plan: fidelity.py CLI subcommands stage, identify, import and validate; fidelity_receipts.py functions stage_original, identify_tree, validate_receipt and import_receipt; schema_version 1 local JSON contracts; tests/test_fidelity_sessions.py; docs/evidence/scenarios.json; tests/test_fidelity_scenarios.py. Generated session/receipt/manifest outputs belong in artifacts/fidelity/ and remain ignored. These are new tooling interfaces, not recovered game interfaces.
</objective>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@.planning/PROJECT.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-RESEARCH.md
@.planning/phases/01-reproducible-fidelity-baseline/01-PATTERNS.md
@.planning/phases/01-reproducible-fidelity-baseline/SKELETON.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-01-01">
<name>Stage one preserved session and review one honestly classified receipt end to end</name>
<reversibility rating="costly">Versioned local records are shared by later tools; retaining raw inputs and explicit schema versions keeps migration bounded.</reversibility>
<files>tools/recon/fidelity.py, tools/recon/fidelity_receipts.py, tests/test_fidelity_sessions.py</files>
<read_first>tools/recon/inventory.py; tools/recon/reference_capture.py; scripts/package.sh; tests/test_extractors.py; docs/compatibility.md; docs/original-manifest.json; 01-RESEARCH.md sections Existing Analogs, Pattern 1 and Security Domain.</read_first>
<behavior>At least 16 discovered tests cover a valid CLI stage→identify→import→validate round trip, changed/missing/added originals, empty/single-file manifests, two-direction path equality/overlap and sibling prefixes, symlink/drive/case escape, shell characters as inert paths, reuse/concurrent allocation, interruption, byte tampering, identical duplicate import and conflicting duplicate ID. Native acceptance rejects synthetic/component/Wine/cross-publish classifications.</behavior>
<action>Create tests first, including one subprocess-level CLI round trip with tiny fixture trees. Implement stdlib-only tools with argument arrays, bounded subprocess/JSON sizes and streaming SHA-256. Reuse the existing inventory comparison without regenerating docs/original-manifest.json. Resolve and validate all roots before writing; reject symlink escapes, Windows normalized aliases, case collisions and source/output overlap in either direction. Allocate fresh session directories exclusively, stage in a temporary sibling and atomically publish after complete pre-run copy verification; failed/interrupted attempts retain diagnostics without publishing a completed receipt. Lock session/import publication and distinguish exact duplicate content from conflicting reuse. Stage a separate generated original copy per fresh run per D-15; retained cases keep one explicitly identified lifetime. Store pre-run copy identity, post-run copy changes and source pre/post inventory separately. Define receipt identity, evidence_kind, status, case/session IDs, actual executable/package/resource and launcher hashes, actual source/dirty/diff identity, native/platform category, invocation/cwd, clocks, artifacts/derivatives and open acceptance. Separate reported historical evidence from newly generated evidence. Exercise one real existing on-disk port package/report, verifying its actual bytes and reporting its recorded scope; if referenced artifacts are absent, explicitly retain missing/stale evidence rather than minting identity. Import an explicitly synthetic paired-media fixture only to exercise plumbing; it cannot qualify as original/native proof. The validate command prints a readable receipt summary with actual category, missing evidence and acceptance state, not just success. Preserve the legacy Wine harness classification and behavior. Establish read-only contained relative references and a documented allowed-receipt state machine for later consumers.</action>
<acceptance_criteria>The CLI round trip yields a hashed receipt and readable summary; original/copy/package identities are distinct; every hostile/partial identity case is rejected without original writes; an existing report is labeled historical or missing exactly as found; synthetic paired fixtures remain in a separate test namespace; no completed acceptance results from a launcher exit code.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_sessions.py"); assert s.countTestCases() >= 16,"fewer than 16 session tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 16 discovered tests, any failed round-trip/security/classification case, or no test summary.</fails_when>
<automated>python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json</automated>
<fails_when>Nonzero exit or missing output Verified 539 unchanged original files.</fails_when>
</verify>
<done>One preserved session can be staged, identified, imported and inspected through the real CLI; all negative tests pass; genuine historical evidence and synthetic test data remain visibly distinct from new native acceptance.</done>
</task>
<task type="auto" tdd="true" id="01-01-02">
<name>Make every required journey and lifetime cell explicit and reject incomplete evidence</name>
<files>docs/evidence/scenarios.json, tests/test_fidelity_scenarios.py, tools/recon/fidelity.py, tools/recon/fidelity_receipts.py</files>
<read_first>01-CONTEXT.md D-01 through D-04; .planning/REQUIREMENTS.md EVID-01 through EVID-04; the receipt interfaces created in task 01-01-01; docs/checkpoint/next-work-plan.md; docs/gameplay/main-menu-player-lifetime.md.</read_first>
<behavior>At least 12 tests require all eight fresh/retained × natural/skipped × ordinary/edge cells, continuous and focused evidence for each, stable IDs/order, real retained-session continuity, and explicit skipped/aborted/missing cases. Equal counts with a missing cell, disconnected scene snapshots, reset timestamps and synthetic/native substitution fail completeness.</behavior>
<action>Define schema-versioned scenarios.json with eight explicit matrix cells and a continuous journey plus focused replay obligations per cell per D-01–D-04. Ordinary runs use normal play; edge runs include held input spanning dialogue/RETURN, both bank directions, landing and idle. Natural and skipped dialogue are separate equal obligations per D-02. Fresh means an independently staged launch; retained means a recorded departure/return in the same session, including prerequisite setup and retained copy state, per D-03. Specify visible setup, actions, end condition and required media/event markers for startup/control, dialogue start/end/skip, first neutral/resumed held input, jump/bank/landing/idle, lab departure, VR04 entry/use, RETURN/cleanup, lab exit and outside arrival. Markers reference actual media time, monotonic elapsed time and observation method/uncertainty; simulation ticks stay separate. Original annotations are procedural/manual unless directly observed by a proven recorder. Allow truthful missing/failed results, but require all cells and artifacts for acceptance. Add validate --scenarios PATH --receipts ROOT with --allow-open for structural readiness and --require-complete for actual acceptance; both emit counts and missing case IDs, and the strict mode exits nonzero on gaps. Never invent universal timing/pixel/audio tolerances. Keep the existing TSK ordering correction, fresh direct-scene order and legitimate landing bank as protected observations rather than changes.</action>
<acceptance_criteria>There are eight uniquely identified matrix cells with explicit continuous and focused obligations; validators detect omitted dimensions and broken retained continuity; structural readiness and evidence acceptance use visibly different verdicts.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_scenarios.py"); assert s.countTestCases() >= 12,"fewer than 12 scenario tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 12 discovered tests, or a missing matrix/continuity/classification negative case passes validation.</fails_when>
</verify>
<done>Every required baseline run has a stable executable procedure, complete artifact obligations and a validator that preserves missing acceptance.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; unresolved high/critical threats block execution acceptance. No package installs are planned.
| Boundary | Description |
|---|---|
| Authoritative originals → generated session | Reads may produce writable copies only outside originals |
| Imported local records → evidence index | Untrusted paths, classifications and identities become reviewable records |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-01 | Tampering | stage_original | high | mitigate | Resolve aliases before allocation; reject overlaps; verify recorded originals before/after and staged bytes before execution |
| T-01-02 | Spoofing | validate_receipt/import_receipt | high | mitigate | Bind actual bytes, platform/method/scope and schema; reject promotion of synthetic/Wine/cross-publish; retain failures |
| T-01-03 | Tampering | Session publication | high | mitigate | Exclusive allocation, atomic completed publication, bounded failure diagnostics and conflicting-ID rejection |
| T-01-SC | Tampering | Package installation | high | mitigate | No new packages; any later proposed npm/pip/cargo install requires research legitimacy audit before execution |
</threat_model>
<verification>Run both counted test suites and original inventory check. Confirm current tree baselines: these new tooling/tests do not exist at planning time, so no new behavior is claimed verified. CLI negative tests must demonstrate nonzero exits, not only raised internal exceptions.</verification>
<success_criteria>Preservation and complete scenario contracts support independent viewer, ledger and native capture work without claiming new original/native execution.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md with interfaces, actual test counts/durations and evidence boundaries.</output>
@@ -0,0 +1,163 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "01"
subsystem: testing
tags: [python, sha256, fidelity, preservation, receipts, scenarios]
requires: []
provides:
- Local preserved-session stage/identify/import/validate CLI
- Version 1 hashed receipt and read-only relative-reference contract
- Eight explicit lifetime/dialogue/input cells with 120 original/native obligations
affects: [01-02, 01-03, 01-04, 01-05, 01-06, 01-07]
tech-stack:
added: []
patterns: [stdlib-only tooling, exclusive allocation, atomic directory publication, streaming SHA-256, bounded JSON, explicit open acceptance]
key-files:
created:
- tools/recon/fidelity.py
- tools/recon/fidelity_receipts.py
- tests/test_fidelity_sessions.py
- docs/evidence/scenarios.json
- tests/test_fidelity_scenarios.py
modified: []
key-decisions:
- "A valid or reviewed receipt never implies native/original acceptance without identified bytes, compatible category, required artifacts and declared audiovisual review."
- "Each matrix cell requires continuous plus dialogue-return, bank-left, bank-right and landing-idle observations on original-DxWnd Windows, native Linux port and native Windows port: 120 obligations."
- "Retained runs bind one session, prerequisite departure/return observations and hashed copy state; fresh runs require independent launch/session IDs."
patterns-established:
- "Import IDs are append-only; only byte-identical duplicate records are idempotent."
- "Incomplete temporary publications retain diagnostics; stale locks are never stolen automatically."
requirements-completed: [EVID-01, EVID-02, EVID-04]
requirements-acceptance: "OPEN: these shared IDs remain Pending in REQUIREMENTS.md; this field records this plan's assigned contribution, not full requirement acceptance."
coverage:
- id: preserved-sessions
description: Preserved staging, actual byte identification and typed hashed imports
requirement: EVID-01
verification:
- kind: integration
ref: tests/test_fidelity_sessions.py
status: pass
- kind: other
ref: python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
status: pass
human_judgment: false
- id: scenario-contract
description: Eight matrix cells, continuous/focused procedures and strict completeness audit
requirement: EVID-02
verification:
- kind: integration
ref: tests/test_fidelity_scenarios.py
status: pass
human_judgment: false
- id: runtime-acceptance
description: Actual identified original-DxWnd and native Linux/Windows audiovisual comparison
requirement: EVID-04
verification: []
human_judgment: true
rationale: "Future capture and human review are required; current real receipt coverage is 0/120. No new game or platform execution occurred in this plan."
actuals:
tokens: 21054
tasks: 2
commits: 4
basis: "ceil(chars/4) of the realized five-file production/test/protocol diff; excludes planning metadata"
plan_head_before: 96c5f2c00fd41e379945300b027e2c5ce9552845
plan_head_after: 32a72654e88ad3709aa1e2f0f108eea06e1b7469
duration: 16 min
started: 2026-11-12T23:56:04Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 01: Preserved Sessions and Scenario Contract Summary
**Streaming original/copy/package identities, atomic typed receipt imports and eight explicit comparison cells preserve missing native/reference acceptance.**
## Performance
- Started: 2026-11-12T23:56:04Z; completed: 2026-11-13 UTC; approximately 16 minutes.
- Tasks: 2; source/test/protocol files created: 5; task commits: 4, measured from the persisted plan ledger.
- Final counted suites: 29 session tests in 0.698 seconds including process overhead; 22 scenario tests in 0.460 seconds. The combined discovery run executes 51 tests in 1.017 seconds.
- Original inventory: 539 unchanged files, final measured invocation 0.229 seconds.
## Accomplishments
- Real CLI fixture round trip stages a pristine installation, identifies its copy, imports paired explicitly synthetic WAV artifacts and prints a readable hashed receipt with OPEN acceptance. Hostile output paths and tampered evidence also return nonzero CLI exits.
- Preservation checks reject equal/nested/case/symlink aliases, changed/missing/added/empty identities, drive/traversal references, collisions and reuse. Source pre/post identity, pristine copy and post-run copy changes remain separate. Interrupted stage/import attempts retain incomplete diagnostics; concurrent stage allocation has one winner.
- Explicit procedures cover all fresh/retained × natural/skipped × ordinary/edge cells. Each has one continuous lab → VR04 → lab → outside journey plus four focused obligations, independently required on three original/native sides.
- Validators reject disconnected clips, timestamp resets, missing dimensions/events/artifacts, conflicting slots, reused fresh sessions, broken retained continuity and synthetic/Wine/component/cross-publish substitution. Structural readiness succeeds with visible gaps; strict acceptance exits 1 with 0/120 obligations accepted and all eight missing case IDs.
## Task Commits
1. Task 01-01-01 RED: `597caa0` — test preserved sessions and receipt trust boundaries.
2. Task 01-01-01 GREEN: `cd7783b` — implement stage/identify/import/validate and historical package identification.
3. Task 01-01-02 RED: `cc4a5a3` — test complete journey and lifetime matrix.
4. Task 01-01-02 GREEN: `32a7265` — enforce protocol, completeness and additional shared receipt security regressions.
Commits ran normal hooks, with explicit scoped staging. No tracked files were deleted. The existing user-authorized main workflow uses the primary's `git.allow_default_branch_commits` setting. The primary owns review, milestone status documents, integration and push; this executor did not push.
## Interfaces for Consumers
`fidelity_receipts.py` exports `stage_original(source, manifest, output, session_id)`, `identify_tree(root)`, `identify_file(path)`, `postflight_session(session, source, manifest)`, `validate_receipt(receipt, root)`, `import_receipt(path, root, output)`, `read_receipt(path)`, `contained_path(root, relative)`, `source_identity(project)`, `identify_report(...)`, `validate_scenario_contract(protocol)`, `required_events(protocol, cell, obligation_id)`, `audit_scenarios(protocol, [(receipt, root), ...])` and `audit_receipt_tree(protocol, root)`. Invalid input raises `ValueError`; filesystem failures propagate. CLI errors return 2; strict valid-but-open audit returns 1.
- Schema version 1 receipt: `receipt_id`, `session_id`, `case_id`, `evidence_kind`, `status`, `historical`, `scope`, `platform`, `identity`, `invocation`, `clocks`, `artifacts`, `derivatives`, `events`, `limitations`, `missing_evidence`, `acceptance`.
- `platform`: explicit `os`, `execution`; native port uses `native`, original Windows reference uses `dxwnd`, other kinds use their own category. Actual OS version and port GPU/driver/Vulkan/SDL provenance are required for acceptance.
- Artifacts/identity references use contained relative POSIX `path`, actual `size` and `sha256`. Artifacts carry `role`; timed media carries `duration_seconds`. Source identity additionally records commit, dirty/diff/status hashes and hashed untracked file identities. Invocations are inert argument arrays and a recorded cwd; imported commands are never executed.
- `clocks`: timezone-aware wall start/end plus finite monotonic start/end; scenario observations additionally require `clock_id`. Events use name/artifact/media_seconds/elapsed_seconds/method/uncertainty_seconds. Port simulation ticks are separate; original annotations remain manual/procedural.
- Scenario records add `obligation_id` and matching `scope`: `continuous`, `dialogue-return`, `bank-left`, `bank-right`, `landing-idle`; `case_id` equals the explicit cell ID. `continuity` binds lifetime/session and prerequisite artifact; retained cases also bind same departure/return session, identified pre/retained copy hashes and observed prerequisite markers preceding the tested interval.
- State-machine documentation lives in the module docstring and `RECEIPT_TRANSITIONS`. Import snapshots are immutable by ID; changing a capture/review requires a new receipt ID, rather than overwriting history. Synthetic imports require a separate output directory containing `test` in its name.
- JSON is bounded to 4 MiB, tree enumeration to 100000 entries, and tool-owned Git identity subprocesses to 20 seconds with bounded reads. Hashes stream in 1 MiB blocks. No dependencies were installed.
## Verification and Evidence Limits
Both exact counted plan commands passed, as did the mandated inventory command. Full logs and measured exit codes are in ignored `artifacts/fidelity/verification/`; the strict open audit's expected exit 1 is recorded there. Task 1 tracer verification ran again before expansion. Evaluation scope resolves all four task commits on the current branch.
One real on-disk `dist/linux-x64` package, its DLL/assets/launcher and `docs/gameplay/main-menu-player-lifetime.md` were hashed by the actual CLI. Ignored `artifacts/fidelity/historical-package.json` records package tree SHA-256 `eff9739dc6282ebb9e047f0a4a38e24b3c46e82502435e07c5a4b66bd31f05de` and DLL SHA-256 `8769ddd4e9f5fa8d4600dcca6ca46436385e14223097f44de68489bc4222f83b`. The report's recorded scope remains historical, with no current applicability or new runtime identity inferred from today's source HEAD. Missing-artifact behavior is separately tested.
The 120-slot positive test uses temporary metadata declarations solely to prove the counting/validation algorithm. The paired WAV fixture is explicitly synthetic and exercises import plumbing only. Neither is imported into the real receipt index. Hashes and declared human-review fields do not independently prove visible/audible content or truthful capture assertions; capture/probe/review/applicability remain later plan responsibilities. No original, DxWnd, Wine, native Windows, native Linux gameplay, browser, GPU, managed runtime, build or package execution was performed by this plan. Legacy `reference_capture.py`, movement, TSK ordering, fresh direct-scene order, legitimate landing bank and admission gates were not edited.
## TDD Gate Compliance
- Task 1: the real CLI round-trip target failed its stage-success assertion before implementation; full 25-test report and semantic assessment are in `artifacts/fidelity/tdd/01-01-01-red.json`. The classifier returned `RED_EVIDENCE_OK`; RED precedes GREEN in ancestry. Final suite has 29 passing cases.
- Task 2: the eight-cell target failed its explicit protocol-presence assertion before implementation; full 18-test report and semantic assessment are in `artifacts/fidelity/tdd/01-01-02-red.json`. The classifier returned `RED_EVIDENCE_OK`. That report also retains a separate missing-API error; the named target itself executed and failed the intended assertion. Final suite has 22 passing cases.
- REFACTOR: no separate refactor was necessary. No skipped/todo tests, unrun planned automated checks or implementation stubs remain.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 2 - Missing Critical Functionality] Strengthened shared receipt security while completing scenario validation.**
- Found during: Task 2.
- Issue: shared import review needed directory-component case-alias checks and receipt-metadata sidecar tamper verification, in addition to file hashes.
- Fix: added these checks and regressions, bounded aggregate JSON output, and used actual paired synthetic WAVs. Task 2 consequently also edits `tests/test_fidelity_sessions.py`, beyond its narrow task file list but within the plan's exclusive ownership.
- Files: both fidelity modules, session/scenario tests.
- Verification: all 51 tests pass, including CLI tamper rejection and prefix-case collision tests.
- Commit: `32a7265`.
Total deviations: 1 correctness/security expansion within the planned boundary; no architectural or gameplay change. Optional broken-windows recording was attempted through the handler.
## Threat/Test Coverage
| Threat | Implemented controls | Evidence |
|---|---|---|
| T-01-01 | Alias/overlap checks before staging writes, exact inventory records, verified pristine copy, source pre/post checks | Session preservation/hostile-path/postflight tests; 539 original hashes |
| T-01-02 | Actual file hashes, typed platform/kind, explicit history/open acceptance, independent matrix slots and human review requirements | Tamper/classification/strict-audit and 120-slot metadata tests |
| T-01-03 | Exclusive allocation, sibling temporary publication, persistent incomplete diagnostics, exact duplicate bytes and conflicts | Concurrent allocation/interruption/duplicate import tests |
| T-01-SC | No package installation | Stdlib-only implementation |
No new endpoints, authentication paths or schema trust boundaries beyond the plan's local filesystem/import surface were introduced. The workflow serializes cooperative writers; concurrent hostile filesystem mutation is explicitly outside its offline threat boundary. Revalidate after collection and before review.
## Issues Encountered
None blocking. Synthetic fixtures stay separate from runtime proof. The unrelated `tools.yaml`, primary-owned config/state changes and milestone lock were preserved.
## User Setup Required
None for these tooling tests. Actual original-DxWnd/native capture and audiovisual review remain future combined checkpoint obligations, not requested prematurely here.
## Next Phase Readiness
Plans 01-02/03/04 can consume the versioned interfaces and scenario contract. Shared EVID-01/02/04 remain Pending until all declaring plans and actual acceptance conditions finish. Current strict audit is OPEN with 0/120 runtime obligations. The primary will update root continuity/compatibility documents and perform integration tests/push.
## Self-Check: PASSED
All five created source/test/protocol files exist. All four task commits are ancestors of current HEAD; evaluation-scope resolves them. Exact counted acceptance commands, original inventory and diff whitespace checks pass. No implementation stubs or unexplained tracked deletions were found.
@@ -0,0 +1,112 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "02"
type: execute
wave: 2
depends_on: ["01-01"]
files_modified:
- tools/recon/fidelity_review.py
- tools/recon/fidelity_viewer/index.html
- tools/recon/fidelity_viewer/viewer.mjs
- tools/recon/fidelity_viewer/style.css
- tests/test_fidelity_review.py
- tests/fidelity-viewer.test.mjs
autonomous: true
requirements: [EVID-02, EVID-03, EVID-04]
estimate:
tokens: 32000
raw_tokens: 32000
tasks: 2
confidence: low
must_haves:
truths:
- "A tester opens a local scenario with paired original/port playback and corresponding image, audio and input/event links per D-05."
- "Raw captures are unobstructed by default; annotations and provenance-bound image differences are optional overlays per D-06."
- "Selecting an event seeks each recording to its own observed time; both play at actual speed with separate elapsed clocks, event drift and playback drift per D-07."
- "The reviewer switches corresponding original/port audio with at most one source audible and visible review gain per D-08."
- "Missing, buffering, rejected-play, decoding and asymmetric-end states remain visible and preserve the full recording tails."
artifacts:
- path: tools/recon/fidelity_review.py
provides: "Contained local review export/server"
- path: tools/recon/fidelity_viewer/viewer.mjs
provides: "Testable paired media controller and capability navigation renderer"
- path: tests/fidelity-viewer.test.mjs
provides: "Built-in Node media-state tests without dependency installation"
key_links:
- from: tools/recon/fidelity_review.py
to: tools/recon/fidelity_receipts.py
via: "Only validated receipt/artifact identities enter generated review data"
- from: tools/recon/fidelity_viewer/viewer.mjs
to: "Generated review.json and contained media"
via: "Actual per-side event times and exclusive mute state"
prohibitions:
- statement: "MUST NOT manufacture apparent parity by retiming recordings, hiding drift, mixing both soundtracks or presenting synthetic media as an original reference."
status: unresolved
reason: "Spec-less recall; descriptor-less and flagged-unverified pending real playback judgment."
---
<objective>
Deliver the local paired review workflow per D-05–D-08. This is a filesystem-based tool, with a contained loopback viewer only where browser seeking requires it.
Artifacts this phase produces in this plan: fidelity_review.py CLI export and serve; generated review.json, index.html and copied/link-validated media under artifacts/fidelity/review; viewer.mjs exports createPairController and renderCapabilities; index.html/style.css; counted Python export/server tests and Node media-state tests. No hosted site or external integration.
</objective>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-RESEARCH.md
@.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-02-01">
<name>Open one validated local pair with real media links and event selection</name>
<files>tools/recon/fidelity_review.py, tools/recon/fidelity_viewer/index.html, tools/recon/fidelity_viewer/viewer.mjs, tests/test_fidelity_review.py, tests/fidelity-viewer.test.mjs</files>
<read_first>01-RESEARCH.md Pattern 3 and Security Domain; 01-01-SUMMARY.md receipt interfaces; tools/recon/fidelity_receipts.py; docs/evidence/scenarios.json; 01-CONTEXT.md D-05–D-08.</read_first>
<behavior>At least 10 Python tests export and serve one valid imported pair end to end, preserve synthetic labels, reject traversal/symlinks/absolute or remote references and escaping labels, test GET/HEAD/byte-range seeking, and forbid write methods. Initial Node tests exercise event alignment, actual-speed playback, artifact links and failed play with media doubles.</behavior>
<action>Create tests before implementation. Export a self-contained review tree from validated receipts and their hashed artifacts; expose a real CLI flow from import output to generated review index and paired native media elements. Use one existing genuine port artifact where present and clearly labeled synthetic audiovisual pair fixtures for plumbing; display missing original reference explicitly. Retain raw recordings and derivative ancestry. Include links to original/port recordings, source audio, lossless stills and traces per D-05. Validate event correspondence and finite in-range timestamps before seeking. For local serving, bind loopback only, serve only the generated review root, reject resolved symlink escapes and unsupported methods, implement bounded GET/HEAD byte-range responses so seeking is exercised by tests; never expose repository/original roots or a write endpoint. Use textContent/escaped rendering and contained relative links, never imported HTML/commands. The browser shows scope/platform/synthetic/missing labels beside results, and no successful export or fixture is an acceptance receipt. Add capability-navigation rendering consuming the ledger model contract recorded in SKELETON.md, without inventing ledger facts.</action>
<acceptance_criteria>A CLI subprocess export plus local HTTP test opens both fixture media links and event metadata; malicious paths/labels cannot escape or execute; missing original is visible; generated media is local and properly classified.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_review.py"); assert s.countTestCases() >= 10,"fewer than 10 review tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 10 tests, failed CLI/export/range test, or a traversal/write-method negative case is accepted.</fails_when>
<automated>node --test tests/fidelity-viewer.test.mjs</automated>
<fails_when>Nonzero exit, zero tests or absence of a positive pass count; any media alignment/link/classification test fails.</fails_when>
</verify>
<done>One explicitly classified pair travels from validated receipt through local export/serving to the paired reviewer; no external request is required.</done>
</task>
<task type="auto" tdd="true" id="01-02-02">
<name>Complete truthful timing, exclusive audio, optional overlays and failure interaction</name>
<files>tools/recon/fidelity_viewer/index.html, tools/recon/fidelity_viewer/viewer.mjs, tools/recon/fidelity_viewer/style.css, tests/fidelity-viewer.test.mjs, tests/test_fidelity_review.py</files>
<read_first>The pair controller created in task 01-02-01; 01-CONTEXT.md D-06–D-08; 01-RESEARCH.md Pattern 3 and Meaningful Negative Cases.</read_first>
<behavior>At least 16 Node tests cover both elapsed clocks, event versus playback drift, rate 1.0 after seek/play/recovery, exclusive audio switch, default gain 1, labeled adjusted gain, missing/buffering/decode/play-rejection states, asynchronous seek readiness, asymmetric ends/tails, overlays default off and viewport mismatch. The test runner asserts its own nonzero count.</behavior>
<action>Keep video surfaces unobstructed by default and make annotation/difference layers separately opt-in per D-06. Event selection pauses both, waits for readiness, seeks each side independently to its own observed marker and resumes only on explicit review action at playbackRate 1 per D-07. Display absolute recording elapsed times, aligned-event elapsed offsets, scenario-event drift with uncertainty and browser playback drift separately. No periodic follower seeking, duration normalization or hidden timing correction. Expose per-side manual controls and raw media links. On buffering/missing/decode/play rejection pause the pair and show the cause; if one side ends, preserve and make the longer tail playable instead of trimming it. Mute both before selecting one soundtrack at corresponding times per D-08; gain starts unadjusted, is visibly labeled review-only when changed, and never changes recorded media. Optional image differences require matched lossless frame identity, viewport/aspect and crop metadata; explain mismatches and avoid numerical fidelity claims from lossy video. Add keyboard-accessible controls, readable narrow-window layout and explicit empty review states. Keep raw captures and elapsed time visible throughout.</action>
<acceptance_criteria>Sixteen or more behavior tests pass; both tracks always remain at real speed; at most one soundtrack is audible; initial overlays are off; failures and longer tails remain accessible. Browser/real-audio judgment remains an end-of-phase human check.</acceptance_criteria>
<verify>
<automated>node --test tests/fidelity-viewer.test.mjs</automated>
<fails_when>Nonzero exit, fewer than 16 declared/executed tests, missing positive test summary, or any drift/rate/audio/error/overlay assertion fails.</fails_when>
<human-check>During the single combined session, open real paired media in the actual browser; hear each source separately, seek observed markers, inspect asymmetric tails and toggle overlays. Record browser/version/codec failures and leave affected review acceptance open.</human-check>
</verify>
<done>The paired reviewer implements D-05–D-08 with tested state handling; actual codec/audio playback is listed for the one final session without creating an earlier user request.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; high/critical unresolved threats block acceptance. No package installs.
| Boundary | Description |
|---|---|
| Imported evidence → HTML/media | Labels and paths become local browser content |
| Loopback HTTP → generated files | Only the contained generated tree is readable |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-04 | Information disclosure | fidelity_review server | high | mitigate | Loopback only, root containment, symlink rejection, bounded byte ranges, read-only methods |
| T-01-05 | Tampering | Viewer text/media links | high | mitigate | Escaped/text rendering, local relative URL allowlist and no receipt commands/HTML execution |
| T-01-06 | Spoofing | Pair controller | medium | mitigate | Visible evidence category, raw clocks, rate 1 and explicit missing/uncertainty states |
| T-01-SC | Tampering | Package installation | high | mitigate | Built-in browser/Node/Python only; no npm/pip additions |
</threat_model>
<verification>Run counted Python and Node checks. First real-media browser acceptance occurs with final combined session; fixture playback is tooling evidence only.</verification>
<success_criteria>Local paired review exposes visual/audio/event correspondence without concealing drift or inventing original execution.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md with local invocation and measured checks.</output>
@@ -0,0 +1,176 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "02"
subsystem: testing
tags: [python, native-media, node, local-http, fidelity, evidence]
requires:
- phase: 01-01
provides: Version 1 validated hashed receipts and scenario contract
provides:
- Self-contained review export with contained read-only loopback GET/HEAD ranges
- Independent event seeks, raw clocks, drift, exclusive audio and preserved tails
- Capability navigation with validated copied source text and explicit missing states
affects: [01-03, 01-05, 01-06, 01-07]
tech-stack:
added: []
patterns: [stdlib-only export, native browser media, independent clocks, opt-in review aids, built-in Node tests]
key-files:
created:
- tools/recon/fidelity_review.py
- tools/recon/fidelity_viewer/index.html
- tools/recon/fidelity_viewer/viewer.mjs
- tools/recon/fidelity_viewer/style.css
- tests/test_fidelity_review.py
- tests/fidelity-viewer.test.mjs
modified: []
key-decisions:
- "Review exports always retain OPEN acceptance; synthetic/history labels and absent original/native recordings stay explicit."
- "Pair playback uses rate 1 with separately observed event anchors, independent clocks, visible drift and explicit recovery; longer tails remain playable."
- "Capability source links are copied only from contained tracked bounded UTF-8 text; the viewer activates only exporter-validated local hrefs."
requirements-completed: [EVID-02, EVID-03, EVID-04]
requirements-acceptance: "OPEN: assigned tooling contributions only; shared EVID IDs remain Pending and real runtime coverage remains 0/120."
coverage:
- id: contained-review
description: Validated receipt export, contained HTTP seeking and local source links
requirement: EVID-02
verification:
- kind: integration
ref: tests/test_fidelity_review.py
status: pass
human_judgment: false
- id: paired-controller
description: Event alignment, raw clocks, drift, exclusive audio, failure states and optional aids
requirement: EVID-03
verification:
- kind: unit
ref: tests/fidelity-viewer.test.mjs
status: pass
- kind: automated_ui
ref: artifacts/fidelity/viewer-smoke-final/browser-result.json
status: pass
human_judgment: false
- id: real-audiovisual-review
description: Actual original/native recordings, audible source switching and browser/codec judgment
requirement: EVID-04
verification: []
human_judgment: true
rationale: "Headless synthetic playback verifies tooling only. Actual identified original/native media and audible review belong to the final combined session."
actuals:
tokens: 18814
tasks: 2
commits: 4
basis: "ceil(chars/4) over the realized six-file production/test diff, excluding planning metadata"
plan_head_before: 6be848480288480208ac737c953b7c9bfc82bd84
plan_head_after: 91da92f17d93ba80ead87f92cf4714b6635133bb
duration: 16 min
started: 2026-11-13T00:30:27Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 02: Local Paired Review Summary
**Contained hashed-media export and actual-speed paired playback expose event/playback drift, exclusive audio, optional still differences and complete recording tails.**
## Performance
- Measured implementation window: first persisted RED evidence at 00:30:27 UTC through final verification at 00:46:15 UTC, rounded to 16 minutes. Required setup/context reads preceded this measurement.
- Two tasks; six source/test files; four task commits measured from the persisted ledger.
- Final exact checks: 21 Python review tests, 5.234 seconds including process startup; 27 Node tests, 0.120 seconds. Combined fidelity discovery: 72 tests, 6.318 seconds. Original inventory: 539 unchanged files, 0.268 seconds.
- Full logs and command/exit/time records: ignored `artifacts/fidelity/verification/01-02-*`.
## Accomplishments
- A real subprocess exports imported hashed receipts into a new self-contained directory. Tests read both media links and event metadata over actual loopback HTTP, including HEAD, prefix/open/suffix ranges and invalid-range rejection.
- Both recordings seek to their own observed markers after metadata/seek readiness. Explicit play preserves rate 1, and raw elapsed clocks, event offsets, event drift plus uncertainty, and browser playback drift remain separately visible. No follower seeks, duration normalization or retiming occur.
- Dedicated keyboard-accessible per-side play/pause/seek controls coexist with exclusive soundtrack selection and visibly labeled review-only volume. Buffering, missing media, decoding failure, play rejection, stale asynchronous actions and asymmetric endings remain explicit; the full longer tail can resume.
- Annotations and lossless image differences begin off and leave raw captures unobstructed. Difference eligibility requires identified PNGs, source-media hashes, corresponding observed event timestamps, matching dimensions/viewport/aspect/crop and successful image decoding. Differences have no numerical fidelity score.
- Capability navigation preserves supplied facts/current evidence/history, orders discrepancies by impact, and links copied validated source text. Empty ledger and missing-source states remain explicit.
## Task Commits
1. Task 01-02-01 RED: `488c904` — specify contained paired media review.
2. Task 01-02-01 GREEN: `49f874e` — export and serve validated local media pairs.
3. Task 01-02-02 RED: `75d7ca4` — specify truthful timing, audio and failure states.
4. Task 01-02-02 GREEN: `91da92f` — preserve clocks, exclusive audio and complete review tails.
Normal hooks ran with scoped staging. No tracked files were deleted. The primary owns milestone review and push; this executor did not push.
## Local Invocation and Interfaces
```sh
python3 tools/recon/fidelity_review.py export \
--original PATH/TO/IMPORTED-ORIGINAL/receipt.json \
--port PATH/TO/IMPORTED-PORT/receipt.json \
--ledger PATH/TO/CAPABILITY-EXPORT.json \
--output artifacts/fidelity/review/NEW-PAIR
python3 tools/recon/fidelity_review.py serve \
--root artifacts/fidelity/review/NEW-PAIR --port 8765
```
Open `http://127.0.0.1:8765/`. Either receipt and the ledger may be omitted; absent evidence stays visible. Output must be a new directory. Invalid input exits 2. Serving requires a generated `.review-root.json` manifest and only binds `127.0.0.1`; it never serves the repository or Original directory. The exporter copies/revalidates bytes, retains raw artifacts/derivative ancestry, and never executes receipt argv. Failed publication retains its incomplete temporary sibling.
Python APIs: `export_review(original, port, output, ledger=None)` returns the model; `make_server(root, port=8765, host='127.0.0.1')` returns an owned `ThreadingHTTPServer`. The caller closes/shuts down that server. The generated root contains `review.json`, the three viewer files, side-specific receipt/artifacts and optional `sources/` text.
`review.json` version 1 contains `case_id`, `sides.original/port`, corresponding `events`, `ledger`, and explicit OPEN acceptance. Side records preserve kind/platform/scope/history/limits/identities, hashed `artifacts` with local `url`, selected `media`, observed `events`, `derivatives`, `receipt_url`, missing evidence and warnings. Only markers on the selected video/explicit preview are seekable; a preview without its own observed correspondence has visible gaps. Same case/scope and unambiguous event names are required. No timestamps are inferred from derivatives.
ES module exports: `createPairController`, `safeLocalURL`, `differenceEligibility`, `framePair`, `renderCapabilities`. Controller methods are `selectEvent`, `play`, `playSide`, `seekSide`, `pause`, `snapshot`, `setAudio`, `setGain`, `setOverlay`, `dispose`; media elements and change callback are injected for testing. Volume starts at 1 and can be attenuated from 0 to 1. Both sources are muted before audio selection; dedicated UI controls prevent native media controls independently enabling another soundtrack.
Optional PNG artifact metadata is `frame: {lossless,event,media_sha256,media_seconds,viewport:[w,h],crop:[x,y,w,h],width,height}`. It binds an identified PNG to its own selected source media and observed marker; unmatched provenance/dimensions disable the aid. PNG decoding must agree with declared dimensions. Raw video remains available, and still differences are review aids even when extracted from lossy video.
The coordinated ledger input contract is `{schema_version:1, capabilities:[...]}` with SKELETON fields `id/group/requirement_ids/summary/verified_scope/differences/acceptance/source_links/scenario_ids/evidence/current/history/discrepancies`. Evidence/current/history are rendered read-only without inventing acceptance facts. `source_links` entries are `{label,path,sha256?}` with repo-relative paths. Export resolves containment, rejects symlinks/private/generated/original roots, requires tracked non-NUL UTF-8 text at most 1 MiB, and verifies optional hashes. Exported links add `{href,validated_local,sha256,size,missing}`; only validated `sources/...` hrefs become links. Safe missing/untracked references have `href:null`, `validated_local:false`, and a visible reason. Other imported HTML/commands remain inert.
## Browser and Evidence Limits
Installed Chromium `157.0.8103.38` decoded local synthetic VP8/Vorbis recordings through the real server. A loopback CDP check verified `.500/.750` event seeks while paused, subsequent actual-speed playback, original/port mute exclusivity, visible volume adjustment, opt-in annotations/difference canvas, a 390px layout without horizontal overflow, and explicit longer-tail playback after the 3.003-second recording ended while the 5.003-second recording retained its tail. The copied source-document link returned HTTP 200. No page runtime exceptions were observed.
Ignored evidence is in `artifacts/fidelity/viewer-smoke-final/browser-result.json` and `browser.png`; fixture generation/CDP scripts are retained alongside them. The final generated synthetic viewer is `test-review-v3/` within that directory. Synthetic moving patterns and tones are labeled throughout, and no genuine original reference is implied. Browser media state checks do not prove audible hardware output or human audiovisual adequacy.
The genuine existing port output `artifacts/window-transitions/2-VR04-1280x720.png` was hashed/imported separately as **historical port_fixture** evidence and exported to `historical-review/`. Chromium displayed its historical label, raw still link, missing playable video and missing original reference. This does not establish a new runtime/source revision or applicability receipt.
Actual original-DxWnd, native Linux/Windows scenario recordings, codec variation and audible judgment remain for the one final combined session. Acceptance stays OPEN at 0/120 real obligations. Shared EVID IDs are not marked complete. No gameplay/runtime/package code, originals or shared receipt/scenario implementation changed; no game, DxWnd, Wine, GPU, managed build or Windows execution was performed here.
## TDD Gate Compliance
- Task 1: `artifacts/fidelity/tdd/01-02-01-red.json` retains the complete actual unittest report. The named CLI round-trip target failed its intended CLI-presence assertion before implementation. The classifier returned `RED_EVIDENCE_OK`; semantic inspection confirmed a behavior assertion rather than import/setup failure. The tracer's exact 15-Python/6-Node checks passed again before task 2.
- Task 2: `artifacts/fidelity/tdd/01-02-02-red.json` retains complete TAP. The named buffering test failed because replay incorrectly returned true while readyState was 2. The classifier returned `RED_EVIDENCE_OK`; other absent-API failures were retained rather than used as target evidence. Final suites pass 21 Python and 27 Node tests, with a dynamic minimum registered-count assertion.
- Each RED commit precedes its GREEN in ancestry. No separate refactor was needed. No skipped/todo tests or unrun planned automated checks remain.
## Deviations from Plan
No scope or architecture changes. The initial stylesheet was included with the tracer so its exported review tree was self-contained. The primary confirmed the exact tracked source-link normalization for plan 01-03 during implementation; this fulfills the planned capability navigation boundary without shared schema edits.
## Threat/Test Coverage
| Threat | Controls and evidence |
|---|---|
| T-01-04 | Generated-root manifest allowlist, actual hashes, loopback-only bind, resolved containment, symlink rejection, no listings, GET/HEAD-only reads, bounded single ranges; real HTTP negative/range tests |
| T-01-05 | Text rendering, relative URL allowlist, no imported HTML/argv execution, CSP/nosniff, imported active documents downloaded inertly, validated copied text sources; hostile-label/path/document tests |
| T-01-06 | Explicit category/history/missing labels, independent clocks, rate 1, separate drift/uncertainty, no auto-acceptance; controller/browser/classification tests |
| T-01-SC | Browser/Node/Python built-ins only; no npm/pip installation. Existing ffmpeg produced ignored synthetic smoke media. |
## Threat Flags
| Flag | File | Description |
|---|---|---|
| threat_flag: file-access | tools/recon/fidelity_review.py | Ledger source references cross the repository-text→generated-review boundary. Contained tracked bounded UTF-8-only copies, excluded roots, optional hash checks, inert text MIME and the generated manifest mitigate this planned navigation surface. |
The cooperative offline filesystem boundary matches the shared receipt module; hostile concurrent filesystem replacement is outside that model. Re-export/revalidate after evidence changes. Native media/browser codec support remains a runtime review condition.
## Issues Encountered
The sandbox blocks loopback sockets and causes Node's child test runner to report one file-only result. Authorized local-test escalation produced the real named counts and HTTP results; the file-only result was not counted as validation. A browser-cancelled read exposed a broken-pipe retry; the handler now ends disconnected responses cleanly. Newer seek actions supersede stale metadata waits without cancelling the current action. These fixes remain within planned failure handling.
No implementation stubs remain. Deliberately absent media/ledger states are implemented outcomes, not mock gameplay data. `tools.yaml`, the transient milestone lock and other owners' files were preserved.
## User Setup Required
None for the local tool checks. The planned combined hands-on original/native/audio session remains open; no earlier user execution request was created.
## Next Phase Readiness
Plan 01-03 can emit the coordinated capability/source-link contract; later checkpoint/capture/import plans can supply real receipts. The primary owns root continuity documents, integrated runtime regression gates and push. The existing gameplay and platform evidence limits remain binding.
## Self-Check: PASSED
All six created files exist. All four task commits are ancestors of HEAD and evaluation-scope resolves them on this branch. Exact counted plan checks, all 72 fidelity tests, whitespace checks and the 539-file preservation command pass. No tracked deletions, skipped tests or unexplained new untracked outputs were introduced; generated media/receipts stay ignored.
@@ -0,0 +1,114 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "03"
type: execute
wave: 2
depends_on: ["01-01"]
files_modified:
- tools/recon/fidelity_ledger.py
- tests/test_fidelity_ledger.py
- docs/evidence/capabilities.json
- docs/evidence/README.md
autonomous: true
requirements: [EVID-03]
estimate:
tokens: 28000
raw_tokens: 28000
tasks: 2
confidence: low
must_haves:
truths:
- "Reviewers browse movement, contacts, gadgets, progression, visuals and audio with requirement/source/scenario/platform links per D-09."
- "Each capability leads with working behavior, verified scope/platform, known differences and remaining acceptance per D-10."
- "Current applicable evidence precedes expandable explicitly superseded revision history per D-11; applicability uses content/scope/platform rather than newest date."
- "Discrepancies order blocking/disruptive failures before subtler differences and missing verification per D-12; all missing evidence keeps acceptance open."
- "All 33 full-game requirements have capability coverage even when unimplemented; an empty ledger fails and one capability remains renderable."
- "Equal receipt/content identities merge only when the record bytes match; conflicts remain explicit, and duplicate history rows never silently overwrite evidence."
- "Equal-priority entries have deterministic stable ID ordering; explicit supersession cycles and unresolved contradictory current claims fail validation."
artifacts:
- path: docs/evidence/capabilities.json
provides: "Authoritative full-game capability ledger"
- path: tools/recon/fidelity_ledger.py
provides: "Scope-aware validator and deterministic render/export"
- path: docs/evidence/README.md
provides: "Generated capability-first navigation and evidence instructions"
key_links:
- from: docs/evidence/capabilities.json
to: .planning/REQUIREMENTS.md
via: "Complete 33-ID coverage with implementation/evidence/acceptance separation"
- from: tools/recon/fidelity_ledger.py
to: "Generated ledger.json consumed by paired review"
via: "SKELETON.md shared capability contract; no parallel viewer file writes"
prohibitions:
- statement: "MUST NOT erase contradictory history, hide unimplemented required content or turn missing evidence into a fidelity-completion claim."
status: unresolved
reason: "Spec-less recall; project-specific transparency value, descriptor-less and flagged-unverified."
---
<objective>
Make the full reconstruction auditable through one authoritative capability ledger per D-09–D-12, retaining all evidence boundaries and exact current applicability.
Artifacts this phase produces in this plan: capabilities.json schema-versioned records; fidelity_ledger.py validate/render/export CLI and select_current_evidence function; generated docs/evidence/README.md navigation; tests/test_fidelity_ledger.py. Exported ledger.json stays below artifacts/fidelity/review. No parallel edits to viewer or root status files.
</objective>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/REQUIREMENTS.md
@.planning/ROADMAP.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-RESEARCH.md
@.planning/phases/01-reproducible-fidelity-baseline/SKELETON.md
@.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-03-01">
<name>Trace one real capability from source report to current receipt and review navigation</name>
<reversibility rating="costly">The ledger is a shared evidence interface; version it and generate all presentation from its retained records.</reversibility>
<files>tools/recon/fidelity_ledger.py, tests/test_fidelity_ledger.py, docs/evidence/capabilities.json, docs/evidence/README.md</files>
<read_first>docs/checkpoint/coverage.md; docs/compatibility.md; docs/gameplay/main-menu-player-lifetime.md; docs/gameplay/jimmy-movement-stabilization.md; .planning/REQUIREMENTS.md; SKELETON.md capability contract; 01-RESEARCH.md Pattern 4.</read_first>
<behavior>At least 12 tests cover one real capability render/export round trip, empty/single ledger, duplicate/conflicting IDs/history, equal-priority ordering, supersession cycles, nonexistent/unsafe links, docs-only revisions, changed package/resources, mismatched platform/scope and missing evidence remaining open.</behavior>
<action>Create tests first. Implement one fully populated capability for the already corrected TSK-backed first-story input order using current authoritative reports, preserving direct-fresh distinction and legitimate landing bank. Link source evidence, implementation revision and exact bounded runtime receipt/report, with missing local artifacts explicitly recorded. Lead with what works, where verified, differences and acceptance per D-10. Define records with stable capability ID, group, requirement IDs, behavior/scenes, source links/addresses when present, implementation source revision, evidence records with method/platform/content/scope and artifact identities, current applicability, discrepancies and acceptance. Current receipt selection must use exact content identity and scope; a newer docs commit does not supersede unchanged runtime bytes, while changed runtime/resources require explicit applicability review. Keep prior statements in history with revision, supersedes ID/reason and current/superseded status per D-11. Produce readable Markdown and JSON review navigation from the same data. The actual capability round trip must show its remaining original/native Windows acceptance; a report link is not a newly executed run. Require finite bounded data and safe repository/local artifact references. Validate conflicting duplicate records and deterministic ordering before rendering, with stable IDs as tie-breakers.</action>
<acceptance_criteria>A reviewer can follow one real capability through source, implementation, bounded platform proof, prior narrative and remaining acceptance; generated navigation agrees with the authoritative JSON; tamper/empty/history failures are test-covered.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_ledger.py"); assert s.countTestCases() >= 12,"fewer than 12 ledger tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 12 tests, missing round-trip result, or any stale/empty/conflicting/history negative case passes.</fails_when>
</verify>
<done>One real capability is auditable through generated navigation with truthful current applicability and visible open acceptance.</done>
</task>
<task type="auto" tdd="true" id="01-03-02">
<name>Account for the complete game and rank actionable discrepancies</name>
<files>docs/evidence/capabilities.json, docs/evidence/README.md, tools/recon/fidelity_ledger.py, tests/test_fidelity_ledger.py</files>
<read_first>docs/progress.md; docs/tasks.md; docs/decisions.md; docs/checkpoint/implementation-plan.md; docs/checkpoint/next-work-plan.md; .planning/REQUIREMENTS.md; all source reports linked by the capability rows being reconciled, read only as needed.</read_first>
<behavior>Extend to at least 16 tests, requiring all 33 requirement IDs and all six locked capability groups; test unimplemented rows, receipt/scenario links, current/history separation, missing-proof open status and impact order blocking→disruptive→subtle→missing-verification with stable ties.</behavior>
<action>Populate every full-game requirement category per D-09 using existing recovery and implementation reports, including unimplemented/unverified work. Preserve all existing checkpoint coverage rows by a corresponding detail row or explicit linked source; record reconciliation so no historical source row disappears silently. Include movement, contacts/helpers, gadgets/vehicles, actors/hazards, authored progression/content, menus/persistence, visuals/cameras, audio and native delivery. Map all 33 requirement IDs without claiming they are implemented. For each row lead with D-10 fields and link the relevant scenarios/source/platform proof; retain exact historical package revisions and limited Wine/component/cross-publish classifications. Rank player-impact discrepancies per D-12 with deterministic ties, but keep verification gaps in acceptance even when displayed later. Export grouping, current summary, expandable history data and scenario links using the shared contract so the viewer can consume it without editing its files. validate must fail on unmapped requirements, missing critical fields, dead source links, contradictory current claims and invalid receipt classifications. Record explicitly missing generated artifacts as known gaps instead of dropping their entries. Generate README.md rather than maintaining a second independent status table.</action>
<acceptance_criteria>All 33 requirement IDs and existing checkpoint coverage entries are accounted for; current and superseded evidence retain exact revisions; missing evidence is visible and open; deterministic discrepancy sorting matches D-12.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_ledger.py"); assert s.countTestCases() >= 16,"fewer than 16 ledger tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 16 tests, or any requirement-coverage/impact/applicability assertion fails.</fails_when>
<automated>python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md</automated>
<fails_when>Nonzero exit or missing summary requirements=33 unmapped=0; any contradictory current record or unresolved broken source link.</fails_when>
</verify>
<done>The full game is traceable in one authoritative capability ledger, and its navigation never conflates implementation, recovered source, bounded execution and remaining acceptance.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; unresolved high/critical threats block acceptance.
| Boundary | Description |
|---|---|
| Historical reports → current capability claims | Report scope and actual identity must survive reconciliation |
| Ledger references → generated navigation | Untrusted labels/paths are emitted as readable local data |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-07 | Spoofing | select_current_evidence | high | mitigate | Exact content/platform/scope checks; explicit supersession; contradictory current evidence blocks validation |
| T-01-08 | Repudiation | Evidence/history import | medium | mitigate | Stable record IDs, duplicate conflict rejection, source-row reconciliation and deterministic history ordering |
| T-01-09 | Tampering | Ledger render/export | medium | mitigate | Escaped text and validated local/repository links; no executable imported commands |
| T-01-SC | Tampering | Package installation | high | mitigate | Stdlib-only ledger tools; no new package installation |
</threat_model>
<verification>Run counted ledger tests and full 33-ID validation. Inspect generated capability summary/history against the authoritative TSK and current platform reports. No native execution is claimed by ledger completion.</verification>
<success_criteria>Full-game proof and remaining acceptance can be reviewed by capability, with current applicability and discrepancies preserved.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-03-SUMMARY.md with reconciliation counts, authoritative model and open evidence.</output>
@@ -0,0 +1,163 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "03"
subsystem: testing
tags: [python, capability-ledger, fidelity, sha256, reconciliation]
requires:
- phase: 01-01
provides: Version 1 receipts and eight-cell scenario protocol
- phase: 01-02
provides: Actual contained viewer export and source-link normalization
provides:
- Authoritative 25-capability ledger covering all 33 full-game requirements
- Exact reconciliation of 16 checkpoint systems, 11 owners and six assumptions
- Scope/content/platform selection, preserved supersession and generated navigation
affects: [01-04, 01-05, 01-06, 01-07, movement, delivery]
tech-stack:
added: []
patterns: [stdlib-only validation, hashed source rows, explicit documentary scope, generated Markdown and JSON]
key-files:
created:
- tools/recon/fidelity_ledger.py
- tests/test_fidelity_ledger.py
- docs/evidence/capabilities.json
- docs/evidence/README.md
modified: []
key-decisions:
- "Full-game coverage includes bounded, unimplemented and tooling work; coverage and report validity never promote native/reference acceptance."
- "Checkpoint reconciliation hashes every system/ownership row and numbered assumption and requires a retained source link from each mapped capability."
- "Current evidence means exact named content/platform/scope applicability; documentation dates and newer source HEAD never substitute for runtime bytes."
patterns-established:
- "One authoritative JSON model generates Markdown and viewer export; equal receipt IDs merge only byte-identical records across the entire ledger."
- "Imported receipt references bind actual receipt digest, category, platform, scope and historical flag; legacy report records remain separately described."
requirements-completed: [EVID-03]
requirements-acceptance: "OPEN: assigned ledger contribution only. EVID-03 remains Pending because other declaring plans and runtime acceptance are unfinished. All 120 actual original/native obligations remain open."
coverage:
- id: capability-accounting
description: All 33 requirements, six groups and 33 checkpoint source rows are explicitly accounted for
requirement: EVID-03
verification:
- kind: integration
ref: tests/test_fidelity_ledger.py
status: pass
- kind: other
ref: python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md
status: pass
human_judgment: false
- id: review-roundtrip
description: Actual ledger CLI and viewer export preserve all capability/current/history/scenario/acceptance data and copied source links
requirement: EVID-03
verification:
- kind: integration
ref: tests/test_fidelity_ledger.py#test_real_startup_capability_cli_and_viewer_roundtrip
status: pass
human_judgment: false
- id: actual-reference-acceptance
description: Identified whole-original and current native Linux/Windows gameplay and audiovisual comparison
verification: []
human_judgment: true
rationale: "Existing reports and bounded historical fixtures are not the required original-DxWnd/native scenario recordings or human review; actual matrix acceptance remains 0/120."
actuals:
tokens: 78646
tasks: 2
commits: 5
basis: "ceil(chars/4) over the realized four-file production/test/model/navigation diff (314583 chars), excluding planning metadata. Commit count is the actual persisted-ledger range, including the intervening pause handoff commit."
plan_head_before: be18d77ca42b1896540ff21122bbc1e684195dc1
plan_head_after: 4d07d60e2fdbfdb065aaa2e7e780055620984521
duration: 22 min
started: 2026-11-13T00:48:50Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 03: Full-Game Capability Ledger Summary
**A generated 25-capability ledger maps all 33 requirements, reconciles 33 hashed checkpoint entries and preserves exact startup-order evidence with open native/reference acceptance.**
## Performance
- Two tasks; four created files. Approximate active execution windows total 22 minutes: prior-plan close at 00:48:50 through pause handoff at 01:02:30, then resumed state at 03:49:05 through verification/commit at 03:57:36 UTC. Approximately 189 wall minutes include the explicitly requested usage pause.
- Persisted base-to-production-HEAD range contains five commits: four task RED/GREEN commits and one pause handoff. Evaluation-scope independently resolves the four task commits on this branch.
- Final ledger suite: 31 tests, 0.980 seconds; all fidelity Python suites: 103 tests, 7.149 seconds (7.229 seconds including process overhead); Node: 27 named tests, 82.360 milliseconds. Original inventory: 539 unchanged files.
## Accomplishments
- The authoritative model accounts for movement, contacts/helpers, actors/hazards, gadgets/vehicles/inventory, authored content/progression, frontend/configuration/persistence, visuals/cameras, audio and native delivery. Its six locked navigation groups contain 25 capabilities: 21 bounded, three explicitly unimplemented full-scope workflows and one tooling capability. Coverage is 33 requirements, zero unmapped.
- Reconciliation retains all 16 system rows, 11 ownership rows and six numbered assumptions from `docs/checkpoint/coverage.md`. Each has exact source-row SHA-256, retained source path and mapped capability IDs. Missing, changed, duplicate or extra source rows and absent retained source links fail validation. Baseline wording remains in its source; continuation summaries explicitly refine it.
- The real startup row retains already-corrected TSK story-entry order, separate fresh direct-scene order, valid landing bank, actual source addresses/REA identifier and exact historical ea04210 Linux/Wine classifications. Prior incorrect fresh-story inference stays explicitly superseded with its successor and reason. Report validity is distinct from runtime applicability.
- Markdown and JSON exports come from the same model. A real subprocess ledger export feeds the existing `fidelity_review.export_review` without viewer edits. All 25 rows preserve their current/history/scenario/acceptance/discrepancy fields; all 153 source-link entries resolve to validated copied text files. Current evidence precedes history; discrepancies sort blocking, disruptive, subtle, missing_verification, then stable ID.
- Validation rejects empty/unmapped ledgers, conflicting duplicate capabilities/receipts/history, cycles, unresolved contradictory current claims, unsafe/dead/tampered sources, nonfinite/unbounded data, unknown scenarios, invalid categories and stale artifact hashes. Actual imported receipts are revalidated and bound to their digest/platform/scope/history instead of accepting a relabeled reference.
## Task Commits
1. Task 01-03-01 RED: `ded848f` — specify capability applicability and review navigation.
2. Task 01-03-01 GREEN: `e6713ea` — trace corrected TSK order through capability evidence.
3. Task 01-03-02 RED: `c21ed7d` — require complete game and checkpoint source coverage.
4. Task 01-03-02 GREEN: `4d07d60` — reconcile full-game capability and checkpoint coverage.
Intervening `fafbd05` is the primary's pause handoff, not another task implementation. Normal hooks ran with explicit scoped staging. No tracked production files were deleted. Main commits use the user-authorized configuration; the primary owns integration and push.
## Files and Interfaces
- `docs/evidence/capabilities.json`: schema_version 1 authoritative facts; 25 capabilities, 28 typed documentary/historical evidence records, 33 reconciliation entries, explicit evidence policy. Unimplemented workflows are honest coverage rows, not implementation stubs.
- `tools/recon/fidelity_ledger.py`: `validate_ledger(data, project, requirements=None)`, `export_ledger(...)`, `render_markdown(...)`, `select_current_evidence(records, target)` and `checkpoint_rows(path)`. Invalid input raises `ValueError`; CLI failures exit 2. Full reconciled CLI models automatically use `.planning/REQUIREMENTS.md` if the optional flag is omitted; singleton API fixtures remain renderable.
- `tests/test_fidelity_ledger.py`: 31 behavior/integration regressions, including actual imported synthetic receipts and the genuine historical startup evidence/viewer round trip.
- `docs/evidence/README.md`: generated capability-first navigation, exact current targets, expandable history, remaining acceptance and source reconciliation. It is not independently maintained status.
```sh
python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md
python3 tools/recon/fidelity_ledger.py render --ledger docs/evidence/capabilities.json --output docs/evidence/README.md
python3 tools/recon/fidelity_ledger.py export --ledger docs/evidence/capabilities.json --output artifacts/fidelity/review/ledger.json
python3 tools/recon/fidelity_review.py export --ledger artifacts/fidelity/review/ledger.json --output artifacts/fidelity/review/new-review
```
Viewer input uses the established capability contract and source links `{label,path,sha256?}`. It adds contained copied `href/validated_local/sha256/size/missing` fields. Ledger source text is contained, tracked, UTF-8/non-NUL and at most 1 MiB per file. Optional source hashes and actual artifact identities are checked. Generated output stays local under the project or `/tmp`, rejects symlinks, and cannot overwrite originals/Git metadata or the authoritative input. No new package dependency, service, runtime endpoint or original-binary investigation was introduced.
## Evidence and Acceptance Limits
The expansion's current evidence records are explicitly **static documentary coverage**, bound to retained report content and named documentary scopes. They do not manufacture fresh component or native receipts. Implementation revisions identify recorded code changes separately from runtime/package identity. Existing copied-original/managed/Linux scene results are described with their narrower scope. Historical package revisions remain exact: current packaged924ad2f versus earlier ea04210 Wine64 and later integrated bf876e9 source checks are not conflated. Scooter/Rocketship milestones and current bounded scene limitations remain visible.
No new game, GPU, DxWnd, Wine or Windows execution, build or package was performed. Native Linux/Windows/original reference captures and human audiovisual review remain open at **0/120 actual obligations**. Shared EVID-03 is not checked complete in REQUIREMENTS.md. The preserved TSK correction is implemented, not an untouched defect; no leveling reset, movement replacement, new gadget, actor admission or lab/outside solver replacement was made. Missing generated original/native recordings retain explicit reasons in the startup evidence rather than being dropped.
## TDD Gate Compliance
- Task 1 RED evidence: `artifacts/fidelity/tdd/01-03-01-red.json`, recorded before implementation; the real CLI-presence/round-trip target failed its intended planned behavior assertion. Existing RED/GREEN commits and the previously verified 18-test tracer were reconciled rather than repeated.
- Task 2 RED evidence: `artifacts/fidelity/tdd/01-03-02-red.json`; the named full-game set-equality target ran and failed because only two movement requirements were mapped. The actual 26-test report retains the three expected missing coverage/reconciliation/unimplemented assertions. The classifier was re-run on resume and returned `RED_EVIDENCE_OK`; semantic inspection confirms intended assertions, not setup/import failures. Final suite passes all 31 tests.
- Each RED commit precedes its GREEN by ancestry. No separate refactor was necessary. Both exact counted plan commands and full 33-ID validation pass; singleton/negative cases remain covered. No skipped tests or unrun planned automated checks remain.
## Decisions Made
One JSON source owns all navigation. Current evidence selects exact content/platform/scope, including explicitly named historical bytes; latest documentation dates do not imply newer execution. Full-game rows and source-row reconciliation expose unfinished work without expanding gameplay. Future imported receipt references require exact receipt SHA-256 plus matching platform/scope/category/history.
## Deviations from Plan
No architecture or scope change. During planned validation, report-content hash binding, ledger-wide receipt duplicate checks, complete category validation and actual imported-receipt identity matching were completed as correctness controls for T-01-07/08. These are within the planned evidence-validation boundary and commit `4d07d60`.
## Threat/Test Coverage
| Threat | Implemented controls and verification |
|---|---|
| T-01-07 | Exact named content/platform/scope targets, explicit supersession/cycles and contradictory-current rejection; changed runtime/resource/package, docs-only and imported receipt tests |
| T-01-08 | Byte-identical duplicate merging, global receipt conflicts, stable ordering and 33 hashed source-row reconciliation entries; retained linked source required |
| T-01-09 | Escaped Markdown, bounded contained tracked UTF-8 source references, actual hashes, no imported command execution; hostile source and real viewer-copy tests |
| T-01-SC | Python standard library only; no package installation |
No additional threat surface beyond the plan's existing local file/navigation boundary was introduced. Cooperative local filesystem assumptions remain; revalidate/re-export after evidence changes.
## Issues Encountered
The user-requested pause interrupted task 2 after its RED commit and 41-line patch. Resume preserved those changes, validated ancestry/evidence and completed GREEN. Primary-owned HANDOFF deletion/STATE/continuation edits and untracked `tools.yaml` were preserved. Socket/Node checks used authorized local-test escalation to avoid the known sandbox false failures/file-only results. All-fidelity log: ignored `artifacts/fidelity/verification/01-03-all-python.log`.
No implementation stubs remain. Missing real recordings and unimplemented full-game workflows are intentional transparent evidence/coverage states whose later owning plans/phases remain open.
## User Setup Required
None for these local tooling checks. The combined Windows/original/native capture and human audiovisual session belongs to later plans; no premature hands-on request was created.
## Next Phase Readiness
Plans 01-04 through 01-07 can consume the coordinated ledger and provide real observer/checkpoint/capture receipts. The primary owns root continuity documents, consumed handoff cleanup, wave regression checks and push. Full-game and phase acceptance remain separate from this completed ledger implementation.
## Self-Check: PASSED
All four created files exist; all four task commits are ancestors of HEAD and evaluation-scope resolves them on this branch. Both exact counted plan checks, full 33-requirement/six-group/33-row validation, real CLI/viewer round trip, 103 fidelity Python tests, 27 named Node tests, whitespace checks and 539 original hashes pass. No tracked production deletions, skipped tests, placeholder implementation or unexplained generated untracked output was introduced.
@@ -0,0 +1,108 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "04"
type: execute
wave: 2
depends_on: ["01-01"]
files_modified:
- src/GamePort/Application/FidelityObservation.cs
- src/GamePort/Program.cs
- tests/GamePort.FidelityObservationTests/GamePort.FidelityObservationTests.csproj
- tests/GamePort.FidelityObservationTests/Program.cs
- tests/test_fidelity_observation.py
autonomous: true
requirements: [EVID-02, EVID-04]
estimate:
tokens: 33000
raw_tokens: 33000
tasks: 2
confidence: low
must_haves:
truths:
- "An optional passive observer records actual native port input/control/scene events across the continuous route per D-01, without changing gameplay or scene lifetime."
- "Natural/skipped and fresh/retained runs have distinct case identities, with one monotonic session across actual retained continuations per D-02 and D-03."
- "Held/neutral input, banked jump, landing and idle observations retain their real owner/tick/time per D-04; injected smoke fixtures stay separately classified."
- "An output failure leaves the observation incomplete and visible rather than reporting acceptance or changing movement/state to finish the recording."
artifacts:
- path: src/GamePort/Application/FidelityObservation.cs
provides: "Optional passive bounded JSONL session observer"
- path: tests/GamePort.FidelityObservationTests/Program.cs
provides: "Managed clock/order/ownership and failure regressions"
- path: tests/test_fidelity_observation.py
provides: "Process-level observer output and receipt interoperability checks"
key_links:
- from: src/GamePort/Program.cs
to: src/GamePort/Application/FidelityObservation.cs
via: "Outer Run continuation lifetime and actual post-Step acceptsInput result"
- from: "Observed events.jsonl"
to: tools/recon/fidelity_receipts.py
via: "Case/session identity, monotonic elapsed and separately labeled simulation tick"
---
<objective>
Supply the native port input/event evidence that existing smoke screenshots/logs cannot provide: accepted input and control ownership, with one lifetime across normal scene continuations. Observe existing behavior; do not repair any movement, rotation, body, camera or gameplay contract.
Artifacts this phase produces in this plan: FidelityObservation with session-owned clock, RecordInput/RecordControl/RecordTransition/Complete/Dispose methods; --fidelity-output PATH, --fidelity-session ID and --fidelity-case ID options; events.jsonl and observation-summary.json under a new generated session directory; standalone net10.0 observation test project and Python interoperability tests. All symbols/options are new observer interfaces, not existing/recovered gameplay APIs.
</objective>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-PATTERNS.md
@.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-04-01">
<name>Observe one real port input-to-control step through a recorded session</name>
<files>src/GamePort/Application/FidelityObservation.cs, src/GamePort/Program.cs, tests/GamePort.FidelityObservationTests/GamePort.FidelityObservationTests.csproj, tests/GamePort.FidelityObservationTests/Program.cs, tests/test_fidelity_observation.py</files>
<read_first>src/GamePort/Program.cs outer presentation/Run loop, SDL polling, PlayerInput construction, playerBinding.Step return and continuation publication; src/GamePort/Application/CutsceneIdleSmoke.cs; tests/GamePort.BodyOwnershipTests/GamePort.BodyOwnershipTests.csproj; 01-PATTERNS.md Optional FidelityObservation; docs/gameplay/main-menu-player-lifetime.md; docs/checkpoint/README.md, coverage.md and implementation-plan.md.</read_first>
<behavior>Managed tests execute at least eight checks for disabled no-op behavior, session identity, monotonic clock, requested versus accepted input, control/tick distinction, bounded output, output exception and correct disposal. Python adds at least four subprocess/interoperability checks proving actual emitted records validate and missing/incomplete records cannot qualify as native gameplay.</behavior>
<action>Write tests first and link the focused observer source into a standalone net10.0 console test project, following existing test conventions. Existing Program logging lacks ordinary accepted-input/timestamp continuity, so add a separate passive observer only at the application boundary. Allocate it once beside the outer RenderSession/Run loop, with a single Stopwatch spanning continuations; inject its reference into Run without creating a second gameplay owner. New options explicitly enable output, carry stable session/case IDs and require a new contained output directory separate from originals. On one actual step record requested PlayerInput values, accepted-input result after playerBinding.Step (or existing direct simulation.Step path), current control ownership, scene, monotonic time and simulation tick separately. Raw polled events, if captured, are labeled raw and never passed off as accepted gameplay input. Emit immutable copied observations after existing owner calls without invoking extra getters/callbacks that mutate game state. Keep observer-off paths behavior-identical. Handle bounded buffering/disk errors visibly in an incomplete observation summary; recording failure must not trigger a simulation reset, extra stepping or modified input. Add a subprocess end-to-end test using a bounded existing smoke invocation with observer output, explicitly classified synthetic/fixture, then validate its output through the receipt contract. This proves observation wiring only; ordinary native play remains required.</action>
<acceptance_criteria>A real port process emits a case-bound observation from input through control decision and file output; counted managed/Python checks pass; disabled observation and write errors preserve game update/state semantics; all fixture results retain their narrow method.</acceptance_criteria>
<verify>
<automated>bash -lc 'source scripts/env.sh && dotnet run --project tests/GamePort.FidelityObservationTests'</automated>
<fails_when>Nonzero exit or missing summary Fidelity observation checks: N passed with N at least 8; any clock/input/ownership/error assertion fails.</fails_when>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_observation.py"); assert s.countTestCases() >= 4,"fewer than 4 observer integration tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than four tests, no actual process output, or incomplete/fixture records incorrectly qualify as native gameplay.</fails_when>
</verify>
<done>Optional passive input/control observation works through the real port process and remains outside gameplay behavior and acceptance classification.</done>
</task>
<task type="auto" tdd="true" id="01-04-02">
<name>Preserve observation identity across dialogue and retained scene lifetimes</name>
<files>src/GamePort/Application/FidelityObservation.cs, src/GamePort/Program.cs, tests/GamePort.FidelityObservationTests/Program.cs, tests/test_fidelity_observation.py</files>
<read_first>Task 01-04-01 observer interfaces; Program.cs actual dialogue skip/control changes and continuation publication; docs/evidence/scenarios.json; protected movement/startup reports.</read_first>
<behavior>Extend managed checks to at least 14, covering natural/skip event distinction, requested held input while input is rejected, first accepted neutral/held step, ordered transition/RETURN records, monotonic continuation time and independent fresh session time. Compare observed/off deterministic state through existing fixtures.</behavior>
<action>Add observation records at actual existing dialogue/control changes and continuation publication per D-01–D-04, preserving exact player/save/return payloads and call order. Give transitions ordered sequence IDs and pair departure/destination in one session without restarting the outer clock. Keep fresh launches independent. Mark natural versus skip from the actual action path, not guessed elapsed duration; publish neutral/held acceptance and landing/bank/idle only from existing owner state observations or external annotations with explicit method. No new physics contacts, setters, orientation resets, cached callback data or actor admission. Annotate observation overhead in provenance; clean external audiovisual recordings and diagnostic observer runs remain distinguishable. Extend process-level tests to confirm fixture on/off state/readback equivalence and shared-session continuity, without calling synthetic transitions ordinary-route evidence. Run existing protected regressions and build; capture a bounded native Linux smoke with observer on/off if display is available, retaining actual readbacks and limitation if unavailable. Native full-route capture is owned by plan 01-06.</action>
<acceptance_criteria>All 14 managed checks pass; real continuation records preserve identity/order/clocks; protected movement/Director/Checkpoint/BodyOwnership checks remain passing; runtime diff contains passive observer plumbing only.</acceptance_criteria>
<verify>
<automated>bash -lc 'source scripts/env.sh && dotnet run --project tests/GamePort.FidelityObservationTests && dotnet build GamePort.csproj --no-restore'</automated>
<fails_when>Nonzero exit, missing at-least-14 positive observer check summary, or any build error.</fails_when>
<automated>bash -lc 'source scripts/env.sh && dotnet run --project tests/GamePort.MovementTests -- ../Original && dotnet run --project tests/GamePort.DirectorTests -- ../Original && dotnet run --project tests/GamePort.CheckpointTests -- ../Original && dotnet run --project tests/GamePort.BodyOwnershipTests'</automated>
<fails_when>Nonzero exit or an absent/zero group-count summary from any protected regression; state/readback equivalence differs.</fails_when>
</verify>
<done>Continuous observations preserve real control and retained lifetimes while all protected gameplay contracts remain unchanged.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; unresolved high/critical threats block acceptance.
| Boundary | Description |
|---|---|
| Runtime observation → local output | Optional diagnostic writes cannot own or modify gameplay state |
| CLI output path → filesystem | Caller-controlled paths must remain outside originals and existing sessions |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-10 | Tampering | Observer output | high | mitigate | Exclusive contained output, no gameplay callbacks/setters/retries and observed/off equivalence checks |
| T-01-11 | Denial of service | Observation buffering | medium | mitigate | Bounded records/buffer, explicit incomplete summary on write failure, reliable disposal |
| T-01-12 | Spoofing | Input/control records | high | mitigate | Distinct raw/requested/accepted observations, one session clock and fixture/native classification |
| T-01-SC | Tampering | Package installation | high | mitigate | Existing .NET framework/runtime dependencies only; no new NuGet packages |
</threat_model>
<verification>Run counted observation tests and protected managed regressions; inspect passive application-only diff. Full local suite runs during checkpoint integration. No body/movement/source algorithm edits are authorized.</verification>
<success_criteria>Native port recording can include truthful input/control/scene traces with preserved lifetime and source behavior.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-04-SUMMARY.md with observation semantics, overhead and actual protected checks.</output>
@@ -0,0 +1,197 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "04"
subsystem: testing
tags: [dotnet, passive-observation, jsonl, sdl, vulkan, provenance]
requires:
- phase: 01-01
provides: Version 1 receipts and separately classified scenario observations
provides:
- Optional bounded application observer with requested/accepted input and immutable state snapshots
- One launch clock and ordered departure/arrival records across retained scene composition
- Explicit script/skip/control methods, incomplete failure summaries and observer-on/off regressions
affects: [01-05, 01-06, 01-07, native-capture]
tech-stack:
added: []
patterns: [standalone net10 console tests, streamed bounded UTF-8 JSONL, snapshot-only application diagnostics]
key-files:
created:
- src/GamePort/Application/FidelityObservation.cs
- tests/GamePort.FidelityObservationTests/GamePort.FidelityObservationTests.csproj
- tests/GamePort.FidelityObservationTests/Program.cs
- tests/test_fidelity_observation.py
modified:
- src/GamePort/Program.cs
key-decisions:
- "One outer observer owns a unique launch/clock identity through Run continuations; simulation ticks remain scene-local and case/session IDs remain declared provenance."
- "Accepted input means the existing binding's returned gate result, with separately identified post-step ownership; individual command dispatch and independent body/fire work are not inferred."
- "Observer records are diagnostic source material for later collectors, not receipts or automatic original/native acceptance; fixture classification survives continuations."
patterns-established:
- "Copied values only: no simulation references, gameplay callbacks, setters, extra steps or recovery resets enter the observer."
- "Caller-selected new local output supports standalone checkpoint/transfer folders while rejecting protected asset/Git overlap, aliases, symlink ancestry and reused sessions."
requirements-completed: [EVID-02, EVID-04]
requirements-acceptance: "OPEN: assigned observation contribution only. Shared requirements remain Pending; actual original-DxWnd/native Linux/native Windows comparison acceptance remains 0/120."
coverage:
- id: observer-semantics
description: Bounded requested/accepted input, identity, clocks, disposal and output failure preserve simulation behavior
requirement: EVID-02
verification:
- kind: unit
ref: tests/GamePort.FidelityObservationTests/Program.cs
status: pass
- kind: integration
ref: tests/test_fidelity_observation.py
status: pass
human_judgment: false
- id: retained-observation
description: Real port fixture publishes LV1B to VR04 to LV1B with one ordered launch clock and paired departure sequences
requirement: EVID-04
verification:
- kind: integration
ref: tests/test_fidelity_observation.py#test_retained_continuation_keeps_one_ordered_session_clock
status: pass
human_judgment: false
- id: passive-runtime-comparison
description: Existing bounded headless and native SDL Carl fixtures preserve exact state and four GPU readbacks with observation on/off
verification:
- kind: integration
ref: tests/test_fidelity_observation.py#test_observed_off_fixture_state_and_readbacks_match
status: pass
- kind: other
ref: artifacts/fidelity/verification/01-04-native-1794543576213164551/comparison.json
status: pass
human_judgment: false
- id: actual-scenario-acceptance
description: Identified ordinary full-route original/native audiovisual comparison
verification: []
human_judgment: true
rationale: "Injected fixtures, observer traces and compilation do not supply ordinary play, physical audio/input or native Windows/original-DxWnd review; later capture plans retain these obligations."
actuals:
tokens: 13375
tasks: 2
commits: 4
basis: "ceil(chars/4) over the realized five-file production/test diff (53497 characters), excluding planning metadata; commits measured from the persisted ledger."
plan_head_before: e8155348950e997462f4d097a0e323c7f17b75fb
plan_head_after: ea4dc9b5dfb84b1d590dae049cabb4a262a5138c
duration: 16 min
started: 2026-11-13T04:04:37Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 04: Passive Port Observation Summary
**Bounded JSONL observations preserve requested input, the real accepted-input gate, control changes and retained scene identity without changing player ownership or movement.**
## Performance
- Two tasks, five production/test files, four measured task commits. Started 04:04:37 UTC; final production verification/commit completed about 04:20 UTC, 2026-11-13.
- Final focused verification: **23 managed checks**, **7 Python process/interoperability tests in 19.126 seconds**. The tracer passed 10 managed/four process checks and repeated its automated gate before expansion.
- Protected projects: **Movement 28**, **Director 23**, **Checkpoint 4**, **BodyOwnership 3** actual passing groups. Existing projects without aggregate totals were additionally captured and counted from their executed PASS lines in `artifacts/fidelity/verification/01-04-protected.json` and per-project logs.
- Debug build and isolated self-contained Linux x64 Release publish succeed. The existing NU1900 warning concerns unavailable NuGet vulnerability metadata; no package was added or installed. All **539 original hashes** match.
## Accomplishments
- `FidelityObservation` is allocated once beside the outer presentation lifetime and passed through `Run`. A unique `launch_id`/`clock_id`, one Stopwatch and increasing sequence survive actual continuations. Simulation ticks remain explicitly separate and can reset at scene entry. Fresh observer instances get independent launch clocks even if a caller mistakenly repeats its declared session ID.
- The ordinary application input seam records the constructed `PlayerInput` and the actual `playerBinding.Step` return, or the existing direct simulation path. It copies post-step root, Euler, velocity, grounded/mode, retained-order flag and controller/body/effect counters. No recovered gameplay algorithm, orientation/reset policy, callback getter, actor admission or solver changed. Disabled observation allocates no observer or additional asset lookup; snapshots execute only through the optional observer path.
- SDL events are labeled raw before routing; only applicable keyboard/mouse union fields are copied. Requested input, returned gate and post-step control owner remain distinct. Script activity/control snapshots surround existing director calls. Explicit skip methods include startup/fixture, debug menu and actual SDL key paths; a playing-to-stopped boundary during the normal director step is identified as `natural_director_step`, without elapsed-time guesses.
- Scene composition records its actual entry path and retained-player/RETURN facts. Published continuations record departure source/destination and RETURN status; each following entry links the actual `departure_sequence`. The real existing fixture emits **LV1B → VR04 → LV1B**, retains one session/category/clock, and records two paired departures. This proves observer wiring through ordinary composition using fixture-owned setup; it is not ordinary-route acceptance.
- Output failure disables recording, retains an incomplete summary/stderr diagnostic and permits the existing game calls to continue. The managed failure regression compares 120 actual `LabSimulation` steps with failed observation versus off, including exact root/Euler/velocity and controller/body/effect counts. On/off headless and native SDL fixtures additionally preserve the existing locked body/fire/energy, first-neutral/300-idle assertions and held-input restoration.
## Task Commits
1. Task 01-04-01 RED: `773c228` — specify passive port input observation.
2. Task 01-04-01 GREEN: `72523ee` — observe accepted input with bounded passive output.
3. Task 01-04-02 RED: `6bccd47` — require retained session and dialogue observation.
4. Task 01-04-02 GREEN: `ea4dc9b` — preserve observer identity through control and scene changes.
Normal hooks ran, scoped staging preserved `tools.yaml`, and no tracked files were deleted. Main commits use the authorized configuration; the integrating primary owns push and root continuity reports.
## Files and Interfaces
- `src/GamePort/Application/FidelityObservation.cs`: optional `FromArguments`/`Create`, `RecordInput`, `RecordControl`, `RecordTransition`, `RecordSceneEntry`, `RecordRawEvent`, `RecordState`, `Complete` and `Dispose`. It holds copied diagnostic values and output ownership only.
- `src/GamePort/Program.cs`: optional CLI flags, one outer observer and post-owner/input/control/continuation seams. Skip and director-step wrappers preserve the original call and surrounding order. Existing helper-internal fixture steps remain outside this trace.
- Standalone `tests/GamePort.FidelityObservationTests` links focused observer plus existing assets/game sources, uses net10.0 and adds no packages. Its 23 Linux checks cover disabled operation, IDs/clocks, requested/rejected/accepted neutral input, ownership/ticks, bounds, write/flush/disposal failure, duplicate/unsafe output, real simulation parity and retained/fresh sequencing. Two symlink checks are Linux-specific; this run is not native Windows validation.
- `tests/test_fidelity_observation.py`: seven actual-port subprocess checks, hashed receipt interoperability, rejected fixture promotion/missing output, retained composition, explicit skip semantics and exact four-image/state equivalence. It builds current source before launching the actual DLL; if generated fixture resources are absent, it uses the existing local preparation command because the consolidated script runs Python before its own extraction step.
Example diagnostic invocation, with a **new** output directory:
```sh
source scripts/env.sh
dotnet run -- --fidelity-output artifacts/fidelity/new-session \
--fidelity-session unique-launch-session --fidelity-case fresh-natural-ordinary
```
IDs accept 1–128 safe alphanumeric/dot/underscore/hyphen characters. The output directory is caller-selected and need not live in a checkout: standalone package checkpoint results and local transfer folders work. Known original/source asset roots and Git metadata cannot overlap output in either direction. Protected asset aliases are resolved; output symlink ancestry and existing directories/files are rejected. A cooperative exclusive sibling reservation and `CreateNew` owned files prevent session reuse. Hostile concurrent filesystem replacement is outside this cooperative local model.
`events.jsonl` schema 1 fields are `session_id`, `case_id`, `evidence_kind`, unique `launch_id`, `clock_id`, increasing `sequence`, `elapsed_seconds`, separate `simulation_tick`, `name`, `scene`, `method` and immutable `data`. Names include `input_step`, `player_state`, `raw_sdl_event`, `control_observation`, `dialogue_start`, `dialogue_end`, `dialogue_skip`, `scene_departure` and `scene_entry`. Dialogue markers describe observed director script activity and explicit action paths, not inferred per-utterance audio timing. `accepted_input` copies the request only when the existing gate returned true; it does not assert that each input field dispatched an action. Independent body/fire work can continue when that gate is false.
`observation-summary.json` records UTC start/end, elapsed/clock identities, count/bytes, limits, completion/failure and overhead scope. It begins incomplete, remains incomplete after abort/error/bounds/disposal without completion, and is atomically updated after successful flush. A write failure never asks gameplay to retry, reset or step. If even the summary cannot be written, stderr explicitly reports that failure; a reserved prior incomplete summary is never promoted.
The writer uses a 64 Ki-character StreamWriter buffer, no growing record queue, at most **250000 records / 512 MiB**, and normalized UTF-8 LF output. These bounds can truncate long diagnostic sessions explicitly. `observer_seconds` measures serialization/write attempts only; caller snapshots, control comparisons, final flush and summary work are excluded, and this limitation is in provenance. No trace is represented as a clean, zero-overhead audiovisual run.
These are observer records, not shared receipt objects. The later collector must identify actual artifacts and map actual media clocks with uncertainty. Tests build an explicitly bounded `port_fixture` receipt from the trace interval, hash the actual trace, and validate it through the existing schema-1 receipt contract without changing that shared module. They do not invent a video/audio clock or promote native acceptance.
## Native Linux Evidence and Limits
Final evidence: `artifacts/fidelity/verification/01-04-native-1794543576213164551/comparison.json`, on/off `port.log`, eight retained PPM files and the actual observation directory. Both native SDL/Vulkan runs use a private Xvfb X11 display on **NVIDIA GeForce GTX 1070**, enabled validation, 32 frames and **zero Vulkan validation errors**. The existing injected Carl control fixture is muted; both runs exit 0. All four corresponding readbacks are byte-identical:
| Readback | SHA-256 |
|---|---|
| locked-start | f0d76654f1196534da20b7cf9a39c5e58931acb7f0aa22d349e87dad6ce176a2 |
| locked-fall | f0819d2dd9a43ff17b339be2bb3b487c3a94c4683e951015f38cd9b4f7c12e38 |
| returned | 642e15ad552c1c5819f41faf7b1bcbb9106462a26b6786753dd2f87f90cf4229 |
| final | e0e71f3c7f187149fc1b5b9d8c7fb7ff694f5ae3f27275a20948543a4f55fdfa |
The final observed run records **88 records / 65308 bytes**, 1.6721105 session seconds and 0.0365354 measured serialization/write seconds. Whole process durations are 1.5783 seconds off and 1.8555 seconds on; a single ordered pair is not an overhead benchmark. Actual Debug DLL SHA-256 is `778a1827d22c5359216c546b1841cea20fffca6a4bece2266a58057c8d24a348`, 776704 bytes. The report retains the actual pre-commit source identity: HEAD `6bccd47`, dirty true, diff SHA-256 `83eac9c22938f1f8d01200027e2fa3aefbe4ba123a9c58dc7bb6a7d9ce5ac33d`, plus unrelated preserved `tools.yaml` identity. Task GREEN commits that tested source; no clean-runtime claim is inferred from the later commit.
Exact state assertions and readbacks preserve the existing TSK first-story ordering correction, grounded neutral return, heading and legitimate source landing behavior. The fixture's deliberate preparatory calls remain fixture setup, not a newly invented reset. Full original playback, physical input/audio, ordinary full-route play, native Windows and broader platform compatibility remain unverified by this plan. **Actual matrix acceptance remains OPEN 0/120.** Plan 01-06 owns native full-route capture; Windows/original collection and review remain later work.
## TDD Gate Compliance
- Task 1: `artifacts/fidelity/tdd/01-04-01-red.json` contains the actual complete unittest report. The real port help succeeded but the named target failed its intended missing `--fidelity-output` assertion. Classifier result: `RED_EVIDENCE_OK`; semantic inspection confirms a planned behavior assertion rather than build/import/setup failure. The tracer's exact focused checks were repeated before expansion.
- Task 2: `artifacts/fidelity/tdd/01-04-02-red.json` contains the actual complete report. The existing real RETURN fixture succeeded, then the named target failed `[] != ['LV1B', 'VR04', 'LV1B']` because scene-entry observations were absent. Classifier result: `RED_EVIDENCE_OK`; semantic inspection confirms the intended sequencing assertion executed. Final 23 managed/seven process checks pass.
- Both RED commits precede their GREEN by ancestry. No separate refactor was required. No skipped/todo tests or unrun planned automated checks remain.
## Deviations from Plan
No architectural or gameplay scope change. Two bounded correctness adjustments remain within the planned application/test boundary:
1. **[Rule 2 — protected output]** Resolve source asset aliases and protect the checkout's known authoritative sibling even when `--assets` points to a generated copy. Otherwise lexical overlap alone could miss the original boundary. Managed source/output alias negatives pass; `ea4dc9b`.
2. **[Rule 3 — fixture preconditions]** Process tests build the current actual port and prepare missing generated resources through the existing extractor. The consolidated script schedules Python before its normal preparation/build steps; assuming prior generated files would make a clean test environment fail. No shared script or extractor was modified; `ea4dc9b`.
## Threat/Test Coverage
| Threat | Controls and actual verification |
|---|---|
| T-01-10 | New exclusive contained output, protected resolved asset/Git boundaries, symlink/reuse negatives, immutable values only; exact 120-step failed-writer parity and headless/native four-readback equivalence |
| T-01-11 | Fixed buffering, record/byte caps, incomplete initial/failure summaries, flush/disposal failure handling; managed bounds and exception regressions |
| T-01-12 | Distinct raw/requested/gate/post-step owner fields, actual director action methods, unique launch clock, ordered retained entries/departures, persistent fixture classification; process and shared-validator negatives |
| T-01-SC | Existing .NET framework/runtime, Python stdlib and already-installed native tools only; no added packages, services or downloads |
The new filesystem surface is exactly the plan's runtime-observation/local-output boundary; no additional network/auth/gameplay trust surface was introduced. Stub scan found only intentional optional/absent fields and test-only empty receipt identities, not unfinished implementation or UI mock data.
## Issues Encountered
The sandboxed first native-display attempt reported no video device. Authorized local-test escalation with explicit X11 on private Xvfb succeeded; both attempts remain in ignored diagnostics. A second `-o` passed to `scripts/build-linux.sh` was rejected by the .NET CLI, so the equivalent publish invocation used an isolated output to preserve existing `dist/` packages:
```sh
source scripts/env.sh
dotnet publish GamePort.csproj -c Release -r linux-x64 --self-contained true \
--no-restore -o artifacts/fidelity/verification/01-04-linux-publish
python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
```
Both commands pass on final code. Existing packaged runtime outputs were not replaced. NU1900 remains a pre-existing offline audit warning, not an observer failure. No new original-binary investigation, REA claim, Wine result or native Windows execution occurred.
## User Setup Required
None for these local checks. The later combined original/native recording and human audiovisual review session remains open; this plan creates no premature hands-on request.
## Next Phase Readiness
Plans 01-05/01-06 can launch the optional observer into a new checkpoint result directory and consume its honest trace/summary while binding actual package/artifact/media provenance separately. The primary owns root progress/tasks/decisions/compatibility integration, broader wave checks and push. Shared EVID-02/EVID-04 remain Pending until all owning plans and actual acceptance conditions close.
## Self-Check: PASSED
All created files exist; all four task commits are ancestors of HEAD and evaluation-scope resolves them on this branch. Exact counted observer commands, positive protected groups, Debug/isolated Linux publish, final native state/four-readback equality and 539 original hashes pass. Native JSONL byte count matches the summary's actual file size. No tracked deletions, skipped tests, implementation stubs or unexplained generated untracked files were introduced; unrelated `tools.yaml` is preserved.
@@ -0,0 +1,113 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "05"
type: execute
wave: 3
depends_on: ["01-02", "01-03", "01-04"]
files_modified:
- tools/recon/fidelity_checkpoint.py
- scripts/prepare-fidelity-checkpoint.sh
- scripts/collect-fidelity-windows.ps1
- scripts/collect-fidelity-windows.cmd
- tests/test_fidelity_checkpoint.py
- tests/fidelity-windows.Tests.ps1
- docs/evidence/windows-session.md
autonomous: true
requirements: [EVID-01, EVID-02, EVID-04]
estimate:
tokens: 34000
raw_tokens: 34000
tasks: 2
confidence: low
must_haves:
truths:
- "One complete local checkpoint bundle contains identified port packages, a verified generated original copy, scenarios, viewer and result collection per D-14."
- "The available Windows PC is treated as a pending execution environment per D-13; actual OS/GPU/driver/tool identities are collected during the session."
- "The original launches only from a generated copy through the user's identified DxWnd binary/exported profile, separately from native port receipts, per D-15."
- "All original-reference and port materials are prepared before one combined session per D-16; preparation does not close EVID-02 or EVID-04."
- "Launcher preflight or recording failure produces an actionable local failure receipt without inventing successful capture or downloading dependencies."
artifacts:
- path: tools/recon/fidelity_checkpoint.py
provides: "Offline checkpoint manifest/preflight and bundle assembly"
- path: scripts/collect-fidelity-windows.ps1
provides: "Native Windows local preflight/launch/collection"
- path: docs/evidence/windows-session.md
provides: "Single combined-session instructions and local result transfer"
key_links:
- from: scripts/prepare-fidelity-checkpoint.sh
to: tools/recon/fidelity_checkpoint.py
via: "Consumes completed package bytes and validated scenario/ledger/viewer artifacts"
- from: scripts/collect-fidelity-windows.ps1
to: tools/recon/fidelity_receipts.py
via: "Same schema-versioned per-run receipt contract and byte identities"
---
<objective>
Prepare the complete local Windows original-DxWnd/native-port checkpoint per D-13–D-16, without asking the user to execute partial materials.
Artifacts this phase produces: fidelity_checkpoint.py prepare/preflight CLI; scripts/prepare-fidelity-checkpoint.sh; scripts/collect-fidelity-windows.ps1 and .cmd; tests/test_fidelity_checkpoint.py; tests/fidelity-windows.Tests.ps1; windows-session.md. The generated dist/fidelity/phase01 checkpoint contains manifest.json, READY.json, original-pristine/, original-runs/, port/win-x64/, port/linux-x64/, review/, protocol/, results/ and local launchers. READY means materials prepared, never acceptance passed. No media/packages are committed or uploaded.
</objective>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-RESEARCH.md
@.planning/phases/01-reproducible-fidelity-baseline/SKELETON.md
@.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-03-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-04-SUMMARY.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-05-01">
<name>Prepare one runnable checkpoint case through package identity, launch plan and collected result</name>
<files>tools/recon/fidelity_checkpoint.py, scripts/prepare-fidelity-checkpoint.sh, scripts/collect-fidelity-windows.ps1, scripts/collect-fidelity-windows.cmd, tests/test_fidelity_checkpoint.py</files>
<read_first>scripts/package.sh; scripts/build-linux.sh; scripts/build-windows.sh; tools/recon/fidelity_receipts.py; tools/recon/fidelity_review.py; docs/evidence/scenarios.json; 01-RESEARCH.md Minimum Viable Windows Recording and Bundle.</read_first>
<behavior>At least 12 Python tests prepare→preflight→fixture-result-import one checkpoint case, compare actual package/resource and original hashes, reject output overlap/reuse, stale/missing binary/resources, tampered launcher/media, interrupted/concurrent assembly and missing dependencies. Fixture collection cannot qualify as native Windows.</behavior>
<action>Create failing tests first. Assemble a complete offline tree consuming actual finished package bytes and their BUILD-INFO rather than stamping the current docs revision onto old DLLs. Use scripts/package.sh locally if new observer packages are needed; retain its original identity fields and add a separate canonical manifest excluding its own output to avoid self-hashing. Record actual runtime source/dirty/diff identity, executable/resource/package tree hashes, original manifest hash and launcher/viewer hashes. Verify originals before copying; retain a pristine generated original seed and make a fresh writable original-runs copy per fresh case, preserving retained case state explicitly. Launchers are script-relative and quoted; no shell/eval or commands supplied by receipts. Implement one complete case path: preflight byte identities and dependencies, select actual tool/profile, start original-DxWnd or native port as separate explicit modes, collect invocation/exit/log/artifact metadata and publish a truthful receipt/failure. Do not assume DxWnd command switches/profile correctness: inspect the selected local distribution's help/config inside the final session, retain original exported profile plus any relocation-only edits, and provide transparent manual launch if automation is unsupported. Windows requires neither Python nor SDK for the self-contained port/PowerShell collector. Retain launcher/profile hashes, Windows/GPU/driver/SDL/Vulkan evidence as actually available. Hash incrementally and bound file counts, sizes and process waits. Bundle test round trips use deliberately synthetic executables/media and are labeled tooling-only. Original/native launch remains an actual final-session check.</action>
<acceptance_criteria>One checkpoint fixture travels through preparation, preflight and schema-valid import; an actual offline package tree can be assembled without original writes or external services; failures identify exact missing/tampered dependencies; Windows runtime remains pending.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_checkpoint.py"); assert s.countTestCases() >= 12,"fewer than 12 checkpoint tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 12 tests, missing end-to-end bundle import, or tampered/partial/tooling-only evidence incorrectly passes.</fails_when>
<automated>bash -n scripts/prepare-fidelity-checkpoint.sh</automated>
<fails_when>Nonzero exit or shell syntax diagnostic.</fails_when>
</verify>
<done>One production checkpoint path exists from completed local package to identity-bound result, with Windows execution explicitly pending.</done>
</task>
<task type="auto" tdd="true" id="01-05-02">
<name>Complete all session materials and collect audiovisual results without fragmented requests</name>
<files>scripts/collect-fidelity-windows.ps1, scripts/collect-fidelity-windows.cmd, tests/fidelity-windows.Tests.ps1, docs/evidence/windows-session.md, tests/test_fidelity_checkpoint.py</files>
<read_first>01-CONTEXT.md D-01–D-04 and D-13–D-16; docs/evidence/scenarios.json; receipt schema; 01-RESEARCH.md assumptions A1/A2 and Windows sequence.</read_first>
<behavior>Extend checkpoint tests to at least 16 checks for all matrix/materials, explicit original/native categories, abort/skip receipts and bundle readiness distinct from acceptance. Create package-free PowerShell tests with at least eight checks for identity/path/argument/exit/result functions; Windows execution is deferred to the same final session.</behavior>
<action>Finish launcher/checklist for all eight matrix cells, continuous/focused obligations, native port and original-DxWnd modes. Put one ordered combined agenda in windows-session.md: local dependency selection; versions/hashes/config capture; short original and port visual/audio preflights; all required runs; paired browser/audio review; result collection/postflight; one local return transfer. Initial OBS recommendation is offline Display Capture, with actual selected tool/version/source/settings recorded. Retain raw MKV plus any verified browser preview, exact derivation command/tool/version/timestamp/crop/aspect metadata; never discard the raw recording. A preview codec is accepted only after real browser playback. Require visible moving game content, intelligible game audio and correct crop in human preflight, not merely ffprobe streams. Original markers describe actual visible input/event intervals and uncertainty; port traces use observer data. Collect missed/skipped/aborted cases and wrapper rendering/timing limitations, distinguish diagnostic runs, and preserve generated original post-run changes. Keep DxWnd provenance distinct from native Windows port receipts per D-15. No guessed profile, forced timer/render setting, tool download or redistributed third-party installer. PowerShell tests run without Pester/package installs using temporary fixtures and explicit positive check count. Include their exact command in the session agenda; absence of pwsh here remains pending rather than pretending syntax tests ran. Local transfer instructions use USB/local filesystem or existing local shares, with hashes rechecked on return. Do not request capture yet.</action>
<acceptance_criteria>Every required case/tool/material appears in the one agenda; synthetic tests prove completeness/classification; package-free Windows selftests are ready; no capture request occurs before final readiness.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_checkpoint.py"); assert s.countTestCases() >= 16,"fewer than 16 checkpoint tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 16 tests, or missing agenda/required-cell/abort/classification checks.</fails_when>
<human-check>At the final combined session run powershell.exe -NoProfile -File .\tests\fidelity-windows.Tests.ps1 from the prepared checkpoint, requiring eight or more passing checks and zero failures; then perform the actual original/native recording agenda. Missing tools/settings remain explicit failure receipts.</human-check>
</verify>
<done>A complete local checkpoint and one combined session agenda cover original-reference and native Windows capture, including honest failure/abort results.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; unresolved high/critical threats block acceptance. No new package installs.
| Boundary | Description |
|---|---|
| Selected tools/profile → process launch | Only explicitly selected local executables run with transparent arguments |
| Checkpoint package → user results | Byte identity and classification must survive local transfer |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-13 | Elevation of privilege | PowerShell launcher | high | mitigate | No elevation/download/eval; allow explicit local selection, argument-safe invocation and no receipt-supplied commands |
| T-01-14 | Tampering | Bundle/transfer | high | mitigate | Canonical hashes, preflight/postflight, atomic fresh assembly and tampered artifact rejection |
| T-01-15 | Spoofing | Original/native receipts | high | mitigate | Separate methods/profile provenance, explicit abort/limitations and no acceptance from launch or metadata alone |
| T-01-SC | Tampering | Package installation | high | mitigate | No ecosystem additions or third-party redistribution; actual external executable provenance recorded locally |
</threat_model>
<verification>Run counted bundle tests and shell syntax check. Checkpoint READY describes materials only. Actual Windows PowerShell/original/DxWnd/native port and browser checks occur once in plan 01-07.</verification>
<success_criteria>Everything needed for the single Windows hands-on session is complete and locally transferable before the user is asked to run it.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-05-SUMMARY.md with checkpoint membership, actual package identities and pending Windows checks.</output>
@@ -0,0 +1,166 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "05"
subsystem: testing
tags: [offline, powershell, windows, fidelity, sha256]
requires:
- phase: 01-02
provides: Offline paired review viewer
- phase: 01-03
provides: Capability ledger and identified source links
- phase: 01-04
provides: Passive port observation and package flags
provides:
- Immutable offline checkpoint with identified original and Linux/Windows packages
- Complete eighty-obligation Windows agenda with separate original-DxWnd and native-port collection
- Package-free PowerShell selftests and truthful terminal/media results
affects: [01-06, 01-07]
tech-stack:
added: []
patterns: [exclusive allocation, bounded hashing, atomic publication, explicit open acceptance, inert argument provenance]
key-files:
created:
- tools/recon/fidelity_checkpoint.py
- scripts/prepare-fidelity-checkpoint.sh
- scripts/collect-fidelity-windows.ps1
- scripts/collect-fidelity-windows.cmd
- tests/test_fidelity_checkpoint.py
- tests/fidelity-windows.Tests.ps1
- docs/evidence/windows-session.md
modified: []
key-decisions:
- "READY validates immutable prepared materials only; actual original-DxWnd/native Linux/native Windows acceptance remains open 0/120."
- "Runtime package source/dirty/diff identity stays bound to its actual completed publish, separately from later collector and document commits."
- "Selected external tools are identified without redistributing executables; raw MKV, terminal failures and actual derivation provenance remain local."
requirements-completed: [EVID-01, EVID-02, EVID-04]
requirements-acceptance: "OPEN: assigned preparation contributions are complete; shared requirement IDs remain Pending until unfinished sibling capture/review plans and actual acceptance gates close."
coverage:
- id: offline-checkpoint
description: Identified complete offline bundle, preservation and tamper checks
requirement: EVID-01
verification:
- kind: integration
ref: tests/test_fidelity_checkpoint.py
status: pass
- kind: other
ref: artifacts/fidelity/verification/01-05-complete-bundle.json
status: pass
human_judgment: false
- id: collection-tooling
description: Package-free collector identity/path/argument/process/result functions on synthetic fixtures
requirement: EVID-02
verification:
- kind: integration
ref: tests/fidelity-windows.Tests.ps1
status: pass
human_judgment: false
- id: combined-session-materials
description: Eighty Windows obligations, session instructions and settings/annotation templates are bundled
requirement: EVID-04
verification:
- kind: integration
ref: tests/test_fidelity_checkpoint.py#test_complete_session_materials_and_eighty_windows_obligations
status: pass
human_judgment: false
- id: actual-original-native-acceptance
description: Actual original-DxWnd/native Windows execution, audiovisual preflight and full scenario review
verification: []
human_judgment: true
rationale: "Linux-hosted synthetic PowerShell tests, prepared bytes and apphost help do not establish Windows gameplay, actual browser/audio playback or whole-original fidelity; plan 01-07 owns the combined session."
actuals:
tokens: 21862
tasks: 2
commits: 7
basis: "ceil(chars/4) over the realized seven-file production/test/document diff: 87448 characters. Measured ledger range includes five plan task commits plus the intervening primary handoff and quota-guard commits; no invented task-commit count."
plan_head_before: de68796df15acaacbc7df1ae5701acac770680ce
plan_head_after: aa4b862a123112085660ee14fc0e2bccb251ddfa
duration: 12h 4min
started: 2026-11-13T04:40:08Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 05: Offline Windows Checkpoint Summary
**An identified 10,983-file offline checkpoint carries preserved originals, both actual port packages, review/protocol materials and a complete Windows original-DxWnd/native-port collection agenda with open acceptance.**
## Performance
- Two tasks, seven production/test/document files. The recorded wall interval starts at the earliest task RED commit, 04:40:08 UTC, and includes the long quota interruption before task 2 resumed. It is not twelve hours of active execution.
- Final targeted verification: **24 Python checkpoint tests**, **17 actual Linux-hosted PowerShell checks**, four PowerShell-produced synthetic receipts validated by the shared Python validator, shell syntax and **539 unchanged original files**.
- The broader fidelity regression passed **133 tests in 123.784 seconds** with authorized local loopback/process access before the final mode-only correction; the affected checkpoint suite then passed all 24 tests in 4.742 seconds. No skipped tests are represented as passes.
- Actual full-bundle Python and Linux-hosted PowerShell preflights both pass, checking 10,983 immutable entries. The PowerShell traversal took several CPU-active minutes and completed before its explicit 600-second supervisory bound. It did not wait for interactive input.
## Accomplishments and Interfaces
- `fidelity_checkpoint.py` seals actual completed publishes, prepares a fresh offline tree and preflights immutable file identities. Existing outputs, overlaps, aliases, tampering, stale DLLs, interrupted/concurrent assembly and missing dependencies are rejected with local diagnostics. The generated original seed is verified before copying and again against its authoritative inventory. Hashes stream; assembly uses an exclusive reservation and retains incomplete diagnostics on failure.
- The bundle contains `manifest.json`, `READY.json`, `original-pristine/`, `original-runs/`, `port/linux-x64/`, `port/win-x64/`, `review/`, `protocol/`, `results/`, both collector launchers, the session guide and standalone PowerShell selftests. Protocol materials include scenarios, capabilities, original inventory, an **80-obligation Windows agenda** and explicit pending settings/annotation templates. Empty/false fields require actual observations during the later session; they are not fabricated identities or implementation stubs.
- `collect-fidelity-windows.ps1` supports `Preflight`, `Run`, `Retained`, `Finish`, `Skip` and `Abort`. Native port and original-DxWnd receipts keep distinct categories. It identifies actual selected external tools without copying third-party executables/installers, preserves the user's profile plus generated original pre/post state, uses quoted direct process invocation and records honest exit/log information. No original is executed in place, no command from a receipt is evaluated, and no dependency is downloaded.
- Raw MKV and actual audio evidence are required to finalize captured results. Derived artifacts retain source/output references, actual tool/version/argv/time/crop metadata and explicit browser-playback declaration. Synthetic promotion, terminal-outcome promotion, reused results and invalid references are rejected. Failed/skipped/aborted results remain available for collection without inventing successful media. All collector outputs retain open acceptance and require the shared validator and later human review.
- `windows-session.md` gives one ordered agenda: local selections/provenance, package-free checks, separate original/port visual/audio preflights, all eight matrix cells and five obligations, paired browser/exclusive-audio review, collection/postflight, then one local return transfer with hash checks. It recommends offline OBS Display Capture initially while requiring actual selected settings. It does not request capture now.
## Task Commits
1. Task 1 RED: `446930d` — specify immutable offline checkpoint round trip.
2. Task 1 GREEN: `6112339` — assemble identified offline Windows checkpoint.
3. Task 2 RED: `818191c` — require complete Windows session materials and open results.
4. Task 2 GREEN: `8574665` — complete offline Windows collection agenda and selftests.
5. Task 2 correctness follow-up: `aa4b862` — retain executable permissions in offline copies.
Task 1 was already complete and was not repeated during recovery. The partially edited collector and checkpoint module were preserved and completed. Normal Git hooks ran with explicit scoped staging, protected-branch configuration and the supplied-root guard; no tracked files were deleted. Unrelated `tools.yaml`, the primary's quota tooling commit `c9b9f2e` and its ownership were preserved. The primary owns review, integration reports and push.
## Actual Offline Bundle and Package Identities
Fresh final bundle: `artifacts/fidelity/01-05-session-checkpoint`. Durable identity/audit evidence: `artifacts/fidelity/verification/01-05-complete-bundle.json`.
| Material | SHA-256 |
|---|---|
| manifest.json, 2,689,788 bytes | `1098cf07030d5acf71b37d2132ec8bf39360855e9f7b2203cd130c9a7ac011be` |
| READY.json, 358 bytes | `1bb81a44da9f5ce92d5549f1608fcc6f46a47e2010d5160b39dcb471d1e8cccd` |
| Original 539-file canonical tree | `419af98a75a9f1d4ae3eceb5c7807bc9634912c2c3918c308470ad798dcef181` |
| Linux sealed package file-list hash | `124cf271e4952f3822eec5c24358447fcffc9e9e1803aded8d96d4d4472dc5a3` |
| Windows sealed package file-list hash | `335e5b75ec15c0fa904113d8b69d4f50e2cfa403f1f2f225353bd9e586322ef4` |
| Linux GamePort.dll, 734208 bytes | `145de80f2628f836cd77f0e8f66cb1b9d5abb8445088ff8ba8eb82527b6cd150` |
| Windows GamePort.dll, 734208 bytes | `d21c917c1d260f3cd2c5b3d19397ab78ae23108c90b4f393eba4904d80e512a1` |
Both packages already existed under `artifacts/fidelity/01-05-packages`; recovery did not rebuild them. Their actual BUILD-INFO identifies source `446930d2a30d6d616c60ac5e59e4169a840bea09`, **dirty yes**, diff SHA-256 `90cef95669caece53fe2d2c4736cf2ac05ed27f5d25ca03ab572589686bcb73d`. Publish timestamps are 2026-11-13T04:45:41.527524+00:00 and 04:47:05.457630+00:00 respectively. Neither the resumed collector revision nor the later clean task commit is stamped over that runtime provenance. Historical `dist/` packages remain unchanged.
The final copied Linux apphost was permission-repaired from its byte-identical package source to mode 0755, then actually ran `--help` successfully. The generator now preserves ordinary source permissions for future copies while dropping privileged mode bits. That permission-only repair changes no manifest/file byte identity. Apphost help establishes startup/CLI availability only, not gameplay, sound, GPU or platform acceptance.
## Verification Commands and Scope
```sh
python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_checkpoint.py"); assert s.countTestCases() >= 16; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'
bash -n scripts/prepare-fidelity-checkpoint.sh
python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
python3 tools/recon/fidelity_checkpoint.py preflight --checkpoint artifacts/fidelity/01-05-session-checkpoint
```
The cached `.tools/powershell-check/root/opt/microsoft/powershell/7/pwsh` is usable with `XDG_CACHE_HOME`, `XDG_CONFIG_HOME` and `XDG_DATA_HOME` set to task-local `/tmp/gameport-pwsh-*` directories. Its default home cache is read-only in the sandbox. No install/download was performed. Actual commands used that executable with `-NoProfile -File tests/fidelity-windows.Tests.ps1 -FixtureOutput /tmp/gameport-01-05-ps-results` and separately `-NoProfile -File scripts/collect-fidelity-windows.ps1 -Action Preflight -Bundle artifacts/fidelity/01-05-session-checkpoint`.
The 17 selftests exercise IDs/paths, hashes/copy identity, arrays/write-once JSON, argument quoting, an actual child with spaced arguments and exit 7, stdout/stderr, timeout/start failure, categories/terminal outcomes, manifest tampering and finish links. Their four captured/failed/skipped/aborted receipts all validate structurally through `fidelity_receipts.validate_receipt`; **all four remain synthetic and unaccepted**. Linux PowerShell is not Windows PowerShell 5.1 execution evidence. The exact native Windows selftest command is included in the future combined agenda.
## TDD Gate Compliance
Both retained RED reports, `artifacts/fidelity/tdd/01-05-01-red.json` and `01-05-02-red.json`, return `RED_EVIDENCE_OK` through the current classifier. Task 1's named target executes its intended missing preparation-API assertion. Task 2's named target completes assembly then fails the planned missing-session-material assertion; its separate missing status-API error remains honestly recorded. Both RED commits precede their GREEN commits by ancestry. No separate refactor was needed. Final targeted tests pass.
## Deviations from Plan
1. **[Rule 1 — collector correctness]** Real PowerShell execution exposed top-level empty arrays serializing incorrectly and asynchronous .NET completion values leaking into the process-result pipeline. `Write-FidelityJson` now uses `ConvertTo-Json -InputObject`; asynchronous completions are suppressed, output closure is bounded and final log size is checked. Standalone serialization/process/terminal tests pass; `8574665`.
2. **[Rule 2 — runnable offline copy]** Final bundle inspection found that byte-only copying dropped Linux apphost execution permission. The generator now preserves ordinary source mode bits, and a regression checks both mode and bytes. The generated apphost was repaired from its verified source and ran help; `aa4b862`. No source/package bytes or gameplay algorithms changed.
No new trust surface beyond the plan's selected-process/local-filesystem boundaries was introduced. The supplied threat mitigations remain applicable: no eval/elevation/downloads, explicit local selections, contained paths, hashes, immutable result IDs and categories that cannot imply acceptance. No implementation stub or skipped mandatory automated verification remains; actual Windows/human checks are intentionally assigned to the later combined session.
## Issues Encountered
Quota interruption required a specific task-2 recovery from the existing RED commit and partial edits. An accidentally duplicated slow preparation was stopped; its incomplete directory and reservation remain under `.01-05-complete-checkpoint*` as diagnostics, and the final assembly uses a new root. No lock was stolen or failed partial tree promoted. The sandboxed broader regression denied loopback sockets and timed out .NET setup; its authorized local rerun passed all 133 tests. The optional full PowerShell preflight was CPU-active and bounded, then passed. No unresolved test failure is hidden by these environment adaptations.
## Next Phase Readiness
The full bundle and session tooling are prepared. Plan 01-06 still owns actual native Linux capture, and plan 01-07 owns the combined original-DxWnd/native Windows session and audiovisual review. The real scenario audit is structurally ready with **accepted 0 / required 120**, all eight cases missing and no invalid receipts. Original launch/profile validity, native Windows execution, real browser playback/audio/crop and full-route fidelity remain open. This plan makes no new original-binary, REA, Wine, native Windows gameplay or whole-original compatibility claim.
Shared EVID-01/EVID-02/EVID-04 IDs remain Pending because `requirements.ready-ids` returns no ready IDs while sibling plans are unfinished. Root progress/tasks/decisions/compatibility integration and consumed-handoff cleanup belong to the primary.
## Self-Check: PASSED
All seven created files exist. All five plan task commits are reachable on this branch, and evaluation-scope resolves the recorded plan commits. Final counted checkpoint/PowerShell checks, shared receipt validation, both full-bundle preflights, shell syntax, Linux apphost help and 539 original hashes pass. The persisted ledger measures seven commits before summary metadata, including the two intervening primary commits explained above. No generated package/media/original is staged, no tracked deletion occurred, and unrelated `tools.yaml` is preserved.
@@ -0,0 +1,105 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "06"
type: execute
wave: 4
depends_on: ["01-05"]
files_modified:
- tools/recon/fidelity_capture.py
- scripts/collect-fidelity-linux.sh
- tests/test_fidelity_capture.py
- docs/evidence/linux-session.md
autonomous: true
requirements: [EVID-01, EVID-04]
estimate:
tokens: 25000
raw_tokens: 25000
tasks: 2
confidence: low
must_haves:
truths:
- "An identified native Linux package yields actual input/event and audiovisual captures where execution is available; synthetic/headless replays remain distinct (EVID-04)."
- "Continuous route and focused captures cover all natural/skipped, fresh/retained and ordinary/edge cells per D-01–D-04, with missing executions explicitly open."
- "Physical input/audio and real visible gameplay require actual native receipts/human review; dummy audio and window-only fixtures cannot complete acceptance."
artifacts:
- path: tools/recon/fidelity_capture.py
provides: "Bounded native Linux capture orchestration and result collection"
- path: docs/evidence/linux-session.md
provides: "Native Linux route protocol, capture setup and physical review agenda"
- path: scripts/collect-fidelity-linux.sh
provides: "Local identified-package launch/collection entry point"
key_links:
- from: tools/recon/fidelity_capture.py
to: "Identified Linux checkpoint package and port observer"
via: "Actual process invocation, accepted input/events, raw media and receipt identity"
- from: "Native Linux receipts"
to: "Paired review and final acceptance audit"
via: "Validated case/session/package/media identity and explicit missing cells"
---
<objective>
Collect current native Linux baseline evidence using the completed checkpoint rather than substituting synthetic fixtures for ordinary gameplay. Prepare all physical/audible review items for the same final combined review.
Artifacts this phase produces: fidelity_capture.py preflight/run/collect CLI; collect-fidelity-linux.sh; tests/test_fidelity_capture.py; linux-session.md; ignored artifacts/fidelity/linux sessions containing receipts, logs, raw video/audio, observer events, annotations, media probes and images. Original-side capture remains on Windows through DxWnd.
</objective>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@.planning/ROADMAP.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-04-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-05-SUMMARY.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-06-01">
<name>Capture one actual Linux focused moment and import its observed evidence</name>
<files>tools/recon/fidelity_capture.py, scripts/collect-fidelity-linux.sh, tests/test_fidelity_capture.py, docs/evidence/linux-session.md</files>
<read_first>docs/evidence/scenarios.json; tools/recon/fidelity_receipts.py; scripts/test-window-transitions.sh; docs/evidence/windows-session.md; 01-RESEARCH.md capture/media guidance; actual completed Linux package BUILD-INFO and manifest.</read_first>
<behavior>At least 10 tests exercise capture launch→probe→hash→import with bounded process/media doubles, real receipt validation and explicit fixture category; missing display/audio, recorder exit, timeout/abort, stale package, empty/frozen media indicators and native-versus-headless classification remain incomplete.</behavior>
<action>Create tests first. Implement bounded orchestration that verifies completed package/resource identities, records OS/GPU/driver/Vulkan/SDL and capture-tool versions, launches the native Linux package using normal controls plus passive observer and collects external recording and actual logs. Use available local FFmpeg/OBS capabilities only after preflight; record the selected X11/Wayland/display/audio capture methods rather than assuming Pulse/PipeWire availability. Preserve raw video/audio and any timestamp-preserving remux preview; ffprobe validates actual streams/durations, while human visibility/audibility remains separate. Prove one focused normal-play dialogue-return/neutral-input moment end to end through launch, logs/events, media collection, import and viewer links. Existing SDL injection may support a clearly labeled automated native replay, but cannot be relabeled physical user input. A smoke or headless fallback stays fixture evidence. If this environment cannot run/capture native audio/video, publish its exact failed preflight/open receipt and finish the usable collector/procedure without blocking remaining bundle preparation. This conditional is an execution dependency, not a waiver of native acceptance. Do not ask the user for an early session.</action>
<acceptance_criteria>Counted capture round-trip tests pass; either an actual identified native focused receipt or a precise failed-preflight receipt exists; no synthetic/automated/dummy-device evidence claims physical/audible acceptance.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_capture.py"); assert s.countTestCases() >= 10,"fewer than 10 capture tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 10 tests, absent round-trip output or an unavailable/synthetic capture promoted to native acceptance.</fails_when>
<human-check>The final combined review checks actual Linux physical input, moving game content and audible output, including the observer's recorded scope and any capture overhead.</human-check>
</verify>
<done>One focused Linux capture path is usable, and its actual execution result or precise access limitation is represented honestly.</done>
</task>
<task type="auto" tdd="true" id="01-06-02">
<name>Collect the complete Linux journey matrix with preserved entry lifetimes</name>
<files>tools/recon/fidelity_capture.py, scripts/collect-fidelity-linux.sh, tests/test_fidelity_capture.py, docs/evidence/linux-session.md</files>
<read_first>Task 01-06-01 collector; docs/evidence/scenarios.json; docs/gameplay/main-menu-player-lifetime.md; docs/gameplay/jimmy-movement-stabilization.md; current checkpoint package identities.</read_first>
<behavior>Extend to at least 14 tests proving full case enumeration, route continuity, focused obligations, fresh/retained separation, natural/skip identification, interrupted matrix resume without reusing sessions and explicit unavailable cells.</behavior>
<action>Expand the real collector/procedure to all required continuous/focused matrix cases per D-01–D-04. Each continuous lab→VR04→lab→outside recording preserves actual scene/control/save/RETURN lifetimes; independent focused setups are labeled and cannot replace the continuous journey. Keep ordinary play separate from held-through-dialogue/return, banked jumping left/right, landing and idle edge runs. Capture raw elapsed/event deltas and annotation uncertainty without inventing tolerances or repairing bank/movement. Use normal gameplay; debug warps/grants and smoke route fixtures remain narrow supplementary evidence. Verify source originals before/after the capture checkpoint. Attempt all runnable native Linux cells, record actual failures and missing media/physical/audible checks, and append remaining local Linux review actions to the single final session agenda. Re-run only failed/incomplete cells under new session IDs with retained history. Export receipt/review data for the final acceptance audit; do not update capability/root status files owned by final integration.</action>
<acceptance_criteria>All eight cells and their continuous/focused obligations are represented by actual receipt IDs or precise open dependencies; no count-only completeness or disconnected scene substitution passes.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_capture.py"); assert s.countTestCases() >= 14,"fewer than 14 capture tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 14 tests, or a missing cell/lifetime/continuity assertion fails.</fails_when>
<automated>python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json</automated>
<fails_when>Nonzero exit or missing Verified 539 unchanged original files.</fails_when>
</verify>
<done>The Linux evidence matrix is collected as far as actual access permits, with all remaining acceptance explicitly retained for final review.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; high/critical unresolved threats block acceptance.
| Boundary | Description |
|---|---|
| Capture configuration → owned processes | Bound selected recorder/native executable and output paths |
| Captured artifacts → receipt | Real media/tool/input provenance must survive import |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-16 | Tampering | Native collector | high | mitigate | Argument arrays, contained fresh output and manifest checks before launch/import |
| T-01-17 | Spoofing | Linux evidence classification | high | mitigate | Actual native/input/audio method fields, fail-open acceptance prohibited, explicit unavailable cells |
| T-01-18 | Denial of service | Recording process | medium | mitigate | Bounded durations, owned-process shutdown and incomplete receipts on abort |
| T-01-SC | Tampering | Package installation | high | mitigate | Existing local capture tools only; no new packages |
</threat_model>
<verification>Counted collector tests and original preservation must pass. Native evidence gaps stay open regardless of tooling success. Actual physical input/audibility is reviewed once with the final combined materials.</verification>
<success_criteria>Current Linux route evidence is reproducible and precisely classified, with no unsupported native acceptance claim.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-06-SUMMARY.md with actual case receipt IDs, missing cells and capture limitations.</output>
@@ -0,0 +1,200 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "06"
subsystem: testing
tags: [linux, fidelity, capture, ffmpeg, provenance]
requires:
- phase: 01-01
provides: Typed receipts and eight-cell scenario contract
- phase: 01-02
provides: Local paired review export
- phase: 01-04
provides: Passive runtime observer
- phase: 01-05
provides: Identified sealed Linux checkpoint package
provides:
- Bounded local Linux preflight/run/collect and immutable receipt import
- Forty Linux obligations with exact open dependencies and verified attempt history
- Actual host failed-preflight receipt and local review export
affects: [01-07]
tech-stack:
added: []
patterns: [fresh output allocation, owned child deadlines, sealed package checks, explicit open acceptance]
key-files:
created:
- tools/recon/fidelity_capture.py
- scripts/collect-fidelity-linux.sh
- tests/test_fidelity_capture.py
- docs/evidence/linux-session.md
modified: []
key-decisions:
- "A real host with no display and only auto_null audio yields failed native preflight, never synthetic replacement gameplay."
- "One common failed environment dependency can explain all forty open Linux obligations without inventing forty game launches."
- "Retry history revalidates actual saved receipts and requires new launch/session IDs; focused captures never substitute for the continuous journey."
requirements-completed: [EVID-01, EVID-04]
requirements-acceptance: "OPEN: conditional tooling/preparation contributions complete; actual native physical/audible acceptance remains 0/40 Linux and 0/120 overall. Shared IDs remain Pending while plan 01-07 is unfinished."
coverage:
- id: linux-collector
description: Bounded process/media doubles, actual receipt import and classification
requirement: EVID-04
verification:
- kind: integration
ref: tests/test_fidelity_capture.py
status: pass
human_judgment: false
- id: linux-matrix
description: Eight cells and forty continuous/focused obligations with retained/fresh history
requirement: EVID-01
verification:
- kind: integration
ref: artifacts/fidelity/linux/01-06-matrix.json
status: pass
human_judgment: false
- id: actual-native-capture
description: Actual moving gameplay, physical input, real audible output and original/native comparison
verification: []
human_judgment: true
rationale: "Actual host preflight found no display session and only auto_null audio. All physical/audible and full-route obligations remain assigned to the final combined session."
actuals:
tokens: 14371
tasks: 2
commits: 4
basis: "ceil(chars/4) over the realized four-file production/test/procedure diff: 57484 characters; persisted ledger measures four task commits before summary metadata."
plan_head_before: 31ae6a6ab2ab1c342361de376a8756dafafb8227
plan_head_after: 0172916ffd9e3120e57c87c3bd853965f3e4d196
duration: 14 min
started: 2026-11-13T16:49:00Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 06: Linux Capture and Open Native Matrix Summary
**A bounded FFmpeg collector preserves package identity, failed native preflight and all forty Linux obligations without substituting synthetic gameplay.**
## Accomplishments
Both conditional plan tasks are complete. The collector provides `preflight`,
`run`, `collect` and `matrix`; the shell launcher does no build, download or
dummy-device fallback. It validates the sealed existing package/resources,
records OS/tools/hash/device/GPU information, and supports installed X11/Pulse
recording with normal `NewGame.tsk --walk` entry and passive observer. Actual
runtime SDL/active GPU/Vulkan versions remain unavailable without a game launch.
Fresh contained output, inert argument arrays, selected local sources, bounded
metadata/log/media sizes, one deadline and owned-child cleanup implement the
plan's process/filesystem trust boundaries. Raw lossless FFV1/PCM MKV, media
probes, logs, clocks and prelaunch identities survive collection/import. Media
emptiness, missing streams, frozen indicators, interrupted/failed children and
post-launch package changes keep observations incomplete. No automatic acceptance,
retiming, volume adjustment or gameplay/movement change was introduced.
The matrix enumerates each lifetime/dialogue/input cell and all five obligations,
including exact events/procedures and continuous lab → VR04 → lab → outside.
Saved retry history is hash-checked; a new attempt needs a new launch/session ID.
Annotations bind contained prerequisite recordings and actual copy-state identity
records without promoting them to physical/audible review. The Linux procedure
joins the single later Windows/original combined agenda.
## Task Commits
1. Task 1 RED: `9c59f60` — require bounded Linux capture round trip.
2. Task 1 GREEN: `16f5e12` — collect bounded Linux capture and honest failed preflight.
3. Task 2 RED: `e17cfbe` — require full Linux matrix continuity and resume history.
4. Task 2 GREEN: `0172916` — preserve full Linux obligation matrix and capture history.
Normal hooks and the supplied-root/protected-branch checks ran. The primary
explicitly authorized recovery after my first guard extraction omitted its bound
assignment; the complete literal guard then passed before any write. No root drift,
tracked deletion, runtime edit or unrelated `tools.yaml` change occurred. Primary
owns integration reports and push.
## Actual Execution and Package Identity
The outside-sandbox host probe found a TTY session, no `DISPLAY`/`WAYLAND_DISPLAY`
or X11 socket, no resolved Xvfb/OBS command and only suspended PipeWire Pulse
`auto_null`/`auto_null.monitor`. FFmpeg/ffprobe are installed distribution version
`6.1.1-3ubuntu5+esm15`; local help confirms the selected frozen-frame filter.
`lspci` succeeded; `vulkaninfo` is absent. The exact observations/tool hashes and
selected settings are retained. No game/recorder was launched, and no raw
video/audio or observed gameplay/input event was fabricated.
The existing package `artifacts/fidelity/01-05-packages/linux-x64` was reused,
without publish or bulk copying. Its file-list hash remains
`124cf271e4952f3822eec5c24358447fcffc9e9e1803aded8d96d4d4472dc5a3`.
Its actual source is `446930d2a30d6d616c60ac5e59e4169a840bea09`, dirty yes,
diff `90cef95669caece53fe2d2c4736cf2ac05ed27f5d25ca03ab572589686bcb73d`;
the collector revision never replaces that runtime provenance.
| Evidence | Exact local result |
|---|---|
| Task-1 diagnostic | `artifacts/fidelity/linux/01-06-focused-preflight/receipt.json`, ID `linux-01-06-focused-preflight-linux`, failed/open |
| Current typed dependency | `artifacts/fidelity/linux/01-06-matrix-preflight/receipt.json`, ID `linux-01-06-matrix-preflight-linux`, failed/open |
| Current applicable import | `artifacts/fidelity/linux-current-receipts/linux-01-06-matrix-preflight-linux/receipt.json` |
| Full Linux checklist | `artifacts/fidelity/linux/01-06-matrix.json`, 8 cells / 40 obligations, all open |
| Current shared audit | `artifacts/fidelity/linux/01-06-audit.json`, accepted 0 / required 120, invalid `[]` |
| Local review | `artifacts/fidelity/linux/01-06-review/index.html`, failed receipt with no fabricated media |
The older task-1 import remains diagnostic history; select the current typed
receipt for scenario audit. The focused failure is an actual preflight result,
not an executed gameplay moment. Every continuous/focused slot retains the exact
current dependency receipt plus its own actual capture/lifetime/human-review
requirement. No native matrix cell was runnable after the shared preflight failed.
## Verification
- Final counted capture verification: **23 tests pass**, exceeding both 10/14
thresholds. Doubles stay synthetic, native automation stays `port_fixture`,
positive retained file/clock binding and invalid retained-session cases pass.
- Broader `test_fidelity*.py` regression: **156 tests pass** in 36.316 seconds,
including local viewer sockets and existing real .NET/observer fixtures outside
sandbox restrictions. This ran before the final capture-size bound regression;
the final focused suite passed all 23 after that bounded collector change.
Complete report: `artifacts/fidelity/linux/01-06-fidelity-tests.log`.
- Shell syntax and `git diff --check` pass. Both actual failed receipts validate
through the shared validator/importer. The current scenario audit has no invalid
receipts and grants no acceptance.
- Original inventory verified **539 unchanged files** before capture preparation
and repeatedly after collection/final changes. No generated package, original,
trace or raw media is staged.
- Task-1 tracer verification reran and passed before matrix expansion. No blanket
fidelity tolerance or native Windows/original execution claim is made.
## TDD Gate Compliance
Actual records `artifacts/fidelity/tdd/01-06-01-red.json` and
`01-06-02-red.json` both return `RED_EVIDENCE_OK`. Task 1's named target executes
the planned missing capture-API assertion, without import/setup failure. Task 2's
named target executes the missing forty-obligation matrix assertion while the
first twelve tests remain green. Both RED commits precede their GREEN commits.
No separate refactor was needed.
## Deviations from Plan
None in scope. The plan's explicit unavailable-native conditional was exercised:
precise failed preflight, usable collector/procedure and complete open matrix
replace unavailable execution, without waiving acceptance. Additional correctness
checks preserve prelaunch identity after package tampering, bind annotation files
and exclude oversized raw media from unbounded import. These implement the
planned T-01-16/17/18/SC mitigations; no new trust surface was introduced.
## Remaining Acceptance and Next Phase
All **40 Linux** and **120 total** actual original/native acceptance obligations
remain OPEN. A usable display, real output/monitor device, physical play, continuous
and focused recordings, audible/visible/browser review and original-DxWnd/native
Windows comparisons are still required in the final combined session. Independent
fresh execution-copy staging and actual same-process retained state remain visible
procedure obligations; no source package is silently relabeled as a fresh copy.
The unavailable physical/native check is recorded as open WINDOWS ledger entry 2
(`unrun-verify`), not as a passed test or waived truth. No implementation stub or
skipped mandatory automated verification remains. Shared EVID-01/EVID-04 IDs stay
Pending because unfinished plan 01-07 owns their remaining gates.
## Self-Check: PASSED
All four implementation/procedure files exist; all four recorded task commits
are ancestors of HEAD. Actual failed/current receipt files, matrix, audit and local
review export exist. The persisted ledger measures four commits over the recorded
before/after range. Original verification, final counted tests and current receipt
audit pass within their stated scope.
@@ -0,0 +1,163 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "07"
type: execute
wave: 5
depends_on: ["01-06"]
files_modified:
- tools/recon/fidelity_acceptance.py
- tests/test_fidelity_acceptance.py
- docs/evidence/checkpoint-session.md
- docs/evidence/capabilities.json
- docs/evidence/phase01-baseline.md
- docs/progress.md
- docs/tasks.md
- docs/decisions.md
- docs/compatibility.md
- scripts/test.sh
autonomous: false
requirements: [EVID-01, EVID-02, EVID-03, EVID-04]
estimate:
tokens: 30000
raw_tokens: 30000
tasks: 3
confidence: low
must_haves:
truths:
- "One fully prepared combined session covers original-DxWnd and native Windows cases, local Linux review and real paired playback, per D-13–D-16."
- "Every required original-reference and native Linux/Windows case has exact revision/package/resource/media and observation provenance; absent or failed cases keep EVID-02/EVID-04 open."
- "Paired review of actual original/port captures applies D-05–D-08 and publishes raw drift, discrepancies and audible/visible checks."
- "Current capabilities/history/discrepancies are reconciled to returned receipts per D-09–D-12, with full matrix completeness per D-01–D-04."
- statement: "Actual original-DxWnd moving game imagery and intelligible audio are observed and reviewed with wrapper/config limitations recorded."
verification: backstop
- statement: "Actual paired recordings decode, seek and switch exclusive audio in the identified local browser without concealing elapsed time."
verification: backstop
assumptions:
- requirement_id: EVID-02
category: unclassified
status: unresolved
flagged: true
statement: "Deterministic probe could not classify reference-execution edge behavior; manually review original/DxWnd capture boundaries and limitations in the final session."
- requirement_id: EVID-04
category: unclassified
status: unresolved
flagged: true
statement: "Deterministic probe could not classify native-platform execution edges; manually review actual native input/audio/route and identity evidence in the final session."
artifacts:
- path: tools/recon/fidelity_acceptance.py
provides: "Separate readiness and strict acceptance audits"
- path: docs/evidence/checkpoint-session.md
provides: "Final single-session handoff and result checklist"
- path: docs/evidence/phase01-baseline.md
provides: "Actual receipts, discrepancies and open acceptance report"
key_links:
- from: "Returned Windows/local Linux results"
to: tools/recon/fidelity_acceptance.py
via: "Validated artifact identities and complete case/platform plus human checks"
- from: docs/evidence/phase01-baseline.md
to: docs/evidence/capabilities.json
via: "Same receipt IDs and current applicability; no unsupported acceptance promotion"
---
<objective>
Finish the prepared checkpoint, perform the one combined hands-on session and reconcile actual original/native proof. Materials readiness, test success and native/original acceptance have separate verdicts. Missing execution prevents Phase 1 acceptance while permitted source-backed later work may continue under the roadmap exception.
Artifacts this phase produces: fidelity_acceptance.py ready/audit CLI; tests/test_fidelity_acceptance.py; checkpoint-session.md; phase01-baseline.md; final local READY.json, acceptance.json and returned-results manifests. Existing capability/root status documents and scripts/test.sh are updated only after independent plans finish. No user capture is requested before task 01-07-01 readiness succeeds.
</objective>
<scope_budget>
The ten-file list is a bounded final integration exception, estimated at 30,000 tokens
against the 100,000-token plan budget. There are two substantive implementation files:
`tools/recon/fidelity_acceptance.py` and its dedicated tests. Task 01-07-01 owns these
plus the final session checklist; it adds no recorder, viewer or package subsystem.
Task 01-07-02 consumes the already prepared bundle and updates the existing capability
records plus one baseline findings report from validated results. Its human dependency
can remain pending and cannot be disguised as completed acceptance.
Task 01-07-03 has only integration/projection work: add already-created counted test
invocations to `scripts/test.sh`; add revision/receipt/open-status entries to the four
existing root reports. It must not refactor the runner, invent new tests/features,
change gameplay or redesign those reports. These five thin edits share one source
of truth (the final acceptance/test receipts) and remain serially owned here after
all parallel work ends. The checklist and baseline report use the same receipt IDs;
no additional independent design decision is deferred to this plan.
If an implementation change beyond those boundaries is discovered, stop that expansion
and record it for a separately planned task; keep current acceptance gaps explicit.
</scope_budget>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-05-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-06-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-SOURCE-AUDIT.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-07-01">
<name>Audit one prepared checkpoint from actual receipts through review and explicit pending acceptance</name>
<files>tools/recon/fidelity_acceptance.py, tests/test_fidelity_acceptance.py, docs/evidence/checkpoint-session.md</files>
<read_first>All prior phase SUMMARY interfaces; docs/evidence/scenarios.json; capabilities.json; windows-session.md; linux-session.md; 01-SOURCE-AUDIT.md flagged assumptions/prohibitions; actual checkpoint manifest and available Linux receipts.</read_first>
<behavior>At least 14 tests cover ready/audit end-to-end, complete valid evidence, missing/aborted cases, false native classification, wrong package/resources, synthetic original, absent human visibility/audio/physical-input checks, contradictory/superseded history and both unclassified review flags. Strict audit must exit nonzero on every acceptance gap while ready may report materials prepared with gaps visible.</behavior>
<action>Create tests first. Implement ready --checkpoint ROOT to validate all prepared manifest members, scenario matrix/procedures, package/observer consistency, generated viewer/ledger links, dependency instructions, PowerShell tests and local transfer/result forms. Implement audit --checkpoint ROOT --results ROOT --require-complete to require actual original-DxWnd and native Linux/native Windows case receipts, exact package/resource/artifact identities, complete continuous/focused matrix, observed event provenance, visibility/audibility/physical-input review and wrapper limitations. Structural audits may use --allow-open but print pending acceptance and all missing cases; their zero exit is never a native acceptance result. End-to-end tests import an actual available Linux receipt plus explicitly synthetic negative fixtures, generate the final review index and show strict acceptance staying nonzero until real dependencies are met. Unknown/unclassified probe assumptions and descriptor-less prohibitions require visible human review disposition; do not auto-dismiss them. Research backstop truths A1/A2 abstain to human_needed if real evidence is insufficient. Merge all earlier human-only checks into checkpoint-session.md as one agenda. Recheck manifest freshness immediately before handoff; changed binaries/resources require a new identified bundle, not patched identity labels. No capture request in this task.</action>
<acceptance_criteria>All 14 tests pass; ready produces materials_ready separately from acceptance; audit demonstrably rejects every absent original/native/human dependency; all session materials and pending checks are assembled before handoff.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_acceptance.py"); assert s.countTestCases() >= 14,"fewer than 14 acceptance tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 14 tests, or strict acceptance succeeds on missing/synthetic/misclassified/unreviewed evidence.</fails_when>
<automated>python3 tools/recon/fidelity_acceptance.py ready --checkpoint dist/fidelity/phase01</automated>
<fails_when>Nonzero exit, missing materials_ready=true summary, stale/missing hashed member, or absent acceptance=pending/open status when actual execution is still missing.</fails_when>
</verify>
<done>The complete bundle is reviewable and ready for one combined session; strict original/native acceptance remains separate and correctly pending where evidence is absent.</done>
</task>
<task type="auto" id="01-07-02">
<name>Collect the single combined session and reconcile actual original/native captures</name>
<files>docs/evidence/capabilities.json, docs/evidence/phase01-baseline.md</files>
<read_first>docs/evidence/checkpoint-session.md; ready audit output; returned local result manifests; current capabilities.json; actual original/native captures and receipt categories.</read_first>
<action>After all materials are complete, hand off one local checkpoint and perform the single combined hands-on session per D-13–D-16. Use end-of-phase human verification rather than intermediate checkpoint tasks. Run the prepared PowerShell selftests, select/identify DxWnd/OBS/profile, verify generated original copies, test visible moving content and audible output, then capture every required original-DxWnd/native-Windows case and physical input checks. Complete actual Linux physical/audible checks and real paired playback review from the agenda in the same review cycle. Retain all failed preflights, skipped cells and wrapper/capture/browser limits. Receive results only through local media/filesystem transfer and validate identities before import. Review raw recordings, images, events, exclusive audio, real elapsed/event drift, optional overlays and derivative metadata per D-05–D-08. No universal parity threshold may be invented. Publish per-case/platform findings, discrepancies and remaining conditions in phase01-baseline.md and update capabilities.json current/history per D-09–D-12. Record manual disposition of both unclassified EVID-02/EVID-04 assumptions and project-value prohibitions; insufficient evidence remains flagged human_needed/open. If execution/results are unavailable, retain pending dependencies and allow documentation integration, but do not claim this task's actual capture acceptance or Phase 1 acceptance complete. Prepared tools and failed/partial results cannot satisfy the native/original deliverable.</action>
<acceptance_criteria>Actual returned results are imported and reviewed, or each unavailable result is explicitly pending; strict acceptance can pass only with all required real original/native receipts and human checks. Native Windows, original-DxWnd and Linux remain separate proof categories.</acceptance_criteria>
<verify>
<automated>python3 tools/recon/fidelity_acceptance.py audit --checkpoint dist/fidelity/phase01 --results dist/fidelity/phase01/results --require-complete</automated>
<fails_when>Nonzero exit, any missing case/platform/media/human-review requirement, unresolved assumption affecting acceptance, or missing acceptance=passed result. Expected nonzero while actual evidence is unavailable is an open acceptance dependency, not a successful verification.</fails_when>
<human-check>One combined session: follow checkpoint-session.md, run the original generated copy through identified DxWnd and the port natively on Windows, return results locally, review actual Linux input/audio and paired recordings. Approve only observed case/platform facts; failed/unavailable cases remain open. No earlier fragmented capture request is authorized.</human-check>
</verify>
<done>Required actual original/native captures and review establish acceptance only when strict audit passes; otherwise the exact remaining session dependencies stay open and Phase 1 is not accepted.</done>
</task>
<task type="auto" id="01-07-03">
<name>Integrate local regressions and publish exact evidence status</name>
<files>scripts/test.sh, docs/progress.md, docs/tasks.md, docs/decisions.md, docs/compatibility.md</files>
<read_first>docs/evidence/phase01-baseline.md; actual acceptance.json and test logs; existing scripts/test.sh; current root status reports; all phase SUMMARY evidence limitations.</read_first>
<action>Integrate counted fidelity Python tests, built-in Node viewer checks and standalone observer tests into scripts/test.sh without duplicate full runs or new dependencies. The consolidated runner must reject zero discovered fidelity tests. Run the existing complete local suite and builds/package identity/resource checks required by changed observer/package boundaries, record actual durations/counts and preserve original hashes. Full-suite/native checks may exceed the quick-test budget; report their separately measured duration. Update all four durable status reports with actual implementation/test/native/whole-original facts, receipt IDs, package/source identities and open gaps; no historical totals copied as new results. If task 01-07-02 remains pending, prominently retain EVID-02/EVID-04 and Phase 1 acceptance open and cite the roadmap source-backed continuation exception. Include test/tool completion and prepared materials as their narrower facts. Keep all generated media/packages/traces local and ignored. Primary integration owns verified commits/push to existing Gitea; this plan authoring assignment performs no implementation or commits.</action>
<acceptance_criteria>The complete local suite and original inventory pass with measured positive counts; status documents agree with strict audit; no pending native/original dependency is marked complete; originals/packages/captures remain outside source uploads.</acceptance_criteria>
<verify>
<automated>scripts/test.sh</automated>
<fails_when>Nonzero exit, zero/missing fidelity or viewer/observer test count, failed managed/GPU/resource/preservation check, or missing consolidated completion log.</fails_when>
<automated>python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json</automated>
<fails_when>Nonzero exit or missing Verified 539 unchanged original files.</fails_when>
</verify>
<done>Local regressions and durable reports truthfully record current proof; Phase 1 acceptance is reported passed only after actual strict original/native acceptance, otherwise remains open.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; unresolved high/critical threats block acceptance.
| Boundary | Description |
|---|---|
| Returned local results → current acceptance | Artifacts and human findings are validated before promotion |
| Prepared checkpoint → user execution | Launch provenance and complete materials are reviewed before handoff |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-19 | Spoofing | Strict acceptance audit | high | mitigate | Require actual method/platform/matrix/identities and human review; reject synthetic/Wine/cross-publish/native substitution |
| T-01-20 | Tampering | Returned result import | high | mitigate | Recheck hashes/containment, atomic import, conflicting duplicate rejection and retained diagnostics |
| T-01-21 | Repudiation | Final evidence/status | medium | mitigate | Exact receipt IDs, explicit history and flags; pending dependencies prevent completion claims |
| T-01-SC | Tampering | Package installation | high | mitigate | Existing dependencies only; no new installation or upload service |
</threat_model>
<verification>Task 01-07-01 proves readiness and strict rejection behavior. Task 01-07-02 requires actual combined-session receipts for acceptance. Task 01-07-03 records local regressions and exact passed/open status; it cannot waive missing original/native evidence.</verification>
<success_criteria>Testers can reproduce identified original/port scenarios and inspect exactly what each native platform proves; unavailable execution remains an explicit incomplete acceptance dependency.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-07-SUMMARY.md with prepared versus accepted status, actual receipts and outstanding human dependencies.</output>
@@ -0,0 +1,196 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "07"
status: complete
completion_scope: autonomous preparation and pending-evidence reconciliation
acceptance: human_needed
subsystem: testing
tags: [fidelity, acceptance, checkpoint, local-regressions]
requires:
- phase: 01-06
provides: Linux collector and failed native preflight diagnostic
provides:
- Strict ready/audit gates and fresh local combined-session materials
- Pending original/native/human acceptance and exact reconciliation mapping
- Counted consolidated local regressions and measured final evidence status
affects: [phase01-acceptance, phase02]
tech-stack:
added: []
patterns: [receipt-bound human findings, immutable materials, explicit current selection, positive test counts]
key-files:
created: [tools/recon/fidelity_acceptance.py, tests/test_fidelity_acceptance.py, docs/evidence/checkpoint-session.md, docs/evidence/phase01-baseline.md]
modified: [tools/recon/fidelity_checkpoint.py, tests/test_fidelity_checkpoint.py, docs/evidence/capabilities.json, scripts/test.sh, docs/progress.md, docs/tasks.md, docs/decisions.md, docs/compatibility.md]
key-decisions:
- "Ready materials and local regressions never substitute for actual original/native acceptance; all 120 obligations and ten named human findings remain open."
- "The integration agent reconciles returned collector records through specified artifact mappings; the tester collects, observes and returns one combined session."
requirements-completed: []
actuals:
tokens: 18163
tasks: 2
commits: 5
plan_head_before: d18f551a26f90cd645309dcd545295911b581357
plan_head_after: 472500bf4e191c2080764471b6b08486c1909b3a
duration: "4h 36min observed commit-to-closeout elapsed, including quota pause; full suite 782.05s"
completed: 2026-11-13
coverage:
- id: D1
description: Immutable readiness and strict rejection of missing original/native/human evidence
verification:
- kind: integration
ref: tests/test_fidelity_acceptance.py; 23 checks in completed local suite
status: pass
- kind: integration
ref: fidelity_acceptance.py ready; 11000 immutable files
status: pass
human_judgment: false
- id: D2
description: Actual combined original-DxWnd/native Linux/native Windows capture and review
verification:
- kind: manual_procedural
ref: docs/evidence/checkpoint-session.md; acceptance.json 0/120
status: unknown
human_judgment: true
rationale: Actual moving content, physical input, audibility and paired playback remain unavailable; strict acceptance exits 1.
- id: D3
description: Counted fidelity regressions integrated with the existing complete local suite
verification:
- kind: integration
ref: artifacts/fidelity/01-07-full-suite.json; exit 0 in 782.0496263504028 seconds
status: pass
human_judgment: false
---
# Phase 01 Plan 07: Strict Fidelity Acceptance Checkpoint Summary
**Fresh 11,000-file offline materials pass readiness and the complete local suite; strict acceptance retains 0/120 original/native obligations and ten human judgments.**
Autonomous preparation and truthful pending-status reconciliation are complete.
Tasks 01-07-01 and 01-07-03 are complete. Task 01-07-02's permitted unavailable-
evidence projection is committed; its actual combined capture/review remains
pending. `status: complete` describes that preparation scope, never Phase 1 or
EVID acceptance. All EVID requirements remain Pending. Phase 2 is not advanced.
The stale quota handoff is retained for primary review/consumption separately.
## Performance and Accounting
- Earliest production-task commit: 2026-11-13T17:09:46Z; closeout: approximately 21:46Z.
- Observed elapsed interval includes the quota pause; active execution time was not measured continuously.
- Full authorized local suite: 782.0496263504028s, exit 0; runner reports 783s.
- Realized diff: 72,652 characters / 4 = 18,163 tokens, including committed quota metadata.
- Persisted plan ledger measures five commits before this summary; hashes above bound that measurement.
- Two fully completed tasks; one pending actual human task with its permitted documentation complete.
## Task Commits
| Task | Commit | Result |
|---|---|---|
| 01-07-01 RED | d78b135 | 18 intentional missing-API assertions fail; machine RED_EVIDENCE_OK |
| 01-07-01 GREEN | 026def9 | Strict audit, 23 passing tests, fresh final bundle and reconciliation checklist |
| 01-07-02 pending projection | fc5e936 | Capability ledger retains failed diagnostic and unresolved human states |
| Quota checkpoint | b732256 | Existing handoff/state only; no production behavior change |
| 01-07-03 | 472500b | Counted existing regressions and actual full-suite/status results |
## Verification Results
The complete suite ran once after the scoped reporter correction; its completed
receipt is `artifacts/fidelity/01-07-full-suite.json` and full output is
`artifacts/fidelity/01-07-full-suite.log`. No duplicate final suite was run.
| Verification | Actual result |
|---|---|
| Python discovery | 556 tests in 68.110s; 180 fidelity across all eight modules |
| Fidelity module counts | acceptance 23, capture 23, checkpoint 24, ledger 31, observation 7, review 21, scenarios 22, sessions 29 |
| Node viewer | 27 tests pass with explicit TAP reporter |
| Standalone managed observer | 23 checks pass |
| HUD Python | 2 separate tests in 0.171s |
| Managed entry points/build | All 51 test-project invocations and main build pass |
| Vulkan | 36 rendered receipts across 32 device groups; 27 saved readbacks; zero reported validation errors |
| Material regression | 17 Vulkan material/readback assertions pass, zero validation errors |
| SDL audio | Existing dummy-audio effect/stream/scene/cutscene checks pass; audibility remains unverified |
| Preservation | Verified 539 unchanged original files |
| Final readiness recheck | 11,000 immutable files; materials_ready=true, acceptance=human_needed |
| Final strict audit recheck | Exit 1; errors=[], accepted 0/120; ten human findings pending |
Optional `NEUTRON_WINDOW_TEST=1` checks were not enabled; no new native window,
physical-input, audible, original gameplay or native Windows execution is claimed.
Existing NU1900 unavailable vulnerability-metadata warnings remain unrelated.
First attempt: Python 556 passed in 71.765s and Node 27 passed, but the new TAP
count guard rejected Node's default spec reporter. Its 74.647s attempt/log is
retained as `01-07-full-suite-attempt1.{json,log}`. Explicit TAP passed focused
checks and the completed full rerun.
## Exact Evidence and Package Identity
- Final bundle: `dist/fidelity/phase01`; READY SHA-256 `48100025fbdcbb5310bdae28b5cae1e8f17412aa7b03be5f823616cd88211951`.
- Manifest SHA-256: `46610a4029f1341e7f48147370a81daaa8ff799a60fba388b641a0678d2032aa`.
- Exact tool/package identities: `artifacts/fidelity/verification/01-07-final-checkpoint.json`.
- Runtime source: `446930d2a30d6d616c60ac5e59e4169a840bea09`, dirty true, diff `90cef95669caece53fe2d2c4736cf2ac05ed27f5d25ca03ab572589686bcb73d`. Later tool/docs commits do not relabel existing packages.
- Actual failed receipt: `linux-01-06-matrix-preflight-linux`, imported under final `results/imported/`; diagnostic viewer: `results/failed-linux-review/index.html`.
- Final audit: `dist/fidelity/phase01/results/acceptance.json`; actual capture and human acceptance remain OPEN.
- Capability validation: 25 capabilities, 33 requirements, 33 reconciled rows, six groups; acceptance OPEN.
No runtime source changed in task 3, no package rebuild/relabel occurred, and no
originals, generated packages, media or traces were uploaded. All remain local.
## Files Created/Modified
`fidelity_acceptance.py` and its dedicated tests separate readiness from strict
acceptance. The existing checkpoint assembler/tests add required final materials
and tool provenance. `checkpoint-session.md` prepares one combined review and
`phase01-baseline.md` records actual/pending findings. `capabilities.json` retains
the failed receipt and unresolved current states. `scripts/test.sh` counts the
existing fidelity Python/Node/observer checks; the four root status reports cite
the completed suite, exact identities and pending acceptance. Planning artifacts
record the quota interruption and final autonomous preparation scope.
## Decisions Made
Prepared bytes, diagnostic fixtures and local regression success do not replace
actual original/native receipts or human judgments. Reconciliation remains an
agent-owned operation after one combined tester session; no fragmented early
capture request or new universal fidelity tolerance is introduced.
## Deviations from Plan
- Approved ownership extension: minimal checkpoint MATERIALS expansion, actual tool_source metadata and existing material-membership assertion update make the final immutable bundle contain Linux/audit dependencies; no second assembler/capture subsystem.
- Baseline pending report was created with task 1 because it must exist before immutable assembly; task 2 actual capture acceptance remains open.
- **[Rule 1 - Bug]** Task 3's new positive-count guard expected TAP while installed Node emitted spec. Explicit `--test-reporter=tap` fixes that scoped runner mismatch; focused 27 checks and complete rerun pass. Commit: `472500b`.
- Quota reserve interrupted closeout; the retained quota commit did not add behavior. The completed suite was recovered after reset without repeating it.
## TDD Gate Compliance
Task 1 RED preceded GREEN: `d78b135` then `026def9`. Saved
`artifacts/fidelity/01-07-red.{log,json}` records RED_EVIDENCE_OK. Prior semantic
inspection confirmed the empty-matrix test ran and failed on planned API existence,
without load/setup failure. Final suite executes all 23 acceptance checks.
## Deferred Issues and Human Dependencies
Actual original-DxWnd 40/native Windows 40/native Linux 40 obligations remain OPEN.
A1/A2, both EVID-02/EVID-04 unclassified assumptions, P1/P2/P3, browser,
paired_review and physical_input are the ten pending named findings. No strict
acceptance verification passed; its expected nonzero result records that missing
evidence. `.planning/WINDOWS.md` entry 3 tracks this unmet truth; entry 2 retains
the Linux capture access dependency. The primary reviews readiness before the
single combined human session. The roadmap source-backed continuation exception
does not waive these dependencies or authorize a phase transition here.
## Known Stubs
None preventing autonomous preparation. Checklist JSON metavariables are explicit
human-review templates, never positive findings. Empty review dictionaries in
negative tests and fail-closed audit defaults intentionally exercise missing
evidence; no production UI/data stub was introduced. Existing gameplay admission
gates remain unchanged. No new security surface beyond the planned local evidence
file/import boundaries was introduced.
## Self-Check: PASSED
All created source/test/checklist/baseline files, final local checkpoint, completed
suite receipt and exact identity receipt exist. All five recorded commits are
ancestors of the measured HEAD. Final readiness passes and strict audit retains
errors=[], 0/120 and ten pending findings. Unrelated `tools.yaml` is preserved.
## Independent review closure
Five confirmed findings were fixed and independently verified; see01-REVIEW.md,01-FIX-REPORT.md,01-REVIEW-VERIFY.md and01-REVIEW-DISPOSITION.md. Final refinement02d182f requires actual artifact bytes at the scenario boundary;191 fidelity checks pass43.355s. The new checkpoint has11,001 immutable entries with current local identities in artifacts/fidelity/verification/01-07-final-checkpoint.json; prior identity notes remain historical. All22 planned security threats are closed, while actual0/120 acceptance and ten named human findings stayOPEN. No original/native acceptance or phase advancement is implied.
@@ -0,0 +1,136 @@
# Phase 1: Reproducible Fidelity Baseline - Context
**Gathered:** 2026-11-12
**Status:** Ready for planning
<domain>
## Phase Boundary
Establish reproducible original/port comparison scenarios, original-file preservation,
a full-game coverage ledger and revision-specific native Linux/Windows baseline
receipts (EVID-01 through EVID-04). Build on existing implementation and evidence.
This phase establishes comparison infrastructure and captures; movement fixes and
broader gameplay admission retain their later phase gates. Unavailable execution
keeps affected acceptance open under the roadmap's source-backed-work exception.
</domain>
<decisions>
## Implementation Decisions
### Baseline journeys
- **D-01:** Capture the continuous lab → VR04 → lab → outside journey and focused replays of specific moments, including dialogue return, banked jumps and landing.
- **D-02:** Natural and skipped dialogue are equally required baseline cases.
- **D-03:** Fresh entry and retained departure/return receive separate, equally required runs that preserve their respective lifetimes.
- **D-04:** Include ordinary play and deliberate edge cases: held input through dialogue/return, banked jumps, landing and idle.
### Comparison review
- **D-05:** Open scenario results with paired original/port playback and links to corresponding images, audio and input/event traces.
- **D-06:** Keep captures unobstructed by default; annotations and image differences are optional overlays.
- **D-07:** Align key events while preserving actual recording speed and elapsed time; expose timing drift rather than concealing it through retiming.
- **D-08:** Switch between original and port audio at corresponding moments, playing one recording at a time. Clearly label any review-only volume adjustment.
### Evidence navigation
- **D-09:** Browse the full-game ledger by gameplay capability (movement, contacts, gadgets, progression, visuals, audio), with links to scenarios, source evidence and platform receipts. Retain requirement traceability.
- **D-10:** Each capability leads with what works, where it was verified, known differences and remaining acceptance conditions.
- **D-11:** Show current applicable evidence first; retain expandable history with exact revisions and clear superseded labels.
- **D-12:** Order discrepancies by player impact: blocking or visibly disruptive failures first, then subtler differences and missing verification. Missing evidence still leaves its acceptance open regardless of display order.
### Original and Windows access
- **D-13:** The user has a local Windows PC available to run prepared packages and return results. Availability does not itself establish successful native execution.
- **D-14:** Prepare one local test bundle per checkpoint. A launcher collects source/package/resource identities, logs and captures, with clear user steps and local transfer instructions. Packages and captures remain local.
- **D-15:** Run a separate generated copy of the original on that Windows PC through **DxWnd**. Record DxWnd version/configuration and execution/rendering limitations with each capture. Preserve wrapper provenance separately from native Windows port receipts; do not silently treat wrapper behavior as historical-platform parity.
- **D-16:** Prepare all materials before one combined hands-on session per checkpoint, covering original-reference captures and port checks and collecting results together.
### Carried-forward constraints
- Preserve every original byte and never execute originals in place; verify against `docs/original-manifest.json`.
- Preserve the implemented TSK-backed first-story input-order correction, fresh direct-scene order and legitimate landing bank. No invented leveling reset or replacement movement tuning.
- Keep source recovery, inference, copied-original component execution, port runtime, Wine, DxWnd reference execution, cross-publish and native platform receipts explicitly distinguished.
- Current Windows and original-reference acceptance remain open until new identified receipts demonstrate the required scenarios. A prepared bundle, wrapper launch or historical result alone cannot close them.
- All builds/tests/captures/packages stay local. Push only verified source/tools/docs to the existing Gitea remote. Preserve current actor/collision admission gates and the lab/outside compatibility solver.
### Agent discretion
No product decisions were explicitly delegated. Research/planning selects file formats,
local viewer technology, capture tooling, event markers and bundle mechanics within
the decisions above. The discussion does not require an external hosted website.
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Scope and preservation
- `.planning/PROJECT.md` — full reconstruction goal, constraints and existing foundations.
- `.planning/REQUIREMENTS.md` — EVID-01 through EVID-04 and full-game acceptance definitions.
- `.planning/ROADMAP.md` — Phase 1 boundary, access exception and later phase dependencies.
- `AGENTS.md` — current fidelity, source-control, REA and gameplay admission rules.
- `../AGENTS.md` — parent project requirements and evidence preservation.
- `../prompt.MD` — authoritative reconstruction specification; later push authorization supersedes older Git restrictions.
- `docs/original-manifest.json` — original-file identity baseline.
### Current evidence and protected behavior
- `docs/progress.md` — implementation and revision-specific verification status.
- `docs/compatibility.md` — platform receipts and explicit verification limitations.
- `docs/tasks.md` — existing work and open gates.
- `docs/decisions.md` — durable project decisions.
- `docs/checkpoint/next-work-plan.md` — movement/recovery and route verification sequence.
- `docs/checkpoint/coverage.md` — existing coverage/admission ledger.
- `docs/checkpoint/implementation-plan.md` — reconstruction dependencies and remaining gates.
- `docs/gameplay/main-menu-player-lifetime.md` — implemented TSK-backed startup-order correction.
- `docs/gameplay/jimmy-movement-stabilization.md` — movement baseline and stabilization priority.
### Reusable infrastructure
- `.planning/codebase/TESTING.md` — local tests, fixtures and runtime evidence boundaries.
- `.planning/codebase/CONVENTIONS.md` — bounded tooling and evidence-reporting conventions.
- `.planning/codebase/STRUCTURE.md` — source, tool and documentation integration locations.
- `docs/rea.md` — original-binary investigation workflow when needed.
No user-supplied DxWnd configuration document was provided; capture the actual local
version/settings during preparation and execution, without inventing them.
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `tools/recon/inventory.py` — hash verification using the recorded manifest.
- `tools/recon/reference_capture.py` — existing copied-original isolated Wine capture and port smoke infrastructure; useful starting evidence/tooling, not proof of Windows/DxWnd support.
- `scripts/test.sh` — consolidated local Python, managed, rendering/audio and original-hash checks.
- `scripts/test-window-transitions.sh` — existing local native window/transition verification.
- `scripts/package.sh`, `scripts/build-linux.sh`, `scripts/build-windows.sh` — existing offline package/build paths and provenance foundations.
- `src/GamePort/Application/CutsceneIdleSmoke.cs`, `src/GamePort/Application/WindowTransitionSmoke.cs` — existing native scenario fixture patterns; reuse suitable behavior instead of claiming component fixtures are gameplay.
### Established Patterns
- Python standard-library tooling and standalone .NET 10 console regression projects.
- Saved original observations and full-state/event comparisons are distinct from integrated native captures.
- Generated resources, screenshots, traces and packages stay in ignored local output, outside originals and source commits.
- Durable reports identify exact revisions, supporting source evidence and bounded verification scope.
### Integration Points
- `tools/recon/` for inventory/reference orchestration; `scripts/` for local launch/test/package entry points.
- `src/GamePort/Program.cs` and existing application fixtures expose bounded port capture routes; gameplay algorithms remain protected by current gates.
- Existing `docs/checkpoint/coverage.md` and root status reports provide ledger inputs; reconcile current/superseded receipts rather than assuming report order establishes current proof.
- A local comparison viewer connects scenario captures, optional overlays, timing markers, audio selection and capability-ledger links. Its implementation is a planning choice.
</code_context>
<specifics>
## Specific Ideas
The user explicitly clarified: “Local testing on my windows machine will have the
original game running via dxwnd”. Use that setup for the planned Windows original
reference sessions. Compare original and port without simultaneous mixed audio or
hidden timing correction. Prepare a complete, reviewable local checkpoint bundle
before requesting hands-on execution.
</specifics>
<deferred>
## Deferred Ideas
None — discussion stayed within phase scope. Native execution and capture are
future execution tasks, not results established by this discussion.
</deferred>
---
*Phase: 01-reproducible-fidelity-baseline*
*Context gathered: 2026-11-12*
@@ -0,0 +1,231 @@
# Phase 1: Reproducible Fidelity Baseline - Discussion Log
> **Audit trail only.** Planning, research and execution consume CONTEXT.md, not this log.
**Date:** 2026-11-12
**Phase:** 01-reproducible-fidelity-baseline
**Areas discussed:** Baseline journeys, Comparison review, Evidence navigation, Original and Windows access
The user selected all four areas. Discussion used individual numbered text questions.
Each area was completed explicitly, and the user selected “Ready for context” after the final summary.
## Baseline journeys
### For lab → VR04 → lab → outside, how should comparison runs be organized?
| Option |
|--------|
| Full route plus focused replays (Recommended) |
| Full route first |
| Focused replays first |
**User’s choice / clarification:** Full route plus focused replays: capture the continuous journey, then replay specific moments such as dialogue return, banked jumps and landing.
### How should natural and skipped dialogue appear in the baseline?
| Option |
|--------|
| Both as equal cases (Recommended) |
| Natural dialogue first |
| Skipped dialogue first |
**User’s choice / clarification:** Both as equal cases: run the route with dialogue completing naturally and with dialogue skipped.
### How should fresh entry and retained return be covered?
| Option |
|--------|
| Separate, equally required runs (Recommended) |
| Continuous journey first |
| Fresh start first |
**User’s choice / clarification:** Separate, equally required runs: capture a clean start and a continuous departure/return journey, preserving each lifetime.
### How should player inputs be chosen for the focused replays?
| Option |
|--------|
| Normal play plus deliberate edge cases (Recommended) |
| Normal play first |
| Repeat your reported sequences first |
**User’s choice / clarification:** Normal play plus deliberate edge cases: include ordinary movement alongside held input through dialogue/return, banked jumps, landing and idle.
### More on baseline journeys, or next area?
| Option |
|--------|
| Next area |
| More on baseline journeys |
**User’s choice / clarification:** Next area: Comparison review.
## Comparison review
### What should appear first when opening scenario results?
| Option |
|--------|
| Paired playback with marked differences (Recommended) |
| Written findings first |
| Chronological capture timeline |
**User’s choice / clarification:** Paired playback with marked differences: original and port shown together, with links to matching images, audio and input/event traces.
### How should differences be highlighted?
| Option |
|--------|
| Clean playback with optional overlays (Recommended) |
| Annotations always visible |
| Clean playback with notes alongside |
**User’s choice / clarification:** Clean playback with optional overlays: both captures remain unobstructed by default; annotations and image differences can be toggled for inspection.
### How should original and port playback line up when timing differs?
| Option |
|--------|
| Align key events and show timing drift (Recommended) |
| Start together and run continuously |
| Step through matching events |
**User’s choice / clarification:** Align key events and show timing drift, preserving actual recording speed and elapsed time.
### How should audio be reviewed?
| Option |
|--------|
| Switch between original and port (Recommended) |
| Original then port excerpts |
| Separate audio review |
**User’s choice / clarification:** Switch between original and port at corresponding moments, hearing one recording at a time; review-only volume adjustments must be clearly labeled.
### More on comparison review, or next area?
| Option |
|--------|
| Next area |
| More on comparison review |
**User’s choice / clarification:** Next area: Evidence navigation.
## Evidence navigation
### What should be the main entry point into the full-game evidence ledger?
| Option |
|--------|
| Gameplay capabilities (Recommended) |
| Playable journeys |
| Requirements |
**User’s choice / clarification:** Gameplay capabilities: browse movement, contacts, gadgets, progression, visuals and audio; each leads to scenarios, source evidence and platform receipts.
### What should each capability show before detailed evidence?
| Option |
|--------|
| Current state and remaining gap (Recommended) |
| Latest comparison result |
| Evidence summary |
**User’s choice / clarification:** Current state and remaining gap: what works, where it was verified, known differences and remaining acceptance conditions.
### How should earlier evidence appear when newer work supersedes it?
| Option |
|--------|
| Current evidence first, history expandable (Recommended) |
| Full history alongside current evidence |
| Separate history index |
**User’s choice / clarification:** Current evidence first, history expandable; retain older results with clear revision and superseded labels.
### How should open discrepancies be ordered within a capability?
| Option |
|--------|
| Player impact first (Recommended) |
| Route order |
| Newest findings first |
**User’s choice / clarification:** Player impact first: failures blocking or visibly disrupting play precede subtler differences and missing verification.
### More on evidence navigation, or next area?
| Option |
|--------|
| Next area |
| More on evidence navigation |
**User’s choice / clarification:** Next area: Original and Windows access.
## Original and Windows access
### What Windows environment is available for this phase?
| Option |
|--------|
| A local Windows PC |
| A local Windows VM |
| None currently |
**User’s choice / clarification:** A local Windows PC; the user can run a prepared test package and return results.
### How should Windows checks be run?
| Option |
|--------|
| One local test bundle per checkpoint (Recommended) |
| Guided sessions |
| Written checklist |
**User’s choice / clarification:** One local test bundle per checkpoint, with a launcher collecting revision details, logs and captures; packages and captures remain local and transfer uses a local method.
### Can the Windows PC also run a separate generated copy of the original?
| Option |
|--------|
| Yes, try it on that PC (Recommended) |
| Use Linux/Wine for original captures |
| Original-game execution is unavailable for now |
**User’s choice / clarification:** Yes, try it on that PC, using a separate generated copy and recording execution/rendering limitations.
### How should hands-on capture sessions be scheduled?
| Option |
|--------|
| Prepare everything, then one combined session per checkpoint (Recommended) |
| Original captures first, port checks later |
| Short sessions as needed |
**User’s choice / clarification:** Prepare everything, then one combined session per checkpoint, bundling original-reference captures and port checks with clear steps and collecting results together.
### Finish execution access or discuss further?
| Option |
|--------|
| Finish this area |
| More on execution access |
**User’s choice / clarification:** User clarification: Local testing on my windows machine will have the original game running via dxwnd.
### Finish this area or discuss the DxWnd setup further?
| Option |
|--------|
| Finish this area |
| Discuss the DxWnd setup further |
**User’s choice / clarification:** Finish this area. Original reference execution uses DxWnd; record its version/configuration with captures and distinguish wrapper effects from native Windows port checks.
## Agent discretion
No explicit product-choice delegation. Implementation mechanics remain for research/planning within the captured decisions.
## Deferred Ideas
None.
@@ -0,0 +1,114 @@
---
phase: 01-reproducible-fidelity-baseline
fixed_at: 2026-11-13T22:09:37Z
review_path: .planning/phases/01-reproducible-fidelity-baseline/01-REVIEW.md
iteration: 1
findings_in_scope: 5
fixed: 5
skipped: 0
status: all_fixed
---
# Phase 01: Code Review Fix Report
All five confirmed findings were fixed. Their logic changes require independent
human/reviewer verification; automated results below establish the stated tooling
contracts, never original/native gameplay acceptance. No runtime/gameplay source,
original file, package bytes, review disposition, or phase state was changed.
| Finding | Status | Commit | Applied fix and regression |
|---|---|---|---|
| CR-01 | fixed: requires human verification | `5569bc2` | Carry the actual selected receipt path into digest review. Two different sibling JSON files without a sidecar prove that only the selected file's digest satisfies the human finding; absent/unrelated digests leave findings pending. |
| CR-02 | fixed: requires human verification | `bda35e5` | Supply the complete checkpoint original file inventory, recompute its digest, and bind `identity.executable.original_member` plus size/header/hash to the exact pristine member. Original pre/post/package/resources require full baseline file records and digest. Positive original fixtures retain actual member/executable hashes; wrong executable/member and altered inventory records fail. Writable-copy post changes are separately identified and remain allowed. |
| CR-03 | fixed: requires human verification | `6e5ee0b` | Bind both lifetimes to the validated named `identity.copy_pre` record; retained lifetimes also require `identity.retained_copy`. Unknown hashes and hashes of launcher/package/other state records fail. Fixtures now retain distinct actual copy-state files. |
| WR-01 | fixed: requires human verification | `548c97a` | Assemble the existing validated ledger projection before review export, seal it at `protocol/capability-ledger.json`, and compare viewer current/history against it during readiness. Actual preparation-to-bundled-renderer regression retains the named current and superseded startup records; a sealed viewer missing history is rejected. |
| WR-02 | fixed: requires human verification | `2608517` | Recover missing `run.json` only as aborted from the retained incomplete record. Preserve the raw initial bytes as an importable `recovery-initial.json` diagnostic artifact, retain session/start identity, remove initial placeholder end clocks, and reject captured promotion or launch-aligned events. Shared validation/import permits this open aborted record with absent end clocks. |
WR-01 has one additional positive regression commit, `a821754`, proving readiness
on a standalone copied checkpoint with no source Git checkout. No fix was skipped
or rolled back. Five finding commits plus this verification commit were made.
Modified source: `tools/recon/fidelity_acceptance.py`, `fidelity_receipts.py`,
`fidelity_checkpoint.py`, and `scripts/collect-fidelity-windows.ps1`. Tests:
`tests/test_fidelity_acceptance.py`, `test_fidelity_scenarios.py`,
`test_fidelity_checkpoint.py`, and `fidelity-windows.Tests.ps1`. Field contracts:
`docs/evidence/checkpoint-session.md` and `windows-session.md`. No new source file
or dependency was required.
## Verification
All gates ran locally in the **main checkout**. The primary explicitly authorized
a temporary `workflow.use_worktrees=false` override. Its original absent setting
was restored without staging or committing it; the unused clean worktree was
removed before edits. Unrelated untracked `tools.yaml` remains unchanged. Normal
Git hooks ran for every commit. The WR-01 refinement was folded into its commit
before the primary's no-rebase steering arrived; subsequent history is preserved.
Logs are retained under ignored `artifacts/fidelity/01-review-fixes/`:
- `python-fidelity.log`: all 189 fidelity regressions passed in 40.072 seconds.
Initial sandbox execution hit eight loopback-socket permission errors; the
successful scoped-escalation run permits only the local tests' necessary host
operations. These were environment errors, not accepted failed tests.
- `acceptance-final.log`: 29 acceptance tests passed after the final standalone
transfer regression was added. This includes the refined readiness path; these
tests overlap the 189-test run and are not added to its count.
- `node-viewer-direct.log`: 27 actual Node behavior tests passed. On this host
`node --test` reports an aggregate one-file result; direct execution supplied
the explicit 27-test count. The preparation test also rendered the real bundled
model with the bundled renderer and a DOM double, without claiming browser
playback evidence.
- `powershell.log`: 18 package-free synthetic tooling checks passed under cached
Linux-hosted PowerShell. This is not native Windows execution evidence.
- `recovered-import.log`: the actual incomplete-only PowerShell output passed
shared validation and atomic import; accepted is false. Raw fixture output and
imported bytes are retained in separate `test-windows-results/` and
`test-recovered-imports/` namespaces.
- `original-preservation.log`: all 539 original files unchanged. The same
inventory command passed after assembly as well; preparation independently
checked the original inventory before and after copying.
- Python parse checks and `git diff --check` passed. The prior 13-minute full
managed/GPU suite was not repeated because these changes touch tooling and
evidence contracts only.
## Fresh immutable checkpoint
The final checkpoint was assembled **once**, using unchanged existing
`artifacts/fidelity/01-05-packages/{linux-x64,win-x64}` bytes. The prior tree was
preserved at `dist/fidelity/phase01-pre-review-48100025`; the documented current
path remains `dist/fidelity/phase01`. No sealed member was patched after assembly.
Mutable results contain a fresh import of the existing failed Linux preflight
receipt and the unchanged pending human-review controls; no captured evidence was
invented. The former assembly remains historical evidence.
| Item | Identity/result |
|---|---|
| Current checkpoint | `dist/fidelity/phase01` |
| Immutable members | 11001 |
| READY SHA-256 | `7ceebcb3a22549a59bb9f7032c5c686b4ca4d32cf7b6a7d934e12e37f05e7aba` |
| Manifest SHA-256 | `a4da759bb264d63b716a931ae3b16a410baf01e36a7b2696ae8ed5649f77f7a9` |
| Tool commit | `a821754b6755151a0e33e4ac5065c8efd252b2e6` |
| Tool working-tree provenance | Tracked diff empty; dirty true solely from preserved untracked `tools.yaml`, identified by the manifest |
| Sealed runtime source | `446930d2a30d6d616c60ac5e59e4169a840bea09`, dirty true |
| Runtime publish diff | `90cef95669caece53fe2d2c4736cf2ac05ed27f5d25ca03ab572589686bcb73d` |
| Linux package tree | `124cf271e4952f3822eec5c24358447fcffc9e9e1803aded8d96d4d4472dc5a3` |
| Windows package tree | `335e5b75ec15c0fa904113d8b69d4f50e2cfa403f1f2f225353bd9e586322ef4` |
| Startup viewer projection | Two current and two historical records retained |
| Readiness | Exit 0, `materials_ready: true`, `acceptance: human_needed` |
| Strict acceptance | Exit 1, 0/120, no structural errors, all ten human findings pending |
`prepare-checkpoint.log`, `readiness.json`, `acceptance.json`, and
`failed-linux-import.json` retain the actual results. The readiness and acceptance
reports also reside under the current bundle's mutable `results/` directory.
The ten pending findings remain A1, A2, EVID-02-unclassified,
EVID-04-unclassified, P1, P2, P3, browser, paired_review, and physical_input.
The host still lacks actual original/native Windows capture access and a usable
Linux display/audio session. Independent re-review and the primary's remaining
security/coverage gates precede any combined capture request.
This report is intentionally uncommitted for the primary workflow to review and
commit. No push, package upload, original execution, or original write occurred.
## Final artifact-boundary refinement
CR-03 independent re-review caught pathless hash-only named records. RED48fca0d reproduces fresh/retained missing-file, wrong-size and hash-only cases; GREEN02d182f validates actual named files inside scenario observation with an explicit root. All191 fidelity tests pass in43.355s; focused26 scenario/23 capture/29 acceptance checks pass. Independent reviewer confirms allfive findings fixed; security auditor closes22/22 planned threats. The earlier11001-file bundle is retained locally; current dist/fidelity/phase01 is freshly assembled from corrected source with original runtime package identities unchanged.
@@ -0,0 +1,349 @@
# Phase 01: Reproducible Fidelity Baseline - Pattern Map
**Mapped:** 2026-11-12
**Files analyzed:** 22 candidate new/modified files (names below are planning recommendations)
**Analogs found:** 16 / 22, including partial matches; five primary source analogs
## Scope and naming
CONTEXT.md locks behavior, not new filenames. RESEARCH.md proposes recon orchestration/receipt validation, a static viewer, scenario/ledger documents, Windows scripts, Python/JavaScript tests and an optional application observer. The concrete names below make that scope assignable; the planner may consolidate modules. Existing reference capture behavior must keep its Wine identity. Optional runtime/package edits are conditional on a demonstrated observation/identity gap, not authorization to change gameplay.
No project-local `.codex/skills/` or `.agents/skills/` directory was found. Read local/parent AGENTS.md, the parent specification, context and research. All five primary source analog paths below were verified by nonempty `git ls-files -- <path>` output. The two documentary sources were also tracked. No runtime/install mirror is used.
## File Classification
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|---|---|---|---|---|
| `tools/recon/fidelity.py` | utility | file-I/O, batch | `tools/recon/reference_capture.py` | role-match |
| `tools/recon/fidelity_receipts.py` | model, utility | transform, file-I/O | `tools/recon/inventory.py` | partial: identity transform only |
| `tools/recon/fidelity_viewer/index.html` | component | event-driven | — | none |
| `tools/recon/fidelity_viewer/viewer.js` | component | event-driven | — | none |
| `tools/recon/fidelity_viewer/style.css` | config | transform | — | none |
| `docs/evidence/scenarios.json` | config | batch | — | none: new protocol |
| `docs/evidence/capabilities.json` | model | transform | `docs/checkpoint/coverage.md` | partial: domain content, no JSON schema |
| `docs/evidence/README.md` | config (documentation) | transform | `docs/checkpoint/coverage.md` | role-match |
| `scripts/prepare-fidelity-checkpoint.sh` | utility | batch, file-I/O | `scripts/package.sh` | role-match |
| `scripts/collect-fidelity-windows.ps1` | utility | event-driven, file-I/O | — | none: new native collector |
| `scripts/collect-fidelity-windows.cmd` | utility | request-response | `scripts/package.sh` | partial: generated launcher stub |
| `tests/test_fidelity_sessions.py` | test | file-I/O | `tests/test_extractors.py` | role-match |
| `tests/test_fidelity_receipts.py` | test | transform | `tests/test_extractors.py` | role-match |
| `tests/test_fidelity_ledger.py` | test | transform | `tests/test_extractors.py` | role-match |
| `tests/fidelity-viewer.test.mjs` | test | event-driven | — | none: no tracked JS test suite |
| `src/GamePort/Application/FidelityObservation.cs` (optional) | service | event-driven, file-I/O | `src/GamePort/Program.cs` | partial: observation seams only |
| `src/GamePort/Program.cs` (optional) | controller | event-driven | `src/GamePort/Program.cs` | exact: existing owner |
| `scripts/package.sh` (optional) | utility | batch, file-I/O | `scripts/package.sh` | exact: existing owner |
| `docs/progress.md` | config (documentation) | transform | `docs/compatibility.md` | role-match |
| `docs/tasks.md` | config (documentation) | transform | `docs/compatibility.md` | role-match |
| `docs/decisions.md` | config (documentation) | transform | `docs/compatibility.md` | role-match |
| `docs/compatibility.md` | config (documentation) | transform | `docs/compatibility.md` | exact: existing owner |
Generated `artifacts/` sessions, media, review indexes and `dist/` checkpoint bundles are outputs, not tracked source targets. `docs/original-manifest.json` is an input that must not be regenerated to accommodate changes.
## Pattern Assignments
### `tools/recon/fidelity.py` — capture/staging/import/review CLI
**Analog:** `tools/recon/reference_capture.py`.
**Imports** (lines 8–16):
```python
import argparse
import ctypes
import hashlib
import json
import os
from pathlib import Path
import shutil
import subprocess
import time
```
Copy only needed stdlib imports; a passive collector does not need the legacy X11 injection helper.
**Path guard** (lines 150–157):
```python
project = Path(__file__).resolve().parents[2]
source = project.parent/'Original'
default_output = 'artifacts/windows-smoke' if args.port_smoke else 'artifacts/asset-probe' if args.asset_probe else 'artifacts/reference'
work = (args.output or project/default_output).resolve()
if work.is_relative_to(source.resolve()) or source.resolve().is_relative_to(work):
p.error('Output must be separate from originals')
work.mkdir(parents=True, exist_ok=True)
if not args.port_smoke and not (work/'game').exists(): shutil.copytree(source, work/'game')
```
Reuse the resolved two-direction overlap rejection. Replace the legacy reuse semantics in new sessions: a session directory must be new, and copy identity must be verified before execution. Add imported relative-path containment, symlink/alias checks and original pre/post verification. Do not simply copy `exist_ok=True` into the new session allocator.
**Bounded subprocess/error pattern** (lines 206–207):
```python
print('Running isolated Windows port' if args.port_smoke else 'Running copied original', 'with no network and no original-directory mount:', work, flush=True)
subprocess.run(cmd, check=True, timeout=args.seconds + 40)
```
Use argument arrays and bounded timeouts. New orchestration must retain failure/abort receipts when launch/probe/import fails; the old top-level exception behavior alone does not supply that contract. Never execute commands read from a receipt.
**Evidence classification** (lines 213–216):
```python
if result['captures'][-1]['wineExit'] != 0 or not evidence_ok:
raise SystemExit('Windows port smoke did not pass; inspect wine.log (native Windows remains unverified)')
print('Windows port audio lifecycle passed under Wine; native Windows validation is still required' if args.port_cutscene_audio
else 'Windows port rendered under Wine; native Windows validation is still required')
```
Preserve the explicit platform qualifier. The harness takes three timed stills (90–106) and installs null audio (159–160); it is not an audiovisual/native/DxWnd capture template. Keep that path separate or unchanged.
### `tools/recon/fidelity_receipts.py` — identities and validation
**Partial analog:** `tools/recon/inventory.py`; no existing complete receipt/ledger schema was found.
**Imports and stable identity** (lines 3–13):
```python
import argparse
import hashlib
import json
from pathlib import Path
def inventory(root):
return [{"path": p.relative_to(root).as_posix(), "size": p.stat().st_size,
"sha256": hashlib.sha256(p.read_bytes()).hexdigest(),
"header": p.read_bytes()[:16].hex()}
for p in sorted(root.rglob("*")) if p.is_file()]
```
Reuse deterministic relative POSIX paths and SHA-256 meaning. Stream large media hashes rather than copying this small-original-file `read_bytes()` approach. Keep session/schema/case/platform/package/resource/artifact/marker validation in a small explicit module; these types are new tooling contracts, not recovered game enums.
**Fail-closed preservation** (lines 21–26):
```python
files = inventory(args.root)
if args.verify:
previous = json.loads(args.verify.read_text())["files"]
if files != previous:
raise SystemExit("Original inventory differs from recorded baseline")
print(f"Verified {len(files)} unchanged original files")
```
Keep the mandated command `python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json`. Validate pristine staged-copy identity separately; post-run writes in that copy are observations, not permission to change the original manifest. Reject incomplete media/audio, nonfinite/out-of-range marker times, mismatched identities and false native classifications; metadata success alone does not establish visual/audible parity.
### `scripts/prepare-fidelity-checkpoint.sh` and optional `scripts/package.sh`
**Analog:** `scripts/package.sh`.
**Entrypoint and offline layout** (lines 1–9):
```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/env.sh"
scripts/build-linux.sh
scripts/build-windows.sh
python3 tools/extractors/prepare.py --all-scenes --audio sounds musicsecretlab
for rid in linux-x64 win-x64; do
out="dist/$rid"
mkdir -p "$out/assets" "$out/scenes/level1b" "$out/scenes/VR01" "$out/scenes/animations" "$out/scenes/actors" "$out/scenes/ui" "$out/audio/sounds" "$out/licenses" "$out/docs"
```
Reuse local SDK/build/resource entry points and quoted portable paths; checkpoint preparation should consume an identified completed package rather than silently rebuild a different one on import. The reference installation and capture tools stay separate from the port resources.
**Current provenance** (lines 48–52):
```bash
{
printf 'source_commit=%s\n' "$(git rev-parse HEAD)"
printf 'source_dirty=%s\n' "$(if [[ -n "$(git status --porcelain)" ]]; then echo yes; else echo no; fi)"
printf 'packaged_utc=%s\n' "$(date -u +%FT%TZ)"
} > "$out/BUILD-INFO.txt"
```
Retain these fields and bind completed executable/resource/package bytes in a separate manifest/receipt. A later documentation HEAD is not the older package's build identity. Avoid self-referential hashing: define manifest membership before hashing. Preparation produces one complete local bundle and transfer instructions before the combined human session; it does not close Windows acceptance.
### `scripts/collect-fidelity-windows.cmd` and `.ps1`
**Partial analog for `.cmd` only:** `scripts/package.sh` lines 144–145 contain generated launcher content:
```bat
@echo off
"%~dp0GamePort.exe" --assets "%~dp0assets" --scene "%~dp0scenes\level1b\scene.json" --level gam/level1b.gam --walk %*
```
Reuse script-relative quoted port paths. This stub does not collect hashes, OBS/DxWnd versions/settings, GPU/driver data, media or structured results. No tracked `.ps1` or standalone `.cmd` analog was returned by `git ls-files`. The new PowerShell collector requires a new bounded design from RESEARCH.md: preflight, generated-copy separation, explicit local tool selection, external recording checklist, separate original-DxWnd/native-port receipts, postflight and abort paths. Do not invent a working DxWnd profile or claim this stub proves Windows collection.
### Python test files
**Applies to:** `tests/test_fidelity_sessions.py`, `tests/test_fidelity_receipts.py`, `tests/test_fidelity_ledger.py`.
**Analog:** `tests/test_extractors.py`.
**Imports/root convention** (lines 1–12):
```python
import json
from pathlib import Path
import struct
import sys
import tempfile
import unittest
import zlib
ROOT = Path(__file__).resolve().parents[1]
ORIGINAL = ROOT.parent / 'Original'
sys.path.insert(0, str(ROOT / 'tools' / 'extractors'))
from omt import Database, FormatError, Reader, export_scene, read_canvas, read_material, read_shape, unpack_row, validate_output, write_png
```
Use only required imports and adapt the import directory to `tools/recon`; do not pull extractor modules into receipt tests.
**Small failing inputs** (lines 17–20):
```python
class BoundedReaders(unittest.TestCase):
def test_read_bounds_and_negative_size(self):
for size in (-1, 2):
with self.assertRaises(FormatError): Reader(b'x').take(size)
```
**Temporary output and real assertion** (lines 46–52):
```python
def test_png_roundtrip_payload(self):
rgba = bytes((4,5,6,255,10,20,30,0))
with tempfile.TemporaryDirectory() as t:
path = Path(t)/'test.png'
write_png(path, 2, 1, rgba)
data = path.read_bytes()
self.assertEqual(data[:8], b'\x89PNG\r\n\x1a\n')
```
Use temporary tiny original/copy/package/media trees for overlap, reuse, symlink escape, changed/missing/added file, bad marker, evidence classification and stale applicability failures. Keep synthetic media labeled and outside real receipt indexes. Unlike original-resource integration tests, quick negative tests should run without a local game installation/GPU. Proposed discovery remains `python3 -m unittest discover -s tests -p 'test_fidelity_*.py' -v`; measure bounded runtime. `tests/fidelity-viewer.test.mjs` has no same-language analog; use the research's built-in Node test approach for independent playback/audio state behavior.
### Optional `FidelityObservation.cs` and `Program.cs`
**Analog/integration owner:** `src/GamePort/Program.cs`. This is an application-boundary match, not an existing recorder API.
**Imports** (lines 1–8):
```csharp
using System.Diagnostics;
using System.Numerics;
using GamePort.Assets;
using GamePort.Application;
using GamePort.Audio;
using GamePort.Game;
using GamePort.Platform;
using GamePort.Rendering.Vulkan;
```
**Session lifetime** (lines 18–30):
```csharp
using var presentation = new RenderSession();
OriginalSave? carriedSave = null;
PlayerLevelState? carriedPlayer = null;
var returning = false;
var diagnostics = new DebugDiagnostics { Enabled = args.Contains("--debug-overlay") };
var energy = new PlayerEnergy();
var grapplerMemory = new GrapplerMemory();
while (true)
{
var result = Run(args, carriedSave, carriedPlayer, returning, diagnostics, presentation, energy, grapplerMemory, out var continuation);
if (result != 0 || continuation == null) return result;
args = continuation.Args; carriedSave = continuation.Save; returning = continuation.Returning;
carriedPlayer = continuation.Player;
```
A continuous-route observation owner belongs across this outer loop. Creating an unrelated new session for each `Run` would lose the retained departure/return relationship.
**Clock/event anchors:** line 819 starts `var clock = Stopwatch.StartNew();`; line 826 creates `var stepClock = new FixedStepClock();`; line 1133 polls `while (!headless && Sdl.SDL_PollEvent(out var e))`. Record monotonic elapsed time separately from simulation ticks; raw polled events and accepted gameplay input are different observations. Focus/debug/menu filtering occurs afterward, so polling alone is not an accepted-input trace.
**Retained transition publication** (lines 1866–1869):
```csharp
continuation = new(nextArgs.ToArray(), (debugCheckpointToLoad ?? interactions!.Snapshot()) with {
StartPoint = transitionRequest.StartPoint, StoredVector = debugCheckpointToLoad?.StoredVector ?? returnRoot }, transitionRequest.Returning,
debugCheckpointToLoad == null ? simulation?.CaptureLevelState(interactions!.Inventory.SelectedGadget) : null);
Console.WriteLine($"Loading original destination: {transitionRequest.LevelFile}, start={transitionRequest.StartPoint}; fade behavior remains unreconstructed.");
```
Observe at actual transition/input owners without changing these payloads or update order. TSK retained first-story order, fresh direct-scene order, landing bank, actor admission and lab/outside compatibility remain protected. Add the helper only if existing logs and external recording cannot supply required evidence. Preserve smoke-fixture classification; injected fixtures cannot replace ordinary full-route input.
**Existing application error boundary** (line 33):
```csharp
catch (Exception error) { Console.Error.WriteLine(error); return 1; }
```
A new optional observer needs explicit output ownership/disposal and bounded buffering. Do not add asynchronous gameplay ownership or a hidden retry/reset to achieve capture success.
### Ledger/protocol/viewer and durable reports
**Applies to:** `docs/evidence/scenarios.json`, `docs/evidence/capabilities.json`, `docs/evidence/README.md`, the three viewer sources, and `docs/progress.md`, `docs/tasks.md`, `docs/decisions.md`, `docs/compatibility.md`.
**Documentary analog:** tracked `docs/checkpoint/coverage.md` lines 63–66:
```markdown
**S**=static/data recovery, **P**=isolated original component probe,
**M**=managed port regression, **R**=port runtime. No row has full original-game
runtime comparison. Coverage does not mean implementation completeness.
```
Its table header at line 100 is `| ID / system | Recovered contract / anchors | Port implementation | Evidence / remaining gap | Next bounded action |`. Reuse the separation of source contract, implementation, actual evidence and remaining action. JSON schemas are new; keep requirement IDs, scope/platform/content identities, current applicability, discrepancies, acceptance and explicit supersession in one authoritative ledger, then render the Markdown/viewer. Historical dates alone cannot select valid current receipts.
**Status-report pattern:** tracked `docs/compatibility.md` lines 5–10:
```markdown
The user has a local Windows PC for combined reference/port checkpoint sessions.
Original-game reference execution is planned through DxWnd on a generated copy;
record Windows, DxWnd version/settings and capture limitations. Native Windows
port results remain distinct. This is setup availability and a discussion decision,
not a new launch, capture, original-comparison or native Windows verification
receipt. Existing verification claims and open acceptance dependencies remain.
```
Apply this evidence precision to all four durable status files. State what actually ran, on which revision/platform, and what remains open; do not copy old success totals into a new checkpoint.
There is no tracked HTML/CSS/JS viewer analog. Use RESEARCH.md's native media design: unobstructed paired playback, separately observed event seeks, rate 1, visible scenario/playback drift, exclusive audio, explicit buffering/decode/missing-media/asymmetric-end states, optional overlays and visible review gain. Use text rendering for imported labels. If a server is necessary, expose only the generated review tree on loopback with validated containment and tested seeking; never serve originals/the repository as the viewer root. The protocol must encode fresh/retained × natural/skipped × ordinary/edge and full-route/focused distinctions.
## Shared Patterns
### Filesystem boundary replaces authentication concerns
There is no account/authentication flow in this phase. Apply the `reference_capture.py:150–155` path guard to staging/import/review generation, then strengthen it for unique sessions and symlink-safe relative references. No hosted service or write API is required.
### Identity and failure remain separate from acceptance
Apply `inventory.py:21–26` fail-closed comparison to original preservation and `package.sh:48–52` build identity to packaging. Add actual byte hashes and typed evidence classifications; exit zero, valid JSON, a compiled binary, a prepared bundle and synthetic media cannot independently close original/native acceptance. Retain error receipts and diagnostic artifacts.
### Local outputs and bounded tools
Reuse `reference_capture.py` argument arrays, explicit cwd/log outputs and timeouts, and `test_extractors.py` temporary-fixture structure. Keep packages/media/generated review indexes local and ignored. No npm/PyPI additions or cloud storage are implied. Preserve the unrelated untracked `tools.yaml`.
### Movement and execution gates
All capture work observes the existing runtime. No movement reset, retiming, body admission, solver replacement or original-in-place execution is part of this map. Real Windows original-DxWnd and native-port results remain a combined human checkpoint after independent preparation is complete. If unavailable/failed, receipts retain open acceptance while independent source-backed work can continue.
## No Analog Found
| File | Role | Data Flow | Reason / fallback |
|---|---|---|---|
| `tools/recon/fidelity_viewer/index.html` | component | event-driven | No tracked web UI; use research's native media layout and actual local playback review |
| `tools/recon/fidelity_viewer/viewer.js` | component | event-driven | No paired player/state machine; implement/test explicit timing and audio rules |
| `tools/recon/fidelity_viewer/style.css` | config | transform | No established viewer stylesheet/design system |
| `docs/evidence/scenarios.json` | config | batch | New baseline protocol and required case matrix |
| `scripts/collect-fidelity-windows.ps1` | utility | event-driven, file-I/O | No native Windows preflight/collector; package launch stub is insufficient |
| `tests/fidelity-viewer.test.mjs` | test | event-driven | No tracked JavaScript testing pattern; use Node built-ins per research |
`fidelity_receipts.py` and `capabilities.json` also have no exact schema analog; their partial matches only cover identity and evidence vocabulary. `.cmd` has only the partial generated stub above. None of these gaps should be presented to the planner as an existing API.
## Metadata
**Analog search scope:** tracked `tools/recon`, `scripts`, `tests`, `src/GamePort/Program.cs`, checkpoint coverage and compatibility reports; repository-wide tracked `*.html`, `*.js`, `*.mjs`, `*.css`, `*.ps1`, `*.cmd` search returned no paths.
**Primary source analogs:** five: inventory, reference capture, package assembly, extractor tests, Program application boundary. Documentary inputs: coverage and compatibility.
**Coverage:** 3 exact-owner matches, 9 role matches, 4 partial matches, 6 without an analog (16 / 22 with some match).
**Pattern extraction date:** 2026-11-12.
**Validation:** tracked paths and line anchors inspected read-only; no runtime tests, original execution, build, package, commit or push performed. PATTERNS.md is the only write.
@@ -0,0 +1,35 @@
# Phase 01 — Plan Verification Receipt
**Date:** 2026-11-12
**Result:** VERIFICATION PASSED after one revision cycle; zero remaining blockers/warnings.
Independent initial checker reviewed seven plans, 15 tasks and five waves. All four
requirements and 16 context decisions are covered; dependencies are acyclic and
same-wave file ownership is disjoint. Deterministic verify-command path and stated
failure-direction probes each examined 24 commands with zero findings. New paths
are declared future artifacts, not implementation already present.
## Findings resolved
1. Research resolution blocker: five research questions now carry concrete RESOLVED
planning policies and task references. Unknown Windows/DxWnd/capture/browser
outcomes remain explicit execution acceptance dependencies.
2. Scope warning for plan 01-07: a scope_budget block bounds ten files to two
substantive implementation/test files and serial final evidence/report/runner
projections. The 30,000-token estimate is below the 100,000-token plan budget;
confidence remains low because this roadmap has no calibration samples.
A separate independent checker rechecked both changes and returned VERIFICATION
PASSED with zero blockers/warnings. No requirement or human acceptance was waived.
## Final deterministic gates
- Requirement coverage: EVID-01 through EVID-04, 4/4.
- Context decision coverage: D-01 through D-16, 16/16.
- Post-planning gap analysis: 20/20 combined items; zero uncovered.
- Seven plan structure/frontmatter validations passed during planning.
- Original inventory: 539 unchanged files verified by the prescribed command.
Planning and original inventory checks only: new implementation/test fixtures,
original/DxWnd captures and native Linux/Windows acceptance were not executed.
They remain in the execution plans; prepared materials cannot establish parity.
@@ -0,0 +1,461 @@
# Phase 01: Reproducible Fidelity Baseline - Research
**Researched:** 2026-11-12
**Domain:** Local original/port capture, evidence provenance, comparison playback and native-platform receipts
**Confidence:** HIGH for repository findings; MEDIUM for external capture approach; Windows execution remains unverified.
<user_constraints>
## User Constraints (from CONTEXT.md)
The following decisions and discretion are copied verbatim. [VERIFIED: 01-CONTEXT.md, Implementation Decisions]
<!-- DATA_71ac69ef_START -->
## Implementation Decisions
### Baseline journeys
- **D-01:** Capture the continuous lab → VR04 → lab → outside journey and focused replays of specific moments, including dialogue return, banked jumps and landing.
- **D-02:** Natural and skipped dialogue are equally required baseline cases.
- **D-03:** Fresh entry and retained departure/return receive separate, equally required runs that preserve their respective lifetimes.
- **D-04:** Include ordinary play and deliberate edge cases: held input through dialogue/return, banked jumps, landing and idle.
### Comparison review
- **D-05:** Open scenario results with paired original/port playback and links to corresponding images, audio and input/event traces.
- **D-06:** Keep captures unobstructed by default; annotations and image differences are optional overlays.
- **D-07:** Align key events while preserving actual recording speed and elapsed time; expose timing drift rather than concealing it through retiming.
- **D-08:** Switch between original and port audio at corresponding moments, playing one recording at a time. Clearly label any review-only volume adjustment.
### Evidence navigation
- **D-09:** Browse the full-game ledger by gameplay capability (movement, contacts, gadgets, progression, visuals, audio), with links to scenarios, source evidence and platform receipts. Retain requirement traceability.
- **D-10:** Each capability leads with what works, where it was verified, known differences and remaining acceptance conditions.
- **D-11:** Show current applicable evidence first; retain expandable history with exact revisions and clear superseded labels.
- **D-12:** Order discrepancies by player impact: blocking or visibly disruptive failures first, then subtler differences and missing verification. Missing evidence still leaves its acceptance open regardless of display order.
### Original and Windows access
- **D-13:** The user has a local Windows PC available to run prepared packages and return results. Availability does not itself establish successful native execution.
- **D-14:** Prepare one local test bundle per checkpoint. A launcher collects source/package/resource identities, logs and captures, with clear user steps and local transfer instructions. Packages and captures remain local.
- **D-15:** Run a separate generated copy of the original on that Windows PC through **DxWnd**. Record DxWnd version/configuration and execution/rendering limitations with each capture. Preserve wrapper provenance separately from native Windows port receipts; do not silently treat wrapper behavior as historical-platform parity.
- **D-16:** Prepare all materials before one combined hands-on session per checkpoint, covering original-reference captures and port checks and collecting results together.
### Carried-forward constraints
- Preserve every original byte and never execute originals in place; verify against `docs/original-manifest.json`.
- Preserve the implemented TSK-backed first-story input-order correction, fresh direct-scene order and legitimate landing bank. No invented leveling reset or replacement movement tuning.
- Keep source recovery, inference, copied-original component execution, port runtime, Wine, DxWnd reference execution, cross-publish and native platform receipts explicitly distinguished.
- Current Windows and original-reference acceptance remain open until new identified receipts demonstrate the required scenarios. A prepared bundle, wrapper launch or historical result alone cannot close them.
- All builds/tests/captures/packages stay local. Push only verified source/tools/docs to the existing Gitea remote. Preserve current actor/collision admission gates and the lab/outside compatibility solver.
### Agent discretion
No product decisions were explicitly delegated. Research/planning selects file formats,
local viewer technology, capture tooling, event markers and bundle mechanics within
the decisions above. The discussion does not require an external hosted website.
## Deferred Ideas
None — discussion stayed within phase scope. Native execution and capture are
future execution tasks, not results established by this discussion.
<!-- DATA_71ac69ef_END -->
</user_constraints>
## Summary
Build an evidence workflow around the established runtime. Extend preservation/capture orchestration, add identified scenario receipts and a capability ledger, and generate a local paired-media viewer. First prove one actual focused original/port comparison; then complete the full route and required case matrix. These are implementation recommendations within the explicit file-format/viewer/bundle discretion above.
The present reference harness captures three timed screenshots in isolated Wine, redirects ALSA to null and reuses an existing generated game directory. Its result is neither a continuous audible recording nor Windows/DxWnd execution. [VERIFIED: tools/recon/reference_capture.py:88-106,149-160] The package script records source revision, dirty state and package time, but those three fields are the scope of its identity block; extend them with hashes of executables, resources and captured artifacts. [VERIFIED: scripts/package.sh:48-52] Current reports explicitly keep original-game and native Windows verification open. [VERIFIED: docs/compatibility.md:3-24]
**Primary recommendation:** Use Python standard-library orchestration/validation, plain HTML/JavaScript playback, existing .NET/SDL replay hooks, a prepared local Windows launcher and an OBS recording preflight for the generated original through DxWnd and the native port separately. Do not change movement, collision admission or gameplay to make a capture pass.
## Architectural Responsibility Map
The following is the recommended ownership boundary, not a claim about already implemented capture features.
| Capability | Primary Tier | Secondary Tier | Rationale |
|---|---|---|---|
| Preserve originals and stage execution copies | Local tooling/filesystem | Windows launcher | Verify before copying; never use the source installation as working directory |
| Port input/event observations | Application/platform boundary | Local receipt collector | Observe accepted input and scene/control changes at their actual owners |
| Original reference video/audio | Windows recording tools | Human operator | Capture externally without pretending port instrumentation exists in the original |
| Event annotation and receipt validation | Local tooling | Human reviewer | Separate manually observed events from instrumented state |
| Paired playback and capability browsing | Browser/client | Read-only loopback file service if needed | No hosted application or database |
| Provenance and history | Versioned JSON/Markdown plus local hashed artifacts | Validator | Source metadata is reviewable; large media stays local |
## Project Constraints (from AGENTS.md)
Actionable directives from the local and parent instructions and authoritative specification: [VERIFIED: AGENTS.md; ../AGENTS.md; ../prompt.MD]
- Follow the parent instructions/specification; originals are authoritative, byte-identical, and never executed in place. Keep analysis, extraction, build and capture output separate.
- Use shared C#/.NET 10, Silk.NET.Vulkan/Vulkan 1.3+ and SDL3 for Linux/Windows x64; keep builds/tests/packages local and the runtime offline.
- Push only completed verified source/tools/docs to existing Gitea through the integrating primary; no original/package uploads, cloud CI or telemetry. This research assignment explicitly excludes committing/pushing.
- Keep recovered source/data, inference, implementation, compilation, component execution, port runtime, Wine, wrapper reference and native verification distinct.
- Preserve Jimmy movement, first-story TSK retained ordering, fresh direct-scene ordering and legitimate landing bank. Keep movement stabilization first; no new gadgets, movement replacement or invented angle reset.
- Preserve live collision/helper/actor admission gates and lab/outside compatibility solver; do not equate isolated recovered components with live gameplay.
- Use REA for any new original-binary investigation, preserve complete Evidence and cross-check bytes/addresses/provider gaps. This phase needs no new binary investigation.
- Use bounded endian-aware parsing, portable/case-insensitive original paths, clear modules, deterministic tests and explicit unmanaged ownership. Build frequently if runtime changes.
- Respect exclusive file ownership, at most three investigators alongside primary, primary integration, and unrelated working-tree files.
- Update progress, tasks, decisions and compatibility evidence before transitions. Read checkpoint coverage/implementation and current reports before gameplay/package work.
- Use local SDK environment and existing build/test/package entry points. Existing runtime claims require actual matching runtime evidence.
## Phase Requirements
<phase_requirements>
Descriptions below are verbatim from the requirements file. [VERIFIED: .planning/REQUIREMENTS.md, Reference and Fidelity Baseline]
| ID | Description | Research support |
|---|---|---|
| EVID-01 | Every original file remains byte-identical to the recorded inventory throughout recovery, testing and release preparation; generated copies and outputs remain separate. | Existing inventory; new bounded staging and pre/post identity guards |
| EVID-02 | Reviewers can reproduce identified original-game reference scenarios from an isolated generated installation, with input/event, visual and audio captures where applicable; unresolved execution limitations are recorded and leave comparison acceptance open. | Windows/DxWnd generated-copy procedure, external recording, event annotations, failure receipts |
| EVID-03 | Reviewers can identify each capability's source evidence, implementation revision, runtime platform, current discrepancy and acceptance condition in a maintained full-game coverage ledger. | Capability-led JSON/Markdown ledger, exact receipt references and explicit supersession |
| EVID-04 | Testers can repeat the baseline movement/route scenarios on native Linux and native Windows with revision-specific receipts; cross-publish, Wine, component execution and native gameplay remain separately labeled. | Shared scenario protocol, existing port hooks, separate native receipts and one combined Windows session |
</phase_requirements>
## Standard Stack
Do not add game or JavaScript packages for this phase. Existing package references are a constraint, not an instruction to upgrade dependencies.
| Layer | Use | Version / evidence |
|---|---|---|
| Runtime | Existing .NET and Vulkan implementation | Project declarations verbatim: `<TargetFramework>net10.0</TargetFramework>`, `<RuntimeIdentifiers>linux-x64;win-x64</RuntimeIdentifiers>`, `Include="Silk.NET.Vulkan" Version="2.23.0"`; KHR/EXT references also declare `Version="2.23.0"`. [VERIFIED: GamePort.csproj:4-17] |
| Evidence tooling | Python stdlib: pathlib, hashlib, json, argparse, subprocess, unittest | Python probe returned `Python 3.12.3`; inventory already uses these primitives. [VERIFIED: environment probe 2026-11-12; tools/recon/inventory.py:3-28] |
| Viewer | Plain HTML, CSS, JavaScript and native media elements | Media APIs expose time, rate, mute and playback; normal speed is 1.0. [CITED: https://html.spec.whatwg.org/multipage/media.html] |
| Recording | OBS Studio locally on Windows; installed version recorded at execution | Offline recording and MKV/remux workflow are documented; Windows Display Capture captures the monitor. [CITED: https://obsproject.com/kb/standard-recording-output-guide] [CITED: https://obsproject.com/kb/display-capture-sources] |
| Media inspection | Existing ffprobe/ffmpeg locally; no automatic download | Probe returned FFmpeg `6.1.1-3ubuntu5+esm15`; ffprobe provides machine-readable stream/format inspection. [VERIFIED: environment probe 2026-11-12] [CITED: https://ffmpeg.org/ffprobe.html] |
| Original wrapper | User's local DxWnd distribution/configuration, retained by hash and reported version | Official project describes a Windows window hooker; no compatible Neutron profile was established here. [CITED: https://sourceforge.net/projects/dxwnd/] |
| Native launcher | PowerShell/.cmd on Windows; shell/Python on Linux | Recommendation: keep launch steps transparent; do not require the Windows user to install Python/.NET SDK for a self-contained port package |
**Installation:** No npm/PyPI/NuGet additions proposed. Record actual Windows DxWnd/OBS/browser versions during preflight, rather than selecting a guessed latest version. Do not redistribute unreviewed third-party tools inside the checkpoint.
### Alternatives Considered
| Choice | Alternative | Decision |
|---|---|---|
| Plain local viewer | React/Electron application | Use plain media elements; component framework/desktop packaging adds no necessary capability here |
| External Windows recording | Custom DirectDraw hook/injected original recorder | Start externally; capture problems are observed limitations, not permission to modify original execution semantics |
| Read-only generated viewer tree | Database/API service | Use identified static records; no multi-user or remote persistence requirement |
| Manual focused original annotations | Original input injection/whole-route automation | Accept honestly labeled observed/manual markers initially; do not invent an original-side deterministic replay guarantee |
## Package Legitimacy Audit
Not applicable: no new ecosystem packages are recommended. Existing locked game dependencies remain unchanged. OBS/DxWnd/FFmpeg are external executables, so retain official provenance, actual versions and hashes during preparation rather than applying an npm existence check. This research neither installs nor runs them on Windows.
## Existing Analogs and Verified Integration Points
Existing symbols/options below are quoted verbatim beside source citations. Proposed filenames later are explicitly recommendations, not existing paths.
| Existing analog | Verified fact and planning implication |
|---|---|
| Inventory | `def inventory(root):` emits `"path"`, `"size"`, `"sha256"`, `"header"`; mismatch raises `"Original inventory differs from recorded baseline"`. Reuse the exact original manifest comparison; verify the copy before execution separately from legitimate post-run copy mutations. [VERIFIED: tools/recon/inventory.py:9-26] |
| Wine harness | `def inside(args):`, `def main():`; timed `for index in range(3):`, `time.sleep(args.seconds / 3)`; copy creation `shutil.copytree(source, work/'game')` only when absent. Preserve this narrow legacy path or separate Windows orchestration; do not relabel it. [VERIFIED: tools/recon/reference_capture.py:40-106,115-157] |
| Existing generated directories | `work.mkdir(parents=True, exist_ok=True)`, `(work/'home').mkdir(exist_ok=True)`, `default_output = 'artifacts/windows-smoke' if args.port_smoke else 'artifacts/asset-probe' if args.asset_probe else 'artifacts/reference'`. These are created/selected by the harness, not a proposed new capture schema. [VERIFIED: tools/recon/reference_capture.py:152-160] |
| Package assembly | `out="dist/$rid"`, `mkdir -p "$out/assets"` (same line creates scene/audio/license/docs subdirectories), and `> "$out/BUILD-INFO.txt"`. Its identity fields are `source_commit=%s`, `source_dirty=%s`, `packaged_utc=%s`. Hash a completed package tree and separate receipt; do not stamp a later docs HEAD onto an older DLL. [VERIFIED: scripts/package.sh:7-11,48-52] |
| Native CLI fixtures | `"--smoke-walk"`, `"--smoke-jetpack"`, `"--smoke-carl-cutscene"`, `"--smoke-control-phases"`, `"--smoke-practice-return"`. They are selected by explicit options; preserve their semantics and test identity. [VERIFIED: src/GamePort/Program.cs:263-283] |
| Idle regression | `LandWhileLocked` and `VerifyReturn` execute bounded synthetic setup/resumption checks; they are not a human full-route recording. [VERIFIED: src/GamePort/Application/CutsceneIdleSmoke.cs:9-30] |
| Window regression | `WindowTransitionSmoke` explicitly says `"not a gameplay replay"`; `Directory.CreateDirectory(output);` creates output. Use for resource/window lifetime, not route completion. [VERIFIED: src/GamePort/Application/WindowTransitionSmoke.cs:9-16] |
| Live observation seam | `var clock = Stopwatch.StartNew();`, `var stepClock = new FixedStepClock();`, `Sdl.SDL_PollEvent(out var e)`. Observe here and at transitions without altering update order. [VERIFIED: src/GamePort/Program.cs:819-826,1133-1148] |
| Scene continuation | `continuation = new(nextArgs.ToArray()` carries the snapshot/retained state; log scene transition identity with one session lifetime spanning scene loops. [VERIFIED: src/GamePort/Program.cs:1846-1869] |
| Local test integration | `python3 -m unittest discover -s tests -p 'test_*.py' -v`, managed projects and native/headless checks are composed in the existing script. [VERIFIED: scripts/test.sh:4-67] |
Repository source files were opened directly in this session. Paths above identify inspected files; quoted generated-path expressions identify their actual creating code.
## Architecture Patterns
### System Architecture Diagram
Recommended data flow:
```mermaid
flowchart TD
O[Immutable original installation] --> H[Preflight inventory verification]
H -->|match| C[Fresh generated Windows reference copy]
H -->|mismatch| F[Failure receipt; no execution]
C --> D[DxWnd plus external recording]
P[Identified offline port package] --> N[Native Linux or Windows play]
N --> R[Port events, logs and external recording]
D --> I[Local importer and artifact hash validation]
R --> I
I -->|valid and complete| E[Scenario receipts and capability ledger]
I -->|missing or failed| U[Explicit open acceptance and discrepancy]
E --> V[Paired local playback]
U --> V
V --> A[Human review with actual timing and one audio source]
```
### Recommended Project Structure
These are NEW proposed files; the executor must create them explicitly:
- Extend orchestration alongside the existing recon tools with a small capture-session/receipt validator module and command-line entry point.
- Add a dedicated viewer source directory under tools/recon, containing static HTML/CSS/JS; generated local media/index belong below ignored artifacts output.
- Add a versioned scenario protocol and capability-ledger JSON under docs/evidence, with a concise rendered Markdown entry point.
- Add Windows preparation/collection scripts under scripts and Python regression coverage under tests.
- Only add a focused application observation helper if required; keep runtime composition changes small and avoid growing the monolithic program with recorder policy.
These locations follow existing repository boundaries; all are proposed additions, not source-of-truth filesystem constants.
### Pattern 1: Immutable session plus append-only observations
Recommended receipt model (new schema, not recovered source enums):
- Versioned schema and stable scenario/session identity; case dimensions include dialogue policy, startup/entry lifetime, ordinary/edge input and route/focused scope.
- Exact source revision, dirty flag/diff identity if applicable, package tree/executable hashes, original manifest hash, resource tree hash, launcher version/hash.
- Platform OS/version, native versus Wine versus original-DxWnd classification; GPU/driver/Vulkan/SDL evidence for port; DxWnd binary/config hashes and actual settings for original.
- Actual invocation, working directory, preflight/postflight inventory result, start/end monotonic and wall-clock timestamps, exit/abort result.
- Per-artifact relative path, bytes, SHA-256, media duration/stream metadata and derivation chain. Keep raw recording and derived preview separately.
- Event markers carry media timestamp, event identity, observation method, uncertainty and supporting frame/log; port simulation tick is a separate optional field. Never fill an original internal-state field from a component fixture.
- Explicit missing artifacts, failure reason and remaining acceptance. An empty directory or exit-zero launcher cannot mean scenario pass.
Use a unique new directory per run and fail on accidental reuse. Check path containment before creating anything; resolve aliases/symlinks and reject overlap with originals in either direction. Verify original inventory before staging, verify pristine execution copy before running, and verify source originals after collection. Runtime writes in the generated copy are expected observations; preserve a pre-run identity manifest and post-run diff.
### Pattern 2: One baseline protocol, multiple evidence methods
Recommended minimum matrix is fresh-session versus retained-entry × natural versus skipped dialogue, with ordinary and edge-input coverage in every combination. Make these explicit cells, not four loosely named recordings. The continuous journey must preserve real lab departure/VR04 return/outside progression; focused replays may use identified setups but cannot substitute for that continuity.
Define procedural checkpoints around: startup/control; dialogue entry; natural or skip boundary; first neutral and held-input resumed moments; left/right banked jump; support/landing; sustained idle; practice entry; VR04 use; RETURN/cleanup; lab exit and outside arrival. Log scene names, ownership and media markers as actually observed. Do not invent numeric timing tolerances: report raw deltas and annotation uncertainty pending original observations.
Record ordinary player input in native port sessions; existing injected smoke fixtures remain separate replay receipts. For the original minimum, use the same written input procedure plus manually annotated video/event intervals with uncertainty and held/released descriptions. Do not claim exact original key sampling without a proven original-side observer. If exact key transition recording is needed, add a bounded local recorder as a distinct instrumented run; preserve a clean visual/audio baseline.
### Pattern 3: Two independent clocks, explicit alignment
Use native media elements at actual speed. Selecting an event pauses both sides and seeks each to its own observed event timestamp; resume at normal speed from there. Display both elapsed times and differences at later corresponding markers. Do not continuously seek the follower, alter playback rates or normalize run durations to manufacture agreement.
Separately show playback drift (browser rendering/buffering) and scenario event drift (actual recorded behavior). Buffering or missing media should pause the review and expose a warning; do not silently skip. Preserve asymmetric tails when one recording ends earlier. Mute both before changing audio selection; enable at most one. Keep any review gain visible and default to unadjusted audio. These are recommendations implementing D-05 through D-08; the underlying time/rate/mute interfaces are documented. [CITED: https://html.spec.whatwg.org/multipage/media.html]
Optional overlays must leave raw recordings available. Image differences require same viewport/aspect, crop metadata and matched event/frame provenance; numerical differences of lossy video are not a fidelity oracle. Use lossless identified stills for byte/difference assertions and label overlays as review aids.
### Pattern 4: Capability ledger with explicit applicability
Create one structured authoritative ledger, and render its navigation rather than maintaining two independent status sources. Capability entries should retain requirement IDs and contain current behavior, scope/scene, source contract links, implementation revision, identified runtime receipts per platform, discrepancies by player impact, acceptance condition, and explicit supersedes/reason links.
Seed all full-game requirement categories, including unimplemented/unverified capabilities; do not limit the ledger to Phase 1 or to current movement fixtures. Retain detail rows or links from the existing checkpoint ledger. Its own legend explicitly distinguishes static/probe/managed/runtime scopes: `**S**=static/data recovery, **P**=isolated original component probe,` and `**M**=managed port regression, **R**=port runtime.` [VERIFIED: docs/checkpoint/coverage.md:63-66]
Current applicable evidence is selected by revision/content/scope/platform, not latest date. A docs-only revision does not invalidate matching unchanged runtime evidence; changed executable/resources require new applicability review. Keep contradictory/old claims in expandable history with explicit supersession, rather than rewriting history as if the defect never existed.
## Minimum Viable Windows Recording and Bundle
Recommended executable sequence:
1. Prepare one checkpoint root with a complete Windows port package, pristine generated original installation, original and package manifests, scenario instructions, a local result directory, launcher/collector, expected artifacts checklist and offline viewer. Include local transfer instructions only; no upload endpoint.
2. Launcher preflight verifies bundled hashes and path separation, records OS/GPU/driver and tool identities, and asks the operator to select the actual DxWnd executable/profile and recording application. Reject missing dependencies with an actionable local receipt, without downloading tools automatically.
3. Perform a short original-DxWnd and port video/audio preflight before the full route, within the same combined hands-on session. Check visible moving game content, intelligible game audio, correct capture area/aspect and elapsed-time behavior. Keep a failed preflight and its limitations.
4. Start externally recorded sessions before game interaction. Use OBS Display Capture as the initial Windows method to avoid assuming old renderer hook compatibility; record only the intended monitor/game crop and retain raw frame/crop metadata. Use the applicable Linux OBS screen-capture source for Linux sessions. These source availability distinctions are documented. [CITED: https://obsproject.com/kb/display-capture-sources]
5. Record locally to MKV and retain it; remux a separate browser-compatible preview if the tested browser needs it. Keep derivation command/tool version and original timestamps. OBS documents MKV and remux; ffprobe documents format/stream inspection. [CITED: https://obsproject.com/kb/standard-recording-output-guide] [CITED: https://ffmpeg.org/ffprobe.html]
6. Run required continuous and focused cases in prescribed order, each with fresh/retained setup recorded. Preserve reference copy writes/settings per case. Native port output is collected separately from DxWnd wrapper output.
7. Collector hashes recordings/logs/settings, writes structured per-run results and copies local annotations; record skipped/aborted cases honestly. Return one complete local result bundle; importing validates it before linking it into the ledger/viewer.
8. Complete audible/visual review and inventory postflight, then update current receipts and open discrepancies. If original execution or native Windows fails, keep EVID-02/EVID-04 open and proceed only with independent permitted work.
DxWnd's project-maintainer logging procedure writes a log in the game execution folder. That makes a writable generated working directory essential; logging is not evidence the original behaved faithfully. [CITED: https://sourceforge.net/p/dxwnd/discussion/general/thread/6e4aa579/] Do not invent a working profile, forced renderer, speed limit or timer setting. Preserve the user's actual exported profile/config and identify any relocation edits. Rich diagnostic runs may perturb timing; label them separately.
## Don't Hand-Roll
| Problem | Don't build | Use instead | Reason |
|---|---|---|---|
| Original-game recording | New injected graphics/audio interception | External recording preflight and explicit limitations | Keeps Phase 1 bounded; original instrumentation has separate evidence costs |
| Media decode/playback | Custom browser decoder or time stretcher | Native video/audio elements | Standard time/rate/mute APIs exist. [CITED: https://html.spec.whatwg.org/multipage/media.html] |
| Stream discovery | File-extension inference | ffprobe JSON output | Stream/format metadata is inspectable. [CITED: https://ffmpeg.org/ffprobe.html] |
| Original integrity | New incompatible inventory format | Existing inventory helper and manifest | Complete list equality is already enforced. [VERIFIED: tools/recon/inventory.py:21-26] |
| Gameplay route | Scene swaps represented as completed route | Human continuous capture plus existing bounded regressions | Window fixture itself excludes gameplay replay. [VERIFIED: src/GamePort/Application/WindowTransitionSmoke.cs:9] |
| Evidence publication | Cloud dashboard/CI/database | Versioned metadata and local media | Required by locked local-only decisions |
## Common Pitfalls
| Failure | Prevention and verification |
|---|---|
| Wine stills become original reference video | Preserve execution category and require actual continuous audiovisual artifacts; harness uses three screenshots and null audio. [VERIFIED: tools/recon/reference_capture.py:90-106,159-160] |
| An old generated installation contaminates a fresh run | Unique staging directories, pre-run copy hashes and explicit retained lifetimes; current harness only copies when the game directory is absent. [VERIFIED: tools/recon/reference_capture.py:157] |
| Native and cross-publish results collapse into one Windows status | Validate receipt category, platform and scenario independently; current report explicitly excludes new Windows execution. [VERIFIED: docs/compatibility.md:18-24] |
| Identity says clean while captures came from other binaries | Hash actual executable/resources and compare imported receipts; build script's source fields alone do not bind individual captures. [VERIFIED: scripts/package.sh:48-52] |
| Old Carl narrative reopens an implemented defect | Apply later source-supported TSK correction; historical next-work prose is followed by explicit correction and open comparison boundaries. [VERIFIED: docs/checkpoint/next-work-plan.md:14-25] |
| Retained scenario restarts the process mid-route | Carry one session/continuation identity through actual transitions; record real source lifetime and don't replace RETURN with a direct scene fixture |
| Viewer hides timing differences | Fixed normal speed, explicit user-triggered event alignment, raw durations and visible drift |
| Silent/black recordings count as acceptance | Preflight checks actual changing game content and audible output; metadata presence alone cannot prove either |
| Synthetic media/tests enter real ledger | Require explicit synthetic designation and reject them as original/native acceptance; test fixtures may validate plumbing only |
## Code Examples
These are recommended new glue patterns, not existing repository APIs. No recovered game constants or schema enums are introduced.
### Preservation command already supported
```bash
python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
```
The positional root and `"--verify"` are implemented by the inventory command; mismatch exits before the success message. [VERIFIED: tools/recon/inventory.py:17-26] This exact invocation is mandated by project instructions. [VERIFIED: AGENTS.md, original preservation directive]
### Paired audio selection and actual speed
```javascript
// Recommended viewer glue; media APIs: WHATWG HTML media elements.
function selectAudio(original, port, useOriginal) {
original.muted = true;
port.muted = true;
(useOriginal ? original : port).muted = false;
}
function alignAtObservedEvent(original, port, originalTime, portTime) {
original.pause();
port.pause();
original.currentTime = originalTime;
port.currentTime = portTime;
original.playbackRate = port.playbackRate = 1;
}
```
Time, rate and mute controls are documented APIs. [CITED: https://html.spec.whatwg.org/multipage/media.html] Production glue must validate finite in-range marker times, await media readiness/seeking, expose play rejection/buffering and retain manual controls. No periodic resync is permitted by the recommended design.
## Bounded Executable Slices
These are planning recommendations in dependency order. Each slice produces a usable part of the actual evidence workflow.
1. **Preserved session and receipt contract.** Stage a generated original copy, verify original/copy hashes, collect an identified existing native port focused run and implement receipt validation. Include failing/stale/incomplete result paths. Define the full scenario matrix now; do not invent successful original captures.
2. **Local paired comparison vertical slice.** Import one actual focused original-DxWnd/port pair when available and open it with media links, time markers, drift and exclusive audio selection. Until real original media arrives, labeled synthetic media exercises viewer plumbing only. Include a completed ready-to-run Windows preflight/bundle path so this is executable.
3. **Current full-game capability ledger.** Reconcile current reports and checkpoint rows into capability-first entries covering every requirement category; link the working scenario viewer, actual receipts, discrepancies and expandable historical revisions. Run metadata validation without a GPU.
4. **Full route capture and native Linux baseline.** Exercise continuous route and all required focused cases, including fresh/retained, natural/skipped and normal/edge inputs. Extend observation hooks only where needed without changing update order; repeat targeted protected movement/ownership checks if runtime composition changes.
5. **One Windows checkpoint and import/review.** Finalize all materials before a single combined human session collecting original-DxWnd and native port cases; validate results locally, inspect audiovisual behavior, update evidence and leave explicit failures open. The phase cannot be fully accepted through a prepared bundle alone.
Dependencies: receipt format before viewer/import and launcher; real capture import before acceptance; ledger population and viewer work can otherwise progress independently with exclusive files. Human session happens after all independent preparation, not as repeated requests after each small task.
## Environment Availability
Actual local probes on 2026-11-12; Windows availability is a user declaration, not a remote machine probe. [VERIFIED: environment probe this session] [VERIFIED: 01-CONTEXT.md, D-13 through D-16]
| Dependency | Available here | Version / result | Planner action |
|---|---|---|---|
| Python | Yes | 3.12.3 | Use stdlib tooling/tests |
| Node | Yes | 24.22.1 | Optional viewer pure-JS checks; do not add packages |
| Project SDK | Yes after sourcing environment | 10.0.402 | Existing .NET 10 project and tests |
| ffmpeg / ffprobe | Yes | ffmpeg 6.1.1 distribution build | Probe capabilities/version in receipt; do not silently assume codec availability |
| Chromium / Firefox | Commands found | Browser execution/version not tested here | Verify actual playback and media decoding |
| OBS / PowerShell | No command returned by command lookup here | Windows installation not inspected | Bundle dependency preflight; no execution guarantee |
| DxWnd on user's Windows | Not inspected | User's actual version/profile unknown | Hands-on preflight and record provenance |
| Native Windows port/Vulkan | Not executed this session | Current report keeps acceptance open | Human run required |
| Original installation | Verified read-only inventory | Output: `Verified 539 unchanged original files` | Repeat before/after execution/package checkpoint |
| Knowledge graph | Disabled | Status response reported disabled | Use direct source and current reports |
No runtime suites, new original-binary probes, packages or native Windows captures were run for this research. Missing Windows execution is an explicit acceptance dependency; it does not block preparation, ledger or independent source-backed later work under the roadmap exception.
## Validation Architecture
Validation is enabled in project configuration: `"nyquist_validation": true` and security `"security_enforcement": true`. [VERIFIED: .planning/config.json:23-25,49-51]
### Test Framework
| Property | Value |
|---|---|
| Existing tooling tests | Python stdlib unittest; existing tests import `unittest` and use temporary directories. [VERIFIED: tests/test_extractors.py:1-20] |
| Existing managed tests | Standalone .NET console projects called through the local script. [VERIFIED: scripts/test.sh:6-54] |
| New quick command, proposed | `python3 -m unittest discover -s tests -p 'test_fidelity_*.py' -v` |
| Pure viewer logic, proposed | `node --test tests/fidelity-viewer.test.mjs` using built-in assertions/test runner; executor creates this file, no npm dependency |
| Existing full suite | `scripts/test.sh`; native window option is `NEUTRON_WINDOW_TEST=1 scripts/test.sh`. [VERIFIED: docs/tasks.md:419-424] |
| Protected targeted checks | `source scripts/env.sh`, then relevant existing managed Director/Checkpoint/BodyOwnership/Movement projects from script; no suite claimed run here |
New quick-test filenames/commands are proposed Wave 0 additions, not present infrastructure. Keep their fixtures tiny so each quick command is bounded below 30 seconds; measure this rather than assuming the full original inventory or GPU suite meets that budget.
### Phase Requirements → Test Map
| Requirement | Behavior | Test type and command | Existing? |
|---|---|---|---|
| EVID-01 | Changed, missing and added original files fail; read-only staging leaves originals unchanged; copy identity verified before launch | Proposed Python fidelity tests; existing real inventory command above at checkpoint | Inventory yes; temporary-tree negative cases Wave 0 |
| EVID-02 | Valid run imports; bad hashes, missing media/audio, invalid/NaN/out-of-bounds markers, incomplete/failed launch remain open | Proposed Python fidelity tests; media-probe tests with bounded fixtures | Wave 0 |
| EVID-02 | Actual original game is visible/audible through identified DxWnd setup and required scenarios | Human Windows capture/review plus receipt importer | Explicit native/human dependency |
| EVID-03 | Every requirement links to capability; missing evidence never becomes passed; current history selection respects content/platform/scope; dead/unsafe links rejected | Proposed Python fidelity tests | Wave 0 |
| EVID-04 | Reused session, package/resource mismatch and Wine labeled native are rejected | Proposed Python fidelity tests | Wave 0 |
| EVID-04 | Port native Linux and native Windows traverse matched full/focused cases with current revision | Native play/replay, physical input/audio and review; existing smoke hooks supplement | Hooks exist; new route receipts required |
| D-05–D-08 | Event alignment, actual speed, timing drift, no mixed audio, asymmetric end/buffering/missing media | Proposed Node pure-logic tests plus local browser integration/manual media review | Wave 0 |
### Meaningful Negative Cases
- Source/output overlap in either direction; symlink escape; Windows drive/case/path traversal; reused session directory; filename containing shell metacharacters. Must fail before writing/launching.
- One-byte changed copy/package/media; absent DLL/resource; unsupported receipt schema; source revision without actual package identity; cross-publish/Wine/component run offered as native gameplay. Reject promotion, retain diagnostic record.
- Synthetic recording offered as original reference; null/missing audio offered as audible pass; zero-byte/black/frozen recordings. Metadata validator catches structural faults; humans check actual game visibility/audibility.
- Fresh/retained and natural/skipped cells missing despite total clip count; full route replaced by unrelated scene snapshots; interrupted run silently marked complete.
- Marker beyond duration, nonfinite time, absent corresponding event, different viewport or unknown media derivative; viewer must show missing state.
- Audio switch while both playing, play promise rejection, decode failure, one video buffering/ending, and raw difference overlay enabled by default. Fail visibly without rate adjustment.
### Sampling Rate
Per tooling commit run focused Python and viewer logic tests; per runtime observation change also run affected managed ownership/movement tests and a native focused replay. Per integrated checkpoint run the full existing local suite, original verification and identified native Linux route. Final Phase 1 acceptance additionally requires the combined Windows original/native session and actual media review. No automated fixture closes human acceptance.
### Wave 0 Gaps
Create the proposed schema/validator tests, a tiny explicitly synthetic audiovisual fixture with known timestamps, viewer state tests and a completed Windows result/import checklist. Keep synthetic fixtures separated from real receipt indexes. Reuse the existing unittest and .NET conventions; no framework installation required.
## Security Domain
This phase handles local binary/media paths and structured receipts, not accounts or remote application sessions. Recommended controls are narrowly scoped to that surface. OWASP's current published standard is ASVS 5.0.0; the inherited checklist's V2–V6 names refer to older numbering, so do not present them as current ASVS 5 chapter mappings. [CITED: https://asvs.owasp.org/]
| Control domain (legacy checklist label) | Applies | Standard control |
|---|---|---|
| Authentication (V2) | No accounts proposed | Keep service local and read-only; no new authentication system |
| Session management (V3) | No web login session | Capture session identity is provenance, not an auth session |
| Access control (V4) | Yes, filesystem boundary | Allowlisted checkpoint root, resolved path containment, no original directory serving or write APIs |
| Input validation (V5) | Yes | Bounded JSON, finite timestamps, relative-path validation, media/receipt sizes, safe HTML text rendering |
| Cryptography (V6) | Integrity only | stdlib SHA-256 for artifact identity; hashes establish correspondence, not trust in arbitrary executables |
| Threat | STRIDE | Mitigation |
|---|---|---|
| Traversal/symlink or imported absolute path | Disclosure/tampering | Resolve under allowed root, reject escapes and overlaps before execution/import |
| Shell metacharacters in paths/config | Tampering/elevation | Argument arrays, no eval/shell interpolation; never execute a command supplied by a receipt |
| HTML/script in labels or report text | Tampering | textContent/escaped output; no untrusted HTML injection or remote resource URLs |
| Hash-valid but wrong evidence classification | Spoofing/repudiation | Typed receipt validation and human scope review; do not auto-promote by exit code |
| Local server exposes repository/originals | Disclosure | Serve only generated review tree on loopback, reject symlink escapes; no uploads |
| Unbounded JSON/media metadata or capture duration | Denial of service | Limits and explicit abort/error receipts; stream hashes and probe with timeouts |
Python's standard handler follows symlinks outside the served directory, so merely choosing a directory is insufficient containment. [CITED: https://docs.python.org/3.12/library/http.server.html] Prefer a generated self-contained review tree or a bounded read-only handler. Test seeking behavior with the chosen server; do not assume all servers provide media byte ranges.
## State of the Art
| Existing/narrow approach | Phase 1 delivery | Evidence boundary |
|---|---|---|
| Wine still capture with null audio | Continuous identified DxWnd recording on Windows | Existing harness remains Wine evidence. [VERIFIED: tools/recon/reference_capture.py:90-106,159-160] |
| Build identity text | Hashed source/package/resource/session binding | Existing identity fields remain preserved. [VERIFIED: scripts/package.sh:48-52] |
| Chronological reports and bounded coverage rows | Capability-led current applicability with history | Existing legend already distinguishes S/P/M/R. [VERIFIED: docs/checkpoint/coverage.md:63-66] |
No dependency modernization or runtime architecture migration is proposed.
## Assumptions Log
| # | Claim | Section | Risk if wrong |
|---|---|---|---|
| A1 | [ASSUMED] Windows external recording can capture this DxWnd game with usable audio and acceptable timing overhead | Windows workflow | Must be tested in preflight; failed capture keeps acceptance open |
| A2 | [ASSUMED] A browser on each review machine can decode the selected preview format with usable seeking | Viewer | Test actual files/browser; retain raw recording and choose a verified derivative if necessary |
These are execution hypotheses, not locked compatibility claims. Do not gate independent implementation on a vague preference question; resolve through the prescribed preflight/native acceptance checkpoint before claiming success.
## Open Questions — RESOLVED planning dispositions
Each policy below is resolved for planning. Actual future capture/native outcomes remain
execution acceptance dependencies; RESOLVED does not claim a successful Windows run.
1. **RESOLVED — Actual DxWnd version/config and original launch behavior:** collect the user's actual executable/version/profile hashes and settings through plan 01-05 preflight, then record launch, visibility and audibility during plan 01-07's combined session. No guessed profile or compatibility guarantee is required to implement the collector. Failed/missing original execution keeps EVID-02 open.
2. **RESOLVED — Windows capture/audio/browser availability:** use a local dependency checklist and short recording/decode/audio preflight in the prepared combined session (plans 01-05/01-07). Record observed versions/devices and blockers; do not automatically download tools or silently substitute black/silent media. Unavailable dependencies remain explicit pending capture acceptance.
3. **RESOLVED — Original input precision:** use procedural inputs plus manually observed event markers, each labeled with method and uncertainty (plans 01-01/01-05/01-07). Port observations remain separately instrumented. No claim of exact original input sampling or deterministic original replay is made. Further instrumentation requires a concrete comparison need and the existing original-binary evidence rules.
4. **RESOLVED — Timing/image/audio tolerances:** preserve actual-speed raw captures, elapsed values and drift without a blanket numeric parity threshold (plans 01-02/01-07). Record discrepancies/uncertainty; later system owners derive any acceptance tolerances from authoritative evidence. Tool acceptance tests validate timing/audio controls, not unestablished whole-game parity.
5. **RESOLVED — Historical applicability:** bind claims to content/source/platform/scenario identity, preserve explicit supersession and reject ambiguous conflicting current evidence (plans 01-01/01-03/01-07). Report date/order alone never promotes historical packages to current proof. Missing underlying artifacts remain missing/historical rather than receiving fabricated identity.
## Sources
### Primary repository evidence (HIGH)
Directly opened this session: local/parent instructions and full specification; phase context/requirements/state/roadmap/config/project; current progress/compatibility/tasks/decisions; checkpoint next-work, coverage and implementation plan; main-menu player lifetime and Jimmy movement stabilization; REA report; codebase testing/conventions/structure; original manifest; inventory/reference tools; package/test/environment/window scripts; project declaration; Program and native fixtures. Inline citations give exact inspected anchors for implementation claims.
### Official external documentation (MEDIUM)
- https://sourceforge.net/projects/dxwnd/ — official wrapper project identity.
- https://sourceforge.net/p/dxwnd/discussion/general/thread/6e4aa579/ — project-maintainer logging procedure; historical guidance, not a tested current Neutron profile.
- https://obsproject.com/kb/standard-recording-output-guide — offline recording, MKV and remux (dated 2023-05-26).
- https://obsproject.com/kb/display-capture-sources — platform-specific display recording methods (dated 2022-01-11).
- https://html.spec.whatwg.org/multipage/media.html — native media time/rate/mute/playback; living standard checked 2026-11-12.
- https://ffmpeg.org/ffprobe.html — media format/stream inspection.
- https://docs.python.org/3.12/library/http.server.html — local serving and symlink caveat.
- https://asvs.owasp.org/ — current ASVS release identity.
## Metadata
- Standard stack confidence HIGH for existing repository/environment; MEDIUM for external recording workflow pending real-device verification.
- Architecture confidence HIGH for inspected integration boundaries; proposed workflow requires implementation and end-to-end verification.
- Pitfalls confidence HIGH where directly demonstrated in code; MEDIUM for browser/device capture risks.
- Research-plan seam selected websearch for three external questions; classify-confidence returned LOW without verification and MEDIUM with verified official-source cross-check. External claims therefore use CITED tags.
- Research-store persistence was attempted for all three digests but failed with `ENOENT: no such file or directory, mkdir '/home/cristian/.gsd/research-cache'`. No cache write claimed; research sources remain in this document. Do not change global home/config or unrelated repository files to repair a research cache.
- Project graph disabled; no graph relationships used. No project agent skills configured.
- Original verification run this session: `Verified 539 unchanged original files`. This is preservation evidence, not new gameplay execution.
- No native Windows, DxWnd, original gameplay, browser playback or new gameplay compatibility claimed. No commit/push performed by this agent per exclusive assignment.
- Research date 2026-11-12; revisit local evidence applicability whenever runtime/resources change; external recording guidance should be rechecked during Windows preflight.
@@ -0,0 +1,39 @@
---
phase: 01
review: 01-REVIEW.md
titles: json
findings:
- id: CR-01
severity: critical
disposition: fixed
title: "Human review is checked against a different file from the selected receipt"
- id: CR-02
severity: critical
disposition: fixed
title: "Original applicability never binds the executed executable or preservation inventories"
- id: CR-03
severity: critical
disposition: fixed
title: "Fresh-copy continuity accepts a hash that identifies no artifact"
- id: WR-01
severity: warning
disposition: fixed
title: "Checkpoint assembly bypasses the capability ledger projection"
- id: WR-02
severity: warning
disposition: fixed
title: "An interrupted Windows collector cannot be finalized through the documented recovery command"
open: 0
total: 5
recorded: 2026-11-13T21:58:50.502559+00:00
---
# Phase 01: Code Review Disposition
| Finding | Severity | Disposition | Source |
|---|---|---|---|
| CR-01 | critical | fixed | 01-REVIEW-VERIFY.md; independent re-review |
| CR-02 | critical | fixed | 01-REVIEW-VERIFY.md; independent re-review |
| CR-03 | critical | fixed | 01-REVIEW-VERIFY.md; independent re-review |
| WR-01 | warning | fixed | 01-REVIEW-VERIFY.md; independent re-review |
| WR-02 | warning | fixed | 01-REVIEW-VERIFY.md; independent re-review |
@@ -0,0 +1,75 @@
---
phase: 01-reproducible-fidelity-baseline
verified: 2026-11-13T22:19:18Z
review_path: .planning/phases/01-reproducible-fidelity-baseline/01-REVIEW.md
fix_report_path: .planning/phases/01-reproducible-fidelity-baseline/01-FIX-REPORT.md
verified_head: 02d182f35de643f9d68699b2fff1d219dd132edb
findings_verified: 5
fixed: 5
open: 0
findings:
critical: 0
warning: 0
info: 0
total: 0
status: clean
---
# Phase 01 review-fix verification
All five fixes are verified. The final CR-03 refinement requires actual backing artifacts for named copy-state identities and rejects the hash-only records that survived its first fix. No reviewed finding remains open.
| Finding | Disposition | Independent verification |
|---|---|---|
| CR-01 | FIXED | The selected path is retained and its own digest is compared with the human finding. The sibling-digest and absent-digest regressions leave human checks pending; the actual selected-file digest satisfies that boundary. |
| CR-02 | FIXED | Complete baseline records and their recomputed digest bind original pre/post/package/resources. The explicit executed `original_member` binds executable size/header/hash. Wrong executable/member and inconsistent inventories are rejected; independently identified writable `copy_post` changes remain allowed. |
| CR-03 | FIXED | Scenario validation now checks the actual named copy-pre artifact for both lifetimes and the retained snapshot for retained runs. Previous hash-only reproductions and an isolated retained-snapshot reproduction are rejected; valid named state files still qualify. |
| WR-01 | FIXED | Assembly exports the validated ledger projection; readiness compares current/history with the sealed projection. The preparation-to-bundled-renderer check preserves named current/superseded records. The standalone-transfer check needs no source Git checkout, and missing viewer history is rejected. |
| WR-02 | FIXED | A real Linux-hosted PowerShell finalizer reproduction recovered an incomplete-only synthetic run as aborted. Initial raw bytes and session identity survived, end clocks remained absent, captured promotion was rejected, and shared validation plus atomic import succeeded with acceptance false. |
## CR-03 refinement verified
**Original classification:** BLOCKER
**Current disposition:** FIXED by `02d182f35de643f9d68699b2fff1d219dd132edb`, with regression `48fca0d`.
**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_receipts.py:667-678`
**Related:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_receipts.py:383-385`
At `a821754`, `_scenario_observation()` compared continuity digests with named identity strings while the generic validator skipped dictionaries without `path`. The refinement now passes the receipt root to scenario validation and calls `_checked_artifact()` on the actual named state records before comparing digests. The scenario audit and Linux capture matrix both pass their artifact root; their direct test callers were updated as well.
The bounded reproduction below uses existing synthetic metadata fixtures and launches no game. It previously demonstrated the gap and now demonstrates rejection for both native lifetimes:
```python
from test_fidelity_scenarios import FidelityScenarios
import fidelity_receipts as receipts
fixture = FidelityScenarios()
fixture.setUp()
try:
for lifetime in ('fresh', 'retained'):
value, root = fixture.receipt(
lifetime + '-natural-ordinary', 'dialogue-return')
value['identity']['copy_pre'] = {'sha256': 'f' * 64}
value['continuity']['copy_pre_sha256'] = 'f' * 64
if lifetime == 'retained':
value['identity']['retained_copy'] = {'sha256': 'e' * 64}
value['continuity']['retained_copy_sha256'] = 'e' * 64
result = receipts.audit_scenarios(
fixture.protocol(), [(value, root)])
print(lifetime, result['accepted'], result['invalid'])
finally:
fixture.doCleanups()
```
Run from the repository with `PYTHONPATH=tests:tools/recon`. Earlier output at `a821754` was `fresh 1 []` and `retained 1 []`. Rerunning at `02d182f` gives zero accepted slots and `Reference must be a bounded relative POSIX path` in each invalid list. A third reproduction retaining valid copy-pre but supplying only a hash for `identity.retained_copy` is rejected independently. The unmodified fresh and retained metadata controls each still accept one slot.
**Additional verification:** Four selected scenario tests passed in **0.424 seconds**: backing-file rejection for both lifetimes, named continuity binding, unrelated retained-snapshot rejection, and complete positive coverage of all 120 metadata slots. The new backing-file test covers hash-only, missing-file and wrong-size state identities, including the retained snapshot. This closes the reported artifact-binding gap without changing the four other verified fixes.
## Verification evidence and limits
Read the historical review, fix report and actual source/test diffs for `5569bc2`, `bda35e5`, `6e5ee0b`, `548c97a`, `2608517`, and `a821754`, then the final `48fca0d` regression and `02d182f` refinement. Initially ran 11 selected Python tests in **2.109 seconds**, all passing: selected-file review binding; original executable/member and inventory rejection; mutable generated-copy allowance; complete positive metadata matrix; standalone readiness without Git; malformed viewer history; actual assembled model through its bundled renderer; named pre/retained continuity; and aborted missing-end-clock import. The additional hash-only identity gap discovered during that verification is closed by the independently repeated checks above.
Separately exercised the actual PowerShell recovery function with a disposable synthetic prepared checkpoint, rejected captured promotion, recovered raw media, compared both raw initial copies byte-for-byte, verified absent end clocks, validated and imported the resulting open aborted receipt. This was Linux-hosted tooling execution, not native Windows evidence.
No full suite, whole 11,001-file checkpoint readiness/hash walk, original execution or gameplay capture was repeated. The primary's current bundle identities and pending 0/120 human acceptance remain separate evidence; this verification does not promote them. Source and tests were read-only, no commit was made, and unrelated concurrent report edits were preserved.
Historical `01-REVIEW.md` is unchanged; its SHA-256 is `493c0b9b7b491f7dcc896d6cfda675ced837f56ee32daf2bbf1cd98f1527f74c`.
@@ -0,0 +1,137 @@
---
phase: 01-reproducible-fidelity-baseline
reviewed: 2026-11-13T21:56:48Z
depth: standard
files_reviewed: 44
files_reviewed_list:
- .codex/hooks.json
- docs/codex-quota-guard.md
- docs/compatibility.md
- docs/decisions.md
- docs/evidence/README.md
- docs/evidence/capabilities.json
- docs/evidence/checkpoint-session.md
- docs/evidence/linux-session.md
- docs/evidence/phase01-baseline.md
- docs/evidence/scenarios.json
- docs/evidence/windows-session.md
- docs/progress.md
- docs/tasks.md
- scripts/collect-fidelity-linux.sh
- scripts/collect-fidelity-windows.cmd
- scripts/collect-fidelity-windows.ps1
- scripts/prepare-fidelity-checkpoint.sh
- scripts/test.sh
- src/GamePort/Application/FidelityObservation.cs
- src/GamePort/Program.cs
- tests/GamePort.FidelityObservationTests/GamePort.FidelityObservationTests.csproj
- tests/GamePort.FidelityObservationTests/Program.cs
- tests/fidelity-viewer.test.mjs
- tests/fidelity-windows.Tests.ps1
- tests/test_codex_quota_guard.py
- tests/test_fidelity_acceptance.py
- tests/test_fidelity_capture.py
- tests/test_fidelity_checkpoint.py
- tests/test_fidelity_ledger.py
- tests/test_fidelity_observation.py
- tests/test_fidelity_review.py
- tests/test_fidelity_scenarios.py
- tests/test_fidelity_sessions.py
- tools/recon/fidelity.py
- tools/recon/fidelity_acceptance.py
- tools/recon/fidelity_capture.py
- tools/recon/fidelity_checkpoint.py
- tools/recon/fidelity_ledger.py
- tools/recon/fidelity_receipts.py
- tools/recon/fidelity_review.py
- tools/recon/fidelity_viewer/index.html
- tools/recon/fidelity_viewer/style.css
- tools/recon/fidelity_viewer/viewer.mjs
- tools/workflow/codex_quota_guard.py
findings:
critical: 3
warning: 2
info: 0
total: 5
necessity: 0
status: issues_found
---
# Phase 01: Code Review Report
**Reviewed:** 2026-11-13T21:56:48Z
**Depth:** standard
**Files Reviewed:** 44
**Status:** issues_found
## Summary
Three acceptance-integrity defects permit mismatched reviewed bytes, unrelated original executable bytes, or an unbound fresh-copy identity to contribute accepted obligations. The prepared capability viewer also omits current/history evidence, and the Windows finalizer cannot recover the interrupted-run state described by its instructions.
Scope is the canonical `/tmp/gameport-phase01-review-scope.json` file union at HEAD `215d01e43e103f3fbb7e26b43607cd09f2856492`. Resolver status is **degraded**, reason `no-task-commit-rows`, using its real phase range from `9aa49970e43bc9ca5470b884757e3481e0c0293a`. The union contains 44 files; all seven SUMMARY key-file lists are covered, and none of these paths is ignored. No structural pre-pass or external reviewer evidence was supplied. The necessity rubric was read; no necessity finding was established.
The pending 0/120 original/native obligations and ten human findings are expected acceptance dependencies, not implementation defects. Findings below concern enforceable identity/continuation contracts. Reproductions used disposable synthetic metadata only; the Windows recovery reproduction used Linux-hosted PowerShell, not native Windows. The existing complete-suite run was not repeated. No original was executed or modified, no source was edited, and no commit was made; unrelated `tools.yaml` was preserved.
## Narrative Findings (AI reviewer)
## Critical Issues
### CR-01: Human review is checked against a different file from the selected receipt
**Classification:** BLOCKER
**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_acceptance.py:134-143`
**Issue:** `current.json` may select any contained receipt filename. The loop reads that path, discards it, then compares the human-review digest against `directory / 'receipt.json'`. A sibling `selected.json` can therefore supply the accepted record while the human finding binds unrelated `receipt.json` bytes. Raw result directories need not have an import sidecar, so `read_receipt` does not close this gap. This defeats the explicit receipt-byte review boundary; the same mismatch can affect every selected slot.
**Evidence:** A bounded synthetic reproduction selected `run/selected.json`, stored a different object at `run/receipt.json`, and supplied the latter's digest in `human-review.json`. The real `audit()` returned `matrix.accepted == 1`, `human_needed == []`, and `errors == []`, despite the selected digest differing from the reviewed digest. Only material readiness was mocked to isolate receipt selection; hash checking, parsing and matrix evaluation ran normally.
**Fix:** Carry the actual selected path/digest alongside each record and compare `receipt_sha256[receipt_id]` with that file. Alternatively, explicitly reject every selected basename other than `receipt.json` before reading it. Missing or different selected-file digests must invalidate the human finding. Add a regression with two different sibling JSON files and no sidecar.
### CR-02: Original applicability never binds the executed executable or preservation inventories
**Classification:** BLOCKER
**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_acceptance.py:81-84`
**Issue:** The original-DxWnd branch checks only a `tree_sha256` string inside the receipt's `original_pre` JSON. It does not compare the actual identified executable against its selected pristine inventory member, validate original package/resource identities against that baseline, or check `original_post`. The generic validator checks each referenced file's own hash, which establishes identity but not applicability. Consequently, attaching a correct original-pre inventory to an unrelated executable is sufficient to pass `_bind`. This is weaker than the concrete executable/pre/post mapping promised in `docs/evidence/checkpoint-session.md:90-94`.
**Evidence:** Starting with the existing complete metadata fixture for an original-DxWnd slot, a synthetic diagnostic replaced only `identity.executable` with the actual size/hash of a new file containing `synthetic wrong original executable`. The expected original-pre record stayed unchanged. `audit_records()` still returned one accepted obligation and no errors. The receipt schema otherwise remained valid; no false artifact hash was required.
**Fix:** Pass the checkpoint's actual pristine file inventory into original binding, retain the exact selected original member path, and compare the receipt executable identity with that member. Validate package/resources and authoritative pre/post inventories against the same baseline; recompute inventory digests from their file records rather than trusting an embedded digest alone. Writable-copy changes must stay separately recorded. Add negative tests for a wrong executable and inconsistent pre/post inventory content.
### CR-03: Fresh-copy continuity accepts a hash that identifies no artifact
**Classification:** BLOCKER
**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_receipts.py:659-669`
**Issue:** All cells require `copy_pre_sha256`, but fresh cells only check its 64-hex syntax. Actual identity membership is checked inside the retained-only branch. Thus a fresh observation can claim a nonexistent copy state and still fill an accepted slot, contrary to the fresh lifetime procedure's separately identified generated execution copy. The executable/package binding does not identify that per-run startup state.
**Evidence:** With `FidelityScenarios.receipt('fresh-natural-ordinary', 'dialogue-return', 'native_port', 'linux')`, replacing `continuity.copy_pre_sha256` with `'f' * 64` produces `audit_scenarios(...).accepted == 1` and `invalid == []`. No identity file has that digest. This reproduction is a synthetic metadata diagnostic, not gameplay evidence.
**Fix:** Require `copy_pre_sha256` to match the validated, explicitly named `identity.copy_pre` record for both lifetimes before branching. Bind retained-copy state to its explicitly named retained snapshot as well, rather than any unrelated identity hash. Add fresh-copy negative tests for an unknown digest and a digest belonging to the launcher/package instead of the per-run copy record.
## Warnings
### WR-01: Checkpoint assembly bypasses the capability ledger projection
**Classification:** WARNING
**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_checkpoint.py:165-167`
**Related:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_viewer/viewer.mjs:228-244`
**Issue:** Assembly passes authoritative `capabilities.json` directly to `export_review()`. That export validates/copies source links but does not call `export_ledger()`, so its rows retain `evidence` without derived `current` and `history`. The browser renders only `row.current` and `row.history`, displaying `Unrecorded` in both sections and concealing the revision/classification details prepared for the reviewer. The separate CLI ledger-to-viewer test exercises the correct projection, but checkpoint assembly does not use that route.
**Evidence:** In the actual sealed `dist/fidelity/phase01/review/review.json`, all 25 capability rows lack both fields. Applying `export_ledger()` to the authoritative input yields two current and two historical records for `startup-order`; none appears in those viewer sections in the prepared model. This is independent of missing original/native recordings.
**Fix:** Generate the validated ledger projection before checkpoint review export, then preserve its current/history fields through source-link copying. Make `ready()` reject a malformed viewer ledger rather than checking only source hrefs. Add a preparation-to-renderer regression asserting that named current and superseded records survive the actual checkpoint assembly path.
### WR-02: An interrupted Windows collector cannot be finalized through the documented recovery command
**Classification:** WARNING
**File:** `/home/cristian/codex/Neutron/GamePort/scripts/collect-fidelity-windows.ps1:332-336`
**Related:** `/home/cristian/codex/Neutron/GamePort/docs/evidence/windows-session.md:150-152`
**Issue:** Startup writes `incomplete.json` before launching, while `run.json` is written only in the final `finally` block. If the collector is terminated before that block completes, its durable result has only the incomplete record. The instructions explicitly tell the tester to recover that state with `Finish -Outcome aborted`, but `Complete-FidelityRun` unconditionally reads missing `run.json` first. The supplied recovery command therefore cannot retain the interrupted launch's media as a terminal receipt; asking for a fresh launch would misidentify its lifetime.
**Evidence:** A disposable synthetic prepared bundle with `results/interrupted/incomplete.json` and no `run.json` was passed to the real finalizer through Linux-hosted PowerShell. It failed immediately with `Cannot find path '.../results/interrupted/run.json' because it does not exist.` The failed lookup precedes annotation/media recovery. Existing terminal tests always create `run.json` and do not cover this durable interrupted state.
**Fix:** Add an explicit aborted-recovery path using the retained initial record when `run.json` is absent. Preserve its launch identity and raw bytes, prohibit captured/reviewed promotion, and leave unavailable end clocks/observations explicitly missing. Recover media into a new write-once diagnostic receipt without inventing elapsed times. Test an incomplete-only result folder and verify that it remains open and structurally importable.
---
_Reviewed: 2026-11-13T21:56:48Z_
_Reviewer: gsd-code-reviewer_
_Depth: standard_
@@ -0,0 +1,60 @@
---
phase: "01"
slug: reproducible-fidelity-baseline
status: verified
threats_open: 0
threats_total: 22
threats_closed: 22
asvs_level: 1
block_on: high
register_authored_at_plan_time: true
verified_head: 02d182f35de643f9d68699b2fff1d219dd132edb
created: "2026-11-13T22:21:09.119266+00:00"
---
# Phase 01 — Security
The typed security auditor verified all planned mitigation boundaries. The repeated reserved T-01-SC is counted once. All dispositions are mitigate; no accepted or transferred risks.
## Trust Boundaries
Originals → generated copies; local paths → file/process operations; media/receipts → review and acceptance; observer → gameplay; transferred checkpoint → immutable validation.
## Threat Register
| Threat ID | Category | Severity | Disposition | Mitigation evidence | Status |
|---|---|---|---|---|---|
| T-01-01 | Tampering | high | mitigate | fidelity_receipts.py:123,221,239,257 | closed |
| T-01-02 | Spoofing | high | mitigate | fidelity_receipts.py:275,667,672,714 | closed |
| T-01-03 | Tampering | high | mitigate | fidelity_receipts.py:198,212,482,500 | closed |
| T-01-04 | Information disclosure | high | mitigate | fidelity_review.py:202,211,219,274 | closed |
| T-01-05 | Tampering | high | mitigate | viewer.mjs:2,190; fidelity_review.py:238 | closed |
| T-01-06 | Spoofing | medium | mitigate | viewer.mjs:43,79,302,318,324 | closed |
| T-01-07 | Spoofing | high | mitigate | fidelity_ledger.py:97,197,203,285 | closed |
| T-01-08 | Repudiation | medium | mitigate | fidelity_ledger.py:69,220,299,320 | closed |
| T-01-09 | Tampering | medium | mitigate | fidelity_ledger.py:117,339,372 | closed |
| T-01-10 | Tampering | high | mitigate | FidelityObservation.cs:54,78,93,109; test_fidelity_observation.py:130 | closed |
| T-01-11 | Denial of service | medium | mitigate | FidelityObservation.cs:165,171,179,192,233 | closed |
| T-01-12 | Spoofing | high | mitigate | FidelityObservation.cs:47,109,130,166; Program.cs:18,1328 | closed |
| T-01-13 | Elevation of privilege | high | mitigate | collect-fidelity-windows.ps1:128,136,144,253,303 | closed |
| T-01-14 | Tampering | high | mitigate | fidelity_checkpoint.py:103,120,198,215,220 | closed |
| T-01-15 | Spoofing | high | mitigate | collect-fidelity-windows.ps1:176,208,234,285,332 | closed |
| T-01-16 | Tampering | high | mitigate | fidelity_capture.py:154,156,195,239,347 | closed |
| T-01-17 | Spoofing | high | mitigate | fidelity_capture.py:85,98,107,325,338 | closed |
| T-01-18 | Denial of service | medium | mitigate | fidelity_capture.py:30,128,148,202,220,224 | closed |
| T-01-19 | Spoofing | high | mitigate | fidelity_acceptance.py:124; fidelity_receipts.py:275,667,672,714; fidelity_capture.py:390 | closed |
| T-01-20 | Tampering | high | mitigate | fidelity_receipts.py:453,482,488,494,500 | closed |
| T-01-21 | Repudiation | medium | mitigate | fidelity_acceptance.py:127,130,160,184; fidelity_ledger.py:328 | closed |
| T-01-SC | Tampering | high | mitigate | fidelity_checkpoint.py:301; collect-fidelity-windows.ps1:253; observer csproj:1 | closed |
## Accepted Risks Log
No accepted risks.
## Security Audit Trail
Initial source audit identified 20/22 closed and T-01-02/T-01-19 open because hash-only copy identities bypassed file checks. Regression48fca0d reproduced it; fix02d182f validates actual named artifacts at the scenario boundary. Independent auditor reinspection closes both. Code re-review confirms all five findings fixed; see01-REVIEW-VERIFY.md. All191 affected fidelity regressions pass in43.355s.
## Sign-Off
All22 planned threats have implemented, verified mitigations; threats_open=0. This tooling verdict does not approve original/native gameplay, physical input, audio or human findings; runtime acceptance remains0/120 OPEN.
@@ -0,0 +1,88 @@
# Phase 01 source audit
Planned 2026-11-12. COVERED means executable tasks exist, not that original/native acceptance has passed. All four source types are audited; no required source item is dropped. Existing instructions, current original inventory and all D-01–D-16 remain binding.
| Source | ID | Required outcome | Plans | Status |
|---|---|---|---|---|
| GOAL | G1 | Reproduce identified original/port scenarios and exact native proof | 01–07 | COVERED |
| GOAL | SC1 | Original inventory and isolated generated execution | 01,05–07 | COVERED |
| GOAL | SC2 | Actual original visual/audio/input/event reference, or open access | 01,02,05,07 | COVERED |
| GOAL | SC3 | Full-game evidence→implementation→platform→discrepancy→acceptance | 03,07 | COVERED |
| GOAL | SC4 | Same native Linux/Windows baseline with exact identity | 04–07 | COVERED |
| REQ | EVID-01 | Every original unchanged; generated output separate | 01,05–07 | COVERED |
| REQ | EVID-02 | Reproducible actual original reference and open limitations | 01,02,04,05,07 | COVERED |
| REQ | EVID-03 | Maintained full-game capability coverage ledger | 02,03,07 | COVERED |
| REQ | EVID-04 | Current native Linux/Windows baseline, separately classified | 01,02,04–07 | COVERED |
| CONTEXT | D-01 | Continuous route plus focused moments | 01,04,06,07 | COVERED |
| CONTEXT | D-02 | Equal natural/skipped runs | 01,04,06,07 | COVERED |
| CONTEXT | D-03 | Equal fresh/retained runs and correct lifetimes | 01,04,06,07 | COVERED |
| CONTEXT | D-04 | Ordinary and edge input/bank/landing/idle | 01,04,06,07 | COVERED |
| CONTEXT | D-05 | Paired playback and corresponding artifacts | 02,07 | COVERED |
| CONTEXT | D-06 | Unobstructed captures; optional overlays | 02,07 | COVERED |
| CONTEXT | D-07 | Event alignment at actual speed; exposed drift | 02,07 | COVERED |
| CONTEXT | D-08 | Exclusive corresponding audio; visible review gain | 02,07 | COVERED |
| CONTEXT | D-09 | Capability navigation with requirement/source/receipt links | 03,07 | COVERED |
| CONTEXT | D-10 | Works/verified/differences/acceptance lead each capability | 03,07 | COVERED |
| CONTEXT | D-11 | Current applicability first, exact superseded history | 03,07 | COVERED |
| CONTEXT | D-12 | Player-impact order without closing missing evidence | 03,07 | COVERED |
| CONTEXT | D-13 | User Windows availability, actual execution pending | 01,05,07 | COVERED |
| CONTEXT | D-14 | One identified local bundle/collector per checkpoint | 05,07 | COVERED |
| CONTEXT | D-15 | Generated original through identified DxWnd | 01,05,07 | COVERED |
| CONTEXT | D-16 | All materials before one combined human session | 05–07 | COVERED |
| RESEARCH | R1 | Stdlib tools, no dependency modernization/install | All | COVERED |
| RESEARCH | R2 | Stage/copy/source identity, fresh allocation, atomic failure | 01,05 | COVERED |
| RESEARCH | R3 | Actual source/package/executable/resource/media hashes | 01,05–07 | COVERED |
| RESEARCH | R4 | Typed evidence, failed/incomplete/missing remains open | 01,03,05–07 | COVERED |
| RESEARCH | R5 | Eight explicit matrix cells, continuous and focused obligations | 01,04–07 | COVERED |
| RESEARCH | R6 | Passive accepted-input/control/scene observation across continuations | 04 | COVERED |
| RESEARCH | R7 | External original recording; manual observed markers/uncertainty | 05,07 | COVERED |
| RESEARCH | R8 | Raw MKV/verified preview, derivation/time/crop metadata | 02,05–07 | COVERED |
| RESEARCH | R9 | Paired clocks/drift, seeking/range, exclusive audio/error/tail states | 02,07 | COVERED |
| RESEARCH | R10 | Full 33-requirement ledger and checkpoint-row reconciliation | 03 | COVERED |
| RESEARCH | R11 | Content/scope/platform current applicability and explicit history | 03,07 | COVERED |
| RESEARCH | R12 | Actual dependency/version/profile/media preflight and local transfer | 05,07 | COVERED |
| RESEARCH | R13 | Real native Linux/Windows/physical audio/input and actual original | 05–07 | COVERED; execution remains a dependency |
| RESEARCH | R14 | Bounded input, path/symlink safety, no receipt commands, safe viewer | All relevant tools | COVERED |
| RESEARCH | R15 | Meaningful negative tests, nonempty discovery, no fake native pass | All | COVERED |
| RESEARCH | R16 | Preserve movement/body/TSK/bank/admission; no source investigation needed | 01,04,06,07 | COVERED |
| RESEARCH | R17 | Actual browser/codec and original capture hypotheses A1/A2 | 02,05,07 | COVERED with human backstops |
| RESEARCH | R18 | Local full suite, original verification and durable status before transition | 07 | COVERED |
No deferred ideas were supplied. Later-phase gameplay expansion is excluded by phase ownership, not omitted from this phase's required evidence ledger. The RESEARCH initial-real-pair recommendation is satisfied by eventual actual pairing in 07; its synthetic plumbing allowance enables earlier 01/02 without claiming parity or blocking preparation.
## Spec-less edge report: no silent drop
Source: actual deterministic /tmp/gameport-edge-coverage.json, 9 rows. Seven classified rows receive explicit criteria in must_haves.truths; both unclassified rows remain unresolved flagged assumptions in 01-07. No auto-dismissal. 9 surfaced = 7 explicit authored + 2 flagged unresolved.
| Requirement | Category | Disposition / exact boundary | Plan/task |
|---|---|---|---|
| EVID-01 | adjacency | Reject equal/nested/aliased source/output; allow distinct sibling prefixes | 01-01-01 |
| EVID-01 | empty | Empty/missing inventory invalid; one-file round-trip valid | 01-01-01 |
| EVID-01 | ordering | Canonical relative path order; reject normalized identity collisions | 01-01-01 |
| EVID-01 | concurrency | Exclusive allocation, atomic publish, interrupted incomplete, duplicate import rules | 01-01-01 |
| EVID-02 | unclassified | Unresolved flagged assumption; manual original/DxWnd capture review | 01-07-02 |
| EVID-03 | adjacency | Identical duplicate receipt idempotent, conflicting bytes/history rejected | 01-03-01 |
| EVID-03 | empty | Empty ledger invalid; single capability renderable | 01-03-01 |
| EVID-03 | ordering | Stable ID tie-breaks; explicit supersession, conflict/cycle checks | 01-03-01/02 |
| EVID-04 | unclassified | Unresolved flagged assumption; actual native route/input/audio review | 01-07-02 |
Research A1/A2 backstop truths are separate from the two unclassified rows: backstops abstain to human_needed if unconfirmed and do not auto-resolve those rows.
## Prohibition recall and precision
Stage 1 adversarial recall considered ten candidates per requirement:
| Requirement | Raw candidates |
|---|---|
| EVID-01 | Original mutation, original in-place execution, changed baseline regeneration, empty tree, symlink escape, alias overlap, hash mismatch, partial copy, concurrent allocation, accidental original write |
| EVID-02 | Synthetic parity, hidden retiming, mixed audio, wrapper as historical parity, black capture, silent capture, missing input, fake markers, swallowed abort, unsafe receipt command |
| EVID-03 | Erased history, hidden unimplemented content, missing-proof completion, newest-date selection, duplicate conflict, empty ledger, lost requirements, impact ordering, dead links, injected labels |
| EVID-04 | Wine as native, cross-publish as native, fixture as gameplay, absent Windows proof, fabricated audible pass, available PC as success, wrong package, stale resources, lost lifetime, zero tests |
Stage 2 drops ordinary correctness/hygiene into edge tests and implementation review. Canon path traversal/injection/access control are referred to per-plan STRIDE/ASVS and secure-phase review, not minted as product prohibitions. Three merged bespoke project values survive: P1 authoritative preservation; P2 honest unretimed/unmixed/non-synthetic comparison; P3 historical/full-scope/native proof transparency. P1 maps EVID-01 to 01-01; P2 maps EVID-02 to 01-02; P3 maps EVID-03/EVID-04 to 01-03. They were projected through the installed probe-core.cjs projectProhibitions serializer and authored descriptor-less with status unresolved. No check_* descriptor or must-NOT truth was fabricated. They remain flagged-unverified for final judgment. 3 kept = 3 must_haves.prohibitions; 0 silently dropped.
## Planning evidence and limits
Discovery level 1 is satisfied by current research/official documentation and inspected repository analogs; no new integration/dependency selection is introduced. Existing source paths were grounded with git ls-files. New artifacts are explicitly listed per plan. No prior verify commands/summaries exist; no new implementation/tests/fixtures ran during planning. UI gate supplied frontend=false/block=false; local paired viewer remains fully in scope. Assumption-delta supplied detected=false. Graph is disabled. API capability detector can false-trigger on local viewer/media terminology; COVERAGE.md records the reasoned no-external-integration declaration.
All seven plans have 2–3 tasks and first-task tracers, five execution waves, zero same-wave file overlap and unique T-01-01 through T-01-21 threats plus reserved T-01-SC. Security uses ASVS1 with high blocking. Full-suite durations remain to be measured; quick checks target under 30 seconds. Human verification is a single end-of-phase session, with strict actual acceptance dependencies preserved.
@@ -0,0 +1,74 @@
---
status: testing
phase: 01-reproducible-fidelity-baseline
source: [01-VERIFICATION.md]
started: 2026-11-14T21:56:41.166382+00:00
updated: 2026-11-14T21:56:41.166382+00:00
---
## Current Test
number: 1
name: A1 — Capture and observe the isolated original through the selected DxWnd setup
expected: |
Complete 40 original-Windows-DxWnd obligations; observe moving game imagery and intelligible game audio, retaining actual executable/profile/copy inventories and wrapper/configuration limitations.
awaiting: user response
## Tests
### 1. A1 — Capture and observe the isolated original through the selected DxWnd setup
expected: Complete 40 original-Windows-DxWnd obligations; observe moving game imagery and intelligible game audio, retaining actual executable/profile/copy inventories and wrapper/configuration limitations.
result: [pending]
### 2. A2 — Exercise actual paired recordings in the identified browser
expected: Both real recordings decode, play at actual speed, seek to their own observed events, preserve full tails and switch exclusive audio without concealing elapsed time.
result: [pending]
### 3. EVID-02-unclassified — Review original capture boundaries and limitations
expected: Document observed original/DxWnd launch, crop, aspect, timing, recording boundaries and retained/fresh lifetimes for the actual reference captures.
result: [pending]
### 4. EVID-04-unclassified — Collect and inspect both native platform routes
expected: Complete 40 native Windows and 40 native Linux obligations with actual OS/GPU/driver/Vulkan/SDL/source/package/resource identity and observed route/input/audio continuity.
result: [pending]
### 5. P1 — Resolve the original-preservation prohibition explicitly
expected: Confirm authoritative originals were never executed or changed; compare all 539 recorded hashes and generated-copy pre/retained/post inventories after the session.
result: [pending]
### 6. P2 — Resolve the honest-comparison prohibition explicitly
expected: Confirm genuine original media, no retiming or concealed drift, no mixed simultaneous soundtracks, and visible review gain/derivation provenance.
result: [pending]
### 7. P3 — Resolve the history/full-scope/native-transparency prohibition explicitly
expected: Confirm all 33 requirements and unimplemented content stay visible; conflicting/superseded evidence and native/Wine/component/cross-publish distinctions are preserved after reconciliation.
result: [pending]
### 8. browser — Review the complete local comparison interface
expected: With real captures, verify readable independent clocks/drift, keyboard controls, raw unobstructed default views, optional annotations/differences and visible loading/error/tail states.
result: [pending]
### 9. paired_review — Compare all corresponding actual recordings and record discrepancies
expected: Review matched events, imagery and sound across the required cases, retaining raw drift and justified system-specific observations without invented tolerances.
result: [pending]
### 10. physical_input — Exercise visible native gameplay and actual audible devices
expected: On Linux and Windows use physical supported inputs through lab → VR04 → lab → outside, natural/skipped and fresh/retained cases, held input, banked jumps, landing and idle; confirm real display/audio output.
result: [pending]
## Summary
total: 10
passed: 0
issues: 0
pending: 10
skipped: 0
blocked: 0
## Gaps
No implementation issues reported in this UAT session. All ten actual human checks remain pending; 0/120 capture obligations are accepted. Follow docs/evidence/checkpoint-session.md as one combined session. Prepared materials and prior tests do not supply human approval.
## Session Notes
Restart requested by the user. Readiness then failed on generated tools/recon/__pycache__/fidelity_checkpoint.cpython-312.pyc before any human capture test. Fixed by2fe8b40; real bundled readiness succeeds twice with no bytecode writes. This automated preflight repair does not pass A1 or any other human check.
@@ -0,0 +1,110 @@
---
phase: "01"
slug: "reproducible-fidelity-baseline"
status: validated
nyquist_compliant: true
wave_0_complete: true
created: "2026-11-12"
---
# Phase 01 — Validation Strategy
## Test Infrastructure
| Property | Value |
|---|---|
| Framework | Existing Python stdlib unittest, standalone .NET 10 console projects; Node built-in tests for pure viewer logic |
| Config file | Existing scripts/test.sh and scripts/env.sh; no new package dependencies |
| Quick run command | `python3 -m unittest discover -s tests -p 'test_fidelity_*.py' -v` |
| Viewer quick command | `node --test tests/fidelity-viewer.test.mjs` |
| Full suite command | `scripts/test.sh` (includes counted Python, Node viewer and managed observer checks) |
| Runtime | Broad fidelity run: 40.072 seconds (30-second target exceeded); focused tooling checks typically 1–5 seconds, process/observer checks can take longer. Complete local suite: 782.049626 seconds. |
## Sampling Rate
- After every task: run its focused tests; require a positive test count, not empty discovery.
- After each plan: run all fidelity tests and relevant existing managed/runtime regressions when their boundaries changed.
- After each wave and before verify-work: run scripts/test.sh and all newly introduced viewer checks.
- Every runnable automated command has an adjacent fails_when predicate in PLAN.md.
- Synthetic media and receipt fixtures validate tooling only. Actual Windows/DxWnd and native gameplay receipts require identified execution.
## Per-Task Verification Map
Final task bindings below reference the exact executable `<automated>` blocks in the named PLAN.md/task. Each block carries its adjacent observable `<fails_when>`; Python commands assert the minimum discovered count before running. The tests exist and have run with positive counts. The status column separates passing automation from actual capture/review still OPEN. Shared EVID requirement acceptance is not implied by any green tooling row.
| Task | Wave | Exact automated command binding | Minimum count / threat refs | Actual result |
|---|---|---|---|---|
| 01-01-01 | 1 | 01-01-PLAN.md task 01-01-01: counted `test_fidelity_sessions.py` runner and mandated original inventory invocation | 16; T-01-01/02/03 | green: 29 session tests; 539 originals |
| 01-01-02 | 1 | 01-01-PLAN.md task 01-01-02: counted `test_fidelity_scenarios.py` runner | 12; T-01-02 | green: 25 scenario tests |
| 01-02-01 | 2 | 01-02-PLAN.md task 01-02-01: counted `test_fidelity_review.py` runner; `node --test tests/fidelity-viewer.test.mjs` | Python 10, Node positive; T-01-04/05/06 | green: 21 review + 27 Node tests |
| 01-02-02 | 2 | 01-02-PLAN.md task 01-02-02: `node --test tests/fidelity-viewer.test.mjs` | 16; T-01-04/05/06 | green: 27 Node tests |
| 01-03-01 | 2 | 01-03-PLAN.md task 01-03-01: counted `test_fidelity_ledger.py` runner | 12; T-01-07/08/09 | green: 31 ledger tests |
| 01-03-02 | 2 | 01-03-PLAN.md task 01-03-02: counted ledger runner; `python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md` | 16 tests, 33 requirements; T-01-07/08/09 | green: 31 tests; 33 requirement mappings validated |
| 01-04-01 | 2 | 01-04-PLAN.md task 01-04-01: exact sourced-SDK observer command and counted `test_fidelity_observation.py` runner | Managed 8, Python 4; T-01-10/11/12 | green: 23 managed + 7 process tests |
| 01-04-02 | 2 | 01-04-PLAN.md task 01-04-02: sourced-SDK observer/build and MovementTests/DirectorTests/CheckpointTests/BodyOwnershipTests commands | Managed 14 plus positive existing groups; T-01-10/11/12 | green: observer/build and protected groups 28/23/4/3 |
| 01-05-01 | 3 | 01-05-PLAN.md task 01-05-01: counted `test_fidelity_checkpoint.py` runner; `bash -n scripts/prepare-fidelity-checkpoint.sh` | 12; T-01-13/14/15 | green: 25 checkpoint tests; shell syntax |
| 01-05-02 | 3 | 01-05-PLAN.md task 01-05-02: counted checkpoint runner; package-free PowerShell command deferred to final human session | Python 16, Windows 8; T-01-13/14/15 | green: 25 Python + 18 Linux-hosted PowerShell checks; native Windows session OPEN |
| 01-06-01 | 4 | 01-06-PLAN.md task 01-06-01: counted `test_fidelity_capture.py` runner | 10; T-01-16/17/18 | green: 23 capture tests; actual Linux capture OPEN |
| 01-06-02 | 4 | 01-06-PLAN.md task 01-06-02: counted capture runner and original inventory command | 14; T-01-16/17/18 | green: 23 capture tests; 539 originals; actual matrix OPEN |
| 01-07-01 | 5 | 01-07-PLAN.md task 01-07-01: counted `test_fidelity_acceptance.py` runner; `python3 tools/recon/fidelity_acceptance.py ready --checkpoint dist/fidelity/phase01` | 14; T-01-19/20/21 | green: 29 acceptance tests; readiness exit 0 |
| 01-07-02 | 5 | `python3 tools/recon/fidelity_acceptance.py audit --checkpoint dist/fidelity/phase01 --results dist/fidelity/phase01/results --require-complete` | Real matrix/native/original/human checks required; T-01-19/20/21 | OPEN: strict audit exit 1, errors=[], 0/120; fail-closed behavior covered by passing acceptance tests |
| 01-07-03 | 5 | `scripts/test.sh`; `python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json` | Positive consolidated counts, 539 originals; all threats | green: completed full suite exit 0; 539 originals |
All 15 task bindings were checked against the seven PLAN verify blocks and SUMMARY interfaces. No missing automated contract was found. Task 01-07-02 remains an explicit actual-evidence dependency; its expected nonzero strict audit is not a green acceptance result. Focused commands ran during their owning slices; the completed integrated suite and subsequent tooling regressions are recorded below. No full suite or large checkpoint hash walk was repeated for this audit.
The seven explicit classified spec-less boundaries and two unresolved unclassified manual assumptions are reconciled in 01-SOURCE-AUDIT.md. The two research backstop truths abstain to human_needed if actual original audiovisual capture/browser review is insufficient. Descriptor-less project prohibitions remain flagged-unverified, not silently passed. ASVS1 high/critical threats block acceptance; T-01-SC is reserved across plans.
## Wave 0 Requirements — Complete (Automation)
- Each implementation slice creates meaningful tests together with its production code; no empty stubs counted as validation.
- Implemented fidelity test fixtures covering changed/missing/added originals, output overlap, symlink/drive/case escape, reused session, tampered hash, invalid marker and unsupported schema.
- Implemented pure viewer tests including asymmetric durations, missing/buffering tracks, preserved playbackRate 1.0 and exclusive audio switching.
- No external test-framework installation required. Existing full suite remains available.
## Manual-Only Verifications
| Behavior | Requirement | Why Manual | Test Instructions |
|---|---|---|---|
| Original visible and audible through DxWnd | EVID-02 | User Windows PC and wrapper/media behavior | Use generated verified copy; record Windows/DxWnd/recorder versions and settings; execute the defined matrix and import hashed recordings/annotations |
| Native Windows port route/input/audio | EVID-04 | Cannot be replaced by Linux cross-publish or Wine | Run local checkpoint bundle on user PC; capture actual route and physical input/audio; collect exact package/resource identities and logs |
| Native Linux route/input/audio | EVID-04 | Synthetic/headless fixtures have narrower scope | Run equivalent identified package/matrix on Linux with actual input, audible checks and captures |
| Local playback review | D-05–D-08 | Browser codecs, audible output and media interaction | Load real paired recordings, inspect optional overlays, event seeks/drift and source audio switching without retiming |
Unavailable/failed executions are recorded as open dependencies. Completing tools or preparing a bundle does not close EVID-02/EVID-04 or mark Phase 1 accepted. Source-backed later work may continue only under the existing roadmap exception.
## Measured Verification Evidence
- Completed integrated run: `artifacts/fidelity/01-07-full-suite.json` and `.log`, exit 0 in **782.049626 seconds**. Actual output records 556 Python tests (180 fidelity), 27 Node tests, 23 standalone managed observer checks, two separate HUD tests, all 51 managed entry-point invocations/build, 36 rendered Vulkan receipts with zero reported validation errors, SDL dummy-audio checks and 539 unchanged originals. Optional native-window checks were not enabled. Dummy audio does not establish audibility.
- Subsequent code-review fixes: `01-FIX-REPORT.md` and `artifacts/fidelity/01-review-fixes/`. `python-fidelity.log` records **189 passing tests in 40.072 seconds**; `acceptance-final.log` records **29 passing acceptance tests** after the final standalone-transfer regression. These runs overlap; do not add their counts. `node-viewer-direct.log` records 27 behavior tests, `powershell.log` 18 synthetic checks under Linux-hosted PowerShell, and `original-preservation.log` 539 unchanged originals. The initial sandbox socket errors were resolved by the scoped local run; they are not represented as passes.
- Current discovery, without executing runtime loops: acceptance 29, capture 23, checkpoint 25, ledger 31, observation 7, review 21, scenarios 25, sessions 29: **190 current fidelity tests**. The final added acceptance test explains the difference from the earlier 189-test aggregate; it was executed in the final 29-test acceptance run. Discovery alone is not execution evidence.
- Review fixes exercise selected-receipt digest binding, pristine executable/inventory identity, named copy-state lifetime binding, sealed ledger/history projection including standalone transfer, and incomplete-session recovery without captured promotion. They strengthen existing covered contracts; independent review remains separate.
- Fresh immutable checkpoint: **11001 members**, `dist/fidelity/phase01`. Saved `01-review-fixes/readiness.json` reports `materials_ready: true`, `acceptance: human_needed` (command exit 0). Saved `acceptance.json` reports `errors: []`, **0/120**, all ten human findings pending (strict command exit 1). Original-DxWnd, native Windows and native Linux each retain 40 outstanding obligations.
- Focused tooling feedback is generally around 1–5 seconds (session/scenario/ledger around one second, checkpoint 4.742 seconds, review 5.234 seconds in owning summaries); observer process integration measured 19.126 seconds. The broad 40.072-second regression **exceeds** the proposed 30-second quick target. This is a latency WARNING, not a missing behavioral check or evidence acceptance.
## Validation Sign-Off
- [x] Final plans bind every task to automated checks or explicit human/native evidence
- [x] Sampling continuity has no three consecutive tasks without automated verification
- [x] New test files exist and execute nonzero test counts
- [x] No watch-mode flags
- [ ] Broad quick feedback below 30 seconds — measured 40.072 seconds; WARNING retained
- [x] Native/original capture limitations recorded
- [x] Implemented automated validation contract audited; `nyquist_compliant` and `wave_0_complete` refer only to automation coverage
- [ ] Actual combined capture and human review complete — OPEN
- [ ] EVID requirements and Phase 01 acceptance complete — OPEN
**Automation validation:** Validated on 2026-11-13 from executed tests and retained logs; no new automated gap found, no tests or implementation changed. The latency target remains a documented warning. `status: validated` does not advance the phase or promote any EVID requirement.
**Acceptance dependencies:** A1, A2, EVID-02-unclassified, EVID-04-unclassified, P1, P2, P3, browser, paired_review and physical_input remain OPEN. Follow the single combined agenda in `docs/evidence/checkpoint-session.md` and its Windows/Linux session procedures. Collect actual original-DxWnd/native Windows/native Linux recordings, physical input and audible checks, review real paired playback, return the identified local results, then rerun strict acceptance. The Linux preflight's missing usable display/audio is an explicit dependency. Cross-publish, Wine, headless/synthetic fixtures and preparation cannot close it. Independent review/security gates remain owned by their respective audits.
## Final copy-state refinement
All191 fidelity checks pass in43.355s after02d182f (26 scenario,23 capture,29 acceptance); missing/hash-only/wrong-size state records are explicitly rejected for both lifetimes. The43.355s aggregate still exceeds the30s quick target. No manual acceptance was promoted.
## Validation Audit 2026-11-13
| Metric | Count |
|---|---|
| Gaps found | 0 |
| Resolved | 0 |
| Escalated | 0 |
@@ -0,0 +1,325 @@
---
phase: 01-reproducible-fidelity-baseline
verified: 2026-11-14T05:34:19Z
status: human_needed
score: 29/42 must-haves verified
covered_files: [".planning/REQUIREMENTS.md",".planning/ROADMAP.md",".planning/phases/01-reproducible-fidelity-baseline/01-01-PLAN.md",".planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md",".planning/phases/01-reproducible-fidelity-baseline/01-02-PLAN.md",".planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md",".planning/phases/01-reproducible-fidelity-baseline/01-03-PLAN.md",".planning/phases/01-reproducible-fidelity-baseline/01-03-SUMMARY.md",".planning/phases/01-reproducible-fidelity-baseline/01-04-PLAN.md",".planning/phases/01-reproducible-fidelity-baseline/01-04-SUMMARY.md",".planning/phases/01-reproducible-fidelity-baseline/01-05-PLAN.md",".planning/phases/01-reproducible-fidelity-baseline/01-05-SUMMARY.md",".planning/phases/01-reproducible-fidelity-baseline/01-06-PLAN.md",".planning/phases/01-reproducible-fidelity-baseline/01-06-SUMMARY.md",".planning/phases/01-reproducible-fidelity-baseline/01-07-PLAN.md",".planning/phases/01-reproducible-fidelity-baseline/01-07-SUMMARY.md","artifacts/fidelity/01-07-full-suite.json","artifacts/fidelity/01-07-full-suite.log","artifacts/fidelity/01-review-fixes/acceptance-final.json","artifacts/fidelity/01-review-fixes/python-fidelity-final.log","artifacts/fidelity/01-review-fixes/readiness-final.json","artifacts/fidelity/bytecode-fix/acceptance.json","artifacts/fidelity/bytecode-fix/fidelity-tests.log","artifacts/fidelity/bytecode-fix/observer-build.log","artifacts/fidelity/bytecode-fix/observer-retry.log","artifacts/fidelity/bytecode-fix/ready-bundled-1.json","artifacts/fidelity/bytecode-fix/ready-bundled-2.json","artifacts/fidelity/verification/01-07-final-checkpoint.json","docs/compatibility.md","docs/decisions.md","docs/evidence/README.md","docs/evidence/capabilities.json","docs/evidence/checkpoint-session.md","docs/evidence/linux-session.md","docs/evidence/phase01-baseline.md","docs/evidence/scenarios.json","docs/evidence/windows-session.md","docs/original-manifest.json","docs/progress.md","docs/tasks.md","scripts/collect-fidelity-linux.sh","scripts/collect-fidelity-windows.cmd","scripts/collect-fidelity-windows.ps1","scripts/env.sh","scripts/prepare-fidelity-checkpoint.sh","scripts/test.sh","src/GamePort/Application/FidelityObservation.cs","src/GamePort/Program.cs","tests/GamePort.FidelityObservationTests/GamePort.FidelityObservationTests.csproj","tests/GamePort.FidelityObservationTests/Program.cs","tests/fidelity-viewer.test.mjs","tests/fidelity-windows.Tests.ps1","tests/test_fidelity_acceptance.py","tests/test_fidelity_capture.py","tests/test_fidelity_checkpoint.py","tests/test_fidelity_ledger.py","tests/test_fidelity_observation.py","tests/test_fidelity_review.py","tests/test_fidelity_scenarios.py","tests/test_fidelity_sessions.py","tools/recon/fidelity.py","tools/recon/fidelity_acceptance.py","tools/recon/fidelity_capture.py","tools/recon/fidelity_checkpoint.py","tools/recon/fidelity_ledger.py","tools/recon/fidelity_receipts.py","tools/recon/fidelity_review.py","tools/recon/fidelity_viewer/index.html","tools/recon/fidelity_viewer/style.css","tools/recon/fidelity_viewer/viewer.mjs","tools/recon/inventory.py"]
covered_digest: "v4:sha256:acca5bdaa1f405a74d29d69c8ebe048085a6a4ff4c86e3b3f80c97cebfba8ac3"
behavior_unverified: 0
overrides_applied: 0
decision_coverage:
honored: 16
total: 16
not_honored: []
non_inferable_checks:
- truth: "Actual original-DxWnd moving game imagery and intelligible audio are observed and reviewed with wrapper/config limitations recorded."
status: uncertain
reason: insufficient_spec
human_check: A1
- truth: "Actual paired recordings decode, seek and switch exclusive audio in the identified local browser without concealing elapsed time."
status: uncertain
reason: insufficient_spec
human_check: A2
unverified_prohibitions:
- id: P1
statement: "MUST NOT sacrifice authoritative original bytes or execute the authoritative installation to make reference collection convenient."
status: unverified
flag: "unverified-prohibition — human review recommended"
- id: P2
statement: "MUST NOT manufacture apparent parity by retiming recordings, hiding drift, mixing both soundtracks or presenting synthetic media as an original reference."
status: unverified
flag: "unverified-prohibition — human review recommended"
- id: P3
statement: "MUST NOT erase contradictory history, hide unimplemented required content or turn missing evidence into a fidelity-completion claim."
status: unverified
flag: "unverified-prohibition — human review recommended"
human_verification:
- test: "A1 — Capture and observe the isolated original through the selected DxWnd setup"
expected: "Complete 40 original-Windows-DxWnd obligations; observe moving game imagery and intelligible game audio, retaining actual executable/profile/copy inventories and wrapper/configuration limitations."
why_human: "Original execution and audiovisual truth are unobserved; the backstop abstains with insufficient_spec."
- test: "A2 — Exercise actual paired recordings in the identified browser"
expected: "Both real recordings decode, play at actual speed, seek to their own observed events, preserve full tails and switch exclusive audio without concealing elapsed time."
why_human: "Controller tests use media doubles; they cannot establish real codec/browser/physical-audio behavior. Backstop: insufficient_spec."
- test: "EVID-02-unclassified — Review original capture boundaries and limitations"
expected: "Document observed original/DxWnd launch, crop, aspect, timing, recording boundaries and retained/fresh lifetimes for the actual reference captures."
why_human: "This flagged assumption cannot be inferred from prepared settings or synthetic metadata."
- test: "EVID-04-unclassified — Collect and inspect both native platform routes"
expected: "Complete 40 native Windows and 40 native Linux obligations with actual OS/GPU/driver/Vulkan/SDL/source/package/resource identity and observed route/input/audio continuity."
why_human: "Windows is cross-published only; current Linux TTY/auto_null preflight cannot capture native physical gameplay."
- test: "P1 — Resolve the original-preservation prohibition explicitly"
expected: "Confirm authoritative originals were never executed or changed; compare all 539 recorded hashes and generated-copy pre/retained/post inventories after the session."
why_human: "Descriptor-less unresolved prohibition requires explicit disposition; current preserved hashes do not prove future session conduct."
- test: "P2 — Resolve the honest-comparison prohibition explicitly"
expected: "Confirm genuine original media, no retiming or concealed drift, no mixed simultaneous soundtracks, and visible review gain/derivation provenance."
why_human: "Unverified-prohibition — human review recommended; genuine playback and perceived audiovisual comparison require observation."
- test: "P3 — Resolve the history/full-scope/native-transparency prohibition explicitly"
expected: "Confirm all 33 requirements and unimplemented content stay visible; conflicting/superseded evidence and native/Wine/component/cross-publish distinctions are preserved after reconciliation."
why_human: "Unverified-prohibition — human review recommended; final returned-evidence reconciliation requires explicit judgment."
- test: "browser — Review the complete local comparison interface"
expected: "With real captures, verify readable independent clocks/drift, keyboard controls, raw unobstructed default views, optional annotations/differences and visible loading/error/tail states."
why_human: "No actual browser visual/usability/codec review has been performed."
- test: "paired_review — Compare all corresponding actual recordings and record discrepancies"
expected: "Review matched events, imagery and sound across the required cases, retaining raw drift and justified system-specific observations without invented tolerances."
why_human: "No corresponding original/native pair or completed visual/audible comparison exists."
- test: "physical_input — Exercise visible native gameplay and actual audible devices"
expected: "On Linux and Windows use physical supported inputs through lab → VR04 → lab → outside, natural/skipped and fresh/retained cases, held input, banked jumps, landing and idle; confirm real display/audio output."
why_human: "Injected/headless/GPU/dummy-audio fixtures prove narrower behavior and cannot satisfy physical-input or audibility acceptance."
---
# Phase 1: Reproducible Fidelity Baseline Verification Report
**Phase Goal:** As a tester, I want to reproduce identified original/port comparison scenarios, so that I understand exactly what the current reconstruction proves on each native platform.
**Verified:** 2026-11-14T05:34:19Z
**Status:** human_needed
**Re-verification:** No existing VERIFICATION.md; completion of the interrupted initial verification after the MVP goal-format correction (`febb4a9`). No scope change or override.
## User Flow Coverage
| Step | Expected | Evidence | Status |
|---|---|---|---|
| Open the local checkpoint and inspect identities | Identified offline original copy, both port packages, complete agenda and viewer | Final readiness receipt: 11,001 immutable members; materials_ready true | VERIFIED for preparation |
| Reproduce isolated original scenarios | Moving imagery, intelligible audio, input/events and retained/fresh provenance from the actual selected DxWnd configuration | Collector/guide prepared; no returned original gameplay captures; 0/40 accepted | UNCERTAIN — WARNING; A1, EVID-02, P1 |
| Repeat matching native Linux/Windows routes | Same route/cases with physical input, real display/audio and exact runtime identities | Windows cross-publish only; real Linux preflight failed without selected X11/real audio; 0/80 accepted | UNCERTAIN — WARNING; EVID-04, physical_input |
| Inspect paired playback | Actual corresponding media with independent event times, exposed drift and exclusive audio | Controller is implemented/tested; prepared viewer contains no actual pair | UNCERTAIN — WARNING; A2, browser, paired_review, P2 |
| Trace what each capability proves | Source/implementation/platform/scope/discrepancy/remaining-acceptance links across the full game | 25 capabilities, six groups, all 33 requirements; current/history preserved | VERIFIED for traceability; P3 final judgment pending |
| Understand the reconstruction on each native platform | Actual identified original/native evidence plus honest discrepancies and unresolved limitations | Audit: errors [], 0/120 accepted; ten named human findings pending | UNCERTAIN — WARNING; user-story outcome remains open |
The MVP user flow is incomplete. No new technical runtime/test run was started to bypass it. The implementation evidence below records inspected code and already completed local verification; it does not constitute manual acceptance. Phase 1 is not passed and Phase 2 is not advanced by this report.
## Goal Achievement
### Observable Truths
Roadmap criteria are retained in full; PLAN truths add detail and do not reduce them. VERIFIED on a tooling truth certifies its bounded implementation, not original/native fidelity. UNCERTAIN items request human verification rather than asserting missing implementation. No accepted override exists.
| ID | Truth | Status | Evidence |
|---|---|---|---|
| SC1 | A reviewer can verify every original against the recorded inventory and run investigation/reference copies without altering the original installation. | UNCERTAIN — WARNING | `verify_inventory`/staging and saved 539-file check prove current preservation; actual generated-copy reference execution and P1 disposition remain unobserved. |
| SC2 | A tester can reproduce identified whole-original reference scenarios from an isolated generated installation and inspect corresponding input/events, images and audio where applicable; unavailable execution keeps this criterion open. | UNCERTAIN — WARNING | Actual original-DxWnd captures absent; explicit access limitation leaves 40 obligations open (A1/EVID-02). |
| SC3 | A reviewer can trace every full-game capability from original evidence through current implementation, platform receipts, discrepancies and its remaining acceptance condition. | VERIFIED | Ledger validator/export/renderer connect 25 capabilities to all 33 requirements, source paths, implementation revisions, scoped platform records, differences and open acceptance. |
| SC4 | Testers can repeat the same baseline movement/route scenarios on native Linux and native Windows with exact revision identities; Wine/cross-publish receipts remain separately labeled and cannot close missing native execution. | UNCERTAIN — WARNING | No accepted current native baseline capture on either platform: 40 Linux + 40 Windows obligations remain open (EVID-04/physical_input). |
| 01.1 | A reviewer can stage and identify a pristine generated original installation without altering any original byte (EVID-01, D-15). | VERIFIED | `fidelity.py:stage` calls `stage_original`; `verify_inventory` compares all recorded file identities before/after isolated copying. Saved original-preservation log verifies 539 unchanged originals. Actual DxWnd execution remains separately pending. |
| 01.2 | The protocol requires continuous lab → VR04 → lab → outside and focused dialogue-return, left/right banked-jump, landing and idle captures per D-01 and D-04. | VERIFIED | `scenarios.json` requires continuous lab → VR04 → lab → outside plus dialogue-return, left/right bank, landing/idle; `validate_scenario_contract`/`audit_scenarios` enforce obligations. |
| 01.3 | Natural/skipped dialogue and fresh/retained entry are equally required, independently identified dimensions per D-02 and D-03. | VERIFIED | Eight case IDs independently cross fresh/retained, natural/skipped and ordinary/held-input; scenario validator rejects collapsed dimensions. |
| 01.4 | Equal, nested, symlink-aliased and Windows case-aliased source/output paths fail before any staging write; sibling paths merely sharing a textual prefix remain distinct. | VERIFIED | `separated_roots`, symlink rejection and canonical path checks precede staging writes; session regressions cover equal/nested/case/symlink/prefix cases. |
| 01.5 | Empty/missing inventories fail; single-file fixtures round-trip, while changed, missing and added files invalidate identity. | VERIFIED | `identify_tree` rejects empty inventory; exact file-list comparison rejects changed/missing/added files; single-file round-trip regressions are active. |
| 01.6 | Manifest order is canonical relative POSIX path order; case-colliding identities fail instead of acquiring filesystem-dependent order. | VERIFIED | `identify_tree` sorts POSIX paths and rejects casefold collisions; canonical-order regression checks actual list/digest values. |
| 01.7 | Interrupted staging/import leaves an explicit incomplete diagnostic and no completed receipt; simultaneous same-session allocation has one winner, and duplicate receipt imports are idempotent only for byte-identical content. | VERIFIED | `_reserve`, exclusive writes, incomplete siblings and atomic publication implement allocation/import ownership. Named concurrency/interruption/duplicate regressions in `test_fidelity_sessions.py` pass in saved 191-test run. |
| 01.8 | Typed receipt validation retains failures and missing evidence as open acceptance; D-13 Windows availability is not a runtime receipt. | VERIFIED | `validate_receipt`/`audit_scenarios` separate failure, synthetic, component, Wine and native kinds. Current real failed Linux receipt remains OPEN; availability is no receipt. |
| 02.1 | A tester opens a local scenario with paired original/port playback and corresponding image, audio and input/event links per D-05. | UNCERTAIN — WARNING | Exporter/controller support paired validated receipts, but final `review.json` has no actual original/native pair. A1/A2/browser/paired_review remain human checks. |
| 02.2 | Raw captures are unobstructed by default; annotations and provenance-bound image differences are optional overlays per D-06. | VERIFIED | Controller defaults `annotations`/`difference` false; corresponding Node overlay/provenance regressions cover opt-in state. Actual visual unobstruction remains part of browser review. |
| 02.3 | Selecting an event seeks each recording to its own observed time; both play at actual speed with separate elapsed clocks, event drift and playback drift per D-07. | VERIFIED | Named Node event-selection/drift/readiness tests assert separate observed times, rate 1, independent elapsed clocks and exposed drift. This verifies controller behavior, not actual codec/browser playback. |
| 02.4 | The reviewer switches corresponding original/port audio with at most one source audible and visible review gain per D-08. | VERIFIED | Named exclusive-soundtrack/gain tests assert both muted before selecting one and labeled review-only gain. Physical audibility remains pending. |
| 02.5 | Missing, buffering, rejected-play, decoding and asymmetric-end states remain visible and preserve the full recording tails. | VERIFIED | Named rejected-play/buffering/decode/asymmetric-end tests assert paired pause, visible cause and resumable full longer tail. Real browser observation is still A2. |
| 03.1 | Reviewers browse movement, contacts, gadgets, progression, visuals and audio with requirement/source/scenario/platform links per D-09. | VERIFIED | `GROUPS` and ledger contain movement, contacts, gadgets, progression, visuals and audio; exported capability links include source/requirement/scenario/platform. |
| 03.2 | Each capability leads with working behavior, verified scope/platform, known differences and remaining acceptance per D-10. | VERIFIED | Capability rows carry working summary, verified scope, implementation revision, differences and open acceptance; renderer presents supplied facts. |
| 03.3 | Current applicable evidence precedes expandable explicitly superseded revision history per D-11; applicability uses content/scope/platform rather than newest date. | VERIFIED | Scope/content/platform applicability and explicit supersession retain current/history. Final reviewed fix verifies both projections survive bundle export; newest date is not acceptance. |
| 03.4 | Discrepancies order blocking/disruptive failures before subtler differences and missing verification per D-12; all missing evidence keeps acceptance open. | VERIFIED | `IMPACTS` orders blocking/disruptive/subtle/missing_verification; acceptance stays open. Strict current audit has no accepted runtime obligations. |
| 03.5 | All 33 full-game requirements have capability coverage even when unimplemented; an empty ledger fails and one capability remains renderable. | VERIFIED | Ledger covers 25 capabilities and all 33 requirements across six groups; validator rejects empty ledger, renderer supports a singleton. Full-game implementation is not claimed. |
| 03.6 | Equal receipt/content identities merge only when the record bytes match; conflicts remain explicit, and duplicate history rows never silently overwrite evidence. | VERIFIED | Canonical byte conflict checks prevent contradictory receipt/content deduplication and preserve history; ledger regression assertions cover conflicts. |
| 03.7 | Equal-priority entries have deterministic stable ID ordering; explicit supersession cycles and unresolved contradictory current claims fail validation. | VERIFIED | Stable ID sorting, supersession-cycle and contradictory-current validation are implemented and covered by active ledger regressions. |
| 04.1 | An optional passive observer records actual native port input/control/scene events across the continuous route per D-01, without changing gameplay or scene lifetime. | VERIFIED | `Program.cs:18-30` owns one optional observer across outer Run continuations; post-Step calls at 1328-1333 use actual accepted input/state. Managed/process regressions cover observer wiring; no physical route acceptance inferred. |
| 04.2 | Natural/skipped and fresh/retained runs have distinct case identities, with one monotonic session across actual retained continuations per D-02 and D-03. | VERIFIED | One retained observer/monotonic session spans Run continuations; distinct case identity and simulation ticks are preserved. Existing observer tests exercise clock/order/continuation. |
| 04.3 | Held/neutral input, banked jump, landing and idle observations retain their real owner/tick/time per D-04; injected smoke fixtures stay separately classified. | VERIFIED | Actual raw SDL/input/state/control calls include owner/tick/time; smoke/injected paths are separately classified. Managed and process assertions check payload/receipt interoperability. |
| 04.4 | An output failure leaves the observation incomplete and visible rather than reporting acceptance or changing movement/state to finish the recording. | VERIFIED | Observer write failure emits an incomplete diagnostic without completing acceptance; standalone managed failure regressions exercise this path. |
| 05.1 | One complete local checkpoint bundle contains identified port packages, a verified generated original copy, scenarios, viewer and result collection per D-14. | VERIFIED | Final checkpoint receipt identifies 11,001 immutable members, both sealed packages, generated original seed, protocol, viewer and result collectors; readiness true. |
| 05.2 | The available Windows PC is treated as a pending execution environment per D-13; actual OS/GPU/driver/tool identities are collected during the session. | VERIFIED | Windows session guide/collector require actual OS/GPU/driver/tool observations; no native Windows receipt exists. Pending environment is explicitly distinguished from execution. |
| 05.3 | The original launches only from a generated copy through the user's identified DxWnd binary/exported profile, separately from native port receipts, per D-15. | UNCERTAIN — WARNING | Collector protects original-pristine, copies a writable run, retains selected DxWnd/profile and requires GUI launch. Actual user-selected DxWnd execution/configuration is unobserved; A1/P1 pending. |
| 05.4 | All original-reference and port materials are prepared before one combined session per D-16; preparation does not close EVID-02 or EVID-04. | VERIFIED | Readiness validates both package identities and complete 80-obligation Windows agenda; guide also requires 40 Linux obligations. `ready()` always reports human_needed. |
| 05.5 | Launcher preflight or recording failure produces an actionable local failure receipt without inventing successful capture or downloading dependencies. | VERIFIED | Collector/preflight failures retain diagnostic/open states. Actual Linux TTY/null-audio failure is retained; PowerShell recovery checks cover aborted incomplete collection without invented success. |
| 06.1 | An identified native Linux package yields actual input/event and audiovisual captures where execution is available; synthetic/headless replays remain distinct (EVID-04). | UNCERTAIN — WARNING | Native Linux collector invokes identified package/observer and real recorder only after preflight. Current host has no selected real display/audio and produced failed preflight, with no gameplay capture. |
| 06.2 | Continuous route and focused captures cover all natural/skipped, fresh/retained and ordinary/edge cells per D-01–D-04, with missing executions explicitly open. | UNCERTAIN — WARNING | Matrix/scenario implementation requires all 40 Linux obligations and tracks missing cases, but no physical Linux route/focused capture is accepted. |
| 06.3 | Physical input/audio and real visible gameplay require actual native receipts/human review; dummy audio and window-only fixtures cannot complete acceptance. | VERIFIED | Preflight rejects dummy/null devices; native review requires real input/audibility/visibility. Strict audit cannot accept headless/synthetic fixtures. |
| 07.1 | One fully prepared combined session covers original-DxWnd and native Windows cases, local Linux review and real paired playback, per D-13–D-16. | UNCERTAIN — WARNING | Materials and one-session agenda are ready; the combined original/native/browser session has not occurred. |
| 07.2 | Every required original-reference and native Linux/Windows case has exact revision/package/resource/media and observation provenance; absent or failed cases keep EVID-02/EVID-04 open. | UNCERTAIN — WARNING | Strict audit reports 0/120 accepted, no structural errors and every missing obligation. Exact successful runtime/media provenance cannot yet be verified. |
| 07.3 | Paired review of actual original/port captures applies D-05–D-08 and publishes raw drift, discrepancies and audible/visible checks. | UNCERTAIN — WARNING | No actual paired recordings or witnessed drift/audio/visual review returned; paired_review/P2 remain pending. |
| 07.4 | Current capabilities/history/discrepancies are reconciled to returned receipts per D-09–D-12, with full matrix completeness per D-01–D-04. | UNCERTAIN — WARNING | Current baseline and ledger honestly retain missing evidence; returned-receipt reconciliation awaits actual collection and agent-owned normalization/import. |
| 07.5 | Actual original-DxWnd moving game imagery and intelligible audio are observed and reviewed with wrapper/config limitations recorded. | UNCERTAIN — WARNING | UNCERTAIN — insufficient_spec: no observed original-DxWnd moving imagery/intelligible audio and wrapper review (A1); metadata fixtures cannot prove it. |
| 07.6 | Actual paired recordings decode, seek and switch exclusive audio in the identified local browser without concealing elapsed time. | UNCERTAIN — WARNING | UNCERTAIN — insufficient_spec: no actual identified-browser decode/seek/exclusive-audio observation (A2); Node media doubles cannot prove browser codecs or audibility. |
**Score:** 29/42 truths verified; 13 UNCERTAIN. **Present-but-behavior-unverified invariants:** 0. Existing behavioral regressions exercise the tooling transitions; the unverified items concern actual external execution, media, physical experience and final reconciliation. A1/A2 separately abstain with `insufficient_spec`.
### Required Artifacts and Wiring Evidence
Owner `query verify.artifacts` independently returned exit 0 for each of seven PLANs: **21/21 declared artifacts** exist and are substantive. Source inspection then checked their actual callers and data contracts.
| Plan | Declared artifacts | Implementation/wiring evidence | Status |
|---|---|---|---|
| 01-01 | fidelity.py; fidelity_receipts.py; scenarios.json | CLI dispatches stage/identify/import/validate; shared validators consume supplied protocol and real byte inventories | VERIFIED |
| 01-02 | fidelity_review.py; fidelity_viewer/viewer.mjs; fidelity-viewer.test.mjs | Validated receipt export → review.json/local media → fetch → controller/renderer; actual pair absent | VERIFIED implementation; actual browser pending |
| 01-03 | capabilities.json; fidelity_ledger.py; docs/evidence/README.md | Validator checks tracked source/requirements/scenarios; canonical export supplies bundle and viewer current/history projection | VERIFIED |
| 01-04 | FidelityObservation.cs; managed observer test Program.cs; test_fidelity_observation.py | Outer Program continuation owns observer; actual raw/input/control/state hooks feed ordered JSONL; process tests feed receipt contract | VERIFIED bounded observer |
| 01-05 | fidelity_checkpoint.py; collect-fidelity-windows.ps1; windows-session.md | Preparation launcher calls assembler; actual files sealed/preflighted; PowerShell emits same versioned contract for later validated import | VERIFIED implementation; native execution pending |
| 01-06 | fidelity_capture.py; linux-session.md; collect-fidelity-linux.sh | Shell execs collector; selected package/observer/recorder argv and real-device preflight feed failure/capture collection and matrix | VERIFIED implementation; native physical capture pending |
| 01-07 | fidelity_acceptance.py; checkpoint-session.md; phase01-baseline.md | Explicit selected receipts/hashes + complete scenario audit + ten findings decide strict acceptance; baseline accurately leaves evidence open | VERIFIED implementation; final reconciliation pending |
Paths above are the exact declared repository paths shown in each PLAN and fingerprint; no artifact is merely an unused placeholder.
### Key Link Verification
The owner heuristic returned 1/14 literal-path links and exit 1 on each PLAN. It searches literal target paths; Python module imports, C# class use, external schema contracts and prose names do not match. Those negative heuristic results are not treated as verified. Manual traces establish the implemented connections below; runtime-return links stay explicitly pending.
| From → To | Actual connection | Status |
|---|---|---|
| fidelity.py → inventory baseline | stage_original → verify_inventory compares inventory.py-compatible file list with docs/original-manifest.json; no direct inventory.py import is needed | WIRED by shared inventory contract |
| fidelity_receipts.py → scenarios.json | CLI/capture pass loaded protocol to validate_scenario_contract/audit_scenarios; stable IDs and required obligations validated | WIRED |
| fidelity_review.py → fidelity_receipts.py | Imports and calls read_receipt, validate_receipt, contained_path, identify_file before export | WIRED |
| viewer.mjs → generated review/media | fetch('review.json') supplies per-side media/events to createPairController; controller enforces exclusive mute and independent times | WIRED; actual media/browser pending |
| capabilities.json → REQUIREMENTS.md | Validator extracts exact IDs and rejects incomplete coverage; all 33 IDs accounted for | WIRED |
| fidelity_ledger.py → viewer ledger | Canonical export/current/history projection copied during checkpoint assembly and rendered by renderCapabilities | WIRED |
| Program.cs → FidelityObservation.cs | Optional outer using owner passed through Run; real post-Step acceptsInput/state/control/raw SDL hooks call observer | WIRED |
| Observed JSONL → shared receipts | Versioned session/case/elapsed/tick payload validated through process interoperability and collector; synthetic scope preserved | WIRED contract; real route pending |
| prepare-fidelity-checkpoint.sh → fidelity_checkpoint.py | Explicit Python invocation consumes original inventory and completed sealed packages | WIRED |
| Windows collector → shared receipts | Emits schema-versioned raw receipts, exact content identities and failure states; documented agent-owned validation/import normalizes returned reviewed records | WIRED contract; actual returned data pending |
| fidelity_capture.py → Linux package/observer | Uses actual package executable/assets and --fidelity-* arguments after real display/audio preflight | WIRED; hardware execution pending |
| Linux receipts → review/acceptance | Collected diagnostics undergo shared validation/import and explicit current selection; real failed Linux receipt remains open | WIRED failure path; successful route pending |
| Returned Windows/Linux results → strict audit | audit reads current.json, validates contained selected receipts and receipt_sha256 binding, checks all 120 slots and named reviews | WIRED implementation; human return pending |
| phase01-baseline.md → capability ledger | Same open acceptance/current scope retained; documented reconciliation updates receipt-bound current/history after return | WIRED present baseline; future reconciliation pending |
### Data-Flow Trace (Level 4)
| Rendered/accepted value | Actual source and flow | Finding |
|---|---|---|
| Capability navigation/current/history/discrepancies | capabilities.json → validate/export → sealed protocol/capability-ledger.json → review.json → renderCapabilities | FLOWING: real maintained evidence; unimplemented and missing scopes remain visible |
| Paired video/audio/event times | Actual imported receipt artifacts/hashes → _side/_events export → review.json → media/controller | Implementation wired; current source is explicitly missing, not synthetic original footage |
| Observer input/state/elapsed | Actual SDL/control/post-Step data → retained observer → bounded JSONL → collector/receipt validation | FLOWING in bounded regressions; current complete physical capture unavailable |
| Native acceptance totals | Explicit selected actual receipt files + content identities → audit_scenarios + CHECKS → strict report | FLOWING: actual failed diagnostic yields 0/120, errors [], human_needed |
Missing media is expected open evidence and is displayed as such; no hardcoded empty success path or invented original recording closes it.
### Existing Behavioral Evidence Reviewed
This completion pass did not rerun tests or launch services. Commands/results below are from retained execution receipts/logs, not SUMMARY assertions; fresh owner queries covered artifact presence, story validity and decision coverage.
| Evidence | Recorded invocation/result | Limit |
|---|---|---|
| Integrated local suite | artifacts/fidelity/01-07-full-suite.json and .log: scripts/test.sh, exit 0, 782.049626s; 556 Python (180 fidelity), 27 Node, 23 managed observer, 2 HUD, 51 managed entry-point invocations, 36 rendered GPU receipts, zero Vulkan errors, 539 originals | Before later tooling-only review fixes; dummy audio/headless checks are not physical/native baseline capture |
| Final tooling regression | artifacts/fidelity/01-review-fixes/python-fidelity-final.log: 191 tests, 43.355s, OK | Includes final copy-state artifact-root fix; no new runtime change or full GPU rerun claimed |
| Media controller | artifacts/fidelity/01-review-fixes/node-viewer-direct.log: 27 pass, 0 fail/skipped; named independent seek/drift, exclusive mute, rejected play, buffering, decode and full-tail assertions inspected | Media doubles exercise controller transitions, not actual browser decoding/audibility |
| Preservation | artifacts/fidelity/01-review-fixes/original-preservation.log: 539 unchanged originals | Byte preservation at check time; final P1 session conduct still needs disposition |
| Readiness | artifacts/fidelity/01-review-fixes/readiness-final.json plus verification/01-07-final-checkpoint.json: 11,001 members, materials_ready true, human_needed | Sealed runtime provenance retained as 446930d dirty true / diff 90cef956…; later tooling revision does not relabel it |
| Strict acceptance | artifacts/fidelity/01-review-fixes/acceptance-final.json: require-complete exit 1, errors [], accepted 0/120, all ten findings pending | Expected open evidence; no malformed acceptance input or observed code failure |
No phase-declared shell probe requiring a separate new execution was identified; the phase relies on the retained local CLI/test/preflight evidence. No full suite was repeated in this completion pass.
### Requirements Coverage
All four accountable requirement IDs are declared across the seven PLANs; no Phase 1 requirement is orphaned. Pending is retained in REQUIREMENTS.md.
| Requirement | Source PLANs | Evidence and remaining dependency | Disposition |
|---|---|---|---|
| EVID-01 | 01,05,06,07 | 539 unchanged originals; bounded isolated staging, canonical inventory and pre/post checks implemented. Final actual session preservation/P1 remains pending | Pending — current preservation verified; final human disposition required |
| EVID-02 | 01,02,04,05,07 | Original-DxWnd collector/protocol/identity/review tooling ready; 0/40 actual original obligations and A1/original-boundary review open | Pending — NEEDS HUMAN |
| EVID-03 | 02,03,07 | All 33 full-game requirements represented in 25 capabilities/six groups; source/implementation/platform/history/discrepancy/open acceptance traceable. Returned-evidence reconciliation and P3 remain open | Pending — ledger implementation verified; final human/reconciliation dependency |
| EVID-04 | 01,02,04,05,06,07 | Native collectors, observer and exact package binding implemented; failed Linux physical preflight retained, no accepted native route; 0/80 accepted | Pending — NEEDS HUMAN |
### Decision Coverage
Owner query: **16/16** trackable CONTEXT decisions honored, not_honored []. “All trackable CONTEXT.md decisions are honored by shipped artifacts.” Advisory gate only; it does not change acceptance.
### Test Quality and Anti-Patterns
Active tests assert concrete identity bytes, rejection behavior, monotonic ownership/state, media-controller transitions and acceptance classification. Test-generated metadata/media are explicitly synthetic fixtures: they verify validators/controller behavior and are never original/native fidelity oracles. The complete-metadata positive matrix test cannot establish actual physical execution; strict real matrix stays 0/120.
The targeted completion scan found no unreferenced TBD/FIXME/XXX or disabled requirement-test markers in the fidelity source/tests/scripts/observer scope; the prior completed 40-file debt/skip scan is retained. Expected empty initial review and false human-review fields preserve missing evidence. They are not stubs claiming completion. No new blocking anti-pattern was established.
Existing gates remain recorded: security 22/22 mitigated, zero open; validation automation complete with manual checks open; independent review verification closes all five historical findings after 02d182f. UI review was explicitly disabled for this phase by the recorded gate configuration; TDD is inactive. These gates were not reopened. Broad tooling feedback 43.355s exceeds its 30s quick target (WARNING), with no effect on native acceptance.
### Human Verification Required
**Ten named findings remain pending.** Collect, observe and return one complete local result tree following docs/evidence/checkpoint-session.md and its Windows/Linux subguides. The integration agent owns evidence-backed normalization, reviewed-copy creation, hash validation, import, current selection, ledger reconciliation and final strict audit after return. Raw receipts remain immutable. Positive human findings must never be generated automatically.
#### 1. A1 — Capture and observe the isolated original through the selected DxWnd setup
**Test:** A1 — Capture and observe the isolated original through the selected DxWnd setup using the combined-session guide.
**Expected:** Complete 40 original-Windows-DxWnd obligations; observe moving game imagery and intelligible game audio, retaining actual executable/profile/copy inventories and wrapper/configuration limitations.
**Why human:** Original execution and audiovisual truth are unobserved; the backstop abstains with insufficient_spec.
#### 2. A2 — Exercise actual paired recordings in the identified browser
**Test:** A2 — Exercise actual paired recordings in the identified browser using the combined-session guide.
**Expected:** Both real recordings decode, play at actual speed, seek to their own observed events, preserve full tails and switch exclusive audio without concealing elapsed time.
**Why human:** Controller tests use media doubles; they cannot establish real codec/browser/physical-audio behavior. Backstop: insufficient_spec.
#### 3. EVID-02-unclassified — Review original capture boundaries and limitations
**Test:** EVID-02-unclassified — Review original capture boundaries and limitations using the combined-session guide.
**Expected:** Document observed original/DxWnd launch, crop, aspect, timing, recording boundaries and retained/fresh lifetimes for the actual reference captures.
**Why human:** This flagged assumption cannot be inferred from prepared settings or synthetic metadata.
#### 4. EVID-04-unclassified — Collect and inspect both native platform routes
**Test:** EVID-04-unclassified — Collect and inspect both native platform routes using the combined-session guide.
**Expected:** Complete 40 native Windows and 40 native Linux obligations with actual OS/GPU/driver/Vulkan/SDL/source/package/resource identity and observed route/input/audio continuity.
**Why human:** Windows is cross-published only; current Linux TTY/auto_null preflight cannot capture native physical gameplay.
#### 5. P1 — Resolve the original-preservation prohibition explicitly
**Test:** P1 — Resolve the original-preservation prohibition explicitly using the combined-session guide.
**Expected:** Confirm authoritative originals were never executed or changed; compare all 539 recorded hashes and generated-copy pre/retained/post inventories after the session.
**Why human:** Descriptor-less unresolved prohibition requires explicit disposition; current preserved hashes do not prove future session conduct.
#### 6. P2 — Resolve the honest-comparison prohibition explicitly
**Test:** P2 — Resolve the honest-comparison prohibition explicitly using the combined-session guide.
**Expected:** Confirm genuine original media, no retiming or concealed drift, no mixed simultaneous soundtracks, and visible review gain/derivation provenance.
**Why human:** Unverified-prohibition — human review recommended; genuine playback and perceived audiovisual comparison require observation.
#### 7. P3 — Resolve the history/full-scope/native-transparency prohibition explicitly
**Test:** P3 — Resolve the history/full-scope/native-transparency prohibition explicitly using the combined-session guide.
**Expected:** Confirm all 33 requirements and unimplemented content stay visible; conflicting/superseded evidence and native/Wine/component/cross-publish distinctions are preserved after reconciliation.
**Why human:** Unverified-prohibition — human review recommended; final returned-evidence reconciliation requires explicit judgment.
#### 8. browser — Review the complete local comparison interface
**Test:** browser — Review the complete local comparison interface using the combined-session guide.
**Expected:** With real captures, verify readable independent clocks/drift, keyboard controls, raw unobstructed default views, optional annotations/differences and visible loading/error/tail states.
**Why human:** No actual browser visual/usability/codec review has been performed.
#### 9. paired_review — Compare all corresponding actual recordings and record discrepancies
**Test:** paired_review — Compare all corresponding actual recordings and record discrepancies using the combined-session guide.
**Expected:** Review matched events, imagery and sound across the required cases, retaining raw drift and justified system-specific observations without invented tolerances.
**Why human:** No corresponding original/native pair or completed visual/audible comparison exists.
#### 10. physical_input — Exercise visible native gameplay and actual audible devices
**Test:** physical_input — Exercise visible native gameplay and actual audible devices using the combined-session guide.
**Expected:** On Linux and Windows use physical supported inputs through lab → VR04 → lab → outside, natural/skipped and fresh/retained cases, held input, banked jumps, landing and idle; confirm real display/audio output.
**Why human:** Injected/headless/GPU/dummy-audio fixtures prove narrower behavior and cannot satisfy physical-input or audibility acceptance.
### Acceptance Conclusion
Autonomous preparation is complete; the promised real comparison outcome remains human_needed. No implementation BLOCKER was established in this bounded completion. The observable absence of original/native accepted captures is a documented human/external evidence dependency, explicitly kept open by the roadmap contract, not silently passed.
A1/A2 are **unverified non-inferable checks** (`insufficient_spec`); P1/P2/P3 are **unverified-prohibition — human review recommended**, with no automatic resolution. No later phase specifically replaces Phase 1 capture/review obligations, so none are deferred. No phase completion, advancement, commit or push was performed.
The fingerprint was produced by the owner CLI `query verification.fingerprint` over the listed actual source/test/document/evidence inputs; its returned fields are copied verbatim. Planning PLAN/SUMMARY coverage was added by the owner. SUMMARYs supply intended interfaces, not proof of behavior.
---
_Verified: 2026-11-14T05:34:19Z_
_Verifier: gsd-verifier_
## Bounded Verification Follow-up — Bundled Bytecode Fix (2026-11-14)
The first actual UAT readiness command exposed a tooling defect: Python local imports created `__pycache__/*.pyc` inside the sealed checkpoint, so later immutable-tree checks could fail. This qualifies the earlier readiness evidence; it was not an original/native capture or an A1 pass. Historical bundle `phase01-before-bytecode-fix-20261114T215109Z` is preserved. The freshly assembled `dist/fidelity/phase01` retains 11,001 immutable members and existing result/run history.
Independently inspected regression commit `23ee1c2` and implementation commit `2fe8b40`. The regression invokes all five copied bundled CLI entry points using `python -E`, checks that no bytecode appears, invokes copied checkpoint preflight twice, and compares the complete tree identity before/after. The fix sets `sys.dont_write_bytecode = True` only under `__name__ == '__main__'`, before local imports, in acceptance/checkpoint/capture/review/ledger. It adds two required sys imports and changes no gameplay, library algorithm, receipt schema or acceptance decision.
| Retained evidence inspected | Actual result and scope |
|---|---|
| bytecode-fix/ready-bundled-1.json and ready-bundled-2.json | Exact bundled-cwd default-python readiness command succeeded twice without -B: materials_ready true, 11,001 members, human_needed; updated checkpoint identity receipt records zero created bytecode files |
| bytecode-fix/fidelity-tests.log | Initial broad attempt ran 185 test methods, with an observer-class setup ERROR caused by its 90-second .NET build timeout; the run is FAILED, not a passing aggregate. The completed methods include the 26 checkpoint regressions |
| bytecode-fix/observer-build.log | Separate bounded build succeeded in 72.12s, zero errors; one NU1900 vulnerability-index access warning retained |
| bytecode-fix/observer-retry.log | Observer-only retry: seven tests PASS in 24.473s; 192 target checks are covered across the separate runs, not by a successful initial full run |
| bytecode-fix/acceptance.json | Strict audit remains exit 1, errors [], 0/120 accepted, all ten named human findings pending |
| verification/01-07-final-checkpoint.json | Current manifest/READY identities updated for source fix 2fe8b40; package runtime provenance remains separately identified |
Evidence paths above are under `artifacts/fidelity/`. No tests, runtime, full GPU suite or wider audit were rerun by this follow-up verifier. The reviewed change is confined to bundled CLI cache behavior; no new native compatibility or gameplay claim follows. The user-selected UAT restart preserves all ten pending findings and agent-owned result reconciliation.
**Follow-up verdict:** the bounded bytecode defect is corrected by the inspected implementation and retained behavioral evidence. Overall status remains **human_needed**, score **29/42**, with **all ten human checks pending**. Fingerprint refreshed through the owner CLI over the prior 65 inputs plus the six evidence files above; prior proof is retained.
_Follow-up verified: 2026-11-14T21:58:58Z_
@@ -0,0 +1 @@
No external API integration: Phase 01 uses local files, native capture, offline media review and a loopback viewer; no hosted API or external SDK is added.
@@ -0,0 +1,35 @@
<!-- CONSUMED: final verification completed human_needed on2026-11-14. Current next action: $gsd-verify-work 1 and combined actual human session; historical interrupted-verifier notes below are superseded. -->
---
context: phase
phase: 01-reproducible-fidelity-baseline
plan: "07"
task: 3
total_tasks: 3
status: consumed
last_updated: "2026-11-13T22:26:46.798618+00:00"
---
# Final verification quota checkpoint
Quota guard explicitly requested pause at15%. Resume completed task01-07-03 and recovered fullsuite exit0 (782.049626s), then reviewed/fixed allfive source-integrity findings. Do NOT redo implementation or tests. Source commits through02d182f, review/coverage/security documentation71366e7. Fullsuite556Python/180fidelity,27Node,23observer,2HUD,51managedentrypoints,36GPUrenderedreceipts,zeroVulkanvalidationerrors,SDLdummychecks,539originalhashes. Latertooling-onlyfixes: all191fidelityregressions PASS43.355s; focused26scenario,23capture,29acceptance,27Node,18LinuxhostedPowerShell. All539originals unchanged. No runtime changes afterfullsuite; no need13minGPUrerun forcurrentPython/collector fixes.
Historicalreview5915128: CR01selected-vs-reviewedpath,CR02originalinventory/executablebinding,CR03copy-stateidentity,WR01viewerledgerprojection,WR02interruptedWindowsfinalization. Fixes5569bc2,bda35e5,6e5ee0b,548c97a,2608517,a821754. Independentre-reviewcaughtremaininghash-onlycopy-statebypass; RED48fca0d/GREEN02d182f requiresactual_checked_artifactwithrootinside_scenario_observation; callersupdated. Finalindependentre-reviewallfiveFIXED in01-REVIEW-VERIFY.md; dispositionopen0. Securityauditorfinal22/22mitigated, threats_open0 in01-SECURITY.md. Nyquistautomationcoveragevalidatedall15taskbindings; manualacceptanceopen;191fidelityaggregate43.355sec exceeds30secquicktargethonestly. UIreviewdisabledconfigfalse. No remainingknowncode/securityblockers.
Currentfreshfinalbundle dist/fidelity/phase01 has11001immutableentries. Currenthashes/readinessreceipt artifacts/fidelity/verification/01-07-final-checkpoint.json. readyexit0true,strictauditexit1 errors[] accepted0/120,10humanpending; logs artifacts/fidelity/01-review-fixes/readiness-final.json,acceptance-final.json,python-fidelity-final.log. Oldbundlespreserved phase01-pre-review-48100025 andphase01-pre-copy-artifact-7ceebcb3. ActualLinuxfailedpreflightimportedcurrentbundle/results/imported. Runtimepackage source446930d dirty/diff90cef956 unchanged; source/docscommitsmustnotrelabelitsidentity. Original/nativeWindows+DxWnd andphysicalLinuxvisible/audible/browserreviewremainonecombinedhuman session pending. Humanonlycollects/observes/returns; agent-ownedexactnormalizationmapping incheckpoint-session.md. No capture request issued yet because finalphaseverification/handoffpending.
Final typed verifier phase01_final_verification was dispatched at21%; quota15% interrupted it, instructedfinishonlyboundedhuman_neededreport/fingerprint thenreturn. It had readall7musthaves/summaries, checked25capabilities/33requirements/0unmapped/6groups/33rows,16/16decisioncoverage,40sourcefilesnoskip/debtscan. A mandatoryMVPgoalformatguard exposed existingROADMAPMode:mvp plainproseGoal. Rootauthorizedformat-only identicalintentuserstory and modifiedROADMAP.md uncommitted: As a tester, I want to reproduce identified original/port comparison scenarios, so that I understand exactly what the current reconstruction proves on each native platform. Validatorvalidtrue; no scope/successcriteriamodified. OneverifiercommandusedwrongunittestclassFidelityAcceptance (loadererror,correctclassAcceptanceTests); twoothernamedbehaviorcheckspassed; don'tmislabelthatcommandassuccess. Priorfulltargeted29passestablishactualcoverage.
NEXT: Reconcile currentverifier's 01-VERIFICATION.md and CLI verification.status; ifreport/fingerprintabsentfinishthat ONLY beforeanynewphase. FingerprintmustbeownerCLIgenerated, notmanual. Oncehuman_neededstatusvalid, persistUATfromnamedhumanitems, updateSTATE/consumedhandoffs, commitverifiedreport+goalmetadata+handoffdocs andpush verifiedsource/tooling toauthorizedGitea/main. Lastpushedhead remainsd18f551; later01-07/task3/reviewfix/auditcommits arelocalawaitingfinalverification. Preserveunrelatedtools.yaml. Do notadvancephase2orclaimPhase1accepted; allEVIDIDsPending0/120humanacceptance. No source changesuncommittedexceptROADMAPformatandpossiblynewverifierreport.
Nativeagents/sourcewritesallfinishedexceptverifierreportbeingclosed. Quota watcher runs and actual15%steeringworks. Noauto-resume; usermust $gsd-resume-workafterreset. Don'tspendquota rereadingmassiveGSDscriptbodies orrerunningfinished13minfullsuite. Existinglocalpackages/media/originalcopiesstaylocal, noCI/uploads. MaintracksGitea/main, scoped.gitwriteescalation; retainhistoricalhandoffsmarkconsumedratherthandelete (priorautomaticreviewrejecteddeletion).
## Required Reading
AGENTS.md,parentinstructions,HANDOFF.json,01-07SUMMARY,01-REVIEW-VERIFY,01-SECURITY,01-VALIDATION,and01-VERIFICATIONifpresent.
## Critical Anti-Patterns
| Pattern | Description | Severity | Prevention Mechanism |
|---|---|---|---|
| Redo completed tests | Fullsuiteand191fidelitychecksfinished | advisory | Reconcile savedlogs first; rerunonlyafternewchanges |
| False phase completion | Preparedmaterialsfailactualstrictacceptance0/120 | advisory | KeepEVIDPending andhuman_needed; owner verification.status beforeadvance |
## Infrastructure State
Testsfinished; verifierinterruptedatpause; reportreconciliationpending; localquota watcher running. No sourceworkeractive.
## Next Action
Inspect01-VERIFICATION.md and owner verification.status; finish report/fingerprint/UAT ifneeded, commit/pushverified01-07reviewedwork; neverredo task3/fulltests orautoapprovehumanacceptance.
@@ -0,0 +1,62 @@
# Evidence Walking Skeleton — Neutron GamePort
Phase 01 · Planned 2026-11-12 · No implementation or new runtime proof implied.
**As a** tester, **I want to** reproduce identified original and port comparison scenarios and inspect their evidence, **so that** I can understand exactly what the current reconstruction proves on each native platform.
This roadmap-derived story framing was supplied by the orchestrator. This is an established native game; its Phase 1 skeleton is the local evidence workflow, without unrelated database, account, routing or deployment scaffolding.
## Capability to prove end to end
Verify authoritative inventory → stage a generated copy → identify actual port bytes → collect/import one honestly classified receipt → inspect local review output. Actual original/native acceptance remains dependent on identified runtime captures and human review.
## Architectural contract
| Decision | Choice | Reason |
|---|---|---|
| Game runtime | Existing .NET 10, SDL3, Silk.NET.Vulkan/Vulkan 1.3+ | Preserve gameplay and current platform design |
| Evidence orchestration | Python stdlib CLI modules under tools/recon | Existing bounded local-tool patterns; no new packages |
| Persistence | Versioned JSON metadata and immutable local hashed artifacts | Actual disk read/write replaces an unrelated database requirement |
| Viewer | Plain HTML/CSS/native media plus testable ES module | Paired recordings, real time, exclusive audio |
| Local access | Contained read-only loopback viewer with GET/HEAD ranges | Browser seeking without hosted services or original-directory exposure |
| Native launch | Local shell / package-free PowerShell and cmd | User Windows PC does not need Python or SDK |
| Auth | No accounts; filesystem containment | A local evidence workflow, not a multi-user service |
| Original reference | Generated copy through actual identified DxWnd | Wrapper provenance remains separate from native port |
| Human gate | One complete session after all preparation | D-13–D-16; actual results required for acceptance |
| Reversibility | Versioned formats, retained raw artifacts, generated views | Shared contracts are costly to change but migrations remain bounded |
## Shared interfaces for parallel execution
Plan 01-01 owns fidelity_receipts.py and scenarios.json. Downstream plans consume those contracts and must not edit them in parallel. Any demonstrated contract correction returns to the owning plan/integrator before consumers continue.
Receipt schema_version 1 carries receipt_id/session_id/case_id, evidence_kind (static, inferred, component, managed, port_fixture, native_port, original_dxwnd, wine, cross_publish, synthetic), status (incomplete, failed, captured, reviewed), source/build/dirty/diff identity, executable/package/resource/original/launcher hashes, platform and observation method, invocation/cwd, wall/monotonic clocks, artifacts/derivatives, event markers with uncertainty, limitations and explicit acceptance. Reviewed status alone never implies full matrix acceptance. Normalized paths, finite times and actual platform/method compatibility are mandatory.
Scenario contract has eight fresh/retained × natural/skipped × ordinary/edge cells, each requiring a continuous lab→VR04→lab→outside run and focused observations. Every side/platform/cell is independently auditable. A retained case carries one session/continuation identity; fresh launches are independent. Original input annotations remain manually observed unless proven otherwise.
Capability export contract is schema_version, capabilities[] with id/group/requirement_ids/summary/verified_scope/differences/acceptance/source_links/scenario_ids/evidence/current/history/discrepancies. Evidence entries retain receipt identity, revision/content/platform/scope and supersedes/reason. Discrepancies carry impact blocking/disruptive/subtle/missing_verification and stable ID ties. Viewer plan 01-02 consumes this contract; ledger plan 01-03 exports it without shared file writes. The authoritative source is docs/evidence/capabilities.json, not generated Markdown or review JSON.
All CLI commands print counted summaries and nonzero invalid/strict-gap exits. `--allow-open` validates structure while visibly reporting pending acceptance; `--require-complete` cannot succeed without actual native/original and human evidence. New source paths, symbols, CLI names and generated artifacts are enumerated in each plan's “Artifacts this phase produces” paragraph.
## Execution graph and ownership
| Wave | Plans | Owned slice |
|---|---|---|
| 1 | 01-01 | Preservation, receipts and complete protocol |
| 2 | 01-02, 01-03, 01-04 | Viewer; ledger; passive port observer, with zero file overlap |
| 3 | 01-05 | Complete Windows checkpoint/collector |
| 4 | 01-06 | Native Linux capture and evidence |
| 5 | 01-07 | Readiness, one combined session, strict audit and status integration |
Every plan begins with a production tracer and then expands the same capability. There are 15 tasks; no task modifies more than five files. Estimates use measured calibration factor 1, sample_count 0, confidence low. No previous GSD summaries/verify commands or graph context exist.
## Walking-skeleton verification
- Real filesystem read/write and CLI receipt inspection are proven in 01-01.
- Actual local media interaction is wired in 01-02 and reviewed with real recordings in 01-07.
- Existing runtime input/event ownership is observed in 01-04, without changing movement/body algorithms.
- The documented full local workflow is package preparation → checkpoint ready → native capture → local import/review → strict audit. Exact commands and failure signals are in plans.
- Any missing original/native access or backstop evidence remains open/human_needed. Tools completion does not complete Phase 1 acceptance.
## Preserved boundaries for later phases
Movement/rotation/body policies, TSK ordering correction, normal landing bank, actor admission and lab/outside compatibility remain unchanged. Broader source-backed work may proceed only under the roadmap access exception while Phase 1 acceptance remains open. New gadgets, online runtime services, cloud CI and artifact uploads remain outside this phase.
+97
View File
@@ -0,0 +1,97 @@
# Reconstruction Architecture and Dependency Gates
**Project:** Neutron GamePort
**Researched:** 2026-11-12
**Scope:** Local repository research for the remaining full reconstruction; no binary analysis, source execution, implementation changes or new runtime verification.
## Recommendation
Extend the existing explicit scene composition and recovered component architecture. Preserve the distinction between a recovered algorithm, a synthetic original-component comparison, a live scene adapter and verified whole-game behavior. Complete movement and interacting lifetimes before expanding gameplay. The architecture already supports playable scenes; replacing it with a new engine or a speculative universal solver would discard the source-order contracts that existing evidence establishes.
This is a dependency analysis of current project reports and selected code, not independent certification of their original-binary findings. The generic CLI confidence classifier returns LOW for the `curated` provider label; it has no repository-evidence provider. Therefore the conclusions below state their documentary basis and limits rather than claiming a provider-certified HIGH confidence result.
## Existing Boundaries to Preserve
| Owner | Existing responsibility | Remaining architectural obligation |
|-------|-------------------------|-------------------------------------|
| `Program.Main` / `RenderSession` | Persistent native window/Vulkan device and session diagnostics; scene replacement | Keep resource replacement separate from original object retention; retain explicit cleanup and native ownership |
| `Program.Run` | Concrete scene composition, held input, fixed-step policy and callback scheduling | Extend actual per-object registry order, live mutation and phase ownership rather than treating grouped updates as original semantics |
| `LabSimulation` / `PlayerSceneBinding` | Player body/controller/fire/control boundaries; fresh versus retained input ordering; script and vehicle bridges | Preserve independent control, body and effect eligibility, retained scalar ownership and authored transform publications |
| `OriginalBodyPhysics`, static/dynamic/pair/normal components | Bounded recovered numeric and callback contracts | Admit only actor states whose membership, callbacks, live reads and helper lifetime have been recovered |
| `SceneDirector` / interactions / tasks | Script actions, task broadcasts, cutscene control, contacts and transitions | Recover remaining real derived callbacks, action acceptance/completion and complete progression consumers |
| `Assets` / offline extractors | Original-format decoding and prepared render/audio resources | Preserve source identity/material metadata, explicit missing resources and immutable originals |
| Application visuals / renderer | Morphs, sprites, UI, camera projection and Vulkan resources | Replace named approximations with source-backed transforms, playback, materials, layers and render states |
| `SceneAudio` / `SdlAudio` | Scene music/speech/effects and native stream ownership | Separate original handle/bank/software clocks from SDL transport; complete positional/lifecycle policies |
Source: [codebase architecture](../codebase/ARCHITECTURE.md), [coverage](../../docs/checkpoint/coverage.md), [implementation ledger](../../docs/checkpoint/implementation-plan.md).
## Physical Scene Admission Is the Immediate Gate
The physical list and the ordinary object registry have separate ownership. Common registration repeats transform/zero/Init work and appends without identity deduplication; Jimmy's outer `49E` guard encloses the whole bridge. A scene-wide two-pass Init/PostLoad abstraction or a snapshot of registry membership would disagree with the recorded same-pass appended-child behavior. Serialized class counts and vtable identities cannot be treated as actual active-body counts.
The registration report inventories all 72 VR04 records/13 interfaces and compares 12 original-component registration/loader cases. Generated-helper edges are catalogued, but constructor/re-entry, conditional creation, removal, activation and retained LOAD/RETURN membership still need full ownership traces. The next integration must recover the actual ordered participants, not simply append every serialized actor or infer eligibility from its presence in the GAM file.
Normal response is also distinct from pair enter/stay/leave notification. Thirty original/C# normal-contact snapshots establish inherited response, Jimmy's ordinary bypass, live accessor order and bounded derived endpoints. Soldier mode10's complete `174` call is only a recorded endpoint; its RNG/action/target policy remains open. The grappler-related Jimmy `204` endpoint is likewise not a recovered universal cleanup policy.
The dynamic query/reclip components already compare empty and populated synthetic contexts, but sequential fixed actors are not a live mutable dispatcher. Post-callback inhibition, geometry permission, radius and `42C` reads must stay live; callback root mutation can be overwritten by final query-local publication. Do not cache constructor values or insert an unevidenced context reset. Preserve old nearest/hit/last-polygon state where recovered.
**Integration order:** real derived responses and game/task consumers → helper activation/removal/re-entry and fresh/retained physical order → shared mutable query context/accessors → bounded response adapter for explicitly supported VR04 states → route and platform verification → broader special-material actors and lab/outside admission.
Sources: [registration](../../docs/checkpoint/physical-registration.md), [helpers](../../docs/checkpoint/vr04-generated-bodies.md), [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [dynamic context](../../docs/checkpoint/dynamic-context.md), [populated reclip](../../docs/checkpoint/dynamic-reclip.md), [pair lifecycle](../../docs/checkpoint/pair-lifecycle.md).
## Camera, Animation and Retained State
- **Shared camera state:** The source report establishes a shared viewport eye read by both scripted camera writes and follow input, strict DEFAULT snapping only above distance1000, and aim computed from the pre-update eye. Current `Program.cs` selects director versus simulation cameras and `LabSimulation` retains its own `CameraEye`; partial gadget bridges do not establish complete shared viewport semantics. Model the owner explicitly after validating the remaining callers. Keep projection, layer masks/fog, noclip and modern orbit policy separate.
- **Animation:** Existing morph assets and deterministic visual checks do not establish the original action acceptance, playback clock, repeat/end events or interruption policy. Recover these across jump/land/STOP/talk/skip/control return before relying on them to drive actor transitions or progression. The port's fixed60Hz simulation policy must not become an assumed oracle for every original animation or script clock.
- **Retained scene state:** Ordinary LOAD/RETURN, TSK loading, debug reset and fresh direct-GAM startup are different paths. Preserve original tasks/items/root state separately from session diagnostics and scene GPU/audio recreation. Current bounded retained player scalars are not permission to carry arbitrary helpers, timers, modes or handles through every transition.
- **Sound clocks:** Original software elapsed/duration, strict completion boundaries, repeat and bank ownership govern cutscene behavior; transport queue-empty and dummy-stream success prove narrower properties. Integrate source channel state before broad playback-dependent script completion.
Sources: [camera handoff](../../docs/checkpoint/camera-handoff.md), [coverage](../../docs/checkpoint/coverage.md), [implementation ledger C5–C8](../../docs/checkpoint/implementation-plan.md), [next-work plan](../../docs/checkpoint/next-work-plan.md).
## Solved Checkpoints Versus Remaining Work
| Reuse as established bounded work | Still required |
|----------------------------------|----------------|
| C1 pre-task objective notification and C2 per-actor Carl task override | Other real derived task/contact policies and full progression |
| Controlled player body-before-callback order, fresh/retained input distinction | Broader object scheduler, mutable helpers and actor-specific eligibility |
| TSK-backed first-story retained Jimmy ordering correction; first-neutral/300-idle regression | Whole-original Carl runtime reference and native Windows comparison; broader handoffs |
| Static camera ray/FIFO/wall-first adapter and per-level far limits | Complete shared eye/aim handoff, special follow branches and visual comparison |
| VR04 ordinary source static body and bounded body publication/mode components | Dynamic registry/response, successful Jimmy hazards/climbs, lab/outside source admission |
| Dynamic query and populated reclip component comparisons | Real actors/accessors and shared ordered scene context |
| Bounded gadget/vehicle scenes and retained scalar bridges | Broader levels, special interactions, helper cleanup and arbitrary save/load lifetimes |
Historical prose in `next-work-plan.md` still says the Carl correction has not begun; later updates and `docs/tasks.md` establish that the source startup-order classification and port correction are already implemented. Do not reopen that defect as untouched work or add an invented leveling reset. Similarly, the old C4 kernel-only checkpoint has been superseded by ordinary-body integration and later component reports, while its broader admission gate remains.
## Dependency Order for the Full Reconstruction
1. **Close the movement/route checkpoint:** real callbacks, helper lifetime/physical order, shared reclip, animation/control/camera handoffs and an integrated lab→VR04→lab→outside regression. Retain the existing playable baseline until each replacement gate closes.
2. **Complete shared actor/gameplay contracts:** source damage/hazards, AI/action/RNG, interactions, gadgets/vehicles and their activation/cleanup. Derive scope from original resources and consumers; existing bounded scenes are reusable implementations, not proof of universal support.
3. **Complete original progression and persistence:** load/RETURN and task/item state, every reachable level/mission, authored scripts and win/loss paths. Add full menu/configuration/save UI once their state ownership is recovered. Level inspection/rendering is insufficient.
4. **Complete presentation and audio contracts:** animation/pivots, material/light/fog/alpha/culling/layers, shared camera and UI; bank/handle clocks, positional mixing and effects. Independent static research can run alongside earlier work, but live integration must respect gameplay and lifetime dependencies.
5. **Verify complete journeys and release packages:** original comparison across representative and full-game routes, native Linux and native Windows gameplay/input/audio/rendering, offline package resource/provenance checks and reproducible discrepancy triage.
These are dependency groups, not a demand to defer all rendering/audio work until the end. Resolve a presentation or sound contract earlier when it blocks a verified gameplay route. Keep the roadmap within the selected standard granularity while allowing phase plans to subdivide evidence gates.
## Verification Architecture
For each admitted capability, maintain an evidence chain: authoritative binary/asset identity → addresses/offsets and REA Evidence or documented provider gap → bounded source contract/probe → managed regression → live scene replay → native platform/package result → whole-original comparison where observable. Preserve complete snapshots and hashes locally. A successful level render, synthetic callback endpoint or cross-publish closes only its named gate.
Use deterministic source/component checks for phase and numeric differences; GPU readbacks for pose/camera/material differences; actual SDL input for integrated ownership and controls; physical/native audio checks for audible behavior; original-format round-trips and live reload for persistence. Define a discrepancy ledger with original/port scenario, first divergence, evidence, fix and remaining uncertainty. Never certify full fidelity from matching a few constants or rendered scenes.
Both packages must identify a clean verified runtime commit and contain matching original/prepared resources. Execute from a standalone directory without source/SDK/development-library paths. Reverify original hashes. Windows cross-publish, Wine compatibility, historical user reports and new native Windows execution remain separate receipts. Push only source/tools/docs to approved Gitea; original assets, generated traces and packages stay local.
## Open Questions for Phase Research
- Complete soldier RNG/action/target response and real enter/stay/leave task effects.
- Constructor-only/conditional helper activation, cleanup mutation and retained physical ordering.
- General live/reentrant scalar getter and shared context ownership beyond fixed synthetic probes.
- Successful Jimmy FENCE/LADDER/hazard paths and multi-frame mode/animation effects.
- Complete shared viewport handoff, source aim quantization and special follow branches.
- Playback clocks/end callbacks, original sound bank lifecycle and full save/menu callers.
- A usable whole-original reference environment and current native Windows verification.
## Sources and Limits
Primary local planning inputs: [PROJECT.md](../PROJECT.md), [architecture map](../codebase/ARCHITECTURE.md), [tasks](../../docs/tasks.md), [coverage](../../docs/checkpoint/coverage.md), [implementation ledger](../../docs/checkpoint/implementation-plan.md), and [next-work plan](../../docs/checkpoint/next-work-plan.md). Selected current code checks: `src/GamePort/Program.cs` camera selection and `src/GamePort/Game/LabSimulation.cs` camera ownership. Specialized evidence reports are linked beside their findings above.
No original files were modified or executed. No current build, platform execution or original-runtime comparison was performed for this report. Architectural recommendations are inference from documented contracts; exact remaining original behavior must be recovered in phase-specific investigation.
+64
View File
@@ -0,0 +1,64 @@
# Remaining Reconstruction Feature Landscape
**Project:** Neutron GamePort
**Reviewed:** 2026-11-12
**Scope:** Remaining full reconstruction, with original fidelity governing scope and acceptance.
## Evidence and interpretation
This is a local specification/report review, not a new binary investigation, build, runtime capture or independent validation of historical receipts. The user's full-reconstruction and maximum-accuracy requirements are explicit. Capability and gap statements below are attributed to repository reports; their exact revision/platform/fixture boundaries remain binding. Older narratives in long reports do not supersede later completion entries. The GSD `classify-confidence --provider local --verified` seam returned LOW because this provider has no curated classification; that label applies to this review's provider classification, not a downgrade of separately recorded original instruction/probe evidence.
Read the current [project context](../PROJECT.md), [current concerns](../codebase/CONCERNS.md), [progress](../../docs/progress.md), [tasks](../../docs/tasks.md), [coverage ledger](../../docs/checkpoint/coverage.md), and [authoritative specification](../../../prompt.MD) together. Treat all remaining-original functionality as required; this is not a market-feature selection exercise.
## Required feature categories
| Category | Existing bounded capability | Remaining reconstruction target | Complexity / acceptance evidence |
|---|---|---|---|
| Jimmy controls and movement | Recovered ground/air acceleration, facing, jump/hold/gravity components and fresh/retained order; native Linux input routes | Close remaining body/contact, mode/facing persistence and animation interactions; preserve original quirks and significant float stores; establish original timing rather than assuming fixed 60 Hz proves parity | High. Original-derived full-state trajectories plus original/port input replays at differing presentation rates; no speed-up from refresh rate |
| Physical world and contacts | Sphere/static kernels, bounded source bodies, ordered pair and normal-response components; lab/outside compatibility capsule | Actual physical registry membership/activation/removal, retained helpers, callback mutations, shared dynamic/static reclip, special hazard/FENCE/LADDER paths, complete derived actor policies | Very high. Complete ordered state/event traces, successful special-contact cases and bounded live scene admission after dependencies close |
| Animation, scripts and control | Original morph assets; CAM/MCA/AI lab chains, natural/skip and TSK story-entry correction | Full action acceptance, animation timing/completion/interruption and script dispatch across characters/scenes; control and body/effect clocks remain independent | High. Compare original action/event/pose sequences, including banked entry, skip/natural return, held input and repeated transitions |
| Cameras and original input | Authored and follow cameras, bounded static camera collision, corrected orbit; SDL keyboard/window handling | Shared scripted/follow viewport state and DEFAULT handoff, full clipping/state policy, source-supported mouse/relative/analog behavior and controller behavior if evidenced | High. Compare eye/target/projection/input state through first resumed frame; verify focus, fullscreen, resize and high-DPI mapping without distorted presentation |
| Actors, enemies and combat | Lab props/patrol subset, source-body components, bounded target/soldier responses | Complete actual class behaviors, sensing, follow, action selection, RNG-dependent policies, damage/health/death/recovery, combat effects and any original difficulty/win/loss rules | Very high. Real derived responses and complete interaction side effects; generic patrol or synthetic callback injection does not prove AI parity |
| Gadgets, vehicles and inventory | Shared selection/energy, ray/jetpack, Invisible, Bubble VR01, Baseball VR07, Rocketship VR02, Grappler VR08 and Scooter VR05/LEV1 | Complete remaining gadgets including Remote; all original intended consumers/scenes, dynamic interactions, mission/hazard policies, retained LOAD/helper/save lifetime and supported input modes | Very high. Inventory earned through normal progression and each intended use exercised without F1 grants or fixture-only shortcuts; current bounded live features remain preserved |
| Levels, tasks and progression | All 35 supplied GAMs parse; 33 have scene geometry; lab → practice → RETURN → outside route and task/score effects | Original reachable campaign, class-specific triggers/objectives/collectibles/NPCs, level-specific mechanics, entrances/exits and final progression outcomes | Very high. Fresh NewGame-to-ending route evidence, intermediate checkpoints and branch/optional content matrix; direct scene selection is not reachability |
| Menus, HUD and configuration | Objective/practice/gadget art and bounded logic; user-authorized modern diagnostics; native window/session handling | Original player-facing frontend, options/configuration persistence, complete HUD/objective flags, cursors/highlights, source-supported input and pause transitions | High. Original screens and modal/input/timer behavior compared; debug menus are test tools, not original frontend completion |
| Save/load and retained state | All 12 supplied TSKs byte-round-trip; tasks/items/RETURN departure-root CLI and carried snapshots | Complete runtime saving/loading and repeated callback semantics, unknown field meanings needed by gameplay, menu integration, arbitrary supported resume, correct fresh/retained/reset ownership | High. Save before/after meaningful interactions and reload to equivalent gameplay state while preserving unknown/raw fields; TSK round-trip alone is insufficient |
| Geometry, animation art and rendering | Original scene/models/morphs/textures, Vulkan material support and GPU/native Linux checks | Original fixed-function equivalents, per-layer lighting/fog/blend/depth/cull/texture states, sprite pivots, full actor root/hierarchy and morph playback fidelity | High. Matched-camera original/port captures, dynamic-state comparisons and documented differences; no pixel-perfect claim from port-only readbacks |
| Audio | Independent music/speech/effects streams, cutscene music stop/restart, default pickup/button/door sounds, some vehicle positional frequency | Full contextual banks, source channel/voice allocation and clocks, volume/pan/attenuation, loops, jetpack and remaining actor effects, encoded resource playback and physical output | High. Matched event/time/listener captures plus audible Linux/Windows verification; dummy-stream lifecycle tests remain narrower |
| Cross-platform release | Shared .NET 10/Vulkan 1.3+/SDL3 runtime; local Linux/Windows publishes and package provenance | Current complete-game packages validated natively on both targets, startup/input/audio/window/resource cleanup and practical driver coverage; offline runtime and reproducible local packaging | High. Standalone native Linux and Windows runs of the same clean source checkpoint and resources; cross-publish/Wine are separate preliminary evidence |
| Original comparison and preservation | 539-original manifest, byte guards, isolated original probes and port regression fixtures | Working copied-original reference captures, systematic discrepancy register, per-system tolerance rationale, integrated whole-game comparison and verified original hashes | Very high. Identify exact reference/port revision, route, input, clock, state and platform; preserve raw evidence locally and distinguish inference from runtime observation |
## Specific boundaries that must shape requirements
- The Carl first-neutral-tick bank has a supported TSK story-entry ordering correction. Preserve it and fresh direct-scene order. Ordinary landing residual bank is user-confirmed original behavior; do not introduce universal leveling. Whole-original Carl comparison remains open. See [menu/player lifetime](../../docs/gameplay/main-menu-player-lifetime.md) and [movement stabilization](../../docs/gameplay/jimmy-movement-stabilization.md).
- Pair/normal components are not a complete live physical world. Soldier complete174 RNG/action effects, helper cleanup/activation across LOAD/RETURN and real enter/stay/leave task consumers remain dependencies. Keep Jimmy ordinary374 separate from inherited reflection and read callback-mutated fields at original times. See [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [registration](../../docs/checkpoint/physical-registration.md), [populated reclip](../../docs/checkpoint/dynamic-reclip.md).
- The independent pickup checkpoint is not the TSK transition-departure root. Save-field preservation must not invent respawn behavior. See [save format](../../docs/save-format.md) and [runtime checkpoint](../../docs/analysis/runtime-checkpoint.md).
- Level3B and Level3E GAMs exist; their OMT archives are absent. Normal gameplay reachability is unverified, so do not declare missing files a campaign blocker, substitute geometry or request files merely from registry membership. Resolve actual reachable content through evidence. See [level-resource mapping](../../docs/analysis/level-resource-mapping.md).
- Some older task lines still call already-live Grappler/Scooter unimplemented. Use [Grappler live](../../docs/gameplay/grappler-live.md), [Scooter live](../../docs/gameplay/scooter-live.md), [Rocketship live](../../docs/gameplay/rocketship-live.md) and [Baseball implementation](../../docs/gameplay/baseball-implementation.md) as their bounded capability records.
- Bird1/id162 retains MPEG Layer3-in-RIFF data and is unsupported by the documented SDL WAV path; do not silently substitute audio. Bank/channel/attenuation policy remains incomplete. See [sound effects](../../docs/analysis/sound-effects.md).
## Dependency order for roadmap construction
1. Establish a usable original-reference comparison route and evidence/discrepancy matrix early. Continue source-backed work when a runtime reference is unavailable, but preserve the outstanding fidelity gate.
2. Finish movement/contact/animation/camera and retained registry/helper contracts; prove the lab → VR04 → lab → outside route as one interacting system before new gameplay expansion.
3. Expand real actor responses, hazards/combat and gadget consumers on that foundation, preserving current bounded features and explicit scene admission.
4. Complete campaign tasks, level-specific systems, frontend and save/resume in playable slices. Unknown reachability, task consumers and saved state require phase-specific recovery.
5. Complete visual/audio behavior alongside supported gameplay slices; do not defer all comparison until release, because presentation clocks and camera/input ownership affect gameplay.
6. Validate the full campaign and supported optional content against original evidence on native Linux and native Windows, then produce local clean packages and a discrepancy audit.
This order is an integration recommendation, not a claim that every system must be fully recovered before any bounded change. Rendering/audio investigations can proceed independently with exclusive ownership; gameplay expansion remains behind the current movement gate.
## Differentiators and explicit exclusions
No new competitive features are proposed. Fidelity to the original is the defining value. Preserve existing user-authorized diagnostics and modern platform support, but keep them separate from original gameplay claims. Exclude invented story/mechanics, replacement movement tuning, PBR/visual redesign, online services, telemetry, cloud CI, and original/generated-package uploads.
## Completion targets
- One faithful playable scene is an intermediate milestone, followed by all original reachable content and progression; loading all assets is not a playable-game criterion.
- Every feature has separate recovery, implementation, component-test, integrated-runtime and original-comparison status, with paths to evidence and known approximations.
- Expected results come from authoritative original instructions/data/execution and working-original observation where available; port outputs cannot be their own fidelity oracle.
- Native Linux and native Windows packages identify the same verified source/resources; original hashes remain unchanged; unresolved discrepancies remain visible and prevent unsupported full-fidelity claims.
## Sources
All source links above are local project evidence. Additional integration references: [next-work plan](../../docs/checkpoint/next-work-plan.md), [implementation plan](../../docs/checkpoint/implementation-plan.md), [compatibility](../../docs/compatibility.md), [presentation/UI](../../docs/presentation-and-ui.md), [graphics recovery](../../docs/analysis/graphics.md), [rendering](../../docs/rendering.md). Rendering and task reports contain historical entries; consult current progress and feature-specific completion reports before treating an older gap as current.
+116
View File
@@ -0,0 +1,116 @@
# Reconstruction Pitfalls
**Project:** Neutron GamePort
**Reviewed:** 2026-11-12
**Scope:** Remaining full reconstruction; local documentation review only. No new original-binary investigation, execution, build or runtime comparison was performed.
## Evidence and confidence
The risks below are cross-referenced repository findings, not externally researched ecosystem claims. Their supporting source/component observations have the bounds specified in the linked reports; their implications for phase ordering are planning inferences. Whole-game accuracy is unverified. The generic `classify-confidence --provider curated --verified` seam returned LOW for this local-source provider; that label must not be mistaken for a new certification of the original experiments. Use the underlying receipts and their explicit execution scope when deciding admission.
## Critical pitfalls
### 1. Promoting component parity into live gameplay fidelity
**Failure:** A matching pair, normal-response or reclip fixture is wired into every scene as though actual actors, registry membership and task effects were recovered.
**Warning signs:** Completion claims cite only fixture counts; synthetic callback endpoints are described as real soldier/Jimmy policies; serialized GAM records become the active physical-body count.
**Prevention:** Require actual class construction, activation, physical order, derived response, enter/stay/leave consumers and shared context before expanding each live adapter. Keep lab/outside capsule compatibility until its replacement dependencies close. Compare complete callback events, flags and state snapshots, not just final positions. Soldier complete174 and Jimmy204 remain record-only endpoints in the normal-contact report.
**Phase implication:** Physical lifecycle and derived callbacks precede broad actor, enemy and gadget collision expansion.
Sources: [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [physical registration](../../docs/checkpoint/physical-registration.md), [pair lifecycle](../../docs/checkpoint/pair-lifecycle.md), [coverage](../../docs/checkpoint/coverage.md).
### 2. Fixing symptoms by changing legitimate original movement
**Failure:** A universal angle reset, added damping or imported tuned movement masks an ownership/scheduling divergence and removes original behavior.
**Warning signs:** Ordinary landing bank is called a bug; fresh direct-scene and TSK-backed retained entry are given the same input order; JN-Engine's tuned movement becomes the oracle.
**Prevention:** Preserve current movement and the successful first-story TSK retained-input correction. Trace the first divergent owner and caller phase before changing arithmetic. Recheck neutral return, sustained idle, held input, both turn directions, natural/skip completion and repeated scenes. External decompiler indexes provide leads only.
**Phase implication:** Movement, control/animation ownership and route handoffs remain the first implementation checkpoint. The Carl initialization correction is existing work, not an untouched future fix.
Sources: [menu/player lifetime](../../docs/gameplay/main-menu-player-lifetime.md), [movement stabilization](../../docs/gameplay/jimmy-movement-stabilization.md), [next-work plan updates](../../docs/checkpoint/next-work-plan.md).
### 3. Flattening physical registration and retained lifetime
**Failure:** Deduplication, snapshot traversal or a generic reset silently changes ordering across fresh load, retained LOAD and RETURN.
**Warning signs:** Constructor registrations are treated as final active membership; Init and PostLoad run as two global passes; setting a flag is treated as deleting a node; helper reuse/cleanup is assumed from a constructor edge.
**Prevention:** Keep ordinary registry and physical list independent. Common registration can append an existing pointer; Jimmy's outer guard is separate. Preserve Init-before-parent-append and per-object Init/PostLoad traversal that can visit new tails. Recover actual helper removal, activation and re-entry before representing retained lists. Compare complete ordered lists across scene transitions.
**Phase implication:** Lifecycle closure must precede arbitrary retained saves, general dynamic contacts and full-level progression admission.
Sources: [registration](../../docs/checkpoint/physical-registration.md), [generated helpers](../../docs/checkpoint/vr04-generated-bodies.md), [dynamic context](../../docs/checkpoint/dynamic-context.md).
### 4. Caching values across source callbacks
**Failure:** A refactor snapshots radius, inhibition, geometry permission or velocity before callbacks, changing subsequent reclip and final publication.
**Warning signs:** Accessors become constructor constants; a callback's root edit is assumed to survive final local-root publication; collision mode and class-specific controller state share an enum or layout.
**Prevention:** Preserve source getter order and independent fields. Test callbacks that mutate radius, flags, Y velocity and roots, plus retained old-hit/last-polygon behavior. Distinguish XYZ writes from full XYZW setters. Do not apply inherited reflection to Jimmy ordinary374, which takes its own material-policy path.
**Phase implication:** Response adapters require live getter and ownership contracts before integration.
Sources: [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [populated reclip](../../docs/checkpoint/dynamic-reclip.md).
### 5. Treating mathematically equivalent arithmetic as source equivalent
**Failure:** Double promotion, normalization changes, reordered operations, triangle winding fixes or a faster broadphase alter strict branches, ties and accumulated state.
**Warning signs:** Double intermediates are called an x87 emulator; only root tolerance is checked; duplicated source cell visits are removed; heading wraps or unclamped damping are normalized to conventional behavior.
**Prevention:** Preserve evidenced float-store boundaries, kernel A,C,B winding, strict comparisons and traversal order. Record the first exact differing field and kernel argument. Widening precision or optimizing needs new differential evidence; degenerate inputs outside the bounded contract remain explicit unknowns.
**Phase implication:** Preserve numeric probes throughout collision, actors and rendering-transform work; optimize after equivalence and measured need.
Sources: [dynamic reclip](../../docs/checkpoint/dynamic-reclip.md), [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [codebase concerns](../codebase/CONCERNS.md).
### 6. Mistaking successful rendering or audio transport for original presentation
**Failure:** Zero Vulkan errors, identical port screenshots or SDL dummy-stream success are reported as visual/audible parity.
**Warning signs:** Merged far-plane policy implies per-layer fog/clipping fidelity; queue-empty replaces the original software sound clock; fixed 60 Hz is called recovered original scheduling; a correct transform kernel implies exact final OMT visual decomposition.
**Prevention:** Compare original reference frames and sound intervals at identified states. Keep lighting/fog/material/blend/culling, sprite/pivot/decomposition, morph clocks, camera handoff, sound-bank/channel duration/attenuation and physical listening as separate targets. Retain device-independent numeric and transport checks, but report their narrower guarantees.
**Phase implication:** Presentation and audio need source-specific recovery and integrated comparisons; start reference acquisition early rather than leaving all fidelity checks until release.
Sources: [coverage](../../docs/checkpoint/coverage.md), [compatibility](../../docs/compatibility.md), [air bridge](../../docs/gameplay/jimmy-air-bridge.md).
### 7. Shipping a different revision from the one verified
**Failure:** Current source, historical GPU tests and an older local package are merged into one completion claim; Wine is presented as native Windows verification.
**Warning signs:** No exact package identity; user Windows reports attributed to an agent-run current build; startup black frames treated as a playable original reference; source-only changes inherit old SDL coverage.
**Prevention:** Bind every receipt to source commit, package provenance, resource hashes, platform, scenario and validation setting. Run the same integrated route/control/window/audio checks on clean standalone Linux and native Windows packages. Keep original-component Wine32, port Wine64, whole-original reference and native Windows evidence separate. A blocked original runtime comparison remains an open release obligation.
**Phase implication:** Reference/native Windows access is an early dependency; final full-game acceptance requires current integrated evidence, not a cross-publish alone.
Sources: [progress](../../docs/progress.md), [compatibility](../../docs/compatibility.md), [codebase concerns](../codebase/CONCERNS.md).
## Further risks during full reconstruction
| Risk | Warning sign | Prevention / roadmap consequence |
|------|--------------|----------------------------------|
| Asset inventory mistaken for playable coverage | All GAMs parse, therefore all levels are called complete | Track each original route, mechanic, actor and script consumer through implementation and runtime verification. |
| Unsupported missing-content conclusion | Level3B/E GAMs described as missing, or absent OMTs called a proven fatal normal-game blocker | GAMs exist; distinguish their referenced absent archives from proven reachability. Investigate hardcoded/serialized routes without inventing substitutes. See [resource evidence](../../docs/analysis/level-resource-mapping.md). |
| Save round-trip mistaken for load fidelity | Binary equality substitutes for repeated task/entity callbacks and retained scene ownership | Recover full original load UI, callback multiplicity, placement and helper lifetimes; test loading at real progression boundaries. See [coverage SAVE](../../docs/checkpoint/coverage.md). |
| Invalid copied-code evidence accepted | Partial captures or relocation scans are counted as source behavior | Preserve full REA replies, source/probe hashes, reviewed operand mappings and completion markers; exclude invalid captures. Provider errors remain errors. See [normal contacts](../../docs/checkpoint/actor-normal-contacts.md). |
| Original evidence altered or published | Extraction/probes target Original, or package files enter source commits | Generated copies/output only; verify all 539 baseline hashes, stage explicit source/docs paths and keep assets/packages local. |
| Old narratives override newer receipts | A solved Carl bug is reopened from an older section | Follow dated continuation updates and exact receipt scope; reconcile current reports before planning changes. |
## Phase-specific gates
1. **Core movement/lifetimes:** preserve baseline, close real response/helper/state owners and validate lab → VR04 → lab → outside before expansion.
2. **Actors/gadgets/combat:** recover actual callbacks, RNG/action policies, activation and physical order before broader admission; bounded training-scene behavior is not full-game coverage.
3. **Progression/save/menu:** exercise complete authored routes, fresh/load/RETURN paths and task callbacks; do not equate parsable resources with playable progression.
4. **Rendering/audio/UI:** obtain observable original references, then address named state/clock/transform differences with isolated and integrated evidence.
5. **Release:** identify exact clean builds and resource manifests; verify full original content and native Linux/Windows behavior, with no unverified fidelity claims hidden by successful packaging.
These gates are dependency recommendations inferred from current findings. They are not new binary findings or implementation approvals.
+59
View File
@@ -0,0 +1,59 @@
# Technology and Verification Foundation
**Project:** Neutron GamePort remaining full reconstruction
**Researched:** 2026-11-12
**Method:** Local specification, source/configuration cross-checks and existing verification reports. No dependency updates, new runtime tests or binary analysis were performed.
## Keep the Existing Stack
| Component | Repository version/requirement | Role and decision |
|-----------|-------------------------------|-------------------|
| C# / .NET | `net10.0`; SDK selector 10.0.100 with latestFeature roll-forward; bootstrap SDK 10.0.402 | Retain one shared Linux/Windows x64 executable. Do not plan a foundation rewrite. |
| Silk.NET.Vulkan / KHR / EXT | 2.23.0 | Existing Vulkan bindings, pinned in the project and lockfile. |
| Vulkan | 1.3 minimum | Existing renderer requests Version13 and rejects older devices. Host driver/loader remains required even with self-contained packages. |
| SDL3 | 3.4.2 in bootstrap | Existing handwritten P/Invoke for native window, input, surface and audio. Retain the shared platform boundary. |
| GLSL / SPIR-V tools | Local shader compiler and validator | Preserve original fixed-function behavior through explicit Vulkan shaders/states rather than modernizing the look. |
| Python / Bash / C | Local tooling; documented Python 3.12 | Offline preparation, repeatable local scripts and isolated original-component probes. None is a packaged gameplay runtime dependency. |
| REA / Ghidra / full JDK | Existing launcher; documented Ghidra 12.1.4 / Java 21 paths | Required investigation route for original binaries. Check actual local launcher/tool identities when producing new evidence. |
| Wine | Documented 11.0 | Isolated original/component investigation and preliminary Windows compatibility only. It cannot substitute for native Windows verification. |
Versions describe this repository, not upstream latest releases or newly verified installations. `docs/dependencies.md` records runtime pack 10.0.13; confirm generated publish runtime metadata for each package rather than deriving runtime version from SDK version.
Sources: [project](../../GamePort.csproj), [SDK selection](../../global.json), [bootstrap](../../scripts/bootstrap.sh), [dependencies](../../docs/dependencies.md), [renderer](../../src/GamePort/Rendering/Vulkan/VulkanRenderer.cs), [REA launcher](../../scripts/rea.sh).
## Existing Local Delivery and Evidence Facilities
- `scripts/env.sh` selects local SDK/cache/native tools and disables .NET CLI telemetry. NuGet dependencies are locked in `packages.lock.json`.
- `scripts/test.sh` combines Python parser/source regressions, managed algorithm programs, Vulkan rendering and SDL dummy-audio checks. Tests must retain their bounded claims: exact component output does not establish original full-game scheduling or visuals.
- `scripts/build-linux.sh`, `scripts/build-windows.sh` and `scripts/package.sh` already implement local self-contained publishing and original-derived asset assembly. Packages include SDL3, shaders, resources, licenses and source provenance. They remain local artifacts.
- Original preservation uses `tools/recon/inventory.py` with `docs/original-manifest.json`. Existing reports record 539 hashes; run the verifier at actual implementation/package checkpoints.
- Runtime has no required hosted service, account system, remote database or telemetry. Gitea is solely the authorized source-control destination for completed verified source/tools/docs.
Sources: [integration map](../codebase/INTEGRATIONS.md), [test entry](../../scripts/test.sh), [packaging](../../scripts/package.sh), [project rules](../../AGENTS.md).
## Remaining Capability Gaps
| Gap | Existing evidence | Required closure and roadmap implication |
|-----|-------------------|------------------------------------------|
| Whole-original reference execution | Compatibility reports record isolated Wine windows with unusable original GL/Vulkan rendering; component execution is available | Establish a working local original reference environment/capture path early. Use a generated copy, local Windows/legacy VM or other supported local investigation path. Feasibility of a particular environment is unverified. Do not silently promote component probes to whole-game reference evidence. |
| Native Windows verification | Windows x64 cross-publish, preliminary Wine checks and bounded user reports exist | Plan repeatable native Windows input, audio, resize, driver and integrated progression checks. Record revision, device/environment and scenario results. A new cross-publish does not refresh prior Windows runtime evidence. |
| Audible and positional audio comparison | Dummy streams verify consumption/lifecycle; broader speakers/latency/attenuation verification remains open | Compare effects/bank selection, spatial behavior, timing and actual listening output against the original on both native platforms. SDL API availability alone does not resolve policy. |
| Rendering equivalence | Native Linux/llvmpipe GPU checks and readbacks exist | Add reference-matched camera/scene captures and per-state discrepancy review for materials, lighting, fog, alpha, pivots and animation. Zero Vulkan validation errors proves API correctness, not fidelity. |
| Timing and retained system composition | Numerous copied-original component cases; fixed 60 Hz port policy; source ordering corrections already integrated | Recover remaining shared scheduling, actor lifetime and callback contracts before broad solver admission. Compare event/state traces as well as pixels and final positions. |
| Full content and release coverage | 35 GAMs catalogued, 33 with matching geometry; local packages contain substantial playable content | Audit all reachable original routes and resources. Missing Level3B/E geometry is recorded but normal gameplay use is unverified: it is not an established blocker or permission to fabricate replacement assets. |
Sources: [compatibility ledger](../../docs/compatibility.md), [current progress](../../docs/progress.md), [next-work plan](../../docs/checkpoint/next-work-plan.md), [authoritative specification](../../../prompt.MD).
## Roadmap Decisions
1. Treat the existing shared renderer/platform/build system as the foundation. Extend focused recovered modules and local checks instead of reselecting engines or libraries.
2. Establish the original-reference and native-platform comparison matrix at the start and grow it with each gameplay slice; reserve final cross-platform acceptance for complete routes and clean packages.
3. Keep the current Jimmy stabilization and collision admission gates ahead of gameplay expansion. Additional tooling should answer a named unresolved source/runtime question, not become an independent infrastructure rewrite.
4. Preserve generated extraction, original-code probes, snapshots and build output separately from immutable originals. Commit findings/tools/source only; no original assets or generated packages may be pushed.
5. Record source commit, package identity and verification scope together. Research does not refresh historical runtime receipts.
## Confidence and Unresolved Questions
The stack/configuration observations are directly cross-checked against repository files; historical runtime results are report evidence, not newly reproduced results. No claim is made about current upstream releases. The generic GSD `classify-confidence --provider curated --verified` returned LOW without a recognized package/ecosystem; that provider score does not independently validate these local artifacts.
Open questions are the working original capture environment, comprehensive native Windows availability, original cadence/reference trace coverage, audible output parity and the complete reachable content matrix. These require phase-specific local investigation and execution; they are not reasons to replace the mandated technology stack.
+181
View File
@@ -0,0 +1,181 @@
# Project Research Summary
**Project:** Neutron GamePort — remaining full reconstruction
**Domain:** Evidence-led reconstruction of a legacy native 3D game
**Researched:** 2026-11-12
**Confidence:** High in mandated scope and existing boundaries; medium in roadmap decomposition; unresolved for complete original/runtime fidelity.
## Executive Summary
This is an existing playable reconstruction, not a new engine project. Retain the shared C#/.NET 10, Silk.NET.Vulkan/Vulkan 1.3+ and SDL3 foundation, original-derived resources, local tooling and bounded recovered components. The user requires the remaining full game to match the original as accurately as possible. Original behavior, including quirks, takes priority over conventional movement or presentation improvements. A faithful scene is an intermediate milestone; complete campaign and supported optional-content coverage remain required.
The immediate implementation dependency is movement and interacting ownership: real derived actor responses, physical/helper registration and cleanup, callback-mutated fields, shared dynamic/static reclip, animation and camera handoffs. Preserve the implemented TSK-backed first-story ordering correction and legitimate landing bank. Expand existing gadgets, actors and levels only after their source admission dependencies close. Complete gameplay, progression/persistence and presentation/audio through integrated playable slices rather than treating their isolated algorithms as full scene support.
The largest acceptance gap is reference evidence. Existing copied-original component execution, Linux SDL/Vulkan tests, Windows cross-publishing and Wine results have useful but different scopes. Establish a usable copied-original reference environment and repeatable native Windows checks early; grow comparison coverage throughout implementation. Full-game completion requires current integrated native Linux/Windows and original-versus-port evidence, exact source/package provenance and explicit discrepancy closure. This research reviewed local documents and selected configuration/code; it did not refresh any runtime receipt or recover new binary behavior.
## Key Findings
### Recommended Stack
Retain the existing implementation. Repository versions are .NET 10 (`net10.0`, bootstrap SDK 10.0.402), Silk.NET.Vulkan/KHR/EXT 2.23.0 and bootstrap SDL3 3.4.2. Vulkan 1.3 is mandatory. These describe repository configuration, not newly checked upstream releases or installations. Host Vulkan loader/driver support remains necessary for self-contained packages.
- **C#/.NET 10:** one shared native Linux/Windows x64 runtime and managed regression programs.
- **Silk.NET.Vulkan and GLSL/SPIR-V:** existing resource ownership and shader pipeline; extend source fixed-function equivalents instead of redesigning the look.
- **SDL3:** existing native window/input/audio transport; original policy and timing remain project responsibilities.
- **Python/Bash/C, REA/Ghidra and Wine:** local preparation, evidence and isolated probes. They are not online or packaged runtime dependencies. REA is required for future original-binary investigations; Wine is preliminary compatibility evidence.
- **Local build/package scripts and hash manifests:** reuse established facilities, adding exact revision/platform/resource receipts rather than replacing infrastructure.
See [STACK.md](STACK.md) for configuration sources and verification capability gaps.
### Expected Features
All original-required behavior belongs in the full reconstruction scope. Existing bounded implementations are reusable progress, not grounds to omit their remaining consumers or lifetimes.
**Must complete:**
- Jimmy movement, original input, body/contact modes, animation/control and camera ownership across fresh entry, scripts, LOAD and RETURN.
- Actual actors, enemies/AI, RNG/action policies, health/damage/hazards, combat and class-specific task/contact effects.
- All original gadgets/vehicles and inventory/energy behavior across intended consumers and scenes, preserving currently live bounded features.
- Reachable campaign levels, authored scripts, tasks, objectives, collectibles, branch/optional content and ending/win/loss behavior where evidenced.
- Original frontend, HUD, options/configuration and complete runtime save/load/resume semantics.
- Original geometry, pivots/morphs, materials, lighting/fog/alpha/depth/cull/layer behavior and camera presentation.
- Music/speech/effects, contextual banks/channels, clocks, loops, attenuation/panning and physical audible output.
- Offline clean packages and integrated native Linux/Windows and original-reference comparisons.
**No new differentiators:** Fidelity is the value. Keep existing user-authorized diagnostics distinct from original frontend/gameplay. Do not add creative mechanics, tuned replacement movement, visual modernization, online services or telemetry. No original-required category is deferred beyond the full reconstruction merely to shorten this roadmap.
See [FEATURES.md](FEATURES.md) for per-category existing capabilities, dependency and acceptance targets. Level3B/E GAMs exist but their referenced OMTs are absent; normal gameplay reachability is unverified, so missing geometry is not an established campaign blocker.
### Architecture Approach
Preserve explicit application composition and scheduling. `RenderSession` owns persistent native presentation; scene composition connects simulation, script/interactions, decoded resources, visual adapters and audio. Original object retention is different from GPU/audio resource recreation. Recovered components require explicit actor/scene admission, with complete registry/helper lifetime and real callback policies before broad integration.
Keep body/controller/fire/control clocks independent; fresh direct-GAM ordering differs from retained TSK story entry. Maintain source live getter order and separate collision modes from class-specific state. Shared camera eye/aim, animation completion and sound software clocks need their own owners rather than generic resets or transport-driven substitutes. Extend focused modules and tests without inventing a universal engine or solver.
See [ARCHITECTURE.md](ARCHITECTURE.md) for boundary tables, the immediate physical admission gate and solved-versus-open checkpoints.
### Critical Pitfalls
1. **Component parity promoted to live fidelity:** Require actual derived policies, active membership, helper lifetime and task effects; compare ordered full state/events before admitting new actors/scenes.
2. **Symptom fixes erase original behavior:** Preserve legitimate landing bank and the implemented startup ordering correction. Trace the first divergent writer instead of adding leveling resets or importing third-party tuned movement.
3. **Convenient lifecycle/numeric rewrites alter semantics:** Preserve mutable registry traversal, repeated registrations, callback-time scalar reads, retained query state, strict comparisons, winding and evidenced float-store boundaries.
4. **Port-only visuals/audio mistaken for original parity:** Zero Vulkan errors and dummy streams prove narrower properties. Compare identified original frames, clocks, listener states and audible output.
5. **Verification and shipped revisions diverge:** Bind receipts to exact source/package/resource identity; distinguish native Windows, Wine, component execution and whole-original runtime. Never inherit historical coverage for a changed build.
See [PITFALLS.md](PITFALLS.md) for warning signs, mitigation and report references.
## Implications for Roadmap
Use eight dependency-led phases at standard granularity. Each phase should contain small source-recovery → implementation → integrated-verification slices; phase boundaries do not justify delaying necessary audio, camera or reference work.
### Phase 1: Fidelity Baseline and Reference Access
**Rationale:** Later acceptance needs a trustworthy original/platform comparison path and current coverage matrix.
**Delivers:** Revision-specific evidence/discrepancy ledger, original-reference capture route and initial native Linux/Windows scenario matrix; explicit unresolved environment limitations.
**Addresses:** Original comparison, preservation and current baseline provenance.
**Avoids:** Treating probes, startup frames, cross-publish or older packages as full-game reference evidence. Independent source-backed recovery can continue if reference execution is unavailable, but its acceptance gate stays open.
### Phase 2: Movement, Contact and Retained Ownership
**Rationale:** This is the existing stabilization gate before broader gameplay expansion.
**Delivers:** Real derived response/helper/physical-order/shared-reclip contracts, supported live admission, animation/control/camera handoffs and integrated lab → VR04 → lab → outside verification.
**Addresses:** Jimmy movement, source timing, contacts, fresh/retained/RETURN state and route ownership.
**Avoids:** Reopening the solved Carl startup correction, generic resets and premature lab/outside capsule replacement.
### Phase 3: Actors, Hazards and Combat
**Rationale:** Gadgets and campaign scripts depend on real class consumers and actor responses.
**Delivers:** Supported enemy/NPC sensing/action/RNG, damage/health/death/recovery, special contacts and actual task/contact side effects in playable slices.
**Addresses:** Actor/AI/combat and level mechanics foundations.
**Avoids:** Synthetic callbacks and generic patrols being called complete original AI.
### Phase 4: Gadgets, Vehicles and Interaction Coverage
**Rationale:** Expand on recovered actor/lifetime contracts and preserve already-live bounded gadget scenes.
**Delivers:** Remaining original gadgets, all intended consumers and supported modes, activation/cleanup, inventory/energy and transition behavior.
**Addresses:** Remote and other remaining functionality, broader existing gadget/vehicle use and source-supported inputs.
**Avoids:** Fixture/F1-grant demonstrations substituted for normal gameplay acquisition/use or blanket physical admission.
### Phase 5: Campaign, Tasks and Level Completion
**Rationale:** Full progression relies on actors, interactions and gadget consumers.
**Delivers:** All evidenced reachable campaign and optional routes, authored missions/scripts, objectives/collectibles, entrances/exits and final outcomes.
**Addresses:** Full original content and class-specific progression consumers.
**Avoids:** Counting parsed GAMs or rendered levels as playable completion; resolve absent-archive reachability before treating it as a blocker.
### Phase 6: Frontend, Configuration and Persistence
**Rationale:** Complete supported gameplay state must survive real player-facing save/resume and menu flows.
**Delivers:** Original frontend/HUD/options, persisted configuration, runtime save/load and repeatable equivalent resume across supported checkpoints and retained lifetimes.
**Addresses:** Full player workflow beyond debug tools and CLI save operations.
**Avoids:** Binary round-trip mistaken for live load correctness; preserving unknown TSK fields does not establish their gameplay semantics. Add necessary persistence earlier when campaign slices require it.
### Phase 7: Visual, Animation and Audio Fidelity Closure
**Rationale:** Systematic final presentation closure needs representative complete gameplay, while blocking presentation contracts are recovered earlier.
**Delivers:** Matched original/port frames and event/audio timelines; corrected rendering states, pivots, playback, camera/UI details, contextual banks/channels and audible spatial behavior.
**Addresses:** Remaining fixed-function and original presentation/sound differences.
**Avoids:** Modernization, assumed 60 Hz equivalence and transport/API correctness used as fidelity evidence.
### Phase 8: Full-Game Native Acceptance and Local Release
**Rationale:** Only integrated complete journeys can establish final scope and platform claims.
**Delivers:** Current clean standalone Linux and Windows packages, full progression/optional-content comparison, physical audio/input/window checks, original hash verification and discrepancy audit.
**Addresses:** Complete reconstruction acceptance and reproducible local delivery.
**Avoids:** Historical receipts or Wine replacing current native Windows execution; generated packages/original assets remain local while verified source/tools/docs go to Gitea.
### Phase Ordering Rationale
Reference access starts early and comparison grows throughout the work. Movement and lifecycle gates precede expansion; actual actors precede their gadget consumers; these enable campaign and complete persistence. Presentation and audio investigations can run independently with exclusive ownership, integrating as soon as they block a gameplay slice. The final presentation and release phases close cross-cutting differences rather than postponing every fidelity check until the end.
### Research Flags
- **Phases 1–2:** Targeted environment feasibility and deep original source/runtime investigation; complete helper/response/camera/animation contracts remain open.
- **Phases 3–6:** Phase-specific REA/asset/caller recovery is required for real actors, gadget consumers, campaign reachability and frontend/save semantics. Existing bounded implementations reduce work but do not establish remaining policies.
- **Phase 7:** Original render/audio state and playback research is essential; reference captures determine acceptance tolerances.
- **Phase 8:** Existing package/build patterns can be reused without ecosystem re-research. Native platform execution and original comparison are mandatory validation, not assumed standard behavior.
## Confidence Assessment
| Area | Confidence | Notes |
|------|------------|-------|
| Stack | High for repository foundation | Mandated by specification and corroborated by project configuration; installation/current runtime not reverified here. |
| Features | High for full scope; medium for remaining exact behavior | Explicit user/spec scope; detailed remaining behavior still requires original evidence. |
| Architecture | High for current boundaries; medium for proposed phase order | Multiple local reports agree; future dependency grouping is planning inference. |
| Pitfalls | High as recorded risks | Supported by prior divergence/lifecycle reports; this review does not reproduce their experiments. |
**Overall confidence:** Medium for the execution roadmap, with strong documented constraints and explicit unresolved original behavior. Generic provider-classifier LOW results in dimension files do not independently certify or invalidate underlying repository evidence.
### Gaps to Address
- Working whole-original capture environment and repeatable native Windows access remain unverified dependencies.
- Complete physical helper membership/removal/activation, derived soldier/Jimmy effects, shared mutable reclip, camera handoff and animation/sound clocks need focused investigation.
- Full reachable content, original frontend/save callers, contextual audio and per-layer rendering remain incomplete; do not fabricate behavior from resource names.
- Comparison tolerances must be justified per system from original observations; no blanket pixel-perfect or bit-exact whole-game claim is supported.
- Historical reports contain superseded narratives. Prefer dated continuation evidence with exact revision/platform scope before implementation.
## Sources
### Authoritative Scope and Repository Rules
- [PROJECT.md](../PROJECT.md) — user-selected full remaining reconstruction and maximum-fidelity priority.
- [prompt.MD](../../../prompt.MD) — original mission, platforms, preservation and full completion requirements.
- [AGENTS.md](../../AGENTS.md) — current movement priority, REA requirements and Gitea/local-only artifact policy.
### Synthesized Research
- [STACK.md](STACK.md) — existing technology/configuration and verification facilities.
- [FEATURES.md](FEATURES.md) — original-required categories, bounded existing support and acceptance gaps.
- [ARCHITECTURE.md](ARCHITECTURE.md) — ownership/admission dependencies and solved versus unresolved work.
- [PITFALLS.md](PITFALLS.md) — fidelity risks and concrete prevention.
### Underlying Local Evidence Indexes
- [Progress](../../docs/progress.md), [compatibility](../../docs/compatibility.md), [tasks](../../docs/tasks.md) — historical implementation/runtime receipts and current limits.
- [Coverage](../../docs/checkpoint/coverage.md), [implementation ledger](../../docs/checkpoint/implementation-plan.md), [next-work plan](../../docs/checkpoint/next-work-plan.md) — source recovery and admission gates, including later correction updates.
- [Codebase architecture](../codebase/ARCHITECTURE.md), [concerns](../codebase/CONCERNS.md) — current source structure and risks.
- Specialized source/probe/runtime reports are linked beside individual findings in the four dimension files. Their evidence scopes remain binding; this synthesis is not new binary or runtime evidence.
---
*Research completed: 2026-11-12*
*Ready for roadmap: yes, with unresolved verification dependencies retained explicitly.*
+53
View File
@@ -0,0 +1,53 @@
{
"contract": "1.0.0",
"flavor": "core",
"milestone": null,
"phases": [
{
"number": "1",
"name": "Reproducible Fidelity Baseline",
"status": "in_progress"
},
{
"number": "2",
"name": "Faithful Movement and Scene Handoffs",
"status": "pending"
},
{
"number": "3",
"name": "Original Actors, Hazards and Combat",
"status": "pending"
},
{
"number": "4",
"name": "Complete Gadget and Vehicle Use",
"status": "pending"
},
{
"number": "5",
"name": "Complete Campaign and Optional Routes",
"status": "pending"
},
{
"number": "6",
"name": "Original Frontend and Save/Resume",
"status": "pending"
},
{
"number": "7",
"name": "Original Visual and Audible Presentation",
"status": "pending"
},
{
"number": "8",
"name": "Full-Game Native Acceptance and Delivery",
"status": "pending"
}
],
"next": {
"command": "$gsd-progress --next",
"label": "Review prepared Phase 1 checkpoint and pending combined human session",
"reason": "Phase 1 remains open: 7/7 autonomous preparation records, actual acceptance human_needed 0/120; Phase 2 not advanced"
},
"updated_at": "2026-11-13T21:49:00Z"
}
+154 -3
View File
@@ -1,7 +1,10 @@
# Neutron GamePort # Neutron GamePort
Follow `../AGENTS.md` and `../prompt.MD`. This is the local Git repository. Follow `../AGENTS.md` and `../prompt.MD`. This is the local Git repository.
Do not configure a remote, push, upload originals or use cloud CI. User workflow update (2026-11-05): push completed, verified commits to the
existing `Gitea` remote; `main` tracks `Gitea/main`. This supersedes earlier
no-remote/no-push rules. Keep builds/tests local; do not upload originals or
generated packages or use cloud CI.
Originals are in `../Original/` and must remain byte-identical; verify using Originals are in `../Original/` and must remain byte-identical; verify using
`python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json`. `python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json`.
@@ -35,5 +38,153 @@ other agents' active changes. Keep updates concise, save detailed evidence to di
Use bounded endian-aware parsers, portable paths, clear C#, deterministic tests, Use bounded endian-aware parsers, portable paths, clear C#, deterministic tests,
and explicit unmanaged ownership. Build frequently. Update `docs/progress.md`, and explicit unmanaged ownership. Build frequently. Update `docs/progress.md`,
`docs/tasks.md`, `docs/decisions.md`, and compatibility evidence before transitions. `docs/tasks.md`, `docs/decisions.md`, and compatibility evidence before transitions.
Current priority is exact asset recovery and one reconstructed original scene; Current direction: preserve exact original movement; keep gameplay expansion
read those documents for actual completion status and next actions. paused. The menu/background→successful TSK-load lifetime now establishes retained
Jimmy-before-level-input order on first story entry. Correct that initialization
classification, preserving fresh direct-scene order and all movement/rotation
algorithms. See docs/gameplay/main-menu-player-lifetime.md. The strengthened
Vulkan Carl fixture reproduces the old first-neutral-tick bank and passes after
the correction; broader/native Windows comparison remains separate.
The broader priority remains Jimmy movement stabilization, with gadgets paused. Preserve current movement as baseline; do not substitute
JN-Engine native/Godot movement. Use its original decompiler index only as leads,
verified with REA/authoritative originals. See docs/gameplay/jimmy-movement-stabilization.md.
Pair continuation: docs/checkpoint/pair-lifecycle.md records28 complete original/
C# cases and20 VR04 class bindings. OriginalPairCollision is a bounded component,
not live scene admission. Next recover full physical registration/activation and
helpers, real actor responses and shared dynamic reclip before replacing existing
collision. Gated pairs retain contacts; sphere exclusions use the earlier actor.
Both packages identify clean924ad2f; standalone Linux Carl return passes with4
readbacks identical to ea04210. Current Windows is cross-published/resource-
verified; earlier Wine64 runtime evidence belongs to ea04210, native Windows open.
Registration continuation: docs/checkpoint/physical-registration.md and
vr04-generated-bodies.md cover72 records/13 classes,12 original component cases
and21 helper edges. Runtime/packages remain924ad2f. Common append is not deduped;
Jimmy49E guards the whole bridge. Per-node Init/PostLoad visits new registry tails.
Full retained helper membership/cleanup/activation and shared reclip remain open.
Dynamic continuation: docs/checkpoint/dynamic-context.md adds17 complete original/
C# test-only reclip cases and12 captured kernel arguments. Kernel winding is A,C,B
relative to construction; preserve retained hit/last polygon and final local-root
publication. Jeep default deletion eligibility is guarded, full cleanup remains
open. Next nonempty shared static reclip/ordered bodies and real callbacks;
no live pair admission or package change.345 Python checks and539 originals pass.
Populated continuation: docs/checkpoint/dynamic-reclip.md matches14 full original/
C# observations and12 kernel steps. Shared edge/ray math now retains evidenced
float-store boundaries; NodeVisits precedes the geometry gate. No broad x87 or
new actor admission claim. Next real Jimmy/VR04 callback mutations/live getter
timing and retained helper cleanup/order; consult current verification receipts.
The populated correction passes348 Python+2 HUD, all managed projects and36 GPU
checks, plus native Linux Carl/VR04 SDL replays and Windows x64 cross-publish.
All539 originals and924ad2f packages are unchanged; no new Windows execution.
Normal continuation: docs/checkpoint/actor-normal-contacts.md adds30 complete
original/C# snapshots,13 interfaces/182 bindings and5 scalar getter fields.
OriginalNormalContacts is standalone; Jimmy ordinary374 bypasses reflection.
Soldier174 and Jimmy204 endpoints are recorded, not fully executed policies.
Next derived response and retained helper cleanup/activation/order; do not wire
new actors or cache pre-callback radius/flags. Use reviewed relocation operands.
352 Python and targeted body/pair/reclip checks pass, with Linux/Windows builds;
539 originals and924ad2f packages stay unchanged. Latest integrated SDL/GPU
evidence is bf876e9; no new live profile or native Windows verification is claimed.
2026-11-06 continuation: the earlier292 original component cases plus50 derived-
caller cases and body/visual-sync audit supply no extra reset. Startup diagnostics
now observe backgroundLevel1D/Jimmy allocation after an explicit OS repaint
acknowledgement, with black frames/timing perturbation recorded. Source lifetime,
not those frames, proves the TSK ordering correction. Preserve normal landing
bank; never substitute a leveling reset. Historical runtime/package baseline is
a2e89c6/dae13ac. Read the current progress/compatibility results before packaging.
The prior collision work is resumed where needed for movement; preserve the
35a2a66/0272f7b checkpoints and their source gates before broader body admission.
Controller checkpoint integrates108 native ground/air/facing/jump comparisons;
13 Jimmy source guards,26 movement/20 body groups and all five native SDL jump
aliases pass. Source pressure requires a real support polygon; lab/outside keep
capsule compatibility. The next bounded air-target/root-render bridge is now
implemented (docs/gameplay/jimmy-air-bridge.md):146 saved source observations
compare, including12 air targets and12 degree/14 hierarchical transforms. Target
dirty/Init and retained apply-owned pitch seeds stay separate from current Euler.
Modern local sole correction and final OMT render-decomposition precision remain
explicit; broader special/root-changing/dynamic contacts are next.27 contact
dispatch observations still do not establish live special callbacks.
Body publication/mode foundation now implements fresh previous/live XYZW,
independent source flags, retained context and post-landing payload ownership.
100 new complete original comparisons plus six bounded callback-state cases pass;
see docs/checkpoint/body-contact-implementation.md. Keep admission gated: actual
Jimmy hazards/climbs, multi-frame actor mode/facing/animation and dynamic/shared
scene context are still open. No automatic lab/outside solver replacement.
No Remote/new-gadget implementation until this movement priority is handled.
The initial architecture checkpoint is documented in docs/checkpoint/review.md; use the playable
69d0187 baseline as a comparison tool. Read
docs/checkpoint/README.md, coverage.md and implementation-plan.md before gameplay
changes. Current gadget controls/resources/primary-fire findings belong in
docs/gameplay/. Distinguish static recovery, implementation, port tests and original
runtime evidence. Main owns integration/runtime; gadget investigators have
exclusive named files, not shared directories.
Scooter feedback fixes: docs/gameplay/scooter-dismount-leveling.md and
scooter-pitch.md. Preserve dismount Euler copy; source4096E0 levels Goddard X/Z
in the bounded follow bridge. ScooterAudio adds47D9D0 positional frequency/history
after the unchanged engine formula; current shared listener includes parked/script
cameras.11 native facing +11 frequency traces,13 Scooter/2 audio/10 Patrol groups
and24 Python guards pass; both native input replays pass with zero validation
errors. Both packages identify cleanfccc0b9; standalone Linux repeats both scenes
with20 matching readbacks. Whole-original/audible Windows comparison remains open.
Latest gadget continuation: docs/gameplay/scooter-live.md. Scooter is live in
VR05 and outsideLEV1 through normal owned tile/F1. Separate C3DJEEP body and four
real wheel supports, source drive/input/impact/default camera, exact source-pivot
art, pitch-controlled engine and summon/contact mount/cleanup/RETURN are integrated.
53 copied-original observations match managed formulas;10-phase headless/native
Linux replays pass in both scenes, zero validation errors. The32-row debug Player
page fits ultrawide. Whole-original/native Windows comparison, modes2..20,
mouse/analog, dynamic pairs and arbitrary retained LOAD/save remain open. Goddard
follow is an opt-in bounded adapter in these scenes. Source/REA artifacts are under
artifacts/scooter-*-live; all ownership is primary. Package evidence is in the live
report. Both packages identify clean62c07a3, resources match, and standalone
Linux from /tmp passes both10-phase native replays with20 identical readbacks.
All303 Python+2 HUD/managed/36 main GPU regressions and539 original hashes pass.
Preserve parked Jimmy collision; Scooter's source callback is independent.
Grappler remains live boundedVR08; see docs/gameplay/grappler-live.md for113
original-component observations,13 managed/40 Python checks and9-phase SDL replay.
The user clarified orbit's remaining issue was inverted Left/Right; Left/A and
Right/D azimuth mappings are corrected, Up/Down unchanged. The historical orbit packages
identified clean70cba65; native input/resize/validation passes. See docs/orbit-camera.md.
Rocketship remains live in boundedVR02: source body/callbacks,
registration-ordered input, maneuvers/camera, original
driver/Goddard/flame resources and F1 grant.96 isolated original component cases
support the source contracts; full pair discovery, other levels, special mission/
hazard/RNG effects and whole-original/native Windows comparison remain open.
Its wall-impact material RGBA correction is docs/gameplay/rocketship-impact-render.md;
13 managed/22 Python checks and final native Linux flight replay pass.
Grappler source is in docs/gameplay/grappler.md. Friend
research assessment is docs/reviews/jn-engine-survey.md; use its decompiler leads
with REA/source checks, not its tuned C gameplay. All ownership has returned.
Preserve baseline69d0187 and parked35a2a66/0272f7b collision checkpoints. Latest
package provenance and validation are recorded in the live report.
Baseball continuation: docs/gameplay/baseball-implementation.md. Its20-slot
pool, hold/release aiming, original TIME art and boundedVR07 moving targets are
implemented; original dynamic pair discovery/other enemy consumers remain open.
Scooter historical recovery is docs/gameplay/scooter.md; live coverage is scooter-live.md.
Bubble's mode2,
original sprite and boundedVR01 source body/floor state are implemented and tested;
Invisible, ray/jetpack and shared energy state remain integrated. Other gadgets
and broader collision/camera/retained-helper behavior remain separate gates.
All current investigator ownership has returned to primary. Keep full enemy AI,
suppression globals, render state and original/native Windows verification distinct.
Use REA for original-binary investigations from now on, including delegated
investigations. Preserve its Evidence and cross-check relevant addresses/bytes;
record provider gaps explicitly and use supporting analysis when needed. Ordinary
source edits and builds do not require a REA call.
Local REA/Ghidra is available through scripts/rea.sh; see docs/rea.md for the
ignored launcher environment and JDK paths. Existing client MCP registration was
not changed. Use generated copies, preserve complete Evidence/snapshots, and keep
static decompilation distinct from source execution. Current C3 continuation:
docs/checkpoint/control-phase-implementation.md; remaining body/wrapper/camera gates
are in its final section and the implementation ledger.
Current C4 follow-up is docs/checkpoint/collision-response.md with ceiling-wrapper,
body-root-registration and camera-handoff reports. The source sphere kernel is
isolated/probed; do not treat it as live capsule replacement. Next integration
report is collision-body-probe.md: source grid/retry component and seven original
dispatcher comparisons, contact/material/friction contracts and ten ordinary-body
observations are recorded. collision-body-implementation.md now records matched
ordinary composition and VR04 static-only live integration. Next: original dynamic
actor eligibility/pair state and special contacts before lab/outside expansion;
shared camera state remains separate. Retain modern render/noclip boundaries.
+115 -6
View File
@@ -2,9 +2,47 @@
Local reconstruction of the supplied **Jimmy Neutron: Boy Genius** installation Local reconstruction of the supplied **Jimmy Neutron: Boy Genius** installation
using C#/.NET 10, Silk.NET.Vulkan (Vulkan 1.3), and SDL3. Original files remain using C#/.NET 10, Silk.NET.Vulkan (Vulkan 1.3), and SDL3. Original files remain
untouched in `../Original`. There are no Git remotes or runtime online services. untouched in `../Original`. Work is local; no remote operations or runtime online
services are used.
**Current direction: stabilize Jimmy movement before more gadgets.** Keep our
playable movement baseline; JN-Engine's original decompiler index supplies leads,
verified with REA and authoritative component probes. The
[movement checkpoint](docs/gameplay/jimmy-movement-stabilization.md) records
controller/facing/jump corrections. The [air bridge](docs/gameplay/jimmy-air-bridge.md)
adds source airborne tilt, target-state ownership and full Euler rendering, with
explicit remaining render precision/body gates. The
[checkpoint review](docs/checkpoint/review.md), [coverage map](docs/checkpoint/coverage.md)
and [implementation plan](docs/checkpoint/implementation-plan.md) compare source
owners, update order and lifecycles with the port. Clean69d0187 and its packages
are preserved locally as the playable baseline. Corrections now include task/Carl
callbacks, controlled player phase ordering, source static camera queries for the
first route and gadget availability through tutorial/return. Full scene scheduling,
collision and shared camera state remain incomplete.
The user requested this change after milestone35a2a66/0272f7b. Gadget work uses
original controls, state and assets; the collision checkpoint remains available
to resume after this gameplay work.
VR04 and the bounded VR01/VR07 tutorials use recovered static body response/support/friction with original-code
numeric references. Lab/outside retain the capsule until special contacts and
dynamic collision are recovered; see [body implementation](docs/checkpoint/collision-body-implementation.md).
**Current milestone: VR08 Grappler, VR02 Rocketship, Baseball, Bubble, Invisible, shrink ray and their gadget screen.**
Tab/Space selects owned gadgets and their practice levels; the default device
fires on Enter/Ctrl/left mouse and supports actual VR04 soldier shrink/restore
with original morphs and score effects. Invisible uses the recovered recharge,
activation, blend flash, meter and cleanup rules; full enemy sensing/combat and
other gadget effects remain incomplete.
See [gadget implementation](docs/gameplay/gadgets-implementation.md) for recovered
rules, modern policies and the verification boundary.
The [Invisible continuation](docs/gameplay/invisible-implementation.md) records
the later implementation and shared energy-warning sounds.
The [Bubble continuation](docs/gameplay/bubble-implementation.md) adds its source
controller, original sprite, automatic/high bounces and VR01 floor behavior.
The [Baseball continuation](docs/gameplay/baseball-implementation.md) adds hold/
release aiming, original ball/TIME art and VR07's moving targets and trophy gate.
The [Grappler continuation](docs/gameplay/grappler-live.md) adds VR08 attachment,
shared body/contact state, source camera, rope/SWING/cursor and cleanup.
**Current milestone: original lab story, interactions and jet pack practice flow.**
The runtime includes recovered camera/speech triggers, moving props, Carl/Goddard The runtime includes recovered camera/speech triggers, moving props, Carl/Goddard
patrol logic, pickups, objectives, the practice prompt, VR04 powered jumping and patrol logic, pickups, objectives, the practice prompt, VR04 powered jumping and
checkpoint transitions. Collision response, timing and visual fidelity remain checkpoint transitions. Collision response, timing and visual fidelity remain
@@ -33,20 +71,73 @@ The lab camera sequence stops background music and DEFAULT restarts it when
control returns, including after skipping. control returns, including after skipping.
**F1** opens the debug menu and pauses gameplay and audio. Use Up/Down to select, **F1** opens the debug menu and pauses gameplay and audio. Use Up/Down to select,
Left/Right to change values, Enter to apply, and F1/Escape to close. It includes Left/Right to change values, Enter to apply, Tab to switch General/Player/Systems
pages, and F1/Escape to close. It includes
live diagnostics, camera switching, cutscene skip, energy refill, jet-pack grant, live diagnostics, camera switching, cutscene skip, energy refill, jet-pack grant,
SCENE task editing, all 33 prepared levels and their original startpoints, and SCENE task editing, all 33 prepared levels and their original startpoints, and
reset. Page Up/Down changes the staged SCENE value by 10. reset. Page Up/Down changes the staged SCENE value by 10.
The Force Control toggle keeps Jimmy controllable during scripted control locks. See The Force Control toggle keeps Jimmy controllable during scripted control locks. See
[debug menu controls](docs/debug-menu.md). [debug menu controls](docs/debug-menu.md). Player/System pages add movement and
jetpack state controls, camera obstruction, audio category mutes, objective/practice
controls and checkpoint save/load. **F3** toggles noclip: WASD moves/strafe, arrows
move/turn, Space/E rises, Ctrl/Q descends and Shift triples flight speed. Noclip
bypasses collision and contact triggers; reset or a new level disables it.
F1→Player also grants/selects Invisible, unequips it, and shows its timers and
targetability state. After selecting Invisible, allow7 seconds to recharge, then
fire without jump to activate for7 seconds at a fixed2-energy cost (tutorials
are exempt). Its last3 seconds flash before normal rendering returns.
F1→Player can also Give/Select Bubble. **Up or primary fire** accelerates, arrows
steer, and holding jump makes higher bounces. Tab/Space first unequips it; the
original sprite fades afterward. VR01 uses source body/floor rules; lab/outside
collision remains provisional.
F1→Player also has **Give/Select Baseball**. Hold **Enter/Ctrl/left mouse** to
aim, use **Up/Down** to change elevation and **Left/Right** to turn, then release
fire to throw. Practice on its owned tile opens VR07. The twenty-ball pool,
target respawn and original aim display are implemented; full enemy combat and
original dynamic contact scheduling remain incomplete.
**F1 → Player → Give All Gadgets** grants all eight gadgets without changing
the equipped gadget. Close F1, then use Tab/Space to select one.
Rocketship flight is available in **VR02**: select its Practice tile, then equip
it there or use **F1 → Player → Give/Select Rocketship**. Up/right mouse accelerates
and climbs; Down brakes and descends; Left/Right banks. **Enter/T** performs a
180-degree turn, **R** barrel rolls, and Tab/Space unequips. R resets normally
when unmounted. Source camera, aircraft body and Jimmy/Goddard/flame visuals are
included. Other levels and special mission/hazard sequences remain unfinished.
Grappler is live in **VR08**. Select its Practice tile, then equip it there or
use **F1 → Player → Give/Select Grappler**. Aim Jimmy toward a surface until the
target appears; **Enter/Ctrl/left mouse** attaches and reels, arrows steer,
and **Shift/Insert/right mouse** detaches when fire is released. Tab/Space
unequips. Original rope, SWING morph, cursor, sounds, camera and contact response
are connected. Other levels and special camera/contact policies remain open.
**F2** toggles a compact live debug overlay without pausing play. It shows frame **F2** toggles a compact live debug overlay without pausing play. It shows frame
timing, position/velocity, movement, control/force state, tasks, camera/clipping timing, position/velocity, movement, control/force state, tasks, camera/clipping
and error counters. F1 also has a Live Overlay toggle. Visibility stays selected and error counters. F1 also has a Live Overlay toggle. Visibility stays selected
across scene changes during the session; `--debug-overlay` enables it at startup. across scene changes during the session; `--debug-overlay` enables it at startup.
The original lab pickup is internally tagged `shrinkray`; the original objective Level changes keep the same window and Vulkan renderer, preserving window bounds,
art identifies it as the **jet pack**. Its practice prompt accepts **Y** or a click focus and fullscreen state. UI scales uniformly on widescreen: prompts/F1 stay
centered, objectives stay bottom-right and F2 stays top-left. Use
`--width 1920 --height 1080` for an initial window/offscreen size; resizing and F11
update UI placement and clicks.
The lab pickup is the combined **shrink ray and jetpack** (inventory item3).
Hold **Enter, Ctrl or left mouse** to fire the continuous ray; release to stop.
Grounded firing stops forward motion. Eligible original Yokian soldiers can be
shrunk for30 seconds, awarding10 points. Their authored shrink animation holds
its small endpoint; complete enemy AI/combat remains unimplemented.
**Tab or Space** opens the original gadget screen; with another special gadget
equipped, the first press unequips it. Use the mouse or arrows to point, then
Enter/Ctrl or a mouse button to select. Escape or Return closes the screen.
Practice Mode followed by an owned gadget enters its original tutorial directly.
The screen scales uniformly on widescreen and pauses port gameplay while music
continues. Other gadget selection art is present; the remaining special behaviors stay
future work. F1's jetpack availability control also controls shrink-ray ownership.
The pickup's original objective calls its jump action the **jet pack**. Its
practice prompt accepts **Y** or a click
on Yes to enter VR04, and **N** or a click on No to resume. Enter selects the on Yes to enter VR04, and **N** or a click on No to resume. Enter selects the
hovered Yes region, otherwise No. Practice RETURN restores Jimmy and Goddard to hovered Yes region, otherwise No. Practice RETURN restores Jimmy and Goddard to
the saved departure position, retains the lab start's yaw and suppresses its intro. the saved departure position, retains the lab start's yaw and suppresses its intro.
@@ -107,6 +198,9 @@ scripts/build-windows.sh
scripts/package.sh scripts/package.sh
``` ```
After building, `scripts/test-window-transitions.sh` runs a local Linux fullscreen/
ultrawide regression using installed Xvfb, Xfwm, D-Bus and xprop.
The publish scripts perform equivalent self-contained publishes: The publish scripts perform equivalent self-contained publishes:
```bash ```bash
@@ -151,3 +245,18 @@ use Wine, DirectX or OpenGL. See `docs/reference-testing.md` for actual results.
All generated extraction output, local SDK/native dependencies, captures and All generated extraction output, local SDK/native dependencies, captures and
packages are ignored by the nested local Git repository. Never configure a remote, packages are ignored by the nested local Git repository. Never configure a remote,
upload assets, or overwrite the original installation. upload assets, or overwrite the original installation.
Native reverse engineering uses the local REA/Ghidra launcher separately from
runtime builds; see [local analysis setup](docs/rea.md). Current source-backed
cutscene control/body phase findings are in
[control-phase implementation](docs/checkpoint/control-phase-implementation.md).
The collision continuation adds a probed
[source sphere kernel](docs/checkpoint/collision-response.md) and integrates the
[overhead response](docs/checkpoint/ceiling-wrapper.md); full capsule replacement
and [shared camera handoff](docs/checkpoint/camera-handoff.md) remain open.
Scooter is implemented in VR05 and outside LEV1. Select its owned tile with
Tab/Space (or F1 → Player → Give/Select Scooter), then walk into the summoned
vehicle at Goddard. Up/primary fire accelerates, Left/Right steers, Down brakes
then reverses, jump jumps, Tab/Space unequips. F1 Give All Gadgets also grants
its normal tile. Source, verification and remaining limits: [Scooter](docs/gameplay/scooter-live.md).
+21
View File
@@ -128,3 +128,24 @@ actual lab bars closed/open passage using the existing provisional swept-sphere
SceneCollision adapter. The latter verifies port integration, not original47BD80 SceneCollision adapter. The latter verifies port integration, not original47BD80
or original runtime behavior. Full edge/vertex sphere response, static reclipping, or original runtime behavior. Full edge/vertex sphere response, static reclipping,
door pushing/crushing and native original comparison remain unresolved. door pushing/crushing and native original comparison remain unresolved.
## Shared response continuation — 2026-11-07
[Dynamic context](../checkpoint/dynamic-context.md) now supplies17 complete
original mode2/static-reclip observations and a test-only C# composition. Twelve
captured kernel calls establish A,C,B argument winding relative to the construction
topology above, with the construction normal retained. Do not reverse live
construction topology indiscriminately. The injected live adapter is unchanged.
The original retains hit/last polygon, can invoke a stale static callback after
the dynamic hit, and publishes its local root after callbacks unless inhibited.
Empty-grid tests close that finite ownership contract, not nonempty shared-world
behavior, real actor responses or broad live admission. The source kernel itself
has since been recovered in collision-response/body reports; the older unresolved
wording above describes this report's original implementation checkpoint.
The [populated follow-up](../checkpoint/dynamic-reclip.md) adds14 exact full
observations and12 kernel-step matches, with source-store corrections in shared
edge/ray arithmetic. This closes the populated synthetic reclip contract without
replacing the live injected adapter. Real callbacks, live getter timing and
retained physical/helper order remain the admission boundary.
+5 -2
View File
@@ -7,10 +7,13 @@ Original DLL/frame and original game comparisons are separate evidence categorie
## Identity ## Identity
The lab pickup's GAM tag SHRINKRAY/PickupIndex301 is a prototype/internal name. The lab pickup's GAM tag SHRINKRAY/PickupIndex301 belongs to the combined device.
Original screens.omt Canv120 says GET JET PACK; its effect grants inventory Original screens.omt Canv120 says GET JET PACK; its effect grants inventory
group0/item3. That exact inventory slot gates the powered-jump code43848E/4385C9. group0/item3. That exact inventory slot gates the powered-jump code43848E/4385C9.
It must not be presented as a shrink-ray weapon. The original readme describes The later gadget recovery corrects the old prototype-name interpretation:
tile14 names SHRINK RAY, controls113 lists both SHRINK and JUMP/JETPACK, and
426E40 fires the default owned-item3 ray. See docs/gameplay/shrink-ray.md.
The original readme describes
Shift/Insert/right mouse as Jump - Jet Pack Burst. The actual C3DShrinkRay class Shift/Insert/right mouse as Jump - Jet Pack Burst. The actual C3DShrinkRay class
has separate ray.ase/ray0000..2.png bindings440035..A6, outside this implementation. has separate ray.ase/ray0000..2.png bindings440035..A6, outside this implementation.
+3 -1
View File
@@ -70,7 +70,9 @@ The follow-up below recovers and implements the actual contact/talk dispatcher
and the internally named shrinkray jet pack checkpoint/inventory/practice/gadget effects. General AI sensing, and the internally named shrinkray jet pack checkpoint/inventory/practice/gadget effects. General AI sensing,
weapon behavior and all special pickups remain incomplete. weapon behavior and all special pickups remain incomplete.
LOAD LABTONEIGH GAM0xA43 goes tolevel1.gam/startlevel1, SCENE60/radius200. LOAD LABTONEIGH GAM0xA43 goes tolevel1.gam/level1, SCENE60/radius200.
The destination start tag is `level1`; the earlier `startlevel1` spelling was a
documentation error. Checkpoint helper re-reads the original GAM field directly.
Underground LOAD0x8360 requires scene65, start riverlab. Binary0x457F32..7F5F: Underground LOAD0x8360 requires scene65, start riverlab. Binary0x457F32..7F5F:
none requiredtask bypasses; taskvalue-1 bypasses; otherwise >=RequiredLevel and none requiredtask bypasses; taskvalue-1 bypasses; otherwise >=RequiredLevel and
ExactLevel!=-1 additionally requires equality to that numeric ExactLevel. ExactLevel!=-1 additionally requires equality to that numeric ExactLevel.
+5
View File
@@ -1,5 +1,10 @@
# Follow-up original collision evidence # Follow-up original collision evidence
Continuation2026-10-26: checkpoint/collision-response.md supersedes the earlier
recursive-sliding inference with REA/byte/probe evidence for47BD80 and its callers.
The source kernel is now a separate tested component; live capsule replacement,
full contact/support order and pivot fidelity remain open.
Static investigation and isolated copied-DLL probes,2026-10-24. The bounded Static investigation and isolated copied-DLL probes,2026-10-24. The bounded
OriginalBodySupport module now translates the vertical support/segment path. OriginalBodySupport module now translates the vertical support/segment path.
This does not supersede the complete provisional SceneCollision solver or prove This does not supersede the complete provisional SceneCollision solver or prove
+8
View File
@@ -250,3 +250,11 @@ The wall response is still the port's swept sphere, not the original47BD80 solve
Visuals use those actor roots without an additional sole-based correction. Visuals use those actor roots without an additional sole-based correction.
The remaining raw-sole/root clearance difference is documented in collision notes. The remaining raw-sole/root clearance difference is documented in collision notes.
Primary added a tenth test group for Carl's profile, speed, yaw factor and state9. Primary added a tenth test group for Carl's profile, speed, yaw factor and state9.
2026-11-04 Scooter follow-up: the opt-in VR05/LEV1 Goddard follow bridge now
applies recovered4096E0 pitch/yaw/roll smoothing toward its ordinary supported
follow target, rather than preserving dismount tilt indefinitely. Cleanup keeps
the full source Euler handoff. Nine active copied-original angle cases plus two
gate observations and actual tilted-dismount tests support this correction;
general patrol/Carl and airborne target selection retain their earlier limits.
See [scooter-dismount-leveling](../gameplay/scooter-dismount-leveling.md).
+214 -4
View File
@@ -5,6 +5,76 @@ SDL3 for platform windowing, input and audio. Linux x64 and Windows x64 are
equally required. Source is `src/GamePort/`; root executable csproj allows equally required. Source is `src/GamePort/`; root executable csproj allows
`dotnet build` and `dotnet run` from GamePort. No runtime network dependencies. `dotnet build` and `dotnet run` from GamePort. No runtime network dependencies.
Shared collision kernels retain recovered float-store boundaries in edge
projection and ray normalization/hit publication. `StaticCollisionContext` keeps
nearest/last polygon, passes, pre-geometry node visits and actual primitive tests
separate. Dynamic pair/reclip composition remains a test fixture until real
actor callbacks and retained physical order are recovered. See
checkpoint/dynamic-reclip.md; no generic live box solver is implied.
`OriginalNormalContacts` exposes inherited370/374/378 through an actor-owned
accessor interface, keeping full-vector/XYZ setters, fresh Y, damping and heading
impulse distinct. It is not a universal Jimmy callback: Jimmy's ordinary374
override bypasses reflection. Real class bindings and late scalar ownership are
documented in checkpoint/actor-normal-contacts.md; live profile wiring is retained.
`Scooter` is a separate registered C3DJEEP in VR05/LEV1, owning body, wheels,
steering/impact/jump clocks and camera state. Selection summons at the companion;
strict contact transfers raw control. PlayerSceneBinding runs body, player/input,
vehicle frame/passenger-copy, then wheel phase. OrdinaryBodyPhysics exposes the
wall callback before floor/friction so contact speed writes affect the same pass.
ScooterVisuals uses exact unit-scale body/wheels/rider morphs; SceneAudio maps
source engine frequency to SDL stream ratio. Goddard follow is opt-in for these
scenes. Scene-local lifetime, provisional moving doors and fixed cadence remain
explicit boundaries. See gameplay/scooter-live.md.
`BaseballGadget` keeps pending/saved/displayed aim, camera adjustments and20 owned
`BaseballProjectile` entries distinct from equipped raw mode. Cleanup hides its
UI/restores the companion but retains the latch and flying balls. `SceneBaseballs`
steps bodies before controller input and target frame state afterward; six duplicate
3TAR tags retain source-instance identities. The source body has an explicit ball
profile for delayed landing impulse, prevent-lowering=false and reflection/friction.
Sphere-pair discovery remains a declared bounded adapter. `BaseballVisuals` and
`BaseballAimOverlay` append source Canv2/253 and TIME16-pixel glyphs using the
existing world/overlay pipelines and uniform viewport. See baseball-implementation.md.
Bubble adds separate `BubbleMotion` input/apply, `BubbleEffect` owned clock and
`BubbleVisuals` original canvas. LabSimulation keeps body factor, current maximum,
movement mode and captured sprite root distinct. The source static factory also
admits VR01; its retained support ID feeds bounded `Vr01FloorState` before the
controller, independently of current support/control. `PlayerAppearance` stores
material writes from Invisible alpha/blend requests and late lava RGBA, preserving
source phase order instead of rebuilding one effect's alpha every render.
See gameplay/bubble-implementation.md for coverage and remaining gates.
The Invisible continuation adds `InvisibleGadget` in Jimmy's post-movement wrapper
phase, separate from input identity. `PlayerSceneBinding` supplies raw-any-control,
handles equip/companion flags and receives a named-Jimmy cleanup event from CAM/
initial MCA, distinct from raw-owner preparation. `PlayerGadgetMaterial` changes
the existing atlas draw; `InvisibleMeterOverlay` loads original Canv21/22 and
uses shared uniform viewport scaling. `PlayerEnergy` is application-session owned
across scene rebuilds, preserving scalar/warning latch separately from TSK.
See gameplay/invisible-implementation.md for exact coverage and remaining gates.
The first gadget slice separates UI display selection from the equipped raw mode.
`GadgetScreen` owns group0 panel state/hit regions; `GadgetMenuOverlay` loads54
original canvases and applies shared uniform640×480 viewport/pointer transforms.
Closing precedes the inventory selection event. Practice captures the existing
departure context and requests the selected VR01..08 without a pickup prompt.
The panel gates new gameplay SFX; full simulation pause is a declared port policy.
`SceneGadgets` subscribes to the player's existing input phase and owns ray sound,
energy, actual3SOL targets and score callbacks to `SceneInteractions`/TSK.
`ShrinkRay` isolates strict source heading/height/distance/wall gates and texture
clock; `OriginalHeading` implements the copied-DLL numeric references.
`ShrinkSoldier` separates authored/reset AI mode from prior dynamic mode, shrink
timer/marker and provisional NPC body support. `ShrinkSoldierVisuals` samples
original WALK/SHRINK morphs with nonloop hold rather than scaling the mesh.
`ShrinkRayVisuals` captures the effect root/yaw and three source textures.
Generic draw opacity and opaque/alpha/additive variants support the recovered
half-opacity ray. Blended-world depth writes disabled is an explicit renderer
policy. See gameplay/gadgets-implementation.md for evidence and remaining gates.
Original assets stay in `../Original`. Python tools parse undocumented original Original assets stay in `../Original`. Python tools parse undocumented original
formats into generated scene resources under `artifacts/`. The modern application formats into generated scene resources under `artifacts/`. The modern application
loads these original-derived resources and big endian GAM entity data. Portable loads these original-derived resources and big endian GAM entity data. Portable
@@ -23,6 +93,38 @@ verification possible without a desktop; this is distinct from SDL presentation.
Simulation implementation must follow recovered algorithms and timing. A generic Simulation implementation must follow recovered algorithms and timing. A generic
fly camera or rendered model alone does not satisfy the playable-scene requirement. fly camera or rendered model alone does not satisfy the playable-scene requirement.
Collision continuation separates the recovered one-triangle47BD80 kernel
(`OriginalSphereResponse`) from the live capsule adapter. Its explicit nearest
state is caller-owned. `OriginalStaticCollision` composes source FIFO cell visits,
retry and support-grid reduction. Its caller owns body
integration, terminal callbacks and shared nearest/last-polygon reset timing.
Prepared collision metadata retains signed material archive identities and an
explicit completeness flag; source body callers must account for special contacts.
Seven original dispatcher comparisons and ten original ordinary-body reference
observations are in checkpoint/collision-body-probe.md. `OriginalBodyPhysics`
composes that static path for ordinary Jimmy flags/contacts and is used in VR04;
the live bridge supplies zero angular velocity, variable source radius60/100 and
separate published160 speed. Lab/outside retain the capsule. Special callbacks,
other original actor pair eligibility and shared dynamic reclipping remain gated.
`OriginalPairCollision` now expresses47A430's ordered physical-list pass and
47B3E0's sphere/exclusion query. It takes live actor callbacks and an explicit
mode2 solver, and preserves contacts when eligibility skips a pair.28 complete
original-component comparisons support it. It is not connected to the grouped
SceneInteractions loop: full registration/activation, real actor responses and
shared dynamic reclip state remain prerequisites. See checkpoint/pair-lifecycle.md.
Registration has separate ordinary registry50999C, physical list695D3C and own
49E flag. Common4623D0/464210 can append duplicates even when49E is already set;
Jimmy42AB50 guards the whole call.479A40 invokes Init before node append, while
46E570 runs Init then PostLoad per node and visits same-pass registry appends.
12 original-component cases support these boundaries; the full VR04 helper/
activation sequence remains open. See checkpoint/physical-registration.md.
Source root and modern feet/sole rendering are distinct adapters; F3 exit still
uses modern capsule occupancy. See checkpoint/collision-body-implementation.md.
The source-root upward ray is supplied separately from the camera debug query:
Jimmy's wrapper reflects upward velocity/cancels mode1 jump/fire before movement,
including while uncontrolled. Fresh input precedes this wrapper; retained input
follows Jimmy/fire. See checkpoint/collision-response.md and ceiling-wrapper.md.
The completed foundation includes a single synchronous Vulkan renderer supporting The completed foundation includes a single synchronous Vulkan renderer supporting
offscreen and SDL surface presentation, an independent SDL WAV stream, bounded offscreen and SDL surface presentation, an independent SDL WAV stream, bounded
GAM/PNG/scene readers, and a retained-topology morph sampler. Prepared scene JSON GAM/PNG/scene readers, and a retained-topology morph sampler. Prepared scene JSON
@@ -30,12 +132,32 @@ avoids a Python runtime dependency in native packages. Mesh draw ranges omit nul
materials following the original renderer, while retaining their geometry. Default materials following the original renderer, while retaining their geometry. Default
normal atlas and morph transforms are supported by binary/duplicate-asset evidence. normal atlas and morph transforms are supported by binary/duplicate-asset evidence.
`OriginalBodyPhysics` now retains current/previous Vec4, anchor and independent
integration/support/collision/world-response/alternate modes. World callbacks see
live state; fresh full-point equality controls candidate publication. Landing
publishes floor root/anchor/acceleration before37C, then restores cached velocity
and supported=true. Inactive paths preserve the prior per-body collision context.
This is a bounded foundation for special callbacks, not automatic scene admission;
see [body contact implementation](checkpoint/body-contact-implementation.md).
`Game/LabSimulation` supplies the no-gadget walking/jump checkpoint, using recovered `Game/LabSimulation` supplies the no-gadget walking/jump checkpoint, using recovered
speed/yaw/impulse/airborne/camera formulas. `FixedStepClock` supplies a deliberate speed/yaw/impulse/airborne/camera formulas. `FixedStepClock` supplies a deliberate
60Hz port policy independent of rendering; original invocation cadence remains 60Hz port policy independent of rendering; original invocation cadence remains
unverified. SDL events feed held keyboard/mouse state; focus/minimize clear input unverified. SDL events feed held keyboard/mouse state; focus/minimize clear input
and pause simulation, while C pauses for inspection and R resets the start area. and pause simulation, while C pauses for inspection and R resets the start area.
The Jimmy movement checkpoint uses `JimmyGroundMotion`/`JimmyAirMotion` for
source input and velocity publication, `JimmyOrientation` in the base phase
before control gating, and `JetpackBurst` for the controller/effect state tables.
Keyboard-turn latch and destination Euler/dirty are retained independently of
current Euler. Init clears the target/dirty while apply-owned air pitch seeds
survive bounded route loads. Ground pressure requires a real source-body support
polygon; the capsule does not manufacture one. JimmyRenderTransform now supplies
the full Euler hierarchical basis, source degree quantization and a modern local
sole correction around the logical root. Final OMT model decomposition remains
a separate precision gate. See
[movement stabilization](gameplay/jimmy-movement-stabilization.md).
`SceneCollision` sweeps/slides a vertical capsule against retained original scene `SceneCollision` sweeps/slides a vertical capsule against retained original scene
triangles, including invisible proxies, and clips the chase camera with a sphere triangles, including invisible proxies, and clips the chase camera with a sphere
sweep. Solver/masks/radius/pivot are explicit approximations. The physical position sweep. Solver/masks/radius/pivot are explicit approximations. The physical position
@@ -68,8 +190,9 @@ remain provisional.
TaskStates and TaskActivation retain original case/sentinel/numeric gates. TaskStates and TaskActivation retain original case/sentinel/numeric gates.
OriginalSave accounts for every TSK byte and preserves unknown data. SceneInteractions OriginalSave accounts for every TSK byte and preserves unknown data. SceneInteractions
implements star/trophy/lab jetpack contacts, Carl dialogue dispatch and LOAD requests, tracking implements star/trophy/lab jetpack contacts, Carl dialogue dispatch and LOAD requests, tracking
contact entry by source offset (duplicate tags remain distinct). Main disposes contact entry by source offset (duplicate tags remain distinct). Main owns a
renderer/window/audio before rebuilding the next scene, carrying task/items/score. RenderSession across loads, replacing scene resources and per-level audio while
preserving the window/Vulkan core and carrying task/items/score.
Checkpoint CLI saves use atomic replacement outside asset directories; complete Checkpoint CLI saves use atomic replacement outside asset directories; complete
runtime saves, menus and configuration are not yet implemented. runtime saves, menus and configuration are not yet implemented.
@@ -98,8 +221,9 @@ PracticePrompt implements source strict Yes/No regions and keyboard dispatch;
Program pauses simulation while modal, clears held input and rebuilds VR04 on Yes. Program pauses simulation while modal, clears held input and rebuilds VR04 on Yes.
SceneHud appends source640x480 screen quads; the Vulkan overlay pipeline disables SceneHud appends source640x480 screen quads; the Vulkan overlay pipeline disables
depth and draws after world geometry using identity transforms. Full HUD state depth and draws after world geometry using identity transforms. Full HUD state
and practice highlighting remain incomplete. Fixed-size authored art and practice highlighting remain incomplete. UiViewport applies uniform art scale
is scaled with the viewport; input uses matching logical-window coordinates. and explicit anchors; input maps logical coordinates into actual drawable pixels
before inverse modal mapping.
Prepared effects/effects.json preserves251 original SoundEffects.omt identities Prepared effects/effects.json preserves251 original SoundEffects.omt identities
and RIFF payloads, including one MPEG-in-RIFF resource whose playback is unverified. and RIFF payloads, including one MPEG-in-RIFF resource whose playback is unverified.
@@ -170,3 +294,89 @@ key and never enters the menu's pause/input-reset boundary. F1 selects the full
menu layout while open, otherwise the same overlay ranges display compact live menu layout while open, otherwise the same overlay ranges display compact live
diagnostics. The source viewport/projection decision supplies actual camera/far diagnostics. The source viewport/projection decision supplies actual camera/far
data. No debug visibility state is written into the original TSK wire format. data. No debug visibility state is written into the original TSK wire format.
RenderSession owns presentation until exit. Renderer replacement stages scene
buffers/textures/descriptors, preserving device/surface/swapchain/layouts/pipelines
and current targets. Resize/fullscreen replace size-dependent resources. Revision
and native identities support checks. See presentation-and-ui.md for rollback,
widescreen policy and runtime verification boundaries.
## Bounded ordinary-load character state
PlayerLevelState is separate from OriginalSave: it carries only mode, jump-hold
and owned-fire timer across proven LV1B/VR04/LEV1 no-gadget/jetpack transitions.
Run reconstructs destination resources/body and applies these scalars before
playback. Source jump state resets independently; TSK/debug checkpoint loads get
no transient carry container. Source retained identity does not justify persisting
all physics/AI/render fields. The detailed contract, phase limits and original
component probe are in checkpoint/retained-player-body.md; companion/shadow
resets and full availability tails have separate reports. Uncontrolled physics
and exact appended-helper traversal remain next scheduler boundaries.
## Player control versus frame ownership
PlayerSceneBinding connects authored preparation/transform events to the player
adapter. Body integration and owned fire run without player control; only input
and movement math are gated. CAM/MCA/AI preparation has distinct order and operates
on the prior raw owner, while Force Control affects effective input. Ordinary
frame/modal/debug pauses stop all these phases. Scripted AI roots/yaw flow into
physics, and physical roots flow back to director/camera targets. Destination yaw
and queued work are not cleared by a transform setter. The original full wrapper,
registry, body response and morph clock are still not reconstructed by this bridge.
See checkpoint/control-phase-implementation.md. REA tooling is separate from
runtime architecture; setup/provenance are in rea.md.
## Owned aircraft
Rocketship composes RocketFlight, RocketMotion, RocketOrientation and the source
static-body/camera adapters in boundedVR02. PlayerSceneBinding schedules ship and
Jimmy bodies before the fresh/retained input/normal boundary, transfers control
to the registered3ROC and synchronizes the still-physical passenger afterward.
Raw control and inventory permission remain distinct from named-Jimmy scripted
cleanup. Release disables ship integration, stops engine/fire, retains rider root
and shared eye, and returns Jimmy to FALL. Four dedicated source-pivot morphs
replace the standing player draw while mounted. Source/probe/port validation and
unresolved lifetime/pair/camera boundaries are in gameplay/rocketship-live.md.
Grappler's distinct source ownership and
geometry/material/swing contract is in gameplay/grappler.md; it is not a simple
player movement mode or nearest-tag interaction.
GrapplerMotion implements the isolated attachment/reel/damping arithmetic and
independent fire/jump detach predicate, compared with30 copied-original cases.
It owns no body/ray/camera/helper lifetime and is not called by live simulation;
integration gates and retained source/REA findings are in gameplay/grappler-component.md.
GrapplerGeometry adds source aim early-return/rope-constraint/post-base contact
rules. GrapplerRay binds the verifiedVR08 static profile and captures selected
polygon/material with the hit via OriginalCameraRay.TraceSelectedGeometry, which
is independent of camera debug disabling. No live simulation calls these yet.
The active-input return must gate later primary dispatch while normal Jimmy frame
publication continues. Shared collision context/base contact and helper/camera
ownership remain integration work; see gameplay/grappler-query.md.
## Live bounded VR08 Grappler (2026-11-04)
The component-only gates described above are now integrated for VR08. Main owns
GrapplerMemory across Run/scene reconstruction; LabSimulation owns the scene's
GrapplerGadget and body/camera state. Normal physics retains its sphere context,
then fresh controlled input runs camera followed by attached movement/aim/fire;
ordinary player apply still runs after an input early return. Retained entry
moves input after ordinary apply, preserving the existing registration boundary.
Attached Move reuses the preceding physics context, including stale last polygon;
support/ray metadata is separate. Both normal and attached wall callbacks reach
the recovered post-base detach rule. No new body integrator or direct-pull path.
Camera locals retain their source writers; GrapplerCamera consumes them through
movement-mode-specific follow branches, obstruction and old shared-eye aim.
GrapplerVisuals appends exact prepared rope/SWING/target resources and draws at
source pivots. It applies the retained first-length scale to base rope geometry,
uses pre-collision desired root and replaces the standing draw only during SWING.
The existing generic sprite-facing bridge remains a documented rendering policy.
PlayerSceneBinding handles selection, companion eligibility and authored cleanup.
RETURN explicitly releases selected Jimmy before staging; ordinary scene teardown
releases scene-local helpers/sound before SceneAudio disposal as a modern safety
boundary. Scalar memory survives; original TSK serialization is not expanded.
F3/R debug cleanup is separate from source ownership semantics. See
[coverage and verification](gameplay/grappler-live.md) for113 component observations,
13 live managed groups, native replay and excluded shared/special-level behavior.
+75
View File
@@ -0,0 +1,75 @@
# Architecture checkpoint
This records the completed architecture checkpoint. The existing port is a preserved baseline and a tool
for testing interpretations. This checkpoint connects original state ownership,
update order and lifecycle to the lab → VR04 → lab → outside route; it does not
require recovering every level or certify complete gameplay fidelity.
Start with [baseline](baseline.md), [coverage map](coverage.md),
[loop and motion](loop-motion.md), [script/state route](script-state-route.md),
[camera/audio/UI](camera-audio-ui.md), and [implementation plan](implementation-plan.md).
Core reports and [input/frame bridge](input-frame-bridge.md) have returned to
primary ownership. Follow-ups cover [lab registry](lab-registry.md),
[camera ray](camera-ray-predicate.md), [voice clock](voice-clock.md), and
[scene loader](scene-loader.md). All investigators have returned file ownership.
Primary owns integration/runtime corrections. [Exit review](review.md) records
checkpoint completion, verified changes and the next evidence gates.
Implementation continuation: [level-game lifetime](level-game-lifetime.md),
[retained character resets](retained-character-reset.md), and
[player phase implementation](player-phase-implementation.md). These supersede
the old-game-removal question and record the first C3/C5/C7 implementation chunks.
The retained-field continuation adds [property reader](retained-streamer.md),
[RETURN cleanup and full availability tails](retained-return-cleanup.md),
[player body/scalar boundary](retained-player-body.md) and
[companion/shadow resets](retained-companion.md). It corrects the earlier
availability-prefix interpretation and implements bounded route scalar carry.
The next C3 continuation is [control phases](control-phase-implementation.md),
backed by [uncontrolled player](uncontrolled-player.md),
[physics eligibility](uncontrolled-physics.md) and
[cutscene preparation](cutscene-preparation.md). [REA setup](../rea.md) records
local Ghidra/JDK and Evidence/snapshot use.
C4 continuation: [sphere response](collision-response.md),
[ceiling wrapper](ceiling-wrapper.md) and [physical re-registration](body-root-registration.md).
The source kernel is isolated/probed; live capsule replacement remains gated.
[Shared camera handoff](camera-handoff.md) records the next C5 state correction.
The next C4 chunk adds [grid traversal](collision-grid-traversal.md),
[contact/material/friction ownership](collision-contact-callbacks.md) and
[dispatcher/body component probes](collision-body-probe.md). The source dispatcher
is implemented and compared with isolated original outputs; whole-body/live
integration and special contacts remain gated. [Independent review](collision-integration-review.md)
records corrections and remaining limits.
The [ordinary-body implementation](collision-body-implementation.md) composes the
ten numeric references and enables the static subset in VR04. Its
[source contract](collision-body-composition-source.md) closes phase/radius fields;
[implementation review](collision-body-implementation-review.md) preserves remaining
dynamic, special-contact, initialization and modern noclip/render boundaries.
User-directed gadget continuation is in ../gameplay/gadgets-implementation.md.
It supersedes older inferred gadget names: raw mode0 is Bubble, menu item3 is the
combined shrink-ray/jetpack and its normal equipped mode remains−1. Numeric
collision findings remain valid independently of those old labels.
Evidence labels used throughout:
- **Recovered:** static instructions, serialized original data, or a specifically
named isolated-original probe. Preferred image VAs and PE-mapped file offsets
refer to the hashed supplied binaries, not ASLR runtime addresses.
- **Inference:** an interpretation whose missing callers, ordering or filters are
explicitly listed. It is not promoted to fact because a replay looks plausible.
- **Implementation:** what this port currently does, including modern policies.
- **Verification:** state separately whether a source-byte check, managed test,
port runtime, isolated original component, or full original runtime was tested.
Earlier analysis documents retain useful evidence but can describe older
implementations. This checkpoint supersedes their architecture/priority summaries;
focused reports remain authoritative for their cited instructions/data. In
particular, movement mode1 reaches the airborne fall-through path, TSK writing is
recovered, and source per-level far planes are recovered; broad older statements
that those are wholly unknown are stale.
Checkpoint exit requires every requested core system to have an evidence anchor,
owner/lifetime, interaction mapping, baseline comparison, explicit unknowns and a
bounded next action. Completion means enough architectural coverage to execute the
plan, not complete disassembly or original gameplay comparison. Preserve unresolved
questions as gates on individual plan chunks, not a reason to block all work.
+210
View File
@@ -0,0 +1,210 @@
# Original normal callbacks and late scalar reads
2026-11-07. Continues [populated reclip](dynamic-reclip.md). Thirty complete
emitted original/C# fixture snapshots now match exact float32 values and event
order. `OriginalNormalContacts` implements the bounded inherited ceiling/wall/
reflection callbacks as a standalone component. Live actor admission and the
current body/profile wiring are unchanged.
## Evidence, layout and class coverage
Canonical Neutron.exe SHA-256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Retained complete REA instruction Evidence:
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`.
`tools/binary/actor_contact.py` guards17 complete bodies,139 relocation operands,
13 actual VR04 interfaces/182 method bindings and5 scalar getters. Source hashes,
table/file offsets and pointer displacements are local in
`artifacts/actor-contact/native/source.json`. Text offsets below equal VA−400000;
the helper uses actual PE mapping.
| Callback VA / file offset | Owner / complete span |
|---|---|
|42A660 /2A660|Jimmy374, through42A714.|
|43AA40 /3AA40|Player material policy, through43AFE3.|
|472690 /72690|Inherited370 positive-Y response, through47274A.|
|458890 /58890|Inherited374 reflection gate, through4588CD.|
|472750 /72750|Inherited378 reflection/heading impulse, guarded through472970.|
|409590 /9590|Soldier374 override, through4095EE.|
Prior REA pseudocode is reused for472690
(`ev_122849f87121b02fefe6a3a443f75c7f02fee30c59c816b617d30e1f98fc2cff`),
458890 (`ev_2e4ec83ea68f06777162a80ab45793cff068e973dc248556d4a408932d24c85a`)
and43AA40 (`ev_4f2a6aa666451db831efd46f5c587573e22d8072315626b8bc2f844f9c6f0cae`).
The new REA/Ghidra requests for409590 and4098C0 both report unrecognized
procedures. Their complete failures, export and closed-session snapshot are
retained under `artifacts/actor-contact/rea/`; no successful pseudocode is
attributed to them. Existing REA instructions, canonical bytes and new copied-code
execution support the bounded caller findings instead. Earlier unrecognized
42A660/472750 requests were not repeated.
Jimmy game table4A373C selects374→42A660; soldier4C19C4 selects409590;
Rocketship4B25AC selects43E8D0 and its separate370→43EB70. The other10 serialized
VR04 interfaces use374→458890. All13 bind378→472750. Tables and complete-object
displacements are recorded separately: some interfaces are+C8 rather than+C0.
Class bindings do not establish active physical membership or constructor defaults.
The sampled offsets are class-specific beyond the shared base. Soldier608 is an
integer state; Jimmy608 is its controller speed float. Player704 movement mode
is separate from physical collision mode178. The composition fixes178 to0;
the direct `jimmy_mode2` fixture changes704, not box-vs-box collision mode.
Snapshot labels do not define a universal actor structure or shared mode enum.
All13 share these pure live-field getters:
| Slot → function VA / file offset | Interface-relative field / use |
|---|---|
|1D0→4718F0 /718F0|byte13C, per-body geometry permission.|
|1D8→471910 /71910|byte13D, inherited wall-reflection gate.|
|1E0→471930 /71930|byte137, box response inhibition.|
|248→471AD0 /71AD0|float150, wall damping.|
|260→471B30 /71B30|float15C, live radius.|
These are source field/read facts. The native fixtures supply explicit accessor
stubs so they can log reads and inject changes; they do not execute these getters
on constructor-created actors. Scene global4F69E5 is a different owner from1D0.
The constructor/property/Init lifetimes of these fields are not established by a
vtable binding alone.
## Recovered policies and state transitions
**Jimmy:**42A660 forwards to43AA40 on ordinary selections, including−1 and
jetpack3.43AA65 explicitly accepts a null polygon, using material sentinel−1.
Neither ordinary/null contact nor rejected elapsed<=3 material contact reaches
generic reflection378. Test modes0/1/2 and raw-control NULL preserve velocity,
acceleration, angular state and root; no control query occurs in this handler.
VR04 has no special material IDs, as previously established in
[material contacts](collision-contact-callbacks.md). Actual lab/outside hazard,
FENCE and LADDER success remain separate gates.
The additional gadget7/active branch zeros globals4F82BC/C0, tests their prior
two-component magnitude **strictly greater than60**, then invokes complete204
and sets interface1D65.36/48 is equality and issues no204;36/49 does. Our204 is a
record-only endpoint, not the actual429C10 cleanup. This does not change live
grappler behavior or recover every cleanup effect.
**Inherited ceiling370:**472690 reads velocity, clears strictly positive Y
through2C0, then independently reads acceleration and clears its positive Y
through274. Negative channels survive independently. There is no generic
position, movement-mode, jump or control reset. The adapter distinguishes full
Vec4 writes from the wall callback's XYZ setter.
**Inherited wall374/378:**458890 first reads1D8; false returns before velocity
normalization.472750 snapshots horizontal velocity, stores its quick magnitude,
normalizes with the retained quotient and reflects using the supplied normal.
It reads velocity again for live Y, then248 damping, then publishes XYZ through
2C4. Damping is not clamped:1.25 reverses the damped horizontal result.
After publication, the source calls copied OMT `angles` twice: old normalized
horizontal direction, then normalized reflected horizontal direction **before
damping**. It wraps oldHeading−newHeading once at strict±180 and adds angular Y:
```
heading delta degrees × old horizontal quick magnitude × float32(0.001)
```
The factor is4D5FD8; angles import48D108 is
`?angles@OMedia3DVector@@QAEXAAF0@Z`. The source's raw yaw uses the14-bit circle,
e.g.9870 and14706 for the oblique fixture. `OriginalHeading.Angles` is a signed
consumer view; masking yaw with16383 recovers that raw circle. Its behavior is
unchanged; its comment now makes the distinction explicit.
Axis velocity(0,7,−40), normal+Z, damping.25 gives velocity(0,7,30) and angular
Y9.20000076 from initial2. Oblique(30,7,−40) gives velocityX22.5000019 and
angularY−3.31300402. Angular response remains independent of damping. A synthetic
second velocity getter returningY99 proves that the second read owns the
published Y; it is an accessor-order test, not observed spontaneous actor mutation.
**Soldier:**409590 calls generic458890 first. It then checks interface608==10
and, independently of reflection being enabled, calls complete174 with force500
and the supplied normal. Complete table4C1E64+174 targets4098C0. That callee
begins by advancing RNG through509A40 twice, then reaches target/action-dependent
branches. Its complete policy is not executed here. The fixture records174 and
optionally changes scalar fields to test the enclosing caller, not to claim
that the real soldier naturally performs those changes.
## Dynamic composition and late ownership
Three cases invoke complete original47A5E0 with real Jimmy/generic/soldier normal
callbacks. Four more use the soldier's record-only174 endpoint to change one
dependency after its dynamic callback:
| Injected change | Original/C# result |
|---|---|
|Box inhibition=true|Contact remains true; root staysZ15, radius reads[10], no static pass or314.|
|Radius10→20|Reclip reads[10,20,20], rootZ55 against wallZ35; cached10 would give45.|
|Scene geometry=false|Static primitive is skipped but retained polygon still gives a second normal callback; rootZ20.|
|Sphere42C=true|Static force flag is visible to reclip; rootZ45, radius reads[10,10,10].|
Static callbacks can therefore run the full generic/soldier chain again. In
these fixtures, the second reflection gives velocityZ−22.5 and angularY3.80000067.
The final local root still publishes after callbacks. There is no added implicit
context reset or root-changed guard.
The C# dynamic composition remains test-only. Its static getters are fixed
between primitive passes; the fixture records repeated identical radius reads
before the sole terminal callback. This is not a reusable live getter/reentrant
dispatcher, linked-list mutation policy or proof of real actor registry ordering.
## Probe correction and implementation boundary
The initial numeric relocation scan selected bytes4095BE..C1 (`8B C4 68 00`)
spanning `mov eax,esp` and `push500`, misreading them as pointer68C48B. It also
selected other cross-instruction sequences. This corrupted the **private probe
image**, causing a derived-dispatch fault. Those partial runs are invalid source
behavior evidence and are retained as diagnostic failures only. Originals were
never patched. The corrected generator uses37 individually reviewed callback
operands within complete REA instructions:139 total rather than152. A regression
explicitly rejects4095BE and guards the original seven bytes. The final30-case
capture exits0 with all source/probe hashes verified.
`OriginalNormalContacts` and `IOriginalNormalBody` preserve the recovered getter/
setter order, XYZ/full-vector distinction, reflection and angular tail. The
standalone component is not substituted into the live Baseball, Jimmy or NPC
profiles. Zero horizontal normalization remains an explicit unsupported source
arithmetic boundary; the component throws rather than silently admitting a new
policy. A disabled reflection gate returns before that boundary. General x87,
arbitrary normals and zero/degenerate cases are not certified by these fixtures.
`tests/GamePort.ActorContactTests` keeps30 fixed snapshots and can compare the
generated native observations with `--native`; `--dump` plus the Python helper's
`--managed` produces complete exact-float32 differences. Snapshots include roots,
velocity/acceleration/angular XYZW, two modes, marker/tether, derived endpoint
calls/arguments, flags, radius samples, raw angle arguments/results, context
counters/limits and the full emitted accessor event order. Jimmy no-effect paths
and the two derived endpoints are bounded fixture logic, not complete new Player,
grappler or soldier implementations.
## Next chunk
Recover the soldier174 policy and helper cleanup/activation/physical order across
LOAD/RETURN; retain special Jimmy material and gadget gates. The next response
adapter must preserve post-callback1E0, live radius/42C and per-node scene-geometry
ownership, and may admit only explicitly supported actor states. Keep lab/outside
capsule and current VR04 static body while those dependencies remain. Final tests,
build identities and runtime limits are recorded in progress.md/compatibility.md
and `artifacts/actor-contact/validation.json`.
Reproduce after preparing and fully copying the disposable Wine prefix:
```sh
python3 tools/binary/actor_contact.py ../Original --output artifacts/actor-contact/native
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wno-unused-function -o artifacts/actor-contact/native/probe.exe artifacts/actor-contact/native/actor_contact_probe.c
python3 tools/recon/reference_capture.py --asset-probe --probe-executable artifacts/actor-contact/native/probe.exe --probe-success ACTOR_CONTACT_COMPLETE --seconds 45 --output artifacts/actor-contact/probe
python3 tools/binary/actor_contact.py ../Original --output artifacts/actor-contact/native --capture artifacts/actor-contact/probe
source scripts/env.sh
dotnet run --project tests/GamePort.ActorContactTests -- --native artifacts/actor-contact/native/observations.json
```
Normal response is separate from pair enter/stay/leave notifications and their
game/task effects; those real consumers remain an admission gate too. In
particular, an inhibited position response does not cancel pair membership.
Verification:352 Python checks,30 native/fixed managed snapshots,5 sphere groups,
11 static groups,20 ordinary-body groups,100 complete body-ownership comparisons
plus6 bounded state cases,28 pair cases,17 prior context cases and14 populated
reclip/12 kernel steps pass. Linux Debug builds with zero warnings/errors;
Windows x64 self-contained cross-publish succeeds. All539 originals and both
924ad2f packaged DLLs/BUILD-INFO remain unchanged. No new SDL/Vulkan or Windows
execution is claimed; the latest integrated render/native SDL evidence belongs
to bf876e9. This unused component does not change live profile wiring.
+25
View File
@@ -0,0 +1,25 @@
# Preserved playable baseline
Baseline: `69d0187a2178deab1edff961d5126dad1cce3a05`, clean source tree at checkpoint
entry, local annotated tag `baseline-re-checkpoint-2026-10-25`. Existing Linux and
Windows packages were copied, without hard links, to
`artifacts/re-checkpoint/baseline/{linux-x64,win-x64}`. Their BuildInfo records
identify69d0187 and clean source. These ignored local copies are comparison tools;
subsequent builds must not overwrite them.
`artifacts/re-checkpoint/original-preservation-start.log` verifies all539 original
files against `docs/original-manifest.json`. Originals were read, never modified or
executed in place. All work remains local. A pre-existing `Gitea` Git remote is
configured; it was not contacted or changed. No fetch/push/remote-service operation
was performed. Older notes saying the repository has no remotes are stale.
The user has traversed lab → tutorial → lab → outside in their Windows build.
Earlier Linux managed, GPU and SDL tests demonstrate port behavior; package
cross-compilation and Wine checks do not establish native Windows verification.
No usable running-original gameplay capture exists. Static code evidence and
isolated DLL probes must not be reported as original end-to-end verification.
Modern authorized baseline policies include F1/F2 diagnostics, persistent SDL/Vulkan
presentation across level changes and uniform widescreen UI. They are not claims
about the original. Fixed60Hz simulation, provisional player capsule/feet grounding,
grouped system phases and duration-driven camera completion remain fidelity gaps.
@@ -0,0 +1,110 @@
# Body callback ownership implementation
2026-11-05. Continues Jimmy movement after the air/render checkpoint27be8ed.
Current lab/outside capsule and all special-contact admission gates are preserved.
This implements the body publication/mode prerequisites, not new climb/hazard
mechanics or a complete original body in every level.
## Evidence and implementation
[Root publication](body-root-publication.md) records19 new original component
cases using actual copied479D20/47B4B0/kernel. [Body modes](body-modes.md) records87
new observations using full479D20/support/friction and a synthetic dispatcher.
Both reuse retained REA Evidence and guard original spans/offsets/provenance.
`OriginalBodyState` now retains finite live-root W, source previous Vec4, support
anchor and independent `BodyModes`: integration210, support1C8, collision220,
world response1D0 and alternate228. Nullable modes mean the ordinary constructor
defaults; the explicit point constructor supplies W1. Scooter reset now uses that
point constructor instead of zero-initializing W through default(struct).
`OrdinaryBodyStep.PreviousPosition` deliberately stays the frame-entry XYZ
diagnostic consumed by the existing provisional dynamic adapter. It is not used
as a substitute for the newly retained previous Vec4.
- Support clear precedes the integration gate. Inactive integration preserves
roots, anchor, pending work and the existing collision context, then returns.
- The geometry argument/global getter remains independent of body modes. Global
geometry-off follows the recovered gravity/support policy. A scene getter
optionally models support's fresh global read after callbacks.
- World response-off copies current root to previous and translates, retaining
gravity/impulse, optional support/friction and the previous static context.
- Collision-off translates or holds according to228, preserves previous root,
skips support/friction and still reaches suppression. Neither unclipped branch
acquires the world branch's−25000 candidate clamp.
- World callbacks now receive the live entry root, not the tentative clipped
candidate. They may edit live/previous independently. Fresh XYZW equality
controls publication of the precomputed candidate and its original W. Callback
roots rejected by that barrier receive neither old fallingY nor candidate clamp.
Changing both roots to equal still permits the old candidate to overwrite them.
- Support uses fresh live/previous XYZ after publication/rejection. Landing37C
observes the floor root, anchor and zeroed vertical acceleration but old velocity.
Callback root/anchor/acceleration/impulse/modes survive; source cached VX/Z plus
Y0 and supported=true are published afterward. Friction/suppression read current
speed/motion and retain their own ownership.
- The existing wall hook remains wall-only. Ordinary/profile ceiling/reflection
behavior is kept separate. Static context resets only in the world branch;
other branches retain it, reporting zero new traversal work.
`tests/GamePort.BodyOwnershipTests` compares81 complete native mode/landing outputs
and19 root outputs. The17 native root-isolation cases no-op support; the managed
support gate mirrors those publication outputs, while two cases execute actual
support in both implementations. For six native synthetic-dispatch mutation cases,
a real wall delivers the managed callback: owned state/flags/branch continuation
compare, while intentionally different clipped XYZ is not claimed as numeric
conformance. All100 complete comparisons and six state comparisons pass.
Existing20 body,13 Scooter and13 Grappler groups pass in initial targeted runs.
Artifacts: artifacts/body-contact-integration/{ownership-initial,body-initial,
scooter-initial,grappler-initial,build-initial}.log. The full regression, native and
package results are recorded below as verification finishes.
## Remaining integration boundary
No real Jimmy material120..129/110..119/FENCE/LADDER callback is enabled here.
Animation acceptance/end/fallback, hazard/impulse updater4255C0, successful ray
filters, control/facing/action state, dynamic eligibility and scene-wide shared
collision globals still need separate recovery and runtime proof. No callback is
classified ordinary merely to bypass constructor rejection.
LabSimulation still reconstructs the admitted ordinary body each pass; actual
multi-frame special modes must persist actor state when their callbacks are
integrated. Vehicles/projectiles already retain their body records. The per-body
static context remains a bounded approximation of original scene-global ownership.
Radius/factor/friction/suppression arguments remain fixed during the admitted
pass; reentrant/nested body updates and other mutable getter side effects are not
established by these finite probes. Modern F3 noclip is a separate policy.
The root record adds no TSK/save fields or runtime original-code dependency.
Physics remains independent of raw player control. The existing rendering/air
state and upright local alignment from the previous checkpoint are preserved.
## Final regression and native verification
Full scripts/test.sh exits0:333 Python tests,2 HUD extraction checks,45 managed
projects,36 main Vulkan render completions (zero validation errors), original
asset decoders, lab/underground routes, saves, animation and SDL dummy audio
lifecycle, plus539 unchanged original hashes. The main restore/build emitsNU1900
warnings for unavailable vulnerability metadata; no compilation errors occur.
Packaging uses cached dependencies with NuGetAudit=false. Logs and structured
summary: artifacts/body-contact-integration/full-tests.log and validation-summary.json.
Native Linux GTX1070/private Xvfb1920×1080 passes both10-stage Scooter replays,
right-mouse VR04 jetpack, Shift lab walking and control phases with received SDL
input/resize and zero Vulkan errors. All five Jimmy final/airborne captures match
the preserved air-bridge baseline byte-for-byte; baseline-readbacks.json records
that comparison. Default gameplay/scene collision admission is preserved.
## Packaged checkpoint
Both self-contained platform packages identify clean runtime commit
`c9d0c5be59eedba3a92dcd46d1beb96b2e9e941a`, source_dirty=no.519 original copies
and4271 prepared scene/resource files match in each; package-identity.json records
binary/build identities. Standalone Linux from /tmp with SDK variables unset
passes both Scooter scenes and Jimmy walking/jetpack. All27 stage/final readbacks
match development exactly, with zero enabled Vulkan validation errors. Logs:
package-{scooter-vr05,scooter-outside,walk,jetpack}.log and package-readbacks.json.
Post-package audit verifies all539 originals unchanged. Windows cross-publishing
and resource checks remain separate from pending native Windows and original
whole-game comparison. Documentation commits after the runtime revision record
validation; package BUILD-INFO.txt retains exact source provenance.
+131
View File
@@ -0,0 +1,131 @@
# Body modes and post-callback ownership
2026-11-05. This closes a bounded prerequisite for Jimmy's special contacts; it
does not enable new terrain/climb policies or replace the lab/outside capsule.
The authoritative EXE SHA256 is
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
JN-Engine gameplay is not the oracle. Retained REA instruction Evidence
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`
is artifacts/jimmy-movement-audit/rea-original-disassembly.json; the original
479D20 procedure Evidence is
`ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0`.
No unchanged failed Ghidra selector was repeated. This investigation reuses those
instructions and independently guards the complete body/support/friction spans.
## Source branch and state map
Addresses are EXE VAs; raw offsets equal VA−400000 in these PE-mapped spans.
Slot numbers refer to the body/game interface, Jimmy complete object+C0.
The generic data fields and initialization are separately recorded in
[body composition](collision-body-composition-source.md).
| Source VA / raw offset | Recovered phase |
|---|---|
|479D2E/479D34 /79D2E/79D34|Read supported218; cache prior support695D49 even if integration will reject.|
|479D3D..479D4E /79D3D..79D4E|If support handling1C8, clear supported21C(false). Otherwise preserve the previous supported flag.|
|479D58..479D60 /79D58..79D60|Integration210=false returns after those effects: root/previous/anchor, impulse, velocity, acceleration, angular velocity and static context remain unchanged.|
|479DDA..479E54 /79DDA..79E54|Global geometry4F69E5=true publishes anchor(0,−25000,0). False publishes supported=true, anchor(0,currentY,0), acceleration(0,+800,0), velocity(oldX,0,oldZ). Pending impulse still applies later.|
|479E63..479FD2 /79E63..79FD2|Rotate by angular×dt; consume impulse once; add acceleration then gravity separately; compute displacement from final velocity.|
|479FD6 /79FD6|Collision220 gates the post-integration branch.|
|479FE8 /79FE8|When collision=true, world-response1D0 selects clipping versus direct translation. This is not the integration/global-geometry gate.|
|47A038..47A096 /7A038..7A096|World branch alone resets last polygon/nearest face130000/nearest edge radius/auxiliary; captures full live root into previous2FC, then dispatches world traversal.|
|47A123..47A1C4 /7A123..7A1C4|World path compares fresh previous/live Vec4; equality permits candidate clampY≥−25000/publication314. See the independent root-publication investigation.|
|47A1CC..47A220 /7A1CC..7A220|Collision=true/world-response=false copies live Vec4 to previous, then translates31C(displacement). No static-context reset, world dispatch or−25000 clamp.|
|47A22A /7A22A|Fresh support1C8 read after world callback/publication/direct translation; true calls47B890.|
|47B890 /7B890|Support independently rereads global geometry. False skips its query/result publication; it does not retroactively cancel the gravity already consumed earlier in479D20.|
|47A241..47A25A /7A241..7A25A|Fresh published-speed268==0 enters friction47A330. That helper reads current supported218 and only damps when supported and magnitude>0.|
|47A264..47A28E /7A264..7A28E|Collision=false reads alternate228: false translates31C; true holds root. Both skip previous-root copy, support and friction.|
|47A294..47A31D /7A294..7A31D|All integrated branches reach suppression. Angular and linear quick magnitude×scale≤.1 clear the respective velocity; linear additionally requires a fresh published268==0. Rotation already happened, even if angular velocity is then cleared.|
A support-disabled body may retain supported=true, including while moving upward.
If collision is enabled, that stale-but-owned supported state still allows
friction. Disabling support is not permission to clear it unconditionally.
Collision-disabled bodies skip friction even when global geometry-off forced
supported=true. World-response-off retains integration, gravity, impulse,
optional support and friction, plus the prior static context. F3 noclip remains a
separate modern policy.
## Flag mutation timing
The source does not reselect a branch already entered. Synthetic world callbacks
that change integration210, collision220 or world1D0 still finish the selected
world publication/support/friction path in the current call. The changed flags
persist for a later call. Support1C8 is read fresh after world dispatch, so changing
it there suppresses the current support query. Global geometry is also read fresh
inside support; changing it during world work suppresses support while retaining
the already integrated gravity/acceleration and earlier anchor.
For example, the final native fixture's world mutation5 changes global geometry
to false after integrating fallingVy−213.333328. The output still has that Vy,
acceleration0 and anchorY−25000, with no support query; it is not the early
geometry-off result with acceleration+800/support=true/vertical cancellation.
A mutable scene-global getter can represent that read boundary; embedding a new
per-body geometry flag would misstate its ownership. No live original writer or
new gameplay use of that global is inferred from the synthetic callback.
## Landing37C: writes before and after callback
47BB10..47BB4B publishes anchor, supported root through318 and acceleration
(oldAx,0,oldAz). It checks prior supported695D49 and invokes37C at47BB5E only on
an unsupported→supported transition. The callback observes the new root/anchor/
zeroed vertical acceleration but old live velocity and supported=false.
47BB64..47BB80 then overwrites velocity with **cached pre-callback VX/Z and Y0**,
and writes supported=true. Support pointers34C/33C follow at47BB91/47BBA1.
Consequently:
- Callback velocityXYZ and supported edits are overwritten, even though the
callback legitimately owned them during its invocation.
- Callback root (including W), acceleration, anchor and pending impulse survive.
Pending impulse is not consumed a second time; its next owner is a later body pass.
- Modes and published speed survive. Published speed is read fresh by friction;
changing it to100 skips damping in the same call.
- Callback angular velocity survives into friction/suppression; with(7,123,9),
friction.8/dt1/60 yields approximately(6.906667,121.360001,8.88).
- Changing support/collision/integration modes during37C does not rerun preceding
branches or stop the support function's final supported=true publication.
The native payload cases verify each item. They do not execute Jimmy's real37C
(which is an inherited no-op), an animation event or a special Player callback.
They establish generic phase ownership for safe composition.
## Copied-original fixture and verification
`tools/binary/body_modes.py` reuses the existing read-only body/support range and
relocation collector. Generated sources are separated from the Wine work/prefix
under artifacts/body-modes/generated. The probe executes full copied479D20,
47A330 friction and47B890/support queries against the existing synthetic floor.
Its47B4B0 world dispatcher is deliberately substituted: it adds the supplied
movement to the candidate and performs selected synthetic flag mutations.
Angular334 is a simple additive synthetic virtual, not proof of generic angle
normalization. The copied original OMT quick-magnitude export is retained.
No real world traversal, actor, loader/game entrypoint, animation or audio runs.
The final isolated Wine32 run exits0 with BODY_MODES_COMPLETE.87 observations:
64 combinations of integration/support/world/collision/alternate/global geometry;
6 world-mutation cases;11 genuine landing-mutation cases;6 no-clamp/suppression
extras. Source, generator/shared harness/generated EXE/log hashes and all numeric
vectors/counters/event traces are committed in tests/body-modes-reference.json.
The initial landing setup had prior support=true and therefore correctly emitted
no37C; it was corrected to unsupported before using those cases as callback
evidence. A regeneration attempt into the parent directory containing a Wine
prefix was rejected by the symlink guard; separate generated output resolved it.
Only the final87-case run is retained as the committed conformance fixture.
Four Python groups pass: identity/ranges/provenance, all64 branch/counter/context
combinations, callback/suppression observations and generated-output separation.
Run from GamePort:
```
python3 -m unittest discover -s tests -p test_body_modes.py -v
python3 tools/binary/body_modes.py ../Original --generate-probe artifacts/body-modes/new-generated
```
Parent owns managed integration and its conformance claim. Source-world mutation
outputs depend on the synthetic unclipped dispatcher candidate; a real-wall
adapter may compare branch/state invariants without claiming candidateXYZ parity.
All64 flag cases,11 landing payload cases and6 no-clamp/suppression cases permit
full numeric body comparison under the corresponding floor/empty-world fixture.
Contact metadata, root-changing Vec4 publication, special animation/control and
dynamic body eligibility remain independent gates. Whole-original gameplay and
native Windows movement are not established by these component calls.
+135
View File
@@ -0,0 +1,135 @@
# Contact-owned Vec4 root publication
2026-11-05. Follow-up to [body composition](collision-body-composition-source.md)
and [special contacts](jimmy-special-contact.md). This closes one body-state
boundary; it does not enable special contacts or replace the lab/outside capsule.
Original Neutron.exe SHA256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
## Source structures and phases
All VAs below are independently PE-mapped; raw offsets equal VA−400000 for these
ranges. REA's retained complete EXE disassembly is
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`,
artifacts/jimmy-movement-audit/rea-original-disassembly.json. Earlier body Evidence
`ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0`
and its prototype limitations remain in the composition report. No unchanged
failed Ghidra selector was repeated. Instructions establish the following facts;
original component execution corroborates their numeric consequences below.
Jimmy uses the game interface at complete+C0. **Data** previous-root Vec4 is
interface1F4/1F8/1FC/200 (complete2B4..2C0); current-root Vec4 is
interface214/218/21C/220 (complete2D4..2E0). These are not same-numbered virtual
slots. Vtable4A373C binds previous getter2F8→4721E0, previous setter2FC→472240,
live getter310→472300 and Vec4 setter314→472360. Each getter copies all four
floats into the caller buffer.314 is a plain four-float store; unlike XYZ318's
472330 wrapper, it does not immediately call3DC. Full logical/render publication
ownership therefore remains distinct from the body-state store.
| VA / raw offset | Recovered operation |
|---|---|
|47A084 /7A084|After integration and before world dispatch, copy current full Vec4 into previous2FC. A stale initial previous root does not survive this boundary.|
|47A0D6 /7A0D6|Positive displacementY:47B4B0 receives fullXYZ.|
|47A10F..47A11F /7A10F..7A11F|NonpositiveY:47B4B0 receives XZ/zeroY, then add the original already-computed fallingY to the **candidate**, after dispatcher/contact returns.|
|47B80F /7B80F;47B82E /7B82E|Dispatcher terminal374/370 receives actor/normal/polygon, not the candidate pointer. The bounded dispatcher call closure has no actor310/314/2FC root publication before those callbacks. It modifies the separate candidate.|
|47A12C /7A12C;47A13D /7A13D|After dispatch/contact, read fresh previous2F8 and then fresh current310 into separate stack buffers.|
|47A143..47A181 /7A143..7A181|Compare X,Y,Z,W. Only equality through all four comparisons reaches candidate publication.|
|47A187..47A1C4 /7A187..7A1C4|Only the permitted candidate has Y clamped to−25000, then full Vec4 is stored through314. A rejected callback-owned live root is neither displaced nor clamped here.|
|47A22A..47A235 /7A22A..7A235|Support eligibility is read afterward. Support47B890 can run even when publication was rejected; it reads current/previous afresh.|
For admitted finite values, the useful projection is:
```
previous = live // world branch entry
candidate = dispatch(entry, full or XZ delta)
if falling: candidate.Y += precontactDelta.Y
previousNow = getPrevious(); liveNow = getLive()
if previousNow.XYZW == liveNow.XYZW:
candidate.Y = max(candidate.Y, -25000)
setLive(candidate) // candidate W, not callback W
supportIfEnabled() // uses current/previous now
frictionAndSuppression() // source state remains independently owned
```
This is not `callback changed Position => skip`: changing **both** previous and
live to equal values permits the old candidate to overwrite that change. Changing
only previous can reject publication even when live XYZ stayed at entry. Changing
only W can reject it even when all XYZ match. The initial entry root remains a
useful diagnostic, but must not substitute for the fresh source previous record
when the support phase runs.
## Original execution and observations
The generated probe executes full copied479D20, real47B4B0/grid/kernel and, in two
cases, real47B890/support. It reuses the independently guarded
body_step_probe.c mapper and synthetic virtual/body/grid contracts. A broad
synthetic vertical wall produces one actual terminal374 contact per case.
The custom contact mutates body records; it is not a recovered climb/hazard
mechanic. A wrapper at the support CALL either logs/no-ops to isolate candidate
publication or calls the unchanged original47B890. No game entrypoint, script,
animation, audio or GPU is executed. Original files are not modified/executed in
place; the existing reference_capture sandbox mounts only a separate copied
installation, disables networking and uses a generated Wine32 prefix.
19 final cases exit0 and print BODY_ROOT_PUBLICATION_COMPLETE. Native output,
capture.json, generated source/header and source hashes are under
artifacts/body-root-publication/. The committed fixture is
`tests/body-root-publication-reference.json`; its input/flag schemas and source,
shared harness, probe executable and output hashes are recorded. Build output is
kept in build/ separately from the Wine prefix: output-symlink protection
intentionally rejects generating over a directory containing prefix symlinks.
Representative observations (entry=(0,20,20,1), radius10, factor1.265,
velocity=(0,−120,−900), dt1/60):
| Contact action | Final live / previous effect | Publication |
|---|---|---|
|None|Live(0,17.7777786,10,1)|Allowed; original gravity and old falling delta applied.|
|Change liveX to100|Live(100,20,20,1), previous remains entry|Rejected; no old fallingY is added to live.|
|Change previousX to100|Live remains entry|Rejected even though live itself did not move.|
|Change liveW to2 or previousW to2|XYZ remains entry; changed W is retained|Rejected.|
|Set both XYZ to(101,250,303)|Old candidate overwrites live; previous remains(101,250,303,1)|Allowed because fresh roots are equal.|
|Set both W to2|Old candidateW1 overwrites liveW; previousW2 remains|Allowed; retaining callback liveW would be incorrect.|
|Set liveY to−30000|Callback-owned liveY remains−30000 in isolated-support case|Rejected, so candidate clamp does not clamp live.|
|EntryY−26000, no root mutation|LiveY−25000|Allowed candidate is clamped.|
|Entry previous=(999,999,999,3)|Contact sees entry previous=(0,20,20,1)|World branch resets previous before callback.|
The unchanged upward case endsY23.1111107; upward liveX/W mutations reject just
as downward ones do. `callback_motion` consumes an initial impulse30 before the
contact (seenVy≈−103.3333), then the contact writes velocity(9,8,7),
acceleration(4,5,6), pendingImpulseY77. Those new fields survive. The root still
uses the precontact falling delta and endsY18.2777786; the new positiveVy8 is not
integrated again during this pass.
Event strings corroborate ownership: C=terminal contact, R=fresh previous read,
L=fresh live read, P=candidate Vec4 publication, S=support CALL. Permitted cases
are `CRLPS`; rejected cases `CRLS`. The two original-support cases continue
`CRLSRL`, proving support reads both records after rejection. With contact-owned
live=(101,5,303,1), real support raises rootY12.6499996, zeros Vy, sets support
and emits one landing. Therefore rejection is not a blanket return from physics.
## Verification and implementation boundary
Four Python groups pass: original identity/ranges/12 publication anchors/four
bindings/four root leaves; all19 saved boundaries and call ordering; generator/
shared-harness provenance; original/output/symlink isolation. Commands:
```
python3 -m unittest discover -s tests -p test_body_root_publication.py -v
python3 tools/binary/body_root_publication.py ../Original --generate-probe artifacts/body-root-publication/build
i686-w64-mingw32-gcc -O0 -I tools/binary -I artifacts/body-root-publication/build artifacts/body-root-publication/build/body_root_publication_probe.c -o artifacts/body-root-publication/build/body_root_publication_probe.exe -lm
python3 tools/recon/reference_capture.py --asset-probe --probe-executable artifacts/body-root-publication/build/body_root_publication_probe.exe --probe-success BODY_ROOT_PUBLICATION_COMPLETE --seconds 15 --output artifacts/body-root-publication/probe
```
Parent owns runtime integration and managed conformance. Preserve live Vec4 W and
fresh previous Vec4; call a contact with live root state rather than candidate.
After it returns, compare those records before applying candidate/clamp. Keep
callback velocity/acceleration/queued impulse, and pass fresh previous into
support. A legacy entry-position diagnostic may remain a distinct output.
Confidence is high for these guarded finite component cases. Nonfinite/x87
unordered comparisons, arbitrary callback-driven flag/radius/material mutations,
actual special animation handlers and their root/previous policies, real dynamic
pairs/shared context, whole-original movement and native Windows gameplay remain
separate gates. This report makes no lab/outside source-body admission claim and
changes no runtime/shared documentation or existing fixtures/tests.
+53
View File
@@ -0,0 +1,53 @@
# Retained identity and physical re-registration
2026-10-26. Static evidence, not whole-loader execution. Original EXE SHA256 is
f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8.
Text offsets are VA−400000; body_root_registration.py guards14 instruction
sites and four Jimmy interface targets from PE-mapped bytes.
Ordinary teardown479000 clears physical records/body list695D3C, while game
object identity can survive in registry50999C.46E131 explicitly clears surviving
interfaces'49E registration flag. Jimmy PostLoad4238B4 invokes interface2C→42AB50:
false49E jumps to4623D0 InitPhysics. Identity retention is not physical-list retention.
4623D0 invokes base458910 (one-time470A00 logging/49E=true), copies current render XYZ
complete44/48/4C through16C→471630, copies angular-unit Euler through174→4716D0,
then calls479A40.479A65 invokes interface150(0,0,0);479A6F invokes Init28 AGAIN,
resolving to Jimmy437890. Only then does it append a12-byte body-list node with
the interface payload and increment695D40. Later PostLoad STRT placement and
final control preparation have their own order; registration's Init is not a
blanket post-placement reset. Existing retained scalar conclusions remain bounded
by the closed437890/generic Init chain, not by an assumption that Init runs once.
Follow-up: [physical registration](physical-registration.md) executes12 bounded
original registration/loader cases.470A00 is a logging hook, not an allocator;
the12-byte body node is allocated inside479A40. The common polygon/sprite bridges
can append repeated actor pointers; Jimmy's outer49E guard supplies the distinct
skip boundary. The per-object Init/PostLoad order and same-pass registry appends
are now covered by original-component execution, not solely static reading.
| REA routine | Evidence ID |
|---|---|
|4623D0|ev_d60cfc7d2ff8266e19176052e1466ba98f09e7b10b92db828566fbc28d36d281|
|458910|ev_a7ef1cecf9385efe4f91ad8ec48ac37ba24831a1b797f24c3039a912f0b61526|
|479000|ev_bae5aeaa4f8ebad1bba6974e9d33ba801959500e41eadc99be5e6b8631feecc1|
|479A40|ev_40105808ae5a1e83bd8221b627e9aeca89b0f399a68dba068ed01e5b11857438|
Complete replies/exports/closed snapshots: artifacts/body-root-registration/.
Some additional requested leaf/derived entries lacked analyzed Ghidra procedures;
their error replies remain alongside successful Evidence. Instruction bytes and
resolved vtables support the callback chain without claiming complete pseudocode.
Previously recovered dimensions remain: ordinary radius60/support factor1.265,
physics position interface214..220, direct physics-to-render XYZ copy4624B0, shape
min/max bound records1C4/1D4. No recovered capsule height follows from mesh bounds.
The standing animation offsets observed in the older copied-DLL probe were zero;
there is still no source evidence for the port's sole-based model translation.
The port reconstructs body state per scene and carries only mode/hold/fire in
its bounded route container. That agrees with the reset boundary at a coarse
level, but does not reproduce source allocation/physical-list order/new helper
traversal or the complete body338 record. REA's prior40E050/462520 Evidence also
shows base transform work before ownership; port destination-yaw smoothing is
not proven equivalent. These remain C3/C4 implementation gates. No extra state
carry, scale correction or live body-shape replacement is justified by this report.
+278
View File
@@ -0,0 +1,278 @@
# Camera, audio and UI architecture checkpoint
Scope: playable baseline `69d0187`, lab → VR04 → lab → outside. Read `prompt.MD`
all1281 lines and both AGENTS files. This checkpoint changes no runtime behavior.
Original files were read only. Source-byte checks below are static evidence,
not original-game runtime comparison. Existing Linux GPU/SDL smoke tests and user
Windows reports describe the port, not a recovered original reference recording.
## Evidence identity and reproduction
| Module | SHA-256 |
| --- | --- |
| Neutron.exe | f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8 |
| OMT2.dll | 3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943 |
`python3 tools/binary/checkpoint_camera_audio_ui.py ../Original` verifies25
selected instruction sequences and7 constants against those identities and prints
mapped physical offsets. `python3 -m unittest discover -s tests -p
'test_checkpoint_camera_audio_ui.py' -v` also checks ray-adjustment algebra.
Fresh bounded objdump reads corroborate the cached `artifacts/binary/neutron.asm`;
RTTI was checked with `tools/binary/rtti_map.py`.
All EXE code/constant VAs in this report have physical offsets VA−0x400000.
Examples and decisive ranges are listed explicitly. **The globals below occupy
PE zero-fill and have no physical file offset**; subtracting the image base from
their VA does not produce an original-file byte location.
| Runtime owner/global | VA | Meaning supported by consumers |
| --- | --- | --- |
| Controlled game-interface pointer | 0x5099E4 | Input ownership; null also suppresses objective clock/draw |
| Shared viewport pointer | 0x509A50 | Position+44/+48/+4C; signed angle words+50/+52/+54 |
| Current music database | 0x696004 | Separate from current Wave/effects/speech bank |
| Current Wave database | 0x696008 | CAM/MCA replace it with authored speech bank; DEFAULT restores effects |
| Sound engine | 0x69600C | Channel array+40; virtual24 returns channel count |
| Default positional-effect gate | 0x4F8434 | Wrapper4589C0 tests it; cutscenes clear, DEFAULT enables |
| Objective time / selector | 0x4F8188 / 0x4F8194 | Separate transient presentation and persistent selection |
| Objective44 flags | 0x4F7D00 | Independent per-row visibility/selection state |
| Modal active / type | 0x4F8198 / 0x4F8048 | UI continues handling modal while main gameplay is paused |
## Shared camera state and ownership
**Recovered fact.** There is a shared viewport, not independent original
"gameplay eye" and "cutscene eye" objects selected by renderer priority.
CAM/MCA and player callbacks write that same position/orientation. MCA helper
431670 (file31670) writes eye+44/+48/+4C at431677/431683/431694, derives angles
using imported angle routine48D108 at4316F9, writes words+50/+52 and roll0 at
43170D..431717, and mirrors camera globals4F8418..4F842C. CAM formulas are at
4161CD..416585 (file161CD..16585), MCA formulas431027..4311C1
(file31027..311C1). Their authored transforms are already documented in
`../analysis/lab-progression.md` and represented by SceneDirector.UpdateCamera.
CAM activation4165E2..4166FA (file165E2..166FA) resolves PlayerControlled:
`none` preserves, `NULL` clears, a named found actor grants control through game
virtual118. Before clear, it calls controlled actor virtual410/438 and rewrites
transform state. MCA431502..4315A7 (file31502..315A7) similarly prepares prior
controlled actor then clears through game virtual118(NULL). Its PlayerControlled
field is completion ownership at4311F0..431228, not an activation grant.
Control loss does not prove all physics/actors should stop. Main-loop report owns
the enclosing update pass and any per-actor active gates.
**New recovered DEFAULT handoff.** DEFAULT447CF0 has a Jimmy-already-controlled
early branch447D5C..447D9C (file47D5C..47D9C). Even that branch reloads the
default effects bank; it skips camera reposition and music restart. Otherwise
447E1E..447E27 restores control, then447E2D..447EC3
(file47E2D..47EC3) computes actor-local point `(0,500,-500)` using game-interface
virtual384, compares distance from current viewport position against float1000
at48E5AC (file8E5AC), and writes the point to viewport only when distance is
**strictly greater than1000**. At equality the original `fcomp; test ah,41; jne`
skips the snap. Non-Jimmy mode-dependent restore targets also exist447DAC..447E1E;
the port's unconditional Jimmy restore is only the route subset.
**Current implementation.** Program selects LabSimulation.CameraEye then replaces
it with SceneDirector.CameraEye while a shot exists. `RestoreControl` clears the
shot eye; it neither transfers current viewport state into follow state nor
performs the source conditional snap. LabSimulation only advances when Jimmy
controls input. Calling its eye "always advanced" is inaccurate; it remains a
separate stale state during ordinary uncontrolled cutscenes. This is an ownership
mismatch, not a reason to add another transition easing heuristic.
## Follow camera, obstruction and clipping
**Recovered fact.** Jimmy complete-object vtable4A3BDC (fileA3BDC), slot124 →
438BC0 walking, slot128 →439900 airborne, slot16C at4A3D48 (fileA3D48) →
43B820 camera ray callback, slot170 →437740 default camera setup. The separate
game-interface vtable4A373C (fileA373C) has complete-object displacement+C0;
do not apply complete-object offsets directly to an interface pointer.
| Complete-player field | Source initialization/use |
| --- | --- |
| +7C8/+7CC/+7D0 | Eye local0,200,−350 at437740..43776D (file37740..3776D) |
| +7D8/+7DC/+7E0 | Look local0,80,0 at437752..437774 |
| +854/+858/+85C | Axis gains1.6,1,1.6 at43775E..437787 |
| +804..+810 | Cached desired eye when special-state branch retains it439658..4396A5 |
| +714/+718/+71C | Prior camera position used by follow deltas43971E..439748 |
| +828, +830, +84C, +851 | Additional state affects offsets/gains; complete semantic names unresolved |
4395CF..4398E4 (file395CF..398E4) does not simply follow a fixed local offset.
Normal eye height is `eyeY−2*self[84C]`; target height is
`lookY+1.9*self[84C]` at439625..4396DA. Special+828/+830 branches use cached
eye or flip/scale backward distance by3.7 after threshold1.7. Float64 constants
are4AFCE8/4AFCF0/495338 (filesAFCE8/AFCF0/95338). Do not rename84C to ground
height or infer its units without tracing writers.
**New ray contract.** Caller439702..439714 passes look-point by value and
desired-eye pointer through complete-object virtual16C. Callee43B820..43B90C
(file3B820..3B90C) calls ray predicate47C210 at43B874; on hit reads16-byte hit
global5CFC60 and mutates desired eye to
`lookPoint−0.75*(lookPoint−hitPoint)`, i.e. `.25*look+.75*hit`. It returns1.5
on hit (float4A3138,fileA3138), otherwise1.0. Predicate layer/filter/ordering and
its use of actor-query virtual310 still require recovery; this algebra alone
does not authorize replacing its ray with the port capsule sweep.
Normal interpolation4397B1..4397F1 multiplies X/Z delta by axis gain, ray return
gain and dt; Y uses `(gainY+0.2)*rayGain*dt`. +851 selects a0.2 branch and
+828 selects another branch without these axis multipliers. Position is added
to current viewport4397F8..43982D, then look angles derive from prior-position
fields and wrap with mask3FFF at439865..4398E4. This order matters and needs an
isolated trace before replacing the source adapter.
**Current approximation.** LabSimulation.DesiredEye uses root+(yaw-rotated
0,180,−350), target root+99, fixed gains1.6/1.2/1.6 and modern sphere/capsule
obstruction before and after interpolation. 180/99 match only an inferred
selected offset state, not the complete field-driven algorithm above.
**Clipping fact versus policy.** OMT2 layer constructor1004D340
(DLL file4D340) defaults near20/far3200/FOV0xAAA. Source initializers override
geometry-layer far values: LV1B44F5A5/44F5B1 (files4F5A5/4F5B1)=10000,
VR04456C04/456C4A (files56C04/56C4A)=50000, outside45086F
(file5086F) sets layer509A3C to28000 while509A30 retains3200. Full35-scene
table is `../analysis/camera-clipping.md`. SceneProjection's maximum of two
layers is a documented merged-renderer policy; layer masks/clip/fog and dynamic
LV4B clip transition are incomplete. Orbit scene-radius far distance only hid
the earlier wrong gameplay3200 range. Widescreen aspect is a modern policy.
## Audio owns cutscene completion, banks and channel lifetime
RTTI disambiguates the camera callback structures: C3DCutSceneCamera complete
vtable498060 (file98060), slotD8 at498138 →4165A0 activation; its **+C8**
game-interface vtable497BFC (file97BFC), slot3C4 at497FC0 →415F90 update.
Thus update-relative handle+8B4/active+8B8/elapsed+8F0 are complete-object
+97C/+980/+9B8 respectively. C3DMultiCutSceneCamera complete vtable4A93C8
(fileA93C8), slotD8 at4A94A0 →431280; its+C8 game-interface vtable4A8F64
(fileA8F64), slot3C4 at4A9328 →430DA0. MCA update-relative handle+DC0,
active+DC4, elapsed+DE0 are complete+E88/+E8C/+EA8. Camera's interface
displacement is C8, whereas Jimmy's is C0; conflating them shifts every field.
**Recovered fact.** CAM415F90 calls base update463090, increments elapsed+8F0
at415FB2..415FBC, then polls sound handle+8B4 at415FC2..415FD3
(file15FC2..15FD3) with47D890. While sound reports active it updates camera and
skip handling. When inactive it stops/releases handle, changes target animation,
deactivates and invokes next trigger4160A4..4160E2. MCA uses the same predicate
at430DD2 before advancing shot; per-shot elapsed reset43190F. Animation is an
effect of activation/completion, not the recovered cutscene clock owner.
47D890..47D8E6 (file7D890..7D8E6) validates engine, nonnegative index and channel
count, reads voice at `engine[40][handle]`, calls voice virtual14 with two outputs,
and reports active if the second output is nonzero **or voice byte+30 is nonzero**.
Missing engine/index/voice returns false. Follow-up [voice-clock.md](voice-clock.md)
resolves both derived vtables: slot14 is inherited software elapsed/duration,
and+30 is repeat/loop state. This is not a hardware-playing or audibility query.
The ordinary one-shot clock is duration-based, but source integer boundaries,
invalid handles, engine clock pause, play failure and stop still need modeling.
47D7A0..47D849 (file7D7A0..7D849) stops voice virtual0C, optionally releases its
resource from selected database via virtual38, clears handle resource table
695EC0[handle], and clears global music handle4F6B30 when equal. Parameter0
still stops/clears handle association; parameter1 additionally releases database
resource. These are source runtime handles, not original Wave identity numbers.
| Lifecycle | Original transition / offsets | Port boundary |
| --- | --- | --- |
| Jimmy PostLoad |423642..423656 (file23642..23656) loads SoundEffects.omt into696008; selected music stored complete+A4C, handle+A38 | Per-scene prepared files; selectedMusic tuple held by SceneAudio |
| CAM takes audio |416776..4167E1 stops Jimmy music handle with47D7A0(handle,0), unloads selected archive, clears696004 | MusicStopped event disposes stream; tuple retained for restart |
| CAM takes Wave bank |4167FD..416830 (file167FD..16830) unloads default bank, clears696008/gate4F8434, loads authored speech bank | Speech opens explicit independent WAV; SFX default gate absent |
| MCA takes Wave bank |4315AD..4315F5 (file315AD..315F5) performs analogous bank/gate replacement; does not establish universal music stop | Standalone MCA intentionally does not mute all music |
| DEFAULT resumes |447F12..447F45 (file47F12..47F45) reloads selected archive, starts Wave0 and stores new music handle | Restart selected track from start; independent streams |
| DEFAULT restores effects |447F4B..447F6F (file47F4B..47F6F) restores volume/bank/gate; early Jimmy-owned branch447D60..447D76 also restores bank/gate | No explicit bank switch; always SoundEffects.omt Effect(id) |
| Level teardown/reset | Full global sound reset is not proven by these callbacks alone | SceneAudio.Dispose destroys every per-scene stream; RenderSession survives |
458980→47D390 is nonpositional wrapper;4589C0→47D640 checks default gate4F8434.
Therefore "mute every effect during every speech" would be a false generalization.
Recover wrapper call sites before suppressing objective216 or mechanism effects.
Original volume, attenuation, spatial pan, voice limits/allocation and stream
pause ownership remain incomplete. Source general-bank switching is broader than
the narrow fixed default bank in `../analysis/sound-effects.md`.
**Current implementation.** SceneDirector consumes prepared PCM sample duration,
including leftover dt across shots; no SDL voice status participates. SceneAudio
uses independent SDL streams for speech/music/one-shots/owner loops. SdlAudio.Pump
queues loop data below one source-buffer length; bytes queued are not proof all
converted output reached the speaker. Debug SetPaused is a modern menu feature.
The lab16-cue SDL dummy smoke validates port stream bookkeeping only. Physical
speaker output and native Windows end timing remain separate verification.
## UI update, modal timing and layout
**Recovered fact.** UI dispatcher404080 (file4080) calls base473240 first at
40408E, normalizes pointer using original1/640 and1/480 at4040B7/4040C5, processes
cursor repeat state when mode flag4F8181 or modal4F8198 is active, then invokes
UI virtual4E4/4DC at40420B..40421B. Notification timers4F8154/58/5C are separate
from objective timer. After virtual4E0 at4043D3, controlled-pointer condition
4043D9 advances objective time and invokes virtual4D0; null-control branch
40447A..4044BD hides art without advancing. Modal branch4044C2 follows this,
so its forced objective time8.7 overrides any earlier increment that UI tick.
This is a recovered local ordering, not proof of frame-wide input/UI scheduling.
Objective407070 (file7070) has .7 entry, stationary until7, exit until8.7; O
edge toggles timer0/7, not layout. Positive Select406F50 resets timer even when
selection repeats; initialization4018A8 and423EC6 sets20 hidden. Exact timings,
sound216 latch, fields, art identities and byte checks are in
`../analysis/objective-timing.md`. UI row flags are44 independently selected
entries; single selector digit and visible flag set are not interchangeable.
Practice406F90 (file6F90) guards existing modal, shows chosen art and cursor,
then407022..407031 invokes game virtual168(1) and stores type. UI continues to
accept selection while gameplay is paused.4044CE excludes type12 from forced
objective hide. No404D1E..404D97 hides modal, restores main game and resets
objective time0. Yes type0 stages VR04/PHONEBOOTH and departure context;
source mode1/2/3 map VR03/02/01. Exact keyboard/pointer strict bounds are in
`../analysis/ui.md`; controller navigation/highlight/cursor ownership remain open.
**Current implementation.** ObjectivePanel correctly separates timer/selector
and controlled/modal gates for the implemented objective subset. Program.Key
adds Jimmy-owned/inventory/focus/inspection/debug gates; original local clock
checks any nonnull controlled entity. Modern focus/orbit/debug gates are not
recovered source rules. PracticePrompt implements only modes0..3 and no source
highlight/controller state. SceneHud shows only lab objectives1..3, pad/digit and
practice art; gadget inventories and layout callbacks406590/406650 are absent.
Original402CC0/402D70 (files2CC0/2D70) scale horizontal/vertical positions with
width/640 and height/480 separately. Current UiViewport deliberately uses uniform
minimum scale with centered modal/bottom-right anchors and inverse DPI-aware
pointer mapping, following the user's widescreen requirement. This is an
intentional modern policy, not a claim that the original had anchored ultrawide
layout. F1/F2 debug UI is likewise modern; keep its state out of source save/UI
fields. The objective pad extending off reference viewport is authored clipping.
## Route interaction and reset map
| Route point | Camera/audio/UI dependencies and ownership |
| --- | --- |
| Lab NewGame/STARTEXP | Loaded selector does not imply visible pad: timer20. STRT/intro activates CAM/MCA chain, takes shared viewport/control; CAM stops music and replaces effects bank. First CAM bank gate persists through chained MCA until DEFAULT. |
| Intro DEFAULT | Restores actor control, conditionally snaps existing viewport only for distance>1000, restarts music if control was not already Jimmy, restores effects bank/gate. UI objective clock resumes with nonnull control; task selector changes remain separate. |
| Jetpack pickup/practice | Objective changes reset timer; practice modal pauses main game and forces objective hidden. No unpauses/reopens timer0. Yes stages VR04/PHONEBOOTH plus return context; script-state report owns persistent departure root/strings. |
| VR04 | Initial geometry layer far50000; scene-specific camera/speech/music state rebuilt by port. Original full teardown/global reset needs loader recovery; do not infer all fields persist because TSK does. |
| RETURN lab | Source return applies STRT/root/one-time trigger suppression; intro should not replay solely because scene rebuilt. Viewport/music/UI reset ordering depends on PostLoad and retained task state, not generic "resume previous audio". Current port constructs fresh SceneAudio, ObjectivePanel and director. |
| Carl → outside | CAM/MCA null control suppresses input/objective time, not all actor advancement. DEFAULT/LOAD order owns camera/music restoration vs scene destruction. Outside geometry far28000 is layer-specific, while current combined renderer uses28000 globally. |
## Coverage, assumptions and next bounded chunks
| Area | Recovered | Remaining source gap / evidence gate | Current implementation gap |
| --- | --- | --- | --- |
| Script cameras | Local transforms, elapsed, shared viewport writes, control handoff | Vtable caller phase/target transforms after actor motion; full skip/loader ordering | Separate eye state and duration clock |
| Follow | Fields, branches, ray mutation/return gain, viewport/angle writes |47C210 layer masks/nearest-hit semantics;84C writers; cached camera updates | Fixed offsets/gains and capsule clipping |
| DEFAULT | Strict>1000 snap, existing viewport retention, effect/music reset | Mode-dependent control targets outside route | Unconditional Jimmy restore and discarded scripted eye |
| Projection | Source layer defaults/all35 initial limits | Assignment/masks/fog, dynamic transitions | Merged maximum and orbit policy |
| Audio | Handle polling, software duration/repeat, bank/gate ownership, stop/reload | Source duration conversion/allocation/play failures, engine pause | Per-file independent streams, floating-duration/leftover-dt completion |
| UI | Local dispatch order/objective/modal gates and resource coords | Mode4F8181/4F8430 semantics, full flags/gadget/highlights/controller | Lab subset, modern input gating and uniform anchors |
1. C5: trace47C210 filter/caller contract; build shared viewport handoff tests
using source snap999.99/1000/1000.01 and ray-hit weighting. Preserve viewport
at control return, apply source conditional snap, then follow. Do not transplant
gains while leaving its previous-position/angle/collision dependencies guessed.
2. C6: voice-clock follow-up resolves virtual14/+30; recover allocation/failure
and source duration conversion before modeling the channel clock. Model
explicit bank/gate state separately from independent stream transport.
Test invalid/missing handle, delayed start, natural end, skip, paused playback,
DEFAULT already controlled, and level disposal before switching CAM/MCA clock.
3. C8: recover UI mode/pause callback boundaries and44 flags; preserve existing
tested timer rules. Add source gadget/layout/controller state only with call
evidence. Uniform widescreen/debug policy remains intentional and independently
tested. Recover animation end notifications separately from speech end.
These support the primary `coverage.md` and `implementation-plan.md`; they do not
claim all systems faithful or require every level/original GPU capture before a
bounded implementation correction. Stale broad binary.md mode1-no-action and
universal3200 clipping claims are superseded by movement/clipping reports. Broad
"camera recovered"/"audio implemented" labels must retain the boundaries above.
+40
View File
@@ -0,0 +1,40 @@
# Shared viewport handoff
2026-10-26. Static source evidence; implementation is deferred to the next bounded
C5 chunk. camera_handoff.py guards50 instruction sites, four callbacks and the
DEFAULT threshold; its four Python projections are not original execution.
Text offsets below are preferred VA−400000 for the manifest's original EXE.
Shared viewport pointer509A50 stores eye at44/48/4C. MCA431677..43169D writes this
same eye. DEFAULT447D54 has an already-Jimmy branch; on the other route it restores
raw control, transforms Jimmy-local(0,500,−500) through384, computes Euclidean
distance to the current shared eye, and writes eye only when distance>1000
(447E9D..447EC3). Equality does not snap. This block leaves orientation unchanged.
Walking input/follow438EF7..438F29 reads the current shared eye into complete
714/718/71C every invocation.439722..439742 uses it for desired-eye delta;
4397F8..43982D adds the filtered delta back to the shared viewport. Airborne
439E33..439E51 likewise captures the shared eye into locals. Therefore the first
resumed input uses the final scripted eye, or DEFAULT's snapped eye, without
relying on an old player-owned follow cache.
Normal walking gains are1.6/1.2/1.6 times dt and the separate ray gain. Aim derives
from look point minus PRE-update eye (439830..439865; airborne43A09F..43A0CE),
then quantized OMT angle conversion. The port's LookAt(newEye,target) is a separate
orientation approximation. Other special follow fields/input branches remain open.
REA decompiled setup437740:
ev_d2502f41c45731b86d4365634fbc6f0d1b3b70d880fd5741275fd36f1d585aa4.
Selected DEFAULT/follow/viewport-write entries lacked recognized Ghidra procedures;
explicit-offset attempts also failed. Complete successes/errors/exports/closed
snapshots are under artifacts/camera-handoff/rea/ and rea-offsets/. Those negative
provider results are limitations, not negative claims about the original code.
The handoff conclusion is supported by the guarded direct instructions.
Current port still separates SceneDirector's scripted eye from LabSimulation's
follow eye. C5 should move viewport eye/aim ownership into one state shared by
script and follow, apply strict DEFAULT snapping only on the recovered boundary,
and preserve pre-update-eye aiming. Test below/equal/above1000, already-owned,
CAM/MCA→DEFAULT, held-input resume and RETURN continuity. Keep projection/fog/masks,
full follow branches and original visual comparison separate. This investigation
does not claim that camera handoff is implemented yet.
+222
View File
@@ -0,0 +1,222 @@
# C5 gate: source camera obstruction predicate
This is a bounded static continuation of `camera-audio-ui.md`, against the
unchanged Neutron.exe SHA-256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Originals were read only; no original instructions were executed. Modern runtime
code is unchanged. Preferred EXE VA → file offset is VA−0x400000 for all code,
vtable and initialized constants below. Zero-fill grid/output globals have no
physical file offset.
**Decision:** enough source evidence now exists to construct a separate static
camera segment-query adapter. It must preserve wall-grid priority, source cell
and insertion order, one-sided winding and first-hit return. Reusing the existing
nearest-hit support query or swept camera sphere would produce a different
algorithm. Full follow-camera integration still requires camera state continuity,
source angle/previous-eye handling and the remaining input-mode branches.
**Implementation continuation:** `OriginalCameraRay` now implements these source
grids and shares the individual segment kernel with `OriginalBodySupport` while
preserving support's nearest-hit reducer. Program uses this query for LV1B/VR04/
LEV1. Player follow consumes one query per input callback, source hit adjustment
and1.5 gain; the post-interpolation sphere sweep is removed for these scenes.
Other scene filters and synthetic fixtures keep the explicit provisional adapter.
Eleven managed groups verify route registration counts and synthetic order/kernel/
filter cases; a separate movement consumer check asserts origin, gain and absence
of a second query. Shared viewport/DEFAULT handoff and full follow state remain
open, so this is static-obstruction recovery rather than whole-camera fidelity.
## Actual caller arguments and unused actor getter
Jimmy complete vtable4A3BDC, slot16C at4A3D48 (fileA3D48), resolves43B820.
Its caller439702..439714 (files39702..39714) supplies computed look target by
value and a pointer to computed desired eye. At43B820 entry let stack pointer beS:
| Entry address | Argument / location |
| --- | --- |
| S+4..S+13 |16-byte input look-target vector |
| S+14 | Desired-eye pointer |
| S−18 | Stack pointer after `sub14; push esi` |
| S−10..S−1 | Local16-byte actor-position getter output |
| S−14 | Local float return gain initialized1.0 |
Hex numbers in this table are offsets, e.g. S+14 means20 decimal bytes.
Both virtual310 calls43B83F and43B84E (files3B83F/3B84E) write local scratch.
Jimmy interface vtable4A373C slot310 at4A3A4C (fileA3A4C) is472300
(file71300), which copies interface fields214/218/21C/220 to its output and
returns with `ret4`; it has no callback or mutation side effect. The local
position vector is not copied to the ray arguments.
After loading end pointer `[esp+2C]` at43B854, caller pushes0 then copies the
desired eye to a16-byte argument. It reserves another16 and uses
`lea edx,[esp+40]` at43B868: this is exactlyS+4, the **incoming look target**,
not the getter output.43B874 calls47C210 with
`(lookPoint, desiredEye, twoSided=false)` and cleans24 hex bytes. The source
therefore has no actor-root ray origin or actor exclusion pointer here.
On hit43B884..43B8F4 reads shared hitXYZ5CFC60/64/68 and changes the pointed eye
to `lookPoint−.75*(lookPoint−hit)`. It returns1.5; miss returns initial1.0.
This caller-level fact corrects any description of25% movement toward actor root.
## Query priority: first wall hit, then first general hit
| Function | File offset | Contract |
| --- | --- | --- |
|47C210..47C279 |7C210..7C279 | Global enable gate; call wall query; immediate return on hit; otherwise all query |
|47C280..47C4A4 |7C280..7C4A4 | Rectangle scan of wall/ceiling static grid509B24 |
|47C4B0..47C6D4 |7C4B0..7C6D4 | Same scan of all-polygon static grid5CFC7C |
|469530..4695A9 |69530..695A9 | Build48-byte segment: start+0, delta+10, end/hit+20 |
|469A10..469B66 |69A10..69B66 | Fetch first three polygon corners, add supplied translation, call triangle kernel |
|469B70..469E26 |69B70..69E26 | Source-winding segment/triangle kernel; recovered earlier for support |
47C210 passes unchanged start/end and sidedness to both queries; the second is
**not a reverse-direction retry**. Wall call47C23D (file7C23D) returns immediately
47C249..47C24C on success; all-grid fallback is47C26C. Both scan functions reset
shared hit polygon/shape identity695D54/695D58 at entry and rebuild global segment
5CFC40. Camera hit output5CFC60 is that segment's+20 vector.
Within each scan,469A10 returns a bool and shared hit point. A true branch at
47C44C or47C67C immediately stores current polygon and shape pointers to
695D54/695D58 then returns true. There is **no nearest-distance comparison**.
Thus a farther wall polygon in the first eligible cell can win over a nearer wall
later in that list, or a nearer floor in the second grid. A successful wall pass
prevents the all-grid pass entirely. This is materially different from47C6E0
used by body support, which retains strictly nearer hits.
Global enable byte4F69E5 is initialized1 at physical fileF69E5, unlike the
zero-fill grids.47C210/280/4B0 independently test it; zero returns false. No
entity-radius, dynamic actor-pair query, visibility, renderer-layer mask, camera
near/far, or material-alpha test appears in the predicate or triangle-call path.
Those static lists were filtered at registration instead.
## Grid coordinates, traversal and insertion order
Float cell scale4D6A04 (fileD6A04) is exactly
`0.0020000000949949026f`, origin49B1FC (file9B1FC) is130.0f. Nominal cell width
is500 world units; use the stored float rather than exact decimal1/500 when
testing source boundaries. For X and Z independently:
```
index = int16(truncate_toward_zero(worldComponent * storedScale + 130))
```
47F940 (file7F940) changes x87 control rounding to truncation, converts through
signed64 and returns low32; query comparisons retain low signed16. Multiplication
and addition remain x87 intermediates before conversion. This matters for exact
cell boundaries and extreme coordinates; Python's double order oracle below is
not an original x87 execution probe. Normal route coordinates fit the grid.
47C2E2..47C386 converts both endpointX/Z values, takes componentwise minima and
maxima, and scans the full inclusive **axis-aligned endpoint-cell rectangle**,
not a DDA path or intersecting-cell distance order. Outer indexX increases;
inner indexZ increases.47C3A4..47C3C6 rejects index<0 or>=260. Cell record stride
is12 bytes; list-pointer address is `gridBase+12*(260*x+z)` with gridBase509B24
or5CFC7C. Record pointer addresses differ from their structure starts by4 bytes.
47C3DF..47C3EA fetches cell sentinel then first node. Node layout is next+0,
previous+4, polygon-registration pointer+8. Each polygon registration record
has polygon pointer+0 and shape pointer+4. Traversal follows next until sentinel;
47C44E..47C459 and47C67E..47C689 continue only after miss. A polygon spanning
multiple cells can be tested multiple times; there is no per-query visited set.
479800..47991B (file79800..7991B) registers into the general grid, rejects
duplicate polygon pointers **within that cell**, and appends new nodes at the
tail.479897..4798A8 sets new.next=sentinel/new.previous=oldTail then links it;
the query therefore visits FIFO registration order, not reversed insertion.
It also appends to the wall grid when **stored polygon normal.Y<0.7f** at
4798B3..4798CF; equality is excluded. Threshold48D974 (file8D974) is the same
float used elsewhere for objective timing, which does not establish shared logic.
479140 (file79140) iterates the source shape polygon array in48-byte increments
at479473..479482. It calculates each polygon's XZ vertex bounds, converts extrema
with the same scale/origin/truncation, and registers the polygon in every cell of
that inclusive rectangle479336..479400. Centroid/radius data are retained in the
registration record, but this camera scan does not consult them for nearestness.
Shared scene loader44DBF0 uses shape resource ID/index initialized0 at44DC21,
fetches with477BA0, increments at44DEAF and tests existence through477C10. For
the three route archives shape IDs are ascending; current file enumeration order
also happens to be ascending, but an adapter should use source shape IDs and
polygon array indices explicitly. Port merged render-draw order is not evidence
for source registration order. The source's behavior at a missing intermediate
shape ID should be preserved or separately investigated before generic reuse.
## Registration filters and route asset coverage
Shared loader lowercases the first two shape-name characters and skips terrain
InitPhysics for NC prefix:44DD2F/44DD64/44DD67 (files4DD2F/4DD64/4DD67).
The ordinary path calls terrain interface2C at44DD6D →464B00 →479140 at464B18.
This excludes a complete NC shape from **both** grids, without removing its draw
geometry. Details and exact source shape payload offsets are in
`../analysis/water-collision.md`.
For remaining shapes4791C7..4791E5 first excludes checkpoint materials via
4794C0 then calls game polygon callback4797A0/virtual134. Null material causes
checkpoint filter false at4794E8; retain such polygons. Route game complete
vtables CLevel01BGame4C3CD0, CLevelVR044CE910 and CLevel01Game4C5A80 all have
slot134→475CD0, which returns false. These three scenes add no exclusion through
that hook. Do not generalize to every level callback.
Fresh decoded data from originals, after NC/checkpoint gates:
| Archive | Registered polygons | Wall-grid eligible | NC excluded | Checkpoint excluded |
| --- | --- | --- | --- | --- |
|level1b.omt |2851 |2483 |18 |0 |
|VR04.omt |508 |420 |0 |0 |
|level1.omt |5231 |3860 |24 |0 |
All remaining route polygons have exactly3 corners.469A10 fetches only first
three corners through477F10 (file77F10); registration bounds use all corners.
This distinction is immaterial for these archives, but cannot justify blindly
fan-triangulating larger original polygons for a future source camera query.
477F10 indexes polygon corner data then raw shape vertices+68; it applies no
terrain transform.469A10 adds supplied translation, which these grid queries
pass as identity vector(0,0,0,1). Runtime moving-body collision is separate.
Route OMT hashes and counts are printed by the new helper; source files remain
untouched. Layer509A30 versus509A3C far masks belong to rendering, not these
camera-obstruction grids.
## Triangle acceptance and offset84C clarification
Camera passesfalse sidedness.469B70 normalizes segment direction using the
recovered OMT quick magnitude, accepts source determinant<=−epsilon, barycentric
u/v edges inclusive, t>=0 but **t<segmentLength**. Constants4D5E40/44 are
±1.1920928955078125e−7. Source endpoint rejection469DDF..469DEE is strict;
do not invent a camera-radius skin or reject t=0. Full kernel/math evidence is
in `../analysis/original-collision.md`; its managed support implementation already
contains the winding/quick-magnitude algorithm, but its nearest-hit reducer must
not be reused unchanged for this query.
Offset84C is a camera-input adjustment, not recovered ground clearance. It is
initialized10 in Player437602 and Jimmy4228DE (files37602/228DE); walking resets
10 at438CC6 when complete virtual15C is false and controller mode4F0588!=6.
When virtual15C is true and mode6,438C64..438C7E adds mouse-relative vertical
delta*dt (mouse delta reader46A460); analog/forward/back paths438C86..438CB4
adjust by ±20*dt (constant495324,file95324). Other state/reset writers exist
428723 and class-specific4083A2/408685; do not rename the flag15C or claim the
whole camera-input mode recovered. At default10, source formulas produce
eye200−2*10=180 and look80+1.9*10=99, explaining the port's fixed offsets.
## Verification, remaining gates and implementation boundary
`tools/binary/checkpoint_camera_ray.py ../Original` verifies33 source anchors,
prints mapped constants/hashes/counts and exposes a bounded order reference.
`python3 -m unittest discover -s tests -p 'test_checkpoint_camera_ray.py' -v`
passes4 tests: source+route data, inclusive X/Z ordering/truncation, deliberately
farther wall-first result, and duplicate-cell tests/fallback/disabled gate.
Synthetic acceptance callbacks test query ownership/order, not original ray
arithmetic execution. No GPU/runtime/original timing fidelity is claimed.
A coherent adapter can now preserve source registration IDs, stored normals and
filters; construct sparse12-byte-equivalent cell lists in FIFO order; reuse the
source segment kernel with first-hit reduction; and expose source-enabled flag,
hit identity/point and gain. Verify synthetic farther-before-nearer, wall-before-
floor, winding/endpoint, repeated cells, negative coordinate and NC cases before
camera integration. Test route against the current playable baseline separately.
Still open: source x87 boundary equality on exact grid thresholds; negative/extreme
integer conversion overflow; missing intermediate shape IDs; explicit nonidentity
terrain transform consumers; further84C/input modes; and shared viewport/previous
camera update phase during control handoff. These limit whole-camera fidelity,
but do not justify retaining nearest-sphere behavior as the source static query.
+52
View File
@@ -0,0 +1,52 @@
# Jimmy's overhead query and cancellation
2026-10-26, static recovery and bounded port correction. Original EXE identity is
the manifest's f5281076…1aea8. Preferred text VAs map to offsets VA−400000;
ceiling_wrapper.py independently maps and guards37 sites,8 targets,6 constants
and four complete bodies. No original ceiling routine was executed in this chunk.
424BE0..424C34 runs before movement437940's raw-control identity gate. It reads
live velocity2BC→471F10; strictly positive Y invokes complete1A4→425170. The
separate1A8→4252E0 downward-distance refresh follows, then movement. These
wrapper queries are not input or camera ownership tests.
425170 reads logical root310→472300.4251B8 adds float150 to rootY;4251FC calls
47C210 with two-sided=false. This is the wall-first/FIFO static predicate shared
with camera queries, not support's nearest reducer and not a capsule-top sweep.
On a hit it rechecks live Vy>0, then writes XYZ through2C4→471F40 with
`Vy=float(min(-double(Vy)*0.6,-85))`, preserving X/Z. It does not correct position.
Optional sound47 depends on selector4F0588 and an elapsed>5 gate; then4252CD
invokes complete1E0→425120.
425120 acts only when complete7C4 mode==1: writes jump7E8=0/mode1, requests FALL,
then zeros owned fire6C0 if present and calls complete140→429910. Hold874,
pending impulse and acceleration are not cleared by these writes.429910 clears
complete1E64/1E68 and saved soundA3C, with a helperA18 cleanup path except selector2.
Those helper/class sound effects are not fully implemented.4252E0's root−2500
nearest ray/shadow placement is separate from this upward response.
REA/Ghidra425120 Evidence:
ev_5fd4a2c55af84285f9b3fe8f9208e08ea88461aba4d1460d74344a9f1cbe3289.
Complete batch replies/export/snapshot are in artifacts/ceiling-wrapper/rea-batch/.
Other wrapper entries were not recognized procedures; explicit mapped-offset
queries also failed, retained in rea-mapped-batch/. Supplementary bytes establish
their bounded contracts; missing pseudocode does not establish missing code.
LabSimulation now performs the source-root query after body integration and before
controlled movement/fire, even without control. Fresh input precedes this Jimmy
wrapper; retained input follows Jimmy/fire, preserving the recovered registry
boundary. For the three recovered route
scenes, Program supplies TraceGeometry independently of the modern camera-only
debug toggle. A ceiling hit reflects velocity and applies mode1 cancellation;
the later owned fire phase independently subtracts dt. Noclip bypasses this path.
Other scenes retain the previous capsule ceiling adapter until their registration
filters are recovered. Capsule position response/root placement remain provisional
even in route scenes; full sound/gadget cleanup and complete wrapper ordering are
explicit gaps, not implied by the new velocity/cancellation contract.
Four Python source/projection groups and one coupled movement group cover the
150-unit root ray, pending-impulse boundary, raw-control independence, mode0/1,
active powered-fire cancellation, hold preservation, post-cancel energy and phase
order. Camera tests check that the modern camera switch neither disables geometry
queries nor overwrites camera diagnostics. Port regressions are separate from the
original kernel probe documented in collision-response.md.
@@ -0,0 +1,173 @@
# Ordinary body composition479D20
2026-10-27 UTC. Independent source investigation for the managed composition
chunk. The EXE SHA256 is
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Preferred VAs below are PE-mapped by body_composition_contract.py; text raw
offsets equal VA−400000 for these supplied bytes. The helper guards the entire
479D20..47A329 body plus81 decisive instruction sites and12 Jimmy vtable targets.
## Evidence and scope
Retained REA479D20 Evidence
`ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0`
is in artifacts/collision-response/rea-response/01.evidence.json. Its incomplete
prototype/local-variable reconstruction must be checked against instructions;
the actual caller supplies actor interface and dt. Reviewed disassembly is saved
to artifacts/collision-integration/body-composition.instructions.txt; fixed source
anchors/offsets are in body-composition-contract.json. No original executable
entry point or original routine was executed in this independent investigation.
The ten prior copied-code body observations remain separate in
[collision-body-probe.md](collision-body-probe.md).
Focused new REA/Ghidra session used the existing generated EXE copy, exported
Evidence, then closed normally under artifacts/collision-integration/rea-body-radius/:
| Procedure | REA Evidence |
|---|---|
|471240, authored/current radius setter|ev_d77d8a0d308e4d9b71dbb0cccfcf68771bd4552a9d4a09c50d14225ec171b058|
|471B40, live body-radius setter|ev_97d21014bcdac4f44484c1c079e957f22d449b60efd7c2a31be450deddc38871|
437F90 was not recognized as a Ghidra procedure; the complete error remains in
00.json. Its burst call site is supported by reviewed instructions/fixed guards,
not attributed to successful pseudocode. No unchanged failed query was retried.
## Recovered phase order
The body pointer is the game interface, complete-object+C0 for Jimmy. Slot offsets
in this report are interface-relative.
| VA / raw offset | Source operation and ownership |
|---|---|
|479D2E /79D2E|Read support218 and cache previous support in global695D49.|
|479D3D..4E /79D3D|If support handling1C8 is enabled, write current support21C(false).|
|479D58..60 /79D58|Only now test integration210; false returns with the preceding support side effects intact.|
|479D6F..479DD4 /79D6F|Read current root310 and old previous root2F8; compute quick magnitude of their difference and discard its result. This is not a pre-support/gravity cancellation query.|
|479DDA..479E54 /79DDA|Test global geometry4F69E5, independently of prior support. Enabled: anchor2F4(0,−25000,0). Disabled: support21C(true), anchor(0,current-root-Y,0), acceleration278(0,−gravity.Y,0), velocity2C4(oldX,0,oldZ).|
|479E63..479EAC /79E63|Read angular velocity2AC, rotate334(angularXYZ×dt) before consuming impulse.|
|479EBB..479EF2 /79EBB|Read pending impulse284, add XYZ through velocity2CC, clear impulse28C(0,0,0) once.|
|479F01..479F4A /79F01|Read acceleration270, add accelerationXYZ×dt to velocity.|
|479F50..479F7E /79F50|Separately add global gravityXYZ×dt.|
|479F8D..479FD2 /79F8D|Read resulting velocity; store displacementXYZ=velocityXYZ×dt.|
|479FD6..479FF0 /79FD6|Read collision flag220, then world-response1D0 when collision is enabled. These gates are distinct from global geometry and support.|
|47A038..47A096 /7A038|World branch clears last polygon695D4C, sets face695D5C=130000 and edge5CFBE0=radius260, copies current root into previous-root2FC, clears auxiliary695D84.|
|47A090..47A11F /7A090|If displacement.Y>0, dispatch47B4B0 with fullXYZ. If Y<=0, dispatch with XZ/zeroY, then add original falling displacement.Y to candidate.Y. Edges flag is true in both paths.|
|47A123..47A181 /7A123|After terminal contact callback, read fresh previous-root2F8 and live root310 and compare all four floats. Only equality permits final candidate publication.|
|47A187..47A1C4 /7A187|Clamp candidate **Y** below−25000 to−25000, then publish Vec4 via314; if any previous/live component differs, skip clamp/publication.|
|47A22A..47A235 /7A22A|If1C8, run support47B890 after displacement/callback/publication. It uses the original previous support695D49 for landing transition.|
|47A241..47A25A /7A241|Read published scalar268/live160. Equal zero invokes friction47A330; this is not controller scalar608 or a raw-control test.|
|47A298..47A2D1 /7A298|Read suppression scale230/live144. Angular quick magnitude×scale<=0.1 zeros angular velocity2B4.|
|47A2E0..47A31D /7A2E0|Linear quick magnitude×scale<=0.1 plus a fresh268==0 zeros linear velocity2C4.|
Publication from the dispatcher means writing the caller's candidate stack vector,
not necessarily changing actor root310. The later Vec4 equality check preserves
contact-owned transform changes. It compares freshly read previous/live roots;
it is not a comparison with a stale local copy and must include W. Ordinary
370 and nonspecial Jimmy374 do not move the root, so a bounded ordinary adapter
can keep W=1 explicitly. A future special callback must preserve this boundary.
The body does not automatically reset movement mode/jump/fire on support. Source
landing37C for Jimmy is a no-op; later controller/fire callbacks own those states.
Landing observer order and friction details are in
[collision-contact-callbacks.md](collision-contact-callbacks.md).
The rotate334 call's order and XYZ arguments are recovered here; this does not
recover generic334 angle wrapping or logical/render transform synchronization.
The original body fixture substitutes a simple Euler-add virtual, so its angular
cases cannot independently prove the real transform implementation. An ordinary
live bridge supplying zero angular velocity remains within a narrower contract.
## Flag branches and shared state
If220 is true but1D0 is false, source47A1CC..47A220 copies current root to
previous2FC and translates31C(displacement). Support and published-speed friction
still run afterward. It does not initialize/query the static context in this path.
If220 is false,47A264 tests228. When228 is false, it translates31C(displacement);
when true it does not translate. Both skip support and friction, but still run
the suppression tail. The initial support clear remains, if1C8 was enabled.
Treating all of these modes as a single collision/noclip boolean would lose
source state changes. Modern F3 noclip is a separate user-requested policy.
Prior source guards establish ordinary defaults: support1C8/live13B=true,
world1D0/live13C=true, integration210/live13E=true, collision220/live140=true,
228/live141=false. Player overrides prevent-lowering208/live13A=true; direct
dispatcher member42C defaults0. Generic suppression-scale default0.5 is
46FE01→471120→234, and Player friction default0.8 is4373B0→4711B0→24C→live150.
These are initialization contracts, not invariants after authored/script setters.
Static context resets occur once before body world traversal. Retries retain
nearest/last polygon. Dynamic response uses its own face/edge initialization and
can retain the last-polygon global; it remains a separate shared-scene contract.
No new meaning is assigned to auxiliary695D84 in this bounded investigation.
## Init restores authored speed separately from current publication
Retained REA470540 Evidence
`ev_c16f95e608194a8f9fb029430f1c6a01512d34099ebf447cf944946c79631166`
in artifacts/collision-integration/rea-support/02.json covers generic Init's scalar
copy. It is independently linked to Jimmy's vtable and the guarded leaf bodies:
| Source site | Initialization contract |
|---|---|
|4706CF /706CF|Calls Jimmy interface114→471260, reads authored float interface38.|
|4706DB /706DB|Passes that value to interface26C→471B60, writes current published160.|
|46FC08 /6FC08|Constructor zeroes EBX.|
|46FE51..54 /6FE51|Pushes EBX=0, invokes471270 (authored-speed setter).|
|471270 /71270|Stores authored38, then forwards the same value to26C/live160.|
|471B50/471B60 /71B50/71B60|268 reads and26C writes current published160 only.|
Controller437C22..2D publishes through26C after applying movement, so it changes
current160 without changing authored38. Preparation43A750 clears controller608
and velocity but not either speed field38/160. Ordinary/retained Init through
437890→4587F0→470540 therefore reapplies authored speed; constructor default is0
and the current route's Jimmy properties do not assign another authored speed.
The bounded bridge's per-scene PublishedSpeed=0 follows this initialization
chain, rather than being inferred from controller608's separate Init reset.
Init is a copy of authored38, not an unconditional zero invariant. A future caller
of interface118→471270 with a nonzero authored value must preserve that value
through subsequent Init. No new source execution is claimed for this follow-up;
the retained REA Init result plus fixed getter/setter/constructor bytes establish
the route/default contract.
## Burst radius is the same live physics radius
There is no independent interaction-only100 radius in this source path:
| Source link | Structure/write |
|---|---|
|437FA3|Air helper obtains EDI=complete object+C0, the same game interface.|
|4384E4 /4384F3|Allowed burst with an effect pushes100, calls interface264.|
|Jimmy table4A373C+264→471B40|Writes interface15C, current body radius.|
|Table+260→471B30|Reads exactly interface15C;479D20 and47B890 both consume260.|
|PostLoad4236A3→110→471240|Writes authored34 then invokes264, initializing current radius60.|
|Held-state3 landing4386C1..C8|Writes current radius60 directly through264.|
|PostLoad4236B3→100→4711E0→254→471B00|Sets live support factor154=1.265;250→471AF0 reads it.|
Thus radius100 changes both sphere response and radius×factor support clearance
and root offset, to126.5 with the ordinary factor. Grounded Jimmy's ordinary
wrapper restores60 in its later object phase; physics/support must not perform
that restoration early or clear it merely because control is absent. Other
gadget radii (for example Bubble/mode0 radius160) remain outside the ordinary
default-device subset. Gadget continuation corrects the earlier Scooter label;
see ../gameplay/gadget-controls.md for display index versus raw mode.
## Verification and remaining integration questions
`python3 -m unittest discover -s tests -p test_body_composition_contract.py -v`
passes eight groups: original body/site identity; disabled-integration support
clear; phase order; descending split; three distinct flag gates; four-component
publication predicate; shared burst/support radius targets; Init authored/current
speed separation. These fixtures are
explicit source control-flow projections, not original execution or managed body
numeric verification. Existing ten isolated body observations and primary's
managed comparisons provide separate numeric evidence recorded by primary.
Before VR04 live use, compare root/support while radius changes60→100→60, retain
separate published160 versus controller608 across control loss, and verify the
phase owner for restoring radius. Source collision root and modern render foot
translation remain separate: no new capsule height or visual sole correction is
derived here. Full wrapper/registry, exact x87 cell/quick-magnitude boundaries,
special160/164/FENCE/LADDER callbacks, dynamic global context and whole original
game comparison remain open. An ordinary component passing numeric fixtures does
not establish those broader contracts.
@@ -0,0 +1,92 @@
# Ordinary body and VR04 bridge review
2026-10-27 UTC. Independent read-only review of primary's current
OriginalBodyPhysics.cs, LabSimulation.cs and Program.cs against
[the source contract](collision-body-composition-source.md). This investigator
owns only this report. No new original execution or REA session was necessary;
existing retained body/radius Evidence and guards establish the reviewed facts.
## Result
No directly evidenced mismatch was found within the stated subset: enabled
integration/support/collision/world flags, prevent-lowering enabled, lower-edge
override disabled, ordinary Jimmy contacts, fixed factor1.265 and zero angular
velocity in the live bridge. The implemented composition preserves source
impulse→acceleration→gravity, positive-Y/full versus nonpositive-Y/horizontal-first
motion, terminal370 positive-Y clearing, support/landing order, independent
published160 friction gate and final suppression. Fresh per-body nearest context
agrees with the source world branch's explicit resets.
The absence of special Player374 behavior is enforced conservatively by rejecting
any source scene with potentially eligible special-contact material IDs. Omitting
the source Vec4 previous/live-root reentrancy test is justified only inside this
bounded no-root-changing-contact subset; the explanatory source comment says so.
Generic334 angle wrapping/transform behavior remains outside the zero-angular
bridge, and the component's nonzero-angular numeric fixtures use the original
probe's substituted Euler-add virtual rather than real source334 execution.
## Integration checks
- Program selects the source body only for actual VR04; lab/outside keep their
existing adapter. OriginalBodyPhysics rejects special-contact geometry and
StepOriginalPhysics rejects attaching the provisional dynamic resolver.
- The live radius passed to body/support is InteractionRadius. This correctly
incorporates burst100 and later wrapper restoration60, rather than retaining
the old capsule24 radius or treating100 as interaction-only. Constant75.9 is
a conversion between modern feet storage and actor root, not the solver's
variable support offset. Rendering's sole correction remains a modern policy.
- Physics still runs before Jimmy input/controller/fire. Grounded radius60 is
restored in the wrapper before ownership checks. Preparing a script clears
controller speed/velocity while preserving body published160, pending impulse
and independent acceleration. A new scene resets published speed separately.
- The bridge supplies zero angular velocity and derives the next state from
current actor root/velocity/acceleration/impulse/support/published speed each
body pass. Dropping the component's angular output does not lose live angular
state inside this declared zero-angular subset.
- Camera debug enable remains camera-only; the body's geometry and overhead
query do not use it. Modern noclip bypasses the body while enabled and resumes
it with cleared motion through the existing debug policy.
## Scope risks and next gates
1. **Prepared doors are not every original dynamic body.** Program rejects a
nonempty StaticSceneVisuals.DoorColliders sequence in the source subset. This
establishes only absence of those prepared doors. Actual VR04 entities include
3SOL,3ROC,3TRO and other classes; their complete original physical-list and
pair-collision eligibility is not closed by that check. Preserve the explicit
no-dynamic-body-pass limitation and recover source registry/flags before
claiming complete tutorial collision fidelity or extending the adapter.
2. **Modern noclip exit uses the old occupancy policy.** SetNoclip(false) still
checks SceneCollision.CanOccupy with capsule24/render-derived height. Source
body response can subsequently reposition a root that this debug test admitted.
The ordinary flight/return test does not establish radius60/100 admission at
walls or tight gaps. Keep this as a documented debug policy; a later source
occupancy check needs an explicit supported contract rather than silently
treating zero-motion dispatch as a complete overlap query.
3. **Initial/visual placement is still bounded.** SceneCollision.GroundHeight and
floor-derived rendering are used to initialize the modern bridge. The stable
VR04 root/sole tests verify port consistency, not original transform/pivot
equivalence. Source spawn/root settling and wrapper/base logical-to-render
synchronization remain separate comparisons.
4. **Shared dynamic context remains unimplemented.** Fresh source body contexts
must not later be reused for dynamic reclipping without the recovered reset/
last-polygon schedule. Special contact root writes require the source Vec4
publication condition; a generic wall reflection is not an adequate substitute.
5. **Gadget scope remains−1/3.** Source gadget7 has additional374 side effects;
source scooter uses another radius policy. The current bridge does not carry
those contracts into OriginalBodyPhysics. Future gadget-selection expansion
must restrict or implement them before broadening this solver's claim.
These are retained integration boundaries, not failures of the ten-reference
ordinary composition. They do not require changing the verified source arithmetic.
## Verification
`source scripts/env.sh && dotnet run --project tests/GamePort.BodyPhysicsTests --
../Original` passes20 groups independently during this review, logged to
artifacts/collision-integration/body-implementation-review-tests.log. Coverage
includes ten original copied-body references, positive/nonpositive split,
ceiling370, radius100 support, unclamped friction, actual VR04 root/visual
consistency, preparation/published speed, control-independent impulse, retained
flight/landing and ordinary noclip return. These are managed port checks;
primary's headless/native/GPU/whole-route results are recorded separately.
@@ -0,0 +1,86 @@
# Ordinary body implementation and tutorial bridge
2026-10-27 UTC. This chunk composes the recovered static dispatcher with ordinary
Jimmy body integration and enables that bounded path in VR04. It does not close
all collision, dynamic bodies, special contacts or original visual comparison.
## Evidence and implementation
[Source composition](collision-body-composition-source.md) records the whole-body
hash,81 guarded sites,12 virtual targets, callers, offsets, flags, source root
publication condition and new REA radius Evidence. [Original component results](collision-body-probe.md)
provide ten copied479D20/support numeric references. No original game entry point
or full Jimmy instance was executed by this implementation chunk.
OriginalBodyPhysics implements the true210/1C8/220/1D0, false228/42C,
prevent-lowering subset. It clears current support, consumes impulse once, adds
acceleration and gravity separately, splits nonpositive-Y motion into horizontal
response then fallingY, and preserves source callback/support/friction/suppression
order.370 clears positive vertical velocity/acceleration independently. Ordinary
374 and inherited37C do not move the root; special-contact worlds are rejected.
This justifies the fixed-W1/no-root-changing-contact publication subset. Future
special callbacks must implement fresh previous/live Vec4 comparison before314.
Landing diagnostics observe new root/zero acceleration and old velocity/support.
Published speed160 is separate from controller608, copied at the controlled tail.
Script preparation clears controller speed/velocity while preserving published
speed, pending impulse and acceleration. Friction reads the preserved body scalar;
control ownership does not suspend physics. The generic scale0.5 suppression and
unclamped friction0.8 follow source contracts. Nonzero angular component tests use
the probe's substituted334 Euler-add contract; the live bridge passes angular0.
Program selects source body only for VR04. Lab/outside retain their prior capsule
because they contain special contact materials and pending dynamic integration.
The source body rejects attaching the provisional dynamic resolver; Program also
asserts no prepared door colliders in this subset. This does not prove absence of
every original dynamic class: VR04 has3SOL/3ROC/3TRO and other eligibility questions.
Live radius is the existing InteractionRadius, which source260/264 prove is the
same body field15C. Burst60→100 changes both sphere response and support offset
75.9→126.5; later grounded wrapper restoration60 stays after physics and outside
the input ownership gate. The replay now records two support landings rather than
the previous capsule's one; radius/support transitions are retained, not flattened
to preserve the old diagnostic count. Maximum rise changes418.98→418.93 because
the source path removes the modern floor skin. Travel remains403.88 in this input
fixture. These are port observations, not original whole-game trajectory metrics.
ActorRoot/feet conversion remains constant75.9 and sole-based rendering remains
the existing modern bridge. Initial placement still uses the bounded floor query;
this does not derive original visual pivot/height or generic transform semantics.
Modern F3 noclip bypasses source physics and clears motion on exit; admission still
uses the capsule24/render-height occupancy check. It is a debug policy, not a
recovered radius60/100 overlap query. Full wrapper/registry remains open.
## Verification
Twenty managed body groups pass, independently reviewed: all ten original-code
numeric references; prior support/landing ownership; angular-before-suppression;
published-speed cutoffs; special-scene rejection; positive/nonpositive split;
ceiling370; radius100 support/unclamped friction; actual VR04 root/render bridge;
pending jump while uncontrolled; preparation/publication; retained jetpack/steering/
landing and noclip return. These tests compile into GamePort.BodyPhysicsTests and
are included in scripts/test.sh. Two existing explicit-source test projects now
include the new dependencies; the initial suite compilation failure is retained
in artifacts/body-composition/integration-initial.log, not reported as a pass.
Headless VR04300-frame replay and native Linux GTX1070/private Xvfb replay at
1920x1080 both pass with zero enabled Vulkan validation errors. Native SDL receives
move/brake/turn/jump and resizes800x600. Both end supported with one burst,
travel403.88, max rise418.93 and energy20 (VR04 exemption). Saved readback shows
the modern standing-foot bridge remains above the visible floor at the final
replay position; this is a port image check, not source pivot comparison.
Logs/readbacks: artifacts/body-composition/body-tests.log, tutorial-jetpack.log,
tutorial-jetpack.png and native/jetpack.log. Independent review is in
[collision-body-implementation-review.md](collision-body-implementation-review.md).
Full-suite, package and preservation results are recorded in progress.md after
their completion. No native Windows runtime result is inferred from cross-builds.
## Next bounded work
Recover original physical-list and pair-collision eligibility for VR04 actor
classes, plus dynamic nearest/last-polygon/reset order. Recover lab/outside's
Player160/164/FENCE/LADDER policies, including control and root ownership, before
using this body solver there. Keep the existing capsule baseline available for
comparison. Shared camera eye/DEFAULT handoff remains the next independent C5
contract; audio clock/banks and later implementation chunks retain their gates.
+122
View File
@@ -0,0 +1,122 @@
# C4 dispatcher and ordinary-body component evidence
2026-10-26 continuation, verified2026-10-27 UTC. Original EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Originals remain unchanged. This report separates copied-code component execution
from the playable port, full original game behavior and native Windows testing.
## Recovered contracts and evidence
The [grid report](collision-grid-traversal.md) recovers47B4B0 recursion, frozen
query bounds, repeated FIFO cell visits and terminal callback ownership. The
[contact report](collision-contact-callbacks.md) recovers370/374/37C, special
material identity, separate published speed and friction. Those reports retain
addresses, file offsets, byte guards, callers, structures and REA Evidence.
Additional closed/exported REA sessions in artifacts/collision-integration/:
| Procedure | Evidence | Contract |
|---|---|---|
|47A330|ev_8be4a538fe941bcf0ba77ce64f552d4f0e17969ea87713cec5d37d39bc560735|Supported/nonzero-linear friction; published160 gates caller.|
|47C6E0|ev_ad96a93792dcf00534130fbd428fb52fa25e2cf9c2492df43f89f425b80c3f08|All-grid strict nearest support reduction, initial segment magnitude.|
|471120|ev_90314124d5ab1c88911198ef9e8d43ad7cc9e096ca075757d29c5e15cf1f86eb|Authored float8 writes live suppression scale through234.|
|470540|ev_c16f95e608194a8f9fb029430f1c6a01512d34099ebf447cf944946c79631166|Init copies authored flags/scalars through virtual setters.|
Body479D20 remains anchored by ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0
in artifacts/collision-response/rea-response/. Generated source.json reports
PE-mapped offsets; the five added body hashes cover479D20/47A330/47B890/47C6E0/
469A10, alongside ten existing dispatcher/kernel bodies. Hashes and relocation
sites are checked by test_body_step_evidence.py; no arbitrary scan of executable
values is used at execution time. Short accessor recognition failures in rea-body
are retained beside successful replies, not represented as decompilation success.
## Isolated execution boundary
tools/binary/collision_dispatch_probe.c and body_step_probe.c map a generated,
hash-checked EXE copy into their own32bit process. Preferred-base mapping was
unavailable; existing guarded mapper rebases only explicit in-memory operands.
Fixtures supply synthetic grids, shape/polygon/corner arrays and virtual methods;
the body fixture supplies ordinary flags, radius60, factor1.265, friction0.8,
suppression scale0.5 and gravity(0,−800,0). No game entry point, full Jimmy
instance, source window/input/audio/script lifecycle or dynamic body pass runs.
Landing37C is an observer fixture; real ordinary Jimmy37C is a no-op.
reference_capture.py runs a separate generated Wine prefix/copy with no network
and no original-directory mount. Sources/header/identity metadata and logs are
under artifacts/collision-integration/dispatch/ and body-probe/. Initial fixture
failures are preserved: a missing Euler328 virtual was diagnosed and supplied,
and direct member42C has allocated zero storage. Those were harness omissions,
not original game defects. Automatic approval review temporarily failed due its
usage limit; after its stated reset time, a normal reviewed retry succeeded.
## Observed dispatcher results
All seven original fixtures completed with DISPATCH_COMPONENT_COMPLETE. Managed
OriginalStaticCollision regressions compare these positions and exact counts.
| Fixture | RootXYZ | Passes / primitive visits | Terminal callback |
|---|---|---|---|
|face retry|0,20,10|2 /4|wall0|
|edge retry|107.071068,100,7.07106781|2 /2|wall0|
|edges disabled|105,100,5|1 /1|none|
|zero motion|0,20,20|0 /0|none|
|forced zero/member42C|0,20,20|1 /2|none|
|corner retry|5,20,10.000001|2 /8|wall0|
|ceiling retry|0,90,0|2 /8|ceiling0|
## Observed body results
All ten copied479D20/support fixtures completed with BODY_COMPONENT_COMPLETE;
finite-output assertions pass. These are observations for the next body adapter,
not claims that a managed full-body equivalent already exists. dt is float1/60;
all unspecified vectors are zero. Initial previous support is false except jump.
| Fixture | Initial distinction | Observed result |
|---|---|---|
|floor support|RootY75.9|Y75.9000015, supported, callback sees Vy−13.333334/support=false.|
|spawn settle|RootY26|Same support root/landing observation.|
|pending jump|Supported, impulseY550, accelerationY−264|Y84.7711105, Vy532.266663, unsupported; impulse consumed.|
|fall above floor|Y100, Vy−200|Y96.4444427, Vy−213.333328, unsupported.|
|fall land|Y76, Vy−200|Y75.9000015, Vy0; callback sees old Vy−213.333328/support=false.|
|ground friction|V(100,0,50), angularY12, published speed0|Root(1.66666675,75.9000015,0.833333373); V(98.6666641,0,49.3333321), angularY11.8400002.|
|published speed|Same vectors, published speed100|Same root; V(100,0,50), angularY12, no friction.|
|stationary angular|Linear0, angularY12|AngularY12 remains; zero linear magnitude skips angular friction.|
|small motion|Vx0.125|RootX0.00208333344 then velocity suppressed to0.|
|geometry disabled|Vy200, accelerationY−264|Y75.9000015, Vy0, accelerationY800, supported, no landing callback.|
The geometry-disabled branch479DF7..479E54 sets supported, anchor and acceleration
before impulse/integration. It does not test prior grounded state. This corrects
the earlier C3 support-cancellation interpretation. With geometry enabled, the
jump fixture applies acceleration and gravity normally.
## Implementation and remaining gate
This section records the dispatcher-only stage. The subsequent
[ordinary-body implementation](collision-body-implementation.md) compares all ten
body references and enables the static subset in VR04; special/dynamic/root gates
below remain explicit for further expansion.
OriginalStaticCollision is currently an isolated source dispatcher/support-grid
component, invoked by tests. It preserves duplicate visits, retry state, negative
Z upper-bound quirk and terminal publication. Its explicit geometry-enable input
skips primitive calls but preserves terminal callback. TraceSupport uses strict
nearest reduction. The256-pass rejection is a defensive port boundary; original
recursion has no recovered depth limit. Double cell intermediates/modern quick
magnitude tables do not promise exact x87 boundary equivalence. Triangular route
metadata is required; general polygon fans are rejected by duplicate identity.
Prepared scenes now include signed3DMa archive IDs. Mesh keeps an explicit
identity-completeness flag; source grid construction rejects old prepared metadata.
Camera behavior is unchanged. Lab/outside contain special fence/climb/ladder IDs;
VR04 contains none. This is a scene-data fact, not proof every lab trajectory
contacts one or that all Player374 policies are implemented.
Next coherent implementation: combine the proven dispatcher with ordinary body
integration, negative-Y horizontal-first split, callback370, support/landing order,
published160 friction and suppression, comparing the ten references above. Start
with an explicit ordinary-contact subset (VR04); reject unsupported special policy
rather than silently discarding it. Then test model/root support, airborne input,
ceiling and tutorial/RETURN through the live adapter. Lab/outside require recovered
special160/164/FENCE/LADDER policies and dynamic shared nearest/last-polygon/reclip
ownership before replacement. Whole-scene registry/base transforms, camera shared
eye, original end-to-end comparison and native Windows validation remain open.
@@ -0,0 +1,253 @@
# C4 contact callbacks, landing and friction
2026-10-26. Static recovery for original EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Addresses below are preferred VAs; these text offsets are VA−400000. The helper
maps PE sections independently and retains exact bytes, offsets, 20 virtual
targets and six complete callback hashes in
`artifacts/collision-integration/contacts/source-contract.json`.
## Recovered dispatch and state ownership
The game-interface pointer is complete object+C0. Slots below are relative to
that interface, not the complete-object movement slots130/134.
| Class/interface table |370|374|378|37C|
|---|---|---|---|---|
|C3DObject4D3154|472690|458890|472750|472970|
|C3DAnimated48FE1C|472690|458890|472750|472970|
|C3DPlayer4AF6C4|472690|43AA40|472750|472970|
|C3DJimmy4A373C|472690|42A660|472750|472970|
Static traversal47B4B0 publishes its candidate current root at47B7B1..BD,
then reads last-hit polygon695D4C. If present, it copies polygon+8..14 normal
and dispatches374 at47B80F if normal.Y is strictly greater than float32−0.7
(4A3148, bytes333333BF); otherwise370 at47B82E. Equality dispatches370.
The arguments are a by-value four-float normal and polygon pointer. This occurs
after grid/triangle response, before the body's later support/friction phase;
the supplied original stored normal is not derived from triangle winding.
370→472690 (raw72690, lengthBA) independently reads live velocity2BC and
acceleration270. A strictly positive Y is set to zero through2C0/274;
nonpositive Y and X/Z/W are preserved. It does not project against the supplied
normal or change movement mode, jump latch, fire timer or horizontal speed.
Generic374→458890 (raw58890, length3D) checks interface1D8, then forwards the
four-float normal to378→472750. Jimmy overrides374:42A660 (raw2A660,lengthB4)
forwards to Player43AA40 at42A70B on the ordinary path. It does **not** enter
generic374/378 on that path. Therefore generic reflection/projection must not be
attached to every Jimmy wall contact merely because base378 exists.
No-selection−1 and selected-jetpack3 both take this ordinary branch because
neither equals7 (selection identities recovered in retained-return-cleanup.md).
For a nonspecial metadata ID, neither state adds velocity, position, orientation,
mode, jump or gadget-side effects through374. This bounds the route's supported
states; it does not imply every material on the route is nonspecial.
Jimmy's gadget7 branch additionally checks global4F8210. When set, it invokes
Player contact, zeros global4F82BC/C0, tests their prior two-component magnitude
against60, and may invoke complete-object204 and set interface1D65. Those
gadget effects remain outside ordinary-contact integration.
## Player material handler
43AA40 (raw3AA40,length5A3) first requires interface774 elapsed>3.0. The signed
discriminator comes from polygon+4 → material+0C → database chunk+8; missing
records produce no ordinary effect. The follow-up below proves this is the
3DMa archive resource ID, not an additional custom payload flag. It remains
distinct from a merged render-array index or texture resource ID.
| Metadata ID | Effect after elapsed gate |
|---|---|
|120..129|Calls complete-object160 with supplied normal.|
|110..119|Calls complete-object164.|
|60..69, only mode704==0|Additional rays/orientation/root/action handling ending in FENCE.|
|180, only mode704==0|Additional rays/orientation/root/action handling ending in LADDER.|
|Others|Returns without generic velocity projection or mode/jump reset.|
These are dispatch facts, not complete recovery of the four special policies.
Complete160/164 effects and all ray success/failure transitions need separate
tracing before implementation. The ordinary callback has no raw-control5099E4
gate; controller ownership alone cannot justify suppressing contact effects.
## Material database identity and actual route coverage
OMT2.dll SHA256 is
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
The EXE chain above reaches OMediaDBObject's inherited database association:
| DLL VA / raw offset | Proven role |
|---|---|
|10030070 /30070, exported db_link|Arguments are database, OMediaFSChunk*, type.1003007F stores that chunk pointer in material/object+0C; chunk+0C is the reciprocal object pointer.|
|10030260 /30260, DBObjectStreamLink::read_class|Reads link fourcc through100302B3 and signed long ID through100302BF;100302EE calls database get_object(type,ID), stores resulting material pointer in temporary streamlink+4.|
|10003E20 /3E20, Polygon::read_class|10003F56 reads a temporary stream link;10003F5B obtains its pointer at temporary+4;10004277 calls set_material100043F0.10004408 publishes it in polygon+4, with material reference-count bookkeeping. The legacy-version path10004252..5E also uses set_material.|
|1002DEF0 /2DEF0, DataBase::get_object(type,long)|Looks up the requested chunk through formatted-stream slots6C/74, then passes that chunk to object's virtual18/db_link at1002E0B0.|
|10045B70 /45B70, FormattedStream::get_chunk(node,long)|Looks up signed ID in the chunk map, returns the corresponding chunk record (list-node+8).|
|100464C0 /464C0, FormattedStream::load_header|100465A7 reads ID into stack58;100465B4/C1 read offset/size into stack50/54;10046638..46 insert record starting stack50. Thus ID is chunk record+8.|
The on-disk source is the 0MF2 resource-table entry's big-endian32 identity,
not a field inside the 3DMa material payload. The payload parser's trailing BE16
is3 for every used material in all three archives, including special and
ordinary contacts. The helper records each material's exact table ID byte offset,
separate payload offset/size/hash, archive hash, and source shape/polygon identity.
Negative on-disk IDs require signed32 interpretation for policy comparisons;
all special route IDs below are positive.
| Archive | Special ID | Non-NC polygons using ID | Wall-grid polygons eligible for374 |
|---|---:|---:|---:|
|level1b.omt|61|23|20|
|level1b.omt|62|24|24|
|level1b.omt|63|4|4|
|level1b.omt|120|4|4|
|level1b.omt|121|32|20|
|level1b.omt|122|3|3|
|level1b.omt|180|6|6|
|VR04.omt|none|0|0|
|level1.omt|60|62|62|
|level1.omt|61|51|38|
|level1.omt|62|38|26|
|level1.omt|180|32|20|
Eligibility means registered shape and strictly−0.7<stored normal.Y<0.7:
the lower test dispatches374; the upper test is wall-grid registration. Route
checkpoint-name exclusions are zero (camera-ray-predicate.md). Counts do not
prove a particular player trajectory hits these polygons. LV1B examples are
crates/topcrate shapes76/77 with ID61, Box25/83 with62, Object07/91 with63,
Plane41/51 and Object03/73 with120, Cylinder13/22 andCylinder14/23 with121,
Object03/73 with122, Box31/93 with180. Level1 has fence/bush/blocks/ladder-class
polygons; names are explanatory labels, not policy evidence.
The route cannot be declared ordinary-only. Preserve linked3DMa identity in
CollisionPolygons, retain unsupported special callback boundaries, and test any
ordinary-only integration against the actual contacted polygon's ID. Resource
identity is now justified by the loader trace, rather than assumed from naming.
## Landing order
Support47B890's successful branch calls these virtuals in order:
1. 47BB32: publish root318.
2. 47BB4B: acceleration278, Y=0, retaining original X/Z.
3. 47BB5E: landing37C only if previous-support695D49 was false.
4. 47BB74: velocity2C4, Y=0, retaining original X/Z.
5. 47BB80: support21C=true.
6. 47BB91/47BBA1: contact shape34C and polygon33C.
Jimmy37C→472970 (raw72970) is exactly `C3`/return. Thus the landing callback
would observe the new root/zero vertical acceleration but old velocity/support;
Jimmy itself adds no mode/jump/fire reset here. Controlled movement and the
independent fire callback own their later grounded transitions. Do not merge
these source phases into a universal landing-mode reset.
## Friction and speed publication
479D20 calls support47B890 at47A235 when interface1C8 permits it. It then reads
268 at47A241 and calls47A330 at47A25A only if the returned scalar equals0.
268→471B50 reads interface160. The controlled movement tail437C22 reads its
current scalar speed608, pushes it at437C2A and publishes through26C at437C2D;
26C→471B60 writes160. Publication follows ground/air apply and is skipped by
the earlier ownership/modal gates. Treat published160 and controller608 as
separate state with that copy point, not a fresh input query during friction.
47A330 (raw7A330,lengthF1) requires a nonnull body, support218=true and strictly
positive imported quick_magnitude of the full linear XYZ vector. It reads
friction248→471AD0/live150. It adds these deltas through2CC and2B8:
```
linear delta = (-vx * friction * dt, 0, -vz * friction * dt)
angular delta = (-wx * friction * dt, -wy * friction * dt, -wz * friction * dt)
```
No multiplier clamp is present. Zero linear velocity skips angular friction too;
pure vertical linear motion permits angular friction but leaves vertical speed.
No controller pointer, movement mode, jump or animation state gates this helper.
The enclosing body's later suppression is distinct:230→471A70/live144 scales
quick_magnitude. Angular magnitude×144 <=float32(0.1) zeros angular velocity;
linear magnitude×144 <=0.1 zeros linear velocity only when268==0. The finite
equality boundary is included by the AH&41 tests at47A2C5/47A2FA. The semantic
name of144 is not established by this bounded contact investigation. Follow-up
REA471120 and constructor46FE01..08 recover the default0.5; this is called a
suppression scale in the implementation plan without assigning physical units.
Constructor byte confirmation: generic46FDC8→470FA0 sets1C8/live13B true;
46FDD1→470FD0 sets1D0/live13C true;208/live13A starts false at46FDBF but
Player43740D→470F70 overrides it true (EDI=1).220/live140 defaults true through
46FDF4→4710C0 (authored18);228/live141 defaults false through46FDFC→4710F0
(authored19). Generic46FFB1 writes interface42C=BL=0, with EBX zero at46FC08.
These are constructor defaults, not invariants after property/script changes.
## Evidence and verification
Own REA CLI sessions used only the generated
`artifacts/uncontrolled-phases/rea/Neutron.exe`, Ghidra provider. Complete open,
procedure replies, exported evidence, close and snapshot files are preserved in
`artifacts/collision-integration/contacts/rea-callbacks/` and
`rea-offset-followup/`. Both sessions closed. Session analysis errors are also
preserved;42A660 and472750 were unrecognized by both VA and corrected raw-offset
selectors. This is a REA procedure-recognition limitation, not evidence of an
absent function. Their bounded conclusions use reviewed source instructions and
fixed byte/vtable guards; no pseudocode is attributed to those failed queries.
| Procedure | REA Evidence ID |
|---|---|
|472690|ev_122849f87121b02fefe6a3a443f75c7f02fee30c59c816b617d30e1f98fc2cff|
|43AA40|ev_4f2a6aa666451db831efd46f5c587573e22d8072315626b8bc2f844f9c6f0cae|
|47A330|ev_8be4a538fe941bcf0ba77ce64f552d4f0e17969ea87713cec5d37d39bc560735|
|472970|ev_1af0165b36fee8d2c680091bdaa560a63092016b1010baa947b0fe672f790520|
|458890|ev_2e4ec83ea68f06777162a80ab45793cff068e973dc248556d4a408932d24c85a|
Caller/traversal evidence is reused from collision-response.md, especially
479D20 `ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0`
and47B4B0 `ev_d45e078c585d3773494c0e0dfb1696178dd0b8ce8b696caf133892ff070e552e`.
Reviewed instruction cache: `artifacts/retained-lifecycle/exe-disassembly.txt`.
`python3 -m unittest discover -s tests -p test_collision_contact_callbacks.py -v`
passes eight tests: original identity/50 sites/20 virtuals/six complete bodies,
normal threshold equality, independent positive-Y clearing, material branch
boundaries, no-selection/jetpack gadget exclusion, friction gates/no clamp, and
landing callback observation order;11 DLL linkage/header/publication byte guards plus
decoded route special-ID coverage and payload/table distinction.
The helper fixtures are explicit source projections, not original execution or
x87 numeric identity. No original process ran during the independent callback
investigation; primary's later isolated dispatcher/body executions are documented
separately in collision-body-probe.md.
Confidence is high for guarded targets, finite-input gates and write order;
special callback policy and native runtime equivalence remain unverified.
Follow-up own closed REA sessions and complete exports are in
`artifacts/collision-integration/contacts/rea-material-identity/` and
`rea-material-chunks/` and `rea-polygon-material-link/`, using the generated
asset-probe/game/OMT2.dll copy. All three sessions closed and exported evidence.
| Procedure | REA Evidence ID |
|---|---|
|10030070 db_link|ev_68d90891887ea6865b9caa01929af4c321701bd7c4a2812727fdf42c75cc4007|
|1002DEF0 get_object|ev_81d436d02d94e725815b1f09da5e5a70d12a65a699580a4f4d766fd637e25c9a|
|10030260 stream link|ev_a36a19b371e3f9202b8e7b44f6756593081a18da9f24dcb3a23fcdd92836ad9a|
|10001490 material read|ev_f592b625a60ec683a17627d671c47d78d722eb39d5eb407744d53a283ee2586d|
|10045B70 get_chunk|ev_1eef58e78dd2025953bfc6d29d750992ad031eff3ade40848b565b70493a51af|
|100464C0 load_header|ev_25667da3ab34f3e3a238282bf667878fa957db0b59501f737178637dd8fe2d61|
|100451E0 create_chunk|ev_bb9a4656bc3b4cc1ebd2ce7da540b2f5d633632cc70b9548f30942e52c806868|
|10003E20 polygon read|ev_a611c0c32859d598bd4f02c071cc8f57dec8e85c821593187d3ea6d0b2db18cb|
|100043F0 set_material|ev_66c8163e76d1c4621dd75dbad433b6810d7dc6f69da84d4bdcd6644df935736b|
|10073E00 stream operator|ev_01e2fb540f6adee163371853f0823abcd4a67553b0dc7d067ef88a448ce87740|
## Minimal implementation contract and limits
OriginalSphereResponse currently implements only the bounded triangle kernel;
LabSimulation still calls its capsule adapter at inspection time. Integration
should retain the original traversal's final contact polygon and stored normal,
publish the root before contact dispatch, apply inherited370 positive-Y clearing,
and preserve ordinary374's material-policy boundary. Then run support in its
source order, friction using persisted published160, and separate small-motion
suppression. Contact callbacks are eligible when Jimmy is uncontrolled if the
body phase itself runs; they do not grant input ownership.
Do not add generic horizontal velocity projection, automatic jump/mode reset,
or unconditional friction to compensate for adapter symptoms. Static geometry
order/duplicate visits, dynamic reclipping, negative-Y split and support query
coverage belong to the separate body integration trace. Generic378's complete
reflection arithmetic, special materials, gadget7, runtime-mutated flags,
144 semantics, NaNs and x87 threshold identity remain explicit gaps. Native
Windows gameplay and the lab→tutorial→lab→outside route still require runtime
comparison after integration; these static fixtures do not claim that proof.
+142
View File
@@ -0,0 +1,142 @@
# C4: static grid traversal and retry ownership
2026-10-26. Recovered from EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
These are source facts, with local algorithm fixtures; this investigation did not
execute the original grid dispatcher. VAs below map to EXE offsets by subtracting
400000; uninitialized globals have no file-backed offset. The helper reports PE
mapped offsets and raw bytes independently.
## Dispatcher contract
47B4B0(actor interface, mutable previous-root Vec4 pointer, delta Vec4 by value,
edge-enable byte) computes quick_magnitude(delta) at47B4BB. Actor **member byte
+42C**, not a virtual method, forces processing. Otherwise magnitude below
FLT_EPSILON(1.1920928955078125e-7;4D5E40) returns without moving the root.
Equality processes. Candidate XYZ starts as previous+delta, W=1. Actor virtual260
returns radius. Bounds use extent E=radius+quick_magnitude(delta).
For C(v)=signed16(truncate(v*float(0.002)+130)), the frozen bounds are:
| Bound | Source expression |
|---|---|
|xmin|min(C(previousX−E), C(candidateX−E))|
|xmax|max(C(previousX+E), C(candidateX+E))|
|zmin|min(C(previousZ−E), C(candidateZ−E))|
|zmax|**min**(C(previousZ+E), C(candidateZ+E))|
The asymmetric zmax is explicit:47B61B `cmp di,ax`;47B61E stores DI;
47B624 `jl` keeps DI if smaller, otherwise47B626 stores AX. xmax uses the
opposite comparison at47B59B. Do not substitute a conventional swept-AABB union.
Scale4D6A04 is float0.0020000000949949026; origin49B1FC is130.
X increases in the outer loop, Z in the inner, both inclusive. Coordinates outside
0..259 are skipped. Wall grid509B24 cell record is12bytes at
grid+12*(260*x+z). Its pointer is the circular-list sentinel. Nodes contain next0,
previous4, registration8. Registration contains polygon pointer0 and shape pointer4.
Traversal follows next pointers in insertion order; the same polygon in several
cells is visited repeatedly. Bounds stay frozen while the candidate mutates.
47B6B2 checks global collision-enable4F69E5 per node. A disabled visit still
increments counters and advances the node; dispatcher position publication still
occurs. Before47BBB0, member42C sets695D74=1 when nonzero;47B742 unconditionally
clears it after the wrapper. This is the primitive's lower-edge override, separate
from the caller's edge-enable flag, forwarded unchanged at47B6FE.
47BBB0 receives the previous root **by value**, the shared mutable candidate
pointer, radius, stored polygon normal and edge flag. The first three source
corners are fetched by477F10. A successful47BD80 result stores this polygon in
695D4C and writes the caller's local retry byte at47BD65..47BD6B. Nearest face
695D5C, nearest edge5CFBE0, hit point5CFBE8..5CFBF4 and695D4C persist across all
visits; dispatcher entry does not clear them.
## Retry, publication and callbacks
REA/Ghidra00.pseudo.txt incorrectly reports47B83C unreachable. Missing output
parameter types hide47BBB0's retry-byte mutation. Instruction evidence is decisive:
47B535 clears local byte;47B799 tests it and47B79F branches to47B83C after a hit.
47B83C..47B867 replaces the by-value delta with candidate−*previousRoot.
47B877 pushes the **same previous-root pointer**, then actor, and47B879 recursively
calls47B4B0 with the same edge flag. This body has no explicit recursion-depth
guard;695D78 is an incremented statistic, not a limit. Do not infer dead code or
a depth cap from decompiler output.
The previous-root pointer is not overwritten before retry. Only the deepest pass
with no newly accepted contact writes candidate XYZ and W=1 to it
(47B7A5..47B7BD). If695D4C is nonnull, that final pass reads the **last accepted
polygon** normal+8/+C/+10/+14, even if this pass accepted no contact. It invokes
actor virtual374 when normal.Y>−0.7, otherwise370; equality selects370.
Both callbacks receive normal Vec4 and polygon pointer. Actor logical position
is written later by the enclosing movement caller's virtual314, so publication
through a stack vector does not itself prove the actor transform has changed.
The body integrator479D20 clears last polygon at47A038, initializes face distance
to **130000** at47A03E (bits47FDE800), and edge distance to radius at47A062.
The isolated primitive's −1 face sentinel is not the body-entry initialization.
Dynamic reclip47B364 calls this same dispatcher with edges=false (47B30B), then
publishes actor root through314 at47B399. It inherits nearest state: dynamic
entry separately sets edge=radius at47AB3F and face=−1 at47AB4B. No dynamic clear
of695D4C was found; identified absolute writes are47A038 and47BD65. Its caller
schedule remains relevant when interpreting retained last-polygon callbacks.
## Registration and source layout
479140 walks shape polygon array begin+88/end+8C in48byte strides; it applies
checkpoint4794C0 and game-specific4797A0 filters before registration. Existing
[camera-ray evidence](camera-ray-predicate.md) establishes scene44DBF0's ascending
shape resource-index traversal. No new decorative/material rule is inferred here.
Game filter4797A0 calls the game's virtual134 at4797EC.
Each polygon's **all-corner** X/Z extrema determine registration cells using the
same conversion and inclusive X-outer/Z-inner order. Registration upper Z is a
conventional maximum, unlike query zmax. A28byte registration allocation stores
polygon0, shape4, centerXYZ8/C/10, W14 and radius18; bounds/candidate traversal do
not use this center/radius as a per-visit cull. Record is shared across its cells.
479800 rejects a duplicate polygon pointer within one cell (47985E..479866),
irrespective of shape pointer. New nodes append FIFO to all-grid5CFC7C
(47989F..4798A8), and wall-grid509B24 only when stored normal.Y<0.7
(4798B3..4798CF); equality is excluded. There is no query-wide deduplication.
477F10(out,shape,polygon,signed-short corner) reads polygon+24 corner records,
20bytes each. Their first DWORD is a vertex index into shape+68 Vec4 vertices,
16bytes each. It copies the selected Vec4 without transforming it. The wrapper
uses corners0/1/2 even though registration bounds use all corners.
## Evidence and implementation boundary
Owned REA CLI session used a generated copy, closed normally and retained complete
replies/export/snapshot in artifacts/collision-integration/grid/rea/:
| Procedure | Evidence ID |
|---|---|
|47B4B0|ev_f39128dafc2a3a20b5768613ce22b3c3168fe8653908837d92ad9a69ef5f2ad8|
|479140|ev_c6bffe721e0751327ecdb5e62c27137752574be6624c190a833c5b2c0f5be7b0|
|4797A0|ev_277ddc7e6b8383ea4245072e395a3dda51cd530c56fb160b917823803f55d33f|
dispatcher.instructions.txt retains the reachable retry instructions;
source-anchors.json records raw anchors, offsets, constants and four function-body
hashes. tests/test_collision_grid_traversal.py guards source bytes plus five
fixture groups: asymmetric bounds, clipped/inclusive order, per-cell duplicate
rules, mutable candidate and retained nearest/last-polygon across passes.
Minimal integration: build source-order wall cells; pass an explicit shared nearest
state into existing OriginalSphereResponse; scan frozen bounds with a mutable
candidate; retry revised displacement against unchanged previous root; then publish
and dispatch the last-polygon normal callback once. Reuse this dispatcher for
dynamic reclip without adding implicit state resets. A defensive port recursion
limit would be a documented implementation deviation, not recovered behavior.
Follow-up original dispatcher execution completed seven synthetic grid cases;
see collision-body-probe.md for outputs, fixture boundaries and managed comparison.
OriginalStaticCollision implements the bounded traversal as an isolated component;
it is not yet the live player solver. Geometry-disabled traversal preserves
terminal publication and retained callback; it skips primitive calls per visit.
TraceSupport initializes its strict nearest limit to quick_magnitude(end−start).
Prepared route geometry carries signed archive material IDs and rejects missing
identity metadata before special-contact coverage is assessed.
Unresolved: x87 cell
conversion at integer boundaries and extreme signed-short wrap; full scheduler
ownership of global collision toggles and retained dynamic last-polygon state.
The local projection does not establish numerical identity at those boundaries
or runtime correctness of the integrated port.
@@ -0,0 +1,64 @@
# C4 static dispatcher review
2026-10-26. Independent source review of the uncommitted static dispatcher,
its managed fixtures, saved REA replies and retained original-component output.
No original code was executed and no new REA session was opened by this review.
File ownership for this report only; primary owns integration and corrections.
## Findings and disposition
- **Corrected during review:** `TraceSupport` initially accepted its first
triangle hit without the source's initial nearest-distance limit. Retained
REA support reply `artifacts/collision-integration/rea-support/00.json`,
Evidence `ev_ad96a93792dcf00534130fbd428fb52fa25e2cf9c2492df43f89f425b80c3f08`,
initializes47C6E0's nearest distance to quick_magnitude(end−start), then
requires a strictly smaller hit magnitude. The kernel's parameter-distance
check is separate from the returned hit's magnitude. Primary added that
initial limit and strict comparison. This closes a source-contract omission;
no original numeric boundary probe is claimed.
- **Corrected during review:** old prepared meshes could omit material IDs and
appear ordinary-only. Primary added explicit material-identity completeness
metadata and a `FromRouteScene` rejection requiring newly prepared scenes.
Resolved null-material identity remains distinct from missing metadata.
- **Corrected after review:** `Move` now accepts the source geometry-enable state.
Source47B4B0 reads4F69E5 per node, while its final publication and retained
last-polygon callback can still occur when geometry is disabled. A caller
must not equate disabling geometry with skipping `Move` when it reuses a
context. The added regression checks publication and retained callback without
primitive visits. Dynamic shared-state/reset timing remains a live gate.
- **Live integration gate:** the dispatcher returns a candidate and terminal
polygon; it does not publish the logical actor transform or execute callback
370/374, support, friction or speed publication. Jimmy ordinary374 must retain
the special-material boundary. LV1B/LEV1 contain such materials; VR04's
absence of them is a bounded route-data result, not a general player policy.
- **Documented port limits:** iterative retry rejection after256 passes,
finite inputs, triangular polygons and approximate x87 cell conversion are
explicit boundaries. Do not promote this component to whole-body identity
or claim the source has a recursion cap.
## Verification
`source scripts/env.sh && dotnet run --project
tests/GamePort.StaticCollisionTests` passed seven groups during review. The
seven printed copied-original dispatcher cases in
`artifacts/collision-integration/dispatch/wine.log` match the managed fixtures'
positions, pass/visit counts and terminal polygon observations. The retained
marker is `DISPATCH_COMPONENT_COMPLETE`; the reviewer did not rerun that probe.
This verifies a bounded original component comparison, not live port gameplay.
Primary's subsequent focused run passes eleven groups, adding actual prepared
route material coverage, legacy metadata rejection, geometry-disabled retained
context, equal support ties and zero-length limits. Full integration passes122
Python checks plus HUD/managed/GPU/audio/hash checks; see progress.md for scope.
Registration sorting, X-outer/Z-inner traversal, per-cell duplicate visits,
frozen bounds including source MIN upper-Z, unchanged previous root across
retries, persistent nearest state and terminal-only callback selection agree
with collision-grid-traversal.md and its retained instruction/REA evidence.
Before enabling live body response, extend regression coverage to inherited
nearest/last-polygon state across separate dynamic reclip calls, equal-distance
support ties, and callback ownership/order after publication. Complete the
source contact policies and route/root checks identified by the implementation
ledger. After the stated review reset time, primary retried through normal
approval review and completed the ten-fixture isolated body probe. This closes
that execution blocker, but does not establish live whole-body equivalence.
+109
View File
@@ -0,0 +1,109 @@
# C4: original sphere/triangle response
2026-10-26. Original EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Preferred VAs are used below; EXE text file offsets are VA minus400000.
The helper independently maps PE sections and guards six complete function bodies.
## Recovered contract
479D20 integrates body motion, invokes static response47B4B0, then support47B890
and friction47A330. Static47B4B0 traverses the wall grid, invoking47BBB0 for each
candidate.47BBB0 fetches the first three source polygon vertices through477F10,
then invokes47BD80. Dynamic mode2's twelve box triangles also invoke47BD80
(dynamic-collision.md). Stored polygon normals and winding are independent inputs.
47BD80 takes five by-value four-float records (triangle A/B/C, stored normal,
previous root), a mutable current-root pointer, radius, and an edge-enable byte.
It uses shared nearest state:695D5C face distance,5CFBE0 edge distance,
5CFBE8..5CFBF4 hit point,695D74 lower-edge override. Callers initialize/retain this
state; component tests deliberately supply explicit initial values.
| Path / source range | Recovered transition |
|---|---|
|47BD86..47BE34|Compute normal×radius and endpoint=current−offset, retaining max(currentY,endpointY); build segment469530 from previous root to endpoint.|
|47BEBA..47BFAD|One-sided469B70 triangle ray. A strictly nearer hit updates695D5C and hit point. Root becomes hit+offset in X/Z; Y changes only for normal.Y<−0.7. A farther/equal face returns false without edge fallback.|
|47BFAE..47BFED|Only a failed face query may enter edges. Requires edge flag and strictly −0.7<normal.Y<0.7.|
|47C048..47C08C|4695B0 finds nearest point among the three edge segments, including endpoints. Without695D74, an edge below current root is rejected.|
|47C092..47C150|Normalize root-to-edge using quick_magnitude; require dot(direction,storedNormal)<0 and strictly nearer than5CFBE0 (−1 sentinel allowed).|
|47C194..47C1F8|Write edge point−direction×radius in X/Z, preserve root Y, update edge distance and hit point.|
469880 projects onto a segment using its quick_magnitude-normalized direction,
clamping to either endpoint.4695B0 compares edge distances with quick_magnitude;
ties prefer BC over AB, then CA over either.47B4B0 finally publishes the candidate
and dispatches normal callbacks370/374. The inspected function does not implement
the previously inferred generic recursive capsule slide. That older description
in original-collision.md is superseded by this bounded trace.
## REA evidence
Complete replies, exports and closed-session snapshots are in
artifacts/collision-response/rea-response/ and rea-kernels/.
| Procedure | Evidence ID |
|---|---|
|47BD80|ev_28147145c0fee39c39936e4180890f321711688d6617d1b8314a12bf45a2e565|
|479D20|ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0|
|47BBB0|ev_6e0dbae6267e87abbd0e4816b613923549b0f0787a26d7003d1a0e38fc733809|
|47B4B0|ev_d45e078c585d3773494c0e0dfb1696178dd0b8ce8b696caf133892ff070e552e|
|469530|ev_4fef4d32d2c8b30c306cd742fb9daeb93aa1fa36d4edf0ecaa87497e314dc50e|
|4695B0|ev_5e39f2668d04b1fdd2c91b298a28413327dc3879e6b8bbffe0a14bc1dcbc1128|
REA/Ghidra has incomplete C++ parameter/stack types here; apparent uninitialized
locals and missing arguments were resolved against instructions and the copied
component probe. The47B9F0 interior query resolved to47B890, not a new function.
Pseudocode is static evidence, separate from the execution below.
## Isolated original execution
collision_response_probe.c maps a copied EXE without its entry point/import
initialization, binds only quick_magnitude to copied OMT2.dll, disables debug
drawing, and executes47BD80 on synthetic geometry. Six callgraph bodies and all
selected absolute memory operands are guarded by collision_response.py. Because
the preferred base was occupied in Wine, only these explicit operands are
rebased in the generated in-memory copy. This fixture relocation is not recovered
source loader behavior. No on-disk original is patched.
The existing reference_capture.py namespace exposes generated copies only, with
no network and no Original mount. Final wine.log records ten cases and
COLLISION_COMPONENT_COMPLETE, exit0. An initial incomplete-prefix attempt failed
to load kernel32; a complete copied prefix fixed that. Two preferred-base attempts
failed before any source execution; guarded rebasing resolved that host issue.
Observed references: wall face/crossing roots(0,20,10), departing contact false,
edge root(107.071068,100,7.07106781), edge flag disabled false; lower-edge mode0
rejects while mode1 yields(105.77375,105,5.7737484); ceiling root(0,90,0).
These are isolated kernel results, not full original gameplay or native Windows.
Reproduction after preparing the isolated copied installation/prefix described in
docs/reference-testing.md (wait for copy completion before starting Wine):
```sh
python3 tools/binary/collision_response.py ../Original \
--target-copy artifacts/collision-response/original-probe/game/Neutron.exe \
--probe-header artifacts/collision-response/collision_response_relocations.h
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Iartifacts/collision-response \
-Wl,--image-base,0x14000000 tools/binary/collision_response_probe.c \
-o artifacts/collision-response/collision_response_probe.exe
python3 tools/recon/reference_capture.py --asset-probe \
--probe-executable artifacts/collision-response/collision_response_probe.exe \
--probe-success COLLISION_COMPONENT_COMPLETE --seconds 9 \
--output artifacts/collision-response/original-probe
```
## Implementation and remaining gate
OriginalSphereResponse.cs translates this bounded kernel, with explicit nearest
state and contact type. Five managed groups cover original numeric references,
winding, edge/lower-edge switches, ceiling Y, nearest/ties and finite input.
Zero-distance edge normalization is explicitly outside the bounded contract; the
port returns no contact instead of propagating the source's undefined arithmetic.
Modern arithmetic is not an x87 boundary oracle.
The live player and dynamic response still use the provisional capsule adapter.
Integration requires original grid bounds/order/duplicate visits, negative-Y
motion split, previous-root writes, normal/landing callbacks, support/friction
and dynamic reclipping. Replacing only a radius would not satisfy that gate.
The narrow lab doorway snapshot from control-phase-implementation.md remains
the first integrated response case. No claimed recovery of stairs or complete
body response follows from this kernel alone.
@@ -0,0 +1,82 @@
# C3 continuation: uncontrolled body and fire
Implementation2026-10-26. Source contracts: uncontrolled-player.md,
uncontrolled-physics.md and cutscene-preparation.md. This replaces the port's
whole-player freeze on control loss with a bounded phase split.
LabSimulation.Step consumes prior body state first. Input/controller math runs
only when Jimmy has effective control; fire ticks independently afterward.
The existing fresh/retained input ordering remains. Ordinary grounded radius60
is reasserted before the movement gate, matching the supported wrapper path.
Grounded fire can expire while mode/jump/hold remain untouched by the skipped
controller. Queued impulses survive camera preparation and are consumed once by
the following body pass. Neither control loss nor restoration invents a key flush.
PlayerSceneBinding connects raw-owner preparation events to speed/velocity and
supported gadget cleanup, and publishes the simulated root while uncontrolled.
Authored AI transforms update the body too, preventing a later physics publish
from overwriting the script's teleport. Authored current writes preserve the
facing destination. The later full-Euler bridge publishes all axes; CAM/MCA
preparation now replaces destinationXYZ with the upright current heading too.
See [rotation feedback](../gameplay/jimmy-rotation-handoff.md).
Initial MCA preparation occurs once, with its first-name guard; later
shots do not repeat it. AI and CAM use their own callback order. STOP notification
follows physical preparation. DEFAULT grants control without preparation.
Force Control is a modern effective-input override; raw ownership still selects
source preparations/music. Noclip keeps its separate flight path. F1/modal/inspect
boundaries stop the whole frame, so body/fire do not accrue paused time.
Contact-triggered interactions retain the existing control gate pending C4.
Counters now distinguish total Steps, PhysicsSteps, ControllerSteps and EffectSteps.
Total Steps also counts modern flight, which bypasses the physical/effect phases.
The console report exposes these counts; a cutscene's nonzero total count does
not mean Jimmy accepted input. `--smoke-carl-cutscene` asserts zero controlled
updates/jumps/turn/speed while physical/effect callbacks continue. The new
`--smoke-control-phases` seeds an airborne retained-fire fixture, holds movement
and jump through15 locked frames, checks falling/fire/energy without input, then
skips/restores control and verifies held-input movement resumes. This is a port
fixture, not an original end-to-end recording. Headless story pre-roll uses the
same binding/phase policy.
## Verification and limits
New managed tests cover queued impulse across preparation, uncontrolled fire and
tutorial immunity, independent grounded resets, CAM/MCA/AI order, body-before-STOP
observation, raw/effective ownership, later-shot behavior, held jump restoration
and authored teleport synchronization. Python adds9 source/projection tests.
The input-only lab replay now uses the same binding and waits through live
cutscenes with body/fire ticking. Its old coasting turn missed the narrow exit:
port snapshot root(318.11124,75.02122,770.8816), yaw47.52308, controlJIM1,
no shot/block and2290 wall hits. Braking with the actual Down input before large
heading changes restores the route (score150, owned jetpack, one practice No,
zero jumps,6 wall hits). No physics or task gate was changed to make that replay
pass. The provisional corner response remains a useful C4 investigation case.
Native Linux GTX1070 at1280x720 passes Carl/control-phase and F1/F3 tools/menu
checks with zero enabled Vulkan validation errors. Full integration/package
results are recorded in progress.md; native Windows remains separate.
REA6.8.0/Ghidra12.1.4 source Evidence is retained under
artifacts/uncontrolled-phases/rea/. IDs:
| Procedure | Evidence ID |
|---|---|
|475CA0 gameplay gate|ev_aa0b7db46894c10d2f28f76d0da1e568ef06253f3d6c8cf6b06fbef299602bab|
|479BC0 body traversal|ev_56b7e074ec8509d1c5b3576d02361ff051963b777d7ccb8259ed9c65dc2db52f|
|437940 movement gate|ev_de7097867d129a4232318e667e9496c6868cdb1da4b37a1f3304c94b0b101677|
|40E050 animated base|ev_03a109302788b85597e253293bbcb535c4080732e41cc828bb33d01d2b2da09a|
|462520 base body/rotation bridge|ev_f0a2e1fd465472295b272f2fdbfb6be4651aeb8c35d90dc2ca02a495ed359edd|
These are static decompiler observations with unknown C++ types, not original
source or runtime.421FB0 maps correctly from file21FB0 but lacks an analyzed
procedure in this Ghidra profile; its pseudocode is unavailable, not evidence
that the source callback is absent. Existing guarded bytes/vtable/body hash remain
the authority for that callback. Partial batches preserve successful Evidence.
Remaining: full424600 wrapper timers/UI/sound cleanup, base40E050/462520
resource/transform/morph policies, collision-triggered ceiling cancellation,
Bubble/mode0 radius160 and other gadget/class cases, original body registration and
response, complete registry and engine cadence, shared viewport handoff and
original whole-game comparison. Calling the entire controller with empty input
would not implement these missing phases. Existing capsule/yaw/camera adapters
remain explicit; this chunk does not certify a complete scene scheduler.
+166
View File
@@ -0,0 +1,166 @@
# Core architecture coverage map
2026-11-07 normal callbacks: [actor contacts](actor-normal-contacts.md) adds30
full emitted original/C# snapshots (S/P/M),13 interface/182 method bindings and5
pure scalar getter fields. Inherited ceiling/reflection/angular response is a
standalone component; Jimmy's ordinary374 override stays separate. Late scalar
reads are tested with explicit injected endpoint changes. Soldier174/Jimmy204
full policies, retained helper order and live scene binding remain open. No new
port-render/original-game/native Windows runtime coverage is claimed.
2026-11-07 populated follow-up: [dynamic reclip](dynamic-reclip.md) adds14 full
original/C# comparisons and12 kernel-step matches (S/P/M). Real synthetic static
walls/ceiling now exercise shared nearest, retries,370/374 order and primitive
mode. Kernel arithmetic corrections follow captured divergences and original
float-store boundaries; no numerical tolerance was added. Actual actor callbacks,
post-callback flag/radius ownership and retained helper order still gate live pairs.
2026-11-07: [dynamic/shared context](dynamic-context.md) adds17 complete original/
C# test-composition cases and12 captured kernel argument matches (S/P/M).
Hit/last-polygon retention, old static callback and final local-root publication
are recovered under empty-grid/non-reentrant fixtures. Original kernel A,C,B
arguments differ from construction topology; final position alone hid that error.
Jeep's default deletion predicate is guarded; full active cleanup remains open.
Live collision, nonempty shared reclip, real actor callbacks and retained helper
order remain gated. No new R/whole-original/native Windows coverage is claimed.
2026-11-06 TSK-entry correction: [menu/player lifetime](../gameplay/main-menu-player-lifetime.md)
establishes backgroundJimmy construction and reuse before the first playable
story scene. Input is now after Jimmy for that TSK path, while direct fresh-GAM
order remains. This replaces the named assumption that initial story equals fresh
registry insertion. First-neutral-tick/300-idle native Vulkan and eight managed
Carl trajectories pass; full-suite/platform results are tracked in progress.md.
50 more native derived-caller cases and body/transform ownership are documented.
Original startup diagnostics now reach background allocation after a recorded
repaint intervention, with black frames; no full-original visual/runtime parity
or native Windows execution is claimed.
2026-11-06: [Carl lifecycle trace](../gameplay/jimmy-cutscene-lifecycle.md) adds
292 bounded original-code cases and closes local contact/task/animation/STOP and
DEFAULT-provider questions. Actual first-resumed-frame state remains unobserved.
The new original-state observer passes Wine32 attach/read/leave-running; local
original captures show MAIN only and remain visually unusable. This expands S/P
and investigation-tool coverage, not original gameplay comparison or a new port fix.
MOVE/CONTROL/INPUT's Carl gate and full-body/OMT dependencies stay open.
2026-11-05 follow-up: camera-entry reset is verified, but post-skip neutral idle
remains a port bug. CONTROL/INPUT/skip coverage is reopened around Carl's full
lifecycle;48 port traces and additional original boundaries are documented in
[the focused decompilation checkpoint](../gameplay/jimmy-cutscene-decompilation.md).
No further gameplay change is made before its source-ownership gate is closed.
2026-11-05 handoff correction: CAM/MCA destination state at game+274 is now reset
along with current Euler (20 original-component cases; managed/native Linux
handoff checks). Neutral ground input separately retains residual bank in seven
original trajectories; whole-frame landing comparison remains open. See
[rotation handoffs](../gameplay/jimmy-rotation-handoff.md).
Checkpoint scope: lab → tutorial VR04 → lab → outside, including intro,
explanation, pickup/practice, RETURN, Carl conversation and exit. This compares
source contracts with the current port and preserved playable baseline69d0187,
not all gameplay in all levels. Rows marked “now” include the implementation
continuation; the original baseline remains a separate comparison point.
Address details/PE offsets and source-byte extractors are in the linked reports.
**S**=static/data recovery, **P**=isolated original component probe,
**M**=managed port regression, **R**=port runtime. No row has full original-game
runtime comparison. Coverage does not mean implementation completeness.
2026-11-05 movement continuation: [Jimmy stabilization](../gameplay/jimmy-movement-stabilization.md)
supersedes MOVE/JET arithmetic details below. Ground, air and control-independent
full-axis facing now have108 native component comparisons including the jump
suffix. COLL keeps its admission gate: real support polygon pressure is live in
the source body, while lab/outside retain capsule compatibility.27 special
contact dispatch and12 air-target observations expose remaining gates; they do
not certify special callbacks or the ordinary air-pitch visual bridge.
The following [air-target/render continuation](../gameplay/jimmy-air-bridge.md)
implements ordinary pitch/roll targets, dirty/Init and retained seed ownership,
full current Euler publication and source hierarchical model rotation.146 native
observations now compare with managed components. The model-local sole correction
is modern; exact final OMT render decomposition and broad collision remain open.
[Body contact ownership](body-contact-implementation.md) now closes the finite
current/previous XYZW barrier, independent body modes, context lifetime and landing
payload ordering.100 new complete original comparisons and six callback-state
comparisons pass. Special callback mechanics, actor mode persistence and scene-wide
dynamic/shared context remain separate gates; lab/outside capsule is preserved.
[Ordered pair lifecycle](pair-lifecycle.md) adds28 complete original/C# component
comparisons: physical-list pair order, one-sided sphere exclusions, gate retention,
callback-mutated roots/membership and enter/stay/leave. The component has explicit
mode2 injection and is not admitted to live scenes. VR04's6 inspected actor records
and20 bindings do not yet constitute the full physical/helper registration list.
[Physical registration](physical-registration.md) now inventories all72 VR04
records/13 actual interfaces and executes12 original registration/loader cases.
Common append versus Jimmy49E guard, nested Init and live per-object registry
traversal are verified.21 helper edges/12 RTTI identities are catalogued; actual
retained helper membership, deletion/activation and shared reclip remain open.
| ID / system | Recovered contract / anchors | Port implementation | Evidence / remaining gap | Next bounded action |
|---|---|---|---|---|
| LOOP | Viewport47E4F0 physics before registry473740, including input44DF80; second sync473770; construction order and selective retained-character/new-game ordering. Separate engine morph clock. | Player now integrates prior body state, then fresh input/player/fire or retained player/fire/input. Uncontrolled body/fire now continue while movement/input are gated. Other systems remain grouped; fixed60Hz policy. | S/M/R. Controlled player partial order implemented; bounded raw-owner preparation implemented; full wrapper/registry/cadence open. | C3 continue other callbacks and morph/control phases; C4 support/response remains separate. |
| INPUT | Game interface+8C slot3C4→44DF80→475A70 reads controlled5099E4 and calls3CC; Jimmy interface+C0→426030. | SDL arrows/jump aliases; control gate, modern debug override; mouse/controller incomplete. | S/M/R, user Windows route. Input occurs in object traversal after physics; device sampling/focus and latency open. | Trace event pump, key/mouse and focus gates alongside retained registry order. |
| MOVE |437940/439900 ground/air;479D20 impulse→acceleration→gravity; authored114→26C body speed separate from controller608. | Body/fire continue without control; input/controller gated. VR04 uses ordinary source static body and variable radius; lab/outside capsule retained. Fresh/retained order and overhead wrapper explicit. | S/P/M/R. Source body references/phase checks and native VR04 flight pass; complete registry/base/transform/cadence open. | Continue dynamic/special C4 contracts and C3 base transforms; preserve published speed ownership across preparation/Init. |
| JET |437F90 controller;421FB0 effect; fresh constructor order places fire after Jimmy, both after global physics. States0..5, hold>.4,8s, energy. | Explicit state table with post-collision effect ticking and VR immunity. | S/M/R. Fresh same-pass countdown recovered; retained child lifecycle, sound and expiry→animation open. | Trace retained Jimmy/fire resets and phase end events before scheduler integration. |
| COLL |479D20/47BD80 body;47B4B0 FIFO grid/retries;370/374/37C; signed materials/friction; radius60/100;47A430 ordered pairs/47CA90 one-sided sphere exclusions. | VR04 uses ordinary source static body; lab/outside keep24-unit capsule.28-case pair component remains separate; live dynamic response provisional. | S/P/M/R. Prior kernel/dispatcher/body comparisons and native VR04 pass;28 complete pair observations now match. Real actor callbacks, full physical list and shared reclip remain open. | C4: complete VR04 physical registration/activation/helpers, then shared dynamic context; lab/outside need160/164/FENCE/LADDER before solver expansion. |
| ANIM | Engine morph10002DB0; linear interpolation10002F9A; game logical→OMT sync4624B0. | ASE sample timing, unconditional loop closure, pose/action aliases,1/60 advance. | S/P/M/R. Playback flags, rate, completion callbacks, transition order open. | Recover one-shot/loop/end notifications before more aliases. |
| SCRIPT | Source AI/CAM/MCA dispatch and chains; task45F990 objective406F50 BEFORE records BEFORE per-entity424. | Pre-assignment objective selection and per-actor Carl override implemented; bounded synchronous director. | S/M/R. Script callbacks recovered for route; generic class coverage and reentrancy incomplete. | Continue other class-specific callbacks and reentrancy under the recovered owner/phase boundaries. |
| CONTROL | Global5099E4 null during valid CAM/MCA; PlayerControlled completion target; DEFAULT447D..447F restores camera/UI/music. | Director raw ownership plus explicit debug effective override; eligible player body/fire continue; only input/controller tail is gated. | S/M/R. Raw/effective control and ordered preparation are implemented; full base/class wrappers and scheduler remain incomplete. | Continue full wrapper/base and collision contact phases around deferred LOAD. |
| CAMERA | Shared viewport eye is recaptured by ground/air follow after scripts; strict>1000 DEFAULT snap; aim uses pre-update eye; source ray/gain and per-level far planes. | Static source query integrated for the three route scenes; other scenes use provisional sweep. Separate chase/script eyes and merged clip maximum remain. | S/M/R. Handoff source bytes/projections recovered, not implemented; full follow/input/quantization and visual comparison open. | C5 shared viewport eye/aim and DEFAULT transition; preserve source phase boundary. |
| AUDIO | CAM416776..E1 stops music; DEFAULT447F12..45 restarts; bank696008 / gate4F8434; handle47D890 polls inherited software duration and repeat+30. | Separate SDL streams, floating-file-duration cutscene completion, independent per-file SFX. | S/M/R (dummy streams). Source duration/allocation/play-failure/bank/attenuation lifecycle incomplete; speakers/native Windows timing not verified. | C6: explicit bank owner and software channel-clock tests; SDL queue-empty is not the source oracle. |
| UI |406F50 selector/timer;4043D9 controlled clock;407070/O edge;404D97 practice resume.44 objective flags distinct from selector. | Timed objective subset, modal practice, modern UiViewport/debug. | S/M/R. Other flags/gadgets/highlights/cursor/energy/layout transitions open; source widescreen not recovered. | Keep modern scale policy separate; recover UI dispatcher/mode gates before expanding. |
| LOAD | Deferred request/selective reuse; Init stored+11→live+139; retained Jimmy/Goddard.49E clears; registration repeats Init before STRT. Per-object28→40C and same-pass appends; RETURN root/flags. | Reconstructed scene with retained input order and bounded state; app-owned presentation. | S/P/M/R.12 original registration/loader cases now pass; all72 serialized VR04 records mapped. Helper lifetime/activation and full ordering still open;50988A is editor R input. | Close helper reuse/removal and physical sequence alongside C4; other gadget/level branches remain gated. |
| INVENTORY | PostLoad common prefix enables eight owned gadgets4→1, then VR01..08 disables1→4; full tail re-enables the practice gadget. LV1B disables1/7; other wire values preserved. | Availability pass now applied at level entry and verified across TSK tutorial/return; snapshots preserve raw values. | S/M/R. Full selected-gadget/UI and other level tails remain incomplete; bounded route mode/hold/fire carry is implemented. | Keep availability separate from ownership, task changes and arbitrary state carry. |
| SAVE | TSK45FEE0 writer /4603F0 reader; records, arrays, return strings, stored departure root; queued460E70→460EA0. | Original-format round-trip and CLI save, scene snapshots; no full source save UI/load lifecycle. | S/M. Source reader duplicates matching task callback then all-entity420 post-task hook; this is distinct from Jimmy placement PostLoad423A90. Current fresh-director path differs. | C7 after C1/C2; test repeated callbacks before adopting loader behavior. |
| CHECKPOINT | Pickup42AF00 stores+1E38 root/+1E48 level separately from+9A8 RETURN root. | Capture exposed, not used for return; source capture consumers unknown. | S/M. Do not interpret as death/respawn until read consumer found. | Track unresolved consumer; no speculative gameplay. |
| SCOOTER |4211A0/412A90 owned vehicle/4 children;465220/465830 drive/input;467080 post-normal wheel support;421910 impact;4130A0 camera;4281B3 cleanup. | Now live VR05 and outsideLEV1, normal tile plus F1. Body→input/frame→rider-copy→wheel phases, exact unscaled resources, source camera/audio and RETURN. | S/P/M/R:53 isolated original observations, actual-level managed tests,10-phase native/headless replays. No complete original-game comparison. | Whole-original/native Windows comparison; shared global/pair state, retained LOAD/helper/save lifecycle and other levels remain bounded. See gameplay/scooter-live.md. |
## Interaction and ownership map
| State / owner | Changes when / consumers | Persists or resets |
|---|---|---|
| Task records4FC5FC, name+0/state+64 |45F990 objective hook → record mutation → matching actor424; queries gate triggers/LOAD/NPC | TSK serialized; carried snapshots in port. Same-value assignments still dispatch. |
| Current controlled entity5099E4 | Input dispatch, Jimmy behavior, UI clock, script/camera handoff | Runtime ownership; not interchangeable with task state or whole-world pause. Port F1 override is separate modern state. |
| Scene actor game interface, body, OMT morph | Physics prior body state → registry update → logical/visual sync; animation on engine path | Level-owned construction/destruction; exact spawned effects order not yet recovered. |
| Objective selector4F8194 / transient timing and flags | Task hook406F50, O and practice modal; UI dispatcher reads control | Selector serialized; timer starts hidden20 and is runtime-only. Port implements one selected objective rather than full flags. |
| Departed root complete+9A8 | Ordinary43B5A0 captures; RETURN preserves; PostLoad consumes pending flag | TSK StoredVector persists; pending+954/+9A5 not serialized. STRT yaw remains authored. |
| Return level/start strings | Practice choice records origin; RETURN LOAD selects them | TSK persists strings independently of root and pickup capture. |
| Pickup checkpoint complete+1E38/+1E48 | Pickup callback42AF00 writes; read consumer not proven | Do not equate with departure root or invent reset/respawn semantics. |
| Music/effects/cutscene voice | CAM takes bank/voice and stops music; DEFAULT restores source defaults | Runtime bank/handle lifetime, not task ownership; current port independently opens WAVs. |
| Viewport/camera target | CAM/MCA target/eye; DEFAULT snap and follow; clip/layer resource settings | Original camera handoff is shared viewport state; baseline chase and scripted cameras diverge. |
| Jimmy mode/hold/owned-fire timer | Constructor, controller/fire ticks; property/Init/PostLoad/cleanup boundaries traced for supported route states | Ordinary route container retains these scalars; jump/body reset independently. TSK/debug checkpoint load carries none. First grounded tick can clear retained mode/timer. |
| Modern application presentation and debug | RenderSession keeps window/GPU; debug visibility across loads | User-authorized session policy, outside original TSK or gameplay claims. Scene audio/gameplay disposed/recreated. |
## Assumptions and symptom-level adapters to replace
1. Fixed60Hz remains a deterministic port policy. Baseline controller-before-
physics has now been replaced for the controlled player; other grouped scene
callbacks and morph timing remain incomplete. Preserve arithmetic tests but
do not treat existing travel measurements as the source oracle.
2. Floor snap/visual sole correction and24-unit swept capsule solve visible
penetration/navigation symptoms. They do not recover Jimmy's body/root geometry
or47BD80 response. Keep rendering pivot and physics support investigations separate.
3. Carl activation is applied after a generic actor batch in the baseline;
source virtual callbacks execute per actor in registry order. C2 replaces this
adapter without inventing full NPC sensing.
4. Route static sphere clipping is now replaced by source grids/kernel. Chase
state and DEFAULT's simple camera reset still mask ownership gaps. Per-level
far limits are recovered; merged-layer maximum is a rendering policy pending
masks/fog, not complete clipping recovery.
5. File duration is a cutscene completion estimate. The source also uses software
duration, but integer elapsed boundaries, repeat, invalid/stopped channels,
clock pause and effects-bank ownership remain lifecycle inputs. SDL queue-empty
is not a better source oracle. Dummy playback does not verify original timing
or physical speaker output. See `voice-clock.md` for the resolved vtable evidence.
6. Current RETURN root, MCA control target, NC exclusion, air-turn clear and
objective timeout have direct evidence. Retain those rules, but revalidate their
phase/owner when the surrounding scheduler changes; don't discard them as guesses.
## Limits and unresolved gates
Route coverage is stronger than later levels, but still lacks original end-to-end
runtime comparison. No feature-expansion work is justified by this map alone.
The source's UI/task/return state boundaries are sufficient for C1/C2 now. Scheduler,
physics, camera, audio and loader chunks each require their specified probe before
changing behavior. See the linked reports for exact offsets and additional questions.
+47
View File
@@ -0,0 +1,47 @@
# Cutscene preparation and control handoff
2026-10-26, static EXE evidence. SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
VAs below use400000 preferred base; raw offset=VA−400000 at these sites.
cutscene_preparation.py records exact bytes/virtual targets; its projection is
interpretation, not source execution. Primary completed the investigator's helper,
corrected its sign-extended byte−1 comparison anchor and added tests/report.
| Boundary | Proven order and source sites |
|---|---|
|CAM with PlayerControlled=NULL|Guard prior raw owner416635;43841665D→41041666B→flatten current/destination Euler(0,currentYaw,0)41667E..4166E5→game118(NULL)4166F4. Target lookup occurs later416754. Preparation can precede a missing target/sound failure.|
|Initial MCA activation|First target name `none` guard431300 exits before preparation. A non-none name reaches initial target/animation prelude; missing lookup can continue. Prior owner guard431502;410431512→flatten current/destination Euler431525..43158D→438431598→game118(NULL)4315A7. Per-shot helper invoked431600.|
|Later MCA shot|CompleteE0→431750; target/sound/animation work, no410/438 or raw control clear. The sound−1 check431771 sign-extends one immediate byte, not a four-byte immediate.|
|AI PlayerControlled=NULL|Prior raw owner guard40C4AD→41040C4B9→game118(NULL)40C527; no438 or flatten. Named AI ownership remains an older port interpretation requiring broader proof.|
|DEFAULT|447D5C checks whether Jimmy already owns raw control;447E27 restores via118 without410/438. No new key-release boundary is implemented. Music uses authored ownership independently of debug force.|
Jimmy410→42AFC0 calls43A750 first: clear speed608 and velocity XYZ2C4; stop
saved sound148; then request complete150(`STOP`) at42AFDE/E5. Body changes precede
the STOP animation notification. Mode, jump, hold, pending impulse, acceleration
and fire timer are separate. Existing isolated43A750 probe validates its limited
write set with invalid sound handle; it does not execute full camera activation.
Jimmy438→42AE00 invokes selected-gadget cleanup178→427FF0 and sets interface1D65
and global4F8182. Supported no-selection/jetpack cleanup clears selection; other
gadget cases are not blanket resets (retained-return-cleanup.md). The port exposes
these ordered boundaries, implements supported player motion/selection and logical
orientation changes, and leaves other class/UI/resource side effects explicit.
Authored AI movement has separate setters: marker root310 at40C732→target314
at40C757; yaw40C88F..40C961 uses174→4716D0, writes authored/live Euler and cached
Euler, and does not write movement destination yaw61C. PlayerSceneBinding applies
root/yaw to the simulation without erasing pending motion or destination yaw.
Only actual transform writes emit that event; animation-only changes do not.
The port's skip fast-forward, malformed/reentrant activations, MCA's initial
animation prelude, all other class virtual effects and full shared camera state
are not certified by this chunk. Existing named control behavior is preserved,
not newly recovered here. Three byte/projection tests and coupled managed
director/body tests guard the implemented ordering and boundaries.
2026-11-05 correction: game+274 is the facing destination, not an independent
render cache. CAM/MCA copy `(0,currentYaw,0,currentW)` into both current and
destination vectors without touching dirty. See
[exact rotation handoff](../gameplay/jimmy-cutscene-rotation-source.md) for20
isolated original-code cases and the recovered fix. STOP alone, AI NULL and
DEFAULT retain their existing separate policies.
+156
View File
@@ -0,0 +1,156 @@
# Dynamic box response and shared static context
2026-11-07. Continues [pair lifecycle](pair-lifecycle.md) and
[physical registration](physical-registration.md). This checkpoint executes the
complete original mode2 box query and composes existing C# source kernels in a
**test fixture**, without admitting dynamic pairs to live gameplay.
## Evidence and scope
Canonical Neutron.exe SHA-256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
REA instruction Evidence:
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`.
New REA/Ghidra mode2 pseudocode:
`ev_76827fca086933b7c48a9036a5a4a0a0f86d714935de6373eca4a3530fd231c5`.
Jeep PostLoad4217D0:
`ev_72e727e980c8ad114b46c1f23905088233e2925ff8bf8a9420d3b81bddccda27`.
The request for teardown46DFF0 remains an unrecognized-procedure error; no full
cleanup decompilation or execution is claimed. Complete replies, export and
closed-session snapshot are local under `artifacts/dynamic-context/rea/`.
`tools/binary/dynamic_context.py` guards11 copied bodies and102 relocated
operands, including the complete47A5E0..47B3DC query/switch-table span
(file7A5E0, lengthDFC, SHA-256
`9bb2c187d12f73a73f4ac2f31e19072d9010f919ce93fb6884e2be35b2fac894`).
It uses the prior dispatcher/kernel mapper and a copied original OMT2.dll.
Actor getters, contact callbacks, root setter and box point transform are
synthetic. The source static grid is empty, with a deliberately seeded old
polygon. This is original component execution under isolated Wine32, not an
original scene, live Jimmy callback or native Windows observation.
## Recovered call order and ownership
Text file offsets below equal VA−400000; the tools verify actual PE mapping.
The box query is reached from ordered pair47A430. Its other actor geometry gate,
source radius broadphase and other-mode2 shortcut precede triangle processing.
Those early paths preserve the seeded nearest/hit/last-polygon context.
| Original VA / file offset | Recovered operation |
|---|---|
|47AB3F / 7AB3F|Write sphere radius to edge limit5CFBE0.|
|47AB4B / 7AB4B|Set nearest face695D5C to−1. Do not clear hit5CFBE8 or last polygon695D4C.|
|47B277 / 7B277|Call47BD80 for each of12 transformed box triangles, updating the shared nearest state and local candidate.|
|47B29B / 7B29B|Each accepted kernel result invokes sphere virtual374 with a **null polygon**. This is not a normal-Y choice between370/374.|
|47B2EF / 7B2EF|Read box virtual1E0 after triangle callbacks. If inhibited, return contact without world reclip or sphere root setter.|
|47B364 / 7B364|Call47B4B0 from source previous root with candidate−previous displacement; edge checking is disabled. Reuse current hit/nearest/last state.|
|47B399 / 7B399|Publish the clipped local candidate through sphere314 after the static callback; there is no live-root comparison before publication.|
After all triangles, face−1 and edge>=radius means no contact. An accepted
query resets the nearest limits even when it misses, while old hit and last
polygon survive. The chained fixture verifies this across two successive calls.
Its callback/setter/pass counters are cumulative, not reset for the second call.
With an empty grid,47B4B0 can still issue its terminal callback for the seeded
old polygon, including when static geometry4F69E5 is disabled. An uninhibited
dynamic hit therefore gives a null-polygon dynamic callback followed by an
old-polygon static callback. A callback's live-root mutation is overwritten by
the final local candidate; inhibition leaves that mutation intact, including W2.
Do not replace this with a root-changed suppression rule.
The global primitive mode695D74 is a separate owner.47B6F4 sets it to1 around
an individual static primitive when sphere42C is set, then47B742 clears it.
Our empty-grid fixture starts and ends with mode0, including42C=true. That case
does not establish general mode reset, recursive queries or arbitrary callback
mutations. Parent static-body479D20 normally initializes its own query state;
the later dynamic phase can see another body's last polygon. Explicit seeding
tests state retention, not which real actor supplied it in a complete frame.
## Kernel winding: a meaningful failed comparison
The first C# composition used `DynamicSceneCollision.Triangles` construction
order directly. Its first fixture reached the same root(0,0,20,1), but reported
face−1/edge5 instead of original face40/edge10. The passing interpretation uses
kernel arguments **A,C,B**, with the normal retained from construction A,B,C.
To test that interpretation, the generated private mapped kernel entry is
instrumented to record its first12 triangle/normal arguments. The hook restores
the original five bytes before invoking the actual source kernel and reinstalls
it afterward. All12 complete arguments match the C# fixture; each captured
cross(B−A,C−A) points opposite its supplied normal. The original files and copied
on-disk EXE are not patched. This validates the kernel boundary, not a blanket
change to construction topology or the provisional live collision adapter.
The intentionally wrong construction-winding run remains a failing diagnostic
(`--construction-winding`), with its first divergence and nonzero exit saved in
`artifacts/dynamic-context/construction-winding-failure.json`. Matching final
positions alone would have missed the shared-state error.
## Implemented comparison and verification
`tests/GamePort.DynamicContextTests` composes the existing source sphere and
static kernels with this bounded control flow. No production solver or gameplay
actor is added. Fixed references run without generated artifacts; `--native`
also compares every emitted field and all12 captured kernel arguments.
The17 observations cover old/null polygon, inhibition, geometry-off and
broadphase rejection, other-box overlap/rejection, triangle miss, root-mutating
callbacks with/without inhibition, static-geometry-off,42C force-static flag,
Y45 face contact, translated/90-degree box and a two-call hit→away sequence.
Each compares contact, XYZW, nearest face/edge/hit, retained polygon identity,
dynamic/static callback counts, setter count, static passes and global mode.
The Y45 case is not proof of a successful geometric edge/corner response.
Verification: all17 full native/C# observations and12 kernel arguments match;
fixed references pass;345 Python tests,11 static-dispatcher groups,10 dynamic-box
groups and28 pair lifecycle cases pass. All539 original files remain unchanged.
Both packaged DLLs and BUILD-INFO remain identical to the924ad2f baseline.
No new GPU, audible, whole-original or native Windows comparison is claimed.
Reproduction from GamePort (probe execution uses a separate copied game):
```sh
python3 tools/binary/dynamic_context.py ../Original --output artifacts/dynamic-context/native
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wno-unused-function -o artifacts/dynamic-context/native/probe.exe artifacts/dynamic-context/native/dynamic_context_probe.c
python3 tools/recon/reference_capture.py --asset-probe --probe-executable artifacts/dynamic-context/native/probe.exe --probe-success DYNAMIC_CONTEXT_COMPLETE --seconds 12 --output artifacts/dynamic-context/probe
python3 tools/binary/dynamic_context.py ../Original --output artifacts/dynamic-context/native --capture artifacts/dynamic-context/probe
source scripts/env.sh
dotnet run --project tests/GamePort.DynamicContextTests -- --native artifacts/dynamic-context/native/observations.json
```
## Helper teardown follow-up
`tools/binary/helper_teardown.py` guards13 sites and5 Jeep bindings at table
4A2AEC (fileA2AEC). Constructor42129A (file2129A) pushes1, and4212A8 calls
470F40: authored predicate+11 is stored and dispatched through204 to live+139.
Generic Init4705B3/4705BC restores the authored predicate through8C→204.
Table slots8C/200/204 target470F30/4719B0/4719C0. Default Jeep is therefore
eligible for ordinary deletion, unlike the retained Jimmy default; pointer
clearing in Jimmy PostLoad is not itself evidence of a retained old Jeep.
Teardown re-reads200 at46E032,46E06F and46E0AC (files6E032/6E06F/6E0AC),
with virtual20/34 cleanup between reads, then marks+6 at46E0CA before the
473710 sweep. Jeep20 targets4213E0→462390;34 targets458C50, whose game+4B0
condition can invoke430. Callback/active-vehicle mutations can affect those
re-reads. This closes the **default eligibility** question, not complete active
cleanup, child deletion, sweep execution or final retained registry order.
## Remaining admission gates and next chunk
Follow-up: [populated reclip](dynamic-reclip.md) now executes real synthetic static
walls/ceiling and matches14 full observations/12 kernel steps after directly
evidenced rounding corrections. The first gate below is closed for that bounded
composition; real actors, ordered-body provenance and reentrancy remain separate.
1. Exercise static geometry after a dynamic hit, rather than only empty-grid
reclip. Compare shared nearest/last ownership across two real primitive
candidates and ordered bodies, including face/edge ties and flag transitions.
2. Trace actual Jimmy/door/VR04 actor callbacks and their root, mode, activation
and polygon requirements. Synthetic callbacks do not establish these owners.
3. Finish constructor-only helper re-entry/deletion and physical order across
ordinary LOAD/RETURN, including cleanup mutations between the three reads.
Then implement a bounded shared-context response component and integrate only
the evidenced VR04 actor set. Keep lab/outside capsule and current playable
movement while these gates remain. Preserve ordinary landing bank; this report
adds no rotation reset and does not reopen the completed TSK-entry order fix.
+153
View File
@@ -0,0 +1,153 @@
# Populated dynamic reclip and recovered rounding boundaries
2026-11-07. Continues [dynamic context](dynamic-context.md). The complete original
box query now runs against a populated synthetic static grid. Fourteen full
observations and12 diagnostic kernel steps match the C# composition exactly as
parsed float32 values. This checkpoint corrects directly evidenced shared math;
it does not admit dynamic pairs or new actors to live gameplay.
## Evidence and runtime boundary
Canonical EXE SHA-256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
The generator reuses the prior11 guarded bodies/102 relocations, including
47A5E0,47B4B0,47BBB0,47BD80,469880 and469B70. Body hashes, PE offsets and copied
OMT2.dll identity are retained in `artifacts/dynamic-reclip/native/source.json`.
REA evidence is reused, not regenerated for an unchanged question:
| Evidence | Source |
|---|---|
|`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`|Complete original instruction listing; decisive float stores/call order.|
|`ev_76827fca086933b7c48a9036a5a4a0a0f86d714935de6373eca4a3530fd231c5`|47A5E0 mode2 pseudocode, retained under dynamic-context/rea.|
|`ev_f39128dafc2a3a20b5768613ce22b3c3168fe8653908837d92ad9a69ef5f2ad8`|47B4B0 static traversal/retry; see collision-grid-traversal.md.|
|`ev_5e39f2668d04b1fdd2c91b298a28413327dc3879e6b8bbffe0a14bc1dcbc1128`|4695B0 nearest-edge pseudocode; assembly resolves intermediate stores.|
`tools/binary/dynamic_reclip.py` generates a bounded harness containing copies of
the existing probe sources without their mains. The new executable calls copied
source bodies with synthetic box/sphere getters, point transforms, callbacks and
grid nodes. It never invokes the original entry point. An instrumented private
mapped47BD80 counts primitive mode and captures12 steps only for the skew case;
the hook restores original entry bytes for each real kernel invocation. Original
files and on-disk copied EXE remain unpatched. This is Wine32 component execution,
not full original gameplay, live actor callbacks or native Windows verification.
Final execution is under `artifacts/dynamic-reclip/probe-verified/`, with no
network or Original-directory mount. An earlier overlapping prefix preparation
produced no observations; a separate completed prefix then exceeded the12-second
startup bound while still running. The45-second bound completed successfully.
Incomplete attempts and intermediate comparisons are preserved separately and
are not counted as source observations. One initial ceiling triangle missed the
intended path; the final fixture covers it and proves a real370 callback.
## Shared state through populated static geometry
The box is identity-oriented with cube(−50,−50,−10)..(50,50,10), radius40;
sphere radius10, previous(0,0,50), current(0,0,15). The dynamic face query normally
gives rootZ20, face40, edge10 and hitZ10. A separate old polygon99 is seeded.
| Fixture | Original result / dependency |
|---|---|
|Static wallZ35|Nearer static face wins: rootZ45, face15, hitZ35, last0;2 passes/4 cell-list visits.|
|WallZ10 at equal dynamic face|No replacement: rootZ20, face40, old polygon99 survives.|
|Far wallZ0|No replacement; old polygon99 still supplies the terminal callback.|
|Walls35→30 and30→35|Both end atZ45/face15; winning polygon is0 or1 according to its identity.2 passes/8 visits.|
|Root-mutating callbacks|Final local root still overwrites the mutation, now toZ45.|
|Box response inhibited|Only dynamic callback; no static visits, passes or setter.|
|Static geometry disabled|2 node visits, no static kernel calls; retained old-polygon callback still occurs.|
|Sphere42C enabled|12 dynamic kernel calls in mode0,4 static kernel calls in mode1, terminal callbacks/setter in mode0.|
|Old ceiling polygon|No accepted static face, but retained normal−Y invokes370 rather than374.|
|Real ceilingY35|Root(0,25,23.7499962), face43.7501259, last1;370 follows dynamic374, then314;2 passes/12 visits.|
|Repeated query without context reset|Nearest limits reset per dynamic query; last polygon and all callback/pass/visit/kernel counters persist across calls.|
The real ceiling fixture starts currentY30 and uses a triangle covering positiveZ.
The skew fixture instead starts previousY−30/currentY0 and registers the original
wall/ceiling triangles without claiming that the ceiling accepts. Its dynamic
edge→face sequence is the numerical diagnostic below.
The callback event string records virtual slot, polygon identity and global mode.
Dynamic callbacks use374/null. Static callback370/374 selects from the **retained
last polygon's normal**, and final314 follows callbacks. Every observation compares
contact, rootXYZW, face/edge/hitXYZW, last identity, callback/setter/pass/visit counts,
global mode, mode0/1 kernel counts and complete event order. Sequential queries use
the same synthetic actor; they do not prove registry order across real actors.
## First divergences and supported corrections
Text offsets are VA−400000; the source tools check actual PE mapping.
1. **Visited nodes and primitive tests have different owners.** At47B6A8..47B6B9
(file7B6A8),695D70 increments before4F69E5 is checked. The first managed
comparison reported0 visits versus original2 with geometry disabled.
`StaticCollisionContext.NodeVisits` now counts before that gate, while
`TriangleTests` continues counting only dispatched primitives. This is a
diagnostic-state correction, not a new collision response.
2. **Segment projection X retains its product.** The skew case's first differing
kernel is zero-based6: input(0,0,15,1) matches, but source hitX is
`8.68490133e-7` and managed hitX was0.4699A0..4699DE (file699A0) retains
directionX×projection until adding originX; Y/Z products have intermediate
float stores. `OriginalSphereResponse.NearestOnSegment` now follows those
separate boundaries.47C194..47C1D0 likewise retains X/Z products through the
final edge-root subtraction. This makes the complete step6 output match.
3. **Ray normalization and hit publication retain intermediates.** The next
mismatch is step7's face hit.469BE5..469C09 (file69BE5) uses OMT's returned
quick-magnitude quotient directly for reciprocal normalization; a float return
inserted an extra rounding.469DF0..469E13 (file69DF0) stores hit coordinates
after multiply+add. `OriginalBodySupport` now retains the magnitude intermediate
as double for these ray callers, and delays coordinate rounding until that
final store. Its public float QuickMagnitude result and caller-owned nearest
reduction remain float. All14 final observations and12 kernel steps now match.
Intermediate failure logs and experiment snapshots remain local, including
`managed-initial.log`, `managed-after-visits.log`, `projection-experiment.log`,
`ray-experiment.log` and `wide-experiment.log`. No epsilon or near-zero clamp was
added. The comparator parses native9-digit and managed shortest decimal spellings
back to float32; distinct values remain failures. Double intermediates reproduce
these fixtures, not every x87 extended-precision or table-boundary case.
## Implementation and validation
Runtime changes are confined to the shared support/ray and sphere kernels plus
the additional static visit counter. `tests/GamePort.DynamicReclipTests` keeps
fixed numeric references and all12 kernel steps for artifact-free normal runs;
`--native` checks the complete generated observation file, and `--dump` supports
future differential tracing. Python tests guard instruction boundaries, safe
generation and exact-float comparison semantics. Both probe source and expected
data are test fixtures, not new actor implementations.
`scripts/test.sh` exits0 with348 Python+2 HUD Python checks, all managed projects,
36 Vulkan/render checks with zero validation errors, audio lifecycle and539
original hashes. Debug build has zero warnings/errors. Native Linux SDL Carl
control (first neutral input/300 idle ticks) and VR04 jetpack steering/resize
also pass with zero validation errors. Windows x64 self-contained cross-publish
succeeds to a separate artifact directory. Existing packaged DLLs and BUILD-INFO
remain identical to924ad2f; no new package or Windows execution is claimed.
Reproduction after **waiting for disposable prefix preparation to complete**:
```sh
python3 tools/binary/dynamic_reclip.py ../Original --output artifacts/dynamic-reclip/native
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wno-unused-function -o artifacts/dynamic-reclip/native/probe.exe artifacts/dynamic-reclip/native/dynamic_reclip_probe.c
python3 tools/recon/reference_capture.py --asset-probe --probe-executable artifacts/dynamic-reclip/native/probe.exe --probe-success DYNAMIC_RECLIP_COMPLETE --seconds 45 --output artifacts/dynamic-reclip/probe-verified
python3 tools/binary/dynamic_reclip.py ../Original --output artifacts/dynamic-reclip/native --capture artifacts/dynamic-reclip/probe-verified
source scripts/env.sh
dotnet run --project tests/GamePort.DynamicReclipTests -- --native artifacts/dynamic-reclip/native/observations.json
```
For a complete field/step difference report, run `--dump` to a local file, then
pass that file as `dynamic_reclip.py --managed <file>` with the same output path.
The generated comparison explicitly records every mismatch; it does not turn
nearby values into parity. Final platform/suite receipts are in progress.md and
compatibility.md; local identities/results are in artifacts/dynamic-reclip/.
## Remaining gate and next chunk
Populated-grid composition now supports a bounded shared-context response. Before
live admission, recover actual Jimmy/VR04 actor callback mutations, live flag/
radius reads after callbacks, constructor-only helper re-entry/cleanup and real
physical registration order across LOAD/RETURN. Reentrant global-mode and grid
mutation, extreme coordinates/degenerate inputs and general x87 boundary behavior
remain open. Preserve lab/outside capsule and the existing VR04 static-only actor
set. Next focus on real actor callback ownership, then implement the bounded
response adapter against those interfaces. No movement tuning, angle reset,
gadget feature or unsupported dynamic actor is introduced here.
+195
View File
@@ -0,0 +1,195 @@
# Evidence-based continuation
Checkpoint exit is architecture coverage, not full-game completion. Preserve
baseline69d0187 and original hashes, finish reports/byte checks, then execute these
chunks in dependency order. Each chunk gets its own evidence, regression result
and local milestone; a failed gate triggers further bounded investigation rather
than invented behavior or new levels/features.
| Chunk | Concrete change / evidence gate | Verification and completion condition |
|---|---|---|
| C1 |45F990: notify objectives before changing task records; then dispatch actors. Expose explicit pre-assignment boundary. | Byte assertions45FB5B/7F/D9; observers see old task during objective selection and new task during actor notification; repeat/missing tasks still broadcast. Run Data/Interaction/Director/route regressions. |
| C2 | Preserve per-actor virtual task override boundary. Generic activation then Carl override413F30 before advancing to next actor, rather than applying all Carl overrides after all actors. | Confirm base/derived call bytes; check actor notification sees final per-actor state and authored marker; regression task50→60 conversation/control and lab route. Do not add other class overrides without evidence. |
| C3 | Build original registry/construction/input/frame phase oracle for lab. Split pending motion/controller/effect phases only when registration order and engine callback bridge are recovered. | Assert physics before normal object update, next-node timing, transform sync after callbacks. Compare input→impulse→next-physics→ground/pose trace; test pause/control loss/return. Keep cadence as unresolved policy until engine timer evidence. |
| C4 | Recover47BD80 and Jimmy root/body fields. Replace provisional capsule/feet and wall response behind bounded source adapter. Depends on C3 phase semantics. | Isolated original collision probes plus deterministic wall/step/ceiling/floor/dynamic-body cases; no invisible NC terrain; lab/tutorial route and visual root checks. |
| C5 | Recover follow ray47C210 filtering and coefficients, then implement shared viewport handoff/DEFAULT snap and follow43B820. | Source byte/probe predicate, below/equal/above1000 eye-distance boundary (snap strictly above), obstruction hit adjustment, controlled/scripted/return camera continuity, per-level projection. Port GPU checks remain separate from original visual comparison. |
| C6 | Recover source allocation/failure and sound+44 duration conversion. Source slot14 uses software duration milliseconds and repeat+30, not hardware status. Model that channel state plus current SFX bank/default gate, then connect CAM/MCA completion. | Strict elapsed>duration boundary, repeat/stop/invalid handle/clock pause; bank unload/reload/default/scene disposal. SDL dummy tests validate transport only; queue-empty is not source timing. Physical/native Windows output remains separate. |
| C7 | Queued TSK load460E70→460EA0→4603F0: repeated task424 and all-entity420 post-task hooks. Ordinary scene placement separately uses46E61A→Jimmy40C423610. Recover enclosing loader, RETURN flags/root/STRT and acquired-reset gate50988A. | C1/C2 first. Trace source duplicate-callback effect before adopting; original12-save byte round-trip; fresh load vs RETURN vs practice No/Yes; persistent arrays/score/energy/strings vs reset timers/handles/actors. |
| C8 | Morph playback flags/rate/end events and UI dispatcher mode/layout gates. | Original clip/end-state probes; action interruption/landing/cutscene restoration; objective/practice controls. Preserve modern widescreen/debug policy and test pointer anchors separately. |
Implementation expansion into later levels, gadgets/combat, menus and full save UI
resumes only after these core contracts support it. Later-level investigation is
allowed where it resolves a core-system question, without waiting for every level.
## Execution ledger
- Entry: baseline69d0187 preserved;539 original hashes verified. Dedicated
investigators assigned independent loop/motion, script/state and camera/audio/UI
files. Main loop findings integrated by primary after investigator usage limit.
- C1: implemented pre-assignment objective boundary. Data/Interaction/Director,
input-only lab route and RETURN regressions pass. Source45FB5B/7F/D9 checked
independently and retained in the script/state helper. No scheduler changes.
- C2: captured SCENE before generic activation, moved LV1B Carl override into the
same per-actor director callback, and removed the interactions-layer batch fix.
Original413F3D/413F4E/414068..414118 independently checked. Director callback
observers now see the final derived state before later actors. Director,
Interaction and input-only lab route regressions pass; broader checks pending.
- C3 investigation: input/frame bridge and fresh lab partial construction order
recovered and byte-checked. Fresh game input→Jimmy controller→fire runs after
global physics. Retained registry/lifecycle remains the integration gate; no
speculative global reorder applied.
- C6 investigation: `voice-clock.md` resolves derived slot14 to inherited software
elapsed/duration and+30 to repeat. Replaced the proposed hardware/SDL-playing
interpretation before changing runtime. Original bytes and one new regression pass.
- C5 investigation: `camera-ray-predicate.md` recovers static grid registration,
wall priority, FIFO first-hit and source kernel, with four order/data regressions.
A static adapter is now justified; complete camera handoff still needs its state.
- C7 investigation: `scene-loader.md` closes app deferred request→teardown→GAM→
per-object initialization/PostLoad. Jimmy/Goddard retention/reuse is proven;
per-field reset/old-game/helper lifetime remains a bounded next trace. Editor R
reset distinguished from ordinary load. Consistency review leaves old-game
removal/eligibility explicit rather than treating current pointer overwrite as
deletion. Five evidence regressions pass. This is the next C3/C7 integration gate.
- Exit review: core architecture checkpoint documented in `review.md`; feature
expansion remains paused. C1/C2 full integration passes; final follow-up Python
discovery and original hashes recorded under artifacts/re-checkpoint/.
- C3/C7 gate closed: normal Init copies stored+11 to live+139, restoring the
level game's deletion predicate. Destructor explicitly unlinks its registry
node. `level-game-lifetime.md` and three byte regressions retain that proof.
- C3 first implementation: controlled player physics consumes prior motion/queued
impulse before input/player/fire callbacks. Fresh versus retained input order
follows proven registration; stored mode and same-frame landing reset are
explicit. Twenty movement groups, input-only routes and GPU RETURN pass targeted
checks. Full-scene scheduling, uncontrolled-body and collision response remain open.
- C5 static adapter implemented/integrated for LV1B/VR04/LEV1: source cell/FIFO/
wall-first predicate and single-triangle kernel, source eye adjustment/gain,
one query per input callback. Eleven camera groups and existing support groups
pass; full camera handoff/input state remains open.
- C7 availability correction: level entry enables state4→1 for the recovered eight
gadgets, then VR01..08 disables owned1→4. Unknown states/other groups preserved;
tutorial bypass unchanged. Source anchors and boundary/round-trip tests cover it.
Arbitrary retained scalar/mode/fire state is still gated by the streamer/lifecycle
fixture; no blanket carry was introduced.
- Full integration passes: artifacts/implementation/integration-final.log.
Seventy Python checks, all managed groups including20 movement/11 camera/
13 support, GPU story/route/practice/RETURN/jetpack/animation with zero validation
errors, SDL dummy lifecycle and539 unchanged hashes. RETURN also verifies
retained input order and tutorial availability normalization. Packages rebuilt
after the implementation milestone; platform runtime claims remain separate.
- Packages: clean09cf117 Linux/Windows self-contained outputs; Linux launch from
/tmp passes practice/RETURN and outside scene load. Release validation layers
unavailable; source full integration validated above. Package evidence recorded
separately without changing runtime. Continue the remaining source-state and
shared-camera/control/collision gates rather than resuming feature expansion.
- Retained-field continuation2026-10-26: property extraction has no hidden reset
callback; generic Init re-applies authored body vectors, final preparation clears
velocity/speed, Jimmy jump state resets separately from mode/hold/fire. Bounded
route/no-gadget/jetpack PlayerLevelState now carries only those three scalars
through ordinary transitions, never TSK loads. Companion/shadow reset fields and
same-state AI guard are documented; body registration/new-helper timing remain.
- Corrected C7 prefix-only availability: full VR01..08 tails re-enable the practice
gadget0..7, so owned VR04 jetpack finishes1. LV1B disables gadgets1/7. Managed
state boundaries/unknown values and GPU practice/RETURN guard the correction.
Other level-specific selection/availability tails remain an explicit gate.
- Retained continuation validation:84 Python,22 movement plus remaining managed
groups,26 enabled-validation GPU renders, final nondefault tutorial/RETURN
boundary replay, four final SDL dummy checks and539 original hashes pass.
Original43A750/vector leaf component probe passes in isolated Wine32; this is
separate from whole-loader/original-game/native-Windows validation. Next gates:
uncontrolled body/controller/fire scheduling, body registration/helper traversal,
C4 response/root and shared camera handoff. See progress.md for sampling-check details.
- Release evidence: both self-contained packages from clean9ad5a8e; standalone
Linux launch from /tmp verifies nondefault tutorial/RETURN scalar boundaries and
body resets. Release validation unavailable; source GPU checks enabled. Native
Windows runtime remains unverified for this chunk. Preserved baseline untouched.
- C3 control continuation: gated movement/input independently of eligible body and
fire; explicit CAM/MCA/AI raw-owner preparations and body-before-STOP order;
initial MCA target-none returns, later shots do not repeat preparation. Scripted
player transforms synchronize into body state. Grounded ordinary radius is outside
the control gate. Full wrapper/base/ceiling/class effects remain open.
- Same binding is exercised by the input-only lab route; modern replay now brakes
before large turns instead of coasting past the narrow door. Task/score/inventory/
contact assertions remain. The observed corner behavior is retained as C4 input.
- Local REA/Ghidra/full-JDK setup and batch Evidence/snapshot workflow verified.
Five selected source procedures cross-check gates/base calls. Missing analyzed
fire entry is recorded; no target execution or client registration change.
- Final C3 integration: full scripts/test.sh passes with93 Python checks,24 movement
groups, remaining managed checks and the binding-based input-only lab route,
27 zero-error enabled-validation GPU renders, SDL dummy lifecycle and539 hashes.
Native GTX1070 Carl/control/F1/F3 commands pass; native Windows remains separate.
- C3 release evidence: both self-contained packages identify clean c285b57;
standalone Linux from /tmp passes airborne control/body/fire and nondefault
tutorial/RETURN assertions. Release validation unavailable; enabled-validation
checks above remain separate. Baseline untouched; Windows cross-published only.
Logs: artifacts/uncontrolled-phases/package*.log. Next work is full wrapper/base
ownership, C4 collision/root response and shared camera handoff.
- C4 bounded kernel: REA/byte cross-checks recover47BD80 and helpers, with ten
isolated original Wine32 synthetic cases and a managed numeric-reference module.
Live capsule replacement remains gated on grid traversal/order, negative-Y split,
normal callbacks, support/friction and dynamic reclipping. No source generic
recursive capsule slide was found in the inspected dispatcher.
- C3/C4 wrapper: root+150 upward query and min(−0.6Vy,−85) response now run before
Jimmy movement/fire, regardless of ownership; mode1 cancellation preserves hold
and independent queued/body work. Fresh/retained input boundaries preserved;
camera-only debug switch cannot disable physical query. Other scene filters,
sound and selected-gadget cleanup remain separate.
- Registration: retained registry objects have49E cleared, then physical Init/list
registration repeats Init before placement. Shared-eye capture/pre-update aim
is source-guarded but C5 runtime correction remains next. Detailed reports:
collision-response.md, ceiling-wrapper.md, body-root-registration.md,
camera-handoff.md; complete REA results and provider gaps retained on disk.
- Final C4 bounded continuation validation:104 Python plus HUD,25 movement/five
sphere and remaining managed groups,27 zero-error enabled-validation GPU renders,
SDL dummy lifecycle and539 unchanged originals. Four native GTX1070 window
commands pass (five scene renders). Full capsule replacement, complete camera
state and original whole-game/native Windows validation remain separate gates.
- C4 continuation release: both self-contained packages identify clean57dfcc6
(source_dirty=no); standalone Linux from /tmp passes control/body/fire and
nondefault tutorial/RETURN checks. Release validation unavailable, enabled
source/native checks separate. Package logs in artifacts/collision-response/;
baseline untouched and Windows cross-published only.
- C4 static composition: independent REA grid/contact investigations recover
FIFO duplicate traversal, reachable retries, normal/landing ownership, signed
material archive IDs, separate published160 speed and friction/suppression.
Seven isolated original dispatcher fixtures match the managed component's
positions/counts/callbacks. Ten copied479D20/support fixtures completed; no
managed whole-body equivalent is claimed yet. Reports: collision-body-probe.md,
collision-grid-traversal.md, collision-contact-callbacks.md and independent review.
- Prepared scenes now retain material IDs and completeness; legacy metadata cannot
masquerade as ordinary-only. Actual VR04 has no special contacts; LV1B/LEV1 do.
Geometry-disabled publication/retained callback and strict initial support
distance are explicit. Original geometry-off branch supersedes C3's earlier
support-hit gravity-cancellation inference. Playable body remains baseline.
- Next C4 chunk: ordinary-body composition and ten numeric comparisons, negative-Y
horizontal-first split,370, landing-before-velocity-clear, published160 friction
and suppression; then VR04 live root/input/ceiling/RETURN checks. Trace special
callbacks and dynamic reclip/global context before lab/outside replacement.
- C4 ordinary-body composition implemented and matched against all ten copied
body references. VR04 now selects the source static subset with live radius
60/100, separate published160, control-independent body work and source landing/
friction order. Twenty managed groups and native/headless300-frame jetpack
replay pass; lab/outside capsule retained. Source and independent review:
collision-body-composition-source.md, collision-body-implementation.md and
collision-body-implementation-review.md. Other original VR04 dynamic class
eligibility, special Player callbacks and shared dynamic contexts remain open.
- C4 ordinary-body milestone35a2a66 is clean and packaged for linux-x64/win-x64.
Full integration passes129 Python+HUD/managed/27 GPU/audio/539 hashes; final
Python130 includes the added Init authored114→26C speed regression. Standalone
Linux from /tmp passes source-body VR04 flight and nondefault tutorial/RETURN.
Source/native validation enabled; release layers unavailable; native Windows
comparison remains open. Logs: artifacts/body-composition/.
C4 body ownership continuation (2026-11-05): implemented finite fresh previous/live
XYZW publication, independent body modes, retained context and landing payload
ordering.100 complete native comparisons plus six state-only mutation cases pass;
full regression/native/package checks are in body-contact-implementation.md.
Lab/outside remain gated behind actual hazard/climb callbacks, actor mode/animation
persistence and dynamic/shared-scene context. Do not infer full C4 completion.
+135
View File
@@ -0,0 +1,135 @@
# Input dispatch belongs to the viewport game-object pass
Static recovery, 2026-10-25. This follow-up resolves the input/world-logic bridge
left open in [loop-motion.md](loop-motion.md). Originals were read, never executed
or changed. SHA256: Neutron.exe
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`;
OMT2.dll `3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
The helper maps original bytes through PE sections and verifies30 decisive
anchors, direct calls and vtable entries. File offsets below are hexadecimal.
## Recovered dispatch bridge
The level game receives input dispatch during the same viewport callback that
integrates physics. It is **not** called by the engine world's OMT logic update.
There are two distinct update interfaces, with different ownership and clocks.
| Step | Module VA / file offset | Evidence |
|---|---|---|
| Viewport first integrates physics | EXE47E554 /7E554 →479BC0 | Direct call before game-object pass |
| Viewport updates registry | EXE47E582 /7E582 →473740 | Registry50999C, node+8 payload, slot10 call at473758 /73758 |
| Lab game interface enters normal update | EXE4C387C /C387C =470280;4C3C30 /C3C30 =44DF80 | CLevel01BGame interface vtable4C386C: slot10 wrapper; slot3C4 actual callback |
| Base game has identical dispatch | EXE4C2C94 /C2C94 =470280;4C3048 /C3048 =44DF80 | CJimmyGame interface vtable4C2C84 |
| Wrapper supplies frame argument | EXE47028E /7028E;4702C5 /702C5 | Stores dt at interface+294; calls slot3C4 unless supervisor+8C selects3C8 |
| Game updates timer/event records first | EXE44DF89 /4DF89 →45F510 | Direct call before input;45F5BF..D3 advances record float+10 by dt*owner+8 |
| Game dispatches input | EXE44DF94 /4DF94 →475A70 | Same dt argument propagated |
| Dispatcher obtains controlled object | EXE475A9C /75A9C;475AA9 /75AA9 | Global5099E4 null skips input; nonnull calls its interface slot3CC |
| Jimmy receives input | EXE4A3B08 /A3B08 =426030;426084 /26084 →438A60 | Jimmy vtable4A373C slot3CC; guards precede base movement input |
| Later logical objects update | EXE4A3B00 /A3B00 =424600 | Jimmy slot3C4 eventually calls437940 at424C34 /24C34 |
| Entire registry synchronizes transforms | EXE47E587 /7E587 →473770 | Separate traversal after all ordinary callbacks |
| Base viewport draws | EXE47E6DF /7E6DF imports48D304 | Named import OMediaViewPort::render_viewport |
**Pointer coordinates:** CJimmyGame and CLevel01BGame game-interface pointers
are **complete+8C**, whereas C3DJimmy is **complete+C0**. RTTI locators
EXE4E0768 /E0768 (base game) and4E08F0 /E08F0 (lab game) hold displacement8C.
Instruction475A8A /75A8A explicitly reads the complete vptr from interface-8C
and475A90 forms that complete pointer. Do not apply Jimmy's-C0 conversion here.
For the game, interface+294 is complete+320; for Jimmy it is complete+354.
The registry constructor appends to the tail, so input relative to Jimmy's
ordinary update depends on insertion order. The recovered guarantee is:
```text
physics of registered bodies
-> game-object registry traversal in insertion order
game object: event timers -> controlled object's input callback
Jimmy object: base/rotation -> movement/jump/jetpack controller
other objects/effects in their actual registered positions
-> whole-registry logical-to-visual synchronization -> draw
```
Game-before-Jimmy ordering for an actual loaded lab still requires a bounded
construction trace, including constructor-created shadow/fire objects. The
diagram deliberately does not assert that relative order. Even without it,
Jimmy's current controller cannot change the physics pass that already ran.
Queued jump impulses are consumed by a later physics invocation. A separate
class-specific collision query/update during an object callback must not be
mistaken for replaying the earlier global physics pass.
## Engine OMT logic is separate, and runs before render broadcast
DLL100215C0 /215C0 sends logic message-604 at100215D4 /215D4 when global
1013D6DC is zero, then sends render message-605 at100215E8 /215E8, passing
that global as the render-message argument. These are synchronous virtual
broadcaster calls. World listener100F9C40 /F9C40 converts its listener pointer
by-30 and calls complete world slot30, update_logic100F9B10 /F9B10.
World update_elements100F9C80 /F9C80 invokes complete OMT element slot3C,
parent before descendants, preserving its pre-callback next-node pointer.
For CLevel01BGame, complete OMT vtable4C3CD0 slot3C at4C3D0C /C3D0C is
4747A0; this forwards through IAT48D230 at4747A5 /747A5 to
OMediaElement::update_logic, DLL100EFF20 /EFF20, a `ret4` no-op. Thus this
path does not dispatch44DF80 or player input. For Jimmy, complete vtable4A3BDC
slot3C at4A3C18 /A3C18 is462260; it forwards at462265 /62265 through48D244
to OMedia3DMorphAnim::update_logic10002DB0 /2DB0. That calls
OMediaAnim::update_logic10020CF0 /20CF0 with the morph subobject at complete+90.
Eligible animation updates therefore run through OMT logic before the ensuing
render message's game callbacks select/change poses. Logic can be skipped by the
periodical flag, world pause or timer gate. Exact displayed first-frame and
completion effects still require analysis of animation flags and listener order.
The render message reaches engine listener1006BCB0 /6BCB0, which converts its
listener by-10 and calls engine slot14 at1006BCCA /6BCCA. The full renderer
backend/surface/viewport route remains a separately bounded follow-up; the
viewport's own physics→registry→draw order is already established independently.
## Timer units, defaults and limits
| Owner/field | Source VA / file offset | Recovered value or transition |
|---|---|---|
| World pause count+44 | DLL100F9B18 /F9B18 | Nonzero returns without world logic |
| Timer begins world+48 | DLL100F9B26 /F9B26 | Elapsed obtained by100FA0A0 /FA0A0 unless timer byte+0D is set |
| Timer mode world+58 | DLL100F989D /F989D | Constructor writes1 |
| Timer period world+5C | DLL100F98A0 /F98A0 | Constructor writes40 |
| Maximum elapsed world+60 | DLL100F98A7 /F98A7 | Constructor writes500;100F9B42..47 clamps larger elapsed if max nonzero |
| Minimum elapsed world+64 | DLL100F98AE /F98AE | Constructor writes1;100F9B51..5B skips below this if timer is running |
| Engine clock | DLL100F8D18 /F8D18 | GetTickCount import1011410C, minus global epoch1017A308 in ordinary path; optional override/pause branches exist |
| Engine elapsed passed to elements | DLL100F9BCC..E6 /F9BCC | Unsigned integer elapsed converted to float, no seconds division before world slot3C traversal |
| Viewport game clock | EXE47E490 /7E490;47E502 /7E502 | QPC delta/frequency float seconds stored696030; accepted only0<dt<1 |
The **engine elapsed units are milliseconds** in the ordinary GetTickCount path.
These constructor values are defaults, not proof no game/setup writes replace
them. Mode1 passes the elapsed value when it reaches the minimum. Mode0 and2
also compare elapsed with period; mode2 invokes100FA120 /FA120 to adjust period
using accumulated elapsed samples (initial/reset40). Neither establishes a60Hz
gameplay cadence. World max/min elapsed govern the OMT logic/animation route;
they do not directly clamp the QPC seconds consumed by viewport physics and input.
No recovered fixed1/60 accumulator or Sleep-based frame limiter exists in the
bounded application/periodical/viewport routines inspected here. Presentation,
backend blocking and driver synchronization can still constrain actual cadence.
## Current implementation, verification and concrete C3 next action
Baseline69d0187 samples SDL keys and runs grouped fixed60Hz simulation with
controller before physics; Program then updates mechanisms, patrols, director,
objective state and poses. This is an implementation policy and differs from
the directly recovered order above. Do not describe the source world timer's
1ms minimum or40ms period default as the port's intended fixed rate.
`python3 tools/binary/checkpoint_input_frame.py` and
`python3 -m unittest discover -s tests -p test_checkpoint_input_frame.py -v`
check immutable module hashes, fresh source bytes, direct calls and virtual
slots. They provide static verification only. No original gameplay cadence,
native Windows timing, or source input latency was runtime-verified here.
C3 can now define a traceable frame interface with separate **engine animation**,
**body integration**, **insertion-order object callbacks**, and **visual sync**
phases. Before changing the playable controller, recover the lab construction
sequence through object registration46FF4A..7F, and list game/Jimmy/shadow/fire/
Goddard registry positions. Replay that list with a trace asserting physics
precedes all input/controller callbacks and input uses current5099E4. Then split
LabSimulation's input/velocity production from body integration in one bounded
change, preserving the existing route as a regression. Keep fixed60Hz explicitly
chosen until original timing observation or a recovered game frame-cap mechanism
supports replacing it. Also trace event-pump ordering/focus transitions and
pause/invalid-dt boundaries before claiming end-to-end source equivalence.
+140
View File
@@ -0,0 +1,140 @@
# Jimmy special contacts: movement-stability audit
2026-11-04. Static recovery plus27 isolated original-dispatch observations; no
runtime solver change. Current playable fccc0b9 remains the baseline. The user
returned priority to Jimmy movement and explicitly allowed JN-Engine as a guide.
JN-Engine's prototype movement is not imported or treated as an oracle.
## Result and immediate implementation boundary
The lab/outside capsule bypasses material callbacks entirely: SceneCollision's
private triangles retain geometric positions/normals but no linked material ID,
and LabSimulation.StepPhysics receives only grounded/wall/ceiling flags. This is
a concrete missing interaction layer, not evidence that changing walk constants
or adding universal wall reflection will fix collision fidelity.
**Do not globally admit lab/outside to OriginalBodyPhysics yet.** Besides dynamic
pairs, three directly evidenced contracts are missing: material-driven hazard/
climb actions, world-response1D0 state during special animation, and contact-owned
root publication. The existing ordinary sphere composition assumes no
root-changing callbacks. Its wallContact hook alone does not establish the
source's fresh previous/live Vec4 equality or special-animation lifecycle.
For example, it currently adds the old falling displacement.Y after the hook
returns a root, whereas the original can skip that entire candidate publication
when the contact changed live/previous root. A root-changing callback cannot be
made faithful simply by returning a different OrdinaryBodyState.Position.
The smallest safe movement implementation chunk is ordinary ground/air arithmetic
and phase stability while preserving the current route solver. For collision:
first preserve/report actual contacted shape/polygon/3DMa identity in a diagnostic
path; next implement the state-owning callbacks and source body modes with
regressions; only then enable a bounded real lab/outside source-body route. Do not
silently classify a special contact as ordinary to make scene admission succeed.
## Original identity and source map
Neutron.exe SHA256:
f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8.
Every code VA below maps to raw offset VA−400000, independently checked by PE.
`tools/binary/jimmy_special_contact.py` records five bounded spans with hashes,
raw offsets and four live virtual bindings. Existing material loader/source
coverage is in collision-contact-callbacks.md and its guarded helper.
| Code VA / raw offset | Observed contract |
|---|---|
|43AA40 /3AA40|Player contact handler takes **game interface** (Jimmy complete+C0), supplied Vec4 normal and polygon. First requires elapsed game774>3; missing polygon/material/chunk yields no special policy. Reads signed archive3DMa ID through polygon+4→material+C→chunk+8.|
|43AA7E..43AAD5 /3AA7E..3AAD5|IDs120..129 call **complete virtual160**, IDs110..119 call **complete164**. These dispatches precede the movement-mode check and therefore still occur in nonzero modes.160/164 are slot offsets, not material IDs.|
|43AAD5..43AAF9 /3AAD5..3AAF9|Fence IDs60..69 and ladder180 require mode game704==0. Other metadata returns without generic reflection/projection. The handler contains no raw controlled-pointer gate.|
|43AB17..43ABBF /3AB17..3ABBF|Ladder first requires game338→472570 retained support polygon pointer (live234), then a47C210 probe. This is not the same predicate as current grounded218. A missing retained polygon prevents even the ray attempt.|
|43ACD4..43AE19 /3ACD4..3AE19|Fence requires first probe to miss and subsequent side probes to hit. Miss-only synthetic probes make exactly two calls then reject. Different ray outcome sequences are not equivalent to a single wall hit.|
|43AC29..43ACC5 /3AC29..3ACC5;43AF54..43AFDB /3AF54..3AFDB|Successful branches derive yaw from negative supplied normal through original angles, set destination/live orientation, transform local offsets, publish root314 and request LADDER/FENCE through complete150. Full successful-ray traces remain unexecuted.|
|42A7E0 /2A7E0|Jimmy complete160 requires splat cooldown1E60<=0 and !1DED latch. Requests SPLAT via150, sets latch, clears impact clock1DE8 and controller scalar complete6C8/game608, stores supplied normal at1DF0..1DFC, requests−5 energy/score through42A920/42ADC0, and SFX37. Those helpers retain their own tutorial/global policies.|
|42A8D0 /2A8D0|Jimmy complete164 requires !1DEC latch and raw gadget4F0588!=0 (Bubble0 immunity). Sets latch, clears1DE8, requests−5 energy/score, calls complete1E0→425120 (mode1 jump/effect cancellation). It does not share160's cooldown gate.|
|437953..43796A /37953..3796A|Increment game774 elapsed **before** base40E050 and later raw ownership gate. Physics contact reads the preceding phase's elapsed. Omitting this timer would permanently suppress source policies; gating it only on Jimmy input is also wrong.|
|43B408..43B4B4 /3B408..3B4B4;43B4BE..43B58A /3B4BE..3B58A|FENCE/LADDER animation entry owns saved destination Vec4 complete838..844/game778..784. Respective local offsets(0,320,150)/(0,800,150), velocity0, gameA8(false), action helper148, global busy4F83E0=true, duration complete888=4/6, fallback timer868=5, elapsed834=0, nonloop animation and SFX146/143.|
|43A900 /3A900|AnimEnded handler returns FENCE/LADDER to STOP, clears busy/duration, calls Jimmy game410→42AFC0, clears action flag complete6E4/game624 and controller speed complete6C8/game608, restores saved full Vec4 root314, then gameA8(true). SPLAT/HIT branches differ.|
|437988..437A15 /37988..37A15|Fallback timer game7A8 is decremented before input ownership gate. Expiry while busy can restore the saved root/response state too. Source duration4/6 and fallback5 are distinct; do not invent one universal fixed climb timer.|
|47A123..47A1C4 /7A123..7A1C4|Body publication rereads previous2F8/live310 and compares all four components. A contact-owned root change skips candidate clamp/publication. Vector3-only stale equality is not this boundary.|
Bindings independently checked: Jimmy complete4A3BDC+160→42A7E0,+164→42A8D0;
Jimmy game4A373C+374→42A660→Player43AA40; Player game4AF6C4+374→43AA40.
Game338→472570 returns retained polygon234, not a boolean grounded query.
GameA8→470FD0 changes **world-response** getter1D0/live13C. It does not disable
integration210, support1C8, raw control118 or global geometry4F69E5. Consequently
`geometryEnabled=false` in the current managed body is not an implementation of
this transition: that parameter follows global geometry-off gravity cancellation.
The pose setter's exact callback acceptance, source morph/event cadence, impact
latch/impulse updater4255C0, successful ladder/fence ray offsets/filters and reset
interactions need component/runtime closure before actual mechanics are enabled.
The stored impact normal is consumed later; immediate arbitrary velocity reflection
would replace that state machine with a different behavior.
## REA and JN-Engine evidence
JN-Engine docs/decomp/C3DPlayer.md, C3DJimmy.md and original decompiler bodies
in docs/decomp/evidence/c3dplayer_movement_target3.md/c3djimmy_target6.md supplied
function/field leads. Shared EXE identity is verified; its prototype movement and
its different declared OMT2.dll build are not numeric/runtime authorities here.
Class reports mix game and complete bases in places; the offsets above follow
authoritative instructions and the independently established+C0 interface.
Configured REA/Ghidra12.1.4 batch at artifacts/jimmy-special-contact/rea used the
existing generated target copy and exported Evidence/closed snapshot:
- 42A7E0: ev_801bbf1e21eb341f126f5e57e3efbfca42bb1c799680b2429c7f05dfdda3d625.
- 42A8D0: ev_889e1c63d50f8e6da7e451ba0b821396f884fb7d7961dcdede3c4f3ca0e54af3.
- 43A900: ev_0c030c12f6beb0790a6be2c53d3c4ac6591c8c2bd6552e8ea888f8de13455c7f.
43AFF0 returned an explicit procedure-recognition error; retained reply03.json
is not successful decompilation and the unchanged selector was not repeated.
Its supporting instruction extract is saved as special-animation.asm; the JN
body is only a lead. Reused43AA40 Evidence:
ev_4f2a6aa666451db831efd46f5c587573e22d8072315626b8bc2f844f9c6f0cae
under artifacts/collision-integration/contacts/rea-callbacks. REA x87/return-address
aliases are imperfect; reviewed call signatures/bytes settle the normal payload.
## Isolated original execution and tests
The new generated probe executes copied43AA40 with synthetic game/complete
vtables, linked polygon/material/chunk records, no-op160/164 callbacks and a
miss-only ray stub. It **does not** execute real damage, successful climb,
animation, body integration, collision traversal or the original game entrypoint.
An initialized local Wine32 prefix runs the copied code in the project's separate
network/filesystem sandbox; Wine exit0 and JIMMY_SPECIAL_CONTACT_COMPLETE are
retained in artifacts/jimmy-special-contact/probe/{wine.log,capture.json}.
27 observations cover signed metadata and all dispatch boundaries, strict elapsed
3/above3, nonzero movement modes, null polygon/material/chunk, missing retained
support polygon, and both hazard dispatch/fence ray attempts with raw controlNULL.
Normal Vec4 reaches160 unchanged. Miss-only fence performs two probes; ladder one
when support pointer exists. These are branch/gate observations, not terrain
success or original end-to-end movement traces.
`tests/test_jimmy_special_contact.py` commits the observations, original source
span/binding identity and generator/harness/executable/log hashes. Four Python
groups pass: source/offset/bindings, all27 native dispatch cases, provenance, and
output/original/symlink isolation. Originals remain untouched. No runtime source
or existing tests/docs were modified by this investigator; no commit was made.
## Proposed continuation gates
1. Keep source-backed controller/air/jump fixes and current playable route solver
independent; preserve fccc0b9 and subsequent tested movement checkpoints.
2. Expose contact metadata/root-ownership diagnostics; recover4255C0 impact latch
and impulse completion, then implement material120..129's bounded hazard flow.
3. Recover/verify successful climb rays, full animation-end/fallback ownership and
independent world-response mode before adopting fence/ladder callbacks.
4. Complete dynamic pair eligibility/shared context and Vec4 publication, then
run input-only lab/tutorial/RETURN/outside cases with known special contacts.
General floor/step/wall fidelity is not established by these27 leaf probes.
## Subsequent prerequisite implementation
[Body contact implementation](body-contact-implementation.md) now supplies the
fresh previous/live XYZW barrier, independent source modes and landing ownership,
with100 complete native comparisons plus six callback-state cases. The missing
barrier/flag paragraphs above describe the audit baseline, superseded by that
bounded foundation. Actual hazard/climb callbacks, animation acceptance/completion,
per-actor multi-frame state and dynamic context still gate broad admission.
+129
View File
@@ -0,0 +1,129 @@
# Fresh laboratory construction and registry ordering
Static recovery,2026-10-25. Originals remain untouched; no legacy code executed.
Neutron.exe SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`;
gam/level1b.gam SHA256
`316fff40db565c2add5b07cbccdef640ddb67c64d6625fea1429ce2a0542a234`.
All addresses below are preferred-base EXE VAs; their verified PE file offsets
are VA-400000. The helper emits both coordinates and checks39 source anchors.
## Recovered fresh-load partial order
For a fresh lab with no matching reusable Jimmy, the source establishes:
```text
LV1B game interface+8C enters registry
-> Jimmy interface+C0 enters registry
-> owned jetpack fire interface+C0
-> other Jimmy constructor helpers
-> owned Jimmy shadow interface+C8
-> additional constructor helpers
-> remaining serialized lab entities in file order, with their own helpers
-> postload callbacks in registry order
Jimmy creates absent Goddard interface+C0
-> Goddard shadow interface+C8, then other Goddard helpers
```
This is a **partial order**, not adjacent nodes or absolute list indices. The
helper intentionally does not manufacture a full registry from the GAM alone:
constructor-owned objects are not serialized entity records. Geometry/other
postload objects can also intervene. The ordering does establish that normal
fresh-lab input from the game object runs before Jimmy's controller, Jimmy runs
before his fire effect, and Goddard follows both in the game callback pass.
| Boundary | Calls / source instructions (VA; file offset follows VA-400000) |
|---|---|
| Header first | Loader46E319..32B reads initial FourCC through imported stream operator48D3E0;46E335 /6E335 calls factory459CB0 before entity count read46E36A /6E36A |
| LV1B class allocation | Factory45D3FD /5D3FD →44F300, allocating5C0 bytes; constructor44F3B8 /4F3B8 sets LV1B |
| Game base chain |44F358 →44D2B0;44D306 →4745A0;474602 forms complete+8C;47460A →4586F0;458712 →46FBE0 |
| Common registry insert |46FF4A..7F /6FF4A: global50999C sentinel; alloc12; node.next=sentinel;node.prev=oldtail;sentinel.prev=node;oldtail.next=node;node+8=interface |
| First entity | Lab GAM has129 records; first is3JIM/JIM1 at file000008;46E37F reads its code and fresh branch46E3B9 calls factory459CB0 |
| Jimmy factory/base chain |45B1E2 →422160;4221B1 →437280;4372DA →40D110;40D162 →462040;4620A2 forms complete+C0;4620AA →4586F0 →46FBE0 |
| Fire during player base construction |4374DF →421D80;421DD2 →40D110, so it registers after Jimmy;4374EF stores fire complete pointer at Jimmy complete+7F8 |
| Jimmy shadow |42250C →43F640;43F692 →4352F0;435341 →463F10;463F6C forms complete+C8;463F74 →4586F0 →46FBE0;42251C stores shadow at Jimmy complete+A2C |
| Remaining GAM records |46E3FD invokes stream extraction48D190 on the current interface;46E426 reads next code;fresh branch46E49A calls factory;46E4BA loops to46E3D1 |
| Postload after records |46E4FF invokes supervisor slot128. Vtable4D5EA0 entry4D5FC8 /D5FC8 resolves46E570, which traverses registry and invokes interface40C at46E61A |
| Jimmy postload |Vtable4A373C entry4A3B48 /A3B48 resolves423610. This callback contains the Goddard construction below |
| Goddard is runtime-owned |Lab GAM contains zero3GOD records.423C6A..72 tests Jimmy interface+95C; if absent,423C98 →41C810;423CAE stores Goddard complete pointer at interface+95C (complete+A1C) |
| Goddard registers before his shadow |41C861 →407A40;407A92 →40D110 →462040 →4586F0;41C95F →43F640 builds his shadow afterward;41C96F stores shadow complete pointer at Goddard complete+994 |
The postload traversal reads next after the callback at46E668, so a newly
tail-appended Goddard is eligible to receive postload later in that same traversal.
This follows from the linked-list operations; it is not an original runtime
capture. Allocation failure and callbacks that remove/reorder nodes need separate
handling and are not silently interpreted as the normal successful load.
## Fresh input/controller/effect frame consequence
[input-frame-bridge.md](input-frame-bridge.md) establishes that viewport47E4F0
first calls global physics479BC0, then registry updater473740, then transform
synchronization473770, then base draw. Combining that with the fresh partial
order gives the bounded interaction:
1. Physics consumes existing Jimmy velocity/acceleration/queued impulse.
2. Game44DF80 advances timer records and dispatches input475A70 to current5099E4.
3. Jimmy424600 updates base/rotation/controller437940, which may queue a jump or
start/stop/change a burst.
4. Owned fire421FB0 runs later, observes that controller state and decrements
its timer/energy according to its already recovered rules.
5. Goddard's ordinary game update occurs later in the same registry pass.
6. All surviving logical actor transforms are synchronized before rendering.
Thus a fresh controller-created impulse waits until a later global physics pass,
while a newly assigned positive fire timer can be decremented by its effect
callback in the same game-object pass. This resolves the previous open
Jimmy-versus-fire ordering without inventing a nominal60Hz source cadence.
The baseline port's combined controller→physics→effect call differs at the first
boundary. Splitting pending body inputs is directly supported for this fresh-load
case; actual gameplay comparison remains required for latency/apex fidelity.
## Reuse and transition ordering remain a separate gate
Source explicitly supports existing-object reuse:
- Jimmy constructor42275A writes complete+C9=1, or interface+09. Goddard
constructor41C9C0 writes the equivalent flag. Common constructor46FFAE starts
interface+09 at0. This is an observed reuse flag; it alone does not prove
lifetime across any particular level transition.
- Supervisor vtable4D5EA0 slot11C at4D5FBC /D5FBC resolves46E6A0. It walks
registry50999C and requires matching interface+404 class code **and** nonzero
interface+09 at46E6B9..C6. Slot110 at4D5FB0 /D5FB0 resolves46E6E0, returning
the first matching existing object without moving/re-appending its node.
- Loader46E38B /6E38B and46E45A /6E45A use this predicate before choosing the
fresh factory branch. Reusing Jimmy therefore does not repeat his constructor
or append his fire/shadow again. Jimmy postload separately reuses his existing
Goddard pointer if present.
**Follow-up for lab→tutorial→lab:** `scene-loader.md` now proves Jimmy/Goddard's
zero teardown predicate and positive reuse flag together. Their retention/reuse
contract is recovered, but the complete retained helper set, field resets and
old current-game removal/eligibility remain open. Deferred transition46DFF0 queries each object's
slot200, calls lifecycle slots20/34, marks some interface+06 for deletion and
calls473710.473710 deletes flagged nodes through interface slot0 and restarts
the list scan. A complete retained-set proof needs each relevant slot200 getter
and flag write, plus each object's lifecycle callbacks and owned-child cleanup.
Slot200 for Jimmy/Goddard is4719B0, reading interface+139; **it is not** the
reuse flag+09. Conflating those two fields would fabricate persistent ordering.
Do not assume the fresh game-before-Jimmy relation after a transition: the new
game appends later, while old-game callback eligibility needs its own proof.
## Verification and bounded next implementation
`python3 tools/binary/checkpoint_lab_registry.py` verifies source hashes,
12 decisive instruction ranges,23 direct calls and4 virtual entries, then parses
the original lab GAM for its header/count/first record and absent3GOD record.
`python3 -m unittest discover -s tests -p test_checkpoint_lab_registry.py -v`
passes the original-data regression. This is static evidence; no port or original
gameplay runtime verification was performed for this follow-up.
Baseline69d0187 groups simulation, mechanisms, patrols, director and effects by
subsystem. A C3 scheduler can now model the fresh lab's proven input→Jimmy→fire
ordering after global physics, with logical-to-visual synchronization last.
Keep initial source-order replay separate from current playable policy while
covering queued jump, same-pass burst countdown, landing and control transfer.
For the tutorial return, first trace cleanup46DFF0→lifecycle20/34→473710 and
prove the surviving node sequence; use that sequence when serializing/rebuilding
the scheduler. Other Jimmy/Goddard helper identities, construction-time nested
spawns and later runtime appends still need an explicit registry trace before
claiming the complete list or all-level ordering is recovered.
+99
View File
@@ -0,0 +1,99 @@
# C3/C7: old level-game deletion is restored by ordinary initialization
Static source recovery,2026-10-25. Original Neutron.exe SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Preferred VAs below are EXE addresses. Their physical offsets are VA−400000;
the read-only helper independently uses PE section mapping and emits both.
No original was modified or executed. No modern runtime code was edited here.
## Resolved distinction: stored defaults versus live state
The prior loader report correctly found the lab class-default initializer's
virtual204(0) at44D472, but that writes **live interface+139 only**. The
constructor-reachable class-default stage is not the final lifetime state.
The normal initialization pass subsequently restores live state from a separate
stored field, **interface+11**. This resolves the apparent preserved-old-game
contradiction without inferring destruction from overwriting509948.
| Stage | Original instruction / function | Effect |
|---|---|---|
| Generic constructor |46FDB3 pushes1;46FDB7 →470F40 | Setter writes stored+11 and dispatches204 to set live+139 |
| Class defaults |44D456 pushes0;44D472 invokes204 | Live+139 becomes0, stored+11 remains1 |
| Normal per-object initialization |46E5C3 invokes slot28 | Lab/tutorial/outside game slot28 is44D4E0 |
| Game base initialization |44D4E0 jumps4587F0;4587F3 calls470540 | Enters the common initialization bridge |
| Restore effective lifecycle state |4705B3 invokes8C getter470F30, pushes result4705B9,4705BC invokes204 setter4719C0 | Reads stored+11 and writes live+139 |
| PostLoad |46E61A invokes40C after28 for each object | Game has already restored its ordinary live teardown predicate1 |
| Ordinary departure |46E032/46E06F/46E0AC call200 getter4719B0 | Getter reads live+139; game qualifies for all three teardown passes |
This common initializer also copies other stored/editor configuration fields to
live fields. Do not generalize every corresponding field as persisted gameplay
state: the +11→+139 bridge is specifically proven here.
Route game interface tables:
- Lab4C386C, tutorial VR04 4CE4AC, outside4C561C all resolve28→44D4E0,
8C→470F30 and204→4719C0.
- 470F30 reads byte[interface+11].4719C0 writes byte[interface+139] from its
argument.4719B0 reads that live field for the teardown predicate.
- The usual game interface is complete+8C for level-game objects, unlike Jimmy's
complete+C0. Pointer bases must remain explicit.
## Actual deletion and registry removal
For initialized old level games with live+139=1, ordinary transition46DFF0:
1. Calls slot20 in the first filtered traversal at46E054.
2. Calls slot34 in the second filtered traversal at46E091.
3. Sets interface+6=1 in the third traversal at46E0CA.
4. Calls473710 at46E0D9. That sweep finds marked objects, invokes interface
slot0 with argument1 at473733..737, then restarts the global list scan.
Lab slot0 at4C386C points44F610: subtract5C converts game interface+8C to the
destructor's complete+30 subobject, then jumps44F3F0. That scalar deleting
wrapper calls44F420; its base call44F499→44D390 jumps44D3C2→4746E0.
The game destructor calls4587E0 at47476A with its game interface, and4587E0
jumps470060, the common interface destructor.
The common destructor explicitly scans registry50999C at4700E5, matches the
dying interface against node+8 at4700F2, and erases matching nodes using
469490 at470106 with list object509998. This is the actual old-game registry
removal edge. It precedes allocation/registration of the destination game in
46E170. Existing current-game pointer509948 can temporarily refer to the old
object during teardown; destination construction overwrites it later, but that
overwrite is not the operation responsible for deletion.
There is no need to model accumulating old level-game input callbacks for the
normal route: the initialized live flag selects ordinary deletion. Abnormal
paths that bypass normal Init or mutate the stored/live flags require separate
evidence and are outside this successful-load case.
## Why Jimmy and Goddard differ
Jimmy4226B5..BF and Goddard41C99B..9E invoke470F40 with0. Unlike the game's
class-default virtual204(0), this updates **both** stored+11 and live+139.
Common Init therefore restores0 for these retained characters, and their
positive reusable+9 fields allow GAM/object lookup reuse without re-appending
their nodes. Those constructor values, their reuse flag and any later field
resets are separate concepts.
Fresh lab order game→Jimmy→fire remains proven by lab-registry.md. On a
successful later ordinary load the old game is deleted, retained nodes keep
their order, and the new game is appended afterward. Thus relative input versus
Jimmy order can differ from fresh construction. Complete retained helper-node
and per-field reset coverage is still needed before claiming all callback
ordering or all transition state is recovered.
## Verification and implementation consequence
`checkpoint_level_game_lifetime.py ../Original` checks the binary identity,
decisive stored/live flag, initialization, teardown and destructor/unlink bytes,
plus route vtable targets. Its tests guard the actual source contract rather
than a speculative lifecycle simulation. This is static evidence, not observed
original gameplay.
The normal old-level-game removal gate is now closed. C3 can preserve retained
object insertion order while deleting/replacing the level-game callback owner,
instead of freezing fresh game-before-Jimmy order for every transition. Keep
the port's application-owned window/Vulkan session as the authorized modern
presentation policy. Remaining source gates are per-field character/helper
reset rules, exact timer/event-pump behavior and original runtime comparison.
+113
View File
@@ -0,0 +1,113 @@
# Main loop, input, motion and animation
Static recovery from supplied Neutron.exe (SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`) and
OMT2.dll (`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`).
Investigated independently, integrated and byte-checked by primary. No original
whole-game runtime comparison. `checkpoint_loop_motion.py` reports PE-mapped
file offsets and verifies decisive calls/vtable anchors. For the EXE anchors below,
file offset is VA minus400000; do not apply that shortcut to DLL addresses.
## Recovered loop and ownership
| Boundary / owner | Original evidence | Interaction |
|---|---|---|
| Application pump | EXE4802F2 CRT →4789B0 WinMain →46A4A0 bootstrap; DLL100218A0 application start →10060720 devote_time | Engine periodicals own dispatch; not an established60Hz game loop |
| Engine animation periodical | DLL100215C0 emits -604 logic and -605 animation/render; world100F9B10 →100F9C80, world+48 timer and pause/min/max periods | Engine logic and game render callback are separate timing paths; exact interleaving needs trace |
| Game frame entry | EXE47E374 (file7E374) assigns viewport vtable4D74C4; slot+B8 at4D757C points to47E4F0 | This is a viewport render override, not an ordinary world logic tick |
| Frame time | 47E4FC virtual+D4;47E502 stores float seconds696030; guards47E508..52A accept0<dt<1; QPC reset47E470/elapsed47E490 | No source fixed1/60 accumulator recovered; do not choose original cadence from port tests |
| Conditional first passes | 47E554 →479BC0 physics;47E560 →462A20 transient pass;47E56B →4693A0 frame-list pass | All three require475CA0 true, supervisor509980 nonnull and supervisor+8C clear |
| Remaining passes |47E57A →47D8F0 sound;47E582 →473740 objects;47E587 →473770 transform sync;47E6B1 →477DB0 | These calls are outside that first-pass gate but inside valid-dt branch |
| Draw and post-draw |47E6DF imports viewport render via IAT48D304;47E6E5 →468600;47E6EF increments696028 | Draw occurs after game update/sync; invalid dt skips game passes but still reaches base render |
The object registry is a circular doubly linked list at50999C. Node layout:
next+0, previous+4, game-interface payload+8; allocation12 bytes at46FF50.
Constructor46FF4A..46FF7F appends to tail. Thus473740 walks construction/insertion
order, not grouped actor types. It invokes payload.vtable+10 at473758, then
reads next at47375B: appends during a callback can be visited in that same pass.
Deletion/reentrancy safety is not fully recovered.
Common slot10 wrapper470280 stores dt at interface+294 and invokes slot3C4 in
normal mode (4702C5), slot3C8 when supervisor+8C is set (4702B5).
Jimmy's3C4 is424600; movement path437940 executes during that object update.
Physics479BC0 has already consumed the existing body state. This establishes
prior-velocity/prior-impulse integration before the current controller computes
new motion. It does not alone establish the complete input/engine interleaving.
473770 is a second whole-list traversal invoking interface3DC then3E0. Jimmy
3DC4624B0 gets logical position through slot310 and writes interface-7C/-78/-74
(complete object+44/+48/+4C). Slot3E04624F0 →473540 synchronizes Euler angles.
Many objects expose multiple inheritance interfaces: the usual game interface
is complete+0xC0. Label every field by its pointer base; never merge equal-looking
offsets from unrelated interfaces.
## Input, controller and physics boundaries
Input arrives through game update44DF80 →475A70;475A9C reads controlled pointer
5099E4, null skips dispatch;475AA9 invokes its slot3CC (Jimmy426030).
Follow-up [input-frame-bridge.md](input-frame-bridge.md) proves44DF80 itself is a
normal registry3C4 callback on the level game interface (complete+8C). Thus input
is inside473740 after physics, distinct from Jimmy's own424600 callback but not
an independent world-logic tick. The game's OMT3C callback4747A0 only forwards to
base element no-op. SDL sampling/fixed ticks remain implementation policy.
Previously recovered detailed arithmetic remains in `analysis/jetpack.md`,
`analysis/original-collision.md`, `analysis/dynamic-collision.md` and
`analysis/patrol.md`:
- Jimmy movement437940/437F90 and air fall-through439900 own speed/turn/jump state.
Mode1 does reach airborne steering; the old binary report's “no action” label is
superseded. Grounded/released clears interface+614 (complete+6D4).
-479BC0 visits bodies;479D20/479EBB..479EF2 consumes queued impulse once,
then acceleration/gravity and displacement479F8D. This is a per-body algorithm,
not proof of the port's surrounding controller order.
- Jetpack controller437F90 and effect421FB0 have distinct owners. Timers,
state0..5, radius100/60, impulse550, hold>.4,8s burst and.5/s energy drain
are narrowly recovered. Registry insertion order of Jimmy/effect must be traced
before deciding same-frame vs next-frame effect expiry and impulse application.
- Source support/ray/magnitude and dynamic box broadphase have byte/DLL evidence.
Static response47BD80, stairs, all body masks and contact side effects remain
incomplete. NC shape exclusion is a recovered registration gate, not a water fix.
## Animation
There is a separate OMT logic/morph path: EXE462260 forwards its argument through
IAT48D244 to OMT morph update10002DB0. Common logical/visual transforms are copied
by the later registry sync. Morph interpolation is recovered at DLL10002F9A;
original mode2 probes for tested standing/jump clips return zero dynamic-point
offsets. These probes do not establish full animation scheduling or collision pose.
Port `MorphAnimation` samples extracted ASE timing with linear interpolation,
loops the final sample to first unconditionally, and rejects irregular samples.
`PreviewAnimationLibrary` chooses from pose/action aliases; Program resets poseTime
on clip change and adds1/60 every port tick. Actor visuals likewise run after the
grouped gameplay passes. Playback-end callbacks, one-shot vs looping flags,
class-specific speed, state transitions and interrupt rules remain unresolved.
## Baseline comparison and verification
Baseline69d0187 runs `LabSimulation.Step` controller → physics → jetpack effect →
camera, then contacts/mechanisms → patrols → director → objective timer → animation.
This contradicts the recovered physics-before-object-update contract and replaces
construction-order callbacks with subsystem groups. A global reorder now would
invent ordering for spawned effects, scripts and NPCs. First build a lab registry
and phase trace and assert source contracts; only then split simulation phases.
The helper and Python regression verify exact original bytes/call order; managed
tests verify port arithmetic and deterministic route outcomes. Neither proves source
cadence, input latency or original end-to-end gameplay. Keep both traces separate.
## Explicit unresolved questions / next work
1. Input bridge is resolved: registry3C4→44DF80 after physics. Exact event-pump,
pause/focus/invalid-dt/multiple-viewport behavior remains open. Engine world
timer is milliseconds, default mode1/min1/max500, distinct from QPC game seconds;
see the follow-up before interpreting the40ms period or choosing a cadence.
2. Capture lab construction registry including Goddard, jetpack effect, transient
objects and deletions; identify462A20/4693A0/477DB0 dependencies precisely.
3. Recover47BD80 response, Jimmy body/root/capsule relationship and source contact
ordering before replacing provisional feet grounding/sweep-slide collision.
4. Trace morph flags/end events and class animation selection, including cutscene
exit, jump→fall→land and jetpack state/energy transitions.
5. Probe isolated source components where possible; full original timing remains
unverified until a usable original runtime exists. Do not use nominal60Hz as fact.
+190
View File
@@ -0,0 +1,190 @@
# Next work plan: recover interactions, then implement verified changes
2026-11-05. Proposed execution order following the user's request for a plan.
Gameplay expansion remains paused. Current research checkpoint68154df preserves
runtime a2e89c6 and packaged runtime dae13ac. This plan does not mark the remaining
post-skip tilt fixed or authorize an unsupported rotation reset.
Execution update2026-11-06: [integrated lifecycle findings](../gameplay/jimmy-cutscene-lifecycle.md)
add292 bounded original-code cases, complete DEFAULT recovery and a working
read-only copied-original observer. Steps1–2 remain open at the actual original
Carl entry/resumed-frame observation. Step3 has not begun; source composition
agrees with the port's stale writer under the same synthetic order/state.
Later execution update: [menu/player lifetime](../gameplay/main-menu-player-lifetime.md)
closes the successful TSK story path's source ordering gate. MAIN loads a background
Level1D/Jimmy; successful TSK load uses that controlled Jimmy and the ordinary
retained-object loader. Program's first-story classification is corrected without
another angle reset. Step3's first-neutral-tick/300-idle Vulkan and eight managed
trajectories pass. Integrated/native SDL checks and clean ea04210 packages now
pass, including4 identical standalone Linux readbacks and a preliminary isolated
Wine64 Carl replay. All539 originals remain unchanged. Original
Windows comparison remains a step5 obligation, not a completed claim. Step4's
derived-caller/body-transform investigation is also recorded, with broader
dynamic/special contacts and playback dependencies still open.
Step4 continuation: [ordered pair lifecycle](pair-lifecycle.md) now has28 complete
original/C# comparisons,6 new REA pseudocode results and20 guarded VR04 class
bindings. The pair component is verified separately; scene admission remains
gated on full physical registration/activation, real callbacks and shared reclip.
Registration continuation now covers all72 serialized VR04 records/13 interfaces
and12 original registration/loader cases, plus21 guarded helper edges. This closes
the bounded common registration and per-object loader contracts, not complete
fresh/retained helper membership. See [registration](physical-registration.md).
Next resolve helper re-entry/deletion/activation and dynamic shared reclip state;
keep live scene admission unchanged until those dependencies close.
2026-11-07 continuation: [dynamic context](dynamic-context.md) executes17 original
mode2/reclip cases and captures12 kernel triangle/normal arguments. Test-only C#
composition matches complete snapshots, including retained old polygon and
callback publication. Jeep default deletion eligibility is guarded, while cleanup
mutations/children/order remain open. Next extend to nonempty static reclip and
ordered-body context, then real actor callbacks and retained helper cleanup.
Keep the current live solver and924ad2f packages while those gates remain.
Populated follow-up: [dynamic reclip](dynamic-reclip.md) now matches14 complete
observations and12 kernel steps. Direct source-store corrections remove two
rounding divergences without admitting new actors. Next prioritize real Jimmy/
VR04 callback mutations and live getter timing, then constructor-only helper
cleanup/order across LOAD/RETURN; integrate the bounded response only afterward.
Actor continuation: [normal contacts](actor-normal-contacts.md) now compares30
complete snapshots and implements inherited ceiling/reflection/heading impulse
outside live wiring. Jimmy ordinary374 is separate; soldier mode10's174 policy
and helper lifetime remain unresolved. Post-callback radius/inhibition/geometry/
42C reads are explicit contracts, not constructor snapshots. Next close derived
response and retained helper activation/order before a supported response adapter.
## Objective
Establish the original ownership and timing of player state across gameplay,
contact, cutscenes, landing and level return, then correct the port in small,
verified chunks. Start with the concrete reported failure: jump while banked,
enter Carl's lab conversation, skip, release controls, remain upright afterward.
Ordinary landing bank must remain faithful to the original, as the user confirmed.
## 1. Close the original Carl skip-to-idle sequence
Trace the actual supplied route: physical contact → Carl talk activation →
neutron1a activation → accepted skip → Carlwalk → DEFAULT → first idle input
and player update. Follow direct callers, virtual targets and registry positions
through REA, checking the authoritative bytes and GAM records.
Record support, raw control owner, movement mode, stored turn, current Euler,
destination Euler, dirty flag, skip state, action latch, input suppression and
frame delta at every boundary. Include contact/support state before entry: the
port's grouped contacts might start the scene with different retained state.
Investigate the concrete remaining gaps: skip input-latch consumption and release,
per-camera completion order, same-frame control changes, and fresh/retained actor
ordering. Reuse the three new pseudocode results and existing instruction Evidence.
Keep the unresolved DEFAULT procedure boundary explicit; use its guarded assembly
and a changed analysis strategy where necessary rather than repeat failed queries.
**Deliverable:** an annotated original event/state trace and a clear explanation
of where the original prevents the stale airborne bank from being republished.
A local no-reset result or another plausible hypothesis does not close this gate.
## 2. Compare the original sequence with the reproducible port failure
Extend the existing48-case diagnostic around the original boundaries. Use an
isolated original-code composition with explicit synthetic dependencies and/or
an original-game runtime capture from a generated copy where the available
runtime supports it. Record limitations, including any callbacks not executed.
Compare fresh and retained ordering; grounded and airborne entry; Left/Right
bank; neutral and held input; Escape/Space skip and natural completion. Natural
completion is a separate comparison—the user's confirmed failure concerns skip.
Keep source viewport seconds, morph/engine timing and the port's60Hz policy
explicit rather than assuming they share one clock.
**Deliverable:** a differential trace naming the first meaningful divergence,
its owner and its consequences. Expected outcomes must agree with original
instructions/composition and the user's observation. If they conflict, specify
the exact missing observation before changing gameplay.
## 3. Implement the supported cutscene correction
Resume runtime work once steps1–2 establish the missing transition or ordering.
Change the smallest coherent owner/lifecycle boundary, retaining the existing
playable movement baseline. Preserve normal landing bank, heading, queued body
work and the separately recovered fire/control lifecycles.
Convert the reported skipped-Carl/neutral-return scenario into a regression that
fails on the current baseline. Cover the first resumed frame and sustained idle,
both insertion orders, natural completion, held-input return, and repeated scenes.
**Done when:** the source explanation and implementation agree; Jimmy remains
upright after skipping Carl; legitimate landing bank remains; targeted movement,
Director, jetpack and visual checks pass. State any remaining approximation.
## 4. Deepen the remaining movement interaction contracts
After closing Carl's lifecycle, prioritize the existing core-system gaps:
1. **Body/contact ownership:** real Jimmy callbacks, dynamic pair eligibility,
support admission, callback-mutated root/modes and successful fence/ladder or
hazard paths. Preserve the lab/outside capsule until its replacement gate closes.
2. **Animation lifecycle:** original action acceptance, playback clocks, completion
callbacks and interruption across jump, land, STOP, talk, skip and control return.
3. **Shared camera/input state:** final scripted eye, first resumed follow update,
clipping, pause/menu/input gates and retained scene ordering.
Use each recovered transition to update the coverage map and remove a named
assumption. Existing original arithmetic fixtures remain regression evidence;
JN-Engine supplies original-decompiler leads, not replacement movement tuning.
**Deliverable:** per-system state/ownership contracts with addresses, file offsets,
callers, dependencies, confidence and unresolved questions, plus bounded source
probes where needed. Implement each supported correction as its own verified chunk.
## 5. Validate the route as one interacting system
Exercise lab → VR04 → lab → outside with fresh entry and RETURN. Include normal
and skipped conversations, banked jumps, landing/idle, jetpack cleanup, held input,
objectives, music/speech, camera handoff and persistent/reset state.
Run targeted checks for each change and the full suite at the integrated route
checkpoint. Validate native Linux SDL/Vulkan, then obtain native Windows build
feedback for the same scenarios. Compare original behavior where observed;
managed tests, original components, Linux rendering and Windows execution remain
separate evidence categories.
**Done when:** the route and reported bug pass the defined scenarios, original
hashes remain unchanged, platform results/limits are recorded, and both packages
identify a clean verified runtime commit. Push source/tools/docs to the approved
Gitea remote; keep originals, generated traces and packages local.
## 6. Choose the next reconstruction checkpoint from the updated coverage map
Once movement and route handoffs are stable, rank the remaining audio/music,
UI, progression/save-load and actor/AI gaps by how much existing gameplay they
block. Recover and implement them in that dependency order. New gadgets and
level-specific features stay behind the core movement/route checkpoint.
**Deliverable:** a short next-chunk plan based on measured gaps, with a concrete
source question, implementation boundary and validation condition for each item.
Do not require understanding every level before executing a supported core change.
## Parallel work and ownership
Use two independent investigators when the questions are substantial:
- Original input/skip/state ownership: jimmy-cutscene-return source report and
its named binary analysis helpers.
- Contact/registry/script ordering: jimmy-cutscene-chain-order source report and
its named binary analysis helpers.
Primary owns the port diagnostic, integrated trace, coverage/status documents,
runtime/test integration and commits. Establish exclusive ownership before work;
review shared conclusions before editing gameplay. No investigator changes
another's files or commits shared work.
## Checkpoint discipline
Every checkpoint reports recovered facts, inference, current implementation,
verification and open questions separately. Save Evidence/probe identities and
findings on disk. Commit and push completed, verified milestones. Gameplay work
remains paused until the Carl source/differential gate above is satisfied; this
plan itself introduces no gameplay or package changes.
+172
View File
@@ -0,0 +1,172 @@
# Physical pair ordering and contact lifecycle
2026-11-06. Continues step4 of the movement plan after the Carl story-entry fix.
This closes a bounded pair-dispatch contract. It does not admit new live scene
physics, implement special Jimmy terrain callbacks or establish whole-game fidelity.
## Recovered source and structures
Canonical Neutron.exe SHA256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
`tools/binary/pair_lifecycle.py` guards8 complete source ranges and20 virtual
bindings, records PE file offsets and retains the matching original instruction
Evidence `ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`.
The generated probe relocates11 explicit absolute operands in private memory.
The supplied originals are read only; the executable entry point is not invoked.
New local REA/Ghidra pseudocode Evidence:
| Original VA / file offset | Role | Evidence ID suffix (all prefixed `ev_`) |
|---|---|---|
|479BC0 /79BC0|Physics scheduler; nonzero seconds, body pass then pair pass|56b7e074ec8509d1c5b3576d02361ff051963b777d7ccb8259ed9c65dc2db52f|
|47A430 /7A430|Ordered pair eligibility and notifications|8756a4c51d0c9215d3a36b86b673a2529bf74ed86bb9dcf630f66cbc398259b3|
|47B3E0 /7B3E0|Strict root-sphere overlap and callbacks|b98a1806c11507d5105d6fb22e259efafd141fe3c862eb4bb6602468a93a658d|
|47CA90 /7CA90|Earlier body's exclusion list|3f2613369c1259cba7aadfc00b7383dbf7bd37def7085f003daf81802dddbc4e|
|470B20 /70B20|Base leave, optional wake, contact removal|ae39adff84ac253cd370a2fd3f04ee7e9c00a6a6210d4f0222e938103a114d72|
|470BC0 /70BC0|Base stay/game callback cache|c3f377c29e0818cb43ed7bcc58d4db3871ab34d1b54c329421591438b79f0d00|
Complete replies/export and closed snapshot: `artifacts/pair-lifecycle/rea/`.
Ghidra did not recognize470A60/470BF0 as requested procedures; error replies are
retained. Its47B3E0 pseudocode misidentifies the first argument as a return-address
value. Calling convention, stack arguments and the omitted leaf bodies therefore
use guarded instructions plus actual copied-code execution, not that pseudocode.
No repeated query is presented as successful decompilation of those two leaves.
The physical list at695D3C is a circular sentinel list of12-byte nodes:
next+0, previous+4, game-interface pointer+8. This differs from the ordinary update
registry50999C. Re-registration and repeated Init are documented separately in
[body registration](body-root-registration.md).
Each actor owns contact-list sentinel pointer+260/count+264 and exclusion-list
sentinel pointer+254. These are interface-relative fields, not radius slot260.
Base contact game-callback result caches are+408 enter,+40C stay,+410 leave.
## State transitions and ordering
- Viewport47E554 calls479BC0 before ordinary registry updates. Nonzero delta and
global4F69E7 admit body integration479D20 followed by47A430. Pair global4F69E4
gates the latter independently; raw control5099E4 is not queried here.
- 47A430 traverses each earlier physical node against itself and subsequent nodes.
Identical actor pointers are skipped, with no reverse pair traversal. A duplicate
physical node can cause another test of the same actor pair; it is not deduplicated.
- Own220 is sampled once at the outer boundary; each inner actor's220 is read
again. Mutual3A0 permissions follow. Rejected flags/permissions skip the pair
**without removing stored contacts or emitting leave**. An outer actor disabled
by its first enter callback can still contact later actors in that traversal.
- First actor mode178=2 selects47A5E0(first,second); otherwise second mode2
selects47A5E0(second,first). Both mode2 preserves first-first selection. Other
modes use47B3E0(first,second). Box geometry is a distinct contract.
- Sphere query reads second root, first root, both radii and quick_magnitude.
Contact requires strict distance<radius sum. Tangency is separation.47CA90
checks **only the earlier actor's exclusion list**, after the distance test;
the later actor's exclusions are not consulted by this sphere query.
- Successful sphere query invokes first4C then second4C before notifications,
retaining the computed distance/result. A response may change a live root;
the current pair still notifies, while later pairs read the changed root.
- Each side independently queries membership3C. Positive overlap gives enter40
when absent, stay48 when present; separation gives leave44 only when present.
The first notification can alter the second side's membership before its query.
- Actual470A90 adds a contact unless already present or own deletion byte+6 is set.
Actual470B20 optionally restores live integration214 when own210 is false and
authoredB4 true, then removes matching nodes.470BC0 does not change membership.
These base routines can request current-game callbacks when their cache is−1.
- 470BF0 uses the **other** actor's1E0 inhibition flag. If clear, own integration210
permits414 response; a separate own1F8 branch may call60. Sleeping bodies can
still enter/stay contact. The probe leaves1F8 false; full response60 remains open.
## Original component execution and C# comparison
The native probe executes the complete pair pass, sphere/exclusion queries and
base membership/enter/stay/leave/overlap routines in a hash-verified generated
copy. Quick magnitude uses the copied OMT DLL export. Actors, vtables, permission
getters, response414 mutations, allocation/free and box query results are explicit
fixture adapters. No real Jimmy constructor, actor AI/contact consumer, static
world reclip, original renderer or scene loader executes.
All28 cases pass under isolated Wine32 with no network or Original-directory mount.
Cases cover enter/stay/tangency/leave/reentry, wake-on-leave, earlier/later/reordered
exclusions, gate retention, three-actor order, callback root/flag/membership changes,
duplicate identity, response inhibition, sleeping bodies and mode2 dispatch.
Initial12s capture expired during prefix creation; a reused scalar-only prefix
could not load OMT (error126, missing Wine DLLs). Both failures are retained.
The successful run uses a copied initialized OMT-capable prefix; it is component
evidence, not native Windows or whole-original gameplay verification.
`OriginalPairCollision` now translates the ordered pass and sphere query with
live actor callbacks and explicit mode2 injection. It is intentionally **not
wired into SceneInteractions or LabSimulation**. A stable physical list is required;
callback insertion/removal of list nodes is not yet reproduced by this component.
Base actor callback implementation remains the consumer's responsibility.
`GamePort.PairLifecycleTests` compares all28 native callback traces, contact masks,
integration/enabled flags and root-X snapshots. Fixed copies of those finite
expectations also run without generated artifacts. All28 complete comparisons pass.
The fixture's synthetic base-callback behavior is not a complete actor implementation.
The optional test rejects mode2 without an explicit solver instead of substituting
the provisional capsule. Existing lookup-table/x87 precision limitations remain;
these sphere fixtures use axis distances, not a proof of all boundary arithmetic.
Reproduce locally:
```sh
python3 tools/binary/pair_lifecycle.py ../Original \
--output artifacts/pair-lifecycle/native \
--rea artifacts/jimmy-movement-audit/rea-original-disassembly.json
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wno-unused-function \
-o artifacts/pair-lifecycle/native/probe.exe \
artifacts/pair-lifecycle/native/pair_lifecycle_probe.c
python3 tools/recon/reference_capture.py --asset-probe \
--probe-executable artifacts/pair-lifecycle/native/probe.exe \
--probe-success PAIR_LIFECYCLE_COMPLETE --seconds 12 \
--output artifacts/pair-lifecycle/probe
python3 tools/binary/pair_lifecycle.py ../Original \
--output artifacts/pair-lifecycle/native --capture artifacts/pair-lifecycle/probe
source scripts/env.sh
dotnet run --project tests/GamePort.PairLifecycleTests -- \
--native artifacts/pair-lifecycle/native/observations.json
```
Use an initialized OMT-capable generated Wine32 prefix for the12s capture.
`source.json` records identities/ranges/bindings; `observations.json` hashes the
capture, executable and generated source. The capture verifier checks EXE/DLL copy
hashes and observed probe identity. All generated evidence remains local.
## Integration and package verification
All338 Python tests pass, including2 new source/corpus checks. The28-case native
comparison and saved-reference replay pass; existing10 dynamic collision groups,
body-ownership and Director regressions pass. Debug build has zero warnings/errors.
Windows x64 cross-publish succeeds; its initial normal restore reports NU1900 for
unavailable vulnerability metadata. Clean packaging disables that metadata query.
Both packages identify clean source commit924ad2f67b5a2c3c90856366b0642c12da56d59e.
Each contains519 byte-identical original copies,4285 matching prepared scene files
and7 matching prepared audio files; DLLs match the corresponding publish outputs.
Standalone Linux from /tmp without SDK/development-library paths passes Carl first
neutral input/300 idle ticks/held-input return. All4 captures match the previous
ea04210 package exactly. This run disables optional Vulkan validation; prior
enabled-validation evidence remains separate. No new Windows runtime or whole-
original gameplay result is inferred. All539 originals remain unchanged.
Logs and hashes: artifacts/pair-lifecycle/validation.json, package-identity.json,
package-readbacks.json and package-control.log.
## VR04 eligibility coverage and next gate
Actual VR04 GAM contains Jimmy, Rocketship,3 YokianSoldiers and trophy among its
records. Their4 class game tables bind220→471A30, mode178→471720,
permission3A0→472F80 (unconditional true), overlap4C→470BF0 and210→4719F0.
The3 soldier records explicitly request HasCollision1. Guard output retains their
GAM offsets, tags, task/activation fields and20 common bindings. This removes any
basis for treating their class permission callback as a blanket exclusion.
It does **not** establish the complete physical list: other GAM classes, generated
children/helpers, task activation, constructors, exclusions, registration and live
flags still matter. Visibility and raw-control ownership cannot substitute for
that inventory. SceneInteractions currently groups selected player contacts after
player processing; its single contact set, active/control gates and immediate talk
dispatch are still approximations of these independent owners/phases.
Next: trace actual VR04 physical registration/activation and generated children,
then recover shared nearest/last-polygon dynamic reclip ownership. Recover real
Jimmy material160/164/FENCE/LADDER callbacks and persistent body/animation state
before enabling source physics in lab/outside. Keep ea04210 readbacks as the
comparison baseline; current clean924ad2f packages preserve that live route.
+138
View File
@@ -0,0 +1,138 @@
# VR04 physical registration and initialization boundaries
2026-11-06. Extends the existing [registration trace](body-root-registration.md)
and [pair contract](pair-lifecycle.md) with complete serialized-class coverage and
12 executed original-component cases. No runtime gameplay code or scene admission
changes in this checkpoint. The playable/package baseline remains924ad2f.
## Identity and evidence
Canonical Neutron.exe SHA256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
`physical_registration.py` verifies that identity,6 bounded source hashes,
13 RTTI interface identities,11 own-registration sites and78 method bindings.
It inventories every one of VR04's72 records with source GAM offsets/activation
fields. Original instruction Evidence is
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`;
bounded extracts, offsets, hashes and10 private-memory relocation operands are
retained in artifacts/physical-registration/native/source.json.
New local REA/Ghidra results:
- 464210 sprite bridge:
`ev_4d39cc1aaad564de60bb801c08dfeb740d52e507227e630de9b0570e3e1bc43d`.
- 436B80 derived AI/pickup gate:
`ev_95baf27f6c5f2949dcc5f03f77f3c45bcd14852595b0cc207b9ee27c1dbb02f9`.
Requests for46E570,40E1F0 and45F2B0 had no recognized procedure in this analysis;
complete errors are retained. Their instructions remain available in the earlier
full REA disassembly. No retry is counted as successful decompilation. Successful
results/export and closed snapshot are in artifacts/physical-registration/rea/.
The prior4623D0/458910/479A40 Evidence remains linked in body-root-registration.md.
## What registration actually owns
| VA / PE file offset | Recovered behavior |
|---|---|
|4623D0 /623D0|3D-object interface at complete+C0. Calls458910; copies current complete44/48/4C through16C; converts signed14-bit Euler fields through174; calls479A40.|
|464210 /64210|Sprite interface at complete+C8. Same registration shape with the corresponding−84/−80/−7C render-root offsets; converts Euler units by360/16384; calls479A40.|
|458910 /58910|Tests interface49E. When false invokes470A00 and sets49E=true. This gates the base hook, **not the later append in either bridge**.|
|470A00 /70A00|Logging hook ending at472970; it does not allocate a physical body node. This corrects an earlier allocation label.|
|479A40 /79A40|Calls own150(0,0,0), then own28 Init, then allocates/appends a12-byte physical node and increments695D40. The payload is the game-interface pointer. No identity deduplication or pair/integration gate occurs here.|
|42AB50 /2AB50|Jimmy/Rocketship outer49E guard: true returns; false jumps to4623D0. This is a distinct guard around the whole registration path.|
|46E570..46E69F /6E570..6E69F|Live registry traversal: own28 Init, attached-render handling, own40C PostLoad, attached-render handling, next node. Then app10C cleanup and47E470 timer reset.|
The physical list695D3C and ordinary registry50999C have separate ownership.
Common registration reads the current render transform, which is not a promise
that authored GAM properties have already been streamed. Constructor registration
can precede that streaming; later Init/PostLoad work owns later state publication.
The12-case copied-code probe establishes:
- Repeated direct4623D0 or464210 calls append the same interface again, repeating
transform/zero/Init callbacks even with49E already true. This is a function
contract, not evidence that every real actor naturally acquires duplicate nodes.
- Jimmy's guarded entry skips all that work when49E is set. Clearing49E admits
another append. Clearing a flag is not equivalent to clearing the list.
- A child registered from the supplied Init callback is appended before its
parent's append, because479A40 calls Init before allocating the parent's node.
The child callback is synthetic; no claim is made that all real Init methods do so.
- Pair flag140 and integration13E false do not prevent registration. Membership,
active integration and pair eligibility must stay independent.
- The previously recovered per-object Init/PostLoad order is confirmed by actual
46E570 execution. Nodes appended from either callback are visited later in that
same traversal. A snapshot/two-global-pass model would differ in these fixtures.
## All serialized VR04 classes
The following is a source inventory of **own registration sites**, not a complete
runtime body count. Constructor rows assume that constructor is actually invoked
and succeeds; reuse, nested helpers, later calls and scene state remain separate.
| GAM kind / records | Actual interface | Own registration site / phase |
|---|---|---|
|3JIM /1|C3DJimmy4A373C, complete+C0|4238B4 virtual2C during matching-start PostLoad; guarded42AB50|
|3ROC /1|C3DRocketShip4B25AC, complete+C0|43DB22 virtual2C in PostLoad; guarded42AB50|
|STRT /1|C3DStartPoint4B7654, complete+C8|Constructor44249D→464210|
|3PHO /2|C3DPhoneBooth4ADF6C, complete+C0|Constructor4356A0→4623D0|
|3PAT /34|C3DPatrolPoint4ACEE4, complete+C8|Constructor434D44→464210|
|3PIC /11|C3DPickupItem4AE548, complete+C8|Constructor435A37→464210|
|3SOL /3|C3DYokianSoldier4C19C4, complete+C0|Constructor44BFA4→4623D0|
|3TRO /1|C3DVRTrophy4BE404, complete+C0|Constructor448D33→4623D0|
|3AIT /2|C3DAITrigger48F8C0, complete+C8|Constructor40BE5B→464210|
|3CHK /1|C3DCheckPoint4959A8, complete+C8|Constructor414323→464210|
|LOAD /2|CLoadLevel4D025C, complete+C8|Constructor457CCA→464210|
|3CAM /12|C3DCutSceneCamera497BFC, complete+C8|No own registration call in the inspected constructor/base/PostLoad chain|
|3SM1 /1|C3DSmoke4B4F08, complete+C8|No own call in that chain; it creates a separately registered SmokePuff helper|
Thus57 serialized records map to own constructor sites,2 to PostLoad sites and13
to no own call in the inspected chain. These numbers partition records; they
are **not a claim of59 actual bodies**. All these interfaces expose InitPhysics,
including the two negative own-call classes. Having that method is insufficient
evidence that it is invoked.3CAM's class is the cutscene-camera subclass, not the
base C3DCamera. Source RTTI verifies the distinction.
Authored HasCollision/task/range values are retained per record. Generic activation
40E1F0, task callback40E340, pickup45F2B0 and derived436B80 have different ownership.
The recovered436B80 first calls40E340, then may hide an acquired optional pickup;
it does not establish an independent universal body-list removal policy. Current
live flags, deletion, exclusions and child activation still require tracing.
## Execution, reproduction and limits
`physical_registration_probe.c` executes copied4623D0/464210/458910/470A00/479A40,
42AB50 and46E570. Explicit adapters supply actor vtables/transforms, Init/PostLoad
callbacks, logging, allocation, app cleanup and timer. Render-presence byte8 is
false in loader fixtures, so attached-render branches are not exercised. No real
actor constructor, original game entry point, script/task world or renderer runs.
All12 cases verify full emitted callback/order/count/flag/Init/XYZ/Euler outputs
under isolated Wine32, with Original unmounted and network disabled. The helper
checks copied EXE hash, observed probe identity, exit0 and completion marker;
provenance and validated observations are retained locally. This is original
component execution, not native Windows or full original gameplay verification.
```sh
python3 tools/binary/physical_registration.py ../Original \
--output artifacts/physical-registration/native \
--rea artifacts/jimmy-movement-audit/rea-original-disassembly.json
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wno-unused-function \
-o artifacts/physical-registration/native/probe.exe \
artifacts/physical-registration/native/physical_registration_probe.c
python3 tools/recon/reference_capture.py --asset-probe \
--probe-executable artifacts/physical-registration/native/probe.exe \
--probe-success PHYSICAL_REGISTRATION_COMPLETE --seconds 12 \
--output artifacts/physical-registration/probe
python3 tools/binary/physical_registration.py ../Original \
--output artifacts/physical-registration/native --capture artifacts/physical-registration/probe
```
The short capture uses a copied initialized generated Wine32 prefix; this scalar
probe needs no OMT DLL load. No runtime implementation or package identity changes
follow from these observations alone. [Generated helpers](vr04-generated-bodies.md)
records21 verified creation/registration calls and the remaining lifetime gaps.
Next: close helper reuse/removal and activation enough to reconstruct the actual
physical sequence for fresh and retained VR04; then integrate dynamic response
with original nearest/last-polygon reclip ownership. Keep the playable collision
baseline and separate OriginalPairCollision component until that boundary closes.
@@ -0,0 +1,85 @@
# C3 implementation: player phase boundaries
The first implementation chunk separates the controlled player's prior-body
physics, game input, player controller, owned fire effect and camera-input update.
It does not replace the entire scene scheduler, collision response or animation
clock. Evidence is in `input-frame-bridge.md`, `lab-registry.md`, the new
`player_phase_evidence.py`, and the follow-up `level-game-lifetime.md`.
Continuation: `control-phase-implementation.md` now separates uncontrolled body/
fire from controlled movement, with source-specific preparation boundaries. The
older unresolved-control wording below describes this chunk's original boundary;
full wrapper/base/morph work and the scene scheduler still remain open.
## Source contract and implementation
EXE47E554 calls479BC0 physics before473740 game-object callbacks47E582;473770
sync follows47E587. A fresh game registers before Jimmy, and Jimmy before his
owned fire. Retained Jimmy/fire precede the newly appended destination game.
The level-game deletion predicate is restored by normal initialization; a
constructor-default zero is not the final gameplay lifetime flag. The focused
lifetime report records the complete vtable/field provenance.
`LabSimulation.Step` now integrates **existing** velocity, acceleration and queued
impulse first. Fresh input then produces speed/destination yaw, the player update
produces velocity/impulse for the next physics pass, and fire ticks afterward.
On scene continuation, the player/fire update precedes the destination input
callback. `InputAfterPlayerUpdate` records this specific retained registry relation;
it does not claim all source objects are retained by the current port.
Input uses the stored movement mode, as438B1E..438B2A does, rather than deriving
it from current physical support. Held jump selects air mode at437A96. Grounded
released-jump reset437B9E..437BAC clears jump state, mode and turn in the **player**
callback. Landing can therefore clear turn on the same frame physics finds support.
Jump queues impulse after physics and requests its pose; it does not retroactively
move the body or falsely clear its physical supported state that frame.
Source addresses above have EXE raw offsets VA−400000. The helper verifies the
hashed supplied EXE, maps PE offsets and checks9 decisive instruction sequences.
No original code was executed for these source assertions.
## Verification and remaining limits
Movement regressions assert old velocity before current input, one-time delayed
impulse consumption, fresh versus retained ordering, independent movement mode,
landing reset and unchanged fixed-step presentation independence. Input-only lab
navigation still reaches SCENE35→50→60 and the outside LOAD. This is port evidence,
not original timing/latency fidelity. Source nominal frame rate remains unproven;
the port keeps its explicit60Hz policy.
The existing capsule/gravity adapter remains. C4 follow-up corrects the earlier
support-hit interpretation: source479DF7..479E54 cancels gravity and clears
vertical velocity only when global geometry4F69E5 is disabled. It is not a
prior-grounded or support-hit branch. The isolated body probe confirms the normal
pending-jump fixture consumes550 impulse and applies both−264 acceleration and
−800 gravity, producing Vy532.266663 at dt1/60. See collision-body-probe.md.
No source-fidelity claim is made for jump apex, stairs, wall response or visual
pivot. The underground replay checks clearance of the recovered radius60 body,
not raw209-unit standing-mesh bounds, which are a separate provisional render
scale/pivot policy. Closed-gate collision and both directional crossings remain
required. This clarifies the physical assertion rather than inferring a collider
from the render mesh.
Other scene callbacks still run in subsystem groups. Uncontrolled player physics
and control-release body preparation need their own source trace before changing
cutscene behavior. Engine morph logic remains on the port animation clock. These
are explicit next scheduler boundaries, not claimed solved by this player chunk.
Bounded follow-up anchors for that next boundary (static reads, not implemented
here): Jimmy game vtable4A373C+410→42AFC0 calls43A750 at42AFC3.43A758 clears
speed interface608;43A76C calls2C4 with three zero arguments. That target471F40
writes interface1A4/1A8/1AC. Map this preparation to the body consumer before
changing uncontrolled physics or resumption. Slot438→42AE00 additionally calls
complete178→427FF0 and sets interface1D65/global4F8182. These callbacks belong
to CAM/MCA ownership transfer, rather than interpreting null control as a whole
world pause. Lateral input complete870 is written by walking input43915D/4391B1/
439226; its cross-mode lifetime is another scalar coupling to verify when filling
out the phase state model. The present chunk does not claim all controller fields.
Final verification: full scripts/test.sh passes, log
`artifacts/implementation/integration-final.log`;20 movement groups and the new
11 camera groups, existing support/interaction/route suites, all GPU replays with
zero enabled-validation errors, SDL dummy tests and539 original hashes unchanged.
The70 Python checks include the new mode/phase and lifecycle source anchors.
Baseline69d0187 and current240-step completed walks have essentially identical
travel/final position; within-frame producer/consumer timing is tested separately.
+162
View File
@@ -0,0 +1,162 @@
# Retained character resets: bounded C3/C7 contract
Static investigation,2026-10-25. Originals remain read-only and were not executed.
Neutron.exe SHA256 is
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
All code/vtable anchors below are preferred-base EXE VAs; PE-mapped raw file
offset is VA−400000 for these sites. The new helper prints both coordinates and
checks individual bytes, virtual targets and source route GAM properties.
This report distinguishes proven local resets from fields whose enclosing
retention/property/callback semantics remain unresolved. No runtime code changed.
## Superseding continuation (2026-10-26)
The bounded investigation below was an initial local-prefix audit. Its old claim
that VR04 finishes with jetpack state4 is incomplete: the full level-specific
PostLoad tail re-enables the practice gadget, so owned jetpack finishes state1.
LV1B additionally disables gadgets1/7. See retained-return-cleanup.md for all
VR01..08 tail calls. Runtime/tests now apply those complete tutorial/route rules.
Property callbacks and bounded scalar carry are closed by retained-streamer.md,
retained-player-body.md and retained-companion.md. Later sections preserve the
initial evidence and explicitly limited scope, not the current final-state claim.
## Enclosing ordinary-load phases
The common loader evidence remains `scene-loader.md`: selective teardown, GAM
factory/reuse/property stream, then registry per-object28 followed immediately
by40C. Jimmy/Goddard can survive and be reused; that alone does not imply every
field survives. Jimmy uses game-interface complete+C0; shadow uses complete+C8.
Keep constructor/default-class initialization separate from callbacks28/40C.
The object property read at46E3FD uses IAT48D190, imported
`OMediaStreamOperators::operator>>(OMediaClassStreamer*)`. Route JIM1 property
records contain authored position/rotation/flags/StartPoint and no serialized
jump/movement-mode/burn timer field. This is a statement about decoded records,
not proof the read implementation cannot indirectly invoke another callback.
Full streamer virtual call provenance is still a separate gate.
## Jimmy initialization: exact resets and a coordinate correction
Jimmy interface vtable4A373C+28→437890. It first calls4587F0 at437896;
4587F0→470540 applies generic authored/live-property setters, then calls
interface68(1). Jimmy-specific43789B..4378C1 then:
| Instruction / raw offset | Field and recovered effect |
|---|---|
|4378A1 /378A1|Clear interface608 = complete6C8 (movement speed in existing recovery)|
|4378A7 /378A7|Clear interface614 = complete6D4 (air turning accumulator)|
|4378AD /378AD|Clear interface618 = complete6D8; full semantic name unresolved here|
|4378B8 /378B8|Invoke interface328 =4723F0, the logical Euler-vector getter|
|4378BE..4378C1 /378BE..378C1|Copy that vector's Y into interface61C = complete6DC|
**Correction:** interface328 is not velocity.4723F0 copies interface224/228/
22C/230, the logical Euler vector (position is214/218/21C/220). Therefore the
earlier scene-loader wording “captures another velocity component” is stale.
The clear618/capture61C pair should remain unnamed or associated with yaw
tracking until its consumers are traced; do not carry it as vertical velocity.
Generic470540 additionally clears interface274/278/27C and298 at4709CA..9DC,
then sets byte5=1 and bytesA/6=0. This report does not name that vector as impulse
without tracing the actual body consumer. It also re-applies authored defaults
through virtual getters/setters, so absence of a direct scalar write in437890
alone is not proof of scalar preservation.
## Jimmy PostLoad40C
Vtable4A373C+40C→423610. Selected proven effects relevant to transition state:
| Site | State transition / ownership |
|---|---|
|42363B|Clear interface1D91; semantic name not assigned|
|423642..423656|Load default SoundEffects.omt, set current bank696008; gate4F8434 initially clear|
|4236A3/4236AA|Set current interaction/body radius60 through interface110|
|4236B3/4236BA|Set support factor1.265f through interface100|
|4236C0|Clear interface938 (tutorial flag later set for VR01..08)|
|4236FF|Current game virtual168(0), a gameplay/modal state callback; do not equate every control state with world pause|
|42370A and423729|Complete11C(0) for Jimmy and existing companion; both resolve40D350 and disable morph animation pause flag complete654, not jump/movement mode|
|42375E/423778|Stop associated saved effect handles through458A00, mark handles974/988 as−1|
|42378B /2378B|Clear WORD interface728 = complete7E8, the jump state, to0|
|423792|Clear interface970 temporary object pointer before later allocation|
|42399D/4239E6|Apply matching STRT root and Euler rotation|
|423A90..423B1E|Consume pending RETURN flag, override Jimmy with saved departure root, apply identical companion root|
|423B3D|Grant control through current game virtual118|
|423B43..423C67|Write shared viewport: authored STRT camera occurs inside match loop, later unconditional actor-local(0,200,−300) overwrites viewport eye|
|423CD4..423CE2|When companion already exists, call its interface174(0,0,0); constructor is not repeated|
The final viewport assignment explains why merely carrying the old chase-eye
cache would not reproduce source scene entry. Full orientation/follow cache
setup remains in the camera investigation. The unconditional final eye uses
local(0,200,−300), distinct from DEFAULT's local(0,500,−500) conditional snap.
### Movement mode, fire and transition staging limits
Player constructor43748A initializes complete7C4 movement mode0, but the inspected
JimmyInit28 and JimmyPostLoad40C do not establish an unconditional reset of this
field. PostLoad does explicitly reset jump state7E8 as above. Stage43B5A0 is
called with the complete player pointer; its complete148 call43B7FB resolves
429A00, which stops sound handle completeA44 and assigns−1. That callback does
not reset movement mode or fire time. Stage also clears complete7FC at43B5EE.
Do not promote absence of writes in these bounded local functions to a complete
preservation proof: game/streamer/control callbacks and class-specific gadget
cleanup can change player state elsewhere. In particular RETURN457FF7 performs
gadget cleanup before flags/staging, distinct from ordinary stage. Carrying raw
movement mode, held input, physics vectors or arbitrary jump timers across scenes
is not yet justified by this report. The current port's blanket constructor
zeroing is likewise an implementation policy, not a recovered reset contract.
## Retained fire/shadow/companion callbacks
| Object | Constructor-only state | Ordinary per-object28 /40C |
|---|---|---|
|Jetpack fire complete+C0 interface4A3160|421E51 calls470F40(0), selecting retention;421E62 zeros complete6BC owner and421E68 zeros complete6C0 timer; player437525 later assigns owner interface to6BC|28=4587F0 generic Init;40C=40E7B0 generic visibility/animation policy. Neither local path assigns owner6BC or timer6C0. No repeated constructor assumed.|
|Shadow complete+C8 interface4B37B8|43F767 calls470F40(0); authored size/owner are separate from runtime position|28=4587F0;40C=43F810→4354C0, then copies authored size words to completeAC/B0, resets completeB4=2/B8=0 and optional visibility flag. More base4354C0 effects remain open.|
|Goddard complete+C0 interface49F480|Ctor sets retention/reuse and owns shadow; aliases/defaults are constructor state|28=41E6A0→407EB0→4587F0; then byteA=1, AIstate608=authored87C, current waypoint800=null.40C=41E590→409480, then level-specific visibility/collision/radius policy.|
Fire421FB0 later queries its owner and, when grounded, clears timer interface600
(complete6C0) at421FE9, then subtracts dt. That is an **effect tick**, not an
initialization reset. It can observe the controller's same-pass changes according
to the recovered registry ordering. Timer preservation through local28/40C does
not prove it survives the entire transition unchanged without an intervening
owner/gadget/frame callback; exact first destination tick remains a lifecycle test.
Goddard's ordinary PostLoad sets radius130 and enables normal body behavior for
LV1B/VR04/LEV1; source-level hide branches cover other levels. Its existing-instance
callback174 is4716D0, not a constructor. Full rotation/AI resource resets in
409480 are not recovered here; retain the earlier patrol approximations explicitly.
## Directly evidenced implementation candidate: gadget availability
JimmyPostLoad **always first enables** group0 gadgets in source order
`7,3,0,5,1,6,2,4` via403870(false), calls423DEF..423E3F. For numeric
VR01..VR08 it then calls403870(true) for those same indices at423E71..423EC1.
At40389E, disabling changes only owned state1→4; at4038AA enabling changes only
4→1. All other values are preserved, including unowned0 and unknown wire values.
This is availability state, not ownership acquisition or inventory reset.
For the route: lab entry converts disabled-owned4→1; practice VR04 converts
owned1→4; return lab converts4→1. The VR04 powered-jump path bypasses the normal
inventory state guard, so source state4 here does not imply the tutorial jetpack
should fail. Lab→outside similarly normalizes these group0 entries; tasks, score
and acquired-table state remain independent. The audited baseline lacked this
availability pass. The first continuation called `SceneInventory.ApplyLevelAvailability`
once on level entry, before starting the authored sequence, and preserves raw
values in constructors/snapshots and arbitrary task assignments. Managed tests
cover every VR01..08 code, all relevant/unknown state boundaries, both untouched
inventory regions and TSK round-trip back to lab. GPU practice/RETURN smoke also
asserts state4 in VR04 and state1 on lab return. This correction does not invent
persistence for arbitrary physics/mode/fire fields.
## Verification and remaining gates
Run `python3 -m unittest discover -s tests -p test_checkpoint_character_reset.py -v`
and `python3 tools/binary/checkpoint_character_reset.py ../Original`. Tests verify
31 immutable instruction anchors,11 callback/vtable targets,16 exact gadget-call
arguments, source route player property names, and conditional1/4 conversion
boundaries. The state oracle tests interpretation, not execution of source code.
Remaining gates: complete property-streamer callback chain; RETURN gadget cleanup
versus ordinary departure; movement-mode/fire/hold/extra-acceleration writer
provenance through all destination callbacks; physical body re-registration/reset;
full shadow base reset and Goddard409480 policy; source camera orientation/cache
reset. Do not carry these fields merely because object identity persists.
+127
View File
@@ -0,0 +1,127 @@
# Retained Goddard and shadow: ordinary-load reset trace
Static investigation,2026-10-26. Original EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
All VAs below are in this EXE at preferred base400000; inspected raw offsets are
**VA−400000**, independently PE-mapped by `tools/binary/retained_companion.py`.
No original code was executed. No runtime implementation was changed.
## Identity, caller and property boundary
Goddard complete vtable49F920 is installed at41C866; its game-interface table
49F480 is installed at41C883 with complete+C0 receiver. Shadow complete table
4B3C1C/game-interface4B37B8 are installed at43F6A0/43F6AD, interface complete+C8.
Constructor retention/reuse writes remain as recovered in scene-loader.md:
Goddard41C99B..41C99E passes0 to470F40, and41C9C0 sets complete+C9=1.
These are constructor facts, not repeated initialization.
The route GAMs level1b.gam/LV1B, VR04.gam/VR04 and level1.gam/LEV1 contain **no
3DOG or3SHA serialized records**. Their bounded GAM parses/hashes are emitted by
the helper. Consequently ordinary reuse on this route does not stream a new
Goddard/shadow property record. The app's per-object Init28→PostLoad40C registry
pass still runs on their retained interfaces (scene-loader.md). A fresh companion
is dynamically constructed by Jimmy PostLoad when his interface95C pointer is
null:423C6A tests it;423C98 calls Goddard constructor41C810;423CAE stores it.
Existing pointer takes423CD4..423CE2 instead, discussed below. Exact same-pass
handling of a newly appended companion remains a registry-order question.
## Goddard Init and PostLoad
49F480+28→41E6A0 tail-jumps407EB0. At407EB3 it calls generic4587F0;407EB8 sets
interface byteA=1;407EBC..407EC2 copies authored87C→current AIstate608;
407EC8 clears current waypoint800. Complete offsets add C0. This replaces current
AI state and waypoint, not all AI fields. In constructor41C90E/41C914, current
complete6C8 and authored complete93C both start4.
49F480+40C→41E590 calls shared actor409480 at41E593. Its local work, in order:
| Source VA / raw coordinate | Reset or refresh |
|---|---|
|409486 /9486|Call generic40E7B0 visibility/animation policy; not a constructor.|
|40948B..40949A /948B..949A|Resolve tag string interface6AC through474070; always assign resulting pointer to600.|
|4094A0..4094FD /94A0..94FD|Only if pointer nonnull: refresh610 from target+404 (identity) and828/82C/830 from target logical root310. Null pointer leaves those cached fields untouched locally.|
|409503..40951E /9503..951E|Snapshot current608→authored87C; invoke complete124(current608), target4089B0.|
|40952D..409552 /952D..9552|Read authored Euler via interface170→4716A0 (FC/100/104/108), write logical Euler via32C→472450 (224/228/22C/230).|
|409561..409580 /9561..9580|Read authored Euler again and copy all four words into interface274/278/27C/280. This is an Euler-cache write, not sufficient evidence to name274 a queued physical impulse.|
The state setter4089B0 is not an unconditional state-entry callback. After its
special complete970 guard for requested states0/6,4089F8 copies current6C8 to
previous6CC and assigns requested6C8;408A18 skips transition cases when equal.
Init has already assigned current from authored, and PostLoad passes that exact
current value back. Therefore this chain does not justify replaying arbitrary AI
state-entry side effects at scene load. Intervening source callbacks could change
state; those require their own ordered fixture.
Goddard's derived41E590 then applies level policy:
| Source | Normal LV1B/VR04/LEV1 branch |
|---|---|
|41E598|interface918=1500 (range; exact consumer semantics remain separate). VR06 substitutes3500 at41E5EE.|
|41E608..41E613|If render attachment exists, set complete70=1 and dispatch complete58(0), the existing show/unhide path.|
|41E618/41E624|interfaceD0(1) and214(1); setters4710C0→471A40 and471A00 write authored/live movement/collision flags.|
|41E632|interface2C initialization/sync dispatch42AB50, which gates4623D0 on interface49E. Body re-registration internals remain in the physics investigation.|
|41E637..41E63B|complete17C(0)→41CC30: select submode0, copy globals4F8200/204/208 into complete6D4/6D8/6DC, set WORD complete9A0=0. These are table-sourced resets; do not invent numerical values from uninitialized file storage.|
|41E641/41E64A..651|interface914=1; interface110(130)→471240 writes authored34 and264→471B40 writes live15C.|
|41E657|interface928=0.|
Hidden branch41E661 applies to LEV6,LEV7,LV1C,LV1D,LV4A,LV6A. It calls complete58(1),
interfaceD0(0),214(0), and sets928=1. It does **not** locally assign130 radius or
submode0; carrying an old radius is not equivalent to resetting it to0. The helper
includes exact comparison immediates and a bounded branch oracle, with neighbors
tested. These later-level predicates are recovered locally, not proof of those
levels' full behavior.
## Existing companion174: rotation, not velocity
Jimmy423CD4 addsC0 to the existing companion pointer and passes three zeroes to
its interface174 at423CE2. 49F480+174→4716D0 writes authored EulerFC/100/104,
dispatches330→472420 to logical Euler224/228/22C, then3E0→4624F0→473540 to convert
logical Euler and dispatch render angle sync3E4. It is a rotation reset. Calling
it a velocity reset would conflate distinct coordinate fields.
Thus the source can zero Goddard's authored orientation before his own retained
PostLoad later copies authored→logical/cache. This report establishes both local
mutations; precise registry placement must determine their temporal order. Jimmy's
separate STRT/RETURN root placement still owns companion position, as already
documented. No broad body-velocity reset is inferred from174.
## Shadow PostLoad and resource lifetime
4B37B8+28→4587F0 generic Init;40C→43F810 first calls4354C0 at43F814. That base:
-4354C3..4354CA resolves authored database name interface4BC using46ACC0.
-If found,4354D6..4354F5 calls completeC8→464430 with resolved database,
authored interface4B8 resource selector and float-converted4B4. If a resulting
attached object exists at complete8C (interface−3C),435503..435513 sets its60/64
to1 and calls its embedded interface24 slot10.
-If the first database lookup fails,435518 tries literal4F02C0
`permanenticons.omt`; if found43553F..435542 attaches selector3 with the same
float-converted4B4. If both fail, no attachment dispatch occurs locally.
43F819..43F844 then converts signed authored WORDs interface520/522 into complete
AC/B0 runtime size;43F84A/43F854 resets completeB4=2 andB8=0. If global509A13 is
set,43F867..43F86B calls complete58(1) to hide. This refreshes visual-resource
references and size/flags, so retained identity does not mean retaining the old
scene's texture/database handle. No local owner-pointer reset is proven; full
database teardown/reattachment internals are separate.
## Implementation and remaining gates
Current port reconstructs companion/animation/patrol objects on scene continuation
and explicitly restores RETURN roots. It does not model this complete retained
Goddard/shadow lifecycle. Existing patrol remains a subset: state4 follow, source
angle/render sync, shadow resource identity and per-object ordering are incomplete.
Direct fixture contracts now supported: no route property reload for companion;
Init restores AIstate/clears waypoint; target caches refresh conditionally;
authored rotation controls PostLoad and174; normal route reapplies130/flags/
submode0; shadow resources/sizes refresh. Unknown fields must remain unknown,
not be silently copied or zeroed. Full body registration4623D0 and exact newly
appended/retained registry callback timing gate live retained-container integration.
Validation: `python3 -m unittest discover -s tests -p test_retained_companion.py -v`
checks EXE identity, exact instruction/vtable targets, route record absence,
rotation-setter provenance and level-branch boundaries. Helper JSON:
`python3 tools/binary/retained_companion.py ../Original`. This is immutable static
evidence plus an interpretation oracle, not original runtime execution or port
gameplay validation.
+94
View File
@@ -0,0 +1,94 @@
# Retained player: body reset and ordinary-load scalar boundary
2026-10-26. Original EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Preferred-base EXE VAs below map to raw offset VA−400000; the helper independently
maps PE sections. Originals remain untouched. Static recovery, isolated component
execution and port tests are separate evidence categories.
Continuation: uncontrolled body/fire and cutscene preparation are now implemented
in a bounded C3 chunk; see control-phase-implementation.md. Full wrapper/base
policies, body response and scene scheduling remain separate gates.
## Closed callback chain
Read `retained-streamer.md`, `retained-return-cleanup.md` and
`retained-companion.md` alongside this report. Together they close the bounded
no-selected-gadget/jetpack route path through deferred load, property read,
generic Init, Jimmy PostLoad and final control preparation. The property reader
does named descriptor writes without an implicit constructor/reset callback.
Route game Init28 resolves44D4E0→4587F0→470540. Game control118 resolves475A40,
which writes global5099E4; it does not itself reset Jimmy's movement mode.
Generic Init470540 re-applies authored vectors through virtual getters/setters:
| Quantity | Authored interface field / getter | Live field / setter | Init caller / physics consumer |
|---|---|---|---|
| Acceleration |3C..48 /11C→471290|164..170 /274→471BD0|4706EA→47070F;479F01 reads270→471B70,479F4A adds acceleration×dt to velocity|
| Queued impulse |4C..58 /124→4712E0|174..180 /288→471CC0|47071E→470743;479EBB reads284→471C60,479EE5 adds it,479EF2 clears via28C→471C90|
| Velocity |7C..88 /13C→4713D0|1A4..1B0 /2C0→471F70|4707BA→4707DF;479F8D reads2BC→471F10|
All copied vectors have four float components. These are authored→live copies,
not unconditional zero writes and not arbitrary preservation of the prior live
body. Route GAM JIM1 records do not contain these authored vector properties;
their source constructor/class defaults remain distinct from property extraction.
The port currently initializes its provisional body vectors to zero.
Jimmy PostLoad's common tail424472 grants control;42447D invokes410→42AFC0.
42AFC3 calls43A750, which clears speed608 at43A758 and invokes2C4(0,0,0) at
43A764..43A76C. Target471F40 writes velocity1A4/1A8/1AC; it does not overwrite
the fourth component1B0. Complete148 stops the saved sound, then the derived
preparation requests `STOP` animation. Neither null control nor this preparation
means all scene physics stops. Uncontrolled-body scheduling remains a next chunk.
Generic Init also clears274/278/27C and298; these are separate cached fields,
**not** the acceleration/impulse vectors above. Do not confuse a virtual slot
number with a same-numbered member offset.
## Bounded retained-state contract
| State | Boundary behavior and evidence |
|---|---|
|Movement mode complete7C4/interface704|Constructor zero is not repeated; absent from route GAM, generic Init and resolved no-gadget/jetpack cleanup/PostLoad writes. Retain.|
|Jump hold complete874/interface7B4|Same bounded absence after closing property/control paths. Retain; later state0 takeoff resets it independently.|
|Owned fire timer complete6C0/interface600|Fire retained object; generic28/40C do not reset it; jetpack cleanup does not own it. Retain. First grounded fire tick421FE9 zeros it before subtracting dt.|
|Jump state complete7E8/interface728|PostLoad42378B resets WORD to0. Do not carry with mode/hold.|
|Speed608, turn614, scalar618, destination yaw61C|Jimmy Init437890 clears first three and captures authored logical Euler.Y; final preparation clears speed again.|
|Body vectors, support, radius, collision contacts|Re-apply their own initialization/PostLoad policy; not copied in the scalar container. Source radius60/factor1.265 reasserted. Full registration/response remains open.|
|Selected gadget|Cleanup and destination selection have their own state machine; not persisted by this scalar container.|
|Goddard/shadow|Identity survives; Init/PostLoad restore specific authored AI, waypoint, target, rotation/resource/visibility state. No blanket AI or shadow-state carry.|
This is a **boundary** contract. A first destination controller/effect callback can
change the same scalar immediately. Observing the timer after grounding is not a
test of whether the loader reset it. Other gadget cleanup branches explicitly
change movement mode; other level tails remain unported and need separate proof.
The full ordinary loader and original route have not been executed end to end.
## Port implementation and verification
`PlayerLevelState` carries only mode/hold/fire in memory for LV1B/VR04/LEV1 and
selected gadget−1/3. Apply follows new scene construction and precedes scene
playback. Destination jump state starts0; body, presentation and debug settings
initialize independently. Noclip does not capture a carry state. Unsupported
levels/gadget cases use the existing reconstruction policy, explicitly unproven.
TSK/CLI/debug checkpoint load gets no scalar container; no wire format changed.
R reset remains the authorized modern reset, clearing these transient fields.
Movement tests use nondefault mode/hold/fire sentinels, then independently verify
body/jump reset, airborne first tick, grounded release/effect reset, unsupported
scope and explicit reset. The GPU practice/RETURN fixture seeds nondefault values
and asserts the actual cross-scene bridge before the destination's first tick.
These are port regressions, not original cadence or whole-route fidelity evidence.
Static helper: `python3 tools/binary/retained_player_body.py ../Original`.
Two evidence tests guard26 instruction sites and16 virtual targets. The C probe
maps an isolated copied EXE without entry point/import initialization, calls the
original vector leaf accessors and43A750 with sound handle−1, and compares all
other sentinel bytes. Synthetic fixture vtables use byte-guarded source targets
in a rebased copy; selected paths use no absolute globals or unresolved imports.
The isolated Wine32 probe passes; it is intentionally narrower than full Init/PostLoad.
Runtime probe outcome and full integration/package evidence are in progress.md.
Remaining: body registration4623D0, original support/response and cadence,
uncontrolled controller/fire phases, exact registry traversal of newly appended
helpers, other selected gadgets/level tails and original end-to-end comparison.
+122
View File
@@ -0,0 +1,122 @@
# RETURN cleanup and complete PostLoad route tail
Static C3/C7 continuation,2026-10-26. Read-only source is Neutron.exe SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
All preferred-base EXE VAs below map to raw file offset VA−400000 for these sites.
The helper maps PE sections independently and emits actual offsets/bytes and
virtual targets. No original code was executed; no runtime implementation changed
in this investigation. This report supersedes the earlier **prefix-only** gadget
availability interpretation in retained-character-reset.md.
## Result: cleanup is selected-gadget policy, not a universal motion reset
RETURN457FED adjusts Jimmy's game interface−C0 to complete, then457FF7/9 invokes
complete178. Table4A3BDC+178 resolves427FF0. After cleanup,458014 setscomplete954,
458028 sets9A5, and45815C dispatches complete168→43B5A0. Cleanup therefore runs
before RETURN flags and ordinary transition staging.
427FF0 first updates the C2DInGameMenu at completeA18, if present. Provenance:
Jimmy42238D calls401430,4223A6 stores its result inA18,401464 installs48D414;
literal4EF05C identifies `C2DInGameMenu`. Cleanup calls its4B0(3) at42800C, then
4C4 at42801A; those resolve405FB0 (menu selection/resource visibility) and406590
(close/free menu resources). The receiver is not the owned C3DJetpackFire.
428020 loads signed WORD selected gadget4F0588. Unsigned bound428027..2A rejects
values outside0..7, including−1, to the common epilogue. Table428844 has:
| Selected gadget | Case target | Relevant distinction |
|---|---|---|
|0|428037|If completeA14 exists, explicitly writes movement mode7C4=0 at42804F and restores radius/support.|
|1|4284FB|Writes mode7C4=1 at4286EA after companion/gadget cleanup.|
|2|42810C|Other gadget/companion policy.|
|3 (jetpack)|42882F|Directly the common epilogue: selected gadget4F0588=−1.|
|4|4281B3|Other gadget/companion policy.|
|5|4280CC|Conditional companion/gadget policy.|
|6|42871D|Other gadget/companion policy.|
|7|4287AC|Other gadget/companion policy.|
The jetpack/no-selection branch does not zero movement mode7C4, jump7E8, hold874
or owned fire6C0. This is a local caller projection, not proof that every later
load callback preserves those fields. Generic cleanup must not be modeled as
“clear all movement”; gadgets0/1 demonstrate different behavior.
Ordinary43B5A0 does not use this selected-gadget dispatch. It stages strings,
clears7FC, conditionally copies departure root9A8 unless9A5, queues the scene
request at43B7F1, then calls complete148 at43B7FB. That target429A00 only stops
saved sound handleA44 via458A00 and writes−1. Practice Yes40470D uses this ordinary
stage. Ordinary LOAD uses it at458276. RETURN adds its preceding cleanup/flags.
## Critical correction: read the entire Jimmy PostLoad
The generic prefix423DEF..423E3F enables the eight group0 gadgets, then
VR01..08 prefix423E71..423EC1 disables them. **That is not the final state.**
Jimmy PostLoad continues through424557 and has level-specific overrides:
| Destination | Tail behavior and source call VAs |
|---|---|
|LV1B|423FBB..423FCB recognizes LV1A..LV1C.424108 disables group0 item1;424113 disables item7.|
|VR01|4242BB cleanup;4242C7 enables item0.|
|VR02|424319 cleanup;424325 enables item1.|
|VR03|4242F0 cleanup;4242FC enables item2;424408 selects item2.|
|VR04|424340 cleanup;42434C enables item3;42435A selects item3.|
|VR05|424380 enables item4;424394 cleanup.|
|VR06|4243A8 cleanup;4243B4 enables item5.|
|VR07|4243CA cleanup;4243D6 enables item6.|
|VR08|4243EE cleanup;4243FA enables item7;424408 selects item7.|
|LEV1|Falls through to common42440E without those per-level overrides.|
VR05..08 branch424365 subtracts56523035, bounds0..3, then dispatches table424558
to42437A/42439C/4243BE/4243E0. Every enable call pushes `(disabled=false,item,group0)`
in reverse argument order and targets403870; conversion remains only4→1. Thus
every tutorial enables its corresponding practice gadget0..7 after disabling the
others. Unknown/unowned wire values remain unchanged. LV1B owned items1/7 finish4.
Source VR04 owned jetpack3 finishes1, not4; lab return leaves it1. The earlier
port tests asserting VR04 jetpack4 validated an incomplete source prefix.
Other ordinary-level branches also exist in423EE1..42440E; their availability,
selection and automatic save policies are outside this bounded route correction.
Do not present a route-specific implementation as a full PostLoad reconstruction.
## Remaining callback closure for retained fields
Common PostLoad42373E cleans selected gadget5 specifically, not every gadget.
Jump state is separately cleared at42378B (interface728=complete7E8). The route
tails above run after that reset. VR04's complete174(3) resolves428D50; its table
4298E8 is indexed item+1 and maps both−1 and3 to428DE0. That branch tests global
inventory item9==2, conditionally schedules another practice level, and otherwise
returns. It does not initialize movement/hold/fire time. Its UI prelude uses the
same menu-selection405FB0 and does not own the effect timer.
The common tail424472 grants control through game118, then42447D invokes Jimmy410
→42AFC0. That calls43A750 (speed0/body velocity2C4(0,0,0), separately recovered by
primary), stops sound148, then complete150(`STOP`) at42AFDE..E5. Complete150 is
43AFF0: a conditional animation/action request; it dispatches completeE0→40DD90,
which updates morph selection/alias strings and animation flags through base
targets. It contains no movement-mode/hold/owned-fire write. `STOP` is literal
4ED040, distinct from `RUN`4ECA64. This final control preparation does not mean
movement mode is walking0.
Owned fire has its own subsequent tick421FB0. It queries owner support218 at421FDF,
zeros interface600=complete6C0 only if grounded421FE9, then subtracts dt421FF3.
This is an effect tick, not a loader reset. Takeoff separately zeros the timer at
438391. Initialization can preserve a timer that the first destination tick then
changes; comparisons must observe the same phase.
**Confidence:** high for exact cleanup/table arguments and final route availability;
high for absence of direct scalar reset in these resolved local paths. Mode/hold/
fire preservation through a complete transition additionally requires the sibling
property-stream/Init proof and enclosing control/loader order. Retaining only
these bounded scalars after that closure is justified for no-selection/jetpack
route states; retaining arbitrary gadget modes, physics vectors or effect handles
is not justified by object identity. Body reset, selected gadget and jump state
must remain independent state dimensions. Original runtime comparison remains open.
## Verification
`python3 -m unittest discover -s tests -p test_retained_return_cleanup.py -v`
passes5 tests covering immutable source identity, exact instructions/vtables,
cleanup table, all eight tutorial tail argument/dispatch sites, and a deliberately
nondefault sentinel projection for selected jetpack/no-selection cleanup. The
projection checks interpretation only; it does not execute the original routine.
`python3 tools/binary/retained_return_cleanup.py ../Original` emits the evidence;
local generated copy: artifacts/retained-return-cleanup.json. No originals modified.
Loaded 100 of 635 files, more files were not shown because too many files have changed in this diff. Show more