feat(vfx): decode retail hooks and typed tables

Replace the incomplete package path with one DatCollection-backed compatibility seam for PhysicsScripts and Animations. Preserve CreateBlockingParticle's inherited payload and following cursor, route every production and audit consumer through the corrected loaders, and apply retail's post-UnPack StartTime ordering.

Add exact stored-order PhysicsScriptTable upper-threshold resolution, high-byte DID and embedded-ID validation, plus live effect profiles with Setup-to-PhysicsDesc precedence across top-level and attached entity lifetimes. Keep blocking execution deferred and narrow TS-11 accordingly.

Pin synthetic malformed/cursor/order fixtures, installed-DAT blocking and recall audits, high-index IDs, IEEE boundaries, profile teardown, and ordinary decoder parity; synchronize architecture, inventory, milestones, roadmap, research, and memory.

Co-Authored-By: Codex <noreply@openai.com>

docs/architecture/acdream-architecture.md

@@ -258,7 +258,9 @@ Ownership by phase:
 `LiveEntityRuntime` is now the shipped bridge to this target. It owns one
 `LiveEntityRecord` per accepted server-object incarnation, ServerGuid-to-local-id
 translation, accepted snapshots/timestamp gates, animation and remote-motion
-components, parent-event state, and exact logical teardown. `GpuWorldState`
+components, parent-event state, effect-profile defaults, and exact logical
+teardown. Live `PhysicsDesc` effect fields replace Setup defaults on that same
+record; rebucketing never recreates them. `GpuWorldState`
 owns spatial buckets only: register/rebucket/unregister are separate operations,
 and landblock reloads reuse the same `WorldEntity` without replaying renderer or
 script creation. Its canonical materialized view remains stable across pending
@@ -267,6 +269,14 @@ targeting. Pickup/parent leave-world clears cell membership and pauses root
 movement/animation without destroying retained owners. `GameWindow` retains
 storage-free typed views while its large feature loops are extracted.
 
+DAT decoding for runtime VFX crosses one narrow `AcDream.Content.Vfx` seam.
+`RetailAnimationLoader` and `RetailPhysicsScriptLoader` still read through the
+single shared `DatCollection`, delegate ordinary animation-hook schemas to
+Chorizite.DatReaderWriter, and replace only its incomplete
+`CreateBlockingParticleHook` model with retail's inherited CreateParticle
+payload. Core consumes the loaders through delegates/interfaces and therefore
+does not depend on Content or a database implementation.
+
 The remaining aggregation is primarily `_playerController`'s player-specific
 movement plus the separate `WorldEntity`/animation/physics component types.
 Those should become ONE class:

docs/architecture/retail-divergence-register.md

@@ -230,7 +230,7 @@ AP-94..AP-112 for the confirmed retail-UI completion gaps.
 | TS-8 | `MagicUpdateEnchantment` (0x02C2) records carry no StatMod — mid-session buffs don't move vital max until relog (**#7/#12**) | `src/AcDream.Core/Spells/Spellbook.cs:150` | The wire parser hasn't been extended to the full ~60-64 byte Enchantment payload; PlayerDescription's block IS parsed | Vitals HUD percent reads differently from retail for the whole session after any buff cast | `EnchantAttribute` 0x00594570; holtburger magic/types.rs |
 | TS-9 | MP3 (0x55) and MS-ADPCM (0x02) waves undecoded — affected sounds skipped; retail decoded both via winmm ACM | `src/AcDream.Core/Audio/WaveDecoder.cs:33` | Managed decoder (NAudio or similar) deferred; PCM covers the vast majority of ~3500 waves | Any MP3 (common for music-ish clips) or ADPCM cue plays as silence where retail plays it | winmm ACM path (r05 §2.1) |
 | TS-10 | Setup lights anchored at entity root — per-light Frames not transformed through the animated part chain | `src/AcDream.Core/Lighting/LightInfoLoader.cs:31` | Per-part world transforms aren't exposed to the lighting layer; awaiting animation hook integration | A carried torch glows from the character origin, not the hand, and doesn't track swing/idle animations | LightInfo.ViewSpaceLocation per-part Frame (r13 §1) |
