fix: observe legacy failures in shadow worker

.superpowers/sdd/2026-09-03-ft546wms-shadow-v3/task-6-report.md

@@ -0,0 +1,69 @@
+# Task 6 Report
+
+## Status
+
+GREEN, pending independent review.
+
+## RED Evidence
+
+- The initial Task 6 focused command failed test compilation because
+  `ShadowRuntimeMetrics`, `ShadowFailureStage`, tracked completion factories, the injected
+  `Sleeper`, the v3 gateway constructor, and the metric mapper operation did not exist.
+- After the initial coordinator recovery implementation, the new
+  `staleRefreshTicketCannotCancelANewerRefreshLease` test failed with expected `BUSY` but actual
+  `UNAVAILABLE`, proving that a late old ticket could cancel a newer refresh lease.
+
+## Implementation
+
+- Inbound and outbound completion tokens now support idempotent `complete` and non-throwing
+  `fail(Throwable)`, close caller-owned Legacy activity exactly once, and record Legacy duration
+  without mapper access.
+- `ShadowRuntimeMetrics` uses fixed-cardinality atomic counters and histogram buckets. `drain()`
+  returns an immutable bounded batch for the worker.
+- `ShadowObservationGateway` now performs asynchronous startup refresh, coordinator admission,
+  snapshot-qualified planning, worker-only Legacy waiting/comparison, concurrency invalidation,
+  one-thread/capacity-one execution, quiet-window refresh, 1/2/4-second retry, one-minute recovery
+  coalescing, worker-only structured warnings, and worker-side metric persistence.
+- Snapshot generations continue above the currently stored database generation.
+- Refresh leases are unique; stale ticket completion cannot clear a later refresh.
+- The mapper upserts only fixed metric rows into `alg.shadow_runtime_metric`.
+
+## GREEN Evidence
+
+Task 6 focused suite was run twice with Maven 3.9.11 after implementation:
+
+    & 'D:\BDevTools\maven\apache-maven-3.9.11\bin\mvn.cmd' -pl 'ruoyi-admin' -am '-Dtest=ShadowObservationGatewayTest,ShadowRuntimeMetricsTest,ShadowSnapshotCoordinatorTest' '-Dsurefire.failIfNoSpecifiedTests=false' test
+
+Both runs completed with 21 tests, 0 failures, 0 errors, and `BUILD SUCCESS`.
+
+The final Task 5+6 compatibility command was then run after the metric SQL boundary assertions:
+
+    & 'D:\BDevTools\maven\apache-maven-3.9.11\bin\mvn.cmd' -pl 'ruoyi-admin' -am '-Dtest=ShadowPlanningEngineTest,ShadowObservationGatewayTest,ShadowRuntimeMetricsTest,ShadowSnapshotCoordinatorTest' '-Dsurefire.failIfNoSpecifiedTests=false' test
+
+Result: 36 tests, 0 failures, 0 errors, `BUILD SUCCESS`.
+
+## Concerns
+
+- Tests intentionally emit structured warning lines for simulated plan, wait, compare, and refresh
+  failures. They contain only request id, configured warehouse, generation, fixed stage, exception
+  class, and elapsed microseconds; exception messages are not logged.
+- Existing unrelated Lombok superclass and JVM class-data-sharing warnings remain unchanged.
+
+## Fix Round 1
+
+### RED Evidence
+
+- Command: `mvn -pl ruoyi-admin -am -Dtest=ShadowObservationGatewayTest#inboundLegacyFailureIsRecordedAtLegacyWaitStage+outboundLegacyFailureIsRecordedAtLegacyWaitStage -Dsurefire.failIfNoSpecifiedTests=false test`
+- Result: 2 tests run, 2 failures, 0 errors. Both latch assertions timed out because inbound and outbound workers returned immediately when `LegacyResult.failure()` was non-null.
+
+### GREEN Evidence
+
+- Command: `mvn -pl ruoyi-admin -am -Dtest=ShadowObservationGatewayTest,ShadowRuntimeMetricsTest,ShadowSnapshotCoordinatorTest -Dsurefire.failIfNoSpecifiedTests=false test`
+- Result: `ShadowObservationGatewayTest` 13 tests, `ShadowRuntimeMetricsTest` 3 tests, and `ShadowSnapshotCoordinatorTest` passed with 0 failures and 0 errors; Maven build succeeded.
+
+### Changes and Self-review
+
+- Files: `ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowObservationGateway.java`, `ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowObservationGatewayTest.java`, and this report.
+- Inbound/outbound worker `LEGACY_WAIT` failures now use the existing fixed-stage metric and structured warning path. Warning data remains request id, warehouse, generation, fixed stage, exception class, and elapsed time; failure messages and payloads are not logged.
+- Added direct inbound/outbound `fail(Throwable)` regression tests, including duplicate `fail`/`complete` assertions; Legacy admission remains closed exactly once by the completion token.
+- Review scope stayed limited to the required Important; asynchronous timing Minors were not changed.