fix(shadow): repair field routing and harden evidence collection

docs/superpowers/plans/2026-09-07-shadow-field-repair.md

@@ -0,0 +1,66 @@
+# Shadow Field Repair Implementation Plan
+
+> **For agentic workers:** Execute inline with superpowers:executing-plans. Scouts are read-only; the main agent owns edits and verification.
+
+**Goal:** Repair the field-reproduced shadow failures without changing legacy dispatch or granting production write authority.
+
+**Architecture:** Keep topology routes separate from FT546 command points. Shadow predictions must not become permanent physical reservations. Preserve existing evidence JSON and database schema, add bounded collection and durable runtime metadata using existing authorized tables.
+
+**Tech Stack:** Java 8-compatible source, Maven 3.6.0, JUnit 5, Spring JDBC, SQL Server 2016; H2 for isolated persistence tests.
+
+**Spec:** Existing `docs/superpowers/specs/2026-08-12-ft546-shadow-first-safe-cutover-design.md`, plus the read-only field assessment at `D:/workSpace/PROJECT_SPACE/FT546/outputs/wcs-shadow-review-20260907/live-database-assessment.md` and the user's approval to repair the shadow version.
+
+## Global Constraints
+
+- Work only in the existing optimize/wcs worktree. Preserve prior uncommitted fixes and unrelated files.
+- No production SQL writes, migrations, PLC/WMS connections, application startup or deployment. The repair/validation stage excluded commit/push; subsequent user approval authorizes publishing only the repaired source to origin/optimize/wcs.
+- Keep legacy Admin/PLC behavior unchanged. Generic route changes must be backward compatible and tested across ruoyi-wcs.
+- Do not delete, truncate, silently sample, or change the raw evidence JSON/hash contract.
+- Keep unsupported phase/route representations explicitly unavailable; do not manufacture successful comparisons.
+
+## Task 1: Field Path and Protocol Regression
+
+Files: `ruoyi-wcs-shadow/.../facts/LegacyQueueProtocolProjector.java`, `.../kernel/ShadowCommandIntentFactory.java`, `ruoyi-wcs/.../domain/traffic/RoutePlan.java`, `AStarRoutePlanner.java`, `.../domain/dispatch/DefaultVehicleAssignmentPolicy.java`, focused tests in both modules.
+
+- [x] Add literal expected 4004 payload tests for task 31312, straight numeric paths, long virtual paths, invalid endpoint/turn and overflow cases.
+- [x] Add the overlapping approach/execution reservation regression; verify ordered nodes survive while unique resources are reserved.
+- [x] Run the tests red against current code.
+- [x] Carry geometry-derived turn-node metadata on planned routes; project start/end/turns in the shadow factory. Accept only known virtual transit tokens in historical reconstruction, with numeric validated endpoints/turns.
+- [x] Deduplicate reservation resources at route combination, not ordered route nodes or the reservation safety boundary.
+- [x] Run focused tests green and repeat the captured database probe.
+
+## Task 2: Shadow Prediction Lifecycle
+
+Files: `ruoyi-wcs-shadow/.../kernel/JdbcShadowTrafficStateRepository.java`, snapshot assembly and associated H2/end-to-end tests.
+
+- [x] Write a repeated-poll/restart test showing a prior hypothetical grant cannot consume capacity forever.
+- [x] Keep physical/unknown protection distinct from hypothetical reservations; never interpret a new prediction as PLC execution.
+- [x] Preserve snapshot CAS, evidence transaction rollback and hold-count behavior; tag new state JSON with PER_SNAPSHOT_PREDICTION and explicit predictionReservationIds. Preserve all untagged legacy state and OCCUPIED/unknown/recovery protection; remove only tagged predictions from the next working ledger.
+- [x] Run repeat, restart, conflict and rollback regressions. Add per-startup reservation ID prefix to avoid collision with retained state.
+
+## Task 3: Evidence Growth Guard
+
+Files: shadow evidence storage health/configuration, repository metadata access, property defaults and tests.
+
+- [x] Add tests for database allocation threshold, unavailable capacity metadata, local free-space threshold and preservation of existing evidence rows.
+- [x] Use bounded database-file metadata reads, not whole captured_json scans or broad server-state permission grants.
+- [x] Stop new collection with a specific durable reason when limits are reached. Keep raw evidence/export compatibility unchanged.
+- [x] Document that lossless deduplication/archive remains a separate migration decision, not an automatic deletion policy.
+
+## Task 4: Durable Run State
+
+Files: shadow evidence repository/runtime monitor, scheduler, status report/configuration and tests.
+
+- [x] Test heartbeat on empty polls, last success vs attempt, retryable failure, permanent timeout, orderly stop and persistence failure.
+- [x] Persist bounded run metadata in FT546:RUN:<runId> in shadow_traffic_state and update shadow_run status. No DDL or new privileges.
+- [x] Ensure timeout/stop reasons cannot be overwritten by a late worker completion; monitor failure must not claim healthy collection.
+- [x] Keep timestamps explicitly UTC in serialized metadata and expose freshness for external stale detection.
+
+## Task 5: Acceptance
+
+- [x] Run the full offline Maven reactor tests for shadow and its dependencies, plus existing charging and new field-input replay. 298 tests passed, none skipped; 300 captured inputs and 10 additional field batches replayed without processing/projection errors.
+- [x] Request independent read-only code review of safety boundaries, protocol payloads and new operational paths; fix important findings. No blocking findings; SQL Server integration and blocked-shutdown coverage limits recorded.
+- [x] Verify no legacy source edits, no secrets in outputs, no new database/PLC authority and no background test jobs left running.
+- [x] Record results and remaining field/HIL boundaries; deliver source only, without claiming production-scheduler acceptance. See docs/runbooks/ft546-shadow-20260907-repair-notes.md.
+
+Baseline: offline Maven reactor test command succeeded on 2026-09-07 before this repair. The field probe from the preceding turn reproducibly failed on virtual nodes and duplicate route resources.