Record a launch receipt and revalidate cheaply before subsequent launches

[bobtista]

Problem

There is no record of what a launch actually consisted of. When a launch misbehaves — wrong content, wrong variant, unexpected engine build — there is nothing to compare against.

Proposed approach

Record a receipt per launch capturing:

• Retail archive roots
• Archive fingerprints
• Environment
• Variant
• Engine identity

Then perform cheap revalidation against the receipt before a subsequent launch, so drift is detected without a full re-scan.

Why it matters beyond debugging

This is a prerequisite for LAN and determinism work: without a verifiable record of what each participant launched, desync investigation is guesswork.

Acceptance criteria

• Every launch produces a receipt.
• Pre-launch revalidation is cheap enough to run every time.
• Drift between receipt and current state is detected and surfaced.

[coderabbitai]

Coding Plan

Summary

• Add a durable, JSON-backed LaunchReceipt model + ILaunchReceiptStore under AppData, modeled directly on the existing UserDataTrackerService/UserDataManifest persistence pattern, kept separate from the in-memory LaunchRegistry.
• Populate the receipt from data already converging in GameLauncher.LaunchProfileAsync (installation roots, manifest file hashes, client/engine identity + one-time exe hash, workspace roll-ups, env/args/variant), writing it on every successful launch.
• Provide cheap pre-launch revalidation using the codebase's existing existence→size (hash-on-demand) tiering, surfacing drift through the standard ValidationResult/ValidationIssue and notification channels.
• Deliberately scope out actual LAN/desync/replay features; this delivers only the verifiable launch record and cheap drift detection that those future efforts depend on.

Design Choices

Design Choice 1: Where should launch receipts be persisted?

Options Considered:

1. Store under the AppData root via IConfigurationProviderService.GetApplicationDataPath() (same convention as UserDataTrackerService).
2. Store installation-adjacent via IStorageLocationService alongside CAS/workspace data.

Chosen Option: 1

Rationale: Receipts are audit artifacts that are app-level history not tied to a single install's storage preference, so the AppData convention used by UserDataTrackerService is the most consistent and simplest fit.

Design Choice 2: Should the receipt extend the existing in-memory LaunchRegistry/GameLaunchInfo or be a separate durable store?

Options Considered:

1. Add a separate ILaunchReceiptStore with its own JSON persistence, keeping LaunchRegistry unchanged.
2. Rework LaunchRegistry to persist to disk and carry receipt provenance.

Chosen Option: 1

Rationale: Keeps the live-tracking and durable-audit concerns cleanly separated, avoids disturbing the sensitive two-phase placeholder registration, and mirrors the existing UserDataTrackerService durable-store pattern.

Design Choice 3: How is "engine identity" fingerprinted while keeping revalidation cheap?

Options Considered:

1. Compute the executable SHA-256 once at receipt-write time; on revalidation only check existence/size/version by default.
2. Recompute the executable hash on every pre-launch revalidation.

Chosen Option: 1

Rationale: Satisfies the "cheap enough to run every time" acceptance criterion while still storing a strong fingerprint for later (LAN/determinism) comparison and on-demand deep verification.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Launch Receipt Model and Durable Store

Introduce the receipt data model that unifies the five ticket concepts and a JSON-backed store to persist and retrieve receipts. This phase establishes the persistence foundation modeled directly on the existing UserDataTrackerService/UserDataManifest pattern.

Task 1: Define the launch receipt data model

Create a serializable model capturing everything a launch consisted of.

• Add LaunchReceipt (and a LaunchReceiptFileEntry companion) under GenHub.Core/Models/Launching/, mirroring the shape of UserDataManifest/UserDataFileEntry.
• Capture identity/linkage: LaunchId, ProfileId, WorkspaceId, LaunchedAt, LastVerifiedAt, schema/receipt version.
• Capture retail archive roots: BaseInstallationPath, resolved GeneralsPath/ZeroHourPath, and the per-manifest source-root map (from WorkspaceConfiguration.ManifestSourcePaths).
• Capture archive fingerprints: the applied ManifestIds, workspace roll-ups (FileCount, TotalSizeBytes), and a set of LaunchReceiptFileEntry records (RelativePath, Size, Hash, IsExecutable) sourced from the resolved manifests' ManifestFile data.
• Capture environment: snapshot of EnvironmentVariables, the launch Arguments, and the install source (GameInstallationType/InstallationSourceConstants).
• Capture variant: GameType, EnabledContentIds, WorkspaceStrategy, and the GameClientIdentification variant/publisher fields when available.
• Capture engine identity: executable path, client version/publisher, and the executable SHA-256 hash.

