fix(shadow): protect observed vehicle traffic

docs/superpowers/plans/2026-09-09-shadow-observed-traffic.md

@@ -0,0 +1,20 @@
+# Shadow observed traffic repair
+
+**Goal:** Prevent shadow predictions from crossing observed vehicle positions and issued routes. Production SQL and runtime are out of scope.
+
+**Architecture:** Add immutable, per-snapshot resource owners, separate from the persisted prediction ledger. Existing DispatchSnapshot constructors supply an empty map. Only the shadow assembler supplies observed owners. The coordinator checks before reservation and also checks proposed yield routes. Unknown moving paths block their floor; missing previously observed vehicles reject the snapshot.
+
+## Work and verification
+
+- [x] Reproduce with ShadowObservedTrafficTest: 8 tests, 5 expected assertion failures; baseline reactor passes.
+- [ ] Add snapshot overload accepting Map<String, Set<String>> observedResourceOwners; defensively copy and validate against topology resources.
+- [ ] Add ShadowObservedTrafficProjector.project(batch, topology); project current sites, expand orthogonal live paths through all map nodes/edges, include active issued queue routes; ignore finished queue history. Keep an in-process high-water vehicle roster and reject missing/contradictory vehicle facts.
+- [ ] Coordinator checks other owners before DeadlockGuard reservation; convert conflicting yield into HOLD, without writing observations to the ledger.
+- [ ] Run `mvn -o -pl ruoyi-wcs-shadow -am -Dtest=ShadowObservedTrafficTest -Dsurefire.failIfNoSpecifiedTests=false test`; expand boundary tests and run the full reactor.
+- [ ] Replay the three captured risk cases with real assembler/coordinator; retain input hashes and clearly distinguish this replay from reconstruction of the historical ledger.
+- [ ] Review cache points against formal mapper rules and map geometry. Document candidate points only; keep safe-wait/yield configuration empty.
+- [ ] Review diff, update build identity and repair notes, deliver source without deploying or restarting either field application.
+
+## Safety constraints
+
+No production database writes, no PLC/WMS calls, no remote update/restart. Do not relax allowSend eligibility or release persisted UNKNOWN/OCCUPIED reservations. Old shared dispatch constructors retain existing behavior. A complete source read is not a PLC-atomic observation; this repair is for shadow validation, not approval of production takeover.