From 72523eebb79109b5ffddf593c9cb8ea557a8a20d Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Thu, 12 Nov 2026 23:09:01 -0500 Subject: [PATCH] feat(01-04): observe accepted input with bounded passive output --- .../Application/FidelityObservation.cs | 174 ++++++++++++++++++ src/GamePort/Program.cs | 13 +- 2 files changed, 184 insertions(+), 3 deletions(-) create mode 100644 src/GamePort/Application/FidelityObservation.cs diff --git a/src/GamePort/Application/FidelityObservation.cs b/src/GamePort/Application/FidelityObservation.cs new file mode 100644 index 0000000..305d2fb --- /dev/null +++ b/src/GamePort/Application/FidelityObservation.cs @@ -0,0 +1,174 @@ +using System.Diagnostics; +using System.Text; +using System.Text.Json; +using System.Text.RegularExpressions; +using GamePort.Game; + +namespace GamePort.Application; + +/// Optional application diagnostics. Owns only copied observations and output; +/// it never owns a simulation, callback, input source or continuation payload. +internal sealed class FidelityObservation : IDisposable +{ + private static readonly JsonSerializerOptions Json = new() { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower }; + private readonly Stopwatch clock = Stopwatch.StartNew(); + private readonly string directory, session, caseId, kind; + private readonly DateTimeOffset wallStart = DateTimeOffset.UtcNow; + private readonly int maxRecords; + private const long MaxBytes = 512L * 1024 * 1024; + private TextWriter? writer; + private long sequence, bytes; + private string? failure; + private bool completed, disposed, ownsDirectory; + private double overhead; + + private FidelityObservation(string directory, string session, string caseId, string kind, int maxRecords) + { this.directory = directory; this.session = session; this.caseId = caseId; this.kind = kind; this.maxRecords = maxRecords; } + + public static FidelityObservation? FromArguments(string[] args, string project, string originals) + { + string? Option(string name) + { + var index = Array.IndexOf(args, name); + if (index < 0) return null; + if (index + 1 == args.Length || args[index + 1].StartsWith("--", StringComparison.Ordinal)) + throw new ArgumentException(name + " requires a value"); + if (Array.LastIndexOf(args, name) != index) throw new ArgumentException("Repeated " + name); + return args[index + 1]; + } + var output = Option("--fidelity-output"); + if (output == null) return null; + var session = Option("--fidelity-session") ?? throw new ArgumentException("--fidelity-session required"); + var caseId = Option("--fidelity-case") ?? throw new ArgumentException("--fidelity-case required"); + var fixture = args.Any(a => a.StartsWith("--smoke-", StringComparison.Ordinal) + || a is "--headless" or "--story-time" or "--time" or "--inspect" or "--skip-intro" + or "--noclip" or "--debug-menu" or "--debug-page" or "--gadget-menu"); + return Create(output, session, caseId, fixture ? "port_fixture" : "native_port", project, originals); + } + + public static FidelityObservation Create(string output, string session, string caseId, string kind, + string project, string originals, int maxRecords = 250000, TextWriter? sink = null) + { + foreach (var id in new[] { session, caseId }) + if (!Regex.IsMatch(id, "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", RegexOptions.CultureInvariant)) + throw new ArgumentException("Observation IDs require 1..128 safe characters"); + if (kind is not ("port_fixture" or "native_port") || maxRecords < 1 || maxRecords > 250000) + throw new ArgumentException("Invalid observation category or record limit"); + var path = Path.TrimEndingDirectorySeparator(Path.GetFullPath(output)); + static bool Within(string child, string parent) => child.Equals(parent, StringComparison.OrdinalIgnoreCase) + || child.StartsWith(Path.TrimEndingDirectorySeparator(parent) + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase); + var original = Path.TrimEndingDirectorySeparator(Path.GetFullPath(originals)); + var git = Path.Combine(Path.GetFullPath(project), ".git"); + if (Within(path, original) || Within(original, path) || Within(path, git) || Within(git, path)) + throw new ArgumentException("Observation output must be separate from original assets and Git metadata"); + for (var parent = new DirectoryInfo(path); parent != null; parent = parent.Parent) + if (parent.LinkTarget != null) throw new ArgumentException("Observation output cannot traverse symbolic links"); + if (Directory.Exists(path) || File.Exists(path)) throw new IOException("Observation requires a new output directory"); + var observer = new FidelityObservation(path, session, caseId, kind, maxRecords); + try + { + Directory.CreateDirectory(Path.GetDirectoryName(path)!); + // A cooperative local reservation prevents two observers reusing the same directory. + var reservation = path + ".fidelity-reservation"; + using (new FileStream(reservation, FileMode.CreateNew, FileAccess.Write, FileShare.None)) + { + if (Directory.Exists(path) || File.Exists(path)) throw new IOException("Observation directory was reserved by another writer"); + Directory.CreateDirectory(path); + observer.ownsDirectory = true; + } + File.Delete(reservation); + observer.WriteSummary(false); + observer.writer = sink ?? new StreamWriter(new FileStream(Path.Combine(path, "events.jsonl"), + FileMode.CreateNew, FileAccess.Write, FileShare.Read), new UTF8Encoding(false), 65536); + } + catch (Exception error) when (OutputError(error)) { observer.Fail(error.Message); } + return observer; + } + + public void RecordInput(string scene, int simulationTick, PlayerInput requested, bool acceptsInput, string controlOwner) + => Record("input_step", scene, simulationTick, "post_owner_step", new { + requested_input = requested, accepts_input = acceptsInput, + accepted_input = acceptsInput ? (PlayerInput?)requested : null, + control_owner = controlOwner, + acceptance_scope = "player_binding_input_gate; independent body/fire work is not classified by this boolean" }); + + private void Record(string name, string scene, int simulationTick, string method, object data) + { + if (disposed || completed || failure != null) return; + var started = Stopwatch.GetTimestamp(); + try + { + if (sequence >= maxRecords) throw new IOException("Observation record limit reached"); + var line = JsonSerializer.Serialize(new { schema_version = 1, session_id = session, case_id = caseId, + evidence_kind = kind, clock_id = session + ":stopwatch", sequence = sequence + 1, + elapsed_seconds = clock.Elapsed.TotalSeconds, simulation_tick = simulationTick, + name, scene, method, data }, Json); + var length = Encoding.UTF8.GetByteCount(line) + 1; + if (bytes + length > MaxBytes) throw new IOException("Observation byte limit reached"); + writer!.WriteLine(line); + sequence++; bytes += length; + } + catch (Exception error) when (OutputError(error)) { Fail(error.Message); } + finally { overhead += Stopwatch.GetElapsedTime(started).TotalSeconds; } + } + + public void Complete(int exitCode) + { + if (disposed || completed) return; + if (exitCode != 0) Fail("Port exited with code " + exitCode); + try { writer?.Dispose(); writer = null; } + catch (Exception error) when (OutputError(error)) { Fail(error.Message); } + completed = true; + TrySummary(exitCode == 0 && failure == null); + } + + private static bool OutputError(Exception error) => error is IOException or UnauthorizedAccessException + or System.Security.SecurityException or JsonException or ArgumentException or NotSupportedException; + + private void Fail(string reason) + { + if (failure != null) return; + failure = reason; + Console.Error.WriteLine("Fidelity observation INCOMPLETE: " + reason); + try { writer?.Dispose(); } catch (Exception error) when (OutputError(error)) { } + writer = null; + TrySummary(false); + } + + private void TrySummary(bool success) + { + if (!ownsDirectory) return; + try { WriteSummary(success); } + catch (Exception error) when (OutputError(error)) + { Console.Error.WriteLine("Fidelity observation INCOMPLETE; summary unavailable: " + error.Message); } + } + + private void WriteSummary(bool success) + { + var target = Path.Combine(directory, "observation-summary.json"); + var temporary = target + "." + Guid.NewGuid().ToString("N") + ".tmp"; + var summary = new { schema_version = 1, session_id = session, case_id = caseId, evidence_kind = kind, + clock_id = session + ":stopwatch", wall_start = wallStart, wall_end = DateTimeOffset.UtcNow, + elapsed_seconds = clock.Elapsed.TotalSeconds, records = sequence, bytes, incomplete = !success, + status = success ? "recorded" : "incomplete", failure, + diagnostic = true, observer_seconds = overhead, max_records = maxRecords, max_bytes = MaxBytes, + limitations = new[] { "Diagnostic observer adds serialization, buffered disk writes and state-copy overhead; not a clean audiovisual capture.", + "Observation is not a receipt or an acceptance decision; fixture and native full-route evidence remain distinct.", + "No media clock mapping is inferred. Simulation ticks are scene-local and may reset across continuations.", + "Only named application seams are observed; fixture helper-internal steps are not a complete simulation trace." } }; + try + { + using (var stream = new FileStream(temporary, FileMode.CreateNew, FileAccess.Write, FileShare.None)) + JsonSerializer.Serialize(stream, summary, Json); + File.Move(temporary, target, true); + } + finally { if (File.Exists(temporary)) File.Delete(temporary); } + } + + public void Dispose() + { + if (disposed) return; + if (!completed) { Fail("Session ended without successful completion"); TrySummary(false); } + disposed = true; + } +} diff --git a/src/GamePort/Program.cs b/src/GamePort/Program.cs index ed3bca1..3296a96 100644 --- a/src/GamePort/Program.cs +++ b/src/GamePort/Program.cs @@ -15,6 +15,8 @@ internal static class Program { try { + using var observation = args.Contains("--help") || !args.Contains("--fidelity-output") ? null : FidelityObservation.FromArguments(args, + Directory.GetCurrentDirectory(), AssetPath.FindOriginal(Option(args, "--assets"))); using var presentation = new RenderSession(); OriginalSave? carriedSave = null; PlayerLevelState? carriedPlayer = null; @@ -24,8 +26,8 @@ internal static class Program var grapplerMemory = new GrapplerMemory(); while (true) { - var result = Run(args, carriedSave, carriedPlayer, returning, diagnostics, presentation, energy, grapplerMemory, out var continuation); - if (result != 0 || continuation == null) return result; + var result = Run(args, carriedSave, carriedPlayer, returning, diagnostics, presentation, energy, grapplerMemory, observation, out var continuation); + if (result != 0 || continuation == null) { observation?.Complete(result); return result; } args = continuation.Args; carriedSave = continuation.Save; returning = continuation.Returning; carriedPlayer = continuation.Player; } @@ -45,7 +47,7 @@ internal static class Program private sealed record SceneContinuation(string[] Args, OriginalSave Save, bool Returning, PlayerLevelState? Player); private static int Run(string[] args, OriginalSave? carriedSave, PlayerLevelState? carriedPlayer, bool returning, DebugDiagnostics diagnostics, - RenderSession presentation, PlayerEnergy energy, GrapplerMemory grapplerMemory, out SceneContinuation? continuation) + RenderSession presentation, PlayerEnergy energy, GrapplerMemory grapplerMemory, FidelityObservation? observation, out SceneContinuation? continuation) { continuation = null; if (args.Contains("--help")) @@ -69,6 +71,9 @@ internal static class Program --start TAG Use a named original STRT checkpoint --load-save PATH Resume original TSK task/items/checkpoint state --write-save PATH Write checkpoint state as TSK outside asset directory + --fidelity-output PATH New local diagnostic session directory + --fidelity-session ID Stable session identity across scene continuations + --fidelity-case ID Declared comparison case; does not establish acceptance --mute Disable scene audio --time SECONDS Fixed animation time for comparisons --headless Render offscreen through Vulkan @@ -1294,6 +1299,8 @@ internal static class Program bool acceptsInput; if (playerBinding != null) acceptsInput = playerBinding.Step(input); else { simulation.Step(input); acceptsInput = true; } + observation?.RecordInput(level?.Code ?? "preview", simulation.Steps, input, acceptsInput, + director?.ControlledTag ?? (playerBinding == null ? "direct-simulation" : "script")); scooterFixture?.Received(input); grapplerFixture?.Received(input); rocketFixture?.Received(input);