Task 2: Define the receipt store interface and implementation

Provide durable persistence and retrieval keyed for both per-launch history and latest-per-profile lookup.

• Add ILaunchReceiptStore in GenHub.Core/Interfaces/Launching/ with methods to save a receipt, get a receipt by LaunchId, and get the latest receipt for a ProfileId.
• Implement LaunchReceiptStore in GenHub/Features/Launching/, following UserDataTrackerService: resolve a receipts/ folder under IConfigurationProviderService.GetApplicationDataPath(), write one JSON file per receipt, and maintain a lightweight index.json mapping ProfileId → latest LaunchId and LaunchId → file.
• Reuse the established serialization/concurrency conventions: shared JsonSerializerOptions { WriteIndented = true }, File.ReadAllTextAsync/WriteAllTextAsync, try/catch self-healing reads returning null on corrupt files, and a SemaphoreSlim-guarded index with an in-memory cached copy.

Task 3: Register the store in DI

Wire the new store into the launching module.

• Update GenHub/Infrastructure/DependencyInjection/GameLaunchingModule.cs to register ILaunchReceiptStore → LaunchReceiptStore as a singleton (global durable tracker, matching the ILaunchRegistry lifetime rationale), with an explanatory comment.

🤖 Prompt for AI agents

Implement the launch receipt data model and its durable JSON-backed store,
establishing the persistence foundation for launch receipts.

- Add `LaunchReceipt` and a `LaunchReceiptFileEntry` companion model under
`GenHub.Core/Models/Launching/`, mirroring the shape of
`UserDataManifest`/`UserDataFileEntry`.
- Identity/linkage fields: `LaunchId`, `ProfileId`, `WorkspaceId`, `LaunchedAt`,
`LastVerifiedAt`, schema/receipt version.
- Retail archive roots: `BaseInstallationPath`, resolved
`GeneralsPath`/`ZeroHourPath`, and the per-manifest source-root map (from
`WorkspaceConfiguration.ManifestSourcePaths`).
- Archive fingerprints: applied `ManifestIds`, workspace roll-ups (`FileCount`,
`TotalSizeBytes`), and a set of `LaunchReceiptFileEntry` records
(`RelativePath`, `Size`, `Hash`, `IsExecutable`) sourced from the resolved
manifests' `ManifestFile` data.
- Environment: snapshot of `EnvironmentVariables`, the launch `Arguments`, and
the install source (`GameInstallationType`/`InstallationSourceConstants`).
- Variant: `GameType`, `EnabledContentIds`, `WorkspaceStrategy`, and the
`GameClientIdentification` variant/publisher fields when available.
- Engine identity: executable path, client version/publisher, and the executable
SHA-256 hash.

- Add `ILaunchReceiptStore` interface under `GenHub.Core/Interfaces/Launching/`
with methods to save a receipt, get a receipt by `LaunchId`, and get the latest
receipt for a `ProfileId`.

- Implement `LaunchReceiptStore` in `GenHub/Features/Launching/`, following the
`UserDataTrackerService` pattern:
- Resolve a `receipts/` folder under
`IConfigurationProviderService.GetApplicationDataPath()`.
  - Write one JSON file per receipt.
- Maintain a lightweight `index.json` mapping `ProfileId → latest LaunchId` and
`LaunchId → file`.
- Reuse established conventions: shared `JsonSerializerOptions { WriteIndented =
true }`, `File.ReadAllTextAsync`/`WriteAllTextAsync`, try/catch self-healing
reads returning `null` on corrupt files, and a `SemaphoreSlim`-guarded index
with an in-memory cached copy.

- Register `ILaunchReceiptStore → LaunchReceiptStore` as a singleton in
`GenHub/Infrastructure/DependencyInjection/GameLaunchingModule.cs` (global
durable tracker, matching the `ILaunchRegistry` lifetime rationale), including
an explanatory comment.

Phase 2: Capture a Receipt on Every Launch

Hook receipt creation into the existing launch pipeline so that each successful launch produces a durable receipt, satisfying the "every launch produces a receipt" criterion.

Build and persist the receipt during launch

Assemble the receipt from data already in scope at launch time.

