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"
+1 -2
View File
@@ -2,7 +2,7 @@
"""Fail when the HTTP Client Platform's code and documentation have drifted.
The design (§33 "Documentation") requires the support matrix, configuration reference, security
guide, runbook, and migration guide to match the code. Review cannot hold that line by itself, so
guide and runbook to match the code. Review cannot hold that line by itself, so
this verifier extracts the names that are part of the public contract -- stable exceptions, metric
names, configuration properties, startup violation codes, and transports -- and fails when one
exists in code but nowhere in the documentation.
@@ -30,7 +30,6 @@ REQUIRED_DOCS = [
"security.md",
"streaming.md",
"operations.md",
"migration-guide.md",
"release-checklist.md",
"performance-baseline.md",
"repository-adaptation.md",
+8 -20
View File
@@ -6,20 +6,18 @@
# without provider infrastructure, and then reports -- explicitly -- which promotion evidence it
# could NOT produce.
#
# Required promotion categories (MongoAdvancedPromotionEvidence.REQUIRED):
# Required promotion categories (docs/adr/ADR-MONGO-ADV-001-capability-promotion.md):
#
# stable-platform, actual-topology, security, migration, failure, runbook
#
# `actual-topology` is the one that cannot be substituted. A container gives a functional pass for
# sharding, search, vector and encryption while exercising none of the behaviour that makes them
# Advanced rather than Stable: real shard distribution, a real analyzer, a real KMS. Atlas Local is
# a pull-request convenience and is not release evidence -- see
# MongoAtlasCapabilityContractSuite.Environment.
# sharding and encryption while exercising none of the behaviour that makes them Advanced rather
# than Stable: real shard distribution, a real KMS.
#
# Usage:
# bash scripts/verify-mongodb-advanced.sh
# MONGODB_DOCKER=1 bash scripts/verify-mongodb-advanced.sh
# MONGODB_SHARDED_URI=... MONGODB_ATLAS_URI=... MONGODB_KMS=... bash scripts/verify-mongodb-advanced.sh
# MONGODB_SHARDED_URI=... MONGODB_KMS=... bash scripts/verify-mongodb-advanced.sh
#
set -euo pipefail
@@ -52,8 +50,7 @@ fi
# --- failure + runbook (hermetic) -------------------------------------------------------------
# Every Advanced refusal contract: disabled capability refuses construction, CSFLE/QE cannot share a
# collection, QE substring/prefix/suffix unsupported on 8.0, a non-READY search index cannot serve,
# undeclared scatter-gather is rejected, a dimension mismatch is refused.
# collection, QE substring/prefix/suffix unsupported on 8.0, undeclared scatter-gather is rejected.
echo ""
echo "=== [failure] Advanced contract tests"
if (cd "${GRADLE_DIR}" && "${GRADLE[@]}" "${MODULE}:test" --tests '*advanced*'); then
@@ -64,7 +61,7 @@ fi
echo ""
echo "=== [runbook] capability documentation"
for doc in sharding time-series encryption search-vector multi-tenancy gridfs-migration; do
for doc in sharding encryption multi-tenancy; do
path="${REPO_ROOT}/docs/mongodb/advanced/${doc}.md"
if [[ -f "${path}" ]]; then
echo " + ${doc}.md"
@@ -106,15 +103,7 @@ fi
# Present is not exercised. An environment variable proves somebody exported a string; the
# contract is satisfied by a lane that ran against the deployment it names, which is why this
# records the variable as *not yet* evidence until MONGO-REL-011's class has run.
if [[ -n "${MONGODB_ATLAS_URI:-}" ]]; then
echo "actual-topology(search/vector): MONGODB_ATLAS_URI present (lane not yet implemented)"
MISSING_EVIDENCE+=("actual-topology: MONGO-REL-011 has no lane; an exported URI is not a run")
else
echo "actual-topology(search/vector): no MONGODB_ATLAS_URI"
MISSING_EVIDENCE+=("actual-topology: search/vector on the actual target deployment")
fi
# records the variable as *not yet* evidence until MONGO-REL-012's class has run.
if [[ -n "${MONGODB_KMS:-}" ]]; then
echo "actual-topology(encryption): MONGODB_KMS present (lane not yet implemented)"
MISSING_EVIDENCE+=("actual-topology: MONGO-REL-012 has no lane; an exported KMS is not a run")
@@ -154,8 +143,7 @@ if (( ${#MISSING_EVIDENCE[@]} > 0 )); then
for entry in "${MISSING_EVIDENCE[@]}"; do echo " ~ ${entry}"; done
echo ""
echo "A capability stays opt-in until every category in"
echo "MongoAdvancedPromotionEvidence.REQUIRED is supplied. See"
echo "docs/adr/ADR-MONGO-ADV-001-capability-promotion.md."
echo "docs/adr/ADR-MONGO-ADV-001-capability-promotion.md is supplied."
echo "---------------------------------------------------------------"
exit 2
fi
+1 -1
View File
@@ -99,7 +99,7 @@ echo "repository: ${REPO_ROOT}"
# --- Always-on lanes -------------------------------------------------------------------------
# Static analysis, architecture boundaries, unit and hermetic contract tests. These produce the
# mapping, transaction, migration, change-stream and security evidence that does not need a server.
run_lane "static-analysis" "check" -x "mongoStableContractTest" -x "verifyMongoReleaseContractLanes"
run_lane "static-analysis" "check" -x "mongoStableContractTest"
run_lane "mapping+transaction+migration+change-stream+security" "mongoStableContractTest"
# --- Container lanes -------------------------------------------------------------------------