From 857466568de044d8ae9d319a3d8cfb759e086a81 Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Fri, 13 Nov 2026 11:36:47 -0500 Subject: [PATCH] feat(01-05): complete offline Windows collection agenda and selftests Prepare all session materials, explicit terminal outcomes and raw-media provenance while retaining open acceptance. Verify the package-free collector on synthetic fixtures without redistributing external tools. --- docs/evidence/windows-session.md | 204 +++++++++++++++++++++++++++ scripts/collect-fidelity-windows.ps1 | 110 ++++++++++++--- tests/fidelity-windows.Tests.ps1 | 191 +++++++++++++++++++++++++ tools/recon/fidelity_checkpoint.py | 27 +++- 4 files changed, 510 insertions(+), 22 deletions(-) create mode 100644 docs/evidence/windows-session.md create mode 100644 tests/fidelity-windows.Tests.ps1 diff --git a/docs/evidence/windows-session.md b/docs/evidence/windows-session.md new file mode 100644 index 0000000..588ef80 --- /dev/null +++ b/docs/evidence/windows-session.md @@ -0,0 +1,204 @@ +# One combined local Windows fidelity session + +This is the prepared agenda for plan 01-07, not a request to capture now. +`READY.json` means immutable materials are prepared. It never means original, +native Windows, browser, audio or scenario acceptance passed. Linux PowerShell +selftests, cross-publish, Wine and synthetic media cannot fill those slots. +Keep every package, original copy, raw recording and result on local storage. + +The checkpoint contains `manifest.json`, `READY.json`, both identified +`port/{linux-x64,win-x64}` packages, `original-pristine/`, writable +`original-runs/`, `protocol/`, offline `review/`, collectors, these instructions, +package-free selftests and `results/`. No SDK or Python is needed on Windows. +The manifest records actual package BUILD-INFO and sealed source identities; +the later bundle revision does not replace the runtime's source identity. +Do not alter immutable materials to make a preflight pass. Mutable results and +generated run copies stay outside that immutable hash set. + +## Ordered session agenda + +1. **Select local dependencies and capture provenance.** Transfer the entire + prepared checkpoint to a fresh local directory, preferably a short path with + sufficient recording space. Select the actual Windows PC, DxWnd executable, + original exported DxWnd profile, recorder, browser and any media-probe/ + derivation executables already installed locally. No download, installer + redistribution, elevation or guessed DxWnd switches are part of this bundle. + Copy `protocol/settings-template.json` into `results/session-settings.json` + and fill observed values. Record each tool's actual local source, version, + SHA-256, settings/export and limitations, Windows build, GPU/driver, Vulkan + and SDL versions as actually available; missing identities remain pending. + The collector hashes selected external tool executables without copying them + into returned results. Retain settings/profile exports, not installers. + Initial recorder recommendation: **offline OBS Display Capture**, with the + actual monitor, capture source, crop/aspect, resolution/frame rate, encoder, + audio device/mix and MKV container recorded. Record notification/desktop + exposure and wrapper timing/rendering limitations in the local notes. +2. **Run immutable preflight and package-free selftests.** From the checkpoint + directory run the following exact commands. Require exit zero, at least eight + executed checks and zero failures; preserve the output in local session notes. + A missing PowerShell or dependency is a failure to record, not a silent pass. + + ```powershell + powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Preflight + powershell.exe -NoProfile -File .\tests\fidelity-windows.Tests.ps1 + ``` + + PowerShell 5.1 is the Windows target; a `pwsh` run on Linux exercises tooling + only. Executables are launched directly with quoted arguments, never from + receipt-supplied commands. Keep script execution subject to the PC's existing + policy; record a policy failure rather than changing security policy here. +3. **Perform separate short original and native-port visual/audio preflights.** + Use new diagnostic IDs for each. Inspect the selected DxWnd distribution's + own local help/config. Import the user's retained exported profile and change + only executable/working-directory paths to the generated copy printed by the + collector; export that relocated profile to the result's artifacts directory. + Do not force timer, renderer or compatibility settings or guess profile syntax. + If automation is unsupported, use the transparent DxWnd GUI launch. Retain + original and relocated exports and describe exact changes. The collector opens + DxWnd with no assumed switches and does not infer the original child's exit. + Never select the authoritative installation or `original-pristine/` as target. + Play each raw preflight: require **visible moving game content, intelligible + game audio, correct crop and aspect**, rather than merely detected ffprobe + streams. Record failures before proceeding. Keep diagnostic runs separate + from required cases. Native port launch uses the existing NewGame.tsk story + entry; absence of a reconstructed menu remains an explicit comparison gap. +4. **Record all matrix cells and obligations.** Use `protocol/agenda.json` as + the checklist: 8 cells × 5 obligations × 2 Windows sides = **80 Windows + obligations**. The separate Linux side contributes 40; all **120** remain + subject to actual receipt validation and human review. The table below and + `protocol/scenarios.json` specify the matrix, actual route, required events + and end conditions. Each fresh run has a new launch ID and original copy. + For retained runs, record prerequisite lab departure to VR04 and return in + the same process/clock before the tested interval; do not relaunch or reset + state. Capture the retained generated-copy identity during that lifetime + with `-Action Retained`, preserving the original pre-copy identity. Start the + recorder before interaction, retain the entire raw MKV and audible tail, + then finalize the specific scope after the process ends. Follow each cell's + natural/skip and ordinary/held-input procedure through its focused setup. +5. **Review paired browser video and exclusive audio.** Open `review/index.html` + using the selected local browser. Return results are imported into a fresh + local review export for pairing; the initially empty viewer does not invent + captures. Preserve actual speed and separate raw clocks, annotate offsets, + playback drift, crop and uncertainty. Listen to only one source at a time. + Require actual browser playback/seeking/audio checks for every preview codec. + A codec name, probe success or file extension is insufficient. Retain raw MKV + even if the browser cannot decode it. If a preview or extracted WAV is needed, + use a selected existing local tool and retain exact executable/version/hash, + inert argv, UTC derivation time, raw/output identities, timestamp mapping and + crop/aspect changes. Never silently retime or discard the source. Record + unsupported codecs or inaudible/missing content as open failures. +6. **Collect, postflight and audit.** Finish each run with actual annotations, + recording files, observer logs, settings, DxWnd exports and limitations. + Include missed, skipped, aborted, crashed and incomplete runs. A process exit + or `captured` means collection only. Original-DxWnd provenance is separate + from native port receipts. Preserve generated originals and their post-run + changes, `copy-pre.json`, `retained-copy.json` where applicable and + `copy-post.json`; never restore them over the authoritative originals. + Re-run immutable preflight after collection and preserve output. Actual + review verdicts and shared schema/matrix validation remain separate gates. +7. **Return once using local transfer.** Copy the complete checkpoint (including + raw recordings, results and original-runs) by USB/local filesystem or existing + local share to a new return directory. Do not upload assets/packages/media. + Recheck manifest/READY SHA-256 and all immutable entries, then rehash all + receipt-linked artifacts on return using the shared Python receipt validator. + Preserve a source-side file/hash inventory for the mutable result and + original-runs trees and compare it with the returned copy before importing. + A mismatch or missing file is an explicit transfer failure. Do not overwrite + the source copy, canonical originals, historical packages or an earlier return. + +## Matrix and required procedures + +| Case ID | Lifetime | Carl dialogue | Physical input policy | +|---|---|---|---| +| fresh-natural-edge | Independent fresh launch | Natural completion | Held through dialogue/RETURN | +| fresh-natural-ordinary | Independent fresh launch | Natural completion | Ordinary play/release | +| fresh-skipped-edge | Independent fresh launch | Actual supported skip | Held through dialogue/RETURN | +| fresh-skipped-ordinary | Independent fresh launch | Actual supported skip | Ordinary play/release | +| retained-natural-edge | Observed departure/return, same lifetime | Natural completion | Held through dialogue/RETURN | +| retained-natural-ordinary | Observed departure/return, same lifetime | Natural completion | Ordinary play/release | +| retained-skipped-edge | Observed departure/return, same lifetime | Actual supported skip | Held through dialogue/RETURN | +| retained-skipped-ordinary | Observed departure/return, same lifetime | Actual supported skip | Ordinary play/release | + +Every cell requires separate `continuous`, `dialogue-return`, `bank-left`, +`bank-right` and `landing-idle` obligations on both original-DxWnd and native +Windows port. Continuous means ordinary **lab → VR04 → lab → outside** in one +uninterrupted recording and process, including Carl dialogue, first neutral +input, both banked jumps/landings, gadget use, RETURN cleanup and outside arrival. +Focused clips retain their actual setup/prerequisite recording. A direct scene, +debug warp or injected fixture cannot replace the route or retained prerequisite. +Record keys, skip action and held/released boundaries as actually performed. +Preserve legitimate landing bank and the implemented TSK lifetime ordering; +do not insert a leveling reset or tune movement for the recording. + +## Collector commands and failure results + +Replace paths and IDs with actual selections. Commands are examples for the +later combined session; use a fresh unique ID for each independent launch. +Start external recording when prompted and keep the collector alive for the +entire retained setup and tested interval. The recorder/browser are identified, +not automatically driven. The `.cmd` wrapper is an optional equivalent entry. + +```powershell +powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Run -Mode port -SessionId port-fresh-natural-ordinary-continuous-01 -CaseId fresh-natural-ordinary -Scope continuous -RecorderPath 'C:\Tools\OBS\bin\64bit\obs64.exe' -BrowserPath 'C:\Tools\Browser\browser.exe' -SettingsPath '.\results\session-settings.json' +powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Run -Mode original -SessionId original-retained-natural-edge-bank-left-01 -CaseId retained-natural-edge -Scope bank-left -DxWndPath 'C:\Tools\DxWnd\dxwnd.exe' -ProfilePath 'C:\Local\exported.dxw' -RecorderPath 'C:\Tools\OBS\bin\64bit\obs64.exe' -BrowserPath 'C:\Tools\Browser\browser.exe' -SettingsPath '.\results\session-settings.json' +powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Retained -SessionId original-retained-natural-edge-bank-left-01 +powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Finish -SessionId port-fresh-natural-ordinary-continuous-01 -AnnotationPath '.\results\port-notes.json' -ArtifactsDirectory 'D:\LocalCaptures\port-run-01' +powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Skip -Mode original -SessionId original-missed-01 -CaseId fresh-skipped-edge -Scope bank-left -Reason 'Actual reason this obligation could not run' +``` + +`Skip`/`Abort` create a new terminal result without requiring recorder/browser +selection. An interrupted active run retains its initial `incomplete.json`; +when safe, collect its artifacts with `Finish -Outcome aborted -Reason '...'` +instead of pretending a separate aborted launch describes its lifetime. +Failed starts preserve `run.json`, `failure.json` and available logs. To collect +failed/skipped/aborted media use `Finish -Outcome failed|skipped|aborted` matching +the prior status, a reason and annotation/artifact directories (empty arrays are +allowed for these outcomes). Never promote a failed or terminal run to captured; +use a new independent session for a retry. Existing evidence is write-once. + +## Annotation field contract + +Copy `protocol/annotation-template.json` to a mutable result note and fill it +with actual values. Empty templates cannot finalize capture. All paths are +relative, case-unique and contained below `ArtifactsDirectory`; no commands are +read from annotations. Every captured run retains a raw `.mkv` video and actual +audio evidence. If raw audio is embedded, retain a separately named byte-identical +MKV copy with role `audio`, or a proven extracted WAV with derivation provenance. +This preserves unique artifact paths while binding the actual audio bytes. + +- `artifacts`: entries `{path, role, duration_seconds}`; roles include `video`, + `audio`, `input_events`, `prerequisite`, `diagnostic`. Preserve raw and preview + as separate entries. Original prerequisite recordings/copy-state records and + port `observer/events.jsonl`, summary, stdout/stderr must be included as + appropriate; do not rename synthetic fixtures as native evidence. +- `events`: `{name, artifact, media_seconds, elapsed_seconds, method, + uncertainty_seconds}` using the exact required names/order in scenarios.json. + Original methods are `manual` or `procedural`; markers describe visible input + and event intervals, never invented original simulation ticks. Port events + map observer data to actual media clocks; `simulation_tick` remains separate. + Preserve observer `launch_id`, `clock_id`, requested/accepted input distinctions, + sequence and possible truncation/overhead. Never reset elapsed clocks at scenes. + All times are finite, nonnegative and within actual recording/run duration. +- `derivatives`: `{path, source, tool, version, argv, created_utc, + timestamp_mapping, crop_aspect, browser_playback_verified}`. The collector + stores argv as inert provenance; it does not execute it. Select true browser + playback only after observed playback. Hash tool binaries and retain source + identity/settings in local session notes, including whether crop/time changed. +- `continuity`: `lifetime_id` equals session ID, `prerequisite_artifact` names a + hashed artifact, `copy_pre_sha256` binds the actual copy-state record. Retained + additionally needs `departure_session_id` and `return_session_id` equal to that + same session ID and `retained_copy_sha256` identifying the retained snapshot. + `prerequisite_departure` and `prerequisite_return` markers precede the tested + interval on the prerequisite artifact. Include these state records as hashed + identities/artifacts, never made-up placeholders. The port's actual package/ + startup-state record must be identified separately; missing continuity remains + open rather than treating a second fresh launch as retained. +- `diagnostic`: true for observation overhead, preflight, fixtures or other + diagnostic limitations; `limitations`: actual missing tools, crop/audio/render/ + timer/wrapper differences, incomplete transitions, uncertain markers and review + failures. A successful collector does not clear them or acceptance automatically. + +`Finish` prefixes local media/event/derivative references with `media/` and hashes +copied bytes. It never accepts an annotation-supplied acceptance verdict. The +shared receipt validator and later full matrix/human review decide applicability. +No universal timing, pixel, angle or audio tolerance is asserted by this agenda. diff --git a/scripts/collect-fidelity-windows.ps1 b/scripts/collect-fidelity-windows.ps1 index 08d7be3..20ebb28 100644 --- a/scripts/collect-fidelity-windows.ps1 +++ b/scripts/collect-fidelity-windows.ps1 @@ -9,11 +9,13 @@ param( [string]$DxWndPath, [string]$ProfilePath, [string]$RecorderPath, [string]$BrowserPath, [string]$SettingsPath, [string]$AnnotationPath, [string]$ArtifactsDirectory, [string]$Reason, + [ValidateSet('captured','failed','skipped','aborted')][string]$Outcome = 'captured', [ValidateRange(1,14400)][int]$TimeoutSeconds = 7200, [switch]$LibraryOnly ) Set-StrictMode -Version 2 $ErrorActionPreference = 'Stop' +$script:CollectorSource = $PSCommandPath function Test-FidelityId([string]$Value) { if ($Value -cnotmatch '^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$' -or @@ -65,7 +67,7 @@ function Read-FidelityJson([string]$Path) { } function Write-FidelityJson([string]$Path, $Value) { - $text = ($Value | ConvertTo-Json -Depth 40) + "`n" + $text = (ConvertTo-Json -InputObject $Value -Depth 40) + "`n" $bytes = (New-Object Text.UTF8Encoding($false)).GetBytes($text) if ($bytes.Length -gt 4194304) { throw 'JSON exceeds 4 MiB' } $temporary = $Path + '.incomplete-' + [guid]::NewGuid().ToString('N') @@ -146,8 +148,10 @@ function Invoke-FidelityProcess([string]$Executable, [string[]]$Arguments, $out = [IO.File]::Open((Join-Path $OutputDirectory 'stdout.txt'),[IO.FileMode]::CreateNew) $err = [IO.File]::Open((Join-Path $OutputDirectory 'stderr.txt'),[IO.FileMode]::CreateNew) $timer = [Diagnostics.Stopwatch]::StartNew() + $started = $false try { - if (-not $process.Start()) { throw 'Process did not start' } + $started = $process.Start() + if (-not $started) { throw 'Process did not start' } $stdout = $process.StandardOutput.BaseStream.CopyToAsync($out) $stderr = $process.StandardError.BaseStream.CopyToAsync($err) while (-not $process.WaitForExit(200)) { @@ -155,15 +159,28 @@ function Invoke-FidelityProcess([string]$Executable, [string[]]$Arguments, $process.Kill(); $process.WaitForExit(); throw 'Process timed out or logs exceeded 64 MiB' } } - $stdout.GetAwaiter().GetResult(); $stderr.GetAwaiter().GetResult() + $remaining = [int][Math]::Max(1,($Seconds - $timer.Elapsed.TotalSeconds) * 1000) + if (-not [Threading.Tasks.Task]::WaitAll([Threading.Tasks.Task[]]@($stdout,$stderr),$remaining)) { + throw 'Process output did not close within the bounded wait' + } + $null = $stdout.GetAwaiter().GetResult(); $null = $stderr.GetAwaiter().GetResult() + if ($out.Length -gt 67108864 -or $err.Length -gt 67108864) { throw 'Process logs exceeded 64 MiB' } return @{exit_code=$process.ExitCode; elapsed_seconds=$timer.Elapsed.TotalSeconds; executable=$Executable; argv=@($Executable)+$Arguments; cwd=$WorkingDirectory} } finally { - if ($process.Id -and -not $process.HasExited) { $process.Kill(); $process.WaitForExit() } + if ($started -and -not $process.HasExited) { $process.Kill(); $process.WaitForExit() } $out.Dispose(); $err.Dispose(); $process.Dispose(); $timer.Stop() } } +function Get-FidelityOutcome([string]$Prior, [string]$Requested, [string]$Why) { + if ($Prior -notin @('incomplete','failed','skipped','aborted') -or + $Requested -notin @('captured','failed','skipped','aborted')) { throw 'Invalid outcome' } + if ($Prior -ne 'incomplete' -and $Requested -ne $Prior) { throw 'Failed/terminal run cannot be promoted; use a new session' } + if ($Requested -ne 'captured' -and -not $Why) { throw 'Failure/skip/abort requires a reason' } + return $Requested +} + function Get-FidelityPlatform { $result = @{os='windows'; execution='native'; version=[Environment]::OSVersion.VersionString; powershell=$PSVersionTable.PSVersion.ToString(); gpu=''; driver=''; vulkan=''; sdl=''} @@ -222,24 +239,27 @@ function Start-FidelityRun { if ($manifest.tooling_only) { throw 'Synthetic checkpoint cannot launch native/original evidence' } $protocol = Read-FidelityJson (Join-Path $root 'protocol/scenarios.json') if ($CaseId -notin @($protocol.cells | ForEach-Object {$_.id})) { throw 'Unknown scenario cell' } + if ($Action -in @('Skip','Abort')) { + $receipt.status = Get-FidelityOutcome 'incomplete' $(if ($Action -eq 'Skip') {'skipped'} else {'aborted'}) $Reason + $receipt.limitations = @($Reason) + return 0 + } $platform = Get-FidelityPlatform $platform.execution = $(if ($Mode -eq 'original') {'dxwnd'} else {'native'}) $receipt.platform = $platform $receipt.identity.checkpoint = Copy-FidelityEvidence (Join-Path $root 'manifest.json') $run 'identity/checkpoint.json' - $receipt.identity.launcher = Copy-FidelityEvidence $PSCommandPath $run 'identity/collector.ps1' + $receipt.identity.launcher = Copy-FidelityEvidence $script:CollectorSource $run 'identity/collector.ps1' $tools = @{} foreach ($entry in @(@('recorder',$RecorderPath),@('browser',$BrowserPath),@('settings',$SettingsPath))) { if (-not $entry[1]) { throw ('Select actual local ' + $entry[0] + ' file; no downloads are performed') } - $id = Copy-FidelityEvidence $entry[1] $run ('identity/' + $entry[0] + [IO.Path]::GetExtension($entry[1])) + # Identify external tools; do not redistribute their executables/installers. + $id = Get-FidelityIdentity $entry[1] $tools[$entry[0]] = @{selected_path=$entry[1]; identity=$id; version=[Diagnostics.FileVersionInfo]::GetVersionInfo($entry[1]).FileVersion} } + $receipt.identity.settings = Copy-FidelityEvidence $SettingsPath $run 'identity/settings.json' Write-FidelityJson (Join-Path $run 'tools.json') $tools - if ($Action -in @('Skip','Abort')) { - if (-not $Reason) { throw 'A skipped/aborted run requires a reason' } - $receipt.status = $(if ($Action -eq 'Skip') {'skipped'} else {'aborted'}) - $receipt.limitations = @($Reason) - } elseif ($Mode -eq 'port') { + if ($Mode -eq 'port') { $package = Join-Path $root 'port/win-x64' $exe = Join-Path $package 'GamePort.exe' $receipt.identity.executable = Copy-FidelityEvidence $exe $run 'identity/GamePort.exe' @@ -263,7 +283,10 @@ function Start-FidelityRun { $receipt.limitations = @('Port process exited; media/event mapping and human review pending; observer overhead is diagnostic') } else { if (-not $DxWndPath -or -not $ProfilePath) { throw 'Select actual local DxWnd executable and exported profile' } - $receipt.identity.dxwnd = Copy-FidelityEvidence $DxWndPath $run 'identity/dxwnd.exe' + $dxwndId = Get-FidelityIdentity $DxWndPath + Write-FidelityJson (Join-Path $run 'dxwnd-tool.json') @{selected_path=$DxWndPath;identity=$dxwndId; + version=[Diagnostics.FileVersionInfo]::GetVersionInfo($DxWndPath).FileVersion} + $receipt.identity.dxwnd = @{path='dxwnd-tool.json'} + (Get-FidelityIdentity (Join-Path $run 'dxwnd-tool.json')) $receipt.identity.dxwnd_config = Copy-FidelityEvidence $ProfilePath $run 'identity/original-profile.dxw' $copy = Get-FidelityPath $root ('original-runs/' + $SessionId) if (Test-Path -LiteralPath $copy) { throw 'Original run copy exists' } @@ -282,8 +305,6 @@ function Start-FidelityRun { $wrapper = [Diagnostics.Process]::Start($info) $receipt.invocation = @{argv=@($info.FileName);cwd=$copy;method='manual profile import and GUI launch; original child exit not inferred'} $null = Read-Host 'After the original has exited and recording stopped, press Enter (keep this collector alive during retained prerequisites)' - Write-FidelityJson (Join-Path $run 'copy-post.json') @(Get-FidelityTree $copy) - $receipt.identity.copy_post = @{path='copy-post.json'} + (Get-FidelityIdentity (Join-Path $run 'copy-post.json')) $receipt.wrapper_settings = 'Selected profile retained; relocated export/settings and wrapper limitations require annotation review' $receipt.limitations = @('DxWnd GUI launched; original child invocation/exit and visible/audible behavior require actual session annotations') $wrapper.Dispose() @@ -292,9 +313,16 @@ function Start-FidelityRun { $receipt.status = 'failed'; $receipt.limitations = @($_.Exception.Message) Write-Warning $_.Exception.Message } finally { + if ($Mode -eq 'original' -and (Get-Variable copy -ErrorAction SilentlyContinue) -and + (Test-Path -LiteralPath $copy) -and -not (Test-Path -LiteralPath (Join-Path $run 'copy-post.json'))) { + try { + Write-FidelityJson (Join-Path $run 'copy-post.json') @(Get-FidelityTree $copy) + $receipt.identity.copy_post = @{path='copy-post.json'} + (Get-FidelityIdentity (Join-Path $run 'copy-post.json')) + } catch { $receipt.status = 'failed'; $receipt.limitations += ('Postflight failed: ' + $_.Exception.Message) } + } $clock.wall_end = [DateTime]::UtcNow.ToString('o'); $clock.monotonic_end = $watch.Elapsed.TotalSeconds Write-FidelityJson (Join-Path $run 'run.json') $receipt - if ($receipt.status -in @('failed','skipped','aborted')) { Write-FidelityJson (Join-Path $run 'receipt.json') $receipt } + if ($receipt.status -in @('failed','skipped','aborted')) { Write-FidelityJson (Join-Path $run 'failure.json') $receipt } $watch.Stop() } Write-Host "Result: $run ; status=$($receipt.status); acceptance OPEN" @@ -309,6 +337,34 @@ function Complete-FidelityRun { if (Test-Path -LiteralPath (Join-Path $run 'receipt.json')) { throw 'Result already finalized; preserve it and use a new result ID' } if (-not $AnnotationPath -or -not $ArtifactsDirectory) { throw 'Finish requires actual annotations and a local artifact directory' } $annotation = Read-FidelityJson $AnnotationPath + $requested = Get-FidelityOutcome $receipt.status $Outcome $Reason + if ($annotation.schema_version -ne 1) { throw 'Unsupported annotation schema' } + if (@($annotation.artifacts).Count -gt 10000) { throw 'Too many artifacts' } + $names = @{} + foreach ($file in $annotation.artifacts) { + $null = Get-FidelityPath $ArtifactsDirectory $file.path + if ($names.ContainsKey($file.path)) { throw 'Duplicate/case-aliased artifact' }; $names[$file.path] = $file + $null = Get-FidelityIdentity (Get-FidelityPath $ArtifactsDirectory $file.path) + if ($file.PSObject.Properties.Name -contains 'synthetic' -and $file.synthetic) { throw 'Synthetic media cannot be relabeled as native/original' } + } + foreach ($event in $annotation.events) { + if (-not $names.ContainsKey($event.artifact)) { throw 'Event references missing artifact' } + } + if ($requested -eq 'captured') { + if (-not @($annotation.artifacts | Where-Object {$_.role -eq 'video' -and $_.path.EndsWith('.mkv',[StringComparison]::OrdinalIgnoreCase)}).Count) { + throw 'Captured result requires retained raw MKV video' + } + if (-not @($annotation.artifacts | Where-Object {$_.role -eq 'audio'}).Count) { throw 'Captured result requires actual audio evidence' } + } + foreach ($derivative in $annotation.derivatives) { + if (-not $names.ContainsKey($derivative.path) -or -not $names.ContainsKey($derivative.source) -or + -not $derivative.tool -or -not $derivative.version -or -not $derivative.created_utc -or + -not @($derivative.argv).Count -or -not $derivative.timestamp_mapping -or + -not $derivative.crop_aspect -or $derivative.browser_playback_verified -isnot [bool] -or + -not $derivative.browser_playback_verified) { + throw 'Derivative requires source/output, actual tool/version/argv/time/crop and verified browser playback' + } + } $receipt.artifacts = @() foreach ($file in $annotation.artifacts) { $source = Get-FidelityPath $ArtifactsDirectory $file.path @@ -319,14 +375,30 @@ function Complete-FidelityRun { } $copied = Copy-FidelityEvidence $AnnotationPath $run 'annotations.json' $copied.role = 'input_events'; $receipt.artifacts += $copied - $receipt.events = @($annotation.events) - $receipt.derivatives = @($annotation.derivatives) - $receipt.status = 'captured' + $receipt.events = @($annotation.events | ForEach-Object { + if (-not $names.ContainsKey($_.artifact)) { throw 'Event references missing artifact' } + $_.artifact = 'media/' + $_.artifact; $_ + }) + $receipt.derivatives = @($annotation.derivatives | ForEach-Object { + $_.path = 'media/' + $_.path; $_.source = 'media/' + $_.source; $_ + }) + $receipt.status = $requested + if ($annotation.PSObject.Properties.Name -contains 'continuity') { + $continuity = $annotation.continuity + if ($continuity.PSObject.Properties.Name -contains 'prerequisite_artifact') { + if (-not $names.ContainsKey($continuity.prerequisite_artifact)) { throw 'Continuity references missing artifact' } + $continuity.prerequisite_artifact = 'media/' + $continuity.prerequisite_artifact + } + $receipt | Add-Member -Force -NotePropertyName continuity -NotePropertyValue $continuity + } + if ($annotation.PSObject.Properties.Name -contains 'diagnostic') { $receipt | Add-Member -Force -NotePropertyName diagnostic -NotePropertyValue ([bool]$annotation.diagnostic) } + if ($Reason) { $receipt.limitations += $Reason } + $receipt.limitations += @($annotation.limitations) # Human declarations remain source annotations; the shared importer and final # audit validate times, hashes, category, continuity and actual review later. $receipt.limitations += 'Imported annotations require shared validation; raw MKV and incomplete/failed cases are retained' Write-FidelityJson (Join-Path $run 'receipt.json') $receipt - Write-Host 'Captured result saved; acceptance OPEN. Return full checkpoint locally for validation.' + Write-Host "Result saved ($requested); acceptance OPEN. Return full checkpoint locally for validation." } if ($LibraryOnly) { return } diff --git a/tests/fidelity-windows.Tests.ps1 b/tests/fidelity-windows.Tests.ps1 new file mode 100644 index 0000000..0a7477b --- /dev/null +++ b/tests/fidelity-windows.Tests.ps1 @@ -0,0 +1,191 @@ +# Package-free selftests. All bytes/processes are synthetic tooling fixtures. +# Run with Windows PowerShell 5.1 or pwsh; Linux pwsh is NOT Windows evidence. +[CmdletBinding()] +param([string]$FixtureOutput) +Set-StrictMode -Version 2 +$ErrorActionPreference = 'Stop' +$collector = Join-Path (Split-Path -Parent $PSScriptRoot) 'scripts/collect-fidelity-windows.ps1' +. $collector -LibraryOnly +$temporary = Join-Path ([IO.Path]::GetTempPath()) ('fidelity-selftest-' + [guid]::NewGuid().ToString('N')) +$null = [IO.Directory]::CreateDirectory($temporary) +$script:Checks = 0 +function Assert-True($Condition, [string]$Message) { if (-not $Condition) { throw $Message } } +function Assert-Throws([scriptblock]$Body) { + $thrown = $false + try { & $Body | Out-Null } catch { $thrown = $true } + Assert-True $thrown 'Expected rejection did not occur' +} +function Check([string]$Name, [scriptblock]$Body) { + & $Body + $script:Checks++ + Write-Host "PASS $Name" +} +function Fixture-File([string]$Name, [string]$Content) { + $path = Join-Path $temporary $Name + $null = [IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($path)) + [IO.File]::WriteAllText($path,$Content,(New-Object Text.UTF8Encoding($false))) + return $path +} +try { + Check 'stable IDs reject reserved/path aliases' { + Assert-True ((Test-FidelityId 'session-01') -eq 'session-01') 'ID changed' + foreach ($bad in @('../x','CON','a/b','NUL.txt','')) { Assert-Throws { Test-FidelityId $bad } } + } + Check 'paths reject traversal, drive paths and Windows aliases' { + foreach ($bad in @('../x','a//x','C:/x','/x','a\x','aux.txt','a./x','a /x')) { + Assert-Throws { Get-FidelityPath $temporary $bad } + } + Assert-True ((Get-FidelityPath $temporary 'space dir/a.txt').StartsWith($temporary)) 'Contained path missing' + } + $sample = Fixture-File 'sample.txt' 'abc' + Check 'streamed SHA256 and size match actual bytes' { + $id = Get-FidelityIdentity $sample + Assert-True ($id.size -eq 3 -and $id.sha256 -eq 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad') 'Wrong identity' + } + Check 'copies preserve bytes and never overwrite evidence' { + $id = Copy-FidelityEvidence $sample $temporary 'copied/space name.txt' + Assert-True ($id.sha256 -eq (Get-FidelityIdentity $sample).sha256) 'Copy differs' + Assert-Throws { Copy-FidelityEvidence $sample $temporary 'copied/space name.txt' } + } + Check 'JSON keeps empty arrays, Unicode, singleton arrays and write-once results' { + $path = Join-Path $temporary 'json.json' + Write-FidelityJson $path @{empty=@();single=@('one');text='café'} + $value = Read-FidelityJson $path + Assert-True ($value.empty -is [array] -and $value.empty.Count -eq 0) 'Empty list lost' + Assert-True ($value.single -is [array] -and $value.single.Count -eq 1 -and $value.text -eq 'café') 'JSON changed' + Assert-Throws { Write-FidelityJson $path @{} } + $path2 = Join-Path $temporary 'empty.json' + Write-FidelityJson $path2 @() + Assert-True ([IO.File]::ReadAllText($path2).Trim() -eq '[]') 'Top-level empty list lost' + } + Check 'argument quoting preserves empty/spaces/quotes/trailing backslashes' { + Assert-True ((ConvertTo-FidelityArgument '') -ceq '""') 'Empty quoting' + Assert-True ((ConvertTo-FidelityArgument 'a b') -ceq '"a b"') 'Space quoting' + Assert-True ((ConvertTo-FidelityArgument 'a"b') -ceq '"a\"b"') 'Quote escaping' + Assert-True ((ConvertTo-FidelityArgument 'C:\space dir\') -ceq '"C:\space dir\\"') 'Trailing slash escaping' + Assert-Throws { ConvertTo-FidelityArgument "bad`nargument" } + } + $hostExe = [Diagnostics.Process]::GetCurrentProcess().MainModule.FileName + $child = Fixture-File 'child space.ps1' 'param([string]$Value) [Console]::Out.Write($Value); [Console]::Error.Write("child stderr"); exit 7' + Check 'real child arguments, logs and nonzero exit remain distinct from success' { + $logs = Join-Path $temporary 'process' + $null = [IO.Directory]::CreateDirectory($logs) + $result = Invoke-FidelityProcess $hostExe @('-NoProfile','-File',$child,'value with spaces') $temporary $logs 30 + Assert-True ($result.exit_code -eq 7 -and $result.elapsed_seconds -ge 0) 'Exit result changed' + Assert-True ([IO.File]::ReadAllText((Join-Path $logs 'stdout.txt')) -ceq 'value with spaces') 'Arguments not preserved' + Assert-True ([IO.File]::ReadAllText((Join-Path $logs 'stderr.txt')) -ceq 'child stderr') 'Stderr missing' + } + Check 'process waits are bounded and timeout preserves logs' { + $sleeper = Fixture-File 'sleep.ps1' 'Start-Sleep -Seconds 30' + $logs = Join-Path $temporary 'timeout' + $null = [IO.Directory]::CreateDirectory($logs) + Assert-Throws { Invoke-FidelityProcess $hostExe @('-NoProfile','-File',$sleeper) $temporary $logs 1 } + Assert-True (Test-Path -LiteralPath (Join-Path $logs 'stdout.txt')) 'Timeout logs lost' + Assert-Throws { Invoke-FidelityProcess $hostExe @() $temporary $logs 0 } + } + Check 'failed process start produces original exception without unstarted process access' { + $notExe = Fixture-File 'not-executable.bin' 'synthetic non executable' + $logs = Join-Path $temporary 'bad-process' + $null = [IO.Directory]::CreateDirectory($logs) + Assert-Throws { Invoke-FidelityProcess $notExe @() $temporary $logs 1 } + } + Check 'failure skip abort cannot become captured and require reasons' { + foreach ($state in @('failed','skipped','aborted')) { + Assert-True ((Get-FidelityOutcome 'incomplete' $state 'observed reason') -eq $state) 'Outcome changed' + Assert-Throws { Get-FidelityOutcome $state 'captured' '' } + Assert-Throws { Get-FidelityOutcome 'incomplete' $state '' } + } + } + Check 'result categories and open acceptance remain explicit' { + foreach ($kind in @('native_port','original_dxwnd','synthetic')) { + $r = New-FidelityReceipt 'selftest' 'fresh-natural-ordinary' 'continuous' $kind 'incomplete' @{} @{} 'fixture' + Assert-True ($r.evidence_kind -eq $kind -and $r.acceptance.state -eq 'open' -and $r.missing_evidence.Count -gt 0) 'False acceptance' + } + Assert-Throws { New-FidelityReceipt 'selftest' 'case' 'continuous' 'wine-as-native' 'captured' @{} @{} '' } + } + $bundleRoot = Join-Path $temporary 'bundle' + $null = [IO.Directory]::CreateDirectory((Join-Path $bundleRoot 'protocol')) + $material = Fixture-File 'bundle/protocol/test.txt' 'synthetic immutable material' + $entry = Get-FidelityIdentity $material; $entry.path = 'protocol/test.txt' + Write-FidelityJson (Join-Path $bundleRoot 'manifest.json') @{schema_version=1;tooling_only=$true;mutable_roots=@('results','original-runs');files=@($entry)} + Write-FidelityJson (Join-Path $bundleRoot 'READY.json') @{schema_version=1;status='prepared';manifest=(Get-FidelityIdentity (Join-Path $bundleRoot 'manifest.json'))} + Check 'prepared bundle validates immutable bytes and permits only declared mutable roots' { + $null = Test-FidelityBundle $bundleRoot + $null = Fixture-File 'bundle/results/local-result.txt' 'diagnostic' + $null = Test-FidelityBundle $bundleRoot + $extra = Fixture-File 'bundle/unlisted.txt' 'unexpected' + Assert-Throws { Test-FidelityBundle $bundleRoot } + [IO.File]::Delete($extra) + } + Check 'tampered immutable bytes fail preflight' { + [IO.File]::AppendAllText($material,'tampered') + Assert-Throws { Test-FidelityBundle $bundleRoot } + [IO.File]::WriteAllText($material,'synthetic immutable material',(New-Object Text.UTF8Encoding($false))) + } + $script:Bundle = $bundleRoot + $script:SessionId = 'fixture-finish' + $run = Join-Path $bundleRoot 'results/fixture-finish' + $null = [IO.Directory]::CreateDirectory($run) + $clock = @{wall_start=[DateTime]::UtcNow.ToString('o');wall_end=[DateTime]::UtcNow.ToString('o');monotonic_start=0;monotonic_end=2} + $r = New-FidelityReceipt $SessionId 'fresh-natural-ordinary' 'continuous' 'synthetic' 'incomplete' @{os='test';execution='synthetic'} $clock 'Tooling-only synthetic fixture' + Write-FidelityJson (Join-Path $run 'run.json') $r + $script:ArtifactsDirectory = Join-Path $temporary 'media' + $null = Fixture-File 'media/raw.mkv' 'synthetic video bytes, no gameplay' + $null = Fixture-File 'media/audio.wav' 'synthetic audio bytes, no gameplay' + $script:AnnotationPath = Join-Path $temporary 'annotations.json' + $annotation = @{schema_version=1;artifacts=@(@{path='raw.mkv';role='video';duration_seconds=2},@{path='audio.wav';role='audio';duration_seconds=2});events=@(@{name='startup';artifact='raw.mkv';media_seconds=0;elapsed_seconds=0;method='manual';uncertainty_seconds=0.1});derivatives=@();limitations=@('synthetic tooling only');continuity=@{prerequisite_artifact='raw.mkv'}} + $script:Outcome = 'captured' + Check 'capture rejects an empty annotation before any media copy' { + Write-FidelityJson $AnnotationPath @{schema_version=1;artifacts=@();events=@();derivatives=@();limitations=@()} + Assert-Throws { Complete-FidelityRun } + Assert-True (-not (Test-Path -LiteralPath (Join-Path $run 'media'))) 'Invalid annotation copied data' + [IO.File]::Delete($AnnotationPath) + } + Check 'capture rejects synthetic promotion and missing event targets before writes' { + $annotation.artifacts[0].synthetic = $true + Write-FidelityJson $AnnotationPath $annotation + Assert-Throws { Complete-FidelityRun } + [IO.File]::Delete($AnnotationPath) + $annotation.artifacts[0].Remove('synthetic') + $annotation.events[0].artifact = 'absent.mkv' + Write-FidelityJson $AnnotationPath $annotation + Assert-Throws { Complete-FidelityRun } + [IO.File]::Delete($AnnotationPath) + $annotation.events[0].artifact = 'raw.mkv' + } + Check 'finish maps hashed media/event/continuity paths and preserves synthetic category' { + Write-FidelityJson $AnnotationPath $annotation + Complete-FidelityRun + $result = Read-FidelityJson (Join-Path $run 'receipt.json') + Assert-True ($result.status -eq 'captured' -and $result.evidence_kind -eq 'synthetic' -and $result.acceptance.state -eq 'open') 'Fixture promoted' + Assert-True ($result.artifacts.Count -eq 3 -and $result.events[0].artifact -eq 'media/raw.mkv' -and $result.continuity.prerequisite_artifact -eq 'media/raw.mkv') 'Broken result links' + Assert-True ($result.artifacts[0].sha256 -eq (Get-FidelityIdentity (Join-Path $run 'media/raw.mkv')).sha256) 'Media identity differs' + Assert-Throws { Complete-FidelityRun } + } + Check 'terminal failed skipped aborted results retain empty artifact lists and cannot be promoted' { + foreach ($state in @('failed','skipped','aborted')) { + $script:SessionId = 'fixture-' + $state + $terminalRun = Join-Path $bundleRoot ('results/' + $SessionId) + $null = [IO.Directory]::CreateDirectory($terminalRun) + $terminal = New-FidelityReceipt $SessionId 'fresh-natural-ordinary' 'continuous' 'synthetic' $state @{os='test';execution='synthetic'} $clock 'synthetic terminal fixture' + Write-FidelityJson (Join-Path $terminalRun 'run.json') $terminal + $script:AnnotationPath = Join-Path $temporary ($state + '-notes.json') + Write-FidelityJson $AnnotationPath @{schema_version=1;artifacts=@();events=@();derivatives=@();limitations=@('synthetic tooling only')} + $script:Outcome = $state; $script:Reason = 'Tooling fixture; no actual capture' + Complete-FidelityRun + $saved = Read-FidelityJson (Join-Path $terminalRun 'receipt.json') + Assert-True ($saved.status -eq $state -and $saved.artifacts.Count -eq 1 -and $saved.events -is [array] -and $saved.events.Count -eq 0 -and $saved.acceptance.state -eq 'open') 'Terminal fixture changed' + } + } + if ($FixtureOutput) { + if (Test-Path -LiteralPath $FixtureOutput) { throw 'Fixture output must be new' } + $null = [IO.Directory]::CreateDirectory($FixtureOutput) + foreach ($item in Get-ChildItem -LiteralPath (Join-Path $bundleRoot 'results') -Directory) { + Copy-Item -LiteralPath $item.FullName -Destination $FixtureOutput -Recurse + } + } + Assert-True ($script:Checks -ge 8) 'Fewer than eight executed checks' + Write-Host "PASS: $script:Checks checks; 0 failures; synthetic tooling only; native Windows/original gameplay acceptance OPEN" +} finally { + if (Test-Path -LiteralPath $temporary) { Remove-Item -LiteralPath $temporary -Recurse -Force } +} diff --git a/tools/recon/fidelity_checkpoint.py b/tools/recon/fidelity_checkpoint.py index 9b12c9d..2a2a380 100644 --- a/tools/recon/fidelity_checkpoint.py +++ b/tools/recon/fidelity_checkpoint.py @@ -145,7 +145,7 @@ def prepare_checkpoint(original, original_manifest, packages, output, tooling=Fa for name in MATERIALS: if (PROJECT / name).is_file(): _copy_file(PROJECT / name, temporary / name) - elif name not in ('tests/fidelity-windows.Tests.ps1', 'docs/evidence/windows-session.md'): + else: raise ValueError('Missing collector material: ' + name) _copy_file(original_manifest, temporary / 'protocol/original-manifest.json') for name in ('scenarios.json', 'capabilities.json'): @@ -159,6 +159,25 @@ def prepare_checkpoint(original, original_manifest, packages, output, tooling=Fa for cell in protocol['cells'] for obligation in cell['obligations']] _write_json(temporary / 'protocol/agenda.json', {'schema_version': 1, 'runs': agenda, 'acceptance': {'state': 'open', 'required_all_platforms': 120}}) + _write_json(temporary / 'protocol/settings-template.json', { + 'schema_version': 1, 'diagnostic': True, + 'tools': {k: {'source': '', 'version': '', 'settings': ''} + for k in ('dxwnd', 'recorder', 'browser', 'media_probe', 'derivation')}, + 'capture': {'source': '', 'monitor': '', 'crop': [], 'aspect': '', + 'resolution': [], 'frame_rate': '', 'audio_devices': [], + 'encoder': '', 'container': 'MKV', 'timing_limitations': ''}, + 'preflight': {'original': {'visible_moving_game': False, 'intelligible_game_audio': False, + 'correct_crop_aspect': False}, + 'port': {'visible_moving_game': False, 'intelligible_game_audio': False, + 'correct_crop_aspect': False}, + 'browser': {'actual_playback': False, 'seeking': False, + 'exclusive_audio': False}}, + 'notes': 'Fill actual observed values; false/empty fields remain pending, never acceptance.'}) + _write_json(temporary / 'protocol/annotation-template.json', { + 'schema_version': 1, 'status': 'incomplete', 'diagnostic': True, + 'artifacts': [], 'events': [], 'derivatives': [], 'continuity': {}, + 'limitations': ['Actual media clocks, uncertainty and human review still required'], + 'notes': 'Use windows-session.md field contract; empty template cannot finalize capture.'}) verify_inventory(original, original_manifest) (temporary / 'incomplete.json').unlink() files = identify_tree(temporary)['files'] @@ -218,9 +237,11 @@ def preflight(root, dependencies=None): 'tools': tools, 'failures': failures, 'acceptance': {'state': 'open'}} -def fixture_result(bundle, run, session_id, case_id, scope, artifacts): +def fixture_result(bundle, run, session_id, case_id, scope, artifacts, status='captured'): """Tooling-only end-to-end importer fixture; cannot mint native evidence.""" preflight(bundle) + if status not in ('captured', 'failed', 'skipped', 'aborted'): + raise ValueError('Unknown fixture result status') _id(session_id) protocol = read_json(Path(bundle) / 'protocol/scenarios.json') if case_id not in {c['id'] for c in protocol['cells']} or scope not in protocol['obligations']: @@ -230,7 +251,7 @@ def fixture_result(bundle, run, session_id, case_id, scope, artifacts): **identify_file(contained_path(run, p))) for p in artifacts] receipt = {'schema_version': 1, 'receipt_id': session_id, 'session_id': session_id, 'case_id': case_id, 'obligation_id': scope, 'scope': scope, - 'evidence_kind': 'synthetic', 'status': 'captured', 'historical': False, + 'evidence_kind': 'synthetic', 'status': status, 'historical': False, 'platform': {'os': 'test', 'execution': 'synthetic'}, 'identity': {}, 'invocation': {'argv': ['fixture result; no executable launched'], 'cwd': str(run)}, 'clocks': {'wall_start': utc_now(), 'wall_end': utc_now(),