7f8940788c
- 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>
122 lines
6.1 KiB
Markdown
122 lines
6.1 KiB
Markdown
---
|
|
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*
|