Files
Neutron/scripts/collect-fidelity-windows.ps1

446 lines
27 KiB
PowerShell

# 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,
[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
$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 = (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')
$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()
$started = $false
try {
$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)) {
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'
}
}
$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 ($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=''}
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' }
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 $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') }
# 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 ($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' }
$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' }
$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)'
$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 {
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 'failure.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
$runPath = Join-Path $run 'run.json'
$recovering = -not (Test-Path -LiteralPath $runPath)
if ($recovering) {
if ($Outcome -ne 'aborted') { throw 'Interrupted initial record can only be finalized as aborted' }
$runPath = Join-Path $run 'incomplete.json'
}
$receipt = Read-FidelityJson $runPath
if ($recovering) {
if ($receipt.status -ne 'incomplete' -or $receipt.session_id -cne $SessionId) { throw 'Interrupted initial record does not match the incomplete session' }
# Initial records from older collectors contain placeholder end values.
# Neither those placeholders nor recovery time observed the process end.
$receipt.clocks.PSObject.Properties.Remove('wall_end')
$receipt.clocks.PSObject.Properties.Remove('monotonic_end')
$receipt.missing_evidence += 'Interrupted collector: end clocks and launch-aligned observations unavailable'
$receipt | Add-Member -Force -NotePropertyName diagnostic -NotePropertyValue $true
}
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 ($recovering -and @($annotation.events).Count) { throw 'Interrupted run has no observed end interval; retain annotations without launch-aligned events' }
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 = @()
if ($recovering) {
$initial = Copy-FidelityEvidence $runPath $run 'recovery-initial.json'
$initial.role = 'diagnostic'
$receipt.artifacts += $initial
}
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 | 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 "Result saved ($requested); 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
}