63 lines
6.1 KiB
Markdown
63 lines
6.1 KiB
Markdown
# 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.
|