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

164 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.