FT546MWS/docs/superpowers/plans/2026-09-07-shadow-v3-observation-repair.md

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

• 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.
• Run the test and observe the eight-hour failure.
• Add mapper/ShadowUtcInstantTypeHandler.java; use getTimestamp(..., Calendar.getInstance(TimeZone.getTimeZone("UTC"))) and setTimestamp(..., Timestamp.from(value), utcCalendar).
• Add an explicit snapshot result map and bind the handler only to snapshotSynchronizedAt and both flushedAt placeholders in ShadowInputMapper.xml.
• Verify parameter writes, nulls, both JVM zones, and unchanged default MyBatis handler.

2. Shadow Diagnostics

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

3. Export Compatibility

• Add CMD behavior tests with spaced paths, literal SQL output destinations, success/failure, working-directory restoration and evidence preservation.
• Run and observe the existing output-path failure. Drain test process output without pipe deadlock.
• Run sqlcmd from OUTPUT_DIR, use literal :out names, balance pushd/popd and check each Git command failure.
• Label local export time honestly; add explicit zero-comparison status using read-only SQL.
• 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

• Run focused tests, then reactor tests and package with Maven 3.9.11 / JDK 17; run existing Node guards.
• Independent read-only review, address findings, rerun affected tests and git diff --check.
• Fetch remote again and verify no concurrent remote commits before preparing delivery.
• 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.