acdream/docs/plans/2026-08-25-launcher-content-stabilization.md

# Launcher content stabilization

**Date:** 2026-08-25
**Status:** IMPLEMENTED
**Goal:** make prepared-content updates fast, explicit, and safe without
turning the launcher into a package manager.

## User contract

1. The launcher window appears before network access, full-file hashing,
   baking, recovery, or any other potentially long operation.
2. Ordinary startup reads only small metadata: the install record, pak header,
   file length/write time, and the verification sidecar when present.
3. No long content operation begins silently. The launcher first names the
   reason, work kind, approximate disk requirement, and whether the existing
   installed game remains usable.
4. A prepared-content change uses a small locally generated overlay whenever
   the affected DAT IDs/landblocks are bounded. A full rebuild is an explicit,
   rare fallback for format changes or extraction changes with unbounded
   impact.
5. The launcher never starts a mixed client/content pair. Cancellation or a
   bake/publication failure preserves the prior pair. Once approved content is
   ready, an unavailable or failed matching-client update leaves Play disabled
   and retains the verified content for a cheap retry.

## What exists already

- `acdream.pak` has a 64-byte header containing DAT iterations, format version,
  and `BakeToolVersion` (the current content-recipe identity).
- `install.json` records the pak SHA-256, size, DAT path, and recipe identity.
- `install.verification.json` avoids the former 24-second startup hash when
  size/write-time still match. Explicit **Verify files** remains the full-hash
  path.
- `acdream-bake` already accepts `--ids` and `--landblocks`, and a filtered
  bake produces an ordinary valid pak with only those typed keys.
- `IPreparedAssetSource` and `IPreparedCollisionSource` are the existing
  renderer/physics seams; no consumer needs to know which mapped pak supplied a
  key.
- Launcher and client are published together, and the launcher payload already
  includes the matching bake executable.

## Deliberately small model

There are only four work kinds:

| Kind | Launcher behavior |
|---|---|
| `None` | No content prompt. |
| `Overlay` | Build one cumulative overlay containing all keys changed since the base recipe. |
| `FullRebuild` | Explain the long rebuild and required free space before starting. |
| `Verify` | User-requested or exceptional recovery hash; always visible and cancellable. |

The release-feed schema remains unchanged for the first implementation. Every
published build already updates the launcher before the client. The updated
launcher carries the matching content requirement and a small compiled
migration catalog. This avoids stranding strict schema-1 launchers on a feed
shape they cannot parse. A future independently versioned content feed can
replace the catalog without changing the runtime content model.

`BakeToolVersion` is retained on disk for compatibility but is treated as a
**content recipe version**, not an executable build number. It changes only
when the produced prepared content changes.

## On-disk content state

The existing `install.json` remains the base-pak authority and is not extended;
older launchers reject unknown fields. New state lives in the optional sidecar
`DataDirectory/pak/content.current.json`:

```json
{
  "schemaVersion": 1,
  "baseSha256": "<sha256 from install.json>",
  "effectiveRecipeVersion": 6,
  "overlay": {
    "path": "acdream-update-6.pak",
    "sha256": "<64 lowercase hex>",
    "size": 123,
    "recipeVersion": 6
  }
}
```

Rules:

- The sidecar is valid only when `baseSha256` binds it to the current base
  record and every path is a safe canonical filename beneath the pak directory.
- At most one overlay is active. A later overlay is cumulative and atomically
  replaces the prior sidecar; there is no unbounded lookup chain.
- The base and overlay must name the same installed DAT iterations and pak
  format. The base may carry an older recipe; the overlay carries the effective
  recipe.
- Missing overlay keys fall through to the base. A present-but-corrupt overlay
  key is authoritative corruption and never falls through.
- Render and collision reads follow the same ordering and share the same two
  memory mappings.
- An absent sidecar means the base pak is the complete active content set.
- `content.client-pending` is a separate, tiny crash-safe activation gate. A
  content migration creates it before touching content and removes it only
  after client compatibility is confirmed. It deliberately carries no package
  graph; existence means “do not publish this content to Play yet.”

## Migration catalog

One compiled catalog entry describes each recipe transition:

```text
target recipe
work kind
player-facing reason
affected DAT IDs and/or landblocks (overlay only)
```

To update a base from recipe 5 directly to recipe 7, the launcher asks the
catalog for the cumulative 5 -> 7 impact and emits one recipe-7 overlay. If any
step is `FullRebuild`, the combined migration is a full rebuild. A missing
catalog step fails closed with an explanatory error; it never guesses.

The recent procedural night-sky change is `None` because it changed client
shader/code only. A future addition of bounded prepared sky keys can be
`Overlay`. A global mesh-extraction correction such as recipe 5's solid-face
change is `FullRebuild`.

## Update transaction and UI

The launcher keeps the existing one-question update surface. When the candidate
client needs newer content, pressing **Update** first opens the content-work
confirmation:

> **World data update required**
> This release adds prepared sky assets. acdream will build a small update
> from your installed Asheron's Call files. The existing game stays installed
> until this finishes.
> Estimated work: overlay / approximately N files / M free space required.
> **Update now** · **Later**

After confirmation:

1. Validate the remembered DAT directory and free-space floor.
2. Build to a transaction-owned candidate path while the active content stays
   untouched.
3. Validate pak header/TOC and compute the new artifact's SHA once. Never hash
   the unchanged base as part of an overlay update.
4. Atomically publish the content sidecar.
5. Install/activate the compatible client.

The newly prepared content is not published to the launch orchestrator until
the startup check confirms that the active client is compatible or the client
update succeeds. Choosing **Not now**, losing the network, or failing the
client download therefore cannot launch the old executable against the new
pak. The launcher keeps the verified content on disk and resumes at the much
smaller client-update step.

For `FullRebuild`, the same transaction builds a candidate base beside the old
base, verifies it, then atomically swaps the base record/file. It never moves
the playable base out of place before the long build starts.

Progress uses the existing strict Bake JSONL protocol and shows phase,
percentage, failures, and ETA. Cancellation returns to the launcher without
changing active content.

## Startup ordering

`App.OnFrameworkInitializationCompleted` must not synchronously wait on
`LoadExistingAsync` before constructing `MainWindow`. It constructs the shell
with an explicit `Checking` installation state, assigns/shows the window, then
starts content discovery on the UI dispatcher. Feed update checking begins only
after that cheap discovery completes, preventing two startup modals from
racing.

If an exceptional recovery path really needs a full base hash, the shell is
already visible and says exactly what it is doing. Launch stays disabled until
the recovery check finishes, but the application never looks frozen.

## Compatibility and rollback

- A client session receives the resolved base path plus zero or one overlay
  path. Old clients continue receiving only the base.
- The client validates the effective recipe before constructing world owners.
- The updater does not activate a client whose content requirement is
  unsatisfied.
- Choosing **Later** leaves the old client/base pair active.
- Client rollback is allowed only when the selected client accepts the active
  content set; otherwise the launcher explains the required content rollback
  or rebuild instead of launching an incompatible pair.

## Verification gates

- Launcher window construction test proves no installer/hash task is awaited
  before the main window is assigned.
- Quick-discovery tests cover missing sidecar, matching sidecar, missing cache,
  changed length/time, recipe mismatch, and exceptional visible verification.
- Content-state tests cover path containment, base-digest binding, atomic
  publication, cancellation, and crash residue.
- Composite-source tests cover overlay hit, base fallback, authoritative
  overlay corruption, render/collision parity, stats, and balanced disposal.
- Session-config round trips cover base-only and base+overlay on App and
  Headless.
- Update tests prove prepared content cannot become launchable before client
  compatibility is confirmed; **Not now** and client-download failure remain
  fail-closed, while bake/candidate failure preserves the prior pair.
- Release solution compilation and the affected Launcher, Content, App, and
  Headless gates remain green.

## Implementation checkpoint

Implemented 2026-08-25:

- The Avalonia window is assigned and opened before content discovery, client
  recovery, feed access, or exceptional hashing begins.
- Ordinary current-install discovery uses metadata/header/cache checks; the
  explicit verification command owns visible whole-pak hashing.
- Recipe migrations are compiled and cumulative. Bounded migrations build one
  filtered overlay; unbounded/global migrations use the explicit candidate
  full-rebuild path. The current recipe 4 -> 5 transition is correctly a full
  rebuild because the solid-face extraction change is global.
- Base/overlay reads are unified for render and collision with overlay-first,
  Missing-only fallback and authoritative corruption.
- Content activation is bound to client compatibility in memory and through
  `content.client-pending`, so **Not now**, failed download, process crash, and
  launcher restart cannot expose a mixed pair.

Final Release gates:

- `dotnet build AcDream.slnx -c Release`: 0 warnings, 0 errors.
- Launcher UI/ViewModels, excluding the documented manual desktop lane: 82/82.
- Launcher.Core Windows-compatible suite: 360/360.
- Hermetic Content suite: 130/130.
- Affected App layered/session composition: 35/35.
- Affected Headless configuration: 9/9.