• In GenHub/Features/Launching/GameLauncher.cs (LaunchProfileAsync), after the workspace is prepared and the process has started (where actualInstallationPath, resolved manifests, gameClient, workspaceConfig/workspaceInfo, and the constructed GameLaunchConfiguration/final GameLaunchInfo are all available), construct a LaunchReceipt and persist it via ILaunchReceiptStore.SaveReceiptAsync.
• Inject ILaunchReceiptStore (and IFileHashProvider for the one-time executable hash) into GameLauncher's primary constructor.
• Compute the executable SHA-256 once here for engine identity; populate file-fingerprint entries from the resolved manifests rather than re-scanning the workspace.
• Treat receipt writing as non-fatal: log and continue if persistence fails, so it never blocks an otherwise successful launch.

🤖 Prompt for AI agents

Hook receipt creation into the launch pipeline so every successful launch
produces a durable receipt.

- In `GenHub/Features/Launching/GameLauncher.cs`, within `LaunchProfileAsync`,
after the workspace is prepared and the process has started (at the point where
`actualInstallationPath`, resolved `manifests`, `gameClient`,
`workspaceConfig`/`workspaceInfo`, and the constructed
`GameLaunchConfiguration`/final `GameLaunchInfo` are all available), construct a
`LaunchReceipt` and persist it via `ILaunchReceiptStore.SaveReceiptAsync`.
- Inject `ILaunchReceiptStore` and `IFileHashProvider` into `GameLauncher`'s
primary constructor.
- Compute the executable SHA-256 hash once at this point for engine identity.
- Populate file-fingerprint entries from the resolved manifests rather than
re-scanning the workspace.
- Treat receipt writing as non-fatal: log and continue if persistence fails,
ensuring it never blocks an otherwise successful launch.

Phase 3: Cheap Pre-Launch Revalidation and Drift Surfacing

Compare current state to the most recent receipt cheaply before launching and surface any drift, satisfying the "cheap enough to run every time" and "drift detected and surfaced" criteria.

Task 1: Implement cheap receipt revalidation

Add a revalidation routine that detects drift without a full re-scan.

• Add a revalidation capability (e.g., a LaunchReceiptValidator in GenHub/Features/Launching/, or a method on the store's owning service) that loads the latest receipt for a profile and compares it against current state.
• Use the existing tiered cheap pattern (from WorkspaceReconciler.FileNeedsUpdateAsync/FileSystemValidator): check archive-root directory existence, executable existence, and per-entry File.Exists + size match; compare recorded ManifestIds, EnabledContentIds, WorkspaceStrategy, environment/argument snapshot, and stored executable version — all without hashing by default.
• Return the existing ValidationResult/ValidationIssue types (reusing IssueType values like MissingFile, MismatchedFileSize, DirectoryMissing, and Warning/Error severities) so drift is represented in the codebase's standard validation shape; reserve executable-hash recomputation for an explicit deep-check path only.
• Stamp LastVerifiedAt on the receipt after a successful cheap pass, mirroring UserDataTrackerService.VerifyInstallationAsync.

Task 2: Integrate revalidation into the pre-launch flow and surface drift

Run revalidation before each launch and report results to the user.

• Invoke the revalidation during the existing pre-launch validation stage — either within ProfileLauncherFacade.ValidateLaunchAsync or at the start of GameLauncher.LaunchProfileAsync (during the ValidatingProfile phase) — when a prior receipt exists for the profile.
• Surface detected drift via the existing notificationService (warnings) and/or LaunchProgress/ValidationResult channels; treat drift as informational/warning by default (non-blocking) so a first-launch-with-no-receipt path is unaffected.

Task 3: Add tests for the store, capture, and revalidation

Cover the new components following existing Launching test conventions.

• Add LaunchReceiptStoreTests under GenHub.Tests/GenHub.Tests.Core/Features/Launching/ following LaunchRegistryTests conventions: mock only the logger/config provider, instantiate the real store, and exercise save/get/latest round-trips with inline LaunchReceipt fixtures.
• Extend GameLauncherTests to mock ILaunchReceiptStore (and IFileHashProvider), verifying a receipt is saved on successful launch (Mock.Verify(..., Times.Once)), consistent with the existing two-phase registry verification style.
• Add revalidation tests asserting drift cases (missing archive root, missing/size-mismatched file, changed manifest/variant) produce the expected ValidationIssues and that a matching state produces a valid result.

🤖 Prompt for AI agents

Implement cheap pre-launch revalidation against the most recent receipt and
surface any detected drift, plus add test coverage for the new components.

- Add a revalidation capability (e.g., a `LaunchReceiptValidator` in
`GenHub/Features/Launching/`, or a method on the store's owning service) that
loads the latest receipt for a profile and compares it against current state.
- Use the existing tiered cheap pattern (from
`WorkspaceReconciler.FileNeedsUpdateAsync`/`FileSystemValidator`):
- Check archive-root directory existence, executable existence, and per-entry
`File.Exists` + size match.
- Compare recorded `ManifestIds`, `EnabledContentIds`, `WorkspaceStrategy`,
environment/argument snapshot, and stored executable version — all without
hashing by default.
- Return the existing `ValidationResult`/`ValidationIssue` types, reusing
`IssueType` values like `MissingFile`, `MismatchedFileSize`, `DirectoryMissing`,
and `Warning`/`Error` severities, so drift is represented in the codebase's
standard validation shape. Reserve executable-hash recomputation for an explicit
deep-check path only.
- Stamp `LastVerifiedAt` on the receipt after a successful cheap pass, mirroring
`UserDataTrackerService.VerifyInstallationAsync`.
- Invoke the revalidation during the existing pre-launch validation stage —
either within `ProfileLauncherFacade.ValidateLaunchAsync` or at the start of
`GameLauncher.LaunchProfileAsync` (during the `ValidatingProfile` phase) — when
a prior receipt exists for the profile.
- Surface detected drift via the existing `notificationService` (warnings)
and/or `LaunchProgress`/`ValidationResult` channels; treat drift as
informational/warning by default (non-blocking) so a
first-launch-with-no-receipt path is unaffected.
- Add `LaunchReceiptStoreTests` under
`GenHub.Tests/GenHub.Tests.Core/Features/Launching/` following
`LaunchRegistryTests` conventions: mock only the logger/config provider,
instantiate the real store, and exercise save/get/latest round-trips with inline
`LaunchReceipt` fixtures.
- Extend `GameLauncherTests` to mock `ILaunchReceiptStore` and
`IFileHashProvider`, verifying a receipt is saved on successful launch
(`Mock.Verify(..., Times.Once)`), consistent with the existing two-phase
registry verification style.
- Add revalidation tests asserting drift cases (missing archive root,
missing/size-mismatched file, changed manifest/variant) produce the expected
`ValidationIssue`s and that a matching state produces a valid result.

Research

GenHub launches games through ProfileLauncherFacade → GameLauncher → GameProcessManager. GameLauncher.LaunchProfileAsync is the point where all launch inputs converge: resolved GameInstallation paths, resolved ContentManifests (with per-file ManifestFile.Hash), the GameClient (engine identity), the prepared WorkspaceInfo (with ManifestIds/FileCount/TotalSizeBytes), and the constructed GameLaunchConfiguration (env vars, arguments). Today the only launch record is the in-memory LaunchRegistry (ConcurrentDictionary of GameLaunchInfo), which is lost on restart and has no provenance data. Durable JSON state elsewhere follows the UserDataTrackerService pattern (AppData path via IConfigurationProviderService, per-entity file + index.json, SemaphoreSlim guard, self-healing reads, existence-first/hash-on-demand verification). Validation uses IValidator<T> + ValidationResult/ValidationIssue with a severity gate and a cheap-existence/size → optional-hash tiering already present in FileSystemValidator and WorkspaceReconciler.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the launch receipt data model and its durable JSON-backed store,
establishing the persistence foundation for launch receipts.

- Add `LaunchReceipt` and a `LaunchReceiptFileEntry` companion model under
`GenHub.Core/Models/Launching/`, mirroring the shape of
`UserDataManifest`/`UserDataFileEntry`.
- Identity/linkage fields: `LaunchId`, `ProfileId`, `WorkspaceId`, `LaunchedAt`,
`LastVerifiedAt`, schema/receipt version.
- Retail archive roots: `BaseInstallationPath`, resolved
`GeneralsPath`/`ZeroHourPath`, and the per-manifest source-root map (from
`WorkspaceConfiguration.ManifestSourcePaths`).
- Archive fingerprints: applied `ManifestIds`, workspace roll-ups (`FileCount`,
`TotalSizeBytes`), and a set of `LaunchReceiptFileEntry` records
(`RelativePath`, `Size`, `Hash`, `IsExecutable`) sourced from the resolved
manifests' `ManifestFile` data.
- Environment: snapshot of `EnvironmentVariables`, the launch `Arguments`, and
the install source (`GameInstallationType`/`InstallationSourceConstants`).
- Variant: `GameType`, `EnabledContentIds`, `WorkspaceStrategy`, and the
`GameClientIdentification` variant/publisher fields when available.
- Engine identity: executable path, client version/publisher, and the executable
SHA-256 hash.

- Add `ILaunchReceiptStore` interface under `GenHub.Core/Interfaces/Launching/`
with methods to save a receipt, get a receipt by `LaunchId`, and get the latest
receipt for a `ProfileId`.

- Implement `LaunchReceiptStore` in `GenHub/Features/Launching/`, following the
`UserDataTrackerService` pattern:
- Resolve a `receipts/` folder under
`IConfigurationProviderService.GetApplicationDataPath()`.
  - Write one JSON file per receipt.
- Maintain a lightweight `index.json` mapping `ProfileId → latest LaunchId` and
`LaunchId → file`.
- Reuse established conventions: shared `JsonSerializerOptions { WriteIndented =
true }`, `File.ReadAllTextAsync`/`WriteAllTextAsync`, try/catch self-healing
reads returning `null` on corrupt files, and a `SemaphoreSlim`-guarded index
with an in-memory cached copy.

- Register `ILaunchReceiptStore → LaunchReceiptStore` as a singleton in
`GenHub/Infrastructure/DependencyInjection/GameLaunchingModule.cs` (global
durable tracker, matching the `ILaunchRegistry` lifetime rationale), including
an explanatory comment.
===============================================================================

Task: 2

Hook receipt creation into the launch pipeline so every successful launch
produces a durable receipt.

- In `GenHub/Features/Launching/GameLauncher.cs`, within `LaunchProfileAsync`,
after the workspace is prepared and the process has started (at the point where
`actualInstallationPath`, resolved `manifests`, `gameClient`,
`workspaceConfig`/`workspaceInfo`, and the constructed
`GameLaunchConfiguration`/final `GameLaunchInfo` are all available), construct a
`LaunchReceipt` and persist it via `ILaunchReceiptStore.SaveReceiptAsync`.
- Inject `ILaunchReceiptStore` and `IFileHashProvider` into `GameLauncher`'s
primary constructor.
- Compute the executable SHA-256 hash once at this point for engine identity.
- Populate file-fingerprint entries from the resolved manifests rather than
re-scanning the workspace.
- Treat receipt writing as non-fatal: log and continue if persistence fails,
ensuring it never blocks an otherwise successful launch.
===============================================================================

Task: 3

Implement cheap pre-launch revalidation against the most recent receipt and
surface any detected drift, plus add test coverage for the new components.

- Add a revalidation capability (e.g., a `LaunchReceiptValidator` in
`GenHub/Features/Launching/`, or a method on the store's owning service) that
loads the latest receipt for a profile and compares it against current state.
- Use the existing tiered cheap pattern (from
`WorkspaceReconciler.FileNeedsUpdateAsync`/`FileSystemValidator`):
- Check archive-root directory existence, executable existence, and per-entry
`File.Exists` + size match.
- Compare recorded `ManifestIds`, `EnabledContentIds`, `WorkspaceStrategy`,
environment/argument snapshot, and stored executable version — all without
hashing by default.
- Return the existing `ValidationResult`/`ValidationIssue` types, reusing
`IssueType` values like `MissingFile`, `MismatchedFileSize`, `DirectoryMissing`,
and `Warning`/`Error` severities, so drift is represented in the codebase's
standard validation shape. Reserve executable-hash recomputation for an explicit
deep-check path only.
- Stamp `LastVerifiedAt` on the receipt after a successful cheap pass, mirroring
`UserDataTrackerService.VerifyInstallationAsync`.
- Invoke the revalidation during the existing pre-launch validation stage —
either within `ProfileLauncherFacade.ValidateLaunchAsync` or at the start of
`GameLauncher.LaunchProfileAsync` (during the `ValidatingProfile` phase) — when
a prior receipt exists for the profile.
- Surface detected drift via the existing `notificationService` (warnings)
and/or `LaunchProgress`/`ValidationResult` channels; treat drift as
informational/warning by default (non-blocking) so a
first-launch-with-no-receipt path is unaffected.
- Add `LaunchReceiptStoreTests` under
`GenHub.Tests/GenHub.Tests.Core/Features/Launching/` following
`LaunchRegistryTests` conventions: mock only the logger/config provider,
instantiate the real store, and exercise save/get/latest round-trips with inline
`LaunchReceipt` fixtures.
- Extend `GameLauncherTests` to mock `ILaunchReceiptStore` and
`IFileHashProvider`, verifying a receipt is saved on successful launch
(`Mock.Verify(..., Times.Once)`), consistent with the existing two-phase
registry verification style.
- Add revalidation tests asserting drift cases (missing archive root,
missing/size-mismatched file, changed manifest/variant) produce the expected
`ValidationIssue`s and that a matching state produces a valid result.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!