Reject multi-variant manifests at ingestion until .Files consumers are migrated

[bobtista]

Problem

The content model is gaining a Variants concept, but every existing consumer — deliverers, validators, CAS refcounting and GC — still reads .Files. A manifest that declares variants would be accepted by ingestion and then silently mishandled downstream, because nothing in the pipeline understands the resolved-variant shape yet.

Why this is first

This is a fail-closed gate that buys time for the real migration (see the .Files → ResolvedArtifact issue). Until that migration lands, this gate is the only protection against a provider publishing a Variants manifest and corrupting refcounting or GC state.

It must land before any provider is able to publish such a manifest, not after.

Proposed approach

• Reject manifests declaring variants at ingestion, explicitly and loudly — no partial handling, no best-effort fallback.
• Bump the manifest schema version so the rejection is attributable to a known version rather than a parse failure.
• Error message should name the migration as the unblock condition, so the rejection is self-explaining when a provider hits it.

Acceptance criteria

• A manifest declaring variants is rejected at ingestion with a clear, actionable error.
• Manifest version is bumped and the gate keys off it.
• Existing single-variant manifests are unaffected.
• Test coverage for both the rejection path and the unaffected legacy path.

Notes

Ships inside stack PR 2 (feat/platform-neutral-model).

[coderabbitai]

Coding Plan

Summary

• Implement the ticket body's actual requirement: a pre-spawn retail-archive-root existence check, ignoring the mismatched "multi-variant manifest" title (confirmed to have no corresponding code gap).
• Reuse GenHub's established preflight pattern (PreflightCasCheckAsync) — a private OperationResult<bool> check inserted right after installation-path resolution and before workspace prep/spawn, surfaced as a standard LaunchOperationResult failure.
• Validate each configured retail root with a negligible-cost existence check for sentinel .big archives (per-GameType candidate names aligned with existing LanguageDetector conventions), failing with a diagnostic that names the offending root.
• Guard the behavior with focused unit tests covering the fail-before-spawn and unchanged-happy-path acceptance criteria.

Design Choices

Design Choice 1: What should count as the "sentinel `.big` archive" for a valid retail root?

Options Considered:

1. Check that at least one *.big file exists directly under the resolved root (glob existence check).
2. Check for one specific canonical filename per game type (e.g., a Generals base archive vs. a ZH-suffixed archive for Zero Hour).
3. Check for a small game-type-specific set of candidate sentinel names, passing if any one is present.

Chosen Option: 3

Rationale: The ticket requires an existence-only check but does not name a specific file. Retail .big filenames vary by language/edition, so a single hardcoded filename risks false negatives, while "any .big" risks passing a partially-populated folder. Option 3 — define a short per-GameType candidate list (Generals base-name archive(s), and ZH-suffixed archive(s) for Zero Hour, aligned with the existing LanguageDetector naming convention) and pass if any candidate exists; this is resilient to language/edition variation while still being a pure existence check with negligible cost, and it stays consistent with the codebase's existing .big naming knowledge.

💡 User Tips

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

Implementation Steps

Phase 1: Introduce retail-archive sentinel definitions

Establish the shared, reusable knowledge of which .big archive(s) indicate a genuinely populated retail root for each game type, so the launch pipeline (and any future callers) have a single source of truth rather than scattered literals.

Add sentinel archive name constants

Create a canonical, per-GameType set of sentinel .big filenames used to prove a retail root is populated.

• Add a new constants surface for retail archive sentinels under GenHub/GenHub.Core/Constants/ (either a new RetailArchiveConstants.cs or an addition to GameClientConstants.cs, following the existing executable-name constant style).
• Define a small candidate list per game type, aligned with the existing LanguageDetector convention: base-name .big archive(s) for GameType.Generals and ZH-suffixed archive(s) (e.g. INIZH.big, EnglishZH.big) for GameType.ZeroHour.
• Keep this purely declarative (filenames only); no parsing or hashing logic. This is metadata for an existence check.

🤖 Prompt for AI agents

Implement Phase 1: establish a single source of truth for which `.big` archive
filenames indicate a genuinely populated retail root for each game type.

- Add a new constants surface for retail archive sentinels under
`GenHub/GenHub.Core/Constants/` — either create a new
`RetailArchiveConstants.cs` file, or add to the existing
`GameClientConstants.cs`, following the existing executable-name constant style
used in that file/folder.
- Define a small candidate filename list per `GameType`, aligned with the
existing `LanguageDetector` naming convention: base-name `.big` archive(s) for
`GameType.Generals`, and `ZH`-suffixed archive(s) (e.g. `INIZH.big`,
`EnglishZH.big`) for `GameType.ZeroHour`.
- Keep this purely declarative — filenames only, no parsing or hashing logic —
since this is metadata to be used later for an existence check.

