From ac958e1962f381804f6a5ad6bf9ea2559a652fff Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Thu, 12 Nov 2026 19:12:37 -0500 Subject: [PATCH] docs(01-01): record preserved session and scenario implementation --- .../01-01-SUMMARY.md | 163 ++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 .planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md diff --git a/.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md b/.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md new file mode 100644 index 0000000..dbfa2c8 --- /dev/null +++ b/.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md @@ -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.