# Shadow v3 Observation Repair

> Execute inline with test-driven-development and verification-before-completion. Subagents explore and review only, per project instructions.

**Goal:** Restore timezone-independent shadow sampling and exportable diagnostics without changing Legacy.

**Architecture:** Use a statement-scoped UTC Instant handler, a bounded shadow-only log, and literal sqlcmd output paths. Preserve all scheduling, freshness, transaction and mode guards.

**Tech Stack:** Java 17, MyBatis 3.5.19, Microsoft JDBC 12.10.1, Logback, Windows CMD, SQL Server 2016 RTM.

**Spec:** `docs/superpowers/specs/2026-09-03-ft546wms-shadow-v3-design.md`.

## Constraints

- No global timezone/type-handler override; no Legacy code or business SQL changes.
- Keep SHADOW mode, 60-second snapshot freshness and existing single-worker coordination.
- Do not restart field processes or migrate SQL objects. Keep historical metric counters.
- Export with Windows integrated authentication, read-only SQL, and no overwriting existing evidence.

## 1. UTC Mapping

- [x] Add `ShadowUtcMappingTest` loading the real mapper. Exercise UTC and Asia/Shanghai reads through the actual driver's datetime2 conversion, preserve 100ns precision, and verify fresh/stale coordinator admission.
- [x] Run the test and observe the eight-hour failure.
- [x] Add `mapper/ShadowUtcInstantTypeHandler.java`; use `getTimestamp(..., Calendar.getInstance(TimeZone.getTimeZone("UTC")))` and `setTimestamp(..., Timestamp.from(value), utcCalendar)`.
- [x] Add an explicit snapshot result map and bind the handler only to `snapshotSynchronizedAt` and both `flushedAt` placeholders in `ShadowInputMapper.xml`.
- [x] Verify parameter writes, nulls, both JVM zones, and unchanged default MyBatis handler.

## 2. Shadow Diagnostics

- [x] Add an actual Logback routing test: a shadow WARN must reach a file; unrelated business WARN and INFO must not enter it.
- [x] Observe failure with the current configuration.
- [x] Add a shadow-only WARN-and-higher rolling appender with full dates, 10MB files, 14-day history and 100MB archive cap.
- [x] Add bounded exception metadata (cause class, SQL state/vendor code, source frame) without messages, SQL or payloads; keep logging on the existing worker paths.
- [x] Verify routing, error context, and existing caller isolation tests.

## 3. Export Compatibility

- [x] Add CMD behavior tests with spaced paths, literal SQL output destinations, success/failure, working-directory restoration and evidence preservation.
- [x] Run and observe the existing output-path failure. Drain test process output without pipe deadlock.
- [x] Run sqlcmd from `OUTPUT_DIR`, use literal `:out` names, balance pushd/popd and check each Git command failure.
- [x] Label local export time honestly; add explicit zero-comparison status using read-only SQL.
- [x] Update server AI instructions and add maintenance-window deployment/rollback steps, with no SQL reinstall.

## Review Notes

- UTC read/write and nanosecond mapping reviewed independently; no confirmed defect found.
- Actual Logback configuration test passed with no ERROR status. The existing two root declarations are accepted by the installed Logback; changing them is unnecessary scope expansion.
- Logger additivity intentionally preserves existing console/error behavior. The new file receives only shadow WARN/ERROR, confirmed by file-routing tests.
- SQL diagnostics intentionally select the deepest SQLException within eight cause levels; exception messages and SQL are never logged. The worker test verifies SQLState, code, source and payload exclusion.
- CMD fixture executes the real scripts but does not execute SQL. No live SQL Server or field deployment was performed locally; those remain explicit verification limits.

## Verification and Delivery

- [x] Run focused tests, then reactor tests and package with Maven 3.9.11 / JDK 17; run existing Node guards.
- [x] Independent read-only review, address findings, rerun affected tests and `git diff --check`.
- [x] Fetch remote again and verify no concurrent remote commits before preparing delivery.
- [x] Prepare simple CMD update/rollback steps in `doc/algorithm-shadow/SHADOW_V32_UPDATE.md`.

Final verification: 138 algorithm tests + 78 admin tests = 216 passed, zero failures/errors/skips. Maven reactor `package` succeeded on 2026-09-07; three existing Node scripts passed `node --check`. Existing Lombok/deprecation and JVM test-instrumentation warnings remain. No live SQL Server validation or field restart was performed.

Delivery: commit and push only `test/ft546wms-shadow-v3-20260903`, verify the remote hash, and report it in the handoff. Do not merge into main or switch to ACTIVE.