Phase 2: Enforce retail archive root validation before spawn

Insert a preflight validation step into the existing launch flow that runs after the retail installation path is resolved and before any workspace preparation or process spawn, mirroring the established PreflightCasCheckAsync pattern so failures are surfaced as normal launch failures with a clear, root-naming message.

Task 1: Add a retail-archive-root preflight check to GameLauncher

Add an internal preflight method and wire it into the launch sequence.

• In GenHub/GenHub/Features/Launching/GameLauncher.cs, add a private PreflightRetailArchiveRootCheckAsync(...) that returns OperationResult<bool>, mirroring the signature/error-handling/logging style of the existing PreflightCasCheckAsync.
• The method accepts the resolved retail archive root(s) and the GameType, and verifies (via Directory.Exists + a .big existence check using the Phase 1 sentinels) that each configured root contains game archives. Use an existence-only check (e.g., Directory.EnumerateFiles(root, "*.big") short-circuited / candidate-name File.Exists); do not open or parse archives, keeping cost negligible.
• On failure, return CreateFailure with a diagnostic that names the specific offending root and game type (e.g., "No game data archives (.big) found under retail root '' for ; the installation appears empty or misconfigured.").
• Invoke this check inside the private LaunchProfileAsync core method immediately after actualInstallationPath is resolved and its existing string.IsNullOrEmpty null-check passes, and before WorkspaceConfiguration is built / workspaceManager.PrepareWorkspaceAsync is called.
• Follow the existing conversion pattern: on !result.Success, log an error and return LaunchOperationResult<GameLaunchInfo>.CreateFailure(result.FirstError ?? "...", launchId, profile.Id);. Remain within the current PreparingWorkspace progress window (no new LaunchPhase enum value needed), consistent with how the CAS preflight reports.

Task 2: Cover the configured multi-root case

Ensure validation reflects the "each configured root" wording of the ticket without over-reaching into unrelated content sources.

• Treat the resolved actualInstallationPath (the retail installation root for the profile's GameType) as the primary retail archive root to validate.
• If more than one retail root can feed a given launch, pass the relevant roots into the check as a collection so the diagnostic can name whichever specific root fails; validate each independently and fail on the first empty/misconfigured one.
• Deliberately exclude non-retail content source directories (e.g., mod/content manifestSourcePaths) from this check — those are not "retail archive roots" and are already covered by CAS/manifest preflight. Note this exclusion explicitly to avoid scope creep.

🤖 Prompt for AI agents

Implement Phase 2: add a preflight validation step to the launch pipeline that
runs after the retail installation path is resolved and before workspace
preparation/process spawn, mirroring the existing `PreflightCasCheckAsync`
pattern.

- In `GenHub/GenHub/Features/Launching/GameLauncher.cs`, add a private
`PreflightRetailArchiveRootCheckAsync(...)` returning `OperationResult<bool>`,
matching the signature/error-handling/logging style of `PreflightCasCheckAsync`.
- The method accepts the resolved retail archive root(s) and the `GameType`, and
verifies via `Directory.Exists` plus a `.big` existence check (using the Phase 1
sentinel candidate names) that each configured root contains game archives. Use
an existence-only check (e.g., `Directory.EnumerateFiles(root, "*.big")`
short-circuited, or candidate-name `File.Exists`) — do not open or parse archive
contents, to keep cost negligible.
- On failure, return `CreateFailure` with a diagnostic naming the specific
offending root and game type, e.g. "No game data archives (.big) found under
retail root '<path>' for <GameType>; the installation appears empty or
misconfigured."
- Wire the call into the private `LaunchProfileAsync` core method immediately
after `actualInstallationPath` is resolved and its existing
`string.IsNullOrEmpty` null-check passes, and before `WorkspaceConfiguration` is
built / `workspaceManager.PrepareWorkspaceAsync` is invoked.
- Follow the existing conversion pattern on failure: log an error and `return
LaunchOperationResult<GameLaunchInfo>.CreateFailure(result.FirstError ?? "...",
launchId, profile.Id);`. Remain within the current `PreparingWorkspace` progress
window — do not add a new `LaunchPhase` enum value.
- Treat the resolved `actualInstallationPath` as the primary retail archive root
to validate for the profile's `GameType`. If more than one retail root can feed
a given launch, pass the roots as a collection into the check so the diagnostic
can name whichever specific root fails; validate each independently and fail on
the first empty/misconfigured one.
- Deliberately exclude non-retail content source directories (e.g., mod/content
`manifestSourcePaths`) from this check, since those are not "retail archive
roots" and are already covered by CAS/manifest preflight — note this exclusion
explicitly to avoid scope creep.

Phase 3: Tests

Validate the new behavior against the acceptance criteria using the established launcher test patterns.

Add launcher unit tests for archive-root validation

Add failure-path and happy-path coverage.

• In GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Launching/GameLauncherTests.cs, add a test that configures a retail root with no .big sentinel present and asserts result.Success == false with result.FirstError containing the offending root path / actionable message, and that processManager.StartProcessAsync / workspaceManager.PrepareWorkspaceAsync are not invoked (fails before spawn).
• Add/adjust the "happy path" setup so the mocked installation root reports a present sentinel .big, confirming a correctly configured root launches unchanged (existing passing tests must continue to pass — update the shared constructor GameInstallation/path setup so the default fixture satisfies the new check).
• Follow the existing failure-path test pattern (LaunchProfileAsync_WithWorkspaceFailure_ShouldFail, etc.): set up a single condition, call LaunchProfileAsync(profile.Id), assert on result.Success / result.FirstError.

🤖 Prompt for AI agents

Implement Phase 3: add unit test coverage for the retail archive root validation
added in Phase 2, following existing launcher test patterns.

- In
`GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Launching/GameLauncherTests.cs`,
add a failure-path test that configures a retail root with no `.big` sentinel
present and asserts `result.Success == false` with `result.FirstError`
containing the offending root path / actionable message, and asserts that
`processManager.StartProcessAsync` and `workspaceManager.PrepareWorkspaceAsync`
are NOT invoked (i.e., the launch fails before spawn).
- Add or adjust the "happy path" setup so the mocked installation root reports a
present sentinel `.big` file, confirming a correctly configured root launches
unchanged; update the shared constructor `GameInstallation`/path setup so the
default fixture satisfies the new check and all existing passing tests continue
to pass.
- Follow the existing failure-path test pattern used by tests like
`LaunchProfileAsync_WithWorkspaceFailure_ShouldFail`: set up a single condition,
call `LaunchProfileAsync(profile.Id)`, and assert on `result.Success` /
`result.FirstError`.

Research

GenHub launches a profile through ProfileLauncherFacade → GameLauncher.LaunchProfileAsync → WorkspaceManager.PrepareWorkspaceAsync → GameProcessManager.StartProcessAsync → Process.Start(). The launch pipeline already has a "multi-root" concept: a retail installation root (GameInstallation.GeneralsPath / ZeroHourPath, resolved into actualInstallationPath) where the retail .big archives physically live, and a prepared workspace root that is actually executed from. GameLauncher already performs several pre-spawn preflight checks (notably PreflightCasCheckAsync) that return OperationResult<bool> and are converted into LaunchOperationResult<GameLaunchInfo>.CreateFailure(...) on failure, all within the PreparingWorkspace progress window. The .big naming convention (Generals base names vs. ZH-suffixed Zero Hour names such as INIZH.big) exists today only in LanguageDetector; there is no existing sentinel/archive-root validation, and no RetailArchive/SentinelFile constant anywhere.

Ticket Summary

Add a pre-spawn validation step to the game launch pipeline that verifies each configured retail archive root actually contains its game data archives (a sentinel .big file), failing the launch with an actionable, root-naming diagnostic instead of spawning an engine that silently starts with zero content.

Note: The ticket title ("Reject multi-variant manifests at ingestion…") does not match the ticket body/acceptance criteria, which unambiguously describe pre-launch retail-archive-root validation. Codebase exploration confirmed there is no "multi-variant manifest / .Files consumer" data-model gap to patch. This plan implements the behavior described in the ticket body and acceptance criteria (retail archive root validation).

File-Level Change Summary & Follow-up Notes

• GenHub/GenHub.Core/Constants/ (new RetailArchiveConstants.cs or addition to GameClientConstants.cs) — declare per-GameType sentinel .big filename candidates.
• GenHub/GenHub/Features/Launching/GameLauncher.cs — add PreflightRetailArchiveRootCheckAsync; call it after actualInstallationPath resolution and before workspace preparation; convert failures to LaunchOperationResult.CreateFailure.
• GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Launching/GameLauncherTests.cs — new failure/happy-path tests; update shared fixture so existing tests keep passing.

Follow-up agent guidance:

• Confirm the exact filesystem abstraction used in GameLauncher (it currently uses System.IO directly, no injected IFileSystem); keep the existence check consistent with that (direct System.IO), and ensure tests point the mocked installation paths at real temp directories or otherwise make the .big existence check deterministic.
• Because the ticket title references "multi-variant manifests" but the body/acceptance criteria describe retail archive root validation, flag the title mismatch back to the ticket author; this plan intentionally implements the body/acceptance-criteria behavior.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: establish a single source of truth for which `.big` archive
filenames indicate a genuinely populated retail root for each game type.

- Add a new constants surface for retail archive sentinels under
`GenHub/GenHub.Core/Constants/` — either create a new
`RetailArchiveConstants.cs` file, or add to the existing
`GameClientConstants.cs`, following the existing executable-name constant style
used in that file/folder.
- Define a small candidate filename list per `GameType`, aligned with the
existing `LanguageDetector` naming convention: base-name `.big` archive(s) for
`GameType.Generals`, and `ZH`-suffixed archive(s) (e.g. `INIZH.big`,
`EnglishZH.big`) for `GameType.ZeroHour`.
- Keep this purely declarative — filenames only, no parsing or hashing logic —
since this is metadata to be used later for an existence check.
===============================================================================

Task: 2

Implement Phase 2: add a preflight validation step to the launch pipeline that
runs after the retail installation path is resolved and before workspace
preparation/process spawn, mirroring the existing `PreflightCasCheckAsync`
pattern.

- In `GenHub/GenHub/Features/Launching/GameLauncher.cs`, add a private
`PreflightRetailArchiveRootCheckAsync(...)` returning `OperationResult<bool>`,
matching the signature/error-handling/logging style of `PreflightCasCheckAsync`.
- The method accepts the resolved retail archive root(s) and the `GameType`, and
verifies via `Directory.Exists` plus a `.big` existence check (using the Phase 1
sentinel candidate names) that each configured root contains game archives. Use
an existence-only check (e.g., `Directory.EnumerateFiles(root, "*.big")`
short-circuited, or candidate-name `File.Exists`) — do not open or parse archive
contents, to keep cost negligible.
- On failure, return `CreateFailure` with a diagnostic naming the specific
offending root and game type, e.g. "No game data archives (.big) found under
retail root '<path>' for <GameType>; the installation appears empty or
misconfigured."
- Wire the call into the private `LaunchProfileAsync` core method immediately
after `actualInstallationPath` is resolved and its existing
`string.IsNullOrEmpty` null-check passes, and before `WorkspaceConfiguration` is
built / `workspaceManager.PrepareWorkspaceAsync` is invoked.
- Follow the existing conversion pattern on failure: log an error and `return
LaunchOperationResult<GameLaunchInfo>.CreateFailure(result.FirstError ?? "...",
launchId, profile.Id);`. Remain within the current `PreparingWorkspace` progress
window — do not add a new `LaunchPhase` enum value.
- Treat the resolved `actualInstallationPath` as the primary retail archive root
to validate for the profile's `GameType`. If more than one retail root can feed
a given launch, pass the roots as a collection into the check so the diagnostic
can name whichever specific root fails; validate each independently and fail on
the first empty/misconfigured one.
- Deliberately exclude non-retail content source directories (e.g., mod/content
`manifestSourcePaths`) from this check, since those are not "retail archive
roots" and are already covered by CAS/manifest preflight — note this exclusion
explicitly to avoid scope creep.
===============================================================================

Task: 3

Implement Phase 3: add unit test coverage for the retail archive root validation
added in Phase 2, following existing launcher test patterns.

- In
`GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Launching/GameLauncherTests.cs`,
add a failure-path test that configures a retail root with no `.big` sentinel
present and asserts `result.Success == false` with `result.FirstError`
containing the offending root path / actionable message, and asserts that
`processManager.StartProcessAsync` and `workspaceManager.PrepareWorkspaceAsync`
are NOT invoked (i.e., the launch fails before spawn).
- Add or adjust the "happy path" setup so the mocked installation root reports a
present sentinel `.big` file, confirming a correctly configured root launches
unchanged; update the shared constructor `GameInstallation`/path setup so the
default fixture satisfies the new check and all existing passing tests continue
to pass.
- Follow the existing failure-path test pattern used by tests like
`LaunchProfileAsync_WithWorkspaceFailure_ShouldFail`: set up a single condition,
call `LaunchProfileAsync(profile.Id)`, and assert on `result.Success` /
`result.FirstError`.

💡 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!

[bobtista]

How this closes. Fixed inside the mac stack rather than by its own PR — the fix is folded into the owning branch before the PR opens, so the code will read as originally written with no separate "fixes #314" diff. Closed by PR A (feat/cross-platform-fixes), which introduces the manifest variants model. See #327 for the PR structure.

Dependency: this fail-closed gate is a stopgap. It must stay in place until #321 (.Files → ResolvedArtifact migration) lands — until then it is the only thing preventing a variant manifest from corrupting CAS refcounting and GC state. #321 now sits in milestone 7 (Content Pipeline & Distribution), so the gate should be expected to live for a while.

[bobtista]

Already implemented by #328: ManifestIngestionGate.TryAccept fail-closed rejects any manifest declaring variants or claiming manifest format version >= 2 (VariantsManifestFormatVersion = 2 in ManifestConstants), wired into all three ingestion paths (ContentManifestPool, ManifestProvider, ManifestDiscoveryService), with tests covering both the rejection and legacy paths in ManifestIngestionGateTests. All four acceptance criteria are met by the merged code.