refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환

설계: 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>
This commit is contained in:
DongHyeonka
2026-09-25 12:49:07 +09:00
co-authored by Claude Opus 5.5
parent 208077fddf
commit 6d27356e2b
2822 changed files with 27992 additions and 166879 deletions
+35 -47
View File
@@ -8,8 +8,7 @@
# and a stale directory cannot be mistaken for this run's;
# 2. the static contract, then `config`, then `create` — a stack that cannot render has no partial
# failure mode, and finding that out after `up` costs a teardown;
# 3. `up --wait` for long-running services only, then health and the resolved activation report,
# which is the application's answer rather than the flags this script passed in;
# 3. `up --wait` for long-running services only, then the application's own health answer;
# 4. every one-shot the lane declares, each of which must exit zero — a missing or skipped
# required client is a lane failure, not a lane that had nothing to check;
# 5. sanitized evidence;
@@ -28,6 +27,29 @@ RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
# is lowercased for the project while the evidence directory keeps the readable timestamp.
PROJECT_RUN_ID="$(tr '[:upper:]' '[:lower:]' <<<"${RUN_ID}")"
# The lanes boot the qualification image: the application with every capability module on the
# classpath (src/Dockerfile COMPOSITION, app-bootstrap qualificationBootJar). The default image is
# the composition a service ships and carries none of them, so a lane that switches JPA or Kafka on
# would have nothing to switch. docker-compose.yml passes this to the build and puts it in the tag.
export COMPOSITION=qualification
# Every capability is on while its module is present, so each lane starts from all of them off and
# its activationEnv turns on what it is about. The off-* lanes therefore prove that a present but
# switched-off capability needs no infrastructure at all.
CAPABILITIES_OFF='{
"APP_PERSISTENCE_JPA_ENABLED": "false",
"APP_REDIS_ENABLED": "false",
"APP_MESSAGING_ENABLED": "false",
"APP_PERSISTENCE_MONGO_ENABLED": "false",
"APP_GRAPHQL_ENABLED": "false",
"APP_HTTPCLIENT_ENABLED": "false",
"APP_OBJECTSTORAGE_ENABLED": "false",
"APP_WEBSOCKET_ENABLED": "false",
"CASKELETON_GRPC_ENABLED": "false",
"APP_FILESERVER_PLATFORM_ENABLED": "false",
"APP_NOTIFICATION_PLATFORM_ENABLED": "false"
}'
MODE=""
SELECTED_LANE=""
usage() {
@@ -321,8 +343,8 @@ run_lane() {
for entry in "${lane_environment[@]}"; do
printf ' %s: "%s"\n' "${entry%%=*}" "${entry#*=}"
done
jq -r --argjson override "${phase_override}" \
'.activationEnv + $override | to_entries[] | " \(.key): \"\(.value)\""' \
jq -r --argjson off "${CAPABILITIES_OFF}" --argjson override "${phase_override}" \
'$off + .activationEnv + $override | to_entries[] | " \(.key): \"\(.value)\""' \
<<<"${lane_json}"
} >"${lane_overlay}"
)
@@ -384,59 +406,25 @@ run_lane() {
#
# The management port, not the application port. Actuator runs on its own connector here so the
# management plane is not published on the public one, and fetching 8080/actuator returned an
# empty file that looked exactly like a failed assertion about the profile.
# empty file that looked exactly like a failed assertion.
local management_port
management_port="$(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \
sh -c 'echo "${MANAGEMENT_SERVER_PORT:-9001}"' 2>/dev/null | tr -d "\r\n")"
management_port="${management_port:-9001}"
# Poll rather than trust `up --wait`. Not every overlay defines a healthcheck — the dev one does
# not — and where there is none `--wait` returns as soon as the container is created, so the first
# fetch landed before the application had finished starting and produced an empty file that read
# exactly like a failed assertion about the profile.
# not — and where there is none `--wait` returns as soon as the container is created.
local attempt
for attempt in $(seq 1 60); do
if docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \
wget -qO- "http://localhost:${management_port}/actuator/adapteractivation" \
>"${LANE_EVIDENCE}/activation.json" 2>/dev/null \
&& [[ -s "${LANE_EVIDENCE}/activation.json" ]]; then
break
wget -qO- "http://localhost:${management_port}/actuator/health" \
>"${LANE_EVIDENCE}/health.json" 2>/dev/null \
&& [[ -s "${LANE_EVIDENCE}/health.json" ]]; then
return 0
fi
sleep 5
done
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \
wget -qO- "http://localhost:${management_port}/actuator/health" \
>"${LANE_EVIDENCE}/health.json" 2>/dev/null || true
local reported
reported="$(jq -r '.activeProfile // empty' "${LANE_EVIDENCE}/activation.json" 2>/dev/null || true)"
if [[ "${reported}" != "${runtime}" ]]; then
echo "${id}: the application reports profile '${reported}', the contract says '${runtime}'" >&2
return 1
fi
# The switches the application says are on must be exactly the ones the lane asked for. Without
# this a lane called local-jpa that ran with JPA off would render the right services, start
# cleanly, and prove nothing — which is the failure mode a green lane is least able to reveal.
local expected_on actual_on
expected_on="$(jq -r '.expectedSwitchesOn | sort | join(",")' <<<"${lane_json}")"
actual_on="$(jq -r '.switches | to_entries | map(select(.value)) | map(.key) | sort | join(",")' \
"${LANE_EVIDENCE}/activation.json")"
if [[ "${expected_on}" != "${actual_on}" ]]; then
echo "${id}: the application reports [${actual_on}] on, the contract expects [${expected_on}]" >&2
return 1
fi
# The vendor the application resolved, not the one the lane started. These differ exactly when a
# profile pins a datasource that outranks the lane's environment, and every other field in the
# report looks correct while it happens.
local expected_vendor actual_vendor
expected_vendor="$(jq -r '.expectedPersistenceVendor' <<<"${lane_json}")"
actual_vendor="$(jq -r '.persistenceVendor // "absent"' "${LANE_EVIDENCE}/activation.json")"
if [[ "${expected_vendor}" != "${actual_vendor}" ]]; then
echo "${id}: the application resolved vendor '${actual_vendor}', the contract expects '${expected_vendor}'" >&2
return 1
fi
echo "${id}: the application never answered /actuator/health on port ${management_port}" >&2
return 1
}
await_application_report || return 1
@@ -460,7 +448,7 @@ run_lane() {
return 1
fi
redact_in_place "${LANE_EVIDENCE}/notification-smoke-phase1.log"
cp "${LANE_EVIDENCE}/activation.json" "${LANE_EVIDENCE}/activation-phase1.json"
cp "${LANE_EVIDENCE}/health.json" "${LANE_EVIDENCE}/health-phase1.json"
# The application only. The database and its volume stay up, which is the whole point.
echo "-- ${id}: restarting the application into the second phase"