docs(02-04): complete diagram hash linking gap closure plan
- SUMMARY.md documenting diagram hash linking and test stability fixes - STATE.md updated with position, decisions, metrics - ROADMAP.md updated with phase 02 plan progress - REQUIREMENTS.md DIAG-02 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
hsiegeln
121
.planning/phases/02-transaction-search-diagrams/02-04-SUMMARY.md
Normal file
121
.planning/phases/02-transaction-search-diagrams/02-04-SUMMARY.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
phase: 02-transaction-search-diagrams
|
||||
plan: 04
|
||||
subsystem: database
|
||||
tags: [clickhouse, diagram-linking, surefire, testcontainers, awaitility]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 02-transaction-search-diagrams (plans 01-03)
|
||||
provides: ClickHouse schema, execution repository, diagram repository, ingestion pipeline
|
||||
provides:
|
||||
- diagram_content_hash populated during execution ingestion (DIAG-02 complete)
|
||||
- stable mvn clean verify with classloader isolation
|
||||
affects: [03-agent-registry-sse, 04-security-api-docs]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: [awaitility ignoreExceptions for ClickHouse eventual consistency, surefire reuseForks=false for ELK classloader isolation]
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/DiagramLinkingIT.java
|
||||
modified:
|
||||
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/storage/ClickHouseExecutionRepository.java
|
||||
- cameleer3-server-app/pom.xml
|
||||
- cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/IngestionSchemaIT.java
|
||||
- cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/SearchControllerIT.java
|
||||
|
||||
key-decisions:
|
||||
- "DiagramRepository injected via constructor into ClickHouseExecutionRepository for diagram hash lookup during batch insert"
|
||||
- "Awaitility ignoreExceptions pattern adopted for all ClickHouse polling assertions to handle EmptyResultDataAccessException during flush delay"
|
||||
- "Surefire and Failsafe both configured with reuseForks=false to isolate ELK static initializer from Spring Boot classloader"
|
||||
|
||||
patterns-established:
|
||||
- "Awaitility ignoreExceptions: all awaitility assertions polling ClickHouse must use .ignoreExceptions() to tolerate EmptyResultDataAccessException before data is flushed"
|
||||
|
||||
requirements-completed: [DIAG-02]
|
||||
|
||||
# Metrics
|
||||
duration: 22min
|
||||
completed: 2026-03-11
|
||||
---
|
||||
|
||||
# Phase 2 Plan 4: Gap Closure Summary
|
||||
|
||||
**Diagram hash linking during execution ingestion via DiagramRepository lookup, plus Surefire/Failsafe classloader isolation and test stability fixes**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 22 min
|
||||
- **Started:** 2026-03-11T16:13:57Z
|
||||
- **Completed:** 2026-03-11T16:36:49Z
|
||||
- **Tasks:** 1
|
||||
- **Files modified:** 5
|
||||
|
||||
## Accomplishments
|
||||
- diagram_content_hash populated with active RouteGraph SHA-256 hash during batch insert (DIAG-02 fully satisfied)
|
||||
- DiagramLinkingIT integration test proves both positive (hash populated) and negative (empty fallback) cases
|
||||
- `mvn clean verify` passes reliably -- 51 tests, 0 failures, 0 errors
|
||||
- Fixed flaky test failures caused by EmptyResultDataAccessException in awaitility polling
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Populate diagram_content_hash during ingestion and fix Surefire forks** - `34c8310` (feat)
|
||||
|
||||
**Plan metadata:** (pending)
|
||||
|
||||
## Files Created/Modified
|
||||
- `cameleer3-server-app/src/main/java/com/cameleer3/server/app/storage/ClickHouseExecutionRepository.java` - Added DiagramRepository injection, diagram hash lookup in insertBatch
|
||||
- `cameleer3-server-app/pom.xml` - Added maven-surefire-plugin and maven-failsafe-plugin with reuseForks=false
|
||||
- `cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/DiagramLinkingIT.java` - Integration test for diagram hash linking
|
||||
- `cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/IngestionSchemaIT.java` - Added ignoreExceptions + increased timeouts
|
||||
- `cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/SearchControllerIT.java` - Adjusted pagination assertion count
|
||||
|
||||
## Decisions Made
|
||||
- DiagramRepository injected via constructor into ClickHouseExecutionRepository -- both are @Repository Spring beans, so constructor injection autowires cleanly
|
||||
- Used `ignoreExceptions()` in awaitility chains rather than switching from `queryForObject` to `queryForList`, since ignoreExceptions is the canonical awaitility pattern for eventual consistency
|
||||
- Surefire AND Failsafe both need reuseForks=false -- ELK's LayeredMetaDataProvider static initializer poisons the JVM classloader for subsequent Spring Boot test contexts
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Fixed flaky integration tests due to awaitility not retrying EmptyResultDataAccessException**
|
||||
- **Found during:** Task 1 (verification step)
|
||||
- **Issue:** Awaitility's `untilAsserted` was not retrying `EmptyResultDataAccessException` thrown by `queryForObject` when data hadn't been flushed yet, causing intermittent test failures
|
||||
- **Fix:** Added `.ignoreExceptions()` to all awaitility assertions that poll ClickHouse with `queryForObject`, and increased IngestionSchemaIT timeouts from 10s to 30s
|
||||
- **Files modified:** DiagramLinkingIT.java, IngestionSchemaIT.java
|
||||
- **Verification:** `mvn clean verify` passes with 51/51 tests green
|
||||
- **Committed in:** 34c8310 (part of Task 1 commit)
|
||||
|
||||
**2. [Rule 1 - Bug] Fixed SearchControllerIT pagination assertion count**
|
||||
- **Found during:** Task 1 (verification step)
|
||||
- **Issue:** Pagination test asserted >= 8 COMPLETED executions but seed data only contains 7 COMPLETED (execs 2,4 are FAILED, exec 3 is RUNNING)
|
||||
- **Fix:** Changed assertion to `isGreaterThanOrEqualTo(7)`
|
||||
- **Files modified:** SearchControllerIT.java
|
||||
- **Verification:** Test passes consistently
|
||||
- **Committed in:** 34c8310 (part of Task 1 commit)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed (2 bugs)
|
||||
**Impact on plan:** Both fixes required for test reliability. No scope creep.
|
||||
|
||||
## Issues Encountered
|
||||
- Initial `mvn clean verify` had 3 test failures (DiagramLinkingIT x2, IngestionSchemaIT x1) all caused by `EmptyResultDataAccessException` in awaitility assertions. Root cause: awaitility was propagating the exception immediately instead of retrying. Fixed by adding `ignoreExceptions()`.
|
||||
|
||||
## User Setup Required
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- Phase 2 fully complete: ingestion, search, detail, diagrams, and now diagram-execution linking
|
||||
- DIAG-02 requirement satisfied: transactions link to the RouteGraph version active at execution time
|
||||
- Test suite stable at 51 tests with classloader isolation
|
||||
|
||||
---
|
||||
*Phase: 02-transaction-search-diagrams*
|
||||
*Completed: 2026-03-11*
|
||||
Reference in New Issue
Block a user