# 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.