Files
Neutron/.planning/phases/01-reproducible-fidelity-baseline/01-01-PLAN.md
T

14 KiB
Raw Blame History

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, estimate, must_haves
phase plan type wave depends_on files_modified autonomous requirements estimate must_haves
01-reproducible-fidelity-baseline 01 execute 1
tools/recon/fidelity.py
tools/recon/fidelity_receipts.py
tests/test_fidelity_sessions.py
docs/evidence/scenarios.json
tests/test_fidelity_scenarios.py
true
EVID-01
EVID-02
EVID-04
tokens raw_tokens tasks confidence
34000 34000 2 low
truths artifacts key_links prohibitions
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.
path provides
tools/recon/fidelity.py Local stage, identify, import and validate CLI
path provides
tools/recon/fidelity_receipts.py Versioned receipt, identity, containment and atomic publication contract
path provides
docs/evidence/scenarios.json Required baseline matrix and observed-event protocol
from to via
tools/recon/fidelity.py tools/recon/inventory.py Recorded original inventory checked before staging and after collection
from to via
tools/recon/fidelity_receipts.py docs/evidence/scenarios.json Stable case IDs and completeness rules
statement status reason
MUST NOT sacrifice authoritative original bytes or execute the authoritative installation to make reference collection convenient. unresolved Spec-less recall: preservation is a project value; descriptor-less and flagged-unverified for review.
**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.

<execution_context> @/home/cristian/.codex/gsd-core/workflows/execute-plan.md @/home/cristian/.codex/gsd-core/templates/summary.md </execution_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 Stage one preserved session and review one honestly classified receipt end to end Versioned local records are shared by later tools; retaining raw inputs and explicit schema versions keeps migration bounded. tools/recon/fidelity.py, tools/recon/fidelity_receipts.py, tests/test_fidelity_sessions.py 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. 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. 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. 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. 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())' Nonzero exit, fewer than 16 discovered tests, any failed round-trip/security/classification case, or no test summary. python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json Nonzero exit or missing output Verified 539 unchanged original files. 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. Make every required journey and lifetime cell explicit and reject incomplete evidence docs/evidence/scenarios.json, tests/test_fidelity_scenarios.py, tools/recon/fidelity.py, tools/recon/fidelity_receipts.py 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. 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. 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. 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. 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())' Nonzero exit, fewer than 12 discovered tests, or a missing matrix/continuity/classification negative case passes validation. Every required baseline run has a stable executable procedure, complete artifact obligations and a validator that preserves missing acceptance.

<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>

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. <success_criteria>Preservation and complete scenario contracts support independent viewer, ledger and native capture work without claiming new original/native execution.</success_criteria> Create .planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md with interfaces, actual test counts/durations and evidence boundaries.