feat(01-05): assemble identified offline Windows checkpoint

This commit is contained in:
UnixNight committed 2026-11-12 23:48:03 -05:00
1 parent 446930d2a3
commit 61123394e0
5 files changed
+669 -2

No files matched your search

+5
View File
@@ -0,0 +1,5 @@
@echo off
setlocal
rem Argument selection happens in PowerShell; never run commands from receipts.
powershell.exe -NoLogo -NoProfile -File "%~dp0collect-fidelity-windows.ps1" %*
exit /b %ERRORLEVEL%
+352
View File
@@ -0,0 +1,352 @@
# Windows PowerShell 5.1 compatible. No SDK/Python, elevation, downloads or eval.
[CmdletBinding()]
param(
[ValidateSet('Preflight','Run','Finish','Skip','Abort','Retained')][string]$Action = 'Preflight',
[ValidateSet('port','original')][string]$Mode = 'port',
[string]$Bundle = (Split-Path -Parent $PSScriptRoot),
[string]$SessionId, [string]$CaseId = 'fresh-natural-ordinary',
[ValidateSet('continuous','dialogue-return','bank-left','bank-right','landing-idle')][string]$Scope = 'continuous',
[string]$DxWndPath, [string]$ProfilePath, [string]$RecorderPath,
[string]$BrowserPath, [string]$SettingsPath, [string]$AnnotationPath,
[string]$ArtifactsDirectory, [string]$Reason,
[ValidateRange(1,14400)][int]$TimeoutSeconds = 7200,
[switch]$LibraryOnly
)
Set-StrictMode -Version 2
$ErrorActionPreference = 'Stop'
function Test-FidelityId([string]$Value) {
if ($Value -cnotmatch '^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$' -or
$Value -match '^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.|$)') { throw 'Invalid stable ID' }
return $Value
}
function Get-FidelityPath([string]$Root, [string]$Relative) {
if (-not $Relative -or $Relative.Length -gt 4096 -or $Relative -match '[\\:<>"|?*\x00-\x1f]' -or
$Relative.StartsWith('/') -or $Relative -match '(^|/)(\.{1,2}|)(/|$)') { throw "Unsafe relative path: $Relative" }
foreach ($part in $Relative.Split('/')) {
if ($part.EndsWith(' ') -or $part.EndsWith('.') -or
$part -match '^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.|$)') { throw 'Unsafe Windows alias' }
}
$base = [IO.Path]::GetFullPath($Root).TrimEnd([IO.Path]::DirectorySeparatorChar)
$path = [IO.Path]::GetFullPath((Join-Path $base $Relative))
if (-not $path.StartsWith($base + [IO.Path]::DirectorySeparatorChar, [StringComparison]::OrdinalIgnoreCase)) {
throw 'Path escapes checkpoint'
}
$cursor = $path
while ($cursor) {
if (Test-Path -LiteralPath $cursor) {
if (((Get-Item -LiteralPath $cursor -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) {
throw "Reparse/symlink path: $cursor"
}
}
$parent = [IO.Path]::GetDirectoryName($cursor)
if ($parent -eq $cursor) { break }
$cursor = $parent
}
return $path
}
function Get-FidelityIdentity([string]$Path) {
$item = Get-Item -LiteralPath $Path -Force
if ($item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0 -or
$item.Length -gt 8589934592) { throw "Not a bounded regular file: $Path" }
$stream = [IO.File]::OpenRead($item.FullName)
$sha = [Security.Cryptography.SHA256]::Create()
try {
$digest = [BitConverter]::ToString($sha.ComputeHash($stream)).Replace('-','').ToLowerInvariant()
return @{size=[long]$item.Length; sha256=$digest}
} finally { $stream.Dispose(); $sha.Dispose() }
}
function Read-FidelityJson([string]$Path) {
if ((Get-Item -LiteralPath $Path).Length -gt 4194304) { throw 'JSON exceeds 4 MiB' }
return [IO.File]::ReadAllText($Path, [Text.Encoding]::UTF8) | ConvertFrom-Json
}
function Write-FidelityJson([string]$Path, $Value) {
$text = ($Value | ConvertTo-Json -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')
$stream = [IO.File]::Open($temporary, [IO.FileMode]::CreateNew)
try { $stream.Write($bytes,0,$bytes.Length); $stream.Flush() } finally { $stream.Dispose() }
[IO.File]::Move($temporary,$Path)
}
function Get-FidelityTree([string]$Root) {
$base = [IO.Path]::GetFullPath($Root).TrimEnd([IO.Path]::DirectorySeparatorChar)
$seen = @{}
$files = New-Object 'System.Collections.Generic.List[object]'
# Enumerate directories ourselves so reparse points are checked before descent.
$queue = New-Object 'System.Collections.Generic.Queue[string]'
$queue.Enqueue($base)
$count = 0
while ($queue.Count -gt 0) {
foreach ($item in Get-ChildItem -LiteralPath $queue.Dequeue() -Force) {
$count++
if ($count -gt 100000) { throw 'Tree exceeds 100000 entries' }
$name = $item.FullName.Substring($base.Length+1).Replace('\','/')
$null = Get-FidelityPath $base $name
if ($seen.ContainsKey($name)) { throw 'Case-alias in tree' }; $seen[$name] = $true
if ($item.PSIsContainer) { $queue.Enqueue($item.FullName) }
else { $identity = Get-FidelityIdentity $item.FullName; $identity.path = $name; $files.Add($identity) }
}
}
if ($files.Count -eq 0) { throw 'Empty tree' }
return @($files | Sort-Object path -CaseSensitive)
}
function Test-FidelityBundle([string]$Root) {
$ready = Read-FidelityJson (Get-FidelityPath $Root 'READY.json')
if ($ready.schema_version -ne 1 -or $ready.status -ne 'prepared') { throw 'Checkpoint is not READY' }
$id = Get-FidelityIdentity (Get-FidelityPath $Root 'manifest.json')
if ($id.sha256 -ne $ready.manifest.sha256 -or $id.size -ne $ready.manifest.size) { throw 'Manifest tampered' }
$manifest = Read-FidelityJson (Join-Path $Root 'manifest.json')
if ($manifest.schema_version -ne 1 -or $manifest.mutable_roots.Count -ne 2 -or
$manifest.mutable_roots[0] -ne 'results' -or $manifest.mutable_roots[1] -ne 'original-runs') {
throw 'Unsupported checkpoint manifest'
}
$seen = @{}
foreach ($file in $manifest.files) {
if ($seen.ContainsKey($file.path)) { throw 'Duplicate/case-aliased manifest file' }
$seen[$file.path] = $true
$actual = Get-FidelityIdentity (Get-FidelityPath $Root $file.path)
if ($actual.sha256 -ne $file.sha256 -or $actual.size -ne $file.size) { throw "Tampered/missing material: $($file.path)" }
}
foreach ($file in Get-FidelityTree $Root) {
if ($file.path.Split('/')[0] -notin @('results','original-runs') -and
$file.path -notin @('manifest.json','READY.json') -and -not $seen.ContainsKey($file.path)) {
throw "Unexpected immutable material: $($file.path)"
}
}
return $manifest
}
function ConvertTo-FidelityArgument([string]$Value) {
# Windows CommandLineToArgvW/CRT quoting. No cmd.exe, shell or expression eval.
if ($Value -match '[\x00\r\n]') { throw 'Control character in argument' }
$escaped = [regex]::Replace($Value, '(\\*)"', '$1$1\"')
$escaped = [regex]::Replace($escaped, '(\\+)$', '$1$1')
return '"' + $escaped + '"'
}
function Invoke-FidelityProcess([string]$Executable, [string[]]$Arguments,
[string]$WorkingDirectory, [string]$OutputDirectory, [int]$Seconds) {
$null = Get-FidelityIdentity $Executable
if ($Seconds -lt 1 -or $Seconds -gt 14400) { throw 'Process wait must be bounded' }
$info = New-Object Diagnostics.ProcessStartInfo
$info.FileName = $Executable
$info.Arguments = (($Arguments | ForEach-Object { ConvertTo-FidelityArgument $_ }) -join ' ')
$info.WorkingDirectory = $WorkingDirectory
$info.UseShellExecute = $false
$info.RedirectStandardOutput = $true; $info.RedirectStandardError = $true
$process = New-Object Diagnostics.Process
$process.StartInfo = $info
$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()
try {
if (-not $process.Start()) { throw 'Process did not start' }
$stdout = $process.StandardOutput.BaseStream.CopyToAsync($out)
$stderr = $process.StandardError.BaseStream.CopyToAsync($err)
while (-not $process.WaitForExit(200)) {
if ($timer.Elapsed.TotalSeconds -gt $Seconds -or $out.Length -gt 67108864 -or $err.Length -gt 67108864) {
$process.Kill(); $process.WaitForExit(); throw 'Process timed out or logs exceeded 64 MiB'
}
}
$stdout.GetAwaiter().GetResult(); $stderr.GetAwaiter().GetResult()
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() }
$out.Dispose(); $err.Dispose(); $process.Dispose(); $timer.Stop()
}
}
function Get-FidelityPlatform {
$result = @{os='windows'; execution='native'; version=[Environment]::OSVersion.VersionString;
powershell=$PSVersionTable.PSVersion.ToString(); gpu=''; driver=''; vulkan=''; sdl=''}
if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) { throw 'Native Windows collector requires Windows; Linux library tests are tooling-only' }
try {
$result.gpu_adapters = @(Get-CimInstance Win32_VideoController | Select-Object Name,DriverVersion,DriverDate,PNPDeviceID)
$result.gpu = ($result.gpu_adapters | ForEach-Object { $_.Name }) -join '; '
$result.driver = ($result.gpu_adapters | ForEach-Object { $_.DriverVersion }) -join '; '
$result.windows = Get-CimInstance Win32_OperatingSystem | Select-Object Caption,Version,BuildNumber,OSArchitecture
} catch { $result.query_failure = $_.Exception.Message }
return $result
}
function Copy-FidelityEvidence([string]$Source, [string]$Run, [string]$Name) {
$target = Get-FidelityPath $Run $Name
$null = [IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($target))
$before = Get-FidelityIdentity $Source
[IO.File]::Copy($Source,$target,$false)
$after = Get-FidelityIdentity $target
if ($before.sha256 -ne $after.sha256 -or $before.size -ne $after.size) { throw 'Copy identity changed' }
$after.path = $Name
return $after
}
function New-FidelityReceipt([string]$Id, [string]$Case, [string]$Obligation,
[string]$Kind, [string]$Status, $Platform, $Clocks, [string]$Why) {
$null = Test-FidelityId $Id; $null = Test-FidelityId $Case
if ($Kind -notin @('original_dxwnd','native_port','synthetic') -or
$Status -notin @('incomplete','failed','captured','skipped','aborted')) { throw 'Invalid result classification' }
return @{schema_version=1; receipt_id=$Id; session_id=$Id; case_id=$Case;
scope=$Obligation; obligation_id=$Obligation; evidence_kind=$Kind;
status=$Status; historical=$false; platform=$Platform; identity=@{};
invocation=@{argv=@();cwd=''}; clocks=$Clocks; artifacts=@();derivatives=@();events=@();
limitations=@($Why); missing_evidence=@('Actual audiovisual review and scenario audit remain open');
acceptance=@{state='open';remaining=@('No acceptance from preparation, launch or collector success')}}
}
function Start-FidelityRun {
$null = Test-FidelityId $SessionId
$root = [IO.Path]::GetFullPath($Bundle)
$run = Get-FidelityPath $root ('results/' + $SessionId)
if (Test-Path -LiteralPath $run) { throw 'Session exists; choose an independent new launch ID' }
$null = [IO.Directory]::CreateDirectory((Join-Path $root 'results'))
$reservation = [IO.File]::Open(($run + '.lock'),[IO.FileMode]::CreateNew)
$reservation.Dispose()
$null = [IO.Directory]::CreateDirectory($run)
$watch = [Diagnostics.Stopwatch]::StartNew()
$clock = @{wall_start=[DateTime]::UtcNow.ToString('o'); wall_end=[DateTime]::UtcNow.ToString('o');
monotonic_start=0;monotonic_end=0;clock_id=[guid]::NewGuid().ToString('N')}
$platform = @{os='windows';execution=$(if ($Mode -eq 'original') {'dxwnd'} else {'native'})}
$kind = $(if ($Mode -eq 'original') {'original_dxwnd'} else {'native_port'})
$receipt = New-FidelityReceipt $SessionId $CaseId $Scope $kind 'incomplete' $platform $clock 'Collection pending'
Write-FidelityJson (Join-Path $run 'incomplete.json') $receipt
try {
$manifest = Test-FidelityBundle $root
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' }
$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'
$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]))
$tools[$entry[0]] = @{selected_path=$entry[1]; identity=$id;
version=[Diagnostics.FileVersionInfo]::GetVersionInfo($entry[1]).FileVersion}
}
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') {
$package = Join-Path $root 'port/win-x64'
$exe = Join-Path $package 'GamePort.exe'
$receipt.identity.executable = Copy-FidelityEvidence $exe $run 'identity/GamePort.exe'
$receipt.identity.runtime_dll = Copy-FidelityEvidence (Join-Path $package 'GamePort.dll') $run 'identity/GamePort.dll'
$build = Read-FidelityJson (Join-Path $package 'fidelity-build.json')
$src = Copy-FidelityEvidence (Join-Path $package 'fidelity-build.json') $run 'identity/build.json'
$src.commit = $build.source.commit; $src.dirty = $build.source.dirty; $src.diff_sha256 = $build.source.diff_sha256
$receipt.identity.source = $src
$receipt.identity.package = $src
$receipt.identity.resources = $src
$sdl = [Diagnostics.FileVersionInfo]::GetVersionInfo((Join-Path $package 'SDL3.dll'))
$platform.sdl_binary_version = $sdl.FileVersion
$arguments = @('--assets',(Join-Path $package 'assets'),'--load-save',(Join-Path $package 'assets/NewGame.tsk'),
'--walk','--fidelity-output',(Join-Path $run 'observer'),'--fidelity-session',$SessionId,'--fidelity-case',$CaseId)
Write-Host 'Start the external raw MKV recording now. Record physical inputs and media clocks. This is the existing TSK story entry, not a reconstructed main menu.'
$null = Read-Host 'Press Enter when recording is running'
$receipt.invocation = @{argv=@($exe)+$arguments;cwd=$run}
$result = Invoke-FidelityProcess $exe $arguments $run $run $TimeoutSeconds
Write-FidelityJson (Join-Path $run 'process.json') $result
if ($result.exit_code -ne 0) { throw "Port exited $($result.exit_code); preserve recording and logs" }
$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'
$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' }
$null = [IO.Directory]::CreateDirectory($copy)
$seed = Join-Path $root 'original-pristine'
foreach ($file in Get-FidelityTree $seed) {
$null = Copy-FidelityEvidence (Get-FidelityPath $seed $file.path) $copy $file.path
}
Write-FidelityJson (Join-Path $run 'copy-pre.json') @(Get-FidelityTree $copy)
$receipt.identity.copy_pre = @{path='copy-pre.json'} + (Get-FidelityIdentity (Join-Path $run 'copy-pre.json'))
Write-Host "Generated original copy: $copy"
Write-Host 'Inspect this selected DxWnd distribution help/config. Import the retained exported profile and change ONLY target/working-directory paths to the generated copy; export the relocated profile into this result folder. No switches/settings are assumed.'
Write-Host 'Start external raw MKV recording before original interaction. Launch the original manually through DxWnd. Never select original-pristine or the authoritative installation.'
$info = New-Object Diagnostics.ProcessStartInfo
$info.FileName = [IO.Path]::GetFullPath($DxWndPath); $info.WorkingDirectory = $copy; $info.UseShellExecute = $false
$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()
}
} catch {
$receipt.status = 'failed'; $receipt.limitations = @($_.Exception.Message)
Write-Warning $_.Exception.Message
} finally {
$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 }
$watch.Stop()
}
Write-Host "Result: $run ; status=$($receipt.status); acceptance OPEN"
if ($receipt.status -eq 'failed') { return 2 }; return 0
}
function Complete-FidelityRun {
$null = Test-FidelityId $SessionId
$run = Get-FidelityPath $Bundle ('results/' + $SessionId)
$null = Test-FidelityBundle $Bundle
$receipt = Read-FidelityJson (Join-Path $run 'run.json')
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
$receipt.artifacts = @()
foreach ($file in $annotation.artifacts) {
$source = Get-FidelityPath $ArtifactsDirectory $file.path
$id = Copy-FidelityEvidence $source $run ('media/' + $file.path)
$id.role = $file.role
if ($file.PSObject.Properties.Name -contains 'duration_seconds') { $id.duration_seconds = $file.duration_seconds }
$receipt.artifacts += $id
}
$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'
# 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.'
}
if ($LibraryOnly) { return }
try {
if ($Action -eq 'Preflight') {
$manifest = Test-FidelityBundle $Bundle
Write-Host "Prepared materials checked: $($manifest.files.Count) files; acceptance OPEN; actual Windows/tools/media preflight pending"
exit 0
}
if ($Action -eq 'Finish') { Complete-FidelityRun; exit 0 }
if ($Action -eq 'Retained') {
$null = Test-FidelityId $SessionId
$run = Get-FidelityPath $Bundle ('results/' + $SessionId)
$copy = Get-FidelityPath $Bundle ('original-runs/' + $SessionId)
Write-FidelityJson (Join-Path $run 'retained-copy.json') @{observed_utc=[DateTime]::UtcNow.ToString('o');
files=@(Get-FidelityTree $copy);note='Snapshot only; prerequisite recording and actual media timing/uncertainty still required'}
exit 0
}
exit (Start-FidelityRun)
} catch {
Write-Error ('Collector failed; acceptance OPEN: ' + $_.Exception.Message)
exit 2
}
+6
View File
@@ -0,0 +1,6 @@
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/env.sh"
# Build first into NEW local output, then prepare a different NEW bundle root.
# Existing dist packages retain their historical bytes and BUILD-INFO.
exec python3 tools/recon/fidelity_checkpoint.py "$@"
+2 -2
View File
@@ -36,8 +36,8 @@ class FidelityCheckpoint(unittest.TestCase):
'GamePort.dll', 'GamePort.runtimeconfig.json', 'GamePort.deps.json',
'SDL3.dll' if rid == 'win-x64' else 'libSDL3.so.0',
'assets/NewGame.tsk', 'scenes/level1b/scene.json',
'scenes/VR04/scene.json', 'scenes/outsideLEV1/scene.json',
'scenes/animations/animation.json', 'audio/music.wav', 'Shaders/test.spv'):
'scenes/VR04/scene.json', 'scenes/level1/scene.json',
'scenes/animations/jimstop/animation.json', 'audio/music.wav', 'Shaders/test.spv'):
path = package / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(b'synthetic fixture bytes ' + name.encode())
+304
View File
@@ -0,0 +1,304 @@
#!/usr/bin/env python3
"""Prepare immutable, local-only fidelity checkpoints. READY is never acceptance.
The Windows collector needs no Python or SDK. This module assembles/transfers
identities and imports explicitly synthetic fixture results; it never executes
an original. Cooperative locks/incomplete siblings are retained after failure.
"""
import argparse
import hashlib
import os
from pathlib import Path
import shutil
import subprocess
import sys
import uuid
from fidelity_receipts import (canonical_bytes, contained_path, identify_file,
identify_tree, read_json, relative_name, separated_roots, source_identity,
utc_now, validate_receipt, validate_scenario_contract, verify_inventory,
_id, _write_json)
from fidelity_review import export_review
PROJECT = Path(__file__).resolve().parents[2]
RIDS = ('linux-x64', 'win-x64')
FLAGS = ['--fidelity-output', '--fidelity-session', '--fidelity-case']
MAX_FILE_BYTES = 8 * 1024**3
MUTABLE = ('results', 'original-runs')
MATERIALS = ('scripts/collect-fidelity-windows.ps1',
'scripts/collect-fidelity-windows.cmd',
'tests/fidelity-windows.Tests.ps1', 'docs/evidence/windows-session.md')
def _copy_file(source, target):
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(source, target)
if identify_file(source) != identify_file(target):
raise ValueError('Source changed during copy: ' + str(source))
def _copy_tree(source, target):
tree = identify_tree(source)
target.mkdir(parents=True)
for entry in tree['files']:
if entry['size'] > MAX_FILE_BYTES:
raise ValueError('File exceeds 8 GiB bound: ' + entry['path'])
_copy_file(contained_path(source, entry['path']), target / entry['path'])
if identify_tree(target)['files'] != tree['files']:
raise ValueError('Copied tree differs: ' + str(source))
def _package_files(package):
return [f for f in identify_tree(package)['files'] if f['path'] != 'fidelity-build.json']
def seal_package(package, rid, source, tooling=False, build_argv=None):
"""Called immediately after the local publish by our wrapper, never on old DLLs.
Build source is captured BEFORE publishing and checked again afterward. This
record binds those claims to bytes, without pretending the hash proves their
compiler provenance. A synthetic seal is permanently tooling-only.
"""
package = Path(package)
if rid not in RIDS:
raise ValueError('Unsupported package RID')
required = ['GamePort.dll', 'GamePort.runtimeconfig.json', 'GamePort.deps.json',
'BUILD-INFO.txt', 'GamePort.exe' if rid == 'win-x64' else 'GamePort',
'SDL3.dll' if rid == 'win-x64' else 'libSDL3.so.0',
'assets/NewGame.tsk', 'scenes/level1b/scene.json', 'scenes/VR04/scene.json',
'scenes/level1/scene.json', 'scenes/animations/jimstop/animation.json']
for name in required:
identify_file(contained_path(package, name))
for name in ('assets', 'scenes', 'audio', 'Shaders'):
identify_tree(package / name)
if not tooling:
dll = (package / 'GamePort.dll').read_bytes()
if not all(flag.encode('utf-16le') in dll for flag in FLAGS):
raise ValueError('Stale DLL: observer flags absent')
if not build_argv or not source.get('commit') or not source.get('diff_sha256'):
raise ValueError('Missing actual pre-publish source/command identity')
record = {'schema_version': 1, 'rid': rid, 'source': source,
'built_utc': utc_now(), 'tooling_only': tooling,
'build_argv': build_argv or ['synthetic fixture, no compiler'],
'observer_flags': FLAGS, 'files': _package_files(package)}
_write_json(package / 'fidelity-build.json', record)
return record
def _package(package, rid, tooling):
record = read_json(package / 'fidelity-build.json')
if (record.get('schema_version') != 1 or record.get('rid') != rid or
record.get('observer_flags') != FLAGS or
record.get('files') != _package_files(package)):
raise ValueError('Stale/missing package bytes or observer identity: ' + rid)
if record.get('tooling_only') and not tooling:
raise ValueError('Synthetic package cannot qualify as runtime materials')
return {'build_info': identify_file(package / 'BUILD-INFO.txt'),
'build': {k: v for k, v in record.items() if k != 'files'},
'package_tree_sha256': hashlib.sha256(canonical_bytes(record['files'])).hexdigest(),
'dll': identify_file(package / 'GamePort.dll'),
'executable': identify_file(package / ('GamePort.exe' if rid == 'win-x64' else 'GamePort')),
'resources': {k: {'tree_sha256': identify_tree(package / k)['tree_sha256']}
for k in ('assets', 'scenes', 'audio', 'Shaders')}}
def prepare_checkpoint(original, original_manifest, packages, output, tooling=False):
unresolved = Path(output).absolute()
if any(p.is_symlink() for p in (unresolved, *unresolved.parents)):
raise ValueError('Checkpoint output cannot use symlink aliases')
original, output = separated_roots(original, output)
# Resolve aliases before allocating; reject symlink ancestry even for missing leaves.
candidate = Path(output)
if any(p.is_symlink() for p in (candidate, *candidate.parents)) or candidate.exists():
raise ValueError('Checkpoint output must be a fresh non-symlink directory')
separated_roots(PROJECT.parent / 'Original', output)
if set(packages) != set(RIDS):
raise ValueError('Both identified offline packages are required')
before = verify_inventory(original, original_manifest)
protocol = read_json(PROJECT / 'docs/evidence/scenarios.json')
validate_scenario_contract(protocol)
identities = {}
for rid in RIDS:
package = Path(packages[rid]).resolve(strict=True)
separated_roots(package, output)
identities[rid] = _package(package, rid, tooling)
# Every raw asset shipped by the package must match the original baseline.
if not tooling:
baseline = {f['path'].casefold(): f for f in before['files']}
for f in identify_tree(package / 'assets')['files']:
expected = baseline.get(f['path'].casefold())
if not expected or any(f[k] != expected[k] for k in ('sha256', 'size', 'header')):
raise ValueError('Package raw resource differs from original: ' + f['path'])
output.parent.mkdir(parents=True, exist_ok=True)
lock = output.with_name('.' + output.name.casefold() + '.lock')
try:
lock.mkdir()
except FileExistsError as error:
raise ValueError('Checkpoint reserved; inspect incomplete assembly, never steal lock') from error
temporary = output.with_name('.' + output.name + '.incomplete-' + uuid.uuid4().hex)
temporary.mkdir()
_write_json(temporary / 'incomplete.json', {'status': 'incomplete', 'started_utc': utc_now()})
# On failure retain both the diagnostic sibling and reservation.
_copy_tree(original, temporary / 'original-pristine')
for rid in RIDS:
_copy_tree(packages[rid], temporary / 'port' / rid)
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'):
raise ValueError('Missing collector material: ' + name)
_copy_file(original_manifest, temporary / 'protocol/original-manifest.json')
for name in ('scenarios.json', 'capabilities.json'):
_copy_file(PROJECT / 'docs/evidence' / name, temporary / 'protocol' / name)
export_review(None, None, temporary / 'review', PROJECT / 'docs/evidence/capabilities.json')
for name in MUTABLE:
(temporary / name).mkdir()
# All 80 Windows obligations are prepared; Linux's remaining40 use the same protocol.
agenda = [{'side': side, 'case_id': cell['id'], 'obligation_id': obligation,
'status': 'pending'} for side in ('original-windows-dxwnd', 'port-windows-native')
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}})
verify_inventory(original, original_manifest)
(temporary / 'incomplete.json').unlink()
files = identify_tree(temporary)['files']
manifest = {'schema_version': 1, 'checkpoint_id': output.name,
'created_utc': utc_now(), 'tooling_only': tooling, 'packages': identities,
'original_manifest': identify_file(original_manifest),
'original_pre': {'tree_sha256': before['tree_sha256'], 'count': len(before['files'])},
'files': files, 'mutable_roots': list(MUTABLE),
'acceptance': {'state': 'open', 'remaining': ['Actual original/native captures and human review']}}
_write_json(temporary / 'manifest.json', manifest)
_write_json(temporary / 'READY.json', {'schema_version': 1, 'status': 'prepared',
'manifest': dict(path='manifest.json', **identify_file(temporary / 'manifest.json')),
'acceptance': {'state': 'open'}, 'meaning': 'Materials prepared only; no runtime acceptance'})
preflight(temporary)
if output.exists():
raise ValueError('Output allocated concurrently')
os.rename(temporary, output)
lock.rmdir()
return manifest
def preflight(root, dependencies=None):
root = Path(root)
if root.is_symlink():
raise ValueError('Checkpoint root cannot be a symlink')
ready = read_json(root / 'READY.json')
if ready.get('schema_version') != 1 or ready.get('status') != 'prepared':
raise ValueError('Checkpoint is incomplete, not READY')
actual = identify_file(root / 'manifest.json')
if any(ready['manifest'].get(k) != actual[k] for k in ('sha256', 'size')):
raise ValueError('Manifest identity differs from READY')
manifest = read_json(root / 'manifest.json')
expected = {item['path']: item for item in manifest['files']}
for name, item in expected.items():
actual = identify_file(contained_path(root, name))
if any(item[k] != actual[k] for k in ('sha256', 'size', 'header')):
raise ValueError('Tampered checkpoint material: ' + name)
# Permit only owned result/copy directories to grow after publication.
for directory, dirs, names in os.walk(root, followlinks=False):
for name in dirs + names:
path = Path(directory) / name
relative = path.relative_to(root).as_posix()
if path.is_symlink():
raise ValueError('Symlink in checkpoint: ' + relative)
if path.is_file() and relative.split('/')[0] not in MUTABLE:
if relative not in expected and relative not in ('READY.json', 'manifest.json'):
raise ValueError('Unexpected immutable material: ' + relative)
failures = []
tools = {}
for label, path in (dependencies or {}).items():
try:
tools[label] = dict(path=str(Path(path).resolve()), **identify_file(path))
except (ValueError, OSError):
failures.append('Missing local dependency ' + label + ': select an existing local file (' + str(path) + ')')
return {'schema_version': 1, 'status': 'blocked' if failures else 'ready',
'checked_files': len(expected), 'tooling_only': manifest['tooling_only'],
'tools': tools, 'failures': failures, 'acceptance': {'state': 'open'}}
def fixture_result(bundle, run, session_id, case_id, scope, artifacts):
"""Tooling-only end-to-end importer fixture; cannot mint native evidence."""
preflight(bundle)
_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']:
raise ValueError('Unknown case/scope')
run = Path(run)
items = [dict(path=str(relative_name(p)), role='diagnostic', synthetic=True,
**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,
'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(),
'monotonic_start': 0, 'monotonic_end': 0},
'artifacts': items, 'derivatives': [], 'events': [],
'limitations': ['Synthetic tooling only'], 'missing_evidence': ['No native/reference execution'],
'acceptance': {'state': 'open', 'remaining': ['Actual identified captures and human review']}}
validate_receipt(receipt, run)
_write_json(run / 'receipt.json', receipt)
return receipt
def publish_packages(output, base):
"""Isolated equivalent of existing builds, preserving historical dist packages."""
output, base = Path(output).resolve(), Path(base).resolve()
if output.exists():
raise ValueError('Publish root must be fresh')
separated_roots(base, output)
source = source_identity(PROJECT)
output.mkdir(parents=True)
for rid in RIDS:
target = output / rid
_copy_tree(base / rid, target)
# The old note identifies historical resource packaging, not this compilation.
(target / 'BUILD-INFO.txt').rename(target / 'RESOURCE-BASE-BUILD-INFO.txt')
old_seal = target / 'fidelity-build.json'
if old_seal.exists():
old_seal.unlink()
argv = ['dotnet', 'publish', 'GamePort.csproj', '-c', 'Release', '-r', rid,
'--self-contained', 'true', '--no-restore', '-o', str(target)]
subprocess.run(argv, cwd=PROJECT, check=True, timeout=600)
if source_identity(PROJECT) != source:
raise ValueError('Source changed during publish; preserve diagnostics and republish')
(target / 'BUILD-INFO.txt').write_text('source_commit=' + source['commit'] +
'\nsource_dirty=' + ('yes' if source['dirty'] else 'no') +
'\nsource_diff_sha256=' + source['diff_sha256'] + '\npublished_utc=' + utc_now() + '\n')
seal_package(target, rid, source, build_argv=argv)
return {'status': 'published', 'output': str(output), 'source': source}
def main():
parser = argparse.ArgumentParser(description=__doc__)
sub = parser.add_subparsers(dest='command', required=True)
prepare = sub.add_parser('prepare')
prepare.add_argument('--original', type=Path, default=PROJECT.parent / 'Original')
prepare.add_argument('--original-manifest', type=Path, default=PROJECT / 'docs/original-manifest.json')
prepare.add_argument('--packages', type=Path, required=True)
prepare.add_argument('--output', type=Path, required=True)
check = sub.add_parser('preflight')
check.add_argument('--checkpoint', type=Path, required=True)
publish = sub.add_parser('publish')
publish.add_argument('--output', type=Path, required=True)
publish.add_argument('--base', type=Path, default=PROJECT / 'dist')
args = parser.parse_args()
try:
if args.command == 'prepare':
result = prepare_checkpoint(args.original, args.original_manifest,
{rid: args.packages / rid for rid in RIDS}, args.output)
print('Prepared checkpoint; acceptance OPEN; files:', len(result['files']))
elif args.command == 'publish':
print(canonical_bytes(publish_packages(args.output, args.base)).decode())
else:
print(canonical_bytes(preflight(args.checkpoint)).decode())
return 0
except (ValueError, OSError, subprocess.SubprocessError) as error:
print('Checkpoint failed (acceptance OPEN): ' + str(error), file=sys.stderr)
return 2
if __name__ == '__main__':
sys.exit(main())