설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
3.7 KiB
JPA Platform Runbooks
Operator procedures for the failures this platform is designed to surface rather than hide.
A transaction reported completion unknown
Signal: a write use case failed with a commit-phase error (connection lost, 57P01, class
08) from TransactionPort.
What it means: the commit may or may not have happened. It is not a rollback.
Do not re-run the use case. That is what the platform refused to do automatically, for the same reason.
Procedure:
- Take the idempotency key or operation id of the failed request.
- Check the idempotency record for that key.
- Check the business row the use case would have written.
- Check the outbox for a corresponding event.
- If all three agree the write happened, stop — the request succeeded.
- If all three agree it did not, the use case may be re-run.
- If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome; guessing is not.
Deadlock or serialization rate rising
Signal: DB_DEADLOCK / serialization failures rising in the persistence error codes.
SpringTransactionPort does not retry, so each one reaches the caller.
- Group the failures by operation. A single operation dominating means a hot row or an inconsistent lock order.
- For deadlocks, check whether two operations take the same rows in opposite orders — that is a code fix, not a tuning one.
- For serialization failures under
SERIALIZABLE, confirm the isolation is actually required.
Pool exhaustion
Signal: connection acquisition timeouts; PoolMeasurement.pending non-zero.
- Check
REQUIRES_NEWusage. It takes a second connection while pinning the first, so the pool must satisfy(threads x (1 + depth)) + 1. - Check for streaming outside a bounded scope — a
Streamreturned past the transaction holds its connection until the pool notices. - Check for external calls inside a DB transaction. The design forbids them precisely because an HTTP timeout then holds a connection for its whole duration.
Flyway validation failed at startup
The deployment is running against a schema it was not built for. It failed closed, which is correct.
- Read the reported error codes (the messages are deliberately not propagated).
CHECKSUM_MISMATCH— an applied migration was edited afterwards. Find which change is missing from this database. Do not runrepair: it rewrites history to match the scripts, which resolves the symptom by deleting the evidence.MISSING_SCRIPT— a migration applied here is not in this build. Usually a rollback to an older artifact.
An invalid index exists
Signal: this query returns rows.
select n.nspname || '.' || i.relname as invalid_index
from pg_index x
join pg_class i on i.oid = x.indexrelid
join pg_namespace n on n.oid = i.relnamespace
where not x.indisvalid;
A concurrent build failed. The index is ignored by the planner and maintained by every write.
- Confirm no build is currently running. An in-progress build looks identical in the catalog.
- Run
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;outside a migration. - Re-apply the index migration.
The platform does not drop these automatically: on a rolling deploy every instance would race to drop an index another instance was about to finish building.
The runtime role failed verification
Startup refused because the runtime credential holds CREATE, or search_path contains an
unapproved schema.
This is not a false positive to be worked around. Re-provision from
infra/jpa/roles/runtime-roles.sql; the application's credential having DDL is the condition that
makes every other schema guarantee unenforceable.