Document PAK v2 resource closeout

docs/architecture/acdream-architecture.md

@@ -450,6 +450,15 @@ src/
 
   Prepared-content launch contract
     -> `install.json` remains the strict backward-compatible base-pak authority
+    -> format 2 / recipe 6 is the current full-package contract: globally
+       shared texture payloads, independent adaptive blob compression, and
+       source-native BC1/2/3 for surfaces that require no pixel-local edit
+    -> format changes always use an explicit confirmed full rebuild; the
+       launcher preflights 2 GiB free space, shows long-work progress, validates
+       the candidate beside the active package, and promotes atomically
+    -> the prepared texture LRU is bounded to 64 MiB / 1,024 entries; GPU atlas
+       ownership remains in App and the whole-file mmap is virtual, not a
+       committed-copy cache
     -> optional `pak/content.current.json` binds one cumulative overlay to the
        base SHA; there is never an unbounded overlay chain
     -> `pak/content.client-pending` prevents newly migrated content from

docs/architecture/worldbuilder-inventory.md

@@ -22,7 +22,7 @@ particles), and uses the same Silk.NET + .NET stack we target.
 our tree (see CLAUDE.md for the full breakdown):
 - `src/AcDream.Core/Rendering/Wb/` — pure helpers (no GL): `TerrainUtils`,
   `TerrainEntry`, `RegionInfo`, `SceneryHelpers`, `TextureHelpers`.
-- `src/AcDream.App/Rendering/Wb/` — GL infrastructure + mesh pipeline:
+- `src/AcDream.App/Rendering/Wb/` — Vulkan/RHI infrastructure + mesh pipeline:
   `ObjectMeshManager`, `WbMeshAdapter`, `WbDrawDispatcher`, texture cache,
   shader infra, EnvCell/portal/scenery/terrain-blending pipeline classes.
 
@@ -42,7 +42,7 @@ non-render content plus explicit bake/equivalence tooling.
 
 **MP1a (2026-07-05): CPU mesh-extraction half moved to `AcDream.Content`.**
 The GL-free portion of the former `ObjectMeshManager` — dat read → polygon
-walk → vertex/index build → inline BCn/palette texture decode →
+walk → vertex/index build → palette/conditional BCn texture decode →
 `ObjectMeshData` — is now `MeshExtractor` in a new `src/AcDream.Content/`
 assembly (no Silk.NET dependency), so the MP1b bake tool can run the exact
 same extraction code offline without an OpenGL context. This was a
@@ -84,7 +84,7 @@ behavior change, no divergence-register row.
   survive, as they always did). The MP1b bake tool passes its own
   collector.
 - **Stays in `src/AcDream.App/Rendering/Wb/`:** `ObjectMeshManager` (the
-  staged-queue/worker-pool/Dispose-quiesce lifecycle and all GL upload;
+  staged-queue/worker-pool/Dispose-quiesce lifecycle and all Vulkan/RHI upload;
   production workers now consume `IPreparedAssetSource`),
   `ObjectRenderData`/`ObjectRenderBatch`
   (hold a GL `TextureAtlasManager` field), `TextureAtlasManager`,
@@ -120,9 +120,8 @@ EnvCell, Surface, palette, and texture graphs during portals. The validated
 machine-local `acdream.pak` is opened through Content's
 `IPreparedAssetSource`; typed GfxObj and EnvCell requests deserialize immutable
 `ObjectMeshData` while retaining the existing App worker, staging, render-thread
-upload, cache, ownership, and shutdown contracts. The original
-format-1/bake-tool-3 render payload persists exact batch translucency so App
-does not reconstruct a
+upload, cache, ownership, and shutdown contracts. The prepared render payload
+persists exact batch translucency so App does not reconstruct a
 `GfxObjMesh` for metadata. Setup activation uses the package TOC as an explicit
 type-presence index before reading valid Setup records through the bounded DAT
 cache. `DatPreparedAssetSource` and `MeshExtractor` remain explicit
@@ -146,8 +145,25 @@ keeps either result non-launchable until the matching client is confirmed,
 including across a crash/restart. Design and gates:
 `docs/plans/2026-08-25-launcher-content-stabilization.md`.
 
-**Slice I3 prepared collision extension (2026-07-25).** The package remains
-format 1 and retains mesh type values 1–3; bake-tool 4 appends typed GfxObj,
+**PAK v2 resource closeout (2026-08-27).** Format 2 / bake recipe 6 retains
+the fixed header and sorted random-access TOC while moving texture arrays into
+one globally shared type-8 payload partition and independently applying
+adaptive Brotli compression with raw fallback. Unedited DXT1/3/5 surfaces
+retain exact DAT BC blocks through Vulkan upload; clip maps and authored
+translucency continue through the RGBA edit path. The reader bounds decoded
+blobs and retains shared texture arrays in a 64 MiB / 1,024-entry LRU. The
+complete installed package is 597,229,424 bytes versus 29,908,271,024 bytes
+for format 1; four- and nine-worker bakes have identical SHA-256. The
+authoritative connected before/after route reduced heavy-route working set by
+48.0%, private bytes by 26.1%, and prepared-mesh GPU bytes by 25.9% with equal
+or faster matching reveal/frame percentiles. Format changes remain mandatory
+launcher-confirmed full rebuilds with beside-active validation and atomic
+promotion; overlays never cross a format boundary. Design and evidence:
+`docs/plans/2026-08-27-pak-v2-resource-campaign.md`.
+
+**Slice I3 prepared collision extension (2026-07-25).** At its introduction,
+the package remained format 1 and retained mesh type values 1–3; bake-tool 4
+appended typed GfxObj,
 Setup, CellStruct, and EnvCell-topology collision payloads. Core owns the
 immutable flat records and deterministic raw-DAT flattener. Content owns the
 strict little-endian codec and `IPreparedCollisionSource`.