-| TS-11 | `CreateBlockingParticleHook` is consumed as a no-op because the package model omits its inherited CreateParticle payload; acdream therefore also lacks retail's same-live-nonzero-logical-ID suppression | `src/AcDream.Core/Vfx/ParticleHookSink.cs:112` | A narrow raw-hook compatibility reader is required so the shared payload is decoded without replacing `DatCollection` or duplicating ordinary hook schemas | Blocking-particle hooks emit nothing today; without the corrected decoder the next hook can also be cursor-misaligned, and repeated logical IDs cannot follow retail replacement/suppression rules | `CreateBlockingParticleHook::Execute` 0x00526EF0; `ParticleManager::CreateBlockingParticleEmitter` 0x0051B8A0; r04 §6 |
+| TS-11 | Retail's complete inherited `CreateBlockingParticleHook` payload is decoded by the narrow `DatCollection`-backed compatibility reader, but `ParticleHookSink` deliberately no-ops it until the live emitter-binding owner can apply same-live-nonzero-logical-ID suppression | `src/AcDream.Core/Vfx/ParticleHookSink.cs` (`RetailCreateBlockingParticleHook` case); decoder `src/AcDream.Content/Vfx/RetailAnimationHookReader.cs` | Decoding and cursor alignment are now exact for both PhysicsScripts and Animations; executing it as an ordinary replacement before Step 5 would encode the wrong lifetime rule | Blocking-particle hooks still emit nothing until Step 5; ordinary hooks following them are no longer cursor-misaligned | `CreateBlockingParticleHook::Execute` 0x00526EF0; `ParticleManager::CreateBlockingParticleEmitter` 0x0051B8A0; r04 §6 |
 | TS-12 | Animated entities' emitters use rest-pose part transforms anchored at entity root; retail attaches to the live animated part (per-tick refresh deferred; statics fixed by C.1.5b/#56) | `src/AcDream.Core/Vfx/ParticleHookSink.cs:80` (+ :20) | The renderer doesn't expose per-part world transforms to VFX; root + precomputed matrices reproduce retail placement for everything that doesn't animate | Effects hooked to animated parts (swinging hand, nodding head) emit from the rest pose / float at spawn offsets instead of tracking motion | `ParticleEmitter::UpdateParticles` 0x0051d2d4 |
 | TS-13 | `DefaultScriptHook` / `DefaultScriptPartHook` / `CallPESHook` animation hooks dropped (no OnHook case); blocker comment predates PhysicsScriptRunner (C.1.5a) and may be STALE | `src/AcDream.Core/Vfx/ParticleHookSink.cs:130` | Originally blocked on PhysicsScript dat exposure; spawn-time DefaultScript firing landed via EntityScriptActivator, the animation-frame path never did | VFX retail triggers from specific animation frames (mid-animation script calls) never appear | CallPES / DefaultScript hook dispatch (r04 §6) |
 | TS-14 | Setup `Flatten` ignores ParentIndex part hierarchy (treats every placement as root-local); still in production use (GameWindow hydration, SkyRenderer) | `src/AcDream.Core/Meshing/SetupMesh.cs:15` | Most Setups are flat single-level rigs where root-local equals composed; hierarchical composition deferred ("Phase 3") | Any Setup with genuinely nested parts renders them at wrong offsets — mis-assembled multi-part objects in the Flatten paths | retail Setup ParentIndex chain composition |

docs/architecture/worldbuilder-inventory.md

@@ -101,6 +101,18 @@ behavior change, no divergence-register row.
   running with no GL context, so baked pak output and live-client output stay
   byte-identical.
 
+**Retail VFX hook compatibility seam (2026-07-14).** Chorizite.DatReaderWriter
+2.1.7 models `CreateBlockingParticleHook` as the common hook header only, while
+retail inherits the complete `CreateParticleHook` payload. The narrow readers in
+`src/AcDream.Content/Vfx/` read raw bytes through the existing `DatCollection`
+database, delegate every ordinary hook to the package, and substitute only the
+retail blocking-particle shape. Both live animation playback and PhysicsScript
+loading use those cached readers; `MeshExtractor` uses the same PhysicsScript
+loader when preloading emitter meshes. This is not a second DAT reader:
+`DatCollection` remains the sole database owner and access path. Retail anchors:
+`CreateBlockingParticleHook::Execute` `0x00526EF0` and
+`ParticleManager::CreateBlockingParticleEmitter` `0x0051B8A0`.
+
 **Workflow:** Before re-implementing any AC-specific rendering or dat-handling
 algorithm, **check this inventory first**. If we already extracted it (🟢
 sections), it's in `src/AcDream.App/Rendering/Wb/` — use our copy. If WB has