docs(01-01): record preserved session and scenario implementation
This commit is contained in:
1 parent
32a72654e8
commit
ac958e1962
1 file changed
+163
@@ -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.
|
||||||
Reference in new issue
Block a user