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
-63
View File
@@ -1,63 +0,0 @@
name: reusable-gradle
# One place that knows how a Gradle job starts.
#
# Every job in this repository opened with the same preamble: checkout, a three-line pinned
# wrapper-validation step, then the JDK/cache action. The wrapper step is gone (setup-gradle
# validates wrappers itself), and this workflow removes the rest of the repetition for the jobs whose
# only variation is the Gradle command they run.
#
# Jobs that need service containers, a matrix, artifact uploads or per-job env stay written out with
# `./.github/actions/setup-gradle-java`, because expressing those through `workflow_call` inputs
# means encoding YAML inside strings — which is how a "shared" workflow becomes less readable than
# the duplication it replaced.
on:
workflow_call:
inputs:
tasks:
description: The Gradle task list, whitespace-separated.
required: true
type: string
gradle-args:
description: Flags appended after the task list.
required: false
type: string
default: "--stacktrace"
working-directory:
description: Directory the wrapper is invoked from.
required: false
type: string
default: src
timeout-minutes:
required: false
type: number
default: 30
continue-on-error:
description: Run the job as an advisory signal rather than a gate.
required: false
type: boolean
default: false
permissions:
contents: read
jobs:
gradle:
runs-on: ubuntu-latest
timeout-minutes: ${{ inputs.timeout-minutes }}
continue-on-error: ${{ inputs.continue-on-error }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run ${{ inputs.tasks }}
working-directory: ${{ inputs.working-directory }}
env:
GRADLE_TASKS: ${{ inputs.tasks }}
GRADLE_ARGS: ${{ inputs.gradle-args }}
run: |
set -euo pipefail
# Word-split on purpose: both inputs are task/flag lists. They come from this repository's
# own workflow files, never from a pull request.
# shellcheck disable=SC2086
./gradlew ${GRADLE_TASKS} ${GRADLE_ARGS}
+41
View File
@@ -0,0 +1,41 @@
name: build-logic
# The included builds' own tests (TestKit for the convention plugins, unit tests for build-tools).
# The main task graph does not reach them, so they run here — and only when a pull request touches
# the included builds or the catalog they read.
on:
pull_request:
paths:
- "src/build-logic/**"
- "src/build-tools/**"
- "src/gradle/**"
- ".github/workflows/build-logic.yml"
push:
branches: ["main"]
paths:
- "src/build-logic/**"
- "src/build-tools/**"
- "src/gradle/**"
- ".github/workflows/build-logic.yml"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
included-builds:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Test the build-logic convention plugins
working-directory: src
run: ./gradlew -p build-logic test --stacktrace
- name: Test the build-tools verifiers
working-directory: src
run: ./gradlew -p build-tools test --stacktrace
+5 -165
View File
@@ -30,18 +30,6 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Require the committed public-path security baseline
run: |
set -euo pipefail
readonly snapshot='docs/security/public-paths-snapshot.txt'
if [[ ! -s "${snapshot}" ]]; then
echo "::error::${snapshot} is missing or empty. CI must not let verifyPublicPathSnapshot create its own first-run baseline."
exit 1
fi
if ! git ls-files --error-unmatch "${snapshot}" >/dev/null 2>&1; then
echo "::error::${snapshot} exists locally but is not committed."
exit 1
fi
- uses: ./.github/actions/setup-gradle-java
- name: Export the live Gradle verification task map
working-directory: src
@@ -54,47 +42,15 @@ jobs:
if-no-files-found: error
# `ci`, not `check`. A leaf's `check` is that leaf's — compile, its tests, Spotless, Checkstyle
# and Error Prone — and the repository-wide gates are named tasks of their own:
# ci = every leaf check + architectureCheck + qualityCheck + configContractCheck + qualificationCheck
# so CI runs strictly more than it used to while `./gradlew :domain-core:check` runs strictly
# less.
# ci = every leaf check + architectureCheck + qualityCheck
# The main-branch stage (`mainCheck`: environment contract, full-boot qualification, public-path
# baseline, API surfaces, transport and messaging lanes) runs in integration-main.yml.
- name: Run the pull-request gate
working-directory: src
run: ./gradlew :ci :verifyPublicPathSnapshot :verifyDependencyLocks --warning-mode=fail --stacktrace
# Named as its own step because nothing else runs it: `check` does not depend on
# graphqlStableTest, so the lane's required-class guard — the check that its module-boundary
# suite has not silently stopped being discovered — would protect nothing in CI.
- name: Qualify the GraphQL Stable lane
working-directory: src
run: ./gradlew :adapter:inbound:graphql:graphqlStableTest --stacktrace
- name: Qualify opt-in inbound transports without skips
working-directory: src
run: ./gradlew :conditionalTransportQualification --stacktrace
run: ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --stacktrace
- name: Verify Compose profile contracts render exactly as declared
run: bash scripts/verify-compose-profile-contracts.sh
build-logic:
# Included-build tests are independent of the main project task graph. Running them as a
# separate blocking job keeps plugin TestKit work off the quality-gates critical path.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Test the build-logic convention plugins
working-directory: src
run: ./gradlew -p build-logic test --stacktrace
build-tools:
# build-tools is an included build, so its verifier tests are not reached by the main :ci task.
# These tests protect env/JPA/messaging/Mongo/notification evidence parsers; a broken verifier
# must fail the pull-request gate rather than silently bless bad evidence.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Test the build-time verifier plugins
working-directory: src
run: ./gradlew -p build-tools test --stacktrace
sample-portfolio:
# The sample is excluded from production architecture/runtime membership policy, but it is still
# the reference implementation adopters copy. Compile/test/OpenAPI drift must therefore block PRs.
@@ -106,19 +62,6 @@ jobs:
working-directory: src
run: ./gradlew :sample-portfolio:check --stacktrace
redis-sdk:
# Milestone A of the Redis wrapper/typed API plan: policy catalog, typed API parity, permit
# provenance, connection isolation, and the executor guard. There is no real-server lane yet.
#
# `verifyConfigurationPropertiesProcessor` used to be in this list. It is deleted: the parity it
# enforced — a leaf declares Spring's configuration processor exactly when it owns
# @ConfigurationProperties — is now what applying `ca.spring-config` means.
# `verifyEnvKeys` is no longer named here either; it belongs to :app-bootstrap and runs through
# `configContractCheck`, which the quality-gates job covers.
uses: ./.github/workflows/_reusable-gradle.yml
with:
tasks: ":shared-contract:test --tests '*EdgeRateLimitProviderNeutralContractTest'"
optional-platforms:
runs-on: ubuntu-latest
steps:
@@ -128,104 +71,11 @@ jobs:
working-directory: src
run: ./gradlew -p optional-platforms ci --stacktrace
configuration-cache:
# Two questions, and they are not the same question.
#
# The first is whether every task in the repository-wide gates can be *stored*. That is a
# property of the task graph, so `--dry-run` answers it for the whole of `ci`,
# `integrationCheck` and `releaseCheck` in seconds, and it is the question this job used to
# duck: it checked two leaves, because four tasks elsewhere held a live `Configuration` in
# their state and could not be serialised at all. They hold resolved root components now, so
# the honest scope is all three gates rather than two leaves.
#
# The second is whether a stored entry is actually *reused* and the build still executes its
# work. `--dry-run` cannot answer that, so the executing check stays — on the two core leaves,
# because doubling a full `ci` run to prove reuse would cost more than the guarantee is worth.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Require every repository-wide gate to be storable
working-directory: src
shell: bash
run: |
set -euo pipefail
for gate in ci integrationCheck releaseCheck; do
echo "::group::${gate}"
./gradlew "${gate}" --dry-run \
--configuration-cache --configuration-cache-problems=fail --stacktrace
output="$({ ./gradlew "${gate}" --dry-run \
--configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)"
printf '%s\n' "${output}"
echo '::endgroup::'
grep -Fq 'Reusing configuration cache.' <<<"${output}" || {
echo "::error::Gradle did not reuse the configuration cache for ${gate}."
exit 1
}
done
- name: Store configuration cache for the everyday core build
working-directory: src
run: >-
./gradlew
:domain-core:check
:application-core:check
--configuration-cache
--configuration-cache-problems=fail
--stacktrace
- name: Require configuration-cache reuse
working-directory: src
shell: bash
run: |
set -euo pipefail
output="$({ ./gradlew :domain-core:check :application-core:check \
--configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)"
printf '%s\n' "${output}"
grep -Fq 'Reusing configuration cache.' <<<"${output}" || {
echo '::error::Gradle did not reuse the configuration cache on the second identical build.'
exit 1
}
jpa-candidate-evidence:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Produce zero-skip JPA candidate manifests
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:verifyJpaCandidateEvidence
--stacktrace
- name: Retain content-addressed JPA candidate manifests
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
with:
name: jpa-candidate-evidence-${{ github.sha }}
path: src/adapter/outbound/persistence-jpa/build/jpa-evidence/manifests
if-no-files-found: error
retention-days: 14
# Advisory. The quarantine bucket runs so a flaky test is still executed and reported; it never
# blocks. The 14-day sunset registry that used to make an expired quarantine entry a build failure
# is gone — it was a 250-line YAML-and-Java parser guarding a registry with zero entries.
quarantine:
uses: ./.github/workflows/_reusable-gradle.yml
with:
tasks: ":quarantineTest"
gradle-args: "--stacktrace"
continue-on-error: true
release-gate:
needs:
- quality-gates
- build-logic
- build-tools
- sample-portfolio
- redis-sdk
- jpa-candidate-evidence
- optional-platforms
- configuration-cache
if: always()
runs-on: ubuntu-latest
permissions:
@@ -234,24 +84,14 @@ jobs:
- name: Require every current blocking job to succeed
env:
QUALITY_RESULT: ${{ needs.quality-gates.result }}
BUILD_LOGIC_RESULT: ${{ needs.build-logic.result }}
BUILD_TOOLS_RESULT: ${{ needs.build-tools.result }}
SAMPLE_RESULT: ${{ needs.sample-portfolio.result }}
REDIS_RESULT: ${{ needs.redis-sdk.result }}
JPA_CANDIDATE_RESULT: ${{ needs.jpa-candidate-evidence.result }}
OPTIONAL_PLATFORMS_RESULT: ${{ needs.optional-platforms.result }}
CONFIGURATION_CACHE_RESULT: ${{ needs.configuration-cache.result }}
run: |
set -euo pipefail
for result in \
"${QUALITY_RESULT}" \
"${BUILD_LOGIC_RESULT}" \
"${BUILD_TOOLS_RESULT}" \
"${SAMPLE_RESULT}" \
"${REDIS_RESULT}" \
"${JPA_CANDIDATE_RESULT}" \
"${OPTIONAL_PLATFORMS_RESULT}" \
"${CONFIGURATION_CACHE_RESULT}"; do
"${OPTIONAL_PLATFORMS_RESULT}"; do
if [[ "${result}" != "success" ]]; then
echo "::error::release-gate: required job result was ${result}"
exit 1
@@ -43,13 +43,6 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the architecture-wide dependency and module verification
working-directory: src
run: >-
./gradlew
:verifyCleanArchitectureDependencies
--stacktrace
- name: Run the complete fileserver suite across every leaf
working-directory: src
run: >-
-1
View File
@@ -108,6 +108,5 @@ jobs:
run: >-
./gradlew
:adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest'
:adapter:inbound:web:test --tests '*DataBufferReleaseTest'
--stacktrace
+101 -53
View File
@@ -15,21 +15,20 @@ name: integration-main
# shared. They now run on every push to main as well as nightly, which is strictly more often
# than before.
#
# 2. Lanes that were registered in Gradle and invoked by nothing. Ten Gradle tasks — six MongoDB
# container lanes, app-bootstrap's Testcontainers `integrationTest`, and the three messaging
# evidence tasks that `verifyMessagingContracts` reaches — existed, failed closed, and executed
# in no workflow. A lane nobody runs is not coverage; it is a file that looks like coverage. They
# 2. Lanes that were registered in Gradle and invoked by nothing — the MongoDB container lanes and
# app-bootstrap's Testcontainers `integrationTest` — existed, failed closed, and executed in no
# workflow. A lane nobody runs is not coverage; it is a file that looks like coverage. They
# are here rather than in stage 1 because every one of them either starts containers or re-runs
# suites the PR gate already covers, and the pull-request budget is minutes for the whole gate.
#
# What is deliberately NOT here: the web and WebSocket "Advanced capability" nightly lanes that used
# to exist as web-advanced-nightly.yml and websocket-advanced-nightly.yml. Both leaves' build files
# say it outright — "They also run inside `test`, deliberately ... excluding them from the PR gate to
# make this lane look meaningful would mean the PR gate stopped covering a fifth of the leaf" — so
# `webAdvancedTest` and `websocketAdvancedTest` select tagged tests that `:<leaf>:test` already runs,
# and `:<leaf>:test` runs inside the root `check` on every pull request and every push to main. The
# strict lanes themselves survive in release.yml, where their fail-on-nothing-discovered guard is
# worth a job.
# What is deliberately NOT here: the web "Advanced capability" nightly lane that used to exist as
# web-advanced-nightly.yml (websocket-advanced-nightly.yml went with the websocket Advanced code,
# deleted 2026-09-25). The web leaf's build file says it outright — "They also run inside `test`,
# deliberately ... excluding them from the PR gate to make this lane look meaningful would mean the
# PR gate stopped covering a fifth of the leaf" — so `webAdvancedTest` selects tagged tests that
# `:<leaf>:test` already runs, and `:<leaf>:test` runs inside the root `check` on every pull request
# and every push to main. The strict lane itself survives in release.yml, where its
# fail-on-nothing-discovered guard is worth a job.
on:
push:
@@ -58,6 +57,93 @@ concurrency:
# answer: does this link resolve.
jobs:
# The main-branch stage of the Gradle gates (`:mainCheck`): the environment contract, full-boot
# qualification, the sample web contract, the public-path baseline, the API surfaces, the
# conditional transport lanes, the messaging contract lanes and the JPA readiness registry. They
# left the pull-request gate (review 2026-09-24 BUILD, item 12); none of them is deleted.
main-check:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Require the committed public-path security baseline
run: |
set -euo pipefail
readonly snapshot='docs/security/public-paths-snapshot.txt'
if [[ ! -s "${snapshot}" ]] || ! git ls-files --error-unmatch "${snapshot}" >/dev/null 2>&1; then
echo "::error::${snapshot} is missing, empty or not committed; verifyPublicPathSnapshot must not create its own baseline."
exit 1
fi
- uses: ./.github/actions/setup-gradle-java
- name: Run the main-branch stage
working-directory: src
run: ./gradlew :mainCheck --warning-mode=fail --stacktrace
# Two questions. Can every task in the repository-wide gates be *stored* (a property of the task
# graph, so `--dry-run` answers it for all of them in seconds)? And is a stored entry *reused* while
# the build still executes its work (checked on the two core leaves)?
configuration-cache:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Require every repository-wide gate to be storable
working-directory: src
shell: bash
run: |
set -euo pipefail
for gate in ci mainCheck integrationCheck releaseCheck; do
echo "::group::${gate}"
./gradlew "${gate}" --dry-run \
--configuration-cache --configuration-cache-problems=fail --stacktrace
output="$({ ./gradlew "${gate}" --dry-run \
--configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)"
printf '%s\n' "${output}"
echo '::endgroup::'
grep -Fq 'Reusing configuration cache.' <<<"${output}" || {
echo "::error::Gradle did not reuse the configuration cache for ${gate}."
exit 1
}
done
- name: Store configuration cache for the everyday core build
working-directory: src
run: >-
./gradlew
:domain-core:check
:application-core:check
--configuration-cache
--configuration-cache-problems=fail
--stacktrace
- name: Require configuration-cache reuse
working-directory: src
shell: bash
run: |
set -euo pipefail
output="$({ ./gradlew :domain-core:check :application-core:check \
--configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)"
printf '%s\n' "${output}"
grep -Fq 'Reusing configuration cache.' <<<"${output}" || {
echo '::error::Gradle did not reuse the configuration cache on the second identical build.'
exit 1
}
jpa-candidate-evidence:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Produce zero-skip JPA candidate manifests
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:verifyJpaCandidateEvidence --stacktrace
- name: Retain content-addressed JPA candidate manifests
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
with:
name: jpa-candidate-evidence-${{ github.sha }}
path: src/adapter/outbound/persistence-jpa/build/jpa-evidence/manifests
if-no-files-found: error
retention-days: 14
# Load, abuse and graceful shutdown measure behaviour that degrades gradually rather than breaking
# outright — which is exactly the kind of regression a per-PR gate never catches.
web-load-abuse-and-shutdown:
@@ -72,7 +158,6 @@ jobs:
./gradlew
:adapter:inbound:web:test
:adapter:inbound:web:webJettyCompatTest
:adapter:inbound:web:webFluxContractTest
--stacktrace
- name: Publish the test reports
@@ -181,40 +266,6 @@ jobs:
path: src/adapter/outbound/persistence-mongo/build/reports/tests/
if-no-files-found: warn
# The messaging contract evidence DAG. `verifyMessagingContracts` is the root of a chain that ran
# nowhere: it depends on four production qualification tasks (application-core,
# shared-contract and two in adapter:outbound:messaging), each of which depends on
# `prepareMessagingContractEvidence`; it is finalizedBy
# `validateMessagingContractsEvidenceManifestSchema`; and it depends on
# `validateMessagingJsonSchemaV1EvidenceManifestSchema`, which depends on
# `verifyMessagingJsonSchemaV1`. Strict qualification tasks are registered outside `check` by
# design (ca.strict-qualification.gradle), so none of the seven was reachable from any workflow.
#
# The schema validators are the part that matters. They re-read the manifest bytes the run just
# wrote and validate them against config/messaging/evidence/build-evidence-manifest-v1.schema.json
# — a manifest that claims a qualification nobody executed is exactly the failure they exist to
# catch, and until now nothing executed them either.
#
# Stage 2 rather than stage 1: no containers, but it runs four qualification suites across three
# leaves plus two JavaExec validators, and the tests it re-runs are already inside the PR gate's
# `check`. What this job adds is the evidence manifest, which is a main-branch artifact.
messaging-contract-evidence:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Qualify the messaging contract, catalog, binding and schema evidence
working-directory: src
run: ./gradlew :verifyMessagingContracts --stacktrace
- name: Publish the messaging evidence manifest
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: messaging-contract-evidence
path: src/build/messaging-evidence/
if-no-files-found: warn
# app-bootstrap's Testcontainers lane. The leaf gave it a source set of its own precisely so that
# `./gradlew :app-bootstrap:test` would not require a Docker daemon — and the consequence nobody
# closed is that a source set outside `test` is also outside `check`, so the real-PostgreSQL
@@ -241,9 +292,6 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: RabbitMQ transport contract
working-directory: src
run: ./gradlew :messaging:messaging-rabbit:integrationTest --stacktrace
- name: Inbox PostgreSQL contract
working-directory: src
run: ./gradlew :messaging:messaging-inbox-jdbc-postgresql:integrationTest --stacktrace
@@ -274,9 +322,6 @@ jobs:
- name: Distributed lock contract
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest --stacktrace
- name: Idempotency unique-scope contract
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlIdempotencyUniqueScopeIntegrationTest --stacktrace
- name: Integer lock migration compatibility
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlIntLockMigrationCompatibilityIntegrationTest --stacktrace
@@ -323,6 +368,9 @@ jobs:
# main and nightly; a partial lane run is reproduction only and cannot satisfy this job. The count
# is not written here on purpose — a number in prose drifts the moment a lane is added, and the
# matrix file is the thing this job reads.
#
# The lanes boot the qualification image (src/Dockerfile COMPOSITION=qualification: every
# capability module present). The script selects it; release.yml builds the default image.
compose-runtime-smoke:
runs-on: ubuntu-latest
timeout-minutes: 180
+4 -4
View File
@@ -21,17 +21,17 @@ jobs:
- id: jakarta-persistence-4
target: Jakarta Persistence 4
coordinate: jakarta.persistence:jakarta.persistence-api:4.x
test: "*CompatibilityLaneDefinitionTest"
test: "*Jpa4CompatibilityTest"
reason: the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it
- id: hibernate-8
target: Hibernate 8
coordinate: org.hibernate.orm:hibernate-core:8.x
test: "*HibernateCompatibilityPolicyTest"
test: "*Hibernate8CompatibilityTest"
reason: Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it
- id: postgresql-19
target: PostgreSQL 19
coordinate: postgres:19-alpine
test: "*ExperimentalPromotionGateTest"
test: "*PostgreSql19CompatibilityTest"
reason: no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane
runs-on: ubuntu-latest
timeout-minutes: 60
@@ -61,7 +61,7 @@ jobs:
echo "status=NOT_EXECUTABLE"
echo "probe-result=${PROBE_OUTCOME}"
echo "reason=${REASON}"
echo "what-ran=the current runtime's own policy and lane-definition tests"
echo "what-ran=the current runtime's own version canary for this target"
echo "sha=${{ github.sha }}"
} > compatibility-evidence/status.properties
echo "::notice::${TARGET} compatibility is NOT_EXECUTABLE: ${REASON}"
+1 -4
View File
@@ -114,15 +114,12 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Verify architecture boundaries and the support matrix
- name: Verify the release registry and the support matrix
working-directory: src
run: >-
./gradlew
:verifyJpaReleaseGateTasks
:verifyJpaReadinessRegistry
:verifyCleanArchitectureDependencies
checkstyleMain
:app-bootstrap:architectureTest
:adapter:outbound:persistence-jpa:test --tests '*JpaReleaseManifestTest'
--stacktrace
+12 -21
View File
@@ -22,8 +22,8 @@ on:
- 'src/adapter/outbound/notification/**'
- 'src/adapter/outbound/persistence-jpa/src/**/notification/**'
- 'src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/notification-platform/**'
- 'src/adapter/inbound/web/src/**/notification/**'
- 'src/app-bootstrap/src/**/notification/**'
- 'src/adapter/inbound/web-notification/**'
- 'src/composition/notification-platform/**'
- 'src/app-bootstrap/src/main/resources/application*.yml'
- 'src/gradle/notification-*.gradle'
- 'src/config/architecture/modules.json'
@@ -67,7 +67,7 @@ jobs:
run: ./gradlew :adapter:outbound:notification:test --console=plain
- name: Persistence and web
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:test :adapter:inbound:web:test --console=plain
run: ./gradlew :adapter:outbound:persistence-jpa:test :adapter:inbound:web-notification:test :composition:notification-platform:test --console=plain
# The PR tier never touched a database, so every claim about migrations, claim atomicity and
# lease fencing rested on a fake. Docker is available on this runner; the lane fails closed
# when the container cannot start, because a skipped contract reports success for a database
@@ -78,22 +78,12 @@ jobs:
- name: Notification migration upgrade (real PostgreSQL)
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest --console=plain
- name: Architecture gates
# The architecture gates run in ci-quality-gates.yml on the same pull request; the evidence
# manifest (NotificationEvidenceVerifierTest) and the environment registry
# (NotificationEnvironmentRegistryTest) are leaf tests the steps above already ran.
- name: Notification API surface
working-directory: src
run: |
./gradlew :verifyCleanArchitectureDependencies --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain
- name: Configuration surface
working-directory: src
run: |
./gradlew :app-bootstrap:verifyEnvKeys :verifyPublicPathSnapshot --console=plain
./gradlew :verifyNotificationApiSurface :verifyNotificationConfiguration --console=plain
# A support grade is a promise about production behaviour. This refuses one the pipeline
# cannot back — the check that would have caught five channels reading "Stable" while no
# request had ever left the process.
- name: Evidence manifest
working-directory: src
run: ./gradlew :verifyNotificationEvidence --console=plain
run: ./gradlew :adapter:outbound:notification:verifyNotificationApiSurface --console=plain
- name: Static analysis
working-directory: src
run: ./gradlew :adapter:outbound:notification:check -x test --console=plain
@@ -125,7 +115,8 @@ jobs:
:application-core:test
:adapter:outbound:notification:test
:adapter:outbound:persistence-jpa:test
:adapter:inbound:web:test
:adapter:inbound:web-notification:test
:composition:notification-platform:test
--console=plain
# A filter that matches nothing passes. Each --tests filter above names a class that exists
# today; if one is renamed the job must fail rather than quietly stop covering it.
@@ -149,5 +140,5 @@ jobs:
#
# The unimplemented state is still stated in two places that do not depend on a workflow:
# ProviderSandboxSmokeTest itself, and the unsatisfied provider-wire-qualified claim in
# docs/notification/evidence-manifest.json, which verifyNotificationEvidence enforces inside
# check. When a real sandbox call is implemented, the job comes back with it.
# docs/notification/evidence-manifest.json, which NotificationEvidenceVerifierTest enforces in
# the notification leaf's tests. When a real sandbox call is implemented, the job comes back with it.
+12 -31
View File
@@ -12,8 +12,8 @@ name: pr-adapters
# here is only what `check` does not run.
#
# What `check` does not run, and therefore what this file is for:
# * lanes with their own source set — a second servlet container, a real Nginx, Reactor Netty;
# * lanes selected by a tag that `test` excludes — the cross-stack parity recording comparison;
# * lanes with their own source set — the servlet system contract, a second servlet container,
# a real Nginx;
# * lanes parameterised per run — one PostgreSQL major per job, one HTTP transport per job.
# Each of those genuinely cannot run inside `check`, which is the test for whether a job belongs
# here at all.
@@ -126,10 +126,9 @@ jobs:
'^infra/jpa/' \
"${common}"
# The parity gate depends on all three recording lanes and fails when one is missing, so it runs
# them itself rather than trusting a previous job to have left the recordings behind. Its tag is
# excluded from `test`, which is why `check` cannot cover it.
web-cross-stack-parity:
# The servlet system contract on both containers the template supports (Tomcat, Jetty). Real
# sockets, so neither lane is part of `check`.
web-servlet-containers:
needs: changes
if: needs.changes.outputs.web == 'true'
runs-on: ubuntu-latest
@@ -137,39 +136,21 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Compare the wire contract across Tomcat, Jetty and Reactor Netty
- name: Run the servlet system contract on Tomcat and Jetty
working-directory: src
run: >-
./gradlew
:adapter:inbound:web:webCrossStackParityTest
:adapter:inbound:web:systemTest
:adapter:inbound:web:webJettyCompatTest
--stacktrace
- name: Publish the parity recordings
- name: Publish the test reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: web-contract-parity
path: src/adapter/inbound/web/build/web-contract-parity/
if-no-files-found: error
# Docker-gated, and the lane fails rather than skipping when the runtime is missing. A proxy
# contract that quietly passes without a proxy has been certifying nothing since whenever the
# container runtime last broke.
web-nginx-proxy-contract:
needs: changes
if: needs.changes.outputs.web == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the proxy, prefix and spoofing contract behind a real Nginx
working-directory: src
run: >-
./gradlew
:adapter:inbound:web:webNginxProxyTest
--stacktrace
name: web-servlet-containers-reports
path: src/adapter/inbound/web/build/reports/tests/
if-no-files-found: warn
websocket-container-matrix:
needs: changes
+16 -7
View File
@@ -31,6 +31,8 @@ name: redis-sdk-topology
on:
pull_request:
paths:
- "src/adapter/outbound/redis-runtime/**"
- "src/adapter/outbound/redis-sdk/**"
- "src/adapter/outbound/cache-redis/**"
- "infra/redis-sdk/**"
- ".github/workflows/redis-sdk-topology.yml"
@@ -145,10 +147,15 @@ jobs:
working-directory: src
run: |
set -euo pipefail
# Each leaf declares the lanes its tests qualify; a mode a leaf does not declare fails
# closed, so each topology names exactly the leaves that have classes for it.
runtime=:adapter:outbound:redis-runtime:redisTopologyTest
sdk=:adapter:outbound:redis-sdk:redisTopologyTest
semantic=:adapter:outbound:cache-redis:redisTopologyTest
case '${{ matrix.topology }}' in
standalone) port=6379; extra='' ;;
sentinel) port=27010; extra='-Predis.topology.master=skeleton' ;;
cluster) port=7100; extra='' ;;
standalone) port=6379; extra=''; tasks="$runtime $sdk $semantic" ;;
sentinel) port=27010; extra='-Predis.topology.master=skeleton'; tasks="$runtime $sdk" ;;
cluster) port=7100; extra=''; tasks="$runtime $sdk $semantic" ;;
# The TLS lane's CA is generated at start-up, so the trust material is extracted from
# the lane rather than checked in. A checked-in key is a secret in the repository
# however loudly the file is named "test".
@@ -156,10 +163,11 @@ jobs:
port=6390
docker compose -f ../infra/redis-sdk/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem"
tasks="$runtime"
;;
*) echo "unknown topology"; exit 1 ;;
esac
./gradlew :adapter:outbound:cache-redis:redisTopologyTest --console=plain \
./gradlew $tasks --continue --console=plain \
-Predis.topology.host=localhost \
-Predis.topology.port="$port" \
-Predis.topology.mode='${{ matrix.topology }}' \
@@ -168,7 +176,7 @@ jobs:
if: always()
run: |
set -euo pipefail
out=src/adapter/outbound/cache-redis/build/test-results/redisTopologyTest
out=src/build/redis-topology-evidence
mkdir -p "$out"
cat > "$out/evidence-manifest.txt" <<MANIFEST
commit=${{ github.sha }}
@@ -184,8 +192,9 @@ jobs:
with:
name: redis-topology-${{ matrix.topology }}-${{ matrix.redis_version }}
path: |
src/adapter/outbound/cache-redis/build/test-results/redisTopologyTest/**
src/adapter/outbound/cache-redis/build/reports/tests/redisTopologyTest/**
src/build/redis-topology-evidence/**
src/adapter/outbound/*/build/test-results/redisTopologyTest/**
src/adapter/outbound/*/build/reports/tests/redisTopologyTest/**
if-no-files-found: error
retention-days: 90
- name: Stop the topology
+10 -11
View File
@@ -59,12 +59,11 @@ jobs:
working-directory: src
run: ./gradlew :releaseCheck --stacktrace
# Every web lane that `check` cannot reach. webCrossStackParityTest depends on `test`,
# webJettyCompatTest and webFluxContractTest, so naming it runs all four — which is what
# web-advanced-release.yml spent a separate 90-minute job doing by naming the three by hand.
# Every web lane that `check` cannot reach: the servlet system contract on Tomcat (systemTest)
# and Jetty (webJettyCompatTest), and the Advanced lane.
#
# webAdvancedTest is here rather than in a nightly of its own. Its tests run inside
# `:adapter:inbound:web:test` by design, so the lane adds exactly one thing: it fails closed when
# `:adapter:inbound:web-advanced:test` by design, so the lane adds exactly one thing: it fails closed when
# the `web-advanced` tag selects nothing. That is worth asserting at a release and is not worth a
# workflow file and a runner every night.
web-stable-release-gate:
@@ -77,9 +76,9 @@ jobs:
working-directory: src
run: >-
./gradlew
:adapter:inbound:web:webCrossStackParityTest
:adapter:inbound:web:webNginxProxyTest
:adapter:inbound:web:webAdvancedTest
:adapter:inbound:web:systemTest
:adapter:inbound:web:webJettyCompatTest
:adapter:inbound:web-advanced:webAdvancedTest
--stacktrace
- name: Publish the release evidence
@@ -88,8 +87,8 @@ jobs:
with:
name: web-release-evidence
path: |
src/adapter/inbound/web/build/web-contract-parity/
src/adapter/inbound/web/build/reports/tests/
src/adapter/inbound/web-advanced/build/reports/tests/
if-no-files-found: error
websocket-stable-release-gate:
@@ -98,15 +97,15 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run every websocket lane, Stable and Advanced
- name: Run every websocket lane
working-directory: src
run: >-
./gradlew
:adapter:inbound:websocket:test
:adapter:inbound:websocket:systemTest
:adapter:inbound:websocket:websocketJettyTest
:adapter:inbound:websocket:websocketNginxTest
:adapter:inbound:websocket:websocketTransportQualificationTest
:adapter:inbound:websocket:websocketAdvancedTest
--stacktrace
- name: Publish the release evidence
@@ -120,7 +119,7 @@ jobs:
# The three gRPC certification lanes. Their tests already run on every pull request — the
# `grpc-inprocess`, `grpc-netty` and `grpc-fault` tags are NOT excluded from
# `:grpc:grpc-testkit:test` (only `grpc-performance` is), and that task runs inside the root
# `check`. So this job adds exactly what the web and WebSocket Advanced lanes above add: the lane
# `check`. So this job adds exactly what the web Advanced lane above adds: the lane
# fails closed when its tag selects nothing, which is the one thing a tag-filtered suite inside
# `test` cannot tell you. A renamed or deleted @Tag would otherwise leave the in-process,
# transport and fault evidence grades claiming coverage that stopped existing.
+69 -9
View File
@@ -49,8 +49,8 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
## Gradle 정책 권위
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로,
Gradle path, 허용 production project dependency edge. runtime membership은 실제 resolved
runtimeClasspath에서 검증하며 registry에 별도 membership 목록을 복제하지 않는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 —
Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다: 조립 루트가
받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 —
산문에 적힌 숫자는 leaf가 추가되는 순간 drift하기 때문이다. 이제 이걸 강제하는 태스크는 없다:
`verifyDocumentedLeafCount`는 삭제됐다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬
사유는 아니고, 그 태스크는 모든 `CLAUDE.md`와 `build.gradle`을 정규식으로 훑는 파서였다.
@@ -59,10 +59,15 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은
`verifyCleanArchitectureDependencies`가 답한다 — settings에서 죽으면 실행할 수 있는 태스크가
하나도 없다.
- `src/build-logic/`: convention plugin. leaf는 `ca.java-library` / `ca.spring-library` /
`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트
기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 소유한다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `releaseCheck`, `qualityCheck`,
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나
(`strictTestLanes`). leaf는 `ca.java-library` / `ca.spring-library` / `ca.platform-module` 중
자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다.
`ca.architecture`가 아키텍처 검증 태스크를 소유한다. 기능별 검사(notification·mongo·messaging·
graphql 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면 그 파일을
그 leaf의 test task `inputs`로 선언한다.
- `src/build-tools/`: 아직 옮기지 않은 검사만 남는다(`ca.config-contract`의 `verifyEnvKeys`, JPA
evidence·readiness·release registry). 새 검사를 여기에 추가하지 않는다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `releaseCheck`, `qualityCheck`,
`configContractCheck`, `integrationCheck`)과 버전/리비전
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
@@ -86,7 +91,7 @@ commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit
## 모듈 책임
모든 leaf 모듈의 ID, 실제 소스 경로, Gradle path, 허용 production 의존성, runtime membership은
모든 leaf 모듈의 ID, 실제 소스 경로, Gradle path, 허용 production 의존성은
`src/config/architecture/modules.json`이 SSOT다. focused test는 소유 leaf의 `gradle_path`에서
파생한다. 이 문서는 leaf 목록을 복제하지 않고 family 책임만 정의한다. 작업 파일에서는 가장 가까운
`src/**/CLAUDE.md`를 함께 읽는다.
@@ -145,6 +150,27 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
- 그 밖의 `adapter:outbound:*`: external capability adapter contract를 검증한다.
- `app-bootstrap/settings`: configuration binding, validation, logging 설정을 검증한다.
테스트 작성 규칙 (새로 쓰거나 고치는 테스트에 적용):
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 언어는 영어로
통일한다.
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
`// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다.
4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다.
5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는
`extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`/`isPresent`/
`doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외).
예외는 타입과 reason/message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다.
6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는
포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크
경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다.
GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고,
실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다.
검증 원칙:
- 완료를 주장하기 전에 `superpowers:verification-before-completion`을 사용한다.
@@ -157,9 +183,10 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
cd src
./gradlew <owner-gradle-path>:check --console=plain # 그 leaf만: 컴파일·테스트·포맷·스타일·ErrorProne
./gradlew check # 모든 leaf의 check
./gradlew architectureCheck # 의존 방향·런타임 멤버십·application-core 순수성
./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
./gradlew ci # PR 게이트 = leaf check + architecture + quality + config + qualification
./gradlew ci # PR 게이트 = leaf check + architecture + quality
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·API surface·전송/메시징 레인·JPA readiness
./gradlew verifyPublicPathSnapshot
./gradlew :app-bootstrap:verifyEnvKeys
```
@@ -169,6 +196,39 @@ leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름
소유 leaf의 정확한 Gradle path는 `src/config/architecture/modules.json`에서 읽고 focused test
명령을 파생한다. root 문서에 leaf별 명령 목록을 복제하지 않는다.
## 부가 기능(capability) 모듈 규칙
Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다.
각 서비스는 `app-bootstrap/build.gradle`에 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
설계 근거는 `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md`.
템플릿 기본 조립은 web에서 쓰는 부분뿐이다: `adapter:inbound:web`, 운영 관측(actuator·metrics·
tracing·로그), `domain-core`·`application-core`·`shared-contract`, `adapter:outbound:support`·
`adapter:outbound:identifier`. 그 밖의 기능(JPA 포함)은 한 줄을 추가해서 켠다.
capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다.
2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled`
설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 명시한다(`afterName`).
3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키
자체를 두지 않는다.
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
constructor에서 한다.
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두
통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지
않고, 한 줄을 지우면 기능이 완전히 사라진다.
모듈 설정 기본값은 `config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의
`ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf
(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다.
서비스 코드가 모듈 타입을 직접 호출해야 하는 라이브러리형 기능은 `runtimeOnly`로 컴파일되지
않는다. 그런 기능은 가능한 한 포트 뒤로 옮기고, 불가피하면 서비스의 어댑터 leaf에서
`implementation`으로 받는다.
## 설정과 런타임
설정 규칙:
+31 -10
View File
@@ -21,12 +21,18 @@ If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must
## Gradle policy authorities
- `src/config/architecture/modules.json`: every registered leaf identity, repository-relative source
paths, Gradle paths, allowed production project dependency edges, and the exact runtime
memberships of both composition roots. The registry owns the leaf list and its size; no document
restates the count, because a number written in prose drifts the moment a leaf is added.
paths, Gradle paths and allowed production project dependency edges. There is no runtime
membership list: what a composition root may take is its `allowed_dependencies`, and the direction
gate refuses any other edge. The registry owns the leaf list and its size; no document restates
the count, because a number written in prose drifts the moment a leaf is added.
- `src/settings.gradle`: fail-closed registry validation, project inclusion, and directory mapping.
- `src/build.gradle`: `verifyCleanArchitectureDependencies` and the other architecture-wide
verification tasks.
- `src/build-logic/`: the architecture core (registry, direction and purity tasks), the conventions,
and one test-lane mechanism (`strictTestLanes`). Feature-specific checks are the owning leaf's
tests; a test that reads repository files declares them as that leaf's test `inputs`.
- `src/build-tools/`: only checks not yet moved (`verifyEnvKeys`, JPA evidence/readiness/release
registry). Do not add new checks there.
- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `releaseCheck` and the named
repository-wide gates).
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
@@ -112,15 +118,30 @@ Architecture-wide commands:
```
A leaf's `check` covers that leaf only — compile, its tests, Spotless, Checkstyle, Error Prone.
Repository-wide questions have their own names: `architectureCheck` (dependency direction, runtime
membership, application-core purity, Git-carryable sources), `qualityCheck` (SpotBugs, FindSecBugs),
`configContractCheck` (the environment contract), `integrationCheck` (the declared strict test
lanes). `ci` is leaf checks + architectureCheck + qualityCheck + configContractCheck + qualificationCheck; `releaseCheck` adds
provenance, archive hygiene and the public-path snapshot.
Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity
of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck`
(SpotBugs, FindSecBugs), `configContractCheck` (the environment contract), `integrationCheck` (the
declared strict integration lanes). `ci` (pull request) is leaf checks + architectureCheck +
qualityCheck; `mainCheck` (main branch) is configContractCheck + qualificationCheck + the sample web
contract + the public-path snapshot + API surfaces + the transport and messaging qualification lanes
+ the JPA readiness registry; `releaseCheck` is `ci` + provenance, archive hygiene and the
public-path snapshot.
Test-writing rules (behavior-sentence names that assert what they promise, given/when/then comments,
one `// when`, one fake per port in the port owner's testFixtures, fake and adapter sharing one
abstract contract test) are canonical in `AGENTS.md`.
Use public-path and env-key checks only when their surfaces changed. Full `test`, `check` or `ci`
requires the controller's workflow authorization.
## Capability modules
Optional features (JPA, Redis, Kafka, notification, Mongo, object storage, HTTP client, GraphQL,
WebSocket, gRPC, file server) are modules that turn on when present and disappear when removed. A
service selects them with one `runtimeOnly` line each in `app-bootstrap/build.gradle`; the template's
default composition is the web inbound adapter, observability, the cores, and support/identifier. The
seven completion criteria for a capability module are canonical in `AGENTS.md`.
## Advisory and reporting
Use dependency-DAG/topological reasoning and 3–5 materially distinct alternatives when that many
+12 -7
View File
@@ -23,7 +23,7 @@ family 수준의 책임은 다음과 같습니다.
| `application-core` | command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 |
| `adapter:inbound:*` | HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 |
| `adapter:outbound:persistence-*` | JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration |
| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 외부 연동 어댑터(messaging·cache·notification·HTTP client)는 기본 비활성 |
| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고릅니다 |
| `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
| `app-bootstrap` | Spring Boot entrypoint와 composition root |
| `sample-portfolio` | WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 |
@@ -42,7 +42,7 @@ cd src
./gradlew bootstrap
```
`bootstrap`은 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동(startup Flyway 포함), sample 격리 검증, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 별도 Gradle task라 실패 단계가 task 이름으로 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
`bootstrap`은 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, sample 격리 검증, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 별도 Gradle task라 실패 단계가 task 이름으로 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
```bash
curl -fsS http://localhost:8080/api/healthcheck
@@ -56,22 +56,27 @@ docker compose -f docker-compose.yml -f docker-compose.local.yml down
`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다.
### 프로파일별 데이터스토어
### 기본 조립과 부가 기능
`bootstrap`은 컨테이너 경로(PostgreSQL)를 검증하는 첫 실행 진입점입니다. 일상 개발은 Docker 없이 돌리는 `local` 프로파일이며, 이때 데이터스토어는 H2 in-memory입니다.
기본 조립(`bootJar`)은 web, 관측, `domain-core`·`application-core`·`shared-contract`, support,
identifier뿐이라 DB·Redis·Kafka 없이 기동합니다.
```bash
cd src
./gradlew :app-bootstrap:bootRun
```
| 프로파일 | 데이터스토어 | 스키마 소유자 |
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 `app-bootstrap/build.gradle`에 주석 처리된
`runtimeOnly` 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다.
줄마다 필요한 env와 끄는 키는 [src/README.md](src/README.md)의 "기능 추가 = 한 줄 + env" 표에 있습니다.
| 프로파일 | 데이터스토어 (persistence-jpa 줄을 넣었을 때) | 스키마 소유자 |
| --- | --- | --- |
| `local` (bootRun 기본) | H2 in-memory | Hibernate `create-drop` |
| `local` | Compose PostgreSQL (`./gradlew :app-bootstrap:bootRunH2`는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) | Flyway (H2는 Hibernate `create-drop`) |
| `dev` | PostgreSQL | Flyway |
| `prod` | PostgreSQL | Flyway |
`local`은 wiring과 애플리케이션 동작을 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 [src/app-bootstrap/src/main/resources/](src/app-bootstrap/src/main/resources/)의 `application-{local,dev,prod}.yml`이, 상세 설명은 [src/README.md](src/README.md)가 소유합니다.
H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 [src/app-bootstrap/src/main/resources/](src/app-bootstrap/src/main/resources/)의 `application-{local,dev,prod}.yml`이, 상세 설명은 [src/README.md](src/README.md)가 소유합니다.
## 새 프로젝트로 시작하기
+6 -1
View File
@@ -33,7 +33,12 @@ services:
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
GIT_SHA: "${GIT_SHA:-0000000}"
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
# qualification: every capability module present, each lane switching on what it tests.
COMPOSITION: "${COMPOSITION:-default}"
# The composition is in the tag, so a lane's qualification image is never reused as the
# default one (Compose reuses a matching tag instead of building).
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
# Generated per run by scripts/run-compose-runtime-smoke.sh and removed on teardown. Seven values
# have no inline default on purpose — the datasource address and credential, the application
# name, and the JWT issuer and audience — so a lane has to supply them, and a lane that borrowed
@@ -1,6 +1,9 @@
# ADR-JPA-002 — Retry re-runs the whole use case
- Status: Accepted
- Status: Superseded (2026-09-25) — the retry engine this ADR describes
(`FullTransactionRetryCoordinator`, `JpaTransactionExecutor`) was removed. `SpringTransactionPort`
retries nothing; a caller that retries still re-runs the whole use case, which is the part of this
decision that stands. The last commit is in `docs/capability-status.md`.
- Date: 2026-08-11
- Design: §19.2
+7 -4
View File
@@ -1,6 +1,8 @@
# ADR-JPA-003 — Completion unknown is never retried
- Status: Accepted
- Status: Accepted; amended 2026-09-25 — `TransactionCompletionResolver`, `CommitFailureClassifier`
and the retry engine were removed. The invariant holds because `SpringTransactionPort`, the only
transaction engine, retries nothing; enforcement below is updated accordingly.
- Date: 2026-08-11
- Design: §17
@@ -14,7 +16,7 @@ acknowledgement may simply have been lost. The driver cannot tell the two apart.
`TransactionCompletionUnknownException` is never retried, automatically or otherwise. It is
produced only by a failure observed while the transaction phase is `COMMITTING`, and only for
SQLSTATE `40003`, a connection-class (`08*`) state, or a transport break. Recovery is
domain-specific reconciliation through `TransactionCompletionResolver`.
domain-specific reconciliation.
## Consequences
@@ -37,5 +39,6 @@ which idempotency record, business row, or outbox entry proves the write happene
## Enforcement
`JpaFailureContextTest`; `DefaultJpaRetryPolicyTest`; `CommitFailureClassifierTest`; release gate
`completion-unknown-no-retry`.
`JpaFailureContextTest`;
`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried`
(also the `jpa-failure` lane, i.e. release gate `completion-unknown-no-retry`).
@@ -33,5 +33,6 @@ intended cost: it makes schema change reviewable and reversible.
## Enforcement
`JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate`;
`PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and `runtime-role-no-ddl`.
`JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate` (testkit, used by the
migration contract tests); `PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and
`runtime-role-no-ddl`.
@@ -3,6 +3,13 @@
- **Status:** Accepted
- **Date:** 2026-08-13
- **Design source:** design §2 (D-15), §3.2–§3.3; Advanced expansion plan Task 15
- **Amended 2026-09-25:** the `ca-skeleton.persistence-mongo.advanced.*.enabled` binding
(`MongoAdvancedConfiguration`/`MongoAdvancedSettings`) was imported by nothing, so no deployment
property ever reached the flags; it was removed together with `propertyFor`. The flags are now
built in code by the adapter that constructs an entry point. `MongoAdvancedPromotionGate`,
`MongoAdvancedPromotionEvidence`, `MongoVectorSearchBenchmarkGate` and the search, vector, time
series and GridFS packages (interfaces with no implementation) were removed. The evidence
categories below remain a review obligation; no class checks them.
## Context
@@ -19,15 +19,16 @@ retention, its own eviction and its own opinion about ordering.
## Decision
**Three outcomes, expressed in the stream rather than in the status.** `WebStreamEnvelope` is sealed
over `Item`, `Failure` and `Complete`. A client that sees neither terminal envelope has been cut off,
and that third case is recorded as `ABRUPT_CLOSE` rather than counted as a completion — which is
where a rising rate of mid-stream failures would otherwise hide.
**Three outcomes, expressed in the stream rather than in the status.** The wire record (for NDJSON,
`NdjsonRecord`) is an item, a failure or a completion. A client that sees neither terminal record
has been cut off, and that third case is recorded as `ABRUPT_CLOSE` rather than counted as a
completion — which is where a rising rate of mid-stream failures would otherwise hide.
**Nothing writes a problem document onto a committed response.** `WebStreamTerminationMapper`
branches on whether any byte has been written. Before commit, an RFC 9457 problem with a real
status; after, a terminal record. Attempting both produces a body that is half stream and half JSON,
which no client parses and every proxy caches as a success.
**Nothing writes an error body onto a committed response.** Before commit, a failure is an ordinary
HTTP error (the `Envelope`) with a real status; after, a terminal record. Attempting both produces a
body that is half stream and half JSON, which no client parses and every proxy caches as a success.
(The mapper that encoded this, `WebStreamTerminationMapper`, was removed on 2026-09-25 with the
problem-document vocabulary it returned; the rule stands.)
**Positions are monotonic, and it is enforced.** `WebStreamEvidence.recordDelivered` refuses a
repeated or regressing position. A client deduplicating on position would silently drop the second
@@ -6,8 +6,9 @@
## Context
Advanced Task 2 offers a virtual-thread executor for MVC; Task 3 offers a bounded blocking bridge
for WebFlux.
Advanced Task 2 offers a virtual-thread executor for MVC; Task 3 offered a bounded blocking bridge
for WebFlux. (The WebFlux adapter for it was removed on 2026-09-25 — the template is servlet only;
`advanced.blockingbridge` remains as library code.)
A platform-thread MVC deployment has an implicit concurrency limit — the thread pool — and that
limit is usually what has been protecting the database pool, the outbound HTTP bulkhead and every
@@ -40,6 +41,9 @@ offload; `BlockingBridgeBudget` bounds the concurrency and refuses a caller that
in time, because otherwise a slow dependency's callers accumulate until the heap does and the fast
dependencies starve behind them.
> 2026-09-25: `advanced.blockingbridge` was removed. Its WebFlux adapter went with the WebFlux twin
> (D4), and a budget for a bridge that no longer exists bounded nothing.
**Pinning is observed, not assumed away.** `VirtualThreadProfile.requiredObservations()` lists what
has to be watched — `jdk.VirtualThreadPinned` above all. A synchronized block held across a blocking
call pins the carrier thread, the carrier pool is bounded by CPU count, and enough pinned carriers is
@@ -23,6 +23,10 @@ contributor that mutates it on the way to 3.2 changes the artifact that is actua
silently, and only when the experimental lane runs. `OpenApi32CompatibilityReport` compares the
snapshot hash before and after and makes a difference a promotion blocker.
> 2026-09-25: `OpenApi32CompatibilityReport` and `OpenApiToolchainMatrix` were removed — promotion
> checks kept in production code, called only by their own tests. `WebOpenApi32Generator` remains
> as library code in `adapter:inbound:web-advanced`; the decision below is unchanged.
**Four kinds of tool are checked separately.** A parser reports structural errors; a linter applies
style rules and accepts documents a parser rejects; a generator produces client code, and this is
where an unsupported construct surfaces — not as an error but as a method with the wrong signature;
@@ -1,6 +1,9 @@
# ADR-WS-001: The WebSocket platform ships as packages in one leaf, with machine-checked boundaries
- Status: accepted
- Status: Superseded 2026-09-25 — the eighteen-package platform was cut to the parts a Spring
configuration or a real-container lane reaches: the `stomp` channel and the servlet handler
library (`servlet`, `outbound`, `budget`). The Advanced packages, the reactive runtime and the
`WebSocketArchitectureRules` pack went with the rest (see `docs/capability-status.md`).
- Date: 2026-08-25
- Scope: `:adapter:inbound:websocket`
+2 -1
View File
@@ -1,6 +1,7 @@
# ADR-WS-002: Resume and cluster state are caches, and are treated as caches
- Status: Accepted
- Status: Superseded 2026-09-25 — `advanced.resume`, `advanced.cluster` and `advanced.presence`
were removed: nothing assembled them (see `docs/capability-status.md`).
- Date: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence`
@@ -1,6 +1,7 @@
# ADR-WS-003: STOMP is an Advanced adapter with a declared destination catalog
- Status: Accepted
- Status: Superseded 2026-09-25 — `advanced.stomp` and `advanced.stomp.rabbit` were removed; the
`stomp` package is the only STOMP channel (see `docs/capability-status.md`).
- Date: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit`
+1 -234
View File
@@ -5,180 +5,22 @@
# split into capability artifacts.
# Update only after review with:
# ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange
# types: 401
# types: 168
dev.caskeleton.adapter.inbound.graphql.HealthGraphqlController
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlAdminPrincipal
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationAdminAuthorization
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationAdminDeniedException
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationAdminPort
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationAdminService
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationAudit
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationBlockCommand
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationRemovalGate
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationRemovalRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationUsage
dev.caskeleton.adapter.inbound.graphql.advanced.bootstrap.GraphQlAdvancedCapability
dev.caskeleton.adapter.inbound.graphql.advanced.bootstrap.GraphQlAdvancedCapabilityDisabledException
dev.caskeleton.adapter.inbound.graphql.advanced.bootstrap.GraphQlAdvancedCapabilityGrade
dev.caskeleton.adapter.inbound.graphql.advanced.bootstrap.GraphQlAdvancedDependencyRules
dev.caskeleton.adapter.inbound.graphql.advanced.bootstrap.GraphQlAdvancedFeatureFlags
dev.caskeleton.adapter.inbound.graphql.advanced.bootstrap.GraphQlAdvancedModuleGuard
dev.caskeleton.adapter.inbound.graphql.advanced.chaining.GraphQlChainedDataLoaderPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.chaining.GraphQlChainedDispatchConfigurer
dev.caskeleton.adapter.inbound.graphql.advanced.chaining.GraphQlChainedLoaderMetrics
dev.caskeleton.adapter.inbound.graphql.advanced.chaining.GraphQlDataLoaderCycleDetector
dev.caskeleton.adapter.inbound.graphql.advanced.chaining.GraphQlDataLoaderDependencyCycleException
dev.caskeleton.adapter.inbound.graphql.advanced.chaining.GraphQlDataLoaderDependencyGraph
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlClientOperationGenerator
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlCodegenBoundaryException
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlCodegenProfile
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlGeneratedCompatibilityGate
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlGeneratedSourceBoundary
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlOperationValidator
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlScalarMapping
dev.caskeleton.adapter.inbound.graphql.advanced.codegen.GraphQlTransportTypeGenerator
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlFederationCompositionGate
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlFederationCompositionResult
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlFederationDeploymentOrder
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlFederationLatencyBudget
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlFederationReleaseEvidence
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlFederationReleaseRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlFederationUsageReport
dev.caskeleton.adapter.inbound.graphql.advanced.composition.GraphQlSubgraphContract
dev.caskeleton.adapter.inbound.graphql.advanced.federation.GraphQlFederationBatchResolver
dev.caskeleton.adapter.inbound.graphql.advanced.federation.GraphQlFederationCapability
dev.caskeleton.adapter.inbound.graphql.advanced.federation.GraphQlFederationEntityKey
dev.caskeleton.adapter.inbound.graphql.advanced.federation.GraphQlFederationEntityResolver
dev.caskeleton.adapter.inbound.graphql.advanced.federation.GraphQlFederationProperties
dev.caskeleton.adapter.inbound.graphql.advanced.federation.GraphQlFederationRepresentationException
dev.caskeleton.adapter.inbound.graphql.advanced.federation.GraphQlFederationSchemaFactory
dev.caskeleton.adapter.inbound.graphql.advanced.get.GraphQlHttpDraftCompatibilityReport
dev.caskeleton.adapter.inbound.graphql.advanced.get.GraphQlHttpGetCachePolicy
dev.caskeleton.adapter.inbound.graphql.advanced.get.GraphQlHttpGetCsrfPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.get.GraphQlHttpGetOperationPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.get.GraphQlHttpGetProfile
dev.caskeleton.adapter.inbound.graphql.advanced.get.GraphQlHttpGetRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.get.GraphQlHttpGetRequestParser
dev.caskeleton.adapter.inbound.graphql.advanced.incremental.GraphQlIncrementalCancellation
dev.caskeleton.adapter.inbound.graphql.advanced.incremental.GraphQlIncrementalCompatibilityGate
dev.caskeleton.adapter.inbound.graphql.advanced.incremental.GraphQlIncrementalDeliveryCapability
dev.caskeleton.adapter.inbound.graphql.advanced.incremental.GraphQlIncrementalDeliveryProfile
dev.caskeleton.adapter.inbound.graphql.advanced.incremental.GraphQlIncrementalDeliveryRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.incremental.GraphQlIncrementalPatch
dev.caskeleton.adapter.inbound.graphql.advanced.incremental.GraphQlIncrementalTransportPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperation
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationConflictException
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationId
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationInterceptor
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationLookup
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationNotFoundException
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationRecordMapping
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationRegistry
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationRequest
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationStatus
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedOperationTransition
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.GraphQlPersistedPreparsedBridge
dev.caskeleton.adapter.inbound.graphql.advanced.persisted.OperationalStoreGraphQlPersistedOperationRegistry
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedCompatibilityMatrix
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedPromotionDecision
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedReleaseEvidence
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedReleaseException
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedReleaseGate
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedRunbookIndex
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedSoakScenario
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlReplayAuthorization
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlReplayAuthorizationException
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlReplayGapException
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlReplayHistoryLostException
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlReplayPosition
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlReplaySource
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlSnapshotLiveHandoff
dev.caskeleton.adapter.inbound.graphql.advanced.replay.GraphQlSubscriptionCursor
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketAdmission
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketAuthentication
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketCapability
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketErrorMapper
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketHandlerFactory
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketProperties
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketRoutePolicy
dev.caskeleton.adapter.inbound.graphql.advanced.rsocket.GraphQlRSocketRouteRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.security.GraphQlSubscriptionAuthorizationPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.security.GraphQlWebSocketAuthenticationException
dev.caskeleton.adapter.inbound.graphql.advanced.security.GraphQlWebSocketAuthenticationInterceptor
dev.caskeleton.adapter.inbound.graphql.advanced.security.GraphQlWebSocketCloseReason
dev.caskeleton.adapter.inbound.graphql.advanced.security.GraphQlWebSocketCredentialExpiry
dev.caskeleton.adapter.inbound.graphql.advanced.security.GraphQlWebSocketPrincipal
dev.caskeleton.adapter.inbound.graphql.advanced.security.GraphQlWebSocketRevocationSignal
dev.caskeleton.adapter.inbound.graphql.advanced.springdata.GraphQlRepositoryAllowlist
dev.caskeleton.adapter.inbound.graphql.advanced.springdata.GraphQlRepositoryArgumentPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.springdata.GraphQlRepositoryExposure
dev.caskeleton.adapter.inbound.graphql.advanced.springdata.GraphQlRepositoryExposureRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.springdata.GraphQlRepositoryExposureValidator
dev.caskeleton.adapter.inbound.graphql.advanced.springdata.GraphQlRepositoryPaginationPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.springdata.GraphQlRepositoryProjectionPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.sse.GraphQlSseAdmission
dev.caskeleton.adapter.inbound.graphql.advanced.sse.GraphQlSseConnectionPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.sse.GraphQlSseHandlerFactory
dev.caskeleton.adapter.inbound.graphql.advanced.sse.GraphQlSseHeartbeat
dev.caskeleton.adapter.inbound.graphql.advanced.sse.GraphQlSseProperties
dev.caskeleton.adapter.inbound.graphql.advanced.sse.GraphQlSseRejectedException
dev.caskeleton.adapter.inbound.graphql.advanced.sse.GraphQlSseTermination
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSlowConsumerPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionBufferPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionCancellation
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionContext
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionDispatcher
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionDrainCoordinator
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionDrainPhase
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionDrainingException
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionEvent
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionExecutionPolicy
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionLease
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionMetrics
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionOrderingProfile
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionSource
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionState
dev.caskeleton.adapter.inbound.graphql.advanced.subscription.GraphQlSubscriptionTermination
dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfile
dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfileName
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationId
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationName
dev.caskeleton.adapter.inbound.graphql.api.GraphQlSchemaCoordinate
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlAsyncReturnShape
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlControllerContractException
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlControllerInspector
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlControllerTransactionRule
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlInputTypePolicy
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlResolverBoundaryRules
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlReturnTypePolicy
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlTransportTypeRules
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlTypeGraph
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlActivationEnvironmentPostProcessor
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlDeploymentMode
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlOffAutoConfigurationImportFilter
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformActuatorEndpoint
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformAutoConfiguration
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformConfigurationException
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformConfigurationReport
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformRuntime
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformSettings
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformStartupValidator
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRetiredSafetyAxis
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRootAutoConfiguration
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRuntimeTransport
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlChangeKind
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlClientOwnerApproval
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlCompatibilityImpact
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlCompatibilityPolicy
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlCompatibilityReport
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlDeprecationGate
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlRemovalDecision
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlRemovalRequest
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlSchemaChange
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlSchemaComparator
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlSchemaUsage
dev.caskeleton.adapter.inbound.graphql.context.ActorRef
dev.caskeleton.adapter.inbound.graphql.context.GraphQlCommandAttribution
dev.caskeleton.adapter.inbound.graphql.context.GraphQlDeadline
@@ -193,16 +35,7 @@ dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentComplexityScorer
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentShape
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentShapeAnalyzer
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlFieldCostDescriptor
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlParserLimitPolicy
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlParserLimits
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlParserOptionsFactory
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlParserRejectedException
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlResolverWeight
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlResponseByteLimiter
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlResponseNodeCounter
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlRuntimeBudget
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlRuntimeBudgetExceededException
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlRuntimeBudgetTracker
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitException
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitPolicy
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimits
@@ -227,33 +60,21 @@ dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorCategory
dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorCode
dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext
dev.caskeleton.adapter.inbound.graphql.error.GraphQlExceptionResolver
dev.caskeleton.adapter.inbound.graphql.error.GraphQlFailureBoundary
dev.caskeleton.adapter.inbound.graphql.error.GraphQlInternalErrorMasker
dev.caskeleton.adapter.inbound.graphql.error.GraphQlNullabilityContract
dev.caskeleton.adapter.inbound.graphql.error.GraphQlRequestErrorMapper
dev.caskeleton.adapter.inbound.graphql.error.GraphQlSubscriptionExceptionResolver
dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireError
dev.caskeleton.adapter.inbound.graphql.execution.BoundedPreparsedDocumentProvider
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlAnonymousOperationException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlCancellation
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlDeadlinePropagator
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipeline
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineValidator
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfileException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfileValidator
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionStage
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlOperationNameInterceptor
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlOperationNamePolicy
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlOperationSelection
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheKey
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheMetrics
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCachePolicy
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlRequestCancelledException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlResolverBudget
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlResolverCatalog
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlResolverDescriptor
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlTimeoutPolicy
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfile
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileClassifier
@@ -265,41 +86,22 @@ dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionCoordinate
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionSetView
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionSignature
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlUnmappedSelectionException
dev.caskeleton.adapter.inbound.graphql.http.GraphQlAcceptHeader
dev.caskeleton.adapter.inbound.graphql.http.GraphQlExecutionOutcome
dev.caskeleton.adapter.inbound.graphql.http.GraphQlExtensionsPolicy
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpContractException
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpExecutor
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpOutcome
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpProfile
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpRequestEnvelope
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpResponse
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpResponseFactory
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpResponsePolicy
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpStatusMapper
dev.caskeleton.adapter.inbound.graphql.http.GraphQlJsonStructurePolicy
dev.caskeleton.adapter.inbound.graphql.http.GraphQlJsonValues
dev.caskeleton.adapter.inbound.graphql.http.GraphQlMediaTypes
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestEnvelopeValidator
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestFormatException
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestSize
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestTooLargeException
dev.caskeleton.adapter.inbound.graphql.moduleboundary.GraphQlAdvancedModule
dev.caskeleton.adapter.inbound.graphql.moduleboundary.GraphQlModuleBoundary
dev.caskeleton.adapter.inbound.graphql.moduleboundary.GraphQlModulePurity
dev.caskeleton.adapter.inbound.graphql.moduleboundary.GraphQlStableModule
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlBatchMutationItemResult
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlBusinessResult
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlCanonicalInput
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlExpectedVersion
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlIdempotencyConflictException
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlIdempotencyKey
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationContractException
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationContractValidator
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationCoordinate
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationFingerprint
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationIdempotencyContext
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationIdempotencyInterceptor
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationPayload
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationResultMapper
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlDataLoaderObservationConvention
@@ -307,7 +109,6 @@ dev.caskeleton.adapter.inbound.graphql.observation.GraphQlMetricCardinalityPolic
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlObservationContractException
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlObservationNames
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlOperationNameCardinality
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlProfilerAccessPolicy
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlRequestObservationConvention
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlResolverObservationConvention
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlSensitiveAttributeFilter
@@ -329,23 +130,7 @@ dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlKeysetWindow
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlPageInfo
dev.caskeleton.adapter.inbound.graphql.pagination.HmacGraphQlCursorCodec
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlClientPolicy
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlClientPolicyManifest
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlOperationCatalog
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlOperationPolicy
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlOperationType
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlPolicyViolation
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlUnknownClientProfileException
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlUnknownOperationException
dev.caskeleton.adapter.inbound.graphql.policy.ResolverExecutionType
dev.caskeleton.adapter.inbound.graphql.release.GraphQlCompatibilityMatrix
dev.caskeleton.adapter.inbound.graphql.release.GraphQlFaultScenario
dev.caskeleton.adapter.inbound.graphql.release.GraphQlPerformanceScenario
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseEvidence
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseException
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseGate
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseOverride
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseReportWriter
dev.caskeleton.adapter.inbound.graphql.release.GraphQlStableCapabilityManifest
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridge
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridgeFullException
@@ -373,25 +158,9 @@ dev.caskeleton.adapter.inbound.graphql.scalar.GraphQlScalarWiringConfigurer
dev.caskeleton.adapter.inbound.graphql.scalar.InstantScalar
dev.caskeleton.adapter.inbound.graphql.scalar.LongScalar
dev.caskeleton.adapter.inbound.graphql.scalar.UuidScalar
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlContractVersion
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlMappingInspectionGate
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlMappingIssue
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlMappingPolicy
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlOneOfInputValidator
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlOneOfPolicy
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlOneOfSchemaGate
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlOneOfViolationException
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarDefinition
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarManifest
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarPolicy
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaAssembler
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaAssemblyException
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaAssemblyResult
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaContract
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaHash
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaMappingException
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaOwnership
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlSchemaResource
dev.caskeleton.adapter.inbound.graphql.security.ApplicationObjectAuthorization
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticatedPrincipal
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticationContextFactory
@@ -401,8 +170,6 @@ dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationDeniedExcept
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationInterceptor
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationPolicy
dev.caskeleton.adapter.inbound.graphql.security.GraphQlBatchContext
dev.caskeleton.adapter.inbound.graphql.security.GraphQlClientProfileResolver
dev.caskeleton.adapter.inbound.graphql.security.GraphQlContextCleanup
dev.caskeleton.adapter.inbound.graphql.security.GraphQlContextPropagator
dev.caskeleton.adapter.inbound.graphql.security.GraphQlObjectAuthorizationPort
dev.caskeleton.adapter.inbound.graphql.security.GraphQlTenantIsolationException
@@ -10,14 +10,10 @@ dev.caskeleton.adapter.outbound.persistence.config.PersistenceVendorSettings
dev.caskeleton.adapter.outbound.persistence.failure.SqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.fileserver.FileserverSchemaActivation
dev.caskeleton.adapter.outbound.persistence.hibernate.HibernateProviderPolicy
dev.caskeleton.adapter.outbound.persistence.idempotency.IdempotencyClaimRepository
dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy
dev.caskeleton.adapter.outbound.persistence.outbox.OutboxClaimRepository
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlIdempotencyClaimRepository
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlLocalTimeoutConfigurer
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlOutboxClaimRepository
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlSqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.security.DatabasePrivilegeReport
dev.caskeleton.adapter.outbound.persistence.security.PostgreSqlRuntimeRoleVerifier
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionLocalTimeoutConfigurer
+2 -99
View File
@@ -5,7 +5,7 @@
# root yet.
# Update only after review with:
# ./gradlew :adapter:outbound:persistence-jpa:updateJpaApiSurface -PapproveJpaApiSurfaceChange
# types: 311
# types: 214
dev.caskeleton.adapter.outbound.persistence.api.PersistenceOperationName
dev.caskeleton.adapter.outbound.persistence.api.capability.CapabilitySupport
dev.caskeleton.adapter.outbound.persistence.api.capability.JpaCapability
@@ -28,12 +28,9 @@ dev.caskeleton.adapter.outbound.persistence.api.error.QueryTimeoutException
dev.caskeleton.adapter.outbound.persistence.api.error.SchemaMismatchException
dev.caskeleton.adapter.outbound.persistence.api.error.SerializationFailureException
dev.caskeleton.adapter.outbound.persistence.api.error.SqlExceptionSqlStateResolver
dev.caskeleton.adapter.outbound.persistence.api.error.SqlStateResolver
dev.caskeleton.adapter.outbound.persistence.api.error.TransactionCompletionUnknownException
dev.caskeleton.adapter.outbound.persistence.api.error.TransactionTimeoutException
dev.caskeleton.adapter.outbound.persistence.api.error.UniqueConstraintViolationException
dev.caskeleton.adapter.outbound.persistence.api.error.VendorFailureTranslator
dev.caskeleton.adapter.outbound.persistence.api.query.CursorCodec
dev.caskeleton.adapter.outbound.persistence.api.query.CursorPayloadCodec
dev.caskeleton.adapter.outbound.persistence.api.query.KeysetPageRequest
dev.caskeleton.adapter.outbound.persistence.api.query.KeysetSlice
@@ -43,18 +40,7 @@ dev.caskeleton.adapter.outbound.persistence.api.query.QueryObservation
dev.caskeleton.adapter.outbound.persistence.api.query.QueryScope
dev.caskeleton.adapter.outbound.persistence.api.query.SignedJsonCursorCodec
dev.caskeleton.adapter.outbound.persistence.api.query.SortDirection
dev.caskeleton.adapter.outbound.persistence.api.transaction.IsolationLevel
dev.caskeleton.adapter.outbound.persistence.api.transaction.JitterMode
dev.caskeleton.adapter.outbound.persistence.api.transaction.JpaRetryPolicy
dev.caskeleton.adapter.outbound.persistence.api.transaction.JpaTransactionExecutor
dev.caskeleton.adapter.outbound.persistence.api.transaction.PropagationMode
dev.caskeleton.adapter.outbound.persistence.api.transaction.RetryDecision
dev.caskeleton.adapter.outbound.persistence.api.transaction.RetryDisposition
dev.caskeleton.adapter.outbound.persistence.api.transaction.RetryEventListener
dev.caskeleton.adapter.outbound.persistence.api.transaction.RetryProfile
dev.caskeleton.adapter.outbound.persistence.api.transaction.TransactionAttempt
dev.caskeleton.adapter.outbound.persistence.api.transaction.TransactionCompletionEvidence
dev.caskeleton.adapter.outbound.persistence.api.transaction.TransactionProfile
dev.caskeleton.adapter.outbound.persistence.audit.AuditContextPort
dev.caskeleton.adapter.outbound.persistence.audit.AuditableEntity
dev.caskeleton.adapter.outbound.persistence.audit.DomainContextAuditContextPort
@@ -69,20 +55,11 @@ dev.caskeleton.adapter.outbound.persistence.config.PersistenceVendorSettings
dev.caskeleton.adapter.outbound.persistence.envers.EntityRevision
dev.caskeleton.adapter.outbound.persistence.envers.EnversConfigurationGuard
dev.caskeleton.adapter.outbound.persistence.envers.EnversHistoryPolicy
dev.caskeleton.adapter.outbound.persistence.envers.EnversHistoryReader
dev.caskeleton.adapter.outbound.persistence.envers.EnversRevisionMetadata
dev.caskeleton.adapter.outbound.persistence.envers.HibernateEnversHistoryReader
dev.caskeleton.adapter.outbound.persistence.experimental.ExperimentalFeature
dev.caskeleton.adapter.outbound.persistence.experimental.ExperimentalFeatureGate
dev.caskeleton.adapter.outbound.persistence.experimental.database.TenantDataSourceLifecycle
dev.caskeleton.adapter.outbound.persistence.experimental.database.TenantDataSourceRegistry
dev.caskeleton.adapter.outbound.persistence.experimental.database.TenantEntityManagerFactoryRegistry
dev.caskeleton.adapter.outbound.persistence.experimental.database.TenantPoolBudget
dev.caskeleton.adapter.outbound.persistence.experimental.next.CompatibilityLane
dev.caskeleton.adapter.outbound.persistence.experimental.next.ExperimentalPromotionGate
dev.caskeleton.adapter.outbound.persistence.experimental.next.HibernateCompatibilityPolicy
dev.caskeleton.adapter.outbound.persistence.experimental.next.PromotionDecision
dev.caskeleton.adapter.outbound.persistence.experimental.next.PromotionEvidence
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ConsistencyAwareDataSourceRouter
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ConsistencyToken
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ReadConsistency
@@ -90,7 +67,6 @@ dev.caskeleton.adapter.outbound.persistence.experimental.replica.ReplicaLagMonit
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ReplicaRoutingDecision
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ReplicaTarget
dev.caskeleton.adapter.outbound.persistence.experimental.replica.TransactionContext
dev.caskeleton.adapter.outbound.persistence.experimental.rls.RlsAdminBypassToken
dev.caskeleton.adapter.outbound.persistence.experimental.rls.RlsPolicyVerifier
dev.caskeleton.adapter.outbound.persistence.experimental.rls.RlsTenantSessionBinder
dev.caskeleton.adapter.outbound.persistence.experimental.schema.SchemaMultiTenantConnectionProvider
@@ -99,13 +75,10 @@ dev.caskeleton.adapter.outbound.persistence.experimental.schema.SchemaTenantRegi
dev.caskeleton.adapter.outbound.persistence.experimental.schema.TenantMigrationStatus
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantAwareRepositoryGuard
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantContext
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantEntityListenerGuard
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantId
dev.caskeleton.adapter.outbound.persistence.failure.PersistenceExceptionTranslator
dev.caskeleton.adapter.outbound.persistence.failure.SqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.failure.StandardSqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.h2.H2IdempotencyClaimRepository
dev.caskeleton.adapter.outbound.persistence.h2.H2LocalTimeoutConfigurer
dev.caskeleton.adapter.outbound.persistence.h2.H2OutboxClaimRepository
dev.caskeleton.adapter.outbound.persistence.h2.H2PersistenceConfig
dev.caskeleton.adapter.outbound.persistence.h2.H2SqlStateErrorMapping
@@ -118,50 +91,30 @@ dev.caskeleton.adapter.outbound.persistence.hibernate.QueryNameContext
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.BatchExecutionResult
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.HibernateBatchConfigurationGuard
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.HibernateJpaBatchExecutor
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.JpaBatchExecutor
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.JpaBatchProfile
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.JpaBatchProfileRegistry
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.AffectedRowsExpectation
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.BulkDmlExecutor
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.BulkDmlResult
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.BulkOperationName
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.HibernateBulkDmlExecutor
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.HibernateStatelessSessionRunner
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.StatelessRowCapExceededException
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.StatelessSessionRunner
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.StatelessWorkName
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.StatelessWorkResult
dev.caskeleton.adapter.outbound.persistence.idempotency.IdempotencyClaimRepository
dev.caskeleton.adapter.outbound.persistence.idempotency.IdempotencyReaper
dev.caskeleton.adapter.outbound.persistence.idempotency.IdempotencyRecordJpaRepository
dev.caskeleton.adapter.outbound.persistence.idempotency.IdempotencyResponseObjectStore
dev.caskeleton.adapter.outbound.persistence.idempotency.IdempotencyStoreAdapter
dev.caskeleton.adapter.outbound.persistence.idempotency.entity.IdempotencyRecordEntity
dev.caskeleton.adapter.outbound.persistence.idempotency.mapper.IdempotencyRecordEntityMapper
dev.caskeleton.adapter.outbound.persistence.liveevent.JpaLiveEventReplayAdapter
dev.caskeleton.adapter.outbound.persistence.liveevent.LiveEventJpaRepository
dev.caskeleton.adapter.outbound.persistence.liveevent.entity.LiveEventEntity
dev.caskeleton.adapter.outbound.persistence.lock.DistributedLockPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.lock.LockRegistryDistributedLockAdapter
dev.caskeleton.adapter.outbound.persistence.lock.LockSettings
dev.caskeleton.adapter.outbound.persistence.migration.ConcurrentIndexMigrationInspector
dev.caskeleton.adapter.outbound.persistence.migration.FailedConcurrentIndexRecovery
dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy
dev.caskeleton.adapter.outbound.persistence.migration.FlywayValidationGate
dev.caskeleton.adapter.outbound.persistence.migration.MigrationResource
dev.caskeleton.adapter.outbound.persistence.migration.NonTransactionalMigrationPolicy
dev.caskeleton.adapter.outbound.persistence.migration.SchemaManagementMode
dev.caskeleton.adapter.outbound.persistence.migration.SchemaVersionSnapshot
dev.caskeleton.adapter.outbound.persistence.notification.NotificationJpaPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.notification.NotificationSchemaActivation
dev.caskeleton.adapter.outbound.persistence.notification.NotificationSchemaStream
dev.caskeleton.adapter.outbound.persistence.notification.configuration.NotificationJpaPersistenceFacade
dev.caskeleton.adapter.outbound.persistence.notification.crypto.DirectAeadNotificationPayloadCrypto
dev.caskeleton.adapter.outbound.persistence.notification.crypto.NotificationCiphertext
dev.caskeleton.adapter.outbound.persistence.notification.crypto.NotificationCryptoException
dev.caskeleton.adapter.outbound.persistence.notification.crypto.NotificationHmacDigester
dev.caskeleton.adapter.outbound.persistence.notification.crypto.NotificationKeyMaterialHandle
dev.caskeleton.adapter.outbound.persistence.notification.crypto.NotificationKeyMaterialProvider
dev.caskeleton.adapter.outbound.persistence.notification.platform.AdminAuditEntity
dev.caskeleton.adapter.outbound.persistence.notification.platform.AdminAuditJpaRepository
dev.caskeleton.adapter.outbound.persistence.notification.platform.ConsentEntity
@@ -206,8 +159,6 @@ dev.caskeleton.adapter.outbound.persistence.notification.platform.inbox.InboxIte
dev.caskeleton.adapter.outbound.persistence.notification.platform.inbox.InboxOutboxRecordFactory
dev.caskeleton.adapter.outbound.persistence.notification.platform.inbox.JpaNotificationInbox
dev.caskeleton.adapter.outbound.persistence.observation.JpaMetricTags
dev.caskeleton.adapter.outbound.persistence.observation.JpaRetryObservation
dev.caskeleton.adapter.outbound.persistence.observation.JpaTransactionObservation
dev.caskeleton.adapter.outbound.persistence.observation.LowCardinality
dev.caskeleton.adapter.outbound.persistence.observation.MicrometerQueryObservation
dev.caskeleton.adapter.outbound.persistence.observation.SqlDiagnosticRedactor
@@ -219,8 +170,6 @@ dev.caskeleton.adapter.outbound.persistence.outbox.OutboxEventJpaRepository
dev.caskeleton.adapter.outbound.persistence.outbox.OutboxReaper
dev.caskeleton.adapter.outbound.persistence.outbox.OutboxStoreAdapter
dev.caskeleton.adapter.outbound.persistence.outbox.entity.OutboxEventEntity
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlIdempotencyClaimRepository
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlLocalTimeoutConfigurer
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlOutboxClaimRepository
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlSqlStateErrorMapping
@@ -233,50 +182,29 @@ dev.caskeleton.adapter.outbound.persistence.postgresql.copy.CopyFormat
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.CopyLimits
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.CopyOperationName
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.CopyResult
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.PostgreSqlCopyLoader
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.RegisteredCopyStatement
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.RegisteredPostgreSqlCopyLoader
dev.caskeleton.adapter.outbound.persistence.postgresql.error.ConstraintCatalog
dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlExceptionTranslator
dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlFailureClassifier
dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlServerErrorFields
dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlState
dev.caskeleton.adapter.outbound.persistence.postgresql.idempotency.IdempotencySchemaStream
dev.caskeleton.adapter.outbound.persistence.postgresql.idempotency.PostgreSqlOwnerSafeIdempotencyStore
dev.caskeleton.adapter.outbound.persistence.postgresql.inbox.PostgreSqlSameStoreInboxAdapter
dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonDocument
dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonDocumentCodec
dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonPathName
dev.caskeleton.adapter.outbound.persistence.postgresql.json.PostgreSqlJsonQuerySupport
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.LockWaitObservation
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.PostgreSqlLockExceptionTranslator
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.PostgreSqlLockOptions
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.PostgreSqlWorkClaimExecutor
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.WorkClaim
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.WorkClaimExecutor
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.WorkQueueDefinition
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.WorkQueueName
dev.caskeleton.adapter.outbound.persistence.postgresql.outbox.PostgreSqlImmutableOutboxAppendAdapter
dev.caskeleton.adapter.outbound.persistence.postgresql.outbox.PostgreSqlPollingDeliveryAdapter
dev.caskeleton.adapter.outbound.persistence.postgresql.range.PgRange
dev.caskeleton.adapter.outbound.persistence.postgresql.range.PgRangeCodec
dev.caskeleton.adapter.outbound.persistence.postgresql.range.PgRangeJdbcType
dev.caskeleton.adapter.outbound.persistence.postgresql.range.PostgreSqlRangeQuerySupport
dev.caskeleton.adapter.outbound.persistence.postgresql.write.NativeWriteName
dev.caskeleton.adapter.outbound.persistence.postgresql.write.PostgreSqlUpsertExecutor
dev.caskeleton.adapter.outbound.persistence.postgresql.write.RegisteredPostgreSqlUpsertExecutor
dev.caskeleton.adapter.outbound.persistence.postgresql.write.RegisteredUpsertStatement
dev.caskeleton.adapter.outbound.persistence.postgresql.write.UpsertConflictTarget
dev.caskeleton.adapter.outbound.persistence.postgresql.write.UpsertResult
dev.caskeleton.adapter.outbound.persistence.postgresql.write.WriteDisposition
dev.caskeleton.adapter.outbound.persistence.querydsl.PredicatePolicy
dev.caskeleton.adapter.outbound.persistence.querydsl.QueryPage
dev.caskeleton.adapter.outbound.persistence.querydsl.QuerydslJpaSupport
dev.caskeleton.adapter.outbound.persistence.security.DatabasePrivilegeReport
dev.caskeleton.adapter.outbound.persistence.security.DatabaseRolePolicy
dev.caskeleton.adapter.outbound.persistence.security.PostgreSqlRuntimeRoleVerifier
dev.caskeleton.adapter.outbound.persistence.security.SearchPathPolicy
dev.caskeleton.adapter.outbound.persistence.springdata.EntityGraphCatalog
dev.caskeleton.adapter.outbound.persistence.springdata.EntityManagerAccess
dev.caskeleton.adapter.outbound.persistence.springdata.FetchPlanApplier
dev.caskeleton.adapter.outbound.persistence.springdata.FetchPlanName
dev.caskeleton.adapter.outbound.persistence.springdata.JpaKeysetQuerySupport
@@ -291,29 +219,4 @@ dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortField
dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortMapper
dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortRegistry
dev.caskeleton.adapter.outbound.persistence.springdata.ScrollPolicy
dev.caskeleton.adapter.outbound.persistence.springdata.SpecificationPolicy
dev.caskeleton.adapter.outbound.persistence.transaction.BackoffCalculator
dev.caskeleton.adapter.outbound.persistence.transaction.CommitFailureClassifier
dev.caskeleton.adapter.outbound.persistence.transaction.CompletionUnknownRecord
dev.caskeleton.adapter.outbound.persistence.transaction.CompletionUnknownRecorder
dev.caskeleton.adapter.outbound.persistence.transaction.DefaultJpaRetryPolicy
dev.caskeleton.adapter.outbound.persistence.transaction.EffectiveTransactionTimeouts
dev.caskeleton.adapter.outbound.persistence.transaction.EvidenceAwareJpaTransactionManager
dev.caskeleton.adapter.outbound.persistence.transaction.FullTransactionRetryCoordinator
dev.caskeleton.adapter.outbound.persistence.transaction.JpaTransactionConfig
dev.caskeleton.adapter.outbound.persistence.transaction.JpaTransactionSettings
dev.caskeleton.adapter.outbound.persistence.transaction.OptimisticConflictTranslator
dev.caskeleton.adapter.outbound.persistence.transaction.PersistenceFailureTranslatorChain
dev.caskeleton.adapter.outbound.persistence.transaction.RetryBudget
dev.caskeleton.adapter.outbound.persistence.transaction.RetrySleeper
dev.caskeleton.adapter.outbound.persistence.transaction.SpringJpaTransactionExecutor
dev.caskeleton.adapter.outbound.persistence.transaction.SpringTransactionPort
dev.caskeleton.adapter.outbound.persistence.transaction.ThreadRetrySleeper
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionDefinitionMapper
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionEvidenceContext
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionEvidenceFrame
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionEvidenceScope
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionLocalTimeoutConfigurer
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionProfileRegistry
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionStartBudget
dev.caskeleton.adapter.outbound.persistence.transaction.UnknownOperation
+2 -77
View File
@@ -5,8 +5,8 @@
# root yet.
# Update only after review with:
# ./gradlew :adapter:outbound:persistence-mongo:updateMongoApiSurface -PapproveMongoApiSurfaceChange
# types: 346
dev.caskeleton.adapter.outbound.mongo.MongoOptInAutoConfigurationImportFilter
# types: 271
dev.caskeleton.adapter.outbound.mongo.MongoDefaultsEnvironmentPostProcessor
dev.caskeleton.adapter.outbound.mongo.MongoPersistenceConfig
dev.caskeleton.adapter.outbound.mongo.MongoPersistenceSettings
dev.caskeleton.adapter.outbound.mongo.MongoRootAutoConfiguration
@@ -14,22 +14,10 @@ dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedCapabilityFlags
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedCapabilityGuard
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedEntryPoint
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedPolicy
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedPromotionEvidence
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedPromotionGate
dev.caskeleton.adapter.outbound.mongo.advanced.autoconfigure.MongoAdvancedConfiguration
dev.caskeleton.adapter.outbound.mongo.advanced.autoconfigure.MongoAdvancedSettings
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoBridgeCheckpointPolicy
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoBridgeOutboxPolicy
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoChangeMessagingBridge
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoChangeToIntegrationEventMapper
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoIntegrationEventEnvelope
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoIntegrationEventPublisher
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoPublishResult
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.csfle.MongoCsfleClientFactory
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.csfle.MongoCsfleFieldPolicy
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.csfle.MongoCsfleMode
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.csfle.MongoCsfleProfile
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.csfle.MongoDataKeyResolver
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoEncryptedFieldDescriptor
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoEncryptionMetadataOwnership
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryShape
@@ -37,15 +25,6 @@ dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryShapeSupp
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryableEncryptionCollectionManager
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryableEncryptionProfile
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryableEncryptionQueryType
dev.caskeleton.adapter.outbound.mongo.advanced.gridfs.MongoGridFsCompatibilityReader
dev.caskeleton.adapter.outbound.mongo.advanced.gridfs.MongoGridFsMigrationCheckpoint
dev.caskeleton.adapter.outbound.mongo.advanced.gridfs.MongoGridFsMigrationJob
dev.caskeleton.adapter.outbound.mongo.advanced.gridfs.MongoGridFsObjectReference
dev.caskeleton.adapter.outbound.mongo.advanced.search.MongoSearchIndexDescriptor
dev.caskeleton.adapter.outbound.mongo.advanced.search.MongoSearchIndexState
dev.caskeleton.adapter.outbound.mongo.advanced.search.MongoSearchOperations
dev.caskeleton.adapter.outbound.mongo.advanced.search.MongoSearchQuery
dev.caskeleton.adapter.outbound.mongo.advanced.search.MongoSearchReadinessGate
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.MongoRoutingClassification
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.ShardAwareQueryValidator
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.ShardKeyDescriptor
@@ -56,25 +35,12 @@ dev.caskeleton.adapter.outbound.mongo.advanced.sharding.admin.ReshardApproval
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.admin.ShardKeyAnalyzer
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.admin.ShardKeyReadinessReport
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.database.MongoTenantClientRegistry
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.database.MongoTenantDatabaseResolver
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.database.MongoTenantLifecyclePolicy
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.database.MongoTenantMigrationCheckpointStore
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.database.MongoTenantMigrationCoordinator
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.shared.MongoTenantContext
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.shared.MongoTenantManifestValidator
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.shared.MongoTenantPredicateInjector
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.shared.TenantScopedMongoOperations
dev.caskeleton.adapter.outbound.mongo.advanced.timeseries.MongoTimeSeriesCapability
dev.caskeleton.adapter.outbound.mongo.advanced.timeseries.MongoTimeSeriesCapabilityValidator
dev.caskeleton.adapter.outbound.mongo.advanced.timeseries.MongoTimeSeriesDescriptor
dev.caskeleton.adapter.outbound.mongo.advanced.timeseries.MongoTimeSeriesGranularity
dev.caskeleton.adapter.outbound.mongo.advanced.timeseries.MongoTimeSeriesOperations
dev.caskeleton.adapter.outbound.mongo.advanced.timeseries.MongoTimeSeriesSupport
dev.caskeleton.adapter.outbound.mongo.advanced.vector.MongoEmbedding
dev.caskeleton.adapter.outbound.mongo.advanced.vector.MongoVectorIndexDescriptor
dev.caskeleton.adapter.outbound.mongo.advanced.vector.MongoVectorQuery
dev.caskeleton.adapter.outbound.mongo.advanced.vector.MongoVectorSearchBenchmarkGate
dev.caskeleton.adapter.outbound.mongo.advanced.vector.MongoVectorSearchOperations
dev.caskeleton.adapter.outbound.mongo.aggregation.MongoAggregationPlan
dev.caskeleton.adapter.outbound.mongo.aggregation.MongoAggregationProfile
dev.caskeleton.adapter.outbound.mongo.aggregation.MongoAggregationRisk
@@ -95,7 +61,6 @@ dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyDescriptor
dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyGuarantee
dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyProfile
dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyRegistry
dev.caskeleton.adapter.outbound.mongo.api.error.MongoBulkPartialFailureException
dev.caskeleton.adapter.outbound.mongo.api.error.MongoConnectionException
dev.caskeleton.adapter.outbound.mongo.api.error.MongoCursorException
dev.caskeleton.adapter.outbound.mongo.api.error.MongoDataSchemaUnsupportedException
@@ -124,7 +89,6 @@ dev.caskeleton.adapter.outbound.mongo.api.mapping.DomainDocumentId
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoBigIntegerRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoDecimalRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoEnumRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoIdRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoTemporalRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoTypeMetadataPolicy
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoTypeRepresentationManifest
@@ -148,27 +112,6 @@ dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoPlatformSettings
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoProfileProperties
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoStartupValidator
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoTopologyProbe
dev.caskeleton.adapter.outbound.mongo.changestream.MongoChangeEventIdentity
dev.caskeleton.adapter.outbound.mongo.changestream.MongoChangeStreamPipeline
dev.caskeleton.adapter.outbound.mongo.changestream.MongoChangeStreamState
dev.caskeleton.adapter.outbound.mongo.changestream.MongoChangeStreamSubscription
dev.caskeleton.adapter.outbound.mongo.changestream.MongoClusterTime
dev.caskeleton.adapter.outbound.mongo.changestream.MongoResumeCheckpoint
dev.caskeleton.adapter.outbound.mongo.changestream.MongoResumeCheckpointStore
dev.caskeleton.adapter.outbound.mongo.changestream.MongoResumePosition
dev.caskeleton.adapter.outbound.mongo.changestream.MongoResumeTokenCodec
dev.caskeleton.adapter.outbound.mongo.changestream.consumer.MongoChangeStreamSource
dev.caskeleton.adapter.outbound.mongo.changestream.consumer.ReactiveMongoChangeStreamConsumer
dev.caskeleton.adapter.outbound.mongo.changestream.consumer.SpringReactiveChangeStreamSource
dev.caskeleton.adapter.outbound.mongo.changestream.projector.MongoChangeClaim
dev.caskeleton.adapter.outbound.mongo.changestream.projector.MongoChangeDeduplicationStore
dev.caskeleton.adapter.outbound.mongo.changestream.projector.MongoChangeProjectionResult
dev.caskeleton.adapter.outbound.mongo.changestream.projector.MongoChangeProjector
dev.caskeleton.adapter.outbound.mongo.changestream.projector.MongoChangeStreamRunner
dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoChangeHistoryLostException
dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoChangeStreamRecoveryDecision
dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoChangeStreamRecoveryPolicy
dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoInvalidateRecovery
dev.caskeleton.adapter.outbound.mongo.client.MongoClientSettingsFactory
dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureClassifier
dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureTranslator
@@ -276,18 +219,6 @@ dev.caskeleton.adapter.outbound.mongo.query.pagination.MongoKeysetQueryBuilder
dev.caskeleton.adapter.outbound.mongo.query.pagination.MongoKeysetSlice
dev.caskeleton.adapter.outbound.mongo.query.pagination.MongoKeysetSort
dev.caskeleton.adapter.outbound.mongo.query.pagination.MongoNullSortOrdering
dev.caskeleton.adapter.outbound.mongo.reactive.DefaultReactiveMongoExecutor
dev.caskeleton.adapter.outbound.mongo.reactive.ReactiveMongoCallback
dev.caskeleton.adapter.outbound.mongo.reactive.ReactiveMongoCollectionAccess
dev.caskeleton.adapter.outbound.mongo.reactive.ReactiveMongoConsistencyBinder
dev.caskeleton.adapter.outbound.mongo.reactive.ReactiveMongoContextKeys
dev.caskeleton.adapter.outbound.mongo.reactive.ReactiveMongoExecutor
dev.caskeleton.adapter.outbound.mongo.reactive.ReactiveScopedMongoOperations
dev.caskeleton.adapter.outbound.mongo.reactive.cursor.MongoCursorGuard
dev.caskeleton.adapter.outbound.mongo.reactive.cursor.MongoCursorLease
dev.caskeleton.adapter.outbound.mongo.reactive.cursor.MongoCursorTermination
dev.caskeleton.adapter.outbound.mongo.reactive.cursor.MongoReactiveCursorPublisher
dev.caskeleton.adapter.outbound.mongo.reactive.cursor.MongoResultBudgetTracker
dev.caskeleton.adapter.outbound.mongo.schema.index.MongoIndexApplyPolicy
dev.caskeleton.adapter.outbound.mongo.schema.index.MongoIndexDescriptorView
dev.caskeleton.adapter.outbound.mongo.schema.index.MongoIndexDiff
@@ -337,18 +268,12 @@ dev.caskeleton.adapter.outbound.mongo.transaction.MongoTransactionProfile
dev.caskeleton.adapter.outbound.mongo.transaction.MongoTransactionScope
dev.caskeleton.adapter.outbound.mongo.transaction.MongoTransactionSession
dev.caskeleton.adapter.outbound.mongo.transaction.MongoTransactionSessionFactory
dev.caskeleton.adapter.outbound.mongo.transaction.ReactiveMongoTransactionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.ReactiveMongoTransactionSession
dev.caskeleton.adapter.outbound.mongo.transaction.ReactiveMongoTransactionSessionFactory
dev.caskeleton.adapter.outbound.mongo.transaction.SpringMongoTransactionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.SpringMongoTransactionSessionFactory
dev.caskeleton.adapter.outbound.mongo.transaction.SpringReactiveMongoTransactionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.SpringReactiveMongoTransactionSessionFactory
dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoCommitReconciler
dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoRetryBudget
dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoRetryDecision
dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoTransactionRetryCoordinator
dev.caskeleton.adapter.outbound.mongo.transaction.session.MongoCausalSessionContext
dev.caskeleton.adapter.outbound.mongo.transaction.session.MongoCausalSessionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.session.ReactiveMongoCausalSessionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.session.SpringMongoCausalSessionExecutor
+227 -22
View File
@@ -9,7 +9,7 @@ real provider."
| Column | The question | Who decides it |
| --- | --- | --- |
| **IMPLEMENTED** | Does this repository contain the capability? | `src/config/architecture/modules.json` — the leaf is registered |
| **WIRED** | Does the shipped `app-bootstrap` artifact assemble it when its switch is on? | the leaf's `META-INF/spring/...AutoConfiguration.imports`, its edge in `app-bootstrap/build.gradle`, and a composition test that boots `CaSkeletonApplication` |
| **WIRED** | Present when selected: does the module assemble itself — own `AutoConfiguration.imports`, own settings, on when present, off with `enabled=false` — once a service adds its one `runtimeOnly` line to `app-bootstrap/build.gradle`? | the leaf's `META-INF/spring/...AutoConfiguration.imports`, the commented line in `app-bootstrap/build.gradle`, and an activation test in the leaf (present = on, `enabled=false` = off) |
| **QUALIFIED** | Has it been proven against a real provider, by something CI runs? | a strict test lane against a real provider **and** a workflow that executes it |
The third column is the one that rots quietly, because a lane can exist and be invoked by nothing.
@@ -17,35 +17,240 @@ Each row below names the lane *and* the workflow, so "qualified" can be checked
## Status
| Capability | Master switch | IMPLEMENTED | WIRED | QUALIFIED | Evidence |
The default composition — what `bootJar` builds — is web, observability, `domain-core`,
`application-core`, `shared-contract`, `adapter:outbound:support` and `adapter:outbound:identifier`.
Every **yes** row in WIRED below is absent from it until a service uncomments that row's
`runtimeOnly` line in `app-bootstrap/build.gradle`. A module on the classpath is on; its enabled key
defaults to `true`, and `false` turns a present module fully off. `./gradlew
:app-bootstrap:qualificationBootJar` packages the main runtime plus every capability, for compose
lanes and CI; it is not a deployment artifact.
| Capability | Enabled key (property / env, default) | IMPLEMENTED | WIRED | QUALIFIED | Evidence |
| --- | --- | --- | --- | --- | --- |
| Relational persistence (JPA/PostgreSQL) | `APP_PERSISTENCE_JPA_ENABLED` | yes | yes | yes | six `postgresql*IntegrationTest` lanes, run by `integration-main.yml` → `jpa-provider-ownership-contracts` |
| Document persistence (MongoDB) | `APP_PERSISTENCE_MONGO_ENABLED` | yes | yes | yes | six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `mongo-container-lanes` |
| Messaging (broker-neutral core) | `APP_MESSAGING_ENABLED` | yes | yes | Kafka only | `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`. **No broker starter ships**: a deployment composes `messaging-spring-boot-starter-kafka` or `-rabbit` itself, and selecting a broker it did not compose is refused at startup. Rabbit ships validators and no transport. |
| Redis capabilities (cache / rate-limit / lease / idempotency) | `APP_REDIS_ENABLED` | yes | yes | yes | `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml` |
| Notification platform | `APP_NOTIFICATION_PLATFORM_ENABLED` | yes | yes | claim-scoped | `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. |
| File export publication (R2) | `APP_FILESERVER_ENABLED` | yes | yes | yes | A different capability from the platform row below, in its own namespace so the two cannot be switched on together by accident. Atomic publication and durability are proven by `adapter:outbound:fileserver`'s own lanes inside its `check`, which every PR runs. |
| File server platform | `APP_FILESERVER_PLATFORM_ENABLED` | yes | yes | yes | `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane, so it cannot silently disappear), run by `integration-main.yml` → `bootstrap-integration` |
| Outbound HTTP client | `APP_HTTPCLIENT_ENABLED` | yes | yes | yes | `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `integration-main.yml` → `httpclient-fault-injection` |
| GraphQL transport | `APP_GRAPHQL_ENABLED` | yes | yes | compose-level | `local-graphql` and the three `off-*` lanes in `src/config/runtime/compose-profile-contracts.json`, run by `integration-main.yml` → `compose-runtime-smoke`. The route's absence when the switch is off is what those lanes prove. |
| Object storage | `app.object-storage.enabled` (no `MasterSwitch` entry) | yes | **no** | MinIO only | The leaf is **not** an `app-bootstrap` dependency — only `sample-portfolio` consumes it, and `app-bootstrap:integrationTest` assembles it test-only against digest-pinned MinIO. A fork that wants it adds the edge. |
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; six `postgresql*IntegrationTest` lanes, run by `integration-main.yml` → `jpa-provider-ownership-contracts`, qualify it against PostgreSQL. `sample-portfolio` selects it by its build dependency and the module's auto-configuration (no broad scan of the persistence package). `bootRunH2` adds the module to its own classpath only. |
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `mongo-container-lanes` |
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge, the legacy `KafkaSender` seam and the vendored platform with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`; the starter's `integrationTest` is the live Kafka round trip. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis only | One generation: the application `IdempotencyExecutor`, built once by `app-bootstrap` `IdempotencyProviderSelectionConfig` over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `sample-portfolio` cannot depend on `app-bootstrap`, so its own `SampleIdempotencyConfig` builds its one executor from the same keys. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, but no workflow runs it. The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`.. The executor stays in the composition root on purpose — it needs only application-core and its settings — while each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. |
| File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `integration-main.yml` → `bootstrap-integration` |
| Outbound HTTP client | `app.httpclient.enabled` / `APP_HTTPCLIENT_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:httpclient')`) | yes | On when present (`HttpClientPlatformActivationTest`). `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `integration-main.yml` → `httpclient-fault-injection` |
| GraphQL transport | `backend.graphql.enabled` / `APP_GRAPHQL_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:graphql')`) | leaf-level | On when present; `false` also excludes Spring GraphQL's own auto-configuration, so no `/graphql` (`GraphQlCapabilityActivationTest`). `graphqlTransportQualificationTest` runs the HTTP boundary. The deployment-mode/runtime-profile rule is the module's own `GraphQlPlatformStartupValidator`. The default jar does not ship GraphQL, so a compose lane that exercises it runs the qualification jar. |
| Object storage | `app.object-storage.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:objectstorage')`) | MinIO only | Own `ObjectStorageAutoConfiguration` (was bound through bootstrap's properties scan); on when present, `false` leaves only the explicit legacy seam (`ObjectStorageAutoConfigurationTest`). `app-bootstrap:integrationTest` assembles it against digest-pinned MinIO. |
| gRPC platform | — (build-level) | yes | **no** | yes | Absent from the main build entirely: `optional-platforms` is a separate Gradle build, so the switch is the `include`, not an environment variable. `-p optional-platforms ci` runs on every PR and `integrationCheck` certifies the operation ledger against real PostgreSQL. |
| WebSocket transport | — (build-level) | yes | **no** | — | Qualification-only edge in `app-bootstrap`; `ConditionalTransportBuildContractTest` asserts it has no production edge. |
| gRPC transport (`adapter:inbound:grpc`) | `ca-skeleton.grpc.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `ca-skeleton.grpc.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). |
| WebSocket transport | `app.websocket.enabled` / `APP_WEBSOCKET_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:websocket')`) | — | Own `AutoConfiguration.imports` (`WebSocketConfig`), on in a servlet app when present (`WebSocketAutoConfigurationTest`); `ConditionalTransportBuildContractTest` asserts it has no default production edge. |
| Web Advanced library (`adapter:inbound:web-advanced`) | — (build-level; three `backend.web.advanced.*.enabled` switches inside) | yes | **no** | — | No composition root depends on it; `app-bootstrap` takes it `testRuntimeOnly` for the ArchUnit import. No real-provider lane: `webAdvancedTest` (the `web-advanced` tag, run by `release.yml` → `web-stable-release-gate`) is unit and context-runner level. The Nginx lane went with the proxy library on 2026-09-25. |
## Reading the "no" rows
A **no** in WIRED is not a defect. It is the review's Build Composition principle working: the
repository holds more capabilities than any one derived service should ship, and a capability that
is absent from the artifact holds no beans, no connections and no threads whatever its configuration
says. The three **no** rows are the ones where that choice has been made and is enforced by a test.
A **yes** in WIRED means "present when its line is selected": uncommenting the one line is the whole
change, and deleting it removes the module's beans, settings and dependencies together. It does not
mean the default artifact ships the capability — none of the **yes** rows is in the default
composition. A capability that is absent from the artifact holds no beans, no connections and no
threads whatever its configuration says, so the missing line is the ordinary off state and
`enabled=false` is only the explicit off for a module that is present.
The rows that say **yes** are the ones where the choice is still "ship it and switch it off", which
is a weaker guarantee — correct, but it depends on the switch being honest rather than on the code
being absent. Moving more rows to **no** is what `app-bootstrap`'s composition-ownership work is for.
A **no** in WIRED is not a defect either. It marks a capability with no one-line selection: the gRPC
platform is a separate Gradle build, and the web-advanced library is taken as `implementation` by a
service's own adapter leaf, never by a composition root.
## Keeping this honest
`CapabilityStatusDocumentTest` derives the switch list from `MasterSwitch` and fails when a switch
has no row here. That is deliberately the only automated check: a table of facts that a parser
`CapabilityStatusDocumentTest` checks that the column sources above are named — the module
registry, `AutoConfiguration.imports`, and a workflow that executes the lane. The switch list it used
to derive from `MasterSwitch` went with that class (2026-09-25). That is deliberately the only
automated check: a table of facts that a parser
re-derives would be a second source of truth, and the columns above are judgements about evidence,
which is exactly the thing the review says a build must not pretend to compute.
## 제거된 코드 (2026-09-25 리팩터링)
web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/`, `WF/`는 `src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/`.
복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`).
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
| --- | --- | --- | --- |
| 파일 publication R1/R2 어댑터(`FileserverR2Config`, `FileExportConfig`, local-persistent provider 등 31개)와 테스트 | `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/*.java`, 같은 위치의 `src/test` 루트 파일 | `208077fd` | 조립 경로 없음(component scan 밖, 호출자 없음) |
| `FilePublicationPort`·`FileExportPort` 계약 | `src/application-core/src/main/java/dev/caskeleton/application/filepublication/`, `.../application/fileexport/` | `208077fd` | 호출자 없음 |
| `MasterSwitch.FILESERVER`, `app.fileserver.*`·`app.file-export.*` 설정, `APP_FILESERVER_ENABLED`·`APP_FILESERVER_LOCAL_*` env key | `src/shared-contract/.../activation/MasterSwitch.java`, `src/app-bootstrap/src/main/resources/config/fileserver.yml` | `208077fd` | 읽는 코드 없음 |
| websocket Advanced STOMP·RabbitMQ relay(`StompBrokerExclusivity` 포함), `APP_WEBSOCKET_ADVANCED_STOMP_*` env key | `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/advanced/stomp/` | `208077fd` | 같은 기능의 중복 구현(`stomp/`가 남음) |
| websocket main의 검증용 코드(`moduleboundary`, `evidence`, `release`) | `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/{moduleboundary,evidence,release}/` | `208077fd` | 호출자 없음 |
| httpclient `BoundedErrorBody` | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/BoundedErrorBody.java` | `208077fd` | 호출자 없음 |
| httpclient Spring 7 service group·`RestTemplate` 이행 패키지 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/{spring7,migration}/` | `208077fd` | 테스트에서만 사용 |
| `UuidCodec` | `src/adapter/outbound/identifier/src/main/java/dev/caskeleton/adapter/outbound/identifier/UuidCodec.java` | `208077fd` | 호출자 없음 |
| object storage legacy adoption(`maintenance/`, `ObjectStorageLegacyMigrationConfig`, `LegacyObjectAdoptionSettings`), `storage/migration` 포트, sample `AdoptLegacyPosterImageUseCase`와 전용 타입 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/maintenance/`, `src/application-objectstorage/src/main/java/dev/caskeleton/application/storage/migration/`, `src/sample-portfolio/.../application/poster/migration/` | `208077fd` | 켜면 기동 실패(SPI 구현 없음) |
| object storage readiness 타입(`ObjectStorageCapabilityEvidence`, `ObjectStorageCapabilityCard`, `ObjectStorageReadinessLevel`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/readiness/` | `208077fd` | 테스트에서만 사용(검증은 `ObjectStorageReadinessRegistryTest`로 이동) |
| `ObjectControlRecordEnvelope` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectControlRecordEnvelope.java` | `208077fd` | 호출자 없음 |
| application-core 테스트 헬퍼 `CompiledPackageScanner` | `src/application-core/src/test/java/dev/caskeleton/application/testsupport/CompiledPackageScanner.java` | `208077fd` | 호출자 없음 |
| web WebFlux 플랫폼 (`WebFluxPlatformAutoConfiguration` 외) | `W/webflux/` | `208077fd` | D4: servlet + virtual threads 단일 스택, 기본 조립이 선택할 수 없음 |
| web Advanced WebFlux 스트리밍·blocking bridge 어댑터 | `W/advanced/webflux/` | `208077fd` | D4: WebFlux 쌍둥이 |
| 알림 콜백 WebFlux 핸들러 | `W/notification/platform/callback/reactive/` | `208077fd` | D4: WebFlux 쌍둥이 (MVC 컨트롤러가 유일 경로) |
| 파일 서버 WebFlux 전송 | `WF/reactive/` | `208077fd` | D4: WebFlux 쌍둥이, 조립 불가 |
| WebFlux 계약·성능 lane, cross-stack parity lane | `src/adapter/inbound/web/src/webfluxContractTest/`, `build.gradle`의 `webFluxContractTest`·`webFluxPerformanceTest`·`webCrossStackParityTest` | `208077fd` | D4: Reactor Netty 대상 lane, 비교 대상 소멸 |
| web 모듈 경계 맵 (`WebStableModule` 외) | `W/moduleboundary/`, `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/moduleboundary/` | `208077fd` | main에 둔 governance 코드, 소비자 없음 |
| 서명 커서 코덱 (`CursorCodec`, `CursorException`) | `W/cursor/` | `208077fd` | 호출자 0, `GlobalExceptionHandler` 커서 처리도 함께 제거 |
| 2세대 관측 (`WebAccessLog*`, `WebAudit*`, `WebObservationConvention`, `WebMetricCardinalityPolicy`) | `W/observability/` | `208077fd` | 조립 안 된 2세대, `RequestLoggingFilter`가 정본 |
| 2세대 조건부 요청 (`EntityTag`, `ConditionalReadEvaluator`, `MutationPreconditionEvaluator` 외) | `W/conditional/` | `208077fd` | 2세대, `ETags`·`PreconditionFailedException`이 정본 |
| 2세대 페이지네이션 (`HmacWebCursorCodec`, `WebCollectionRequestParser` 외 16개) | `W/pagination/` | `208077fd` | 2세대, `PageParams`·`SortParam`이 정본 |
| 응답 계약·헤더 이름 (`WebHeaderName`, `WebResponseContract`, `WebSuccessResponse`, `DeprecationHeaderWriter`) | `W/http/`, `W/versioning/` | `208077fd` | 호출자 0 |
| 병렬 rate-limit (`WebRateLimiter`, web `RateLimitDecision`·`RateLimitFailurePolicy`·`RateLimitProfileName`, `WebMvcThrottleFilter`, `ThrottleProblemWriter`) | `W/ratelimit/`, `W/mvc/throttle/`, `W/error/` | `208077fd` | 2세대, `RateLimitInterceptor` + shared-contract `RateLimitDecision`이 정본 |
| rate-limit draft 헤더 (`RATELIMIT_DRAFT_HEADERS`) | `W/advanced/ratelimit/`, `WebAdvancedFeature` 상수 | `208077fd` | 병렬 rate-limit 세트에만 붙는 부가 기능 |
| admission 제어 | `W/admission/` | `208077fd` | 조립 안 된 2세대 |
| evidence 필터·startup check·platform snapshot | `W/evidence/`, `W/mvc/filter/WebMvcEvidenceFilter.java`, `W/mvc/autoconfigure/WebMvcPlatformStartupCheck.java`, `W/admin/platform/` | `208077fd` | 읽는 곳 없는 bean, `WebMvcPlatformAutoConfiguration`은 3개 bean만 유지 |
| 검증 예외 매퍼 | `W/validation/` | `208077fd` | 제거된 bean·problem handler에서만 도달 |
| WebProblem 어휘 (`ProblemCode`, `ProblemCatalog`, `WebProblem`, `WebProblemFactory` 외) | `W/error/`, `W/mvc/error/`, `src/adapter/inbound/web/src/main/resources/META-INF/web/problem-catalog.yaml`, `W/openapi/ProblemSchemaContributor.java`, `W/openapi/WebOpenApiReleaseGate.java` | `208077fd` | 운영 에러는 `GlobalExceptionHandler`의 Envelope, `spring.mvc.problemdetails.enabled=false` |
| 요청 budget 필터 (`WebMvcBudgetFilter`, `BudgetProblemMapper`) | `W/mvc/budget/`, `W/error/BudgetProblemMapper.java` | `208077fd` | fixture 전용, WebProblem 어휘에 의존 |
| stream 종료 어휘 (`TerminationDecision`, `WebStreamEnvelope`, `WebStreamTerminationMapper`) | `W/advanced/stream/` | `208077fd` | `ProblemCode`에 의존, 호출자 0 |
| durable operation HTTP 투영 (`OperationQueryService`, `OperationHttpController` 외) | `W/operationasync/`, `W/mvc/operation/` | `208077fd` | 운영 조립 없음(scan 제외·bean 없음), 실패를 `WebProblem`으로만 표현. application-core use case는 유지 |
| WebProblem·budget·throttle·operation fixture와 lane | `src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/adapter/inbound/web/testkit/{budget,throttle,operation,contract,webflux}/`, `webtestkit/{Budget,Throttle}FixtureApplication.java`, `systemTest`·`jettyCompatTest`의 budget/contract/operation/throttle IT | `208077fd` | 제거된 표면만 인증. Tomcat/Jetty 전송 lane은 Envelope 기준으로 유지 |
| WebFlux 전용 오버로드 (`ZeroCopyEligibility.isEligible(ServerHttpResponse…)`·`supportsZeroCopy`, `CallbackRequestFactory.create(…externalUrl…)`) | `WF/http/ZeroCopyEligibility.java`, `W/notification/platform/callback/CallbackRequestFactory.java` | `208077fd` | 제거된 reactive 핸들러만 호출 |
| graphql 부팅 시 컨트롤러 경계 검사 `architecture/` (9개, ~970줄) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/architecture/` | `208077fd` | 부팅마다 리플렉션으로 검사하던 것. 규칙 2개(resolver 전송 타입, raw DataFetcher 위치)는 `GraphQlTransportBoundaryArchitectureTest`(ArchUnit)로 옮김 |
| `GraphQlPlatformAutoConfiguration.graphQlControllerBoundaryCheck` bean | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformAutoConfiguration.java` | `208077fd` | 위 검사를 부팅 때 돌리던 bean. 빌드 때 ArchUnit으로 대체 |
| graphql 스키마 호환성 비교기 `compat/` (11개, ~1,560줄) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/compat/` | `208077fd` | 호출하는 production 코드 없음(테스트만) |
| graphql 모듈 경계 모델 `moduleboundary/` (main 4개 + test 스캐너 3개) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/moduleboundary/` | `208077fd` | sub-package 경계 선언과 소스 스캐너 테스트. 런타임 소비자 없음 |
| graphql 릴리스 게이트 `release/` (9개) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/release/` | `208077fd` | 호출하는 곳 없음. 성능·장애 증거도 없었음 |
| graphql Advanced 릴리스 게이트 `advanced/release/` (7개) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/advanced/release/` | `208077fd` | 호출하는 곳 없음 |
| `GraphQlAdvancedDependencyRules` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/advanced/bootstrap/GraphQlAdvancedDependencyRules.java` | `208077fd` | `moduleboundary` 전용, 테스트에서만 사용 |
| `GraphQlGeneratedCompatibilityGate` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/advanced/codegen/GraphQlGeneratedCompatibilityGate.java` | `208077fd` | `compat` 전용, 테스트에서만 사용 |
| testFixtures `GraphQlSchemaContractSuite` | `src/adapter/inbound/graphql/src/testFixtures/java/dev/caskeleton/adapter/inbound/graphql/testkit/GraphQlSchemaContractSuite.java` | `208077fd` | `compat` 의존, 테스트에서만 사용 |
| messaging adapter R1 contract/binding 컴파일러 `contract/`·`destination/`·`config/` (MessagingCapabilityCardRegistry 포함) | `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/{contract,destination,config}/` | `208077fd` | 어느 조립에도 연결되지 않은 R1 세대 |
| messaging adapter R1 JSON Schema envelope encoder `envelope/` + pin한 Draft 2020-12 meta-schema 리소스 | `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/envelope/, src/adapter/outbound/messaging/src/main/resources/contracts/messaging/meta/` | `208077fd` | 조립 없음. NetworkNT가 production 의존성에서 빠짐. `IntegrationEventEncoderPort`는 adopter 확장 지점으로 유지 |
| messaging adapter `realtime/` (`MessagingDurableFanoutAdapter`, `RealtimeFanoutEnvelopeJson`) | `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/realtime/` | `208077fd` | bean 없음 |
| strict lane `messagingCompiledContractsQualificationTest`·`messagingJsonSchemaV1QualificationTest`, 루트 `verifyMessagingJsonSchemaV1`·`validateMessagingJsonSchemaV1EvidenceManifestSchema` | `src/adapter/outbound/messaging/build.gradle, src/build-tools/src/main/java/dev/caskeleton/buildtools/messaging/MessagingQualificationPlugin.java` | `208077fd` | 삭제한 R1 코드만 검증하던 레인. `verifyMessagingContracts`는 application·shared 레인으로 남김 |
| `MessagingEvidenceManifestSchemaValidator`(+Test)와 루트 JavaExec `validateMessagingContractsEvidenceManifestSchema` | `src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/qualification/` | `208077fd` | 삭제한 `LocalJsonSchemaRegistry`에 의존했고, 다른 project의 test classpath를 루트 task가 풀어 쓰는 구조였음. 같은 검증을 build-tools `MessagingEvidenceSchemaValidator`로 옮겨 `verifyMessagingContracts`가 직접 수행 |
| `messaging-pulsar-experimental` leaf | `src/messaging/messaging-pulsar-experimental/` | `208077fd` | SDK 없는 seam, 기본 비활성, 조립 없음 |
| `messaging-nats-experimental` leaf | `src/messaging/messaging-nats-experimental/` | `208077fd` | SDK 없는 seam, 기본 비활성, 조립 없음 |
| `messaging-kafka-share-experimental` leaf | `src/messaging/messaging-kafka-share-experimental/` | `208077fd` | 기본 비활성, 조립 없음 |
| `messaging-spring-cloud-stream-bridge` leaf | `src/messaging/messaging-spring-cloud-stream-bridge/` | `208077fd` | StreamBridge 연동 없는 seam, 조립 없음 |
| `messaging-rabbit` leaf | `src/messaging/messaging-rabbit/` | `208077fd` | production transport가 없어 선택하면 기동 거부되던 상태 |
| `messaging-spring-boot-starter-rabbit` leaf | `src/messaging/messaging-spring-boot-starter-rabbit/` | `208077fd` | 위 rabbit leaf의 조립 모듈 |
| Debezium outbox 매핑 (`DebeziumOutboxEventRouter` 등 4개 + `debezium/outbox-event-router.properties`) | `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/Debezium*.java` | `208077fd` | 조립 없음. `routing_key` 컬럼은 유지 |
| `MessagingSettings.Experimental`·`Bridge` (`app.messaging.experimental.*`, `app.messaging.bridge.*`) | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingSettings.java` | `208077fd` | 바인딩만 되고 읽는 코드 없음 |
| `MessagingProviderSelection`의 rabbit 항목 | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProviderSelection.java` | `208077fd` | rabbit leaf 삭제에 따름 |
| starter의 `messaging-cloudevents`·`messaging-claim-check` 의존 edge (leaf는 유지) | `src/messaging/messaging-spring-boot-starter/build.gradle, src/config/architecture/modules.json` | `208077fd` | starter main이 두 leaf를 참조하지 않음 |
| RabbitMQ·Pulsar·NATS 개발용 compose | `infra/messaging/{rabbitmq,pulsar,nats}/docker-compose.yml` | `208077fd` | 해당 어댑터 삭제에 따름 |
| Notification R1 타입 96개(`NotificationPort`·`Notification`·`NotificationChannel` 제외)와 테스트 19개 | `src/application-notification/src/{main,test}/java/dev/caskeleton/application/notification/*.java` | `208077fd` | production 소비자 0건. platform이 canonical(NOTIF-ADR-005) |
| ArchUnit 규칙 `NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER` | `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java` | `208077fd` | R1이 없어져 지킬 경계가 없음 |
| Notification Reactor facade와 `reactor-core`·`reactor-test`·`spring-web` 의존 | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/reactor/` | `208077fd` | 조립 0건. `spring-web`은 import 0건 |
| `NotificationOrchestrator` | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/api/NotificationOrchestrator.java` | `208077fd` | 호출자는 연산별 use case 포트로 이미 분리됨 |
| notification platform `sms`·`push`·`email`·`webpush` facade와 `ApplicationReceiptServiceImpl` | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/{sms,push,email,webpush}/`, `.../platform/dispatch/ApplicationReceiptServiceImpl.java` | `208077fd` | 구현·조립 0건 |
| 던지는 곳이 없는 notification 예외 12종 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/api/error/` | `208077fd` | throw 0건 |
| notification redaction 5종(`NotificationRedactor`, `SafeDiagnosticContext`, `SensitiveValueClassifier`, `SensitiveValueKind`, `UnsafeDiagnosticFieldException`) | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/security/` | `208077fd` | production 호출 0건 |
| `contract-v1` 테스트 템플릿 4개 | `src/adapter/outbound/notification/src/test/resources/notification/templates/` | `208077fd` | 읽는 테스트 없음 |
| JPA notification crypto 6종과 테스트 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/crypto/` | `208077fd` | 테스트 외 사용 0건. `ContactPointRoundTripTest`는 application-notification으로 이동 |
| JPA 두 번째 트랜잭션·재시도 엔진 19종(`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`, `CommitFailureClassifier`, `EvidenceAwareJpaTransactionManager`, `CompletionUnknownRecorder` 등), `JpaTransactionAutoConfiguration`, `JpaObservabilityAutoConfiguration`, `JpaRetryObservation`, `api/transaction/*`(`TransactionCompletionEvidence` 제외) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/{transaction,autoconfigure,observation,api/transaction}/` | `208077fd` | 빈은 있었으나 호출자 0건. 트랜잭션 엔진을 `SpringTransactionPort` 하나로 |
| `VendorFailureTranslator` 빈 2개와 `H2FailureTranslator` | `.../persistence/postgresql/PostgreSqlPersistenceConfig.java`, `.../persistence/h2/` | `208077fd` | 유일한 소비자(위 엔진)가 사라짐 |
| 위 엔진 전용 테스트(`CommitAmbiguityContractTest`, `OptimisticRetryIntegrationTest`, `PostgreSqlVendorFailureTranslatorRegistrationTest` 등) | `src/adapter/outbound/persistence-jpa/src/{test,postgresqlIntegrationTest}/` | `208077fd` | 대상 코드 삭제 |
| `PolicyTransactionPort` 계열(`TransactionRequest`, `TransactionResult`, `TransactionPolicyId`, `TransactionPhase`, `TransactionOutcome`, `ReconciliationReference`, `TransactionAdmissionException`) | `src/application-core/src/main/java/dev/caskeleton/application/transaction/` | `208077fd` | 유일한 호출자(fileserver 보상)를 `TransactionPort.inNew`로 교체 |
| `SpringPolicyTransactionPort`, `TransactionRetryBackoff`, `TransactionRetryClassifier`, 타임아웃 계열(`TransactionDeadlineCalculator`, `TransactionStartBudget`, `EffectiveTransactionTimeouts`, `TransactionLocalTimeoutConfigurer`, `PostgreSqlLocalTimeoutConfigurer`, `H2LocalTimeoutConfigurer`, `JpaTransactionSettings`, `JpaTransactionConfig`)과 `ca-skeleton.jpa.transaction.*` 설정 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/`, `src/app-bootstrap/src/main/resources/config/persistence.yml` | `208077fd` | policy 경로 전용. 교체 후 사용처 0건 |
| `FileserverCompensationTransaction` | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/` | `208077fd` | `transactions.inNew(...)` 한 줄로 대체 |
| Mongo reactive 경로(`reactive/**`, reactive transaction/session 6종, `ReactiveExecution`, `applyTo(ReactiveMongoTemplate)`)와 reactive starter·`reactor-test` 의존 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/{reactive,transaction}/` | `208077fd` | 기본 조립에서 exclude되어 도달 불가, 포트 없음 |
| Mongo change stream(`changestream/**`)과 change-stream→messaging bridge(`advanced/bridge/`), 문서 `change-stream-guide.md`·`runbooks/history-lost.md` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/{changestream,advanced/bridge}/`, `docs/mongodb/` | `208077fd` | driver source가 없어 실행 불가 |
| application-core cache 20종(`CacheAsideExecutor`, `CacheAsidePolicy`, `CacheSingleFlight`, `CacheRefresh*`, `CacheObservation*` 등)과 테스트 4개 | `src/application-core/src/main/java/dev/caskeleton/application/cache/` | `208077fd` | 조립·소비자 0건. cache-redis는 `CacheRegionPort` 계열 9종만 사용 |
| `LeaseWatchdog` | `src/application-core/src/main/java/dev/caskeleton/application/lease/` | `208077fd` | main 참조 0건 |
| `TransactionCompletionResolver`, `CompletionResolution` | `src/application-core/src/main/java/dev/caskeleton/application/transaction/` | `208077fd` | 구현체 0건 |
| same-store inbox(`application/inbox/`, `PostgreSqlSameStoreInboxAdapter`, `PostgreSqlInboxIntegrationTest`, `db/migration/jpa/inbox`, readiness card `jpa-inbox-same-store-v1`) | `src/application-core/src/main/java/dev/caskeleton/application/inbox/`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/inbox/` | `208077fd` | 어떤 조립도 migration 트리를 적용한 적 없음 |
| `EphemeralFanoutPort`, `RedisEphemeralFanoutAdapter` | `src/application-core/src/main/java/dev/caskeleton/application/realtime/`, `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/realtime/` | `208077fd` | bean·테스트·호출자 0건 |
| PostgreSQL work-claim 실행기(`WorkClaimExecutor`, `PostgreSqlWorkClaimExecutor`, `WorkClaim`, `WorkQueueDefinition`, `WorkQueueName`) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/lock/` | `208077fd` | 호출자 0건 |
| PostgreSQL upsert 실행기 7종 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/write/` | `208077fd` | 호출자 0건 |
| Mongo `ca-skeleton.persistence-mongo.advanced.<capability>.enabled` 바인딩(`MongoAdvancedConfiguration`, `MongoAdvancedSettings`)과 `MongoAdvancedCapabilityFlags.PROPERTY_PREFIX`·`propertyFor` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/autoconfigure/`, `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/MongoAdvancedCapabilityFlags.java` | `208077fd` | import하는 main 코드 0건이라 어떤 배포 property도 flag에 닿지 않음. flag는 진입점을 만드는 어댑터 코드가 직접 만든다 |
| Mongo search·vector(`advanced/search/` 5종, `advanced/vector/` 5종, `MongoSearchReadinessGate`·`MongoVectorSearchBenchmarkGate` 포함), 문서 `docs/mongodb/advanced/search-vector.md` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/{search,vector}/` | `208077fd` | `MongoSearchOperations`·`MongoVectorSearchOperations` 구현체 0건. 나머지는 그 인터페이스의 인자와 main에 둔 gate |
| Mongo time series(`advanced/timeseries/` 6종), 문서 `docs/mongodb/advanced/time-series.md` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/timeseries/` | `208077fd` | `MongoTimeSeriesOperations` 구현체 0건. 나머지는 descriptor와 모든 항목이 unsupported인 표 |
| Mongo GridFS 호환(`advanced/gridfs/` 4종), 문서 `docs/mongodb/advanced/gridfs-migration.md` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/gridfs/` | `208077fd` | `MongoGridFsCompatibilityReader` 구현체 0건이라 `MongoGridFsMigrationJob`을 실행할 수 없음 |
| `MongoDataKeyResolver`, `MongoTenantDatabaseResolver`, `TenantScopedMongoOperations` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/{encryption/csfle,tenancy/database,tenancy/shared}/` | `208077fd` | 구현체·호출자 0건 |
| `MongoAdvancedPromotionGate`, `MongoAdvancedPromotionEvidence` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/` | `208077fd` | production classpath의 promotion gate, 자기 테스트 외 호출자 0건. 증거 항목은 ADR-MONGO-ADV-001의 리뷰 의무로 남김 |
| testFixtures `MongoAtlasCapabilityContractSuite`, provider testkit `MongoAtlasLocalContainer`, release contract `MONGO-REL-011` | `src/adapter/outbound/persistence-mongo/src/{testFixtures,mongoProviderTestkit}/java/dev/caskeleton/adapter/outbound/mongo/testkit/atlas/`, `src/config/mongodb/release-contracts.json` | `208077fd` | 위 promotion gate 테스트만 사용. 등록된 lane 없음 |
| `MongoIdRepresentation`, `MongoBulkPartialFailureException` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/api/mapping/`, `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/api/error/` | `208077fd` | 참조 0건. 문서는 "`_id` 표현을 정한다", "부분 실패를 알린다"고 했지만 쓰거나 던지는 코드가 없음 |
| Mongo `platform.change-streams` 키(`MongoPlatformSettings.changeStreams`, `MongoStartupValidator`의 change stream 검사) | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/` | `208077fd` | 켜면 기동 실패만 하는 키. change stream 기능은 이미 삭제됨 |
| Mongo profile 키 `consistency-default`, `decimal-representation`, `runtime-auto-create-indexes` | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoProfileProperties.java`, `src/app-bootstrap/src/main/resources/config/persistence.yml`(주석 예시), `docs/mongo/persistence-profile.example.yml` | `208077fd` | 검증만 하고 읽는 코드 0건. decimal은 허용 값이 `DECIMAL128` 하나, auto-index는 Spring Data 설정에 연결되지 않음 |
| 위 대상 전용 테스트 5개 클래스(36개)와 테스트 메서드 2개 | `src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/advanced/{autoconfigure,search,timeseries,gridfs}/`, `.../advanced/MongoAdvancedPromotionGateTest.java`, `MongoPlatformSettingsTest.productionRefusesRuntimeIndexCreation`, `MongoStartupValidationTest.changeStreamsCannotBeSwitchedOn` | `208077fd` | 대상 코드 삭제. guard 거부 검증은 `MongoAdvancedCapabilityGuardTest`로 옮김 |
| redis-sdk 진입 인터페이스 `RedisOperations`·`ReactiveRedisOperations` | `src/adapter/outbound/redis-sdk/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/api/` | `208077fd` | 구현체 없음 |
| redis-sdk `ExpirationUpdatePolicy` | `src/adapter/outbound/redis-sdk/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/api/operations/` | `208077fd` | 호출자 없음 |
| redis-sdk `RedisCommandMetadataDiff`·`RedisServerCommandMetadata`와 테스트 | `src/adapter/outbound/redis-sdk/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/command/` | `208077fd` | main에 둔 gate, 연결된 build 검사 없음(테스트에서만 사용) |
| redis-sdk `RedisConnectionRegistry`·`RedisConnectionLease`와 테스트 | `src/adapter/outbound/redis-sdk/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/connection/` | `208077fd` | 테스트에서만 사용. lane 한도는 redis-runtime `RedisRuntimeOwner`가 소유 |
| `app.redis.limits.*`·`advanced.*`·`raw.*`·`timeout.collection`·`timeout.admin`·`blocking.max-block`·`lifecycle.tls-handshake-timeout`·`capacity.maximum-in-flight-bytes`·`capacity.maximum-reply-bytes`·`pubsub.overflow-policy`, env key 23개, `RedisCredentialRole.RAW` | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkSettings.java`, `RedisSdkAutoConfiguration.java` | `208077fd` | 검증만 하고 읽는 코드 없음. `raw.*`는 어떤 lane도 쓰지 않는 RAW 계정 클라이언트를 만들고 allowlist 파일은 존재만 확인. SDK 한도·advanced 정책·raw 승인은 코드(`RedisOperationLimits`, `ConfiguredRedisPolicyAuthority`, `RawCommandApprovals`)로 준다 |
| application-core outbox V2 포트·유스케이스 17종(`NewOutboxEventV2`, `OutboxAppendPortV2`, `OutboxPollingDeliveryPortV2`, `PublishNextOutboxDeliveryUseCase`, `OutboxV2RetryPolicy`, `OutboxPublicationAuthority` 등)과 계약 테스트 2개 | `src/application-core/src/{main,test}/java/dev/caskeleton/application/outbox/v2/` | `208077fd` | 어떤 조립도 만들지 않은 세대(D2). v1 relay 한 세대만 남기고 owner/token fencing은 v1로 이식 |
| JPA outbox V2 adapter(`PostgreSqlImmutableOutboxAppendAdapter`, `PostgreSqlPollingDeliveryAdapter`, `CanonicalOutboxEventRowMapper`)와 단위 테스트(`PostgreSqlOutboxTransitionDigestTest`, `OutboxStorageMigrationSafetyTest`) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/outbox/`, `.../src/test/java/.../persistence/{postgresql/outbox,migration}/` | `208077fd` | 빈 등록 0건, 위 V2 포트 전용 |
| outbox V2 migration stream `jpa/outbox-storage`(V1·V2), `jpa/outbox-polling`(V1·V2)과 `applied-migrations.sha256`의 해당 4줄 | `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/{outbox-storage,outbox-polling}/` | `208077fd` | 어떤 composition도 Flyway location으로 설정한 적 없음 |
| outbox V2 PostgreSQL 통합 테스트(`PostgreSqlOutboxStorageIntegrationTest`, `PostgreSqlOutboxPollingIntegrationTest`, `CanonicalOutboxV2TestFixture`, `LegacyOutboxDrainContractTest`), lane `postgresqlOutboxStorageIntegrationTest`·`postgresqlOutboxPollingIntegrationTest`, `PostgreSqlOptionalStreamLifecycle.outboxStorage()/outboxPolling()` | `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/`, `src/build-logic/src/main/java/dev/caskeleton/buildlogic/jpa/JpaTestLanesPlugin.java` | `208077fd` | 대상 코드 삭제. CI에 걸린 lane 없음 |
| readiness card `jpa-outbox-storage-v2`, `jpa-outbox-polling-delivery-v2`, `jpa-outbox-cdc-retention-v1`(storage-v2 전제)과 polling/CDC 동시 선택 금지 규칙 | `src/config/jpa/readiness-cards.yaml`, `src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaReadinessRegistryValidator.java` | `208077fd` | 대상 stream·adapter 삭제 |
| web Advanced release gate (`WebAdvancedPromotionGate`, `WebAdvancedReleaseManifest`)와 기능 카탈로그 `WebAdvancedFeature`, 테스트 `WebAdvancedReleaseTest`·`WebAdvancedRollbackIT`의 gate 테스트 2개 | `W/advanced/release/`, `W/advanced/WebAdvancedFeature.java`, `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/release/` | `208077fd` | main에 둔 승격 gate, 테스트에서만 호출. 카탈로그는 읽는 코드 없는 설정 키(`…json-merge-patch.enabled`, `…sse.enabled`, `…cbor.enabled` 등)를 문서에 약속 |
| OpenAPI 3.2 승격 리포트 (`OpenApi32CompatibilityReport`, `OpenApiToolchainMatrix`)와 테스트 5개 | `W/advanced/openapi/`, `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/openapi/OpenApi32CompatibilityReportTest.java` | `208077fd` | main에 둔 승격 gate, 테스트에서만 호출. `OpenApiVersionLane` 테스트 1개는 `OpenApiVersionLaneTest`로 남김 |
| blocking bridge 예산 (`BlockingBridgeBudget`, `BlockingBridgeProfile`, `BlockingBridgeRejectedException`)과 테스트 | `W/advanced/blockingbridge/`, `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/blockingbridge/` | `208077fd` | 예산을 거는 WebFlux bridge 어댑터가 이미 삭제됨(D4) |
| 호출자 0 타입: `SpringMvcRouteInventoryCollector`, `WebPartialResponseException`, `WebBudgetMeter`(+ `WebBudgetOutcome`·`WebBudgetExceededException`·`WebBudgetViolation`), `WebStatusContract`, `WebJsonDecodingException` | `W/admin/route/`, `W/advanced/stream/`, `W/budget/`, `W/http/`, `W/json/` | `208077fd` | main·테스트 어디서도 참조 없음 |
| 쓰지 않는 테스트 대역 `InMemoryIdempotencyStore` | `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/idempotency/` | `208077fd` | 참조 0 |
| websocket Advanced 전체(resume, cluster, presence, CBOR·Protobuf codec, compression, 외부 client, GraphQL bridge, HTTP/2·3 profile, SockJS profile·`SockJsConfiguration`, `AdvancedPromotionGate`, `WebSocketAdvancedCapability`)와 테스트 16개, lane `websocketAdvancedTest`, `compileOnly` CBOR·protobuf 의존, `application-core` 의존 | `WS/advanced/`, `WST/advanced/`, `src/adapter/inbound/websocket/build.gradle` | `208077fd` | 어떤 Spring 설정도 import하지 않음(`AutoConfiguration.imports` 없음, bootstrap scan 밖). `SockJsConfiguration`은 켜면 조립되지 않는 platform bean 3개를 요구. `application-core` edge는 이 코드만 사용 |
| `app.websocket.platform.*` 설정(`WebSocketPlatformSettings`, `WebSocketPlatformSafetyConfiguration`, `WebSocketPlatformStartupValidator`, `WebSocketStackExclusivity`)과 env key 15개(`APP_WEBSOCKET_PLATFORM_*` 14개, `APP_WEBSOCKET_ADVANCED_SOCKJS_ENABLED`) | `WS/config/`, `docs/registries/env-keys.yaml`, `src/.env.example` | `208077fd` | 바인딩하는 코드 없음(`@EnableConfigurationProperties` 없음). safety config는 import하는 곳이 없고, 켜면 아무도 만들지 않는 catalog bean 6개를 요구해 기동 실패 |
| platform catalog·정책 패키지 `admin`, `authz`, `codec`, `handler`, `handshake`, `lifecycle`, `observability`, `ordering`, `security`, `session`, `protocol`(`WebSocketMessageId` 제외), `core`(`WebSocketConnectionId`와 idempotency가 쓰는 2개 제외)와 테스트 | `WS/{admin,authz,codec,handler,handshake,lifecycle,observability,ordering,security,session,protocol,core}/`, `WST/` 같은 패키지 | `208077fd` | 테스트에서만 사용. `PlatformWebSocketHandler`도 쓰지 않음. `HandshakeAdmissionPipeline`은 bearer/cookie를 헤더 존재만으로 통과시켰고(2026-09-24 모듈 리뷰 K#1), `WebSocketSessionRegistry`는 연결 수 상한 경쟁 조건이 있었음(K#7) |
| reactive runtime `webflux/`(`ReactiveFrameSink`, `WebSocketDataBufferLifecycle`, `WebSocketDataBufferPolicy`)와 `spring-webflux`·`reactor-core` 의존 | `WS/webflux/`, `WST/webflux/` | `208077fd` | 템플릿은 servlet 전용(D4). 호출자 없음. sink 버퍼가 무제한이라 budget이 동작하지 않았음(K#3) |
| `inbound/FragmentAssembler`, close-code catalog `error/`, `WebSocketConnectionBudget`의 `maxFrameBytes`·`maxFragments`·`maxInboundMessagesPerSecond`·`maxConnectionAge`·`idleTimeout` | `WS/{inbound,error}/`, `WS/budget/WebSocketConnectionBudget.java` | `208077fd` | servlet handler는 whole-message 모드라 frame·fragment를 볼 수 없어 frame/fragment 상한이 동작하지 않았음(K#2). 나머지 3개는 읽는 코드 없음. 수신 상한은 `maxMessageBytes`(UTF-8 바이트) 하나, idle timeout은 컨테이너 설정. close는 Spring `CloseStatus`(1001/1009/1013) 직접 사용 |
| testFixtures `WebSocketArchitectureRules`(WS-ARCH-1~6)와 `WebSocketArchitectureRulesTest`, ArchUnit test 의존 | `src/adapter/inbound/websocket/src/testFixtures/java/dev/caskeleton/adapter/inbound/websocket/testkit/arch/`, `WST/arch/` | `208077fd` | 규칙 대상 패키지(`handler`, `webflux`, `advanced`)가 삭제됨. 남는 WS-ARCH-4(persistence 금지)는 registry 의존 게이트가 이미 막음 |
| 문서 `docs/websocket/advanced-support-matrix.md`, `docs/websocket/repository-adaptation.md`, `docs/websocket/runbooks/resume-history-loss.md` | `docs/websocket/` | `208077fd` | 삭제한 코드와 존재하지 않는 `…advanced.*.enabled` 플래그를 설명 |
| messaging adapter `realtime/` (`MessagingDurableFanoutAdapter`, `RealtimeFanoutEnvelopeJson`) | `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/realtime/` | `208077fd` | bean 없음. `DurableFanoutPort`는 websocket이 쓰므로 유지 |
| `app.jpa-platform.addons-enabled` 조건(`PersistenceJpaRuntimeConfig`, bootstrap `JpaPlatformRuntimeAutoConfiguration`)과 그 스위치 테스트 2개 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/autoconfigure/PersistenceJpaRuntimeConfig.java`, `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/JpaPlatformRuntimeAutoConfiguration.java` | `208077fd` | 어떤 property source·env 키도 설정하지 않음(테스트만 false로 설정). JPA 마스터 스위치 `ca-skeleton.persistence-jpa.enabled` 하나로 켜고 끈다 |
| `backend.jpa.experimental.*` 플래그 8개(`ExperimentalFeature`, `ExperimentalFeatureGate`, 진입점 3개의 `enabledBy(..)` 팩토리)와 `ExperimentalEntryConsentTest` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/` | `208077fd` | 설정에서 플래그를 읽는 코드 0건. gate는 호출자가 직접 만든 Map만 검사했고 "기동 실패" 문서 약속은 거짓. 진입점은 public 생성자로 직접 만든다 |
| `experimental/next/*`(`CompatibilityLane`, `ExperimentalPromotionGate`, `PromotionDecision`, `PromotionEvidence`, `HibernateCompatibilityPolicy`)와 테스트 `CompatibilityLaneDefinitionTest`·`ExperimentalPromotionGateTest`·`HibernateCompatibilityPolicyTest` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/` | `208077fd` | main에 둔 promotion/lane gate, 자기 테스트 외 호출자 0건. `HibernateProviderPolicy` 검증은 `HibernateProviderPolicyTest`로, 버전 canary는 `Jpa4/Hibernate8/PostgreSql19CompatibilityTest`로 남김(`jpa-next.yml`이 실행) |
| `TenantEntityManagerFactoryRegistry`, `RlsAdminBypassToken`, `TenantEntityListenerGuard` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/{database,rls,tenant}/` | `208077fd` | 테스트·호출자 0건 |
| `JpaTransactionObservation`(`jpa.transaction.*` meter)와 테스트 메서드 2개 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/observation/JpaTransactionObservation.java` | `208077fd` | 생성하는 곳 0건이라 문서의 transaction metric은 나온 적 없음. `docs/jpa/observability.md` 정정 |
| 단일 구현 인터페이스 `JpaBatchExecutor`, `BulkDmlExecutor`, `StatelessSessionRunner`, `PostgreSqlCopyLoader`, `EnversHistoryReader`, `CursorCodec`, `VendorFailureTranslator`, `SqlStateResolver`, `ConstraintCatalog` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/{hibernate/batch,hibernate/bulk,hibernate/stateless,postgresql/copy,envers,api/query,api/error,postgresql/error}/` | `208077fd` | 구현 1개, 인터페이스를 참조하는 테스트·외부 코드 0건. 테스트된 구현(`HibernateJpaBatchExecutor` 등)을 진입점으로 남김 |
| 구현 없는 인터페이스 `EntityManagerAccess`, `LockWaitObservation` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/springdata/`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/lock/` | `208077fd` | 구현·호출자 0건 |
| `JpaBatchProfileRegistry`, `SpecificationPolicy`, `QuerydslJpaSupport`, `PgRangeJdbcType`, `PostgreSqlRangeQuerySupport`, `FailedConcurrentIndexRecovery`, `NonTransactionalMigrationPolicy`, `SchemaVersionSnapshot` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/{hibernate/batch,springdata,querydsl,postgresql/range,migration}/` | `208077fd` | 테스트·호출자 0건. invalid index 확인은 `docs/jpa/runbooks.md`의 SQL로 대체 |
| `FlywayValidationGate`, `ConcurrentIndexMigrationInspector`, `MigrationResource`(main에서 testkit으로 이동, 삭제 아님) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/` → `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/` | `208077fd` | 테스트·testkit에서만 쓰는 gate. 기동 검증은 Flyway validate-on-migrate와 `ddl-auto=validate`가 한다 |
| `JpaCapability.TRANSACTION_RETRY`·`POSTGRESQL_NATIVE_WRITE`·`POSTGRESQL_WORK_CLAIM`과 `jpaplatform` actuator 보고 항목 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/api/capability/JpaCapability.java`, `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/JpaPlatformAutoConfiguration.java` | `208077fd` | 해당 코드(재시도 엔진, upsert·work-claim 실행기)가 이미 삭제됐는데 보고서는 Stable/Advanced로 광고함 |
| web Advanced functional routes (`FunctionalRouteRegistry`, `WebFunctionalHandlerAdapter` 외)와 테스트, web-advanced의 `spring-webflux` 의존 | `W/advanced/functional/`, `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/advanced/functional/` (W3-2에서 `adapter:inbound:web-advanced`로 옮긴 뒤 삭제) | `208077fd` | D4: WebFlux `RouterFunction`을 만든다. servlet 전용 템플릿에서 서빙할 곳이 없음 |
| forwarded header 라이브러리 (`ForwardedHeaderSanitizer`, `TrustedProxyPolicy`, `NormalizedForwardedHeaders`, `UntrustedForwardedHeaderException`)와 외부 URI (`ExternalOrigin`, `ExternalPrefix`, `ExternalUriBuilder`, `ExternalUriPolicy`), 테스트 | `W/proxy/`, `W/http/External*.java` (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 `server.forward-headers-strategy`(`app-bootstrap/.../config/server.yml`) |
| Nginx proxy lane `webNginxProxyTest`와 CI job (`pr-adapters.yml` → `web-nginx-proxy-contract`, `release.yml`) | `src/adapter/inbound/web/src/nginxProxyTest/` | `208077fd` | 위 forwarded header 라이브러리만 인증하던 lane |
| CORS/CSRF 프로필 (`CorsProfile`, `CsrfProfile`, `WebCorsPolicyValidator`, `WebCredentialMode`, `WebCsrfPolicyResolver`)과 테스트 | `W/security/` 의 해당 5개 파일 (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 `CorsSettings` + `SecurityConfig`. 같은 패키지의 security-context bridge는 유지 |
| cache 정책 카탈로그 (`WebCachePolicyCatalog`, `WebCachePolicy`, `WebVaryPolicy`, `WebCacheHeaders`)와 테스트 | `W/cache/` (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 `CacheControlFilter` |
| JSON mapper factory (`WebObjectMapperFactory`, `WebJsonProfile`, `BoundedJsonFactory`)와 테스트 | `W/json/` (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 Boot `JsonMapper` + `spring.jackson.*`. 스트리밍 encoder는 Boot `JsonMapper` bean을 받도록 변경 |
| OpenAPI customizer (`WebOpenApiCustomizer`, `WebOpenApiProfile`, `CursorSchemaContributor`)와 `WebOpenApiSnapshotTest` | `W/openapi/` 의 해당 3개 파일 (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 springdoc + `OpenApiContractConfig`. `CursorPage` 스키마는 이미 삭제된 커서 페이지네이션을 설명 |
| realtime 포트 (`ConnectionRegistryPort`, `DurableFanoutPort` 외 7개 타입)와 Redis 연결 레지스트리 (`RedisConnectionRegistryAdapter`) | `src/application-core/src/main/java/dev/caskeleton/application/realtime/`, `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/realtime/` | `208077fd` | 소비자 0 (websocket 정리 후 호출자 없음, bean 없음). `LiveEventReplayPort` 계열은 유지 |
| graphql `advanced/**` 전체 (15개 패키지, 130개, ~5,600줄) + 테스트 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/advanced/` | `208077fd` | 모든 진입점이 `GraphQlAdvancedModuleGuard`를 거치는데 그 플래그(`GraphQlAdvancedFeatureFlags`)를 바인딩하는 코드가 없다. Spring GraphQL/graphql-java SPI를 구현한 타입이 없어 SSE·RSocket·federation·incremental·GET·chaining은 이름만 있는 모델. `GraphQlReplaySource`·`GraphQlPersistedOperationAdminPort`는 구현체 없는 인터페이스, persisted 레지스트리가 기대는 `OperationalRecordStorePort`도 구현체 0. composition/incremental/bootstrap은 gate·등급 코드 |
| `backend.graphql.unsupported.*` 6개 키 (`GraphQlPlatformSettings.Unsupported`, `withUnsupportedCapability`, 검증기 분기) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformSettings.java`, `GraphQlPlatformStartupValidator.java` | `208077fd` | 켜면 부팅 실패만 한다. 구현하지 않은 기능에는 설정 키를 두지 않는다(AGENTS 기준 3) |
| `backend.graphql.cursor.key-ids` (`GraphQlPlatformSettings.Cursor`, `withCursorKeyIds`) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformSettings.java` | `208077fd` | 읽는 곳이 등록되지 않은 actuator 보고서뿐. 커서 서명은 라이브러리(`HmacGraphQlCursorCodec`)를 서비스가 직접 조립한다 |
| `GraphQlPlatformActuatorEndpoint`, `GraphQlPlatformConfigurationReport` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/` | `208077fd` | 빈으로 등록하는 곳이 없어 노출되지 않는 endpoint. 테스트만 호출 |
| `GraphQlClientPolicy`의 `persistedOperationOnly`·`maxResponseNodes`·`maxResponseBytes` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/policy/GraphQlClientPolicy.java` | `208077fd` | 아무도 읽지 않는 필드. `persistedOperationOnly=true`는 허용 목록 우회(fail-open)였다 |
| `GraphQlRequestErrorMapper`, `GraphQlSubscriptionExceptionResolver`, `GraphQlNullabilityContract`, `GraphQlFailureBoundary` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/` | `208077fd` | main 참조 0 |
| `GraphQlWireErrorMapper.mapRequestRejection` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapper.java` | `208077fd` | 호출처 0. 요청 단계는 `GraphQlPlatformRejectionMapper.map`을 직접 쓴다(Javadoc에 사실대로 적음) |
| parser 한도(`GraphQlParserLimitPolicy`, `GraphQlParserLimits`, `GraphQlParserOptionsFactory`, `GraphQlParserRejectedException`) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/` | `208077fd` | auto-configuration이 parser 기본값을 바꾸지 않는다. 테스트만 호출 |
| 응답 runtime budget(`GraphQlRuntimeBudgetTracker`, `GraphQlRuntimeBudget`, `GraphQlResponseByteLimiter`, `GraphQlResponseNodeCounter`, `GraphQlRuntimeBudgetExceededException`) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/` | `208077fd` | 유일한 소비자가 `advanced/incremental`. 요청 경로에 없음 |
| `GraphQlCancellation`, `GraphQlDeadlinePropagator`, `GraphQlResolverBudget`, `GraphQlOperationNameInterceptor`, `GraphQlOperationNamePolicy`, `GraphQlResolverCatalog`, `GraphQlResolverDescriptor`, `GraphQlExecutionProfileValidator` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/execution/` | `208077fd` | 등록·호출하는 곳이 없는 interceptor·검증기·신호. 익명 operation 거부는 `GraphQlOperationSelectionHandler`가 이미 한다 |
| `GraphQlClientPolicyManifest`, `GraphQlOperationCatalog`, `GraphQlOperationPolicy`, `GraphQlPolicyViolation`, `GraphQlUnknownClientProfileException`, `GraphQlUnknownOperationException`, `ResolverExecutionType`, `api/GraphQlClientProfileName` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/policy/`, `api/` | `208077fd` | 요청 경로가 참조하지 않는 카탈로그·manifest. 테스트만 호출 |
| schema gate·병렬 조립기(`GraphQlMappingInspectionGate`, `GraphQlOneOf*` 4개, `GraphQlSchemaAssembler`/`AssemblyResult`/`AssemblyException`, `GraphQlSchemaContract`, `GraphQlSchemaHash` 등 14개) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/schema/` | `208077fd` | 스키마 조립·mapping inspection·`@oneOf` 검증은 Spring GraphQL/graphql-java가 한다. 이 gate들은 어디에도 등록되지 않았다 |
| 병렬 HTTP 전송 모델(`GraphQlHttpExecutor`, `GraphQlHttpResponseFactory`, `GraphQlHttpStatusMapper`, `GraphQlMediaTypes`, `GraphQlAcceptHeader`, `GraphQlHttpProfile` 등 9개) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/http/` | `208077fd` | HTTP 처리는 Spring GraphQL handler가 한다. `GraphQlHttpExecutor`는 구현체 없는 인터페이스 |
| `GraphQlClientProfileResolver`, `GraphQlContextCleanup`, `GraphQlProfilerAccessPolicy` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/security/`, `observation/` | `208077fd` | 등록·호출하는 곳 없음 |
| testFixtures testkit(계약 suite 5개, JPA/Mongo 통합 fixture, `GraphQlStorageIntegrationEvidence`, `GraphQlPartialResponseFixture`)와 `GraphQlCrossModuleContractSuiteTest` | `src/adapter/inbound/graphql/src/testFixtures/java/dev/caskeleton/adapter/inbound/graphql/testkit/` | `208077fd` | 삭제한 병렬 HTTP 모델 위에서 자기 자신만 검사하던 증거 코드. 다른 모듈이 testFixtures를 쓰지 않는다. `GraphQlRequestContexts`만 남김 |
| 요청 멱등성 v1 모델 (`IdempotencyExecutor`(v1), `IdempotencyStorePort`(v1), `IdempotencyScope`, `IdempotencyContext`, `IdempotencyRecord`, `IdempotencyStatus`, `IdempotencyScopeMissingException`, `Sleeper`)와 `IdempotencyScopeTest`, `IdempotencyV2ContractSingularityTest` | `src/application-core/src/main/java/dev/caskeleton/application/idempotency/` | `208077fd` | W2-6 한 세대: V2(owner-safe store, scope digest, 대기 없는 경합 처리)가 정본. V2 타입은 `v2` 패키지에서 상위 패키지로 옮기고 `V2` 접미사를 뗐다(`IdempotencyExecutorV2`→`IdempotencyExecutor`, `IdempotencyStorePortV2`→`IdempotencyStorePort`) |
| JPA v1 멱등성 store (`IdempotencyStoreAdapter`, `IdempotencyClaimRepository`, `IdempotencyResponseObjectStore`, `mapper/IdempotencyRecordEntityMapper`, `postgresql/PostgreSqlIdempotencyClaimRepository`, `h2/H2IdempotencyClaimRepository`)와 `IdempotencyStoreAdapterTest`, `PostgreSqlIdempotencyUniqueScopeIntegrationTest`, lane `postgresqlIdempotencyUniqueScopeIntegrationTest` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/` (`idempotency/`, `postgresql/`, `h2/`) | `208077fd` | W2-6: v1 `jdbc` provider 구현. `postgresql` provider는 `PostgreSqlOwnerSafeIdempotencyStore`. unique-scope lane은 v1 제약 `uq_idempotency_scope`만 확인했다(마이그레이션 파일은 그대로) |
| bootstrap 멱등성 조립 (`IdempotencyConfig`, `IdempotencyComposition`, `PostgreSqlIdempotencyProviderConfig`, `IdempotencyProviderSettings`, `config/idempotency.yml`)와 `IdempotencyProviderSettingsTest`, `IdempotencyShippedAutoConfigurationTest`, `IdempotencyProviderScanCollisionTest` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/idempotency/` | `208077fd` | W2-6: executor를 여러 곳에서 만들고 lease/codec을 하드코딩했다. 이제 `IdempotencyProviderSelectionConfig`가 `IdempotencySettings` 하나로 한 번 만든다. 테스트는 `IdempotencyProviderCompositionTest`로 합침 |
| sample v1 멱등성 설정 (`SampleIdempotencySettings`) | `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/idempotency/` | `208077fd` | W2-6: v1 `ca-skeleton.idempotency.ttl` 바인딩. `SampleIdempotencyConfig`가 `ca-skeleton.capabilities.idempotency`를 직접 읽는다 |
| websocket command ledger (`idempotency/CommandReconciliation`, `CommittedResultLedger`, `WebSocketCommandKey`, `WebSocketCommandOutcome`, `core/WebSocketActorReference`, `core/WebSocketEndpointName`, testFixtures `testkit/fault/WebSocketFaultInjector`, `WebSocketFaultPoint`)와 `InMemoryCommittedResultLedger`, `WebSocketCommandIdempotencyTest`, `CommandLossRecoveryTest` | `src/adapter/inbound/websocket/src/` | `208077fd` | W2-6: v1 executor 전용 ledger. `core/` 두 타입은 ledger 삭제 뒤 참조가 없다. 멱등성이 필요하면 use case 안에서 `IdempotencyExecutor`를 쓴다 |
| GraphQL mutation 멱등성 (`GraphQlMutationIdempotencyInterceptor`, `GraphQlMutationIdempotencyContext`, `GraphQlIdempotencyKey`, `GraphQlIdempotencyConflictException`, `GraphQlCanonicalInput`, `GraphQlMutationFingerprint`, `GraphQlExtensionsPolicy`의 `idempotencyKey` 허용, `GraphQlMutationContractValidator.requireIdempotency`)와 `GraphQlMutationIdempotencyContextTest` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/` (`mutation/`, `http/`) | `208077fd` | W2-6: store에 연결된 적 없는 v1 executor 사용처. `idempotencyKey` extension은 이제 거부된다 |
| web v1 멱등성 fake (test `idempotency/InMemoryIdempotencyStore`, testFixtures `testkit/fault/FaultFixtureStore`) | `src/adapter/inbound/web/src/` | `208077fd` | W2-6: application-core testFixtures `testkit/InMemoryIdempotencyStore` 하나로 대체 |
| Import filters `MongoOptInAutoConfigurationImportFilter`, `GraphQlOffAutoConfigurationImportFilter`, `MessagingOffAutoConfigurationImportFilter` (+ `MessagingOffAutoConfigurationImportFilterParityTest`) and their `spring.factories` entries | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/`, `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/`, `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/` | `208077fd` | W4-4: off machinery for a jar shipped switched off. A capability is now absent unless selected; an explicit `enabled=false` excludes Boot's Mongo/GraphQL auto-configuration from the module's own environment post-processor |
| bootstrap capability settings `config/messaging.yml`, `config/graphql.yml`, `config/httpclient.yml`, `config/fileserver.yml`, the Mongo block of `config/persistence.yml`, `spring.servlet.multipart` in `application.yml`, `app.messaging.broker` in `application-local.yml` | `src/app-bootstrap/src/main/resources/` | `208077fd` | W4-4: moved into the owning modules (`config/<capability>.yml`, loaded at lowest precedence by each module) |
| RabbitMQ broker settings (`BrokerSettings` `addresses`/`publisher-confirms`/`publisher-returns`/`mandatory`/`confirm-timeout`/`auto-ack`/`prefetch`/`quorum-queues`, `BrokerSettings.RABBITMQ`, the compiler and key-validator Rabbit branches) and the RabbitMQ YAML example | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/`, `docs/messaging/configuration-reference.md` | `208077fd` | W4-4 (criterion 3): the keys bound with no transport behind them; `type: rabbitmq` and Rabbit keys now fail startup naming the key |
| bootstrap tests for shipped-and-switched-off capabilities: `MongoShippedCompositionContractTest` (moved to the Mongo leaf as `MongoReactiveDriverAbsenceTest`), `MessagingMembershipQualificationTest`, systemTest `GraphQlShippedAndGatedTest`; the Mongo/GraphQL/messaging cases of `ShippedRuntimeFacadePresenceTest`, the HTTP client/Kafka cases of `OptionalAdapterBeanGatingTest` and `BootstrapCapabilityReachabilitySystemTest` | `src/app-bootstrap/src/test/`, `src/app-bootstrap/src/systemTest/` | `208077fd` | W4-4: absent from the default composition is the off state; each leaf proves present = on and `enabled=false` = off itself |
| `JpaOffAutoConfigurationImportFilter`, `DataSourceRequirement`과 `DataSourceRequirementTest` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/`, `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/jpa/` | `208077fd` | W4-2: JPA를 싣지 않는 조립에서는 Boot의 관계형 자동 설정이 classpath에 없어 꺼진다. 끄는 장치 불필요 |
| `JpaPlatformAutoConfiguration`(플랫폼 조립 factory), `PersistenceJpaRootAutoConfiguration`, `JpaPlatformRuntimeAutoConfiguration`, `MigrationStartupConfig`와 `JpaPlatformAddonAssemblyTest`, `PersistenceJpaRootAutoConfigurationOrderingTest` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/`, `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/jpa/` | `208077fd` | W4-2: persistence-jpa `startup.JpaStartupAutoConfiguration` 하나로 합침. 보고서 조립은 `JpaPlatformReport.read`/`platformCapabilities` |
| `DistributedLockConfig`와 `DistributedLockConfigTest` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/lock/`, `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/lock/` | `208077fd` | W4-1: `distributedLockProvider` bean을 persistence-jpa `DistributedLockPersistenceConfig`로 옮김(테스트도 그쪽에 합침) |
| `DisabledMessagingSentinelAutoConfiguration` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/messaging/` | `208077fd` | W4-1: relay 스케줄러가 `OutboxMessagePublishPort` bean이 있을 때만 생기므로 대역 publisher가 필요 없다 |
| `OutboxRelayBrokerRequirementValidator`와 테스트 | `src/app-bootstrap/src/{main,test}/java/dev/caskeleton/bootstrap/autoconfigure/outbox/` | `208077fd` | W4-1: 발행 포트가 없으면 스케줄러 자체가 없어 PENDING 행을 DEAD로 소진할 경로가 없다 |
| `RuntimeSafetySettings.migrationOnStartup` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/settings/RuntimeSafetySettings.java` | `208077fd` | W4-2: 읽는 곳이 persistence-jpa뿐. 키 `ca-skeleton.runtime.migration-on-startup`은 그 모듈 기본 설정으로 이동 |
| systemTest H2 도달성 케이스 3개(lock/outbox/PostgreSQL 멱등성)와 `ShippedCompositionHarness.allOffWithH2`, `ShippedRuntimeFacadePresenceTest`의 JPA 케이스 | `src/app-bootstrap/src/systemTest/java/dev/caskeleton/bootstrap/activation/`, `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/activation/ShippedRuntimeFacadePresenceTest.java` | `208077fd` | W4-2: 기본 조립이 JPA를 싣지 않는다. 같은 증명은 persistence-jpa `PersistenceJpaCapabilityAssemblyTest` |
| 모듈별 설정 로더 `HttpClientDefaultsEnvironmentPostProcessor`, `FileserverDefaultsEnvironmentPostProcessor`, `NotificationDefaultsEnvironmentPostProcessor`, `MessagingDefaultsEnvironmentPostProcessor`와 각 `spring.factories` | `src/adapter/outbound/httpclient/`, `src/composition/fileserver-platform/`, `src/composition/notification-platform/`, `src/adapter/outbound/messaging-kafka/` | `208077fd` | W4 병합: 설정 파일을 `config/module-defaults/<모듈>.yml`로 옮기고 support의 `ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. support에 닿지 않는 persistence-mongo·graphql만 자기 EPP가 `config/<이름>.yml`을 읽는다 |
| `DisabledOutboxMessagePublisher`(outbox 대역 publisher) | `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/outbox/` | `208077fd` | W4 병합: 대역이 있으면 relay 스케줄러가 켜져 모든 발행이 실패하고 PENDING 행이 DEAD로 소진된다. broker가 비어 있고 canonical transport도 없으면 기동을 거부한다 |
| bootstrap `config/persistence.yml`, `config/outbox.yml`, `config/redis.yml`, `config/ratelimit.yml`와 그 import 줄, 기본 조립의 `cache-redis`·`redis-runtime`·`adapter:outbound:messaging` 의존성 | `src/app-bootstrap/` | `208077fd` | W4 병합: 설정은 persistence-jpa·cache-redis 모듈 기본 설정으로, 의존성은 `app-bootstrap/build.gradle`의 주석 한 줄 목록으로 |
| `AutoConfigurationReachabilityParityTest.offImportFiltersReferenceCurrentBootCandidates`와 stale-target 검사 | `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/` | `208077fd` | W4 병합: 검사할 off import filter가 남아 있지 않다 |
| `MasterSwitch`, `MasterSwitchParser`, `MasterSwitchParseResult`(shared-contract `activation` 패키지 전체)와 `MasterSwitchParserTest` | `src/shared-contract/src/main/java/dev/caskeleton/shared/activation/`, `src/shared-contract/src/test/java/dev/caskeleton/shared/activation/` | `208077fd` | W4-5: 모든 capability를 한 jar에 싣고 스위치로 끄던 장치의 SSOT. 이제 capability는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고르고, 있는 모듈은 자기 `enabled` 키(기본 `true`)로만 끈다 |
| bootstrap `activation` 패키지: `MasterSwitchEnvironmentPostProcessor`, `CapabilityDependencyValidator`, `CapabilityDependencyEnvironmentValidator`, `CapabilityDependencyStartupCheck`, `AdapterActivationAutoConfiguration`, `AdapterActivationEndpoint`(`/actuator/adapteractivation`), `AdapterActivationReport` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/activation/` | `208077fd` | W4-5: 스위치 값을 정규화하고, 켠 capability가 꺼진 의존을 가리키면 기동을 거부하고, 스위치 상태를 endpoint로 보고하던 코드. capability 사이 의존은 이제 build 줄로 표현한다(알림·파일 서버는 persistence-jpa 줄도 넣는다). 무엇이 조립됐는지는 Boot의 `conditions` endpoint로 본다(기본 노출 목록에는 없으니 `management.endpoints.web.exposure.include`에 추가). 같은 패키지의 `RuntimeEnvironmentProfileValidator`는 삭제가 아니라 `dev.caskeleton.bootstrap.runtime`으로 옮김 |
| `CaSkeletonApplication.AUTO_CONFIGURED_PACKAGES`(component scan 제외 정규식) | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/CaSkeletonApplication.java` | `208077fd` | W4-5: scan은 이제 `dev.caskeleton.bootstrap`만 본다. web은 `WebAdapterAutoConfiguration`, support는 `OutboundSupportConfig`를 자기 `AutoConfiguration.imports`로 공개하므로 제외할 패키지가 없다 |
| `StartupOrder.MASTER_SWITCH_NORMALISATION`, `StartupOrder.CAPABILITY_DEPENDENCY` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/startup/StartupOrder.java`(지금은 `adapter:outbound:support`의 `support.startup.StartupOrder`) | `208077fd` | W4-5: 순서를 정해 줄 post-processor·validator가 삭제됨 |
| `RedisActivationValidator`, `RedisActivationAutoConfiguration`과 `RedisActivationValidatorTest` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/redis/RedisActivationValidator.java`, `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/redis/RedisActivationValidatorTest.java`(W4 병합 중 cache-redis로 옮긴 뒤 삭제) | `208077fd` | W4-5: Redis를 기본으로 끈 채 싣던 시절의 활성화 가드. 이제 cache-redis 줄이 있으면 켜지고(`APP_REDIS_ENABLED` 기본 `true`), `false`면 `RedisCapabilityConfig`·`RedisSdkAutoConfiguration`이 bean을 하나도 만들지 않는다 |
| `DatabaseReadinessGroupPostProcessor` | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/DatabaseReadinessGroupPostProcessor.java` | `208077fd` | W4-5: persistence-jpa `startup.JpaActivationEnvironmentPostProcessor`로 대체. 켜져 있으면 readiness에 `db`를 넣고, `APP_PERSISTENCE_JPA_ENABLED=false`면 Boot의 JDBC·Hibernate·Spring Data JPA·Flyway 자동 설정까지 빼서 완전히 끈다 |
| 끄는 장치 테스트: `AdapterActivationEndpointTest`, `AdapterActivationReportShapeTest`, `CapabilityDependencyValidatorTest`, `MasterSwitchRegistryContractTest`, `ShippedRuntimeFacadePresenceTest`, `DisabledAdapterSentinelTest`, `OptionalAdapterBeanGatingTest`, `AutoConfigurationReachabilityParityTest`, `RedisOptionalityContractTest`, persistence-jpa `OutboxMasterSwitchWiringContractTest` | `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/{activation,contract}/`, `src/app-bootstrap/src/test/java/dev/caskeleton/adapter/outbound/`, `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/` | `208077fd` | W4-5: 기본 jar에 실린 capability가 꺼져 있음을 증명하던 테스트. 이제 기본 조립에 없는 것이 꺼진 상태이고, 각 leaf가 "있으면 켜짐 / `enabled=false`면 꺼짐"을 스스로 증명한다 |
| systemTest `activation/AdapterActivationInventory`, `DependencyErrorStartupContractTest`, `FiveAdapterOffInventoryTest`, `MasterSwitchEnvironmentPostProcessorTest` | `src/app-bootstrap/src/systemTest/java/dev/caskeleton/bootstrap/activation/` | `208077fd` | W4-5: 다섯 어댑터를 모두 싣고 끈 기동과 의존 오류 메시지를 확인하던 lane. 기본 조립 기동은 systemTest `composition/DefaultCompositionBootTest`(local/dev/prod, capability bean 0개)가, capability별 켜짐/꺼짐은 각 leaf의 activation 테스트가 본다 |
| bootstrap `GraphQlDeploymentModeRegistryParityTest` | `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/activation/GraphQlDeploymentModeRegistryParityTest.java` | `208077fd` | W4-5: 규칙(deployment mode ↔ runtime profile)이 graphql `GraphQlPlatformStartupValidator`로 옮겨 가면서 테스트도 graphql leaf의 같은 이름 테스트로 옮김 |
+1 -3
View File
@@ -1,9 +1,7 @@
# Fileserver configuration
Every key below lives under `app.fileserver-platform` (environment form
`APP_FILESERVER_PLATFORM_*`). That namespace is the HTTP platform's alone: `app.fileserver.*`
belongs to the R2 tabular publication capability and `app.file-export.*` to the R1 CSV export, and
the three are deliberately separate so switching one on cannot switch on another.
`APP_FILESERVER_PLATFORM_*`).
While `app.fileserver-platform.enabled` is false none of these keys is bound at all — the
auto-configuration that binds them is not processed — so a malformed value in a block nobody
+1
View File
@@ -64,6 +64,7 @@ port rather than the public one.
| `416` | unsatisfiable Range; carries the real length |
| `422` | digest, signature, or scanner rejection |
| `429` | transfer admission or rate limit |
| `460` | tus `Upload-Checksum` does not match that request's bytes; the chunk is discarded and the offset does not move |
| `503` | storage or scanner unavailable |
| `504` | downstream timeout |
| `507` | out of storage capacity |
+4 -15
View File
@@ -20,7 +20,6 @@ that does not exist, so a level can never outlive the test that justified it.
|---|---|---|
| Local filesystem (ext4) content store | Stable | `fileserver-local-ext4-contract` |
| Spring MVC transport (raw, multipart, batch, download) | Stable | `fileserver-http-contract` |
| Spring WebFlux transport | Experimental | `fileserver-http-contract` |
| Path, filename, range, and problem-detail hardening | Stable | `fileserver-security-suite` |
| Bounded-memory transfer | Stable | `fileserver-bounded-memory` |
| Application and architecture invariants | Stable | `fileserver-unit-and-architecture` |
@@ -37,21 +36,11 @@ that does not exist, so a level can never outlive the test that justified it.
| Full release verification | Stable | `fileserver-full-verification` |
| HTTP resumable uploads draft-12 | Experimental | `fileserver-http-contract` |
### Why WebFlux is Experimental, not Stable
### WebFlux transport removed
The reactive router, handlers and readers are now wired: `FileserverReactiveConfiguration`
contributes the scheduler, the handlers and a `RouterFunction` bean under
`@ConditionalOnWebApplication(type = REACTIVE)` plus the platform master switch. Previously nothing
built them at all, so "Stable" described the source tree rather than a running server.
It stays `Experimental` because the shipped composition cannot select it. `adapter:inbound:web`
also puts `DispatcherServlet` on the classpath — deliberately, so adding `spring-webflux` does not
drag a second embedded server onto the runtime — and Boot's application-type deduction therefore
resolves SERVLET. A fork that removes the servlet stack and adds a reactive server gets working
routes without editing any Fileserver code; the shipped template does not exercise that path.
Raising it to Stable requires a contract job that drives the routes over a running reactive server
rather than through direct construction.
The reactive router and handlers (`web.fileserver.reactive`) were removed on 2026-09-25 (D4: the
template is servlet on virtual threads). The shipped composition could never select them — the web
leaf puts `DispatcherServlet` on the classpath, so Boot resolves SERVLET.
## Explicitly not claimed
+10 -9
View File
@@ -12,18 +12,19 @@ production deployment must decide has either no default or an unusable one, and
| Property | Type | Default | Environment |
|---|---|---|---|
| `app.httpclient.enabled` | boolean | `false` | `APP_HTTPCLIENT_ENABLED` |
| `app.httpclient.enabled` | boolean | `true` | `APP_HTTPCLIENT_ENABLED` |
Off is the shipped state and it is a structural one. `HttpClientPlatformAutoConfiguration` lives in
a package the composition root's component scan excludes, so while the switch is absent or false the
class is never processed and neither is anything it imports: no property is bound, and no transport
The module is on when present: a service adds `runtimeOnly project(':adapter:outbound:httpclient')`
to `app-bootstrap/build.gradle`, and the module's own `config/module-defaults/httpclient.yml` (loaded at the lowest
precedence by the support leaf's `ModuleDefaultsEnvironmentPostProcessor`) supplies `enabled: true`. Absent from the
build is the ordinary off state. `false` is the explicit off: `HttpClientPlatformAutoConfiguration`
is then never processed and neither is anything it imports — no property is bound, and no transport
provider, connection pool, TLS context, credential, thread, gateway or actuator endpoint exists. A
malformed HTTP client setting cannot fail the startup of a deployment that never wanted outbound
HTTP.
malformed HTTP client setting cannot fail the startup of a deployment that switched it off.
Anything that is not exactly `true` — `yes`, `1`, blank — leaves the platform off. Turning it on
with no client declared is a startup failure carrying `HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`: a
platform with nothing to call still holds transport providers and gateways no caller can reach.
Anything that is not exactly `true` — `yes`, `1`, blank — turns the platform off. On with no client
declared is a startup failure carrying `HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`: a platform with nothing
to call still holds transport providers and gateways no caller can reach.
## Declaring clients from the environment
-64
View File
@@ -1,64 +0,0 @@
# Migrating from `RestTemplate`
`RestTemplate` is permitted only inside `…httpclient.migration`; `RestTemplateBoundaryTest` enforces
that. New retry, Dynamic Target, and HTTP/3 capabilities are deliberately unreachable from the
migration path — a caller that wants them moves to a Named Client Profile.
## 1. Audit before changing anything
```java
RestTemplateInventory inventory = new RestTemplateInventoryScanner().scan(existingTemplate);
```
The inventory reports the request factory, message converters, interceptors, error handler, and URI
template handler, plus findings:
| Code | Severity | Meaning |
|---|---|---|
| `SIMPLE_REQUEST_FACTORY` | blocking | no connection pool; unsupported in production |
| `NO_MESSAGE_CONVERTERS` | blocking | the template cannot encode or decode a body |
| `NO_INTERCEPTORS` | warning | confirm where correlation and timeouts are applied |
| `TIMEOUTS_NOT_INTROSPECTABLE` | informational | declare timeouts explicitly on the target profile |
## 2. Bridge without changing behaviour
```java
RestClient client = new RestTemplateToRestClientAdapter().adaptChecked(existingTemplate);
```
`adaptChecked` refuses to migrate a template with a blocking finding. The bridge carries the
existing converters, interceptors, error handler, and URI handler across, so this step changes the
API and nothing else.
## 3. Move to a Named Client Profile
Turn the platform on with `APP_HTTPCLIENT_ENABLED=true` — it ships off, and while it is off none of
the settings below are bound — then declare the upstream as `app.httpclient.clients[N]` with its
`name` and an explicit base URL, transport, timeouts, pool, body limits, authentication, retry
policy, redirect policy, and TLS profile. Startup validation will tell you exactly which of those is
missing. See `docs/httpclient/configuration-reference.md` for the environment form.
## 4. Move to a typed client
```java
@HttpClientProfile("payment")
@HttpExchange("/payments")
public interface PaymentClient {
@PostExchange
@HttpOperationPolicy(
name = "create-payment",
idempotency = OperationIdempotency.IDEMPOTENCY_KEY_REQUIRED,
retryPolicy = "payment-write")
PaymentResponse create(
@RequestHeader("Idempotency-Key") String idempotencyKey, @RequestBody PaymentRequest request);
}
```
The interface fails startup validation unless it declares a profile, gives every method a stable
operation name and an explicit idempotency, supplies a key parameter when the operation requires
one, keeps a single execution model, and does not enable retry on a non-idempotent write.
## 5. Retire the template
Once no production package references `RestTemplate`, `RestTemplateBoundaryTest` keeps it that way.
+1 -1
View File
@@ -38,7 +38,7 @@ python3 ../scripts/verify-httpclient-docs.py
- [ ] Logical calls and attempts are separate metrics with no forbidden label.
- [ ] DNS, pool, TLS, reset, partial response, and HTTP/2 GOAWAY are reproducible.
- [ ] Thread, heap, direct memory, pool, and retry budget bounds hold.
- [ ] The support matrix, configuration reference, security guide, runbook, and migration guide match the code.
- [ ] The support matrix, configuration reference, security guide and runbook match the code.
## Experimental
+1 -3
View File
@@ -52,8 +52,6 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo
| `httpclient-webclient` | `…httpclient.webclient` | `…outbound.httpclient.webclient` |
| `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` |
| `httpclient-dynamic-target` | `…httpclient.dynamic` | `…outbound.httpclient.dynamic` |
| `httpclient-resttemplate-migration` | `…httpclient.migration` | `…outbound.httpclient.migration` |
| `httpclient-spring7-service-groups` | `…httpclient.spring7` | `…outbound.httpclient.spring7` |
| `httpclient-jetty-http3-experimental` | `…httpclient.http3` | `…outbound.httpclient.http3` |
| `httpclient-spring-boot-starter` | `…httpclient.autoconfigure` | `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` |
| `httpclient-testkit` | `…httpclient.testkit` | `…outbound.httpclient.testkit` (`testkit` source set) |
@@ -63,7 +61,7 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo
| Design assumption | Repository reality | Adaptation |
|---|---|---|
| Gradle Kotlin DSL, `build-logic` convention plugin | Groovy DSL, root `build.gradle` conventions, `LockMode.STRICT` dependency locking | Dependencies declared in `src/adapter/outbound/httpclient/build.gradle`; `gradle.lockfile` regenerated. |
| Spring Framework 6.2 baseline with 7.0 compatibility | Spring Boot 4.0.8 / Spring Framework 7.0 is the repository baseline | Common code targets the Spring 6.2 **API surface** (no 6.2-only or 7.0-only classes in common packages). The Spring 7 HTTP Service Group integration stays isolated in `…httpclient.spring7`, exactly as the design requires. |
| Spring Framework 6.2 baseline with 7.0 compatibility | Spring Boot 4.0.8 / Spring Framework 7.0 is the repository baseline | Common code targets the Spring 6.2 **API surface** (no 6.2-only or 7.0-only classes in common packages). The Spring 7 HTTP Service Group integration and the `RestTemplate` migration package were removed. |
| `settings.gradle.kts` module registration | Fail-closed registry | No registry change; leaf identity, gradle path, allowed dependencies unchanged. |
| Design §6.2 grades Apache HttpClient 5 as HTTP/2-capable | Spring's blocking factory drives Apache's **classic** client, which is HTTP/1.1 only; HTTP/2 lives in Apache's async client | `ApacheBlockingTransportProvider` declares HTTP/1.1 and rejects an HTTP/2 profile at startup. Blocking HTTP/2 is served by the JDK transport, measured by `NegotiatedProtocolContractTest`. |
| Design §28.1 names WireMock for stateful fixtures | WireMock's Jetty modules bind a different Jetty 12 ABI than the Boot-managed one this module already needs for HTTP/3, and fail at server start | `StatefulUpstream` provides path-keyed stateful responses on the existing fixture server; the WireMock dependency was removed rather than worked around with a shaded jar |
+2 -3
View File
@@ -10,7 +10,6 @@ proves it; anything the suite cannot prove is **Experimental** and says so.
| `RestClient` | Stable | Blocking execution | Bounded concurrency and an effective deadline are mandatory |
| `WebClient` | Stable | Reactive, streaming, SSE | No blocking work on the event loop |
| HTTP Service Client (`@HttpExchange`) | Default | Declarative typed client | Operation metadata is mandatory |
| `RestTemplate` | Migration only | Moving existing calls | No new profile or feature |
| Generic Exchange (H2) | Restricted | Dynamic method, path, body | Base URL and policy are immutable |
| Dynamic Target (H3) | Restricted | User-supplied URL | Separate SSRF policy; inherits no credential |
| Native engine | Internal | Engine-specific configuration | Never an application-facing API |
@@ -70,8 +69,8 @@ gives route-scoped pooling and Dynamic Target pinning, JDK gives HTTP/2.
This repository's Spring Boot 4.0 baseline pins Spring Framework 7, so a real 6.2 runtime cannot be
resolved here. `spring62CompatibilityTest` therefore verifies the **API surface**: the common
packages must not reference any Spring 7-only type, and `org.springframework.web.service.registry`
is confined to `…httpclient.spring7`. Executing the suite against an actual 6.2 distribution
packages must not reference any Spring 7-only type, and no class uses
`org.springframework.web.service.registry`. Executing the suite against an actual 6.2 distribution
requires a host project on that line. This limitation is stated rather than hidden behind a passing
check.
+3 -1
View File
@@ -1,6 +1,8 @@
# Experimental Promotion Checklist
`ExperimentalPromotionGate` evaluates this checklist. Every technical item, then the ADR.
A reviewer evaluates this checklist. Every technical item, then the ADR. (The
`ExperimentalPromotionGate` class that encoded it in main code was removed on 2026-09-25; nothing
called it.)
## Technical evidence
+15 -15
View File
@@ -1,22 +1,22 @@
# Experimental Support Matrix
Everything here is off unless its `backend.jpa.experimental.*` flag is explicitly true, and none of
it is part of the Stable composition.
Experimental code is library code in `dev.caskeleton.adapter.outbound.persistence.experimental`.
Nothing composes it and no setting turns it on: a deployment that wants one of these creates the
entry point in its own adapter code, and that call is the opt-in. None of it is part of the Stable
composition, and `JpaModuleBoundaryTest` keeps Stable packages from depending on it.
| Feature | Flag | State |
|---|---|---|
| Shared-schema multi-tenancy (column) | `backend.jpa.experimental.multitenancy-column` | Experimental |
| PostgreSQL RLS multi-tenancy | `backend.jpa.experimental.multitenancy-rls` | Experimental |
| Schema-per-tenant | `backend.jpa.experimental.multitenancy-schema` | Experimental |
| Database-per-tenant | `backend.jpa.experimental.multitenancy-database` | Experimental |
| Consistency-aware read replica | `backend.jpa.experimental.read-replica` | Experimental |
| Jakarta Persistence 4.0 lane | `backend.jpa.experimental.jakarta-persistence-4` | Experimental |
| Hibernate ORM 8 lane | `backend.jpa.experimental.hibernate-8` | Experimental |
| PostgreSQL 19 lane | `backend.jpa.experimental.postgresql-19` | Experimental |
| Feature | Entry point | Evidence (PostgreSQL lane unless noted) | State |
|---|---|---|---|
| Shared-schema multi-tenancy (column) | `tenant.TenantContext`, `tenant.TenantAwareRepositoryGuard` | `TenantColumnIsolationTest` | Experimental |
| PostgreSQL RLS multi-tenancy | `rls.RlsTenantSessionBinder`, `rls.RlsPolicyVerifier` | `RlsIsolationFailureTest` | Experimental |
| Schema-per-tenant | `schema.SchemaMultiTenantConnectionProvider`, `schema.SchemaTenantMigrationOrchestrator` | `SchemaTenantMigrationContractTest` | Experimental |
| Database-per-tenant pool budget | `database.TenantDataSourceRegistry`, `database.TenantPoolBudget` | `TenantPoolCapacityContractTest` | Experimental |
| Consistency-aware read replica | `replica.ConsistencyAwareDataSourceRouter` (you implement `ReplicaLagMonitor`) | `ReadAfterWriteRoutingContractTest` | Experimental |
| Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | none — probes in `.github/workflows/jpa-next.yml` record `NOT_EXECUTABLE` | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest` (unit-lane version canaries) | Not executable |
Presence on the classpath is not consent. `ExperimentalFeatureGate` fails startup when a module is
present and its flag is not set, because an experimental module can arrive transitively and a
tenant-isolation feature that switched itself on would be the worst possible default.
The `backend.jpa.experimental.*` flags and `ExperimentalFeatureGate` that used to front these were
removed on 2026-09-25: no code read the flags from configuration, so setting one did nothing, and
the gate only checked a map the caller built itself.
## Known constraints
+9 -7
View File
@@ -18,8 +18,10 @@ whichever instance started first.
## Validation fails closed and never repairs
`FlywayValidationGate` throws `SchemaMismatchException` on a checksum mismatch, a missing migration,
or a schema Hibernate disagrees with. It never calls `repair`.
At startup Flyway's own validation (and Hibernate `ddl-auto=validate`) refuses a checksum mismatch,
a missing migration, or a schema Hibernate disagrees with. Nothing in the application calls
`repair`. In tests, the testkit's `FlywayValidationGate` turns a failed `ValidateResult` into
`SchemaMismatchException`; the migration contract tests use it.
Repair rewrites the schema history table to match whatever scripts are on disk. That resolves the
symptom by deleting the evidence: a checksum mismatch means the deployed script differs from the
@@ -40,15 +42,15 @@ one by default. The migration therefore needs a companion configuration:
executeInTransaction=false
```
`ConcurrentIndexMigrationInspector` fails validation without it, and additionally requires the
migration to contain nothing else. A failed concurrent build leaves an invalid index behind;
The testkit's `ConcurrentIndexMigrationInspector` checks a script for this in a migration test
(nothing checks it at startup), and additionally requires the migration to contain nothing else. A failed concurrent build leaves an invalid index behind;
recovering is a single `DROP INDEX` when the migration did nothing else, and a manual reconstruction
of partial state when it did.
An invalid index is not merely useless — the planner ignores it while every write still maintains
it. `FailedConcurrentIndexRecovery` reports them with the statement to run, and deliberately does
not drop them: an invalid index can also mean a build is still running, and the two are
indistinguishable from the catalog alone.
it. [runbooks.md](runbooks.md) has the query that finds them. Nothing drops them automatically: an
invalid index can also mean a build is still running, and the two are indistinguishable from the
catalog alone.
## Upgrade scenarios
+34 -37
View File
@@ -2,55 +2,52 @@
Design §37. What is measured, and what must never appear in a measurement.
## What is emitted by default
Nothing JPA-specific. No composition constructs a `MeterRegistry`-backed observation for the
platform, and `SpringTransactionPort` records no transaction metric. The `jpa.transaction.*` meters
this page used to list (`duration`, `rollback`, `timeout`, `completion.unknown`) were produced by
`JpaTransactionObservation`, which nothing constructed; it was removed on 2026-09-25
(`docs/capability-status.md`). Transaction outcomes are visible through the shared persistence error
codes and the application's own metrics, not through a JPA meter.
## Query metrics — only when the caller asks
`jpa.query.duration` and `jpa.query.rows` are recorded by `MicrometerQueryObservation`, and only
when a service passes it to a library executor that accepts a `QueryObservation`
(`JpaStreamExecutor`, `HibernateBulkDmlExecutor`). The default is `NoopQueryObservation`. Rows are
measured as well as duration because a query that issues one statement and hydrates twenty thousand
rows is fast per statement and catastrophic per request — a duration metric alone reports it as
merely slow.
## Bounded tags, always
Every JPA metric carries exactly five tags: persistence unit, operation, query, outcome, failure
category. All five are registered identifiers, validated by `LowCardinality` at construction rather
than at the registry — so an unbounded value fails where it was introduced instead of surviving
until a dashboard stops loading.
Every meter `MicrometerQueryObservation` records carries exactly five tags: persistence unit,
operation, query, outcome, failure category (`JpaMetricTags`). All five are registered identifiers,
validated by `LowCardinality` at construction rather than at the registry — so an unbounded value
fails where it was introduced instead of surviving until a dashboard stops loading.
Never a tag: entity id, tenant id, SQL parameter, exception message, JDBC URL. Each is unbounded, so
each creates a time series per row or per failure; several are also the data the platform keeps out
of logs, which a metrics backend would store just as durably and export just as widely.
## Transaction metrics
| Meter | Why it exists |
|---|---|
| `jpa.transaction.duration` | the baseline |
| `jpa.transaction.rollback` | rollback rate by failure category |
| `jpa.transaction.timeout` | timeouts, distinct from other rollbacks |
| `jpa.transaction.completion.unknown` | its own counter, deliberately |
Completion-unknown gets a separate counter rather than being folded into failures. It is the one
outcome that means a human has to look: every other failure is a transaction that definitely did not
happen, while this one is a transaction that may have.
## Query metrics
`jpa.query.duration` and `jpa.query.rows`. Rows are measured as well as duration because a query
that issues one statement and hydrates twenty thousand rows is fast per statement and catastrophic
per request — a duration metric alone reports it as merely slow.
## Retry metrics
Attempts are metrics, not warnings. Optimistic conflicts and serialization failures are the expected
cost of concurrency; logging each at WARN pages someone for a system working as designed, after
which the retry log gets filtered out and takes the genuinely interesting entries with it.
`jpa.retry.attempt`, `jpa.retry.attempts` (distribution per operation), `jpa.retry.exhausted`.
## Query names in SQL
`NamedStatementInspector` prefixes each statement with its registered query name as a SQL comment,
which travels into `pg_stat_activity`, `auto_explain`, and the slow-query log. Without it, "which
endpoint issues this query" is answered by grepping the codebase for fragments of SQL.
`JpaRepositoryFragmentSupport` sets the registered query name as the `org.hibernate.comment` hint;
Hibernate writes it into the SQL only when `hibernate.use_sql_comments=true`. The alternative is
`NamedStatementInspector`, which prefixes a statement with the query name bound by
`JpaStreamExecutor`, `JpaKeysetQuerySupport` or `JpaRepositoryFragmentSupport.observing(..)`.
Neither is on by default: a deployment enables the inspector with
`spring.jpa.properties.hibernate.session_factory.statement_inspector=dev.caskeleton.adapter.outbound.persistence.hibernate.NamedStatementInspector`.
The comment then travels into `pg_stat_activity`, `auto_explain`, and the slow-query log. Without it,
"which endpoint issues this query" is answered by grepping the codebase for fragments of SQL.
## Diagnostics
`SqlDiagnosticRedactor` removes string literals, numbers, and anything email-shaped before SQL
reaches a log. Redaction is blunt on purpose: preserving "harmless" values would require knowing
which columns hold personal data.
`SqlDiagnosticRedactor.redact(sql)` removes string literals, numbers, and anything email-shaped. It is
a utility for code that is about to log SQL; nothing in the platform logs SQL through it. Redaction
is blunt on purpose: preserving "harmless" values would require knowing which columns hold personal
data.
## The actuator endpoint
-22
View File
@@ -17,28 +17,6 @@ single field with a magic zero is how "no wait" becomes "wait forever".
the first leaves the transaction alive and the caller in control; the second has already been rolled
back by the server.
## Work claims
`FOR UPDATE SKIP LOCKED` is reachable only through a registered `WorkQueueName`, never as a
repository flag. It deliberately returns an incomplete view of the table: correct for handing
disjoint work to competing workers, silently wrong for anything that needs to see every matching
row. A registered claim statement must skip locked rows and impose a deterministic `ORDER BY`.
## Upserts
`INSERT ... ON CONFLICT ... RETURNING` under a registered `NativeWriteName` with a fixed conflict
target and update column set. The conflict target cannot be a bound parameter, so accepting one from
a caller would mean building SQL from input.
An upsert is the correct answer to a create race precisely because the database decides.
Read-then-write cannot be made correct: another transaction can commit between the read and the
write. `(xmax = 0) AS inserted` in the `RETURNING` list is what lets the platform report
insert-versus-update without a second query.
The executor flushes before and clears after: a native write is invisible to the Persistence
Context, so a pending managed change would otherwise overwrite it, and a managed entity loaded
beforehand would keep serving pre-upsert values.
## JSONB
`JsonDocument` carries a schema name and version alongside the payload. A JSONB column is schemaless
+4 -3
View File
@@ -4,9 +4,10 @@ Design §23-§28. How queries are chosen, bounded, and proven.
## Named queries
Every registered query carries a `QueryName`. It becomes the metric tag, the trace attribute, and
the SQL comment that appears in `pg_stat_activity` and the slow-query log — which is the only thing
that connects a statement on the server back to the use case that issued it. The format rejects raw
Every registered query carries a `QueryName`. It is the tag `MicrometerQueryObservation` records
under and the SQL comment that appears in `pg_stat_activity` and the slow-query log — which is the
only thing that connects a statement on the server back to the use case that issued it. Neither is on
by default; [observability.md](observability.md) says how a deployment turns each on. The format rejects raw
SQL for a reason: a metric tag built from a query string is unbounded by construction, and one built
from a parameterised value leaks row data into telemetry.
+13 -13
View File
@@ -29,7 +29,7 @@ This is the same adaptation already applied to the HTTP client platform
| Plan module | Repository home | Reason |
|---|---|---|
| `jpa-spring-boot-starter` | `:app-bootstrap` (`dev.caskeleton.bootstrap.autoconfigure.jpa`) | This repository's composition root owns wiring, startup validation, and actuator surface; an adapter leaf must not auto-configure itself. `AGENTS.md` assigns composition to `app-bootstrap`. |
| `jpa-spring-boot-starter` | `:adapter:outbound:persistence-jpa` (`…persistence.autoconfigure`, `…persistence.startup`) | Relational persistence is a capability module selected by one build line (`AGENTS.md` capability rules): the leaf registers its own auto-configuration, startup validation, actuator view and shipped settings, and the default composition does not carry it. Use-case assembly over its ports (the outbox relay) stays in `app-bootstrap`. |
| `jpa-testkit`, `jpa-testkit-postgresql`, `jpa-testkit-migration`, `jpa-testkit-queryplan` | `:adapter:outbound:persistence-jpa` `src/testkit/java/**/testkit` | The plan forbids production modules depending on the testkit. A source set whose dependencies are declared only on test configurations gives the same guarantee without a new Gradle project, and more than one lane consumes it. |
The package boundary is enforced by `JpaModuleBoundaryTest`. It holds a closed catalog of the
@@ -57,17 +57,17 @@ Root package: `io.backend.skeleton.jpa` → `dev.caskeleton.adapter.outbound.per
| `jpa-spring-data` | `…jpa.springdata` | `…persistence.springdata` |
| `jpa-querydsl` | `…jpa.querydsl` | `…persistence.querydsl` |
| `jpa-hibernate` | `…jpa.hibernate` (+ `.batch`, `.bulk`, `.stateless`) | `…persistence.hibernate` (+ same subpackages) |
| `jpa-postgresql` | `…jpa.postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.write`) | `…persistence.postgresql` (+ same subpackages) |
| `jpa-postgresql` | `…jpa.postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.write`) | `…persistence.postgresql` (+ same subpackages except `.write`, removed 2026-09-25) |
| `jpa-postgresql-copy` | `…jpa.postgresql.copy` | `…persistence.postgresql.copy` |
| `jpa-migration-flyway` | `…jpa.migration` | `…persistence.migration` |
| `jpa-auditing` | `…jpa.auditing` | `…persistence.auditing` |
| `jpa-auditing` | `…jpa.auditing` | none — removed; `…persistence.audit.AuditableEntity` is the one audit mechanism |
| `jpa-envers` | `…jpa.envers` | `…persistence.envers` |
| `jpa-cache-hibernate` | `…jpa.cache` | `…persistence.cache` |
| `jpa-observability` | `…jpa.observation` | `…persistence.observation` |
| `jpa-security` | `…jpa.security` | `…persistence.security` |
| `jpa-spring-boot-starter` | `…jpa.autoconfigure` | `dev.caskeleton.bootstrap.autoconfigure.jpa` |
| `jpa-spring-boot-starter` | `…jpa.autoconfigure` | `…persistence.autoconfigure`, `…persistence.startup` |
| `jpa-testkit*` | `…jpa.testkit` (+ `.id`, `.mapping`, `.lifecycle`, `.query`, `.fetch`, `.postgresql`, `.migration`, `.queryplan`, `.failure`, `.pool`, `.release`) | `…persistence.testkit` (+ same subpackages), `testkit` source set |
| `jpa-experimental/*` | `…jpa.experimental` (+ `.tenant`, `.rls`, `.schema`, `.database`, `.replica`, `.next`) | `…persistence.experimental` (+ same subpackages) |
| `jpa-experimental/*` | `…jpa.experimental` (+ `.tenant`, `.rls`, `.schema`, `.database`, `.replica`, `.next`) | `…persistence.experimental` (+ same subpackages except `.next`, removed 2026-09-25) |
The existing `…persistence.transaction` and `…persistence.postgresql` packages already hold this
leaf's `TransactionPort` implementation and PostgreSQL vendor composition. The platform types are
@@ -121,7 +121,7 @@ boundary the module map exists to hold.
|---|---|---|---|
| `TransactionCompletionEvidence` | `jpa-transaction` | `…persistence.api.transaction` | `TransactionCompletionUnknownException` (design §17.3 types the field) |
| `ConstraintCode` | `jpa-postgresql` | `…persistence.api.error` | `ConstraintViolationDetails` (design §22.4) |
| `SqlStateResolver`, `SqlExceptionSqlStateResolver` | `jpa-transaction` | `…persistence.api.error` | both the transaction module's commit classifier and the PostgreSQL translator |
| `SqlExceptionSqlStateResolver` | `jpa-transaction` | `…persistence.api.error` | the PostgreSQL translators |
The ArchUnit rule pack (`JpaArchitectureRules`, `EntityMappingCondition`, `EntityExposureCondition`)
is placed in the `testkit` source set rather than in `…persistence.security` production code. ArchUnit
@@ -136,10 +136,9 @@ showed it. Both are recorded here because the design text still reads the old wa
- **§17.2 commit ambiguity is not only SQLSTATE class `08`.** `pg_terminate_backend` on a backend
with a commit in flight reports `57P01` (`admin_shutdown`), not a connection-class state — and the
commit record may already be in the WAL when it arrives. `CommitFailureClassifier` now treats
`57P01`/`57P02`/`57P03` as completion-unknown alongside `40003`, class `08`, and transport breaks.
`CommitAmbiguityContractTest` asserts the SQLSTATE directly so the rule cannot silently narrow
again.
commit record may already be in the WAL when it arrives. The classifier that encoded this
(`CommitFailureClassifier`) was removed with the second transaction engine on 2026-09-25;
`PostgreSqlConcurrencyFailureContractTest` still pins the injection points.
- **Schema-per-tenant status must be read back, not inferred from the run.** `MigrateResult`'s
target version is empty for a tenant that was already current, so recording it reported migrated
tenants as unmigrated during a partial rollout. `SchemaTenantMigrationOrchestrator` now reads the
@@ -159,6 +158,7 @@ showed it. Both are recorded here because the design text still reads the old wa
`ddl-auto` never mutates a deployed schema.
- `CREATE INDEX CONCURRENTLY` requires an explicit non-transactional migration marker.
- Metric labels and ordinary logs never carry SQL parameters, entity IDs, tenant IDs, or PII.
- Experimental features (multi-tenancy, RLS, schema/database tenancy, read replica, JPA 4,
Hibernate 8, PostgreSQL 19) stay behind `backend.jpa.experimental.*` flags and never enter the
Stable composition.
- Experimental features (multi-tenancy, RLS, schema/database tenancy, read replica) are library code
a deployment constructs itself and never enter the Stable composition. JPA 4, Hibernate 8 and
PostgreSQL 19 are `NOT_EXECUTABLE` probes, not features. The `backend.jpa.experimental.*` flags
were removed on 2026-09-25: nothing read them.
+19 -16
View File
@@ -4,8 +4,8 @@ Operator procedures for the failures this platform is designed to surface rather
## A transaction reported completion unknown
**Signal:** `jpa.transaction.completion.unknown` incremented; a `CompletionUnknownRecord` in the
reconciliation channel.
**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.
@@ -14,31 +14,26 @@ reason.
**Procedure:**
1. Take the `transactionKey` from the record.
1. Take the idempotency key or operation id of the failed request.
2. Check the idempotency record for that key.
3. Check the business row the use case would have written.
4. Check the outbox for a corresponding event.
5. If all three agree the write happened, mark the record `COMMITTED` and stop.
5. If all three agree the write happened, stop — the request succeeded.
6. If all three agree it did not, the use case may be re-run.
7. If they disagree or are inconclusive, leave it `STILL_UNKNOWN` and escalate. An inconclusive
answer is a legitimate outcome; guessing is not.
A record with no `transactionKey` cannot be resolved automatically — use the operation name and
timestamp.
7. If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome;
guessing is not.
## Deadlock or serialization rate rising
**Signal:** `jpa.retry.attempt` rising; `jpa.retry.exhausted` non-zero.
**Signal:** `DB_DEADLOCK` / serialization failures rising in the persistence error codes.
Retries are expected. Exhaustion is not.
`SpringTransactionPort` does not retry, so each one reaches the caller.
1. Group `jpa.retry.attempt` by operation. A single operation dominating means a hot row or an
1. Group the failures by operation. A single operation dominating means a hot row or an
inconsistent lock order.
2. For deadlocks, check whether two operations take the same rows in opposite orders — that is a
code fix, not a tuning one.
3. For serialization failures under `SERIALIZABLE`, confirm the isolation is actually required.
4. Only then consider raising `maxAttempts`. A larger budget on a hot row converts a fast failure
into a slow one.
## Pool exhaustion
@@ -64,12 +59,20 @@ The deployment is running against a schema it was not built for. It failed close
## An invalid index exists
**Signal:** `FailedConcurrentIndexRecovery.invalidIndexes()` is non-empty.
**Signal:** this query returns rows.
```sql
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.
1. Confirm no build is currently running. An in-progress build looks identical in the catalog.
2. Run the reported `DROP INDEX CONCURRENTLY` outside a migration.
2. Run `DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;` outside a migration.
3. Re-apply the index migration.
The platform does not drop these automatically: on a rolling deploy every instance would race to
-2
View File
@@ -59,8 +59,6 @@ Refusing the runtime role `CREATE` closes the same route from the other side.
| sort field | part of ORDER BY | `SafeSortRegistry` allowlist |
| JSON path | part of the statement | registered `JsonPathName` |
| schema name | an identifier | registered `SchemaTenantRegistry` |
| upsert conflict target | an identifier list | registered `UpsertConflictTarget` |
| COPY table | an identifier | registered `RegisteredCopyStatement` |
| queue claim SQL | a whole statement | registered `WorkQueueDefinition` |
Values are always bound. Identifiers are always registered.
+17 -23
View File
@@ -31,7 +31,7 @@ it.
| PostgreSQL 16 | Stable | full contract suite, release lane (own matrix job) |
| PostgreSQL 17 | Stable | full contract suite, release lane (own matrix job) |
| PostgreSQL 18 | Stable | full contract suite, release lane (own matrix job) |
| PostgreSQL 19 | Experimental | [`jpa-next-postgresql19.yml`](../../.github/workflows/jpa-next-postgresql19.yml) — `NOT_EXECUTABLE`: no `postgres:19-alpine` is published, so no container of that major has been started; promotion requires an ADR |
| PostgreSQL 19 | Experimental | [`jpa-next.yml`](../../.github/workflows/jpa-next.yml) — `NOT_EXECUTABLE`: no `postgres:19-alpine` is published, so no container of that major has been started; promotion requires an ADR |
| H2 | Local convenience | **never** evidence of PostgreSQL behaviour |
Each major gets its **own release job**, because for a while it did not. The release lane passed
@@ -78,17 +78,18 @@ the difference visible instead of asserting a constant against itself. See
## Capability support levels
The levels are the ones `JpaPlatformAutoConfiguration.capabilities()` reports through the
`jpaplatform` actuator endpoint. Advanced and Experimental rows are library code a service calls
itself (`src/adapter/outbound/persistence-jpa/README.md` "라이브러리 API").
| Capability | Level |
|---|---|
| Full-transaction retry | Stable |
| Commit completion evidence | Stable |
| Keyset pagination | Stable |
| JDBC batch | Stable |
| Flyway schema gate | Stable |
| Runtime role verification | Stable |
| Observability | Stable |
| PostgreSQL native write (`ON CONFLICT`/`RETURNING`) | Advanced |
| PostgreSQL work claim (`SKIP LOCKED`) | Advanced |
| Commit completion evidence | Advanced |
| JDBC batch | Advanced |
| Observability (query metrics, redaction) | Advanced |
| PostgreSQL JSONB | Advanced |
| PostgreSQL array and range | Advanced |
| Bulk DML | Advanced |
@@ -113,24 +114,17 @@ Each row is a way the platform could pass its tests and still be wrong in produc
| `runtime-role-no-ddl` | gate | the application's own credential being able to alter or drop schema objects |
| `collection-fetch-pagination` | gate | a paged collection fetch silently reading the whole table and paginating in memory |
### The two audit mechanisms
### The audit mechanism
`audit/AuditableEntity` is the canonical one: `created_*`/`updated_*`, a 256-character actor,
stamped explicitly by the repository adapter. It is what the sample entities extend and what the
migrations were written for.
`audit/AuditableEntity` is the only one: `created_*`/`updated_*`, a 256-character actor, stamped
explicitly by the repository adapter. It is what the sample entities extend and what the migrations
were written for. A second, Spring Data listener-based mechanism (`auditing/AuditMetadata`) was never
composed and has been removed; `JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism` keeps it
from coming back on an entity.
`auditing/AuditMetadata` is a second, complete mechanism with different column names
(`modified_*`), a different actor length (64) and a different capture lifecycle (Spring Data
listeners). Nothing embeds it and nothing composes `JpaAuditingConfiguration`, which is why it is
listed as a candidate rather than as a capability: promoting it means choosing between reshaping it
to the canonical columns and writing a forward migration for the new ones, and that choice has not
been made. Until it is, an entity picks one mechanism or none — enforced on the production graph by
`JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism`.
Neither mechanism reaches a bulk or native update. Both stamp on an ordinary save — one in the
adapter, one on a managed entity's lifecycle — so a statement that goes straight to the database
leaves the audit columns showing the previous save. A bulk update of an audited entity must
therefore set the audit column in the statement, which
The mechanism does not reach a bulk or native update. It stamps on an ordinary save in the adapter,
so a statement that goes straight to the database leaves the audit columns showing the previous save.
A bulk update of an audited entity must therefore set the audit column in the statement, which
`JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit` checks over the production graph.
## Explicitly unsupported
+30 -41
View File
@@ -4,63 +4,52 @@ Design §15-§20. What owns a transaction, what may be retried, and what must ne
## The application service owns the boundary
Repository adapters do not open transactions. The use case does, through `TransactionPort` or
`JpaTransactionExecutor`, because the unit of work is a business decision and only the use case
knows where it starts and ends.
Repository adapters do not open transactions. The use case does, through `TransactionPort`,
because the unit of work is a business decision and only the use case knows where it starts and
ends. `SpringTransactionPort` is the only implementation: one pre-built `TransactionTemplate` per
mode over Spring's `PlatformTransactionManager`, every mode pinned to `READ_COMMITTED`.
| Call | Propagation | When |
|---|---|---|
| `inWrite` | `REQUIRED`, read-write | command default |
| `inRootWrite` | `REQUIRED`, read-write, rejects an ambient transaction before running | orchestration that must prove a physical commit |
| `inRead` | `REQUIRED`, read-only | query default |
| `inNew` | `REQUIRES_NEW`, read-write | outbox / audit / compensation that must commit on its own |
Open Session In View is off in every runtime profile. It is on by default in Spring Boot, which is
why `JpaDangerousConfigurationGuard` fails startup rather than trusting configuration review.
## Profiles
A `TransactionProfile` fixes propagation, isolation, timeout, read-only, and the retry budget. A
write profile must carry a positive finite timeout — the type refuses to represent one without —
because an unbounded write transaction holds a connection, its locks, and its row versions for as
long as one stuck statement takes.
`REQUIRES_NEW` is opt-in. It acquires a second physical connection while pinning the first, so a
profile using it must be paired with the pool-pressure evidence in design §38:
`REQUIRES_NEW` acquires a second physical connection while pinning the first, so the pool must
satisfy:
```text
maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1
```
## Retry is per use case, never per statement
## Nothing is retried by the port
`FullTransactionRetryCoordinator` re-enters the executor, which produces a new transaction and a new
Persistence Context for every attempt. That granularity is the whole point: an optimistic conflict
means the state the attempt computed against is no longer the committed state, so re-issuing the
same statement would compute the same wrong answer. The domain rules have to run again against
reloaded data.
`SpringTransactionPort` runs the action once. A failure rolls back and propagates, translated to
the shared persistence error codes where the SQLSTATE is known. A caller that decides to retry must
re-run the whole use case in a new transaction — never re-issue one statement — because an
optimistic conflict or a serialization failure means the state the attempt computed against is no
longer the committed state.
Retryable: serialization failure (`40001`), deadlock (`40P01`), optimistic conflict.
Not retryable: constraint violations, schema mismatch, query timeout, and anything unclassified.
Two additional refusals, independent of budget:
- An attempt that declared an irreversible external effect through `IrreversibleSideEffectContext`.
Rollback reverses database work only; an email or a card charge has already changed the world.
- Anything completion-unknown.
A second engine with named policies, deadline budgets, transaction-local timeouts and automatic
full-transaction retry (`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`,
`PolicyTransactionPort`) existed next to this one and was removed on 2026-09-25. Its last commit is
recorded in `docs/capability-status.md`.
## Completion unknown
`TransactionCompletionUnknownException` is never retried, and the type system enforces it twice:
`JpaFailureContext` refuses to represent a retryable completion-unknown failure, and the exception
rebuilds its context through the safe factory whatever it is handed.
`EvidenceAwareJpaTransactionManager` marks the phase `COMMITTING` immediately before delegating to
the provider commit and never after. If the network, the JVM, or the server dies inside that call,
the last thing written is "we asked, we do not know" — which is exactly the state that must not be
mistaken for a rollback.
A connection can break while a commit is in flight; the server may have committed and only the
acknowledgement was lost. `TransactionCompletionUnknownException` is never retried, and the type
system enforces it: `JpaFailureContext` refuses to represent a retryable completion-unknown failure.
The port itself retries nothing, so such a commit surfaces to the caller as a failure exactly once
(`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried`).
Recovery is reconciliation, not retry:
```text
record the transaction key -> check the idempotency record
-> check the business row
-> check the outbox
-> still undetermined? reconciliation queue
check the idempotency record -> check the business row -> check the outbox
-> still undetermined? escalate
```
`CompletionUnknownRecorder` writes that record through a channel outside the unknown transaction.
Writing it through the same connection would make the audit trail share the failure it documents.
+15 -42
View File
@@ -28,7 +28,7 @@ producing-service identity다.
`APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED` / `ca-skeleton.outbox.canonical-transport-enabled`은
기존 `outbox_event` writer/claim/status authority를 유지한 채 canonical row의 **transport만** platform
publish path로 보내는 compatibility gate다. 기본값은 `false`이며 `POLLING_V2`를 활성화하지 않는다.
publish path로 보내는 compatibility gate다. 기본값은 `false`이며 두 번째 relay를 만들지 않는다.
`true`일 때는 `OutboxAppendPort`가 `ValidatedIntegrationEvent`의 exact envelope bytes와 canonical
metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다.
@@ -135,9 +135,10 @@ app:
## Broker profile
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`이 어느 계열의 설정이 적용되는지
결정하며, 다른 계열의 키(Kafka 항목의 `prefetch` 같은)는 무시되지 않고 부팅 실패로 거절된다 —
무시하면 그 줄을 쓴 사람은 무언가가 적용됐다고 믿게 된다.
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`은 `kafka`만 받는다 — transport가
있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(`addresses`, `prefetch`, `quorum-queues` 등)와
`type: rabbitmq`는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라,
지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다.
### Kafka
@@ -160,30 +161,9 @@ app:
authentication-enabled: false # production이면 필수
```
### RabbitMQ
```yaml
app:
messaging:
brokers:
rabbit-primary:
type: rabbitmq
stable: true
production: false
addresses: [rabbit-1:5671]
publisher-confirms: true # stable에서 필수
publisher-returns: true # stable에서 필수
mandatory: true # stable에서 필수
confirm-timeout: 5s
auto-ack: false # 항상 금지
prefetch: 16
quorum-queues: true # durable work queue 필수
tls-enabled: false
authentication-enabled: false
```
`production: true`인 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
그렇지 않으면 `KafkaProfileValidator` / `RabbitProfileValidator`가 부팅을 거절한다. 위 예시가
`production: true`인 Kafka 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
그렇지 않으면 `KafkaProfileValidator`가 부팅을 거절한다. `app.messaging.broker`로 고를 수 있는 값은
`kafka`뿐이다. 위 예시가
`production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다.
## 보안
@@ -211,20 +191,13 @@ app:
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
## Experimental / Optional
기본값은 전부 `false`다.
```yaml
app:
messaging:
experimental:
kafka-share: false
pulsar: false
nats: false
bridge:
spring-cloud-stream: false
```
Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`,
`sasl.jaas.config`, `ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로
조용히 넘어가지 않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나
`authentication-enabled`를 켰는데 `app.messaging.security.<broker>`가 없을 때, security 항목은
있는데 `CredentialProvider` bean이 없을 때, 같은 브로커에 맞는 항목이 둘 이상일 때.
한계: truststore/keystore 설정 키가 없어 TLS는 JVM 기본 truststore를 쓰고, `MUTUAL_TLS`는 클라이언트
인증서를 제출할 수 없다(미지원).
## Backpressure
+3 -2
View File
@@ -27,8 +27,9 @@
`PublishResult` → `OutboxPublishOutcome`. registry에 leaf를 추가하는 변경이라 별도 커밋.
- golden contract 테스트: event/message ID, type, schema revision, partition/order/correlation/
causation/tenant/trace, payload digest, wire version이 bytes 단위로 보존되는지.
- 단일 publication authority: 기존 `OutboxPublicationAuthority` fence를 재사용해 writer/relay가
동시에 ACTIVE가 되지 않도록. **dual write/publish는 금지** — 한 business fact가 두 durable store와
- 단일 publication authority: writer/relay가 동시에 ACTIVE가 되지 않도록 하는 fence. 이 용도로 쓰려던
outbox V2의 `OutboxPublicationAuthority`는 한 번도 조립되지 않은 채 2026-09-25에 삭제됐으므로
(`docs/capability-status.md` "제거된 코드") cutover가 자기 fence를 새로 가져야 한다. **dual write/publish는 금지** — 한 business fact가 두 durable store와
두 relay로 나가는 상태가 cutover에서 가장 위험하다.
- 첫 cutover 범위는 **transport만** 교체(저장소는 기존 유지). storage migration은 shadow read →
authority switch → old backlog drain 순서로 별도 release.
+9 -48
View File
@@ -17,24 +17,22 @@ stopsAcceptingNewWorkDuringShutdown
**Experimental**은 아직 그 증명이 끝나지 않은 어댑터다.
현재 Experimental 어댑터는 없다. Kafka Share Group·Pulsar·NATS JetStream(Experimental), RabbitMQ,
Spring Cloud Stream bridge(Optional)는 SDK 없는 seam이거나 선택할 수 없는 상태여서 2026-09-25에
삭제했다(`docs/capability-status.md` 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다.
## 규칙
### 1. 기본 비활성
```yaml
messaging.experimental.kafka-share: false
messaging.experimental.pulsar: false
messaging.experimental.nats: false
```
새 Experimental 어댑터는 자기 활성화 플래그를 가지고 기본값은 `false`다.
활성화하지 않으면 validator가 `MessagingCapabilityUnavailableException`을 던진다.
Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다.
### 2. Stable 모듈이 Experimental 모듈에 의존하지 않는다
Gradle 의존 그래프로 강제된다. `messaging-spring-boot-starter`의 `allowed_dependencies`에
`messaging-kafka-share-experimental`, `messaging-pulsar-experimental`,
`messaging-nats-experimental`, `messaging-spring-cloud-stream-bridge`가 **없다**.
Gradle 의존 그래프로 강제된다. Experimental leaf는 `messaging-spring-boot-starter`의
`allowed_dependencies`에 넣지 않는다.
`verifyCleanArchitectureDependencies`가 위반을 빌드 실패로 만든다.
@@ -45,45 +43,8 @@ Experimental 어댑터는 브로커의 차이를 `MessagingCapabilities`로 표
### 4. 없는 기능을 광고하지 않는다
| 어댑터 | 광고하지 않는 것 | 이유 |
|---|---|---|
| Kafka Share Group | orderedStream, keyedOrdering, replay, brokerTransaction | 경쟁 소비자 + 개별 ack는 partition 순서를 유지할 수 없다 |
| Pulsar | brokerTransaction | Pulsar에 있지만 플랫폼 Contract Suite로 증명되지 않았다 |
| Pulsar (Shared) | keyedOrdering | round-robin 분배 |
| NATS JetStream | nativeDeadLetter | delivery limit 초과 시 terminate할 뿐 라우팅하지 않는다 |
| NATS JetStream | keyedOrdering | subject 기반 모델에 per-key 순서가 없다 |
`false`인 capability를 요구하는 profile은 startup에서 실패한다.
조용히 약화되지 않는다.
### 5. 명시적 거부
| 조합 | 결과 |
|---|---|
| Kafka Share Group + ordering != NONE | 거부 |
| Kafka Share Group + pause/resume | `MessagingCapabilityUnavailableException` |
| Pulsar Shared + ordering=KEY | 거부 (Key_Shared 필요) |
| Pulsar + ordering=DESTINATION | 거부 |
| NATS Core + AT_LEAST_ONCE | 거부 (JetStream 필요) |
| NATS ordered consumer + 경쟁 워커 > 1 | 거부 |
| NATS + ordering=KEY | 거부 |
## Spring Cloud Stream bridge
Experimental이 아니라 **Optional**이다. 위험이 다르다.
Stream은 자체 binder 설정을 소유하므로, binding이 destination profile이 모르는
serializer·error handling·acknowledgement mode를 조용히 획득할 수 있다.
따라서 브리지는 **플랫폼 보장에 의존하지 않는 destination에만** 허용한다.
```text
ordering scope 선언 → 거부
retry policy 선언 → 거부
dead letter 선언 → 거부
```
이 셋 중 하나라도 필요하면 native adapter를 쓴다. 거기서만 실제로 강제되기 때문이다.
Contract Suite로 증명하지 않은 capability는 `MessagingCapabilities`에서 `false`로 둔다.
`false`인 capability를 요구하는 profile은 startup에서 실패한다. 조용히 약화되지 않는다.
## 승격 조건
+1 -2
View File
@@ -3,8 +3,7 @@
## 배포 전 체크
```bash
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew verifyRuntimeModuleMembership --console=plain
./gradlew architectureCheck --console=plain
./gradlew checkstyleMain --console=plain
```
+4 -6
View File
@@ -107,13 +107,11 @@ message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째
broker의 최대 redelivery window보다 **길어야** 한다.
row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
## Debezium CDC 대안
## CDC 대안
polling relay 대신 WAL을 읽는다. polling interval과 lease 경합이 사라지지만
인프라와 그 자체의 실패 모드가 추가된다.
wire contract는 동일하다. `DebeziumOutboxEventRouter`가 polling relay와 같은 reserved header를
방출하므로 consumer는 어느 쪽이 발행했는지 구분할 수 없고, 전환은 배포 결정일 뿐 계약 변경이 아니다.
relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는
곳이 없어 2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). `messaging_outbox`의
`routing_key` 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다.
## Claim Check
+25 -47
View File
@@ -4,10 +4,12 @@
여기 없는 조합은 지원되지 않는다.
> **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된
> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. RabbitMQ가 Stable에서 내려온
> 이유가 이것이다 — 어댑터는 공유 contract 7개를 통과하고 `RabbitBrokerIT`가 실 컨테이너에서 정상
> 경로를 돌리지만, 이 저장소의 Stable 기준인 **장애 시나리오 증거**가 하나도 없다. 레인이 생겨
> 증거를 내면 등급은 코드 수정 없이 따라 올라간다.
> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. 레인이 생겨 증거를 내면 등급은
> 코드 수정 없이 따라 올라간다.
> **삭제된 어댑터.** RabbitMQ(선택할 수 없던 validator·설정 모음), Pulsar·NATS JetStream·Kafka Share
> Group(Experimental, SDK 없는 seam), Spring Cloud Stream bridge, Debezium outbox 매핑은 2026-09-25에
> 삭제했다. 복구 경로는 `docs/capability-status.md`의 제거 표에 있다.
> **인증 근거.** 이 표의 버전은 이 저장소의 컨테이너 레인이 실제로 실행한 이미지다. 이전 판은
> Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와
@@ -29,10 +31,7 @@
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|---|---|---|---|---|
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group은 Experimental |
| RabbitMQ | Experimental | 4.3.x | exchange/routing, publisher confirm, mandatory return, manual ACK, quorum queue, retry queue, DLQ | **현재 starter에서 선택 불가** — production `RabbitChannelPublisher`/transport bridge가 없어 `app.messaging.broker=rabbit`은 startup에서 거부된다. 장애 시나리오 증거도 아직 없음 |
| Pulsar | Experimental | 4.0 LTS + 4.2 | typed publish/consume, Shared, Key_Shared, schema | transaction 미승격, 기본 비활성 |
| NATS JetStream | Experimental | 2.14.x | stream, durable consumer, explicit ACK, dedupe, replay | native DLQ 없음(플랫폼이 대행), 기본 비활성 |
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group 미지원 |
| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 |
## Capability 매트릭스
@@ -40,27 +39,20 @@
`MessagingCapabilities`가 런타임에 선언하는 값이다. `false`인 기능을 요구하는 destination profile은
**startup에서 실패**하며, 조용히 약화되지 않는다.
| Capability | Kafka | Kafka Share | RabbitMQ | Pulsar | NATS JS |
|---|---|---|---|---|---|
| brokerAcknowledgement | O | O | O | O | O |
| replicationOrPersistenceEvidence | O | O | O | O | O |
| perMessageSettlement | O | O | O | O | O |
| batchSettlement | O | X | X | O | O |
| orderedStream | O | **X** | X | X | O |
| keyedOrdering | O | **X** | X | Key_Shared만 | X |
| replay | O | X | X | O | O |
| delayedDelivery | X | X | retry queue로 대행 | O | X |
| brokerTransaction | O | X | X | 미승격 | X |
| deduplicatedPublish | O | X | X | X | O |
| nativeDeadLetter | X | X | O | O | **X** |
| topologyManagement | O | X | O | O | O |
Kafka Share Group이 ordering 전부 `X`인 것은 설계 결정이다. share group은 개별 record를
경쟁 소비자에게 나눠주고 개별 ack하므로 partition 순서를 유지할 수 없다. ordered destination을
share group에 설정하면 `KafkaShareProfileValidator`가 거부한다.
NATS JetStream의 `nativeDeadLetter=X`도 마찬가지다. JetStream은 delivery limit 초과 시 메시지를
**terminate**할 뿐 어디로도 라우팅하지 않으므로, 플랫폼이 DLQ publish를 직접 수행한다.
| Capability | Kafka |
|---|---|
| brokerAcknowledgement | O |
| replicationOrPersistenceEvidence | O |
| perMessageSettlement | O |
| batchSettlement | O |
| orderedStream | O |
| keyedOrdering | O |
| replay | O |
| delayedDelivery | X |
| brokerTransaction | O |
| deduplicatedPublish | O |
| nativeDeadLetter | X |
| topologyManagement | O |
## 기능 등급
@@ -73,8 +65,6 @@ NATS JetStream의 `nativeDeadLetter=X`도 마찬가지다. JetStream은 delivery
| Batch / Manual settlement / Pause·Resume / Delayed / Replay 요청 | M2 |
| Broker transaction / partition / routing / subscription | M3 |
| Replay 실행 / Redrive / offset reset / purge / delete | M4 Admin |
| Kafka Share Group, Pulsar, NATS | Experimental |
| Spring Cloud Stream bridge | Optional |
## 무엇이 "Stable"을 증명하는가
@@ -82,7 +72,7 @@ Stable 등급은 두 가지를 **모두** 통과해야 한다. `CompatibilityMat
### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개)
Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
Kafka가 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다.
### 2. 실 브로커 인증 (Testcontainers)
@@ -92,7 +82,6 @@ Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결
| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit |
| `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) |
| `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 |
| `RabbitBrokerIT` | exchange가 confirm했는데 어떤 큐에도 바인딩되지 않은 publish가 **`REJECTED` + `UNROUTABLE`** 로 보고된다 |
| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 |
| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 |
@@ -137,7 +126,7 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
1. **Outbox `IN_FLIGHT` 고아 행** — lease 쿼리가 `PENDING`/`AMBIGUOUS`만 클레임 대상으로 봐서,
publish 도중 죽은 relay가 남긴 행이 lease 만료 후에도 영영 회수되지 않았다.
2. **Rabbit confirm 경합** — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
2. **Rabbit confirm 경합**(2026-09-25에 삭제된 Rabbit transport) — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
confirm이 먼저 도착하면 유실되고 호출자가 무한 대기했다.
둘 다 인메모리 double이 실제보다 관대해서 통과하고 있었다.
@@ -154,21 +143,10 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
- DLQ publish 확인 전 source ACK
## R1 compiler status
`adapter:outbound:messaging`의 contract/catalog/envelope compiler 군은 현재 **의도적으로 미배선**이다.
`DISABLED` + 빈 catalog/binding이 zero-resource 상태이며, 이 R1 compiler를 legacy
`MessagingConfig`에 연결해 Kafka ACK, wire compatibility, `ACTIVE_READY`, R2 qualification을
주장하지 않는다. 코드는 다음 세대 계약을 보존하지만 현재 채택 경로가 아니며, 실제 활성화는 별도 R2
composition/cutover에서 명시적으로 이뤄져야 한다.
### Optional mapping / bridge utilities
### Optional mapping utilities
- `messaging-cloudevents`는 starter runtime에 자동 편입되지 않는 **opt-in mapping utility**다.
내부 envelope와 CloudEvent 객체 사이의 제한된 profile mapping을 제공하지만 binary/structured
CloudEvents wire mode 전체를 구현하거나 임의 CloudEvents producer와의 1.0 interoperability를
인증하지 않는다.
- `messaging-spring-cloud-stream-bridge`는 현재 `ChannelSend` seam과 publish-evidence 판단을 제공하는
framework-neutral bridge contract다. Spring Cloud Stream `StreamBridge` dependency/auto-configuration은
제공하지 않으므로 shipped Spring Cloud Stream integration으로 분류하지 않는다.
- `messaging-claim-check`도 starter에 편입되지 않는 opt-in utility다.
@@ -12,7 +12,6 @@ ca-skeleton:
topology: REPLICA_SET
production: true
stable-api-strict: true
consistency-default: PRIMARY_MAJORITY
server-selection-timeout: 3s
connect-timeout: 2s
socket-read-timeout: 5s
@@ -21,7 +20,5 @@ ca-skeleton:
pool-max-size: 40
pool-max-wait-time: 500ms
uuid-representation: STANDARD
decimal-representation: DECIMAL128
runtime-auto-create-indexes: false
tls-required: true
authentication-required: true
+6 -4
View File
@@ -1,8 +1,9 @@
# Advanced — CSFLE and Queryable Encryption
**Capabilities:** `MongoCapability.CSFLE`, `MongoCapability.QUERYABLE_ENCRYPTION`
**Properties:** `ca-skeleton.persistence-mongo.advanced.csfle.enabled`,
`ca-skeleton.persistence-mongo.advanced.queryable-encryption.enabled`
**Enablement:** library API, no configuration property. The service's own adapter constructs the
entry point with a `MongoAdvancedCapabilityGuard` built from `MongoAdvancedCapabilityFlags` that
enables the capability; construction is refused otherwise.
**Status:** Advanced.
## Requirements
@@ -18,7 +19,8 @@
`MongoCsfleProfile` binds a collection to its `MongoCsfleFieldPolicy` list, a key vault
`MongoCredentialReference` and the key vault namespace. `MongoCsfleClientFactory` builds the encrypted
client; `MongoDataKeyResolver` resolves data keys.
client settings. Data-key selection is the adopter's: `MongoCsfleFieldPolicy.keyAlias()` is the
alias the driver resolves against the key vault.
`MongoCsfleMode`:
@@ -87,5 +89,5 @@ an outage.
Per [ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md), promotion requires the
real KMS and key vault, plus negative cases that fail closed: wrong key, missing permission, rotation
mid-operation (`MongoAtlasCapabilityContractSuite.kmsFailureModes`). A local key provider certifies
mid-operation. A local key provider certifies
none of these — it never rejects anything.
-63
View File
@@ -1,63 +0,0 @@
# Advanced — GridFS compatibility and migration
**Capability:** `MongoCapability.GRIDFS_COMPATIBILITY`
**Property:** `ca-skeleton.persistence-mongo.advanced.gridfs-compatibility.enabled`
**Status:** Advanced, compatibility only. Decision D-14.
## Position
GridFS is a **compatibility adapter for files that already exist there**. New files use the existing
Fileserver / Object Storage adapter, which is the source of truth for binary content.
The reason is not preference. GridFS stores file chunks in the same collections, on the same replica
set, competing for the same working set as your documents. A large file read evicts document pages
from cache, and file storage growth becomes replica-set growth — which means it becomes oplog
pressure, backup duration and failover time. Object storage was built for this and MongoDB was not.
## Reading legacy files
`MongoGridFsCompatibilityReader` reads existing GridFS content as
`GridFsLegacyContent(legacyId, filename, sizeBytes, checksum, stream)`. It reads; it does not write.
## Migration
`MongoGridFsMigrationJob` moves a file to object storage in a fixed order:
```
read legacy content
→ write to object storage
→ verify the target checksum matches the source
→ switch the reference
→ (later, separately) delete the source
```
Three properties, each of which exists because of a specific way this goes wrong:
1. **Verify before switching.** `MongoGridFsObjectReference` requires a non-blank checksum, and the
job returns empty and writes no reference when the target checksum does not match the source. A
migration that switches the reference on a successful *write* rather than a verified *copy*
silently points at a truncated object.
2. **The source is never deleted here.** Deletion is a separate, later decision after the new
location has been serving reads long enough to be trusted. A migration that deletes as it goes has
no rollback.
3. **The checkpoint separates migrated from failed.** `MongoGridFsMigrationCheckpoint` tracks
`migratedCount()`, `failedCount()`, `clean()` and `lastMigratedLegacyId()`, so a restart continues
from the last completed file rather than starting over, and a partially failed run is visible as
partial rather than as "done".
## Failure recovery
| Symptom | Cause | Action |
|---|---|---|
| `migrate` returns empty | Checksum mismatch | The copy is bad. Investigate before retrying; do not force the reference. |
| `IllegalArgumentException` on the reference | Missing checksum | A reference without a checksum cannot be verified and is refused. |
| Checkpoint not `clean()` | Some files failed | Re-run for the failed ids only; the checkpoint names the last successful one. |
| Reference switched but content missing | Source deleted too early | Restore from backup. This is what rule 2 prevents. |
## Promotion evidence
Actual-topology evidence against the real object storage backend, a security review of the storage
credential, the migration path above, failure cases (checksum mismatch refused, missing checksum
refused, restart resumes), and this document as the runbook.
New file storage does not go through here at all — see the fileserver adapter.
+10 -7
View File
@@ -2,16 +2,19 @@
**Capabilities:** `MongoCapability.SHARED_COLLECTION_TENANCY` (Advanced),
`MongoCapability.DATABASE_PER_TENANT` (Experimental)
**Properties:** `ca-skeleton.persistence-mongo.advanced.shared-collection-tenancy.enabled`,
`ca-skeleton.persistence-mongo.advanced.database-per-tenant.enabled`
**Enablement:** library API, no configuration property. The service's own adapter constructs the
entry point with a `MongoAdvancedCapabilityGuard` built from `MongoAdvancedCapabilityFlags` that
enables the capability; construction is refused otherwise.
Shared-collection tenancy has no entry point (its types are policies), so only
`DATABASE_PER_TENANT` is ever checked.
## 1. Shared collection
Every tenant's documents live in one collection, discriminated by a tenant field.
`MongoTenantContext` carries the tenant. `MongoTenantPredicateInjector` adds the tenant predicate to
every query, every atomic filter and the **first** aggregation stage. `TenantScopedMongoOperations`
is the entry point, so a caller cannot construct an unscoped operation by forgetting.
every query, every atomic filter and the **first** aggregation stage. The adopter's repository calls
the injector on every tenant-scoped path; there is no tenant-scoped operations facade in this leaf.
Three details are load-bearing:
@@ -38,8 +41,8 @@ grows with the customer list, and the tag ships tenant identity into the metrics
## 2. Database per tenant (Experimental)
`MongoTenantDatabaseResolver` maps a tenant to its database; `MongoTenantClientRegistry` holds the
clients.
`MongoTenantClientRegistry` holds one client per tenant under a cap with idle eviction; mapping a
tenant to its database is the adopter's code.
Experimental for a specific reason: it is correct in the small and unbounded in the large. Each tenant
database costs connections, file handles and monitoring cardinality. It works beautifully at 20
@@ -76,7 +79,7 @@ contractual isolation or per-tenant-restore requirement.
| Symptom | Cause | Action |
|---|---|---|
| Cross-tenant data visible | An operation bypassed `TenantScopedMongoOperations` | Treat as a security incident. Find the path, close it, audit access. |
| Cross-tenant data visible | An operation skipped `MongoTenantPredicateInjector` | Treat as a security incident. Find the path, close it, audit access. |
| Unique constraint fires across tenants | Unique index missing the tenant field | Rebuild the index with the tenant field as prefix; the validator catches this before it ships. |
| One shard holds most data | Tenant id as shard-key prefix with a dominant tenant | Refine the shard key with a high-cardinality suffix. |
| Connection exhaustion | Database-per-tenant beyond the connection budget | The scale limit. Consolidate or move to shared collections. |
-81
View File
@@ -1,81 +0,0 @@
# Advanced — Search and Vector Search
**Capabilities:** `MongoCapability.SEARCH`, `MongoCapability.VECTOR_SEARCH`
**Properties:** `ca-skeleton.persistence-mongo.advanced.search.enabled`,
`ca-skeleton.persistence-mongo.advanced.vector-search.enabled`
**Status:** Experimental (design §3.3). Hybrid search likewise.
## Requirements
| | |
|---|---|
| Topology | A deployment with the search service. Atlas Local in a container is a pull-request convenience and is **not** release evidence. |
| Privilege | `MongoPrincipalRole.SEARCH_ADMIN` for index management; the application role queries only. |
| Gate | `MongoAtlasCapabilityContractSuite` on the actual target deployment. |
## 1. Created is not ready
`MongoSearchIndexState`: `CREATED` → `BUILDING` → `READY`, plus `FAILED` and `DELETING`.
`MongoSearchReadinessGate.requireReady(state)` refuses anything but `READY`. A search index is built
asynchronously: the create call returns immediately and the index answers queries with *partial*
results while building. Not an error, not empty — partial. A deployment that creates an index and
starts querying serves incomplete results for as long as the build takes, and nothing reports it.
## 2. Search indexes are not application-owned
`MongoSearchIndexDescriptor.metadataOwnership()` is `MongoMetadataOwnership.SEARCH_MANAGED`, and
`droppableByApplicationDrift()` is false. The index reconciliation described in
[ADR-MONGO-004](../../adr/ADR-MONGO-004-index-schema-admin-plane.md) must not drop it.
## 3. Query guardrails
`MongoSearchQuery` binds an index, an allowlist of paths, the search text and a result limit.
- `requireAllowedPaths(allowed)` raises `MongoOperationRejectedException` on a path outside the
allowlist. Without it, a caller can search any indexed field, including ones indexed for a
different purpose.
- Search text length and result count are bounded at construction. An unbounded search text is a
cost multiplier on someone else's service.
## 4. Vector search
`MongoVectorIndexDescriptor.cosine(path, dimensions)` declares the index.
`MongoEmbedding.forIndex(index, values)` binds an embedding to it and **rejects a dimension
mismatch** — a 1536-dimension embedding against a 768-dimension index is not a runtime degradation,
it is a category error, and catching it at construction beats catching it as a confusing server
message.
`MongoEmbedding` copies its backing array in and out. A vector that shares an array with its caller
can be mutated after the query is built, which produces a query nobody wrote.
`MongoVectorQuery` requires `numCandidates > limit` — searching 10 candidates to return 10 results is
an exhaustive scan wearing an ANN index's name. `MongoVectorQuery.nearest(embedding, 10)` uses the
standard 20× ratio (200 candidates for 10 results).
## 5. Relevance is the gate, not functionality
`MongoVectorSearchBenchmarkGate.standard()` requires **recall** alongside latency and index size.
`requiredEvidence()` names recall explicitly.
This is the difference between search and everything else in the platform. A vector index can be
functionally perfect — it accepts the index, accepts the query, returns k results, within the latency
budget — and return the wrong k. A gate that measures only latency certifies a fast wrong answer.
`failures(recall, latencyMs, indexMb)` reports which dimension failed so the finding is actionable.
## 6. Failure recovery
| Symptom | Cause | Action |
|---|---|---|
| Incomplete results after a deploy | Queried a `BUILDING` index | Wait for `READY`. The gate prevents this; if it fired, something bypassed it. |
| `MongoOperationRejectedException` on a path | Path not in the allowlist | Add it deliberately, or fix the caller. |
| Dimension mismatch | Model changed | A new model means a new index. Build alongside, cut over, then retire. |
| Recall dropped without a code change | The index was rebuilt with different parameters, or the data distribution shifted | Re-run the benchmark gate; treat a recall regression like a failing test. |
| Index `FAILED` | Build error on the search service | Search-side diagnosis; the application must not fall back to a scan silently. |
## 7. Promotion evidence
Per [ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md): the actual target
deployment (not Atlas Local), security review of `SEARCH_ADMIN`, a rebuild path, failure cases
(non-ready index refused, disallowed path refused, dimension mismatch refused), this document as the
runbook, **and** relevance evidence. Search and vector search do not promote on functional success.
+3 -1
View File
@@ -1,7 +1,9 @@
# Advanced — Sharding
**Capability:** `MongoCapability.SHARDING`
**Property:** `ca-skeleton.persistence-mongo.advanced.sharding.enabled`
**Enablement:** library API, no configuration property. The service's own adapter constructs the
entry point with a `MongoAdvancedCapabilityGuard` built from `MongoAdvancedCapabilityFlags` that
enables the capability; construction is refused otherwise.
**Status:** Advanced. Reshard orchestration remains Experimental.
## Requirements
-73
View File
@@ -1,73 +0,0 @@
# Advanced — Time Series
**Capability:** `MongoCapability.TIME_SERIES`
**Property:** `ca-skeleton.persistence-mongo.advanced.time-series.enabled`
**Status:** Advanced.
## Requirements
| | |
|---|---|
| Topology | Replica set or sharded cluster. |
| Server | MongoDB 7.0 or 8.0. |
| Privilege | Standard application role; collection creation goes through the admin plane. |
## Descriptor
`MongoTimeSeriesDescriptor` declares:
- **timeField** — required, a BSON date. This is the bucketing axis.
- **metaField** — optional but nearly always wanted: the series identity (device id, tenant, sensor).
Documents sharing a `metaField` value bucket together, which is where the compression comes from.
- **granularity** — `MongoTimeSeriesGranularity`:
| Granularity | Bucket span | Use for |
|---|---|---|
| `SECONDS` | 1 hour | Sub-second to per-second ingest. |
| `MINUTES` | 24 hours | Per-minute metrics. |
| `HOURS` | 30 days | Hourly rollups. |
Granularity that is too fine produces many small buckets and loses the compression; too coarse
produces oversized buckets that must be read whole to answer a narrow query.
## What a time series collection is not
`MongoTimeSeriesCapabilityValidator` refuses the operations the collection type does not support, at
declaration time rather than at first use:
- **No arbitrary updates.** Time series data is append-mostly. Delete and limited update support
exists on recent servers but is not part of this platform's contract.
- **No unique index on the measurement.** There is no `_id` to be unique on in the usual sense.
- **No CSFLE.** Refused — see [encryption.md](encryption.md).
- **No change stream on the raw buckets** as a business event source. The bucket documents are a
storage representation, not your measurements.
Converting an existing regular collection to a time series collection is a copy, not an alter. Plan
it as a migration with a dual-write window.
## TTL
Time series collections use `expireAfterSeconds` on the collection rather than a TTL index on a
field. The [TTL rules](../schema-index-migration-guide.md#4-ttl) still apply: expiry is physical
cleanup on a bucket boundary, so a measurement can outlive its expiry by up to a bucket span plus the
monitor interval. Do not treat absence as a deadline.
## Operations
`MongoTimeSeriesOperations` is the port for insert and windowed read. Reads are bounded by the same
`MongoOperationBudget` as everything else: an unbounded time-range query on a time series collection
is the fastest way to read a year of data into heap.
## Failure recovery
| Symptom | Cause | Action |
|---|---|---|
| Writes rejected with an unsupported-operation error | An update or unique-index expectation | The collection type does not support it; change the access pattern. |
| Poor compression / large storage | Missing `metaField`, or granularity too fine | Both require a rebuild; measure on a copy before committing. |
| Slow range queries | Granularity too coarse for the query window | Same: rebuild with the granularity matched to the dominant query. |
## Promotion evidence
Actual-topology evidence on the target deployment, a migration path from the existing collection,
failure cases (unsupported update refused, CSFLE combination refused), and this document as the
runbook.
-105
View File
@@ -1,105 +0,0 @@
# Change Stream Guide
Design §20, decision D-12. A change stream is an **at-least-once projector**, not an event bus.
## 1. What a change stream is not
D-12 is explicit: a physical change event is not a business integration event. The two differ in
ways that matter to every consumer:
| Change event | Integration event |
|---|---|
| Emitted per document write | Emitted per business fact |
| Shape follows the storage schema | Shape is a published contract |
| A refactor of the document changes it | A refactor of the document does not change it |
| Replayed on resume, duplicated on retry | Versioned and deliberately evolved |
Publishing raw change events externally makes your storage schema a public API, and the first time
someone renames a field the downstream consumers break. If you need to bridge to messaging, use the
Advanced bridge, which maps to an owned envelope
([advanced/multi-tenancy.md](advanced/multi-tenancy.md) is separate;
the bridge is described in §7 below).
## 2. Subscription and resume
`MongoChangeStreamSubscription` declares the collection, pipeline and consistency. `MongoResumePosition`
is either a resume token or a cluster time; `MongoResumeCheckpoint` is what gets persisted and
`MongoResumeCheckpointStore` persists it.
The checkpoint stores the token as a Base64 `encodedToken` string rather than a byte array — a record
with an array component has broken equality, and a checkpoint that does not compare correctly is a
checkpoint that silently fails its own dedup test.
## 3. Checkpoint after processing, not after receiving
The ordering rule that makes at-least-once actually hold:
```
receive event
→ process it (idempotently)
→ persist the checkpoint
```
Checkpointing on receipt turns the delivery guarantee into at-most-once, and the events lost are
exactly the ones the process died while handling.
## 4. Idempotency
`MongoChangeEventIdentity` is the dedup key: `(resumeToken, documentKey, clusterTime, operationType)`.
`MongoChangeDeduplicationStore` records what has been applied. Duplicates are not an edge case — every
resume after any interruption replays at least one event, so a projector that is not idempotent is
wrong on its first restart, not on some rare day.
`MongoChangeProjector` returns a `MongoChangeProjectionResult` so the runner can distinguish applied
from skipped-as-duplicate, and the skip count is worth a metric: a sudden rise means something is
looping.
## 5. States and recovery
`MongoChangeStreamState`: `STARTING`, `RUNNING`, `RESUMING`, `STOPPED`, `HISTORY_LOST`.
`MongoChangeStreamRecoveryPolicy` returns a `MongoChangeStreamRecoveryDecision`, which is either
`resume()` (auto-resume from the checkpoint) or `halt(state, runbook)`. A halting decision **must**
name a runbook — a decision that only says "stopped" leaves the on-call engineer to work out from
scratch whether the projection can be rebuilt and from what.
| Situation | Decision |
|---|---|
| Transient network error, token still valid | `resume()` |
| Primary failover | `resume()` — the token survives an election |
| `invalidate` (collection dropped/renamed) | `halt(STOPPED, …)` → `MongoInvalidateRecovery` |
| Token no longer in the oplog | `halt(HISTORY_LOST, "history-lost")` → `MongoChangeHistoryLostException` |
## 6. History lost
`MongoChangeHistoryLostException` is raised when the resume token predates the oldest oplog entry.
The stream **cannot** be resumed: the events between the checkpoint and now are gone from the server,
and no amount of retrying brings them back.
What the platform will not do is silently restart from "now". That looks like a recovery and is
actually a silent gap in the projection — the worst possible outcome, because nothing reports it. The
runner halts and requires an operator decision. See
[runbooks/history-lost.md](runbooks/history-lost.md).
## 7. Bridging to messaging (Advanced)
`MongoChangeMessagingBridge` is opt-in behind `MongoCapability.CHANGE_STREAM` plus the bridge's own
flag. It maps a change event to a platform-owned `MongoIntegrationEventEnvelope` through
`MongoChangeToIntegrationEventMapper` and hands it to a `MongoIntegrationEventPublisher` port.
The port is defined in the bridge package rather than imported from the messaging adapter because the
architecture registry forbids adapter-to-adapter dependencies; the composition root supplies the
implementation.
`MongoBridgeOutboxPolicy` and `MongoBridgeCheckpointPolicy` state the delivery contract: publish then
checkpoint, at-least-once, consumers must dedup on the envelope's event id.
## 8. Operating notes
- Change streams require a replica set. `MongoStartupValidator` refuses a change-stream profile on
`STANDALONE`.
- The change-stream principal is its own role (`MongoPrincipalRole.CHANGE_STREAM`) with
`changeStream` and `find` — not the application write credential.
- Oplog window is the recovery budget. If the oplog holds four hours, a consumer that is down for five
hours needs a rebuild, not a resume. Alert on consumer lag against the oplog window, not against
wall-clock.
@@ -31,8 +31,7 @@ Collapsing these two into one is how a concurrent overwrite becomes a 404.
## 3. Consistency profiles
`MongoConsistencyProfile` names the read/write concern pair; `MongoConsistencyRegistry` binds a
profile to an operation or collection, and `MongoConsistencyBinder` /
`ReactiveMongoConsistencyBinder` apply it at execution.
profile to an operation or collection, and `MongoConsistencyBinder` applies it at execution.
| Profile | Meaning | Use for |
|---|---|---|
@@ -47,17 +46,14 @@ without a registered profile is rejected rather than defaulting.
## 4. Causal sessions
`MongoCausalSessionContext` plus `SpringMongoCausalSessionExecutor` /
`ReactiveMongoCausalSessionExecutor` carry the cluster time and operation time between operations, so
`MongoCausalSessionContext` plus `SpringMongoCausalSessionExecutor` carry the cluster time and
operation time between operations, so
"write then read" returns the write even when the read lands on a different node. Without a causal
session, `PRIMARY_MAJORITY` gives you durability but not read-your-writes across two calls.
In the reactive path the session travels in the Reactor context (`ReactiveMongoContextKeys`), not in
a thread local — a thread local is empty on the next operator in the chain.
## 5. Transactions
`MongoTransactionExecutor` / `ReactiveMongoTransactionExecutor` open a session through the session
`MongoTransactionExecutor` opens a session through the session
factory, run the body, and commit. `MongoTransactionProfile` carries the consistency profile, the
`maxCommitTime` and the retry budget. Topology matters: a transaction requires a replica set, and
`MongoStartupValidator` refuses a transaction-declaring profile on `STANDALONE` at startup rather
@@ -122,5 +118,5 @@ driver type.
`MongoBulkExecutor` returns a `MongoBulkResult` with per-item `MongoBulkItemFailure` entries. An
unordered bulk write that partially fails is `PARTIAL_BULK_WRITE`, not a failure: some documents were
written. `MongoBulkPartialFailureException` carries the succeeded and failed indexes so a caller can
written. The result's per-item outcomes say which indexes succeeded and which failed, so a caller can
resume rather than replay.
+3 -3
View File
@@ -39,8 +39,8 @@ is the first symptom, and by then the collection is already full of near-limit d
## 4. Identity
`DomainDocumentId` and `MongoIdRepresentation` fix how a domain identifier becomes `_id`. Pick the
representation once per collection and record it in the manifest:
`DomainDocumentId` is written to `_id` as a BSON string by `DomainIdWriteConverter`. Any other
representation is the document class's own field type. Pick the representation once per collection:
- `OBJECT_ID` — server-generated, monotonic, 12 bytes. Good default when the domain has no natural id.
- `UUID_BINARY` — a domain UUID stored as `Binary` subtype 4 (`STANDARD`). Never store a UUID as a
@@ -70,7 +70,7 @@ becomes a data migration; storing an alias keeps it a refactor. See
`MongoCollectionProfileRegistry` binds a `CollectionProfileName` to its consistency profile, budget
and allowlist. A collection that is not registered cannot be reached through
`MongoImperativeExecutor` or `ReactiveMongoExecutor` — the allowlist is the mechanism that keeps an
`MongoImperativeExecutor` — the allowlist is the mechanism that keeps an
unreviewed collection from appearing in production by accident.
## 8. What to write down before the first insert
+2 -16
View File
@@ -92,21 +92,7 @@ registered plan.
`allowDiskUse` is a declared property of the plan, not a runtime flag. A pipeline that needs disk is a
pipeline whose shape should be reviewed.
## 6. Reactive execution and cursors
`ReactiveMongoExecutor` / `DefaultReactiveMongoExecutor` carry the operation context in the Reactor
context. `MongoCursorGuard` and `MongoCursorLease` bound cursor lifetime:
- a cursor has a lease with a deadline
- cancellation closes the server-side cursor (`MongoCursorTermination`)
- an abandoned cursor is a server-side resource, so the lease is released on cancel, error *and*
completion — `MongoReactiveCursorPublisher` uses `Flux.using` so all three paths run the same
release
A leaked cursor does not fail anything locally; it consumes a connection and a snapshot on the server
until the server's own timeout, which is why the guard is not optional.
## 7. Geospatial
## 6. Geospatial
`MongoGeoQuery` + `MongoGeoPoint` + `MongoGeoDistance` over a `2dsphere` index. Distances are metres
on a sphere (`nearSphere` with `maxDistance`), never degrees — a degree of longitude is a different
@@ -114,7 +100,7 @@ distance in Oslo than in Nairobi, and a radius expressed in degrees is a bug tha
from the equator. `SpringMongoGeospatialOperations` is the Spring Data binding;
`MongoGeospatialOperations` is the port.
## 8. Native capability gateway
## 7. Native capability gateway
When a registered operation genuinely needs something outside the Stable API, it goes through
`MongoNativeCapabilityGateway` (`PolicyAwareMongoNativeGateway`), never through the driver directly.
+13 -18
View File
@@ -27,9 +27,8 @@ the tree for exact equality, and every observed edge must appear in it. A forbid
build the same way a missing Gradle dependency would, and so does a new package nobody registered.
This used to be a stronger claim than the test. The rules forbade a handful of reverse dependencies
and said nothing about the rest, so four edges outside the design's DAG existed and passed:
`reactive → imperative`, `reactive → query`, `transaction → reactive` and `geo → imperative`. They
are declared in the matrix now rather than removed — each is a real coupling the code relies on, and
and said nothing about the rest, so edges outside the design's DAG existed and passed, among them
`geo → imperative`. They are declared in the matrix now rather than removed — each is a real coupling the code relies on, and
the point of recording them is that the next one is a decision instead of an accident.
## 2. Package mapping
@@ -43,12 +42,10 @@ Root package: `io.backend.skeleton.mongodb` → `dev.caskeleton.adapter.outbound
| `mongodb-core-api` | `…outbound.mongo.api` (+ `.capability`, `.consistency`, `.error`, `.mapping`, `.observation`, `.profile`, `.schema`) |
| `mongodb-spring-data` | `…outbound.mongo.mapping` (+ `.type`), `…outbound.mongo.failure` |
| `mongodb-imperative` | `…outbound.mongo.imperative` (+ `.atomic`, `.bulk`, `.revision`) |
| `mongodb-reactive` | `…outbound.mongo.reactive` (+ `.cursor`) |
| `mongodb-query` | `…outbound.mongo.query` (+ `.budget`, `.pagination`) |
| `mongodb-aggregation` | `…outbound.mongo.aggregation` |
| `mongodb-transaction` | `…outbound.mongo.transaction` (+ `.retry`, `.session`) |
| `mongodb-index-schema` | `…outbound.mongo.schema` (+ `.index`, `.manifest`, `.model`, `.ttl`, `.validation`) |
| `mongodb-change-stream` | `…outbound.mongo.changestream` (+ `.projector`, `.recovery`) |
| `mongodb-geospatial` | `…outbound.mongo.geo` |
| `mongodb-migration-core` | `…outbound.mongo.migration` |
| `mongodb-migration-flamingock` | `…outbound.mongo.migration.flamingock` |
@@ -68,22 +65,22 @@ the reusable ArchUnit rule set a fork applies to its own document/repository cod
| Design module | Repository package |
|---|---|
| `mongodb-sharding` | `…outbound.mongo.advanced.sharding` (+ `.admin` for the D4 shard plane) |
| `mongodb-timeseries` | `…outbound.mongo.advanced.timeseries` |
| `mongodb-csfle` | `…outbound.mongo.advanced.encryption.csfle` |
| `mongodb-queryable-encryption` | `…outbound.mongo.advanced.encryption.qe` |
| `mongodb-search` | `…outbound.mongo.advanced.search` |
| `mongodb-vector-search` | `…outbound.mongo.advanced.vector` |
| `mongodb-tenancy-shared` | `…outbound.mongo.advanced.tenancy.shared` |
| `mongodb-tenancy-database` | `…outbound.mongo.advanced.tenancy.database` |
| `mongodb-change-stream-messaging-bridge` | `…outbound.mongo.advanced.bridge` |
| `mongodb-gridfs-compat` | `…outbound.mongo.advanced.gridfs` |
| `mongodb-testkit-sharded` | `…outbound.mongo.testkit.sharded` (`testkit` source set) |
| `mongodb-testkit-atlas` | `…outbound.mongo.testkit.atlas` (`testkit` source set) |
`mongodb-timeseries`, `mongodb-search`, `mongodb-vector-search`, `mongodb-gridfs-compat` and
`mongodb-testkit-atlas` have no package any more: each was an operations interface with no
implementation plus the descriptors that parametrised it, and was removed on 2026-09-25
(`docs/capability-status.md`).
The design's rule that a Stable module never depends on an Advanced one survives as an ArchUnit rule
(`stableNeverDependsOnAdvanced`) plus the opt-in flag: every Advanced entry point requires
`MongoAdvancedCapabilityFlags` to have the matching capability enabled and refuses construction
otherwise. Being on the classpath is not being enabled.
(`stableNeverDependsOnAdvanced`). Every Advanced entry point takes a `MongoAdvancedCapabilityGuard`
and refuses construction unless its `MongoAdvancedCapabilityFlags` enable the matching capability.
There is no configuration property behind the flags: the Advanced types are library API, and the
adopter's adapter that constructs them builds the guard.
## 3. Other deliberate substitutions
@@ -114,13 +111,11 @@ otherwise. Being on the classpath is not being enabled.
- Registered operation names and manifests for query, aggregation and index; no free-form JSON query
and no unbounded pipeline.
- Keyset pagination with an authenticated cursor and a unique tie-breaker requirement.
- Change stream as an at-least-once projector with resume-token checkpointing and explicit
history-lost handling.
- TTL as physical cleanup only, never the sole basis for access denial or business scheduling.
- Manifest-owned index/validator state with an apply policy that never drops what it does not own.
- Low-cardinality observation tags, command redaction, and the credential reference indirection.
- The Stable release gate's evidence categories, and the Advanced promotion gate's requirement for
actual-topology evidence.
- The Stable release gate's evidence categories. The Advanced promotion requirements
(actual-topology evidence) are a review obligation in ADR-MONGO-ADV-001; no class checks them.
## 5. Verification
-90
View File
@@ -1,90 +0,0 @@
---
title: Runbook — MongoDB change stream history lost
category: mongodb
severity: P1
owner: oncall
last_updated: 2026-08-13
status: active
---
# Runbook: change stream history lost
Design §20.3, scenarios `OPLOG_HISTORY_LOSS`, `RESUME_TOKEN_LOSS`.
The stored resume token predates the oldest entry in the oplog. The events between the checkpoint and
now are gone from the server; no retry recovers them. `MongoChangeStreamRecoveryPolicy` returns
`halt(HISTORY_LOST, "history-lost")` and the runner stops.
**The platform will not silently restart from "now".** That looks like a recovery and is actually a
permanent, unreported gap in the projection.
## Symptoms
- `MongoChangeHistoryLostException`.
- `MongoChangeStreamState.HISTORY_LOST`; the consumer is stopped, not looping.
- Precedes it: consumer lag approaching the oplog window, or a consumer that was down for a long
period (a deploy that failed, a scaled-to-zero worker, a long outage).
## Diagnosis
1. **Determine the gap.** The checkpoint's cluster time is the start; the oldest oplog entry is the
end of what is unrecoverable. Everything in between was never processed.
2. **Determine the oplog window.** `rs.printReplicationInfo()` on the primary gives the first and last
oplog timestamps. If the window is materially smaller than it was, the write rate rose or the
oplog was resized — the consumer may be fine and the server changed.
3. **Determine what the projection is missing.** Which collections and which operations does this
projector consume? The gap is bounded by that, not by everything that happened.
4. **Check for a second consumer.** If another projector on the same collection is healthy, its
checkpoint tells you whether the problem is this consumer or the oplog.
## Action
Resuming is not an option. The choices are:
**Rebuild from source.** If the projection is derivable from the current state of the source
collections, rebuild it: stop the consumer, rebuild the projection, then start the stream from the
cluster time at which the rebuild snapshot was taken. This is the correct answer whenever the
projection is a materialised view rather than an event log, and it is the reason a projection should
be derivable.
**Backfill the gap.** If the source documents carry a timestamp covering the gap, run a bounded
backfill for that window through the migration runner (checkpointed, resumable — see
[schema-index-migration-guide.md](../schema-index-migration-guide.md) §5), then resume from the
current cluster time.
**Accept the gap explicitly.** Only when the projection is advisory and the business owner says so.
Record the window in the incident log and reset the checkpoint. This is a decision someone signs, not
a default.
Never: reset the checkpoint to "now" and restart quietly. That converts a visible P1 into an
invisible data-quality defect that surfaces months later as "the report has been wrong since March".
## Prevention
- **Alert on lag against the oplog window, not wall-clock.** "Consumer is 30 minutes behind" is fine
with a 24-hour oplog and an emergency with a 45-minute one. The threshold that matters is
`lag / oplogWindow`.
- **Size the oplog for the longest tolerable consumer outage**, including a failed deploy discovered
the next morning.
- **Checkpoint after processing, never on receipt** — see
[change-stream-guide.md](../change-stream-guide.md) §3.
- **Back up the checkpoint store.** `RESUME_TOKEN_LOSS` is the same incident reached from the other
direction: the oplog is fine, the checkpoint is gone.
- **Make the projection rebuildable.** A projection that can only be built by replaying every event
has no recovery path once the oplog rolls.
## Escalation
- P1 on detection. The consumer is stopped, so lag grows for as long as this is unresolved.
- Page the service owner for the rebuild decision, and the database owner if the oplog window shrank
unexpectedly.
## Verification
```bash
cd src
./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain
```
`MongoFailoverScenario.OPLOG_HISTORY_LOSS` and `RESUME_TOKEN_LOSS` assert the runner halts and names
this runbook rather than restarting from the current position.
+8 -7
View File
@@ -119,13 +119,14 @@ command's arguments.
`MongoStartupValidator` runs at context refresh, before the first request:
1. `MongoTopologyProbe` reports the actual `MongoTopology`.
2. Each declared `MongoTopologyRequirement` is checked against it — a transaction, causal-session or
change-stream requirement fails closed on `STANDALONE`.
3. `MongoSecurityProfileValidator` checks credentials and TLS.
4. `MongoCapabilitySupport` checks declared capabilities against the server version, with
`MongoSupportLevel` distinguishing `STABLE` / `ADVANCED` / `EXPERIMENTAL` / `UNSUPPORTED`.
5. `MongoPlatformHealthIndicator` reports the outcome for the readiness probe.
1. `MongoTopologyProbe` reports the actual `MongoTopology` and its `MongoCapabilitySet`.
2. Every profile's declared topology must match it, and a production profile on `STANDALONE` fails.
3. With `platform.transactions=true`, the probe must report `TRANSACTION` as `STABLE`; on
`STANDALONE` it does not, so startup fails.
4. `MongoSecurityProfileValidator` checks credentials and TLS, and that the admin credential differs
from the runtime one; the `MongoSchemaVersionRange` must not be inverted.
5. `MongoPlatformHealthIndicator` reports topology mismatch and secondary availability for the
readiness probe.
A misconfiguration found at startup costs a failed deploy. The same misconfiguration found at runtime
costs an incident, and the failing operation is rarely the one that reveals the cause.
+11 -11
View File
@@ -12,7 +12,6 @@ adds a row.
| Spring Boot | 4.0.0 | BOM-managed. Individual driver overrides are forbidden. |
| Spring Data MongoDB | 5.0.0 | Repository and `MongoTemplate` integration. Version comes from the Boot BOM. |
| MongoDB Java Driver | 5.6.1 | BOM-managed. Never pinned directly in the module. |
| Reactor | 3.8.0 | Reactive execution path. |
| Micrometer | 1.16.0 | Driver-native observability. |
| Testcontainers | 2.0.2 | Replica-set, failover, migration and compatibility lanes. |
@@ -40,19 +39,19 @@ fails `certifies()`.
| Topology | Status | What is certified | What is not |
|---|---|---|---|
| Standalone | **Smoke only** | Basic CRUD and mapping. | Not a production profile and never counts as Stable release evidence (D-03). Transactions, retryable writes and change streams are refused at startup by `MongoStartupValidator`. |
| Standalone | **Smoke only** | Basic CRUD and mapping. | Not a production profile and never counts as Stable release evidence (D-03). A production profile, or `platform.transactions=true`, on a Standalone server is refused at startup by `MongoStartupValidator`. |
| Single-node replica set | **Local default** (D-02) | Transactions, retryable writes, change streams — the same semantics as production. | Elections. A single-node set never holds one, so failover behaviour is untested here. |
| 3-node replica set | **Stable production gate** | Everything above plus primary failover, unknown-commit handling and change-stream resume across an election. | Shard routing. |
| 3-node replica set | **Stable production gate** | Everything above plus primary failover and unknown-commit handling. | Shard routing. |
| Sharded cluster | **Advanced gate** | Shard-key routing classification, scatter-gather refusal, `admin` plane operations. | Not included in the Stable gate. |
| Atlas / provider-managed | **Per-capability gate** | Search, vector search and encryption against the actual target deployment. | Atlas Local in a container is a pull-request convenience, explicitly **not** release evidence (`MongoAtlasCapabilityContractSuite.Environment`). |
| Atlas / provider-managed | **Not certified** | Encryption against the actual target deployment is the adopter's evidence to produce. | Search and vector search have no implementation in this leaf; a native `$search` command can only go through `PolicyAwareMongoNativeGateway` as a registered D3 operation. |
## 4. Stable API and client generations
| Plane | Stable API | Purpose |
|---|---|---|
| D1 Standard document persistence | V1, `apiStrict=true` | Repositories, typed queries, atomic updates, optimistic revision. |
| D2 Advanced document operations | V1, `apiStrict=true` | `MongoTemplate`, transactions, bulk, aggregation, keyset cursors, change streams. |
| D3 Explicit Mongo capability | Not strict | Native BSON, time series, search/vector, CSFLE/QE, shard-aware operations — each behind a registered capability. |
| D2 Advanced document operations | V1, `apiStrict=true` | `MongoTemplate`, transactions, bulk, aggregation, keyset cursors. |
| D3 Explicit Mongo capability | Not strict | Native BSON, CSFLE/QE, shard-aware operations — each behind a registered capability. |
| D4 Admin plane | Not strict | Collection, validator, index, migration, shard and repair commands. Separate credential, separate client. |
D3 is not a raw-client escape. Every call passes capability registration → database profile →
@@ -83,9 +82,10 @@ feature request:
| Tier | Capabilities | Enablement |
|---|---|---|
| Stable | Mapping, imperative/reactive execution, atomic update, optimistic lock, transactions, consistency profiles, retry/translation, query and aggregation guardrails, schema/index manifests, keyset pagination, bulk partial results, change streams, TTL contract, GeoJSON, security, observability | On when `ca-skeleton.persistence-mongo.enabled=true`. |
| Advanced | Sharding-aware query, time series, CSFLE, Queryable Encryption (equality/range), change-stream→messaging bridge, shared-collection multi-tenancy | Each behind `ca-skeleton.persistence-mongo.advanced.<capability>.enabled`. |
| Experimental | Search, vector search, hybrid search, database-per-tenant, collection-per-tenant, reshard orchestration, provider-specific features | Same flag mechanism; promotion additionally requires the evidence in [ADR-MONGO-ADV-001](../adr/ADR-MONGO-ADV-001-capability-promotion.md). |
| Stable, auto-configured | Mapping and BSON converters, imperative execution, atomic update, bulk partial results, consistency profiles, retry/translation, operation budgets, observability, typed client profiles, startup validation, health | Beans registered when `ca-skeleton.persistence-mongo.enabled=true`. |
| Stable, library API | Transactions, causal sessions, optimistic revision, query builder and keyset pagination, aggregation executor, schema/index/validator manifests and diffs, TTL contract, GeoJSON, migration runner, admin plane, native capability gateway | The adopter's adapter leaf takes this leaf as `implementation` and constructs the type. |
| Advanced, library API | Sharding-aware query and shard admin, CSFLE, Queryable Encryption (equality/range), shared-collection tenancy policies | Same, plus a `MongoAdvancedCapabilityGuard` whose flags enable the capability. No configuration property. |
| Experimental, library API | Database-per-tenant client registry and migration coordinator, reshard approval | Same as Advanced; promotion additionally requires the evidence in [ADR-MONGO-ADV-001](../adr/ADR-MONGO-ADV-001-capability-promotion.md). |
`MongoAdvancedCapabilityFlags.propertyFor(capability)` is the authoritative property name for any
capability; the table above is its prose form.
Search, vector search, time series and GridFS compatibility were interfaces with no implementation
and were removed on 2026-09-25 (`docs/capability-status.md`).
@@ -4,6 +4,13 @@
Accepted (2026-08-15). NTF-018 대응.
**갱신 (2026-09-25):** R1 type은 삭제됐다. production consumer가 끝까지 0건이었고 fake로만 증명된
계약이라, 새 consumer를 막는 ArchUnit 규칙을 유지할 이유가 없어졌다. 남은 것은 adapter core의
`RoutingNotifier`가 구현하는 단순 알림 포트 3개(`NotificationPort`, `Notification`,
`NotificationChannel`)뿐이다. 그래서 아래 「강제」의 `NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER`
규칙과 `compatibility.r1` 예외 패키지도 함께 없어졌다. 삭제 목록과 마지막 커밋은
`docs/capability-status.md`의 「제거된 코드」 표에 있다. 아래 본문은 결정 당시 기록이다.
## 문제
같은 저장소에 notification 모델이 **두 개** 있다.
+6 -142
View File
@@ -1,6 +1,8 @@
# NTF-022 — public type surface of the notification platform.
# Every top-level public type under the platform packages. Growth is a reviewed
# change: ./gradlew updateNotificationApiSurface -PapproveNotificationApiChange
# NTF-022 — public type surface of the notification platform (application-notification + adapter:outbound:notification).
# Every top-level public type under the platform packages. Growth is a reviewed change.
# Update only after review with:
# ./gradlew :adapter:outbound:notification:updateNotificationApiSurface -PapproveNotificationApiSurfaceChange
# types: 416
dev.caskeleton.adapter.outbound.notification.NotificationConfig
dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings
dev.caskeleton.adapter.outbound.notification.core.FailOpenNotificationProvider
@@ -34,7 +36,6 @@ dev.caskeleton.adapter.outbound.notification.platform.dispatch.ConfiguredProfile
dev.caskeleton.adapter.outbound.notification.platform.dispatch.CredentialProbe
dev.caskeleton.adapter.outbound.notification.platform.dispatch.CredentialValidationException
dev.caskeleton.adapter.outbound.notification.platform.dispatch.JacksonRoutingPlanCodec
dev.caskeleton.adapter.outbound.notification.platform.dispatch.LeaseRecoveryService
dev.caskeleton.adapter.outbound.notification.platform.dispatch.LoggingInboxSignalPublisher
dev.caskeleton.adapter.outbound.notification.platform.dispatch.MapTemplateRendererRegistry
dev.caskeleton.adapter.outbound.notification.platform.dispatch.NotificationBackgroundWorkers
@@ -120,9 +121,6 @@ dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushNo
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushReceiptCapability
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushRequestMapper
dev.caskeleton.adapter.outbound.notification.platform.reactor.ReactiveNotificationOrchestrator
dev.caskeleton.adapter.outbound.notification.platform.reactor.ReactorContextBridge
dev.caskeleton.adapter.outbound.notification.platform.reactor.ReactorNotificationOrchestrator
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmCallbackPayloadProtection
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmContactPointProtector
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmNotificationPayloadProtection
@@ -147,105 +145,9 @@ dev.caskeleton.adapter.outbound.notification.platform.template.ThymeleafStringTe
dev.caskeleton.adapter.outbound.notification.slack.webhook.SlackClient
dev.caskeleton.adapter.outbound.notification.slack.webhook.SlackNotificationAdapterConfig
dev.caskeleton.adapter.outbound.notification.slack.webhook.SlackWebhookProvider
dev.caskeleton.application.notification.ApplyNotificationReceiptCommand
dev.caskeleton.application.notification.ApplyNotificationReceiptResult
dev.caskeleton.application.notification.ApplyNotificationReceiptUseCase
dev.caskeleton.application.notification.ConsentCheckMode
dev.caskeleton.application.notification.EmailRecipientReference
dev.caskeleton.application.notification.InitializeNotificationWriterFencesCommand
dev.caskeleton.application.notification.InitializeNotificationWriterFencesOperation
dev.caskeleton.application.notification.InitializeNotificationWriterFencesResult
dev.caskeleton.application.notification.InitializeNotificationWriterFencesUseCase
dev.caskeleton.application.notification.InlineNotificationAttemptPort
dev.caskeleton.application.notification.NormalizedNotificationReceiptCommand
dev.caskeleton.application.notification.Notification
dev.caskeleton.application.notification.NotificationAdmissionClass
dev.caskeleton.application.notification.NotificationAdmissionGateCommand
dev.caskeleton.application.notification.NotificationAdmissionGateUseCase
dev.caskeleton.application.notification.NotificationAdmissionReadinessPort
dev.caskeleton.application.notification.NotificationAppendResult
dev.caskeleton.application.notification.NotificationApplicationException
dev.caskeleton.application.notification.NotificationAttemptId
dev.caskeleton.application.notification.NotificationCanonicalWriterFenceGuard
dev.caskeleton.application.notification.NotificationCanonicalWriterFencePort
dev.caskeleton.application.notification.NotificationCanonicalWriterRouteSet
dev.caskeleton.application.notification.NotificationCapabilityCompatibilityValidator
dev.caskeleton.application.notification.NotificationChannel
dev.caskeleton.application.notification.NotificationDeliveryId
dev.caskeleton.application.notification.NotificationDeliveryStorePort
dev.caskeleton.application.notification.NotificationDispatchCommand
dev.caskeleton.application.notification.NotificationDispatchResult
dev.caskeleton.application.notification.NotificationDispatchUseCase
dev.caskeleton.application.notification.NotificationEvidenceTrustSnapshot
dev.caskeleton.application.notification.NotificationFaultScope
dev.caskeleton.application.notification.NotificationFrozenPlan
dev.caskeleton.application.notification.NotificationIntentAppendPort
dev.caskeleton.application.notification.NotificationIntentDraft
dev.caskeleton.application.notification.NotificationIntentId
dev.caskeleton.application.notification.NotificationKindId
dev.caskeleton.application.notification.NotificationKindPolicy
dev.caskeleton.application.notification.NotificationLegacyWriterPermitCommand
dev.caskeleton.application.notification.NotificationLegacyWriterPermitResult
dev.caskeleton.application.notification.NotificationLegacyWriterPermitUseCase
dev.caskeleton.application.notification.NotificationMaintenanceCommand
dev.caskeleton.application.notification.NotificationMaintenanceResult
dev.caskeleton.application.notification.NotificationMaintenanceStorePort
dev.caskeleton.application.notification.NotificationMaintenanceUseCase
dev.caskeleton.application.notification.NotificationMode
dev.caskeleton.application.notification.NotificationOperationsSnapshot
dev.caskeleton.application.notification.NotificationOperationsSnapshotPort
dev.caskeleton.application.notification.NotificationOperationsSnapshotQuery
dev.caskeleton.application.notification.NotificationOperationsSnapshotUseCase
dev.caskeleton.application.notification.NotificationPlanPort
dev.caskeleton.application.notification.NotificationPlanningResult
dev.caskeleton.application.notification.NotificationPort
dev.caskeleton.application.notification.NotificationProviderAttemptPort
dev.caskeleton.application.notification.NotificationProviderCapabilityDescriptor
dev.caskeleton.application.notification.NotificationReasonCode
dev.caskeleton.application.notification.NotificationReceiptEventId
dev.caskeleton.application.notification.NotificationReceiptFact
dev.caskeleton.application.notification.NotificationReceiptIngressCapabilityDescriptor
dev.caskeleton.application.notification.NotificationReceiptProjection
dev.caskeleton.application.notification.NotificationReceiptStorePort
dev.caskeleton.application.notification.NotificationRecipientReference
dev.caskeleton.application.notification.NotificationReconciliationPort
dev.caskeleton.application.notification.NotificationRequestResult
dev.caskeleton.application.notification.NotificationRouteId
dev.caskeleton.application.notification.NotificationRouteStrategy
dev.caskeleton.application.notification.NotificationSignedEvidenceHeader
dev.caskeleton.application.notification.NotificationStoreCapabilityDescriptor
dev.caskeleton.application.notification.NotificationTechnicalSuppressionPort
dev.caskeleton.application.notification.NotificationTemplateParameters
dev.caskeleton.application.notification.NotificationTemplateRef
dev.caskeleton.application.notification.NotificationTemplateValue
dev.caskeleton.application.notification.NotificationWriterCutoverPort
dev.caskeleton.application.notification.NotificationWriterInventoryEvidence
dev.caskeleton.application.notification.NotificationWriterInventoryEvidenceVerifierPort
dev.caskeleton.application.notification.NotificationWriterOwnership
dev.caskeleton.application.notification.NotificationWriterQuiescenceAttestationPort
dev.caskeleton.application.notification.NotificationWriterRouteSet
dev.caskeleton.application.notification.ProviderAttemptOutcome
dev.caskeleton.application.notification.ReconcileNotificationDeliveriesCommand
dev.caskeleton.application.notification.ReconcileNotificationDeliveriesResult
dev.caskeleton.application.notification.ReconcileNotificationDeliveriesUseCase
dev.caskeleton.application.notification.RecordNotificationWriterQuiescenceAttestationCommand
dev.caskeleton.application.notification.RecordNotificationWriterQuiescenceAttestationOperation
dev.caskeleton.application.notification.RecordNotificationWriterQuiescenceAttestationResult
dev.caskeleton.application.notification.RecordNotificationWriterQuiescenceAttestationUseCase
dev.caskeleton.application.notification.RetryDisposition
dev.caskeleton.application.notification.SignedNotificationWriterInventoryManifest
dev.caskeleton.application.notification.SignedNotificationWriterQuiescenceManifest
dev.caskeleton.application.notification.SlackAudienceReference
dev.caskeleton.application.notification.SubmissionCertainty
dev.caskeleton.application.notification.SwitchNotificationWriterOwnershipCommand
dev.caskeleton.application.notification.SwitchNotificationWriterOwnershipOperation
dev.caskeleton.application.notification.SwitchNotificationWriterOwnershipResult
dev.caskeleton.application.notification.SwitchNotificationWriterOwnershipUseCase
dev.caskeleton.application.notification.TargetAttemptOutcome
dev.caskeleton.application.notification.TerminalizeExpiredNotificationWriterPermitsCommand
dev.caskeleton.application.notification.TerminalizeExpiredNotificationWriterPermitsOperation
dev.caskeleton.application.notification.TerminalizeExpiredNotificationWriterPermitsResult
dev.caskeleton.application.notification.TerminalizeExpiredNotificationWriterPermitsUseCase
dev.caskeleton.application.notification.platform.admin.AdminAccessDeniedException
dev.caskeleton.application.notification.platform.admin.AdminActor
dev.caskeleton.application.notification.platform.admin.AdminAuthorizationGuard
@@ -280,7 +182,6 @@ dev.caskeleton.application.notification.platform.api.NormalizedEventType
dev.caskeleton.application.notification.platform.api.NormalizedProviderEvent
dev.caskeleton.application.notification.platform.api.NotificationAcceptance
dev.caskeleton.application.notification.platform.api.NotificationId
dev.caskeleton.application.notification.platform.api.NotificationOrchestrator
dev.caskeleton.application.notification.platform.api.NotificationPlan
dev.caskeleton.application.notification.platform.api.NotificationReceipt
dev.caskeleton.application.notification.platform.api.NotificationSnapshot
@@ -311,31 +212,19 @@ dev.caskeleton.application.notification.platform.api.delivery.DeliveryOutcome
dev.caskeleton.application.notification.platform.api.delivery.EvidenceLevel
dev.caskeleton.application.notification.platform.api.delivery.RecipientDeliveryState
dev.caskeleton.application.notification.platform.api.delivery.SubmissionOutcome
dev.caskeleton.application.notification.platform.api.error.AmbiguousSubmissionException
dev.caskeleton.application.notification.platform.api.error.AttachmentIntegrityException
dev.caskeleton.application.notification.platform.api.error.AttachmentUnavailableException
dev.caskeleton.application.notification.platform.api.error.CallbackProjectionException
dev.caskeleton.application.notification.platform.api.error.CallbackValidationException
dev.caskeleton.application.notification.platform.api.error.FailureCategory
dev.caskeleton.application.notification.platform.api.error.IdempotencyConflictException
dev.caskeleton.application.notification.platform.api.error.InvalidContactPointException
dev.caskeleton.application.notification.platform.api.error.NotificationCapacityException
dev.caskeleton.application.notification.platform.api.error.NotificationException
dev.caskeleton.application.notification.platform.api.error.NotificationExpiredException
dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode
dev.caskeleton.application.notification.platform.api.error.NotificationFailureDescriptor
dev.caskeleton.application.notification.platform.api.error.NotificationSuppressedException
dev.caskeleton.application.notification.platform.api.error.NotificationValidationException
dev.caskeleton.application.notification.platform.api.error.ProviderAuthenticationException
dev.caskeleton.application.notification.platform.api.error.ProviderAuthorizationException
dev.caskeleton.application.notification.platform.api.error.ProviderConfigurationException
dev.caskeleton.application.notification.platform.api.error.ProviderPayloadLimitException
dev.caskeleton.application.notification.platform.api.error.ProviderPermanentException
dev.caskeleton.application.notification.platform.api.error.ProviderRejectedException
dev.caskeleton.application.notification.platform.api.error.ProviderThrottledException
dev.caskeleton.application.notification.platform.api.error.ProviderTransientException
dev.caskeleton.application.notification.platform.api.error.ProviderUnavailableException
dev.caskeleton.application.notification.platform.api.error.ReconciliationException
dev.caskeleton.application.notification.platform.api.error.TemplateNotFoundException
dev.caskeleton.application.notification.platform.api.error.TemplateRenderingException
dev.caskeleton.application.notification.platform.api.error.TemplateVariableValidationException
@@ -378,7 +267,6 @@ dev.caskeleton.application.notification.platform.contact.MobilePushTarget
dev.caskeleton.application.notification.platform.contact.PhoneNumber
dev.caskeleton.application.notification.platform.contact.WebPushSubscriptionValue
dev.caskeleton.application.notification.platform.dispatch.AcceptNotificationApplicationUseCase
dev.caskeleton.application.notification.platform.dispatch.ApplicationReceiptServiceImpl
dev.caskeleton.application.notification.platform.dispatch.AttachmentIntegrityGuard
dev.caskeleton.application.notification.platform.dispatch.CancelNotificationApplicationUseCase
dev.caskeleton.application.notification.platform.dispatch.CanonicalNotificationPlanEncoder
@@ -393,6 +281,7 @@ dev.caskeleton.application.notification.platform.dispatch.DispatchOutcomeRecorde
dev.caskeleton.application.notification.platform.dispatch.DispatchPipeline
dev.caskeleton.application.notification.platform.dispatch.DuplicateIdempotencyKeyException
dev.caskeleton.application.notification.platform.dispatch.GetNotificationApplicationUseCase
dev.caskeleton.application.notification.platform.dispatch.LeaseRecoveryService
dev.caskeleton.application.notification.platform.dispatch.MessageDigestPort
dev.caskeleton.application.notification.platform.dispatch.NotificationDispatchService
dev.caskeleton.application.notification.platform.dispatch.NotificationIdGeneratorPort
@@ -423,8 +312,6 @@ dev.caskeleton.application.notification.platform.dispatch.SubmitNotificationAppl
dev.caskeleton.application.notification.platform.dispatch.SyntheticEventFingerprint
dev.caskeleton.application.notification.platform.dispatch.TemplateRendererRegistry
dev.caskeleton.application.notification.platform.dispatch.TenantContextPort
dev.caskeleton.application.notification.platform.email.EmailNotification
dev.caskeleton.application.notification.platform.email.EmailNotifier
dev.caskeleton.application.notification.platform.inbox.CreateInboxItemCommand
dev.caskeleton.application.notification.platform.inbox.InboxContentCodecPort
dev.caskeleton.application.notification.platform.inbox.InboxCursor
@@ -512,35 +399,14 @@ dev.caskeleton.application.notification.platform.provider.ReconciliationCapabili
dev.caskeleton.application.notification.platform.provider.ReconciliationResult
dev.caskeleton.application.notification.platform.provider.ResolvedAttachment
dev.caskeleton.application.notification.platform.provider.TraceContext
dev.caskeleton.application.notification.platform.push.ApplicationIdentity
dev.caskeleton.application.notification.platform.push.ApplicationReceipt
dev.caskeleton.application.notification.platform.push.ApplicationReceiptService
dev.caskeleton.application.notification.platform.push.MobilePushNotification
dev.caskeleton.application.notification.platform.push.MobilePushNotifier
dev.caskeleton.application.notification.platform.push.ReceiptAuthorizationException
dev.caskeleton.application.notification.platform.push.ReceiptKind
dev.caskeleton.application.notification.platform.push.ReceiptResult
dev.caskeleton.application.notification.platform.security.AccessContext
dev.caskeleton.application.notification.platform.security.ContactPointProtector
dev.caskeleton.application.notification.platform.security.NotificationPayloadProtection
dev.caskeleton.application.notification.platform.security.NotificationPayloadUnreadableException
dev.caskeleton.application.notification.platform.security.NotificationRedactor
dev.caskeleton.application.notification.platform.security.ProtectedContactPoint
dev.caskeleton.application.notification.platform.security.SafeDiagnosticContext
dev.caskeleton.application.notification.platform.security.SecretKeyMaterial
dev.caskeleton.application.notification.platform.security.SecretMaterialProvider
dev.caskeleton.application.notification.platform.security.SecretPurpose
dev.caskeleton.application.notification.platform.security.SensitiveValueClassifier
dev.caskeleton.application.notification.platform.security.SensitiveValueKind
dev.caskeleton.application.notification.platform.security.UnsafeDiagnosticFieldException
dev.caskeleton.application.notification.platform.sms.E164PhoneNumberParser
dev.caskeleton.application.notification.platform.sms.GsmAlphabet
dev.caskeleton.application.notification.platform.sms.InvalidPhoneNumberException
dev.caskeleton.application.notification.platform.sms.SmsEncoding
dev.caskeleton.application.notification.platform.sms.SmsEstimate
dev.caskeleton.application.notification.platform.sms.SmsNotification
dev.caskeleton.application.notification.platform.sms.SmsNotifier
dev.caskeleton.application.notification.platform.sms.SmsSegmentEstimator
dev.caskeleton.application.notification.platform.template.NotificationTemplateRenderer
dev.caskeleton.application.notification.platform.template.NotificationTemplateVersion
dev.caskeleton.application.notification.platform.template.RenderCommand
@@ -553,5 +419,3 @@ dev.caskeleton.application.notification.platform.template.TemplateStatus
dev.caskeleton.application.notification.platform.template.TemplateVariableValidator
dev.caskeleton.application.notification.platform.template.TemplateVersionConflictException
dev.caskeleton.application.notification.platform.template.VariableSchema
dev.caskeleton.application.notification.platform.webpush.WebPushNotification
dev.caskeleton.application.notification.platform.webpush.WebPushNotifier
+1 -1
View File
@@ -104,7 +104,7 @@ the three they achieved.
one thing — `AesGcmCallbackPayloadProtection`, which protects raw callback bodies — and by nothing on
the accept path. Demanding it would make a deployment supply a key that protects nothing while the
payload it appears to be about stays in plaintext. The repository already has one defect of that
exact shape: `backend.graphql.cursor.key-ids`, which production refuses to start without and which no
exact shape: `backend.graphql.cursor.key-ids` (key removed 2026-09-25), which production refuses to start without and which no
code signs a cursor with (GQL-INT-003). Adding a second would make the pattern a habit.
## Consequence
+12 -6
View File
@@ -1,20 +1,25 @@
# Configuration reference
The notification delivery platform binds under `ca-skeleton.notification.platform`. The tree lives in
`src/app-bootstrap/src/main/resources/application.yml`, disabled by default, and every value carries
an inline default so a deployment that leaves the platform off supplies nothing.
`src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`,
which the support leaf's `ModuleDefaultsEnvironmentPostProcessor` loads at the lowest precedence,
so an application without the module carries none of it. The module is in no default composition: a
service selects it with `runtimeOnly project(':composition:notification-platform')` (plus the
persistence-jpa line) in `app-bootstrap/build.gradle`, and it is on when present. Every value carries
an inline default, so a deployment that switches the platform off supplies nothing.
Until 2026-08-15 this page named properties the binding did not have — `max-retry-concurrency`,
`scheduler-poll-interval`, `callback-worker-concurrency` — and omitted three it did. There was no
tree in `application.yml` at all, so the only way to configure the platform was to guess environment
variable names from Boot's relaxed binding. `./gradlew verifyNotificationConfiguration` now fails
when this page, the YAML tree and `docs/registries/env-keys.yaml` disagree.
variable names from Boot's relaxed binding. `NotificationEnvironmentRegistryTest`
(`:composition:notification-platform:test`) now fails when the shipped YAML and
`docs/registries/env-keys.yaml` disagree.
## Master switch
| Property | Environment variable | Default | Meaning |
|---|---|---|---|
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `false` | Binds nothing at all while false: no runtime, no schema check, no scheduler thread, no secret required |
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `true` | On while the module is present. `false` binds nothing at all: no runtime, no schema check, no scheduler thread, no secret required |
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch |
## Dispatch
@@ -40,7 +45,7 @@ still waiting on gets claimed by a second worker, and the recipient receives the
|---|---|---|---|
| `callbacks.enabled` | `APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED` | `false` | boolean |
| `callbacks.max-body-bytes` | `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES` | `65508` | 1..65508 |
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `5m` | positive |
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `5m` | positive; SNS messages whose `Timestamp` is further than this from receipt, either way, are rejected |
| `callbacks.trusted-proxies` | `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` | *(empty)* | CSV of peer addresses |
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다.
@@ -87,6 +92,7 @@ An enabled SES profile adds a typed `ses` block:
| `ses.sender-identity` | verified SES From identity |
| `ses.access-key-id` | AWS access key id; identifier only, not secret material |
| `ses.configuration-set` | optional SES configuration-set name |
| `ses.allowed-topic-arns` | SNS topic ARNs whose SES events this profile accepts (`APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`, comma-separated). Required when `callbacks.enabled=true`: binding fails without it, because a valid SNS signature only proves AWS sent the message and anyone can own a topic |
| `credential-profile` | key id for the secret access-key material; generation 1 is activated at assembly |
The shipped reference profile is `providers.ses` and is disabled by default. It is controlled by
+1 -1
View File
@@ -6,7 +6,7 @@
"ran no restart, and a provider sandbox job whose entire body was two echo statements behind",
"continue-on-error. So the strongest claim in the document rested on the weakest evidence in",
"the pipeline, and nothing connected the two.",
"verifyNotificationEvidence reads this file, checks that every claim marked satisfied names",
"NotificationEvidenceVerifierTest reads this file, checks that every claim marked satisfied names",
"test classes that exist, and refuses a grade whose claims are not all satisfied."
],
"claims": {
+4 -6
View File
@@ -37,11 +37,9 @@ R1 public type 100개를 어떻게 할 것인지 다루지 않았다. 그래서
문서 어디에도 답이 없었다.
- **canonical은 `..notification.platform..`이다.** NOTIF-ADR-005가 근거와 함께 정한다.
- **application R1 public contract는 남지만 새 production consumer를 받지 않는다.** 삭제 계획은
별개이며, R0 삭제와 함께 사라지지 않는다.
- **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은
단순 알림 포트 `NotificationPort`·`Notification`·`NotificationChannel`뿐이다.
- R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의
`catalog/`, `provider/`, `template/` 실험 구현은 제거했다. 실제 runtime은
`catalog/`, `provider/`, `template/` 실험 구현도 제거했다. 실제 runtime은
`dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
- **전수 분류표는 `docs/notification/module-mapping.md`에 있다** (replace / bridge / retain / delete).
- **두 namespace 간 production dependency는 0건이며 ArchUnit이 강제한다.** 변환이 필요하면
`dev.caskeleton.application.notification.compatibility.r1` 한 곳에만 둔다.
- 삭제 목록과 마지막 커밋은 `docs/capability-status.md`의 「제거된 코드」 표에 있다.
+16 -31
View File
@@ -30,13 +30,9 @@ that owns its responsibility. No public contract, evidence rule, or reliability
| `notification-policy` | `application-core` | `…platform.policy` |
| `notification-provider-spi` | `application-core` | `…platform.provider` |
| `notification-callback-api` | `application-core` | `…platform.callback` |
| `notification-email-api` | `application-core` | `…platform.email` |
| `notification-sms-api` | `application-core` | `…platform.sms` |
| `notification-push-api` | `application-core` | `…platform.push` |
| `notification-webpush` (API half) | `application-core` | `…platform.webpush` |
| `notification-inbox-api` | `application-core` | `…platform.inbox` |
| `notification-admin-api` | `application-core` | `…platform.admin` |
| `notification-security` (ports + redaction) | `application-core` | `…platform.security` |
| `notification-security` (ports) | `application-core` | `…platform.security` |
| `notification-observability` (ports) | `application-core` | `…platform.observation` |
| `notification-dispatch-runtime` | `adapter:outbound:notification` | `dev.caskeleton.adapter.outbound.notification.platform.dispatch` |
| `notification-security` (AES-GCM/HMAC impl) | `adapter:outbound:notification` | `…platform.security` |
@@ -50,12 +46,12 @@ that owns its responsibility. No public contract, evidence rule, or reliability
| `notification-webhook-extension` | `adapter:outbound:notification` | `…platform.provider.webhook` |
| `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` |
| `notification-admin-runtime` | `adapter:outbound:notification` | `…platform.admin` |
| `notification-reactor` | `adapter:outbound:notification` | `…platform.reactor` |
| `notification-spring-boot-starter` | `adapter:outbound:notification` | `…platform.autoconfigure` |
| `notification-persistence-jpa` | `adapter:outbound:persistence-jpa` | `dev.caskeleton.adapter.outbound.persistence.notification.platform` |
| `notification-inbox-jpa` | `adapter:outbound:persistence-jpa` | `…persistence.notification.platform.inbox` |
| `notification-callback-mvc` | `adapter:inbound:web` | `dev.caskeleton.adapter.inbound.web.notification.platform.callback` |
| `notification-callback-webflux` | `adapter:inbound:web` | `…callback.reactive` |
| `notification-callback-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.callback` |
| `notification-submission-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.submission` |
| application composition (use cases, callback bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` |
| `notification-testkit` | test source sets of the owning leaves | `…platform.testkit` |
## Dependency-direction consequences
@@ -66,9 +62,11 @@ by the leaf DAG that the registry already enforces:
```text
application-core (all *-api, provider SPI, policy, callback contracts)
↑ ↑ ↑
adapter:outbound:notification adapter:outbound:persistence-jpa adapter:inbound:web
↑ ↑ ↑
app-bootstrap
adapter:outbound:notification adapter:outbound:persistence-jpa adapter:inbound:web-notification
↑ ↑ (→ adapter:inbound:web)
└──────────── composition:notification-platform ────┘
↑
app-bootstrap (one line)
```
Two plan edges cannot be expressed as project edges in this repository, and are replaced by ports:
@@ -111,24 +109,11 @@ reachability is SMTP and SES for dispatch, with SES also available for callback
provider packages are extension assets until a composition contributes a `ProviderRuntimeAssembler`
with the settings and secret sources that family requires. See `support-matrix.md` for the explicit table.
## R1 public type disposition (NOTIF-ADR-005)
## R1 public types (NOTIF-ADR-005)
NOTIF-ADR-005 makes `..notification.platform..` canonical and keeps the R1 namespace in place
without new consumers. The ADR owns the rule; this table owns the list, so the two do not drift
apart by being written twice.
`NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER` in `ApplicationBoundaryArchitectureTest` enforces the
boundary: production dependencies between the two namespaces are zero, and the only permitted
exception is `dev.caskeleton.application.notification.compatibility.r1`.
| Disposition | Meaning | Types |
| --- | --- | --- |
| `replace` (27) | the platform has an equivalent; new consumers use it | `ApplyNotificationReceiptCommand`, `ApplyNotificationReceiptResult`, `ApplyNotificationReceiptUseCase`, `Channel`, `InlineNotificationAttemptPort`, `NormalizedNotificationReceiptCommand`, `NotificationAttemptId`, `NotificationDeliveryId`, `NotificationDeliveryStorePort`, `NotificationDispatchCommand`, `NotificationDispatchResult`, `NotificationDispatchUseCase`, `NotificationEvidenceTrustSnapshot`, `NotificationFrozenPlan`, `NotificationPlanPort`, `NotificationPlanningResult`, `NotificationProviderAttemptPort`, `NotificationReceiptEventId`, `NotificationReceiptFact`, `NotificationReceiptIngressCapabilityDescriptor`, `NotificationReceiptProjection`, `NotificationReceiptStorePort`, `NotificationSignedEvidenceHeader`, `NotificationWriterInventoryEvidence`, `NotificationWriterInventoryEvidenceVerifierPort`, `ProviderAttemptOutcome`, `TargetAttemptOutcome` |
| `bridge` (28) | conversion needed if an R1 caller remains; conversion lives only in the ACL | `InitializeNotificationWriterFencesCommand`, `InitializeNotificationWriterFencesOperation`, `InitializeNotificationWriterFencesResult`, `InitializeNotificationWriterFencesUseCase`, `NotificationAdmissionGateCommand`, `NotificationAdmissionGateUseCase`, `NotificationAppendResult`, `NotificationLegacyWriterPermitCommand`, `NotificationLegacyWriterPermitResult`, `NotificationLegacyWriterPermitUseCase`, `NotificationMaintenanceCommand`, `NotificationMaintenanceResult`, `NotificationMaintenanceUseCase`, `NotificationOperationsSnapshot`, `NotificationOperationsSnapshotQuery`, `NotificationOperationsSnapshotUseCase`, `NotificationRequestResult`, `ReconcileNotificationDeliveriesCommand`, `ReconcileNotificationDeliveriesResult`, `ReconcileNotificationDeliveriesUseCase`, `SwitchNotificationWriterOwnershipCommand`, `SwitchNotificationWriterOwnershipOperation`, `SwitchNotificationWriterOwnershipResult`, `SwitchNotificationWriterOwnershipUseCase`, `TerminalizeExpiredNotificationWriterPermitsCommand`, `TerminalizeExpiredNotificationWriterPermitsOperation`, `TerminalizeExpiredNotificationWriterPermitsResult`, `TerminalizeExpiredNotificationWriterPermitsUseCase` |
| `retain` (45) | a concern the platform does not cover; left as it is | `ConsentCheckMode`, `EmailRecipientReference`, `Notification`, `NotificationAdmissionClass`, `NotificationAdmissionReadinessPort`, `NotificationApplicationException`, `NotificationCanonicalWriterFenceGuard`, `NotificationCanonicalWriterFencePort`, `NotificationCanonicalWriterRouteSet`, `NotificationCapabilityCompatibilityValidator`, `NotificationChannel`, `NotificationFaultScope`, `NotificationIntentAppendPort`, `NotificationIntentDraft`, `NotificationIntentId`, `NotificationKindId`, `NotificationKindPolicy`, `NotificationMaintenanceStorePort`, `NotificationMode`, `NotificationOperationsSnapshotPort`, `NotificationPort`, `NotificationProviderCapabilityDescriptor`, `NotificationReasonCode`, `NotificationRecipientReference`, `NotificationReconciliationPort`, `NotificationRouteId`, `NotificationRouteStrategy`, `NotificationStoreCapabilityDescriptor`, `NotificationTechnicalSuppressionPort`, `NotificationTemplateParameters`, `NotificationTemplateRef`, `NotificationTemplateValue`, `NotificationWriterCutoverPort`, `NotificationWriterOwnership`, `NotificationWriterQuiescenceAttestationPort`, `NotificationWriterRouteSet`, `RecordNotificationWriterQuiescenceAttestationCommand`, `RecordNotificationWriterQuiescenceAttestationOperation`, `RecordNotificationWriterQuiescenceAttestationResult`, `RecordNotificationWriterQuiescenceAttestationUseCase`, `RetryDisposition`, `SignedNotificationWriterInventoryManifest`, `SignedNotificationWriterQuiescenceManifest`, `SlackAudienceReference`, `SubmissionCertainty` |
Total: 100 public types, every one classified.
No type carries `@Deprecated(forRemoval = true)`: no removal release is fixed, and
`forRemoval` without a date is a promise the codebase cannot keep. The boundary is
enforced by the ArchUnit rule instead.
NOTIF-ADR-005 made `..notification.platform..` canonical. The R1 types directly under
`dev.caskeleton.application.notification` had no production consumer and were removed on
2026-09-25, together with the ArchUnit rule that kept the two namespaces apart. What remains there
is the simple notification port the adapter core implements — `NotificationPort`, `Notification`,
`NotificationChannel`. The removed types and their last commit are listed in
`docs/capability-status.md` under "제거된 코드".
+2 -4
View File
@@ -28,10 +28,8 @@ would turn every historical row into a tag failure at read time.
Addresses, tokens, Web Push endpoints and keys, message bodies, template variables, provider
credentials, unsubscribe tokens, attachment URLs, raw callback payloads and raw provider request ids.
Two mechanisms enforce this rather than convention:
- `CardinalityGuard` validates every metric tag against a closed allowlist.
- `SafeDiagnosticContext` rejects any structured-diagnostic field outside its allowlist.
`CardinalityGuard` enforces this for metrics rather than convention: it validates every metric tag
against a closed allowlist.
An allowlist rather than a denylist, because the failure mode of a denylist is that the one field
nobody thought of is the one that leaks.
+3 -3
View File
@@ -4,8 +4,8 @@ What each channel can actually prove, and what the platform refuses to claim.
The grade column is not an opinion. `docs/notification/evidence-manifest.json` declares which claims
each grade requires and which executable artifact proves each claim, and
`./gradlew verifyNotificationEvidence` refuses a grade whose claims are not all backed by a file that
exists. Raising a grade means adding the artifact first.
`NotificationEvidenceVerifierTest` (in `:adapter:outbound:notification:test`) refuses a grade whose
claims are not all backed by a file that exists. Raising a grade means adding the artifact first.
Five channels read `Stable` until 2026-08-15. Nothing in the pipeline had ever sent a request to a
provider — the sandbox job's whole body was two `echo` statements behind `continue-on-error` — and
@@ -32,7 +32,7 @@ implementation is selectable in the default composition. Dispatch reachability i
| Provider family | Dispatch assembler in shipped composition | Callback assembler | Current use |
|---|---|---|---|
| SMTP | **yes** | no | EMAIL dispatch reference family |
| SES | **yes** | **yes** | EMAIL dispatch + SNS callback ingestion; disabled reference profile ships in `config/notification.yml` |
| SES | **yes** | **yes** | EMAIL dispatch + SNS callback ingestion; disabled reference profile ships in `config/module-defaults/notification.yml` (`composition:notification-platform`) |
| Twilio | no | no | contract implementation / extension wiring |
| FCM | no | no | contract implementation / extension wiring |
| APNs | no | no | contract implementation / extension wiring |
-14
View File
@@ -131,19 +131,5 @@ fields:
env: APP_OBJECT_STORAGE_LEGACY_PATH_STYLE_ACCESS
- field: legacy.auto-create-bucket
env: APP_OBJECT_STORAGE_LEGACY_AUTO_CREATE_BUCKET
- field: legacy-adoption.enabled
env: APP_OBJECT_STORAGE_LEGACY_ADOPTION_ENABLED
- field: legacy-adoption.mode
env: APP_OBJECT_STORAGE_LEGACY_ADOPTION_MODE
- field: legacy-adoption.report-path
env: APP_OBJECT_STORAGE_LEGACY_ADOPTION_REPORT_PATH
- field: legacy-adoption.reviewed-manifest-path
env: APP_OBJECT_STORAGE_LEGACY_ADOPTION_REVIEWED_MANIFEST_PATH
- field: legacy-adoption.reviewed-manifest-sha256
env: APP_OBJECT_STORAGE_LEGACY_ADOPTION_REVIEWED_MANIFEST_SHA256
- field: legacy-adoption.batch-size
env: APP_OBJECT_STORAGE_LEGACY_ADOPTION_BATCH_SIZE
- field: legacy-adoption.operation-timeout
env: APP_OBJECT_STORAGE_LEGACY_ADOPTION_OPERATION_TIMEOUT
- field: scan-maintenance.enabled
env: APP_OBJECT_STORAGE_SCAN_MAINTENANCE_ENABLED
+1 -1
View File
@@ -1,6 +1,6 @@
# Command policy
`src/adapter/outbound/cache-redis/src/main/resources/redis-sdk/redis-command-policy.yml` is the
`src/adapter/outbound/redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml` is the
single source of truth for what this SDK is willing to do with each Redis command. Official server
metadata decides what a command *is*; this file decides what we allow.
+7 -3
View File
@@ -7,12 +7,16 @@ exists because skipping it produces a specific failure that only shows up in pro
## 1. Command metadata diff
Run the catalog drift check against the new server. Every command the server reports must be
classified in `src/adapter/outbound/cache-redis/src/main/resources/redis-sdk/redis-command-policy.yml`.
Compare `COMMAND DOCS` / `COMMAND INFO` from the new server with the policy by hand: every command
the server reports must be classified in
`src/adapter/outbound/redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`, and every
key specification, ACL category and deprecation the policy relies on must still match. There is no
automated diff: `RedisCommandMetadataDiff` compared against server metadata nothing ever fetched,
and was removed (see `docs/capability-status.md`).
*Why:* an unclassified command is refused by `CommandPolicyGuard`, so a server that grew a command
does not create a hole — but a command whose **risk changed upstream** and is still classified R1
here does. The diff is what surfaces that.
here does. The comparison is what surfaces that.
## 2. ACL regression
+84 -707
View File
@@ -1,7 +1,7 @@
# Registry: Env Keys
# Schema owner: feature-contract-registry-governance
# Owner branch: feature-env-driven-runtime-configuration
# Last updated: 2026-07-28
# Last updated: 2026-09-25
#
# Conventions:
# - Application-owned env uses `APP_` prefix, fully unified (D2, 2026-06-05):
@@ -1603,8 +1603,8 @@ env_keys:
required_test: rate-limit-contract:cleanup-grace-bounded
- name: APP_IDEMPOTENCY_TTL
# source: feature-rate-limit-idempotency-contract 2026-05-22
# "idempotency TTL default = 24h. long-running use case는 use case 선언으로 72h까지 override 가능"
# ca-skeleton.capabilities.idempotency.replay-ttl: how long a completed response stays
# replayable. One value for every provider; IdempotencySettings refuses more than 72h at startup.
type: duration
default: 24h
allowed_values: null
@@ -1617,17 +1617,21 @@ env_keys:
required_test: idempotency-contract:ttl-applied
- name: APP_IDEMPOTENCY_PROVIDER
# postgresql selects the owner-safe V2 store on the primary data source. Provider selection is
# explicit and disabled by default; no implementation wins merely by being on the classpath.
# ca-skeleton.capabilities.idempotency.provider. redis and postgresql each contribute only the
# store; app-bootstrap builds the one IdempotencyExecutor and refuses startup unless exactly one
# store exists. postgresql uses the primary data source, applies its Flyway streams at startup
# and refuses a non-PostgreSQL data source, so bootRunH2 runs with disabled or redis. Selection
# is explicit and disabled by default; no implementation wins merely by being on the classpath.
# 2026-09-25: jdbc (the V1 store) was removed; a deployment still setting it fails to bind.
type: enum
default: disabled
allowed_values: [disabled, jdbc, redis, postgresql]
allowed_values: [disabled, redis, postgresql]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: redis-production-capability-completion
validation: enum_strict
compatibility_impact: additive
compatibility_impact: breaking
required_test: redis-idempotency-contract:provider-exclusive
- name: APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET
@@ -1756,14 +1760,16 @@ env_keys:
required_test: redis-cache:canonical-cache-role-composition
- name: APP_REDIS_ENABLED
# The single global Redis activation switch (property app.redis.enabled).
# 2026-09-25 capability packaging: the cache-redis module is on when present (its
# config/module-defaults/cache-redis.yml maps this key with default true); false is the explicit
# off. Absent from the build is the ordinary off state.
# False loads no Redis settings, requires no Redis secret, and creates no client, connection,
# thread or health contributor. Role selectors choose which capabilities compose once Redis is
# on; none of them is a second master switch.
# on; none of them is a second on/off key.
property: app.redis.enabled
owner_module: app-bootstrap
owner_module: adapter-outbound-cache-redis
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -1772,7 +1778,7 @@ env_keys:
owner_branch: redis-optionality-and-composition
validation: boolean_strict
compatibility_impact: behavior-change
required_test: redis-optionality:global-switch-off-creates-nothing
required_test: redis-capability-activation:the-switch-off-leaves-no-redis-bean-and-needs-no-redis
- name: APP_CACHE_REDIS_POSITIVE_HARD_TTL
@@ -1879,52 +1885,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_ADVANCED_ENABLED
property: app.redis.advanced.enabled
owner_module: adapter-outbound-redis-runtime
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: boolean_strict
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_ADVANCED_POLICIES
property: app.redis.advanced.policies
owner_module: adapter-outbound-redis-runtime
type: csv
default: ""
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: csv_nonempty
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_BLOCKING_MAX_BLOCK
# Hard ceiling on a server-side block; zero would be unbounded.
property: app.redis.blocking.max-block
owner_module: adapter-outbound-redis-runtime
type: duration
default: "30s"
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: duration_strict
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_BLOCKING_MAX_CONNECTIONS
property: app.redis.blocking.max-connections
owner_module: adapter-outbound-redis-runtime
@@ -1956,171 +1916,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_BATCH_COMMANDS
property: app.redis.limits.max-batch-commands
owner_module: adapter-outbound-redis-runtime
type: integer
default: 500
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_BATCH_REPLY_BYTES
property: app.redis.limits.max-batch-reply-bytes
owner_module: adapter-outbound-redis-runtime
type: integer
default: 16777216
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_BATCH_REQUEST_BYTES
property: app.redis.limits.max-batch-request-bytes
owner_module: adapter-outbound-redis-runtime
type: integer
default: 4194304
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_BITMAP_OFFSET
property: app.redis.limits.max-bitmap-offset
owner_module: adapter-outbound-redis-runtime
type: integer
default: 10000000
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_COLLECTION_ELEMENTS
property: app.redis.limits.max-collection-elements
owner_module: adapter-outbound-redis-runtime
type: integer
default: 1000
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_HASH_FIELD_VALUE_BYTES
property: app.redis.limits.max-hash-field-value-bytes
owner_module: adapter-outbound-redis-runtime
type: integer
default: 524288
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_KEY_BYTES
property: app.redis.limits.max-key-bytes
owner_module: adapter-outbound-redis-runtime
type: integer
default: 512
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_SCAN_COUNT
property: app.redis.limits.max-scan-count
owner_module: adapter-outbound-redis-runtime
type: integer
default: 500
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_STREAM_PAYLOAD_BYTES
property: app.redis.limits.max-stream-payload-bytes
owner_module: adapter-outbound-redis-runtime
type: integer
default: 262144
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_MAX_VALUE_BYTES
property: app.redis.limits.max-value-bytes
owner_module: adapter-outbound-redis-runtime
type: integer
default: 1048576
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_LIMITS_OFFLINE_QUEUE_COMMANDS
property: app.redis.limits.offline-queue-commands
owner_module: adapter-outbound-redis-runtime
type: integer
default: 1000
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_MODE
# standalone | sentinel | cluster.
property: app.redis.mode
@@ -2198,67 +1993,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_RAW_CREDENTIAL_REFERENCE
property: app.redis.raw.credential-reference
owner_module: adapter-outbound-redis-runtime
type: string
default: null
allowed_values: null
classification: sensitive-config
required: false
required_when: app.redis.raw.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: nonblank_when_required
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_RAW_ENABLED
property: app.redis.raw.enabled
owner_module: adapter-outbound-redis-runtime
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: boolean_strict
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_RAW_POLICY_RESOURCE
# Classpath resource listing every approved raw command. Absent resource fails startup.
property: app.redis.raw.policy-resource
owner_module: adapter-outbound-redis-runtime
type: string
default: "classpath:redis-sdk/raw-command-allowlist.yml"
allowed_values: null
classification: public-config
required: false
required_when: app.redis.raw.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: nonblank_when_required
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_TIMEOUT_ADMIN
property: app.redis.timeout.admin
owner_module: adapter-outbound-redis-runtime
type: duration
default: "3s"
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: duration_strict
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_TIMEOUT_BATCH
property: app.redis.timeout.batch
owner_module: adapter-outbound-redis-runtime
@@ -2274,21 +2008,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_TIMEOUT_COLLECTION
property: app.redis.timeout.collection
owner_module: adapter-outbound-redis-runtime
type: duration
default: "2s"
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: duration_strict
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_TIMEOUT_FAST
# Single-key command profile; above 5s produces a startup warning.
property: app.redis.timeout.fast
@@ -2406,21 +2125,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_BYTES
property: app.redis.capacity.maximum-in-flight-bytes
owner_module: adapter-outbound-cache-redis
type: integer
default: null
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_COMMANDS
property: app.redis.capacity.maximum-in-flight-commands
owner_module: adapter-outbound-cache-redis
@@ -2452,21 +2156,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-runtime:script-lane-physical-connections-bounded
- name: APP_REDIS_CAPACITY_MAXIMUM_REPLY_BYTES
property: app.redis.capacity.maximum-reply-bytes
owner_module: adapter-outbound-cache-redis
type: integer
default: null
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_CAPACITY_REJECT_WHEN_DISCONNECTED
# True refuses commands while disconnected. False restores the driver offline queue, which replays a burst of writes on reconnect in arbitrary order relative to the outage.
property: app.redis.capacity.reject-when-disconnected
@@ -2514,6 +2203,7 @@ env_keys:
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_LIFECYCLE_ACQUIRE_TIMEOUT
# How long a lane borrow waits for a returned connection before it is refused as not sent.
property: app.redis.lifecycle.acquire-timeout
owner_module: adapter-outbound-cache-redis
type: duration
@@ -2604,21 +2294,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_LIFECYCLE_TLS_HANDSHAKE_TIMEOUT
property: app.redis.lifecycle.tls-handshake-timeout
owner_module: adapter-outbound-cache-redis
type: duration
default: "3s"
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: duration_strict
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_PUBSUB_BUFFER_CAPACITY
property: app.redis.pubsub.buffer-capacity
owner_module: adapter-outbound-cache-redis
@@ -2634,22 +2309,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_PUBSUB_OVERFLOW_POLICY
# error | drop-oldest | drop-latest.
property: app.redis.pubsub.overflow-policy
owner_module: adapter-outbound-cache-redis
type: string
default: "error"
allowed_values: [error, drop-oldest, drop-latest]
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: nonblank_when_required
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_SENTINEL_CREDENTIAL_REFERENCE
property: app.redis.sentinel.credential-reference
owner_module: adapter-outbound-cache-redis
@@ -3264,7 +2923,8 @@ env_keys:
# (app.messaging.broker=<brokerId>); blank = messaging disabled. Replaces the former
# Kafka-binary APP_MESSAGING_KAFKA_ENABLED. Adding a broker is new files only.
type: string
default: null
# The Kafka module's config/module-defaults/messaging.yml defaults it to kafka, the only registered broker.
default: kafka
allowed_values: null
classification: public-config
required: false
@@ -3292,6 +2952,8 @@ env_keys:
- name: APP_MESSAGING_KAFKA_BROKERS
# source: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter"
# (broker 활성화 시 endpoint 필요)
# Also feeds spring.kafka.bootstrap-servers (the messaging platform's Kafka transport) through
# the Kafka module's config/module-defaults/messaging.yml, so one key addresses both paths.
type: csv_list
default: null
allowed_values: null
@@ -3331,90 +2993,9 @@ env_keys:
compatibility_impact: behavior-change
required_test: adapter-contract:notification-email-provider-selection
- name: APP_FILESERVER_ENABLED
# source: Fileserver R2 control-plane/provider-selection design 2026-07-28.
# Disabled is the shipped safe default. Enabling requires every local attestation
# value below and an exact app.fileserver destination/provider graph.
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: fileserver-r2-control-plane-provider-selection
validation: boolean_strict
compatibility_impact: additive
required_test: fileserver-r2:disabled-default-and-enabled-attestation
- name: APP_FILESERVER_LOCAL_ROOT
# Pre-provisioned local-persistent root. The runtime additionally attests real
# path, ancestor/root symlinks, owner/mode, FileStore, sentinel, and capabilities.
type: string
default: null
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: fileserver-r2-control-plane-provider-selection
validation: absolute_existing_directory_when_app_fileserver_enabled
compatibility_impact: additive
required_test: fileserver-r2:disabled-default-and-enabled-attestation
- name: APP_FILESERVER_LOCAL_EXPECTED_FILE_STORE_NAME
# Exact FileStore.name() expected for the pre-provisioned root.
type: string
default: null
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: fileserver-r2-control-plane-provider-selection
validation: non_empty_string_when_app_fileserver_enabled
compatibility_impact: additive
required_test: fileserver-r2:disabled-default-and-enabled-attestation
- name: APP_FILESERVER_LOCAL_EXPECTED_FILE_STORE_TYPE
# Exact FileStore.type() expected for the pre-provisioned root.
type: string
default: null
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: fileserver-r2-control-plane-provider-selection
validation: non_empty_string_when_app_fileserver_enabled
compatibility_impact: additive
required_test: fileserver-r2:disabled-default-and-enabled-attestation
- name: APP_FILESERVER_LOCAL_MOUNT_SENTINEL_SHA256
# Lowercase SHA-256 of the operator-created .ca-fileserver-volume sentinel.
type: string
default: null
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: fileserver-r2-control-plane-provider-selection
validation: lowercase_sha256_when_app_fileserver_enabled
compatibility_impact: additive
required_test: fileserver-r2:disabled-default-and-enabled-attestation
- name: APP_FILESERVER_LOCAL_EXPECTED_OWNER
# Exact filesystem owner expected for the attested root and private namespace.
type: string
default: null
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: fileserver-r2-control-plane-provider-selection
validation: non_empty_string_when_app_fileserver_enabled
compatibility_impact: additive
required_test: fileserver-r2:disabled-default-and-enabled-attestation
# === HTTP Client platform (app.httpclient.*) ===
#
# Only the master switch is registered here. The per-client surface is an indexed list whose
# Only the enabled key is registered here. The per-client surface is an indexed list whose
# element cannot be templated in application.yml without materialising a nameless client in every
# deployment, so it has no deployment-independent value for this registry to hold and is
# registered in docs/httpclient/env-fields.yaml instead. That manifest is derived from
@@ -3422,11 +3003,14 @@ env_keys:
# HttpClientPlatformEnvManifestTest, and an APP_HTTPCLIENT_ variable with no field fails startup.
- name: APP_HTTPCLIENT_ENABLED
# Master switch. While false the platform block is not bound at all: the auto-configuration that
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
# this key with default true); false is the explicit off. Absent from the build is the
# ordinary off state.
# While false the platform block is not bound at all: the auto-configuration that
# binds it is not processed, so no bean, connection pool, TLS context, credential, thread or
# gateway exists, and a malformed HTTP client setting cannot fail this deployment's startup.
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -3451,16 +3035,15 @@ env_keys:
required_test: httpclient-platform:off-state-zero-side-effects-and-env-manifest-parity
# === Fileserver HTTP platform (app.fileserver-platform.*) ===
#
# A different capability from the app.fileserver R2 publication block above. Separate
# namespaces so the two cannot be switched on together by accident, and so a change to one
# cannot silently re-shape the other.
- name: APP_FILESERVER_PLATFORM_ENABLED
# Master switch. While false the platform block is not bound at all: the auto-configuration that
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
# this key with default true); false is the explicit off. Absent from the build is the
# ordinary off state.
# While false the platform block is not bound at all: the auto-configuration that
# binds it is not processed, so no bean, route, thread, schema check or filesystem call exists.
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -3948,7 +3531,7 @@ env_keys:
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
- name: APP_FILESERVER_PLATFORM_ADMIN_ENABLED
# Management plane, a separate decision from the data plane. Requires the master switch too:
# Management plane, a separate decision from the data plane. Requires APP_FILESERVER_PLATFORM_ENABLED too:
# enabling it alone now does nothing instead of half-building a bean graph.
type: boolean
default: false
@@ -4042,7 +3625,7 @@ env_keys:
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
- name: APP_FILESERVER_PLATFORM_TUS_ENABLED
# tus 1.0. Requires the master switch too.
# tus 1.0. Requires APP_FILESERVER_PLATFORM_ENABLED too.
type: boolean
default: false
allowed_values: [true, false]
@@ -4055,7 +3638,7 @@ env_keys:
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
- name: APP_FILESERVER_PLATFORM_HTTPBIS_DRAFT12_ENABLED
# Unratified draft whose contract can change without notice. Requires the master switch too.
# Unratified draft whose contract can change without notice. Requires APP_FILESERVER_PLATFORM_ENABLED too.
type: boolean
default: false
allowed_values: [true, false]
@@ -4197,12 +3780,14 @@ env_keys:
# supplies nothing. Reference: docs/notification/configuration.md.
- name: APP_PERSISTENCE_JPA_ENABLED
# source: five-adapter-runtime-remediation §5.1 — master switch for relational persistence.
# false means no DataSource, no entity scan, no repositories, no Hibernate, no Flyway and no DB
# health contributor; the old app.jpa-platform.enabled gated three add-on beans while reading
# like this one and defaulting to on.
# source: five-adapter-runtime-remediation §5.1 — switch for relational persistence, shipped by
# the persistence-jpa module itself (config/module-defaults/persistence-jpa.yml). The module is
# selected by one build line and is on while present; false switches off this module's beans
# (entity scan, repositories, stores, startup guards). Removing the build line removes the
# capability and this key's only reader. The old app.jpa-platform.enabled gated three add-on
# beans while reading like this one.
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -4287,9 +3872,12 @@ env_keys:
required_test: jpa-contract:hibernate-runtime-settings
- name: APP_PERSISTENCE_MONGO_ENABLED
# source: five-adapter-runtime-remediation §5.1 — master switch for MongoDB persistence.
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
# this key with default true); false is the explicit off. Absent from the build is the
# ordinary off state.
# source: five-adapter-runtime-remediation §5.1 — on/off key for MongoDB persistence.
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -4329,10 +3917,13 @@ env_keys:
required_test: adapter-contract:persistence-mongo-connection-source
- name: APP_MESSAGING_ENABLED
# source: five-adapter-runtime-remediation §5.1 — master switch for broker publication.
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
# this key with default true); false is the explicit off. Absent from the build is the
# ordinary off state.
# source: five-adapter-runtime-remediation §5.1 — on/off key for broker publication.
# APP_MESSAGING_BROKER selects which transport and is no longer the de-facto switch.
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -4347,10 +3938,13 @@ env_keys:
# decision and these rows do not imply runtime membership.
- name: APP_WEBSOCKET_ENABLED
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
# this key with default true); false is the explicit off. Absent from the build is the
# ordinary off state.
property: app.websocket.enabled
owner_module: adapter-inbound-websocket
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -4402,249 +3996,14 @@ env_keys:
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_ENABLED
property: app.websocket.platform.enabled
owner_module: adapter-inbound-websocket
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: boolean_strict
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_NODE_ID
property: app.websocket.platform.node-id
owner_module: adapter-inbound-websocket
type: string
default: local
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: non_empty_string
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_ALLOWED_ORIGINS
property: app.websocket.platform.allowed-origins
owner_module: adapter-inbound-websocket
type: csv
default: ""
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: explicit_http_origins_when_enabled
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_ALLOW_MISSING_ORIGIN
property: app.websocket.platform.allow-missing-origin
owner_module: adapter-inbound-websocket
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: boolean_strict
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_MAX_FRAME_BYTES
property: app.websocket.platform.max-frame-bytes
owner_module: adapter-inbound-websocket
type: integer
default: 65536
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_integer_with_platform_ceiling
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_MAX_MESSAGE_BYTES
property: app.websocket.platform.max-message-bytes
owner_module: adapter-inbound-websocket
type: integer
default: 524288
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_integer_with_platform_ceiling
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_MAX_FRAGMENTS
property: app.websocket.platform.max-fragments
owner_module: adapter-inbound-websocket
type: integer
default: 16
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_integer
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_MAX_BUFFERED_OUTBOUND_BYTES_PER_CONNECTION
property: app.websocket.platform.max-buffered-outbound-bytes-per-connection
owner_module: adapter-inbound-websocket
type: integer
default: 1048576
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_integer_with_platform_ceiling
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_MAX_BUFFERED_OUTBOUND_BYTES_PER_NODE
property: app.websocket.platform.max-buffered-outbound-bytes-per-node
owner_module: adapter-inbound-websocket
type: integer
default: 67108864
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_integer
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_MAX_CONNECTIONS_PER_ACTOR
property: app.websocket.platform.max-connections-per-actor
owner_module: adapter-inbound-websocket
type: integer
default: 4
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_integer
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_PING_INTERVAL
property: app.websocket.platform.ping-interval
owner_module: adapter-inbound-websocket
type: duration
default: 15s
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_duration
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_IDLE_TIMEOUT
property: app.websocket.platform.idle-timeout
owner_module: adapter-inbound-websocket
type: duration
default: 45s
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_duration
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_MAX_CONNECTION_AGE
property: app.websocket.platform.max-connection-age
owner_module: adapter-inbound-websocket
type: duration
default: 4h
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_duration
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_PLATFORM_TICKET_LIFETIME
property: app.websocket.platform.ticket-lifetime
owner_module: adapter-inbound-websocket
type: duration
default: 30s
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: positive_duration
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_ADVANCED_SOCKJS_ENABLED
property: app.websocket.advanced.sockjs.enabled
owner_module: adapter-inbound-websocket
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: boolean_strict
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_ADVANCED_STOMP_ENABLED
property: app.websocket.advanced.stomp.enabled
owner_module: adapter-inbound-websocket
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: boolean_strict
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_WEBSOCKET_ADVANCED_STOMP_RELAY_ENABLED
property: app.websocket.advanced.stomp.relay.enabled
owner_module: adapter-inbound-websocket
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: 2026-09-20-inbound-realtime-review-remediation
validation: boolean_strict
compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace
- name: APP_GRAPHQL_ENABLED
# source: five-adapter-runtime-remediation §5.1 — master switch for the GraphQL transport.
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
# this key with default true); false is the explicit off. Absent from the build is the
# ordinary off state.
# source: five-adapter-runtime-remediation §5.1 — on/off key for the GraphQL transport.
# false publishes no /graphql route, including the one Spring GraphQL would publish by itself.
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -4864,9 +4223,12 @@ env_keys:
compatibility_impact: behavior-change
required_test: adapter-contract:outbox-relay-dependency
- name: APP_NOTIFICATION_PLATFORM_ENABLED
# source: NTF-025 — master switch for the notification delivery platform; false binds nothing at all
# 2026-09-25 capability packaging: the notification-platform module is on when present (its
# config/module-defaults/notification.yml maps this key with default true); false is the
# explicit off and binds nothing at all. Absent from the build is the ordinary off state.
# source: NTF-025.
type: boolean
default: false
default: true
allowed_values: [true, false]
classification: public-config
required: false
@@ -5288,8 +4650,23 @@ env_keys:
compatibility_impact: additive
required_test: adapter-contract:notification-ses-provider-assembled
- name: APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS
# source: 2026-09-24 module review Critical #10 — SNS topics whose SES event callbacks the
# shipped SES profile accepts. A valid SNS signature only proves AWS sent the message and
# anyone can own a topic, so binding fails when callbacks are enabled and this is empty.
type: csv
default: ""
allowed_values: null
classification: security-relevant
required: false
reload_policy: restart-only
owner_branch: 2026-09-24-notification-critical-remediation
validation: non_empty_when_ses_and_callbacks_enabled
compatibility_impact: behavior-change
required_test: adapter-contract:notification-ses-callback-topic-allowlist
- name: APP_NOTIFICATION_PLATFORM_SMTP_ENABLED
# source: NTF-INT-001 — master switch of the shipped SMTP provider profile; false means assembly skips it entirely.
# source: NTF-INT-001 — on/off key of the shipped SMTP provider profile; false means assembly skips it entirely.
type: boolean
default: false
allowed_values: [true, false]
+4 -3
View File
@@ -348,12 +348,13 @@ metrics:
- name: event_type
cardinality_limit: 50
- name: outcome
cardinality_limit: 4
allowed_values: [PUBLISHED, FAILED, DEAD, IN_FLIGHT]
cardinality_limit: 5
# STALE: the relay's claim was taken over before its result could be written (V17 lease fence).
allowed_values: [PUBLISHED, FAILED, DEAD, IN_FLIGHT, STALE]
percentiles: null
histogram_buckets: null
alert_severity_thresholds:
p2: "FAILED rate > 1% for 10m"
p2: "FAILED rate > 1% for 10m, or STALE > 0 for 10m (in-flight timeout shorter than a relay stall)"
owner_branch: feature-domain-event-outbox-contract
log_field_mapping: [event_type, outcome, event_id]
compatibility_impact: additive
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+7 -5
View File
@@ -10,8 +10,10 @@
- 대응하는 Test 태스크 없음
- 공통 스키마 validator 없음
따라서 `config/messaging/readiness-cards.yaml`의 카드는 `verifyMessagingContracts`와
`verifyMessagingJsonSchemaV1` 두 개를 제외하면 모두 `maturity: not-implemented`다.
따라서 `config/messaging/readiness-cards.yaml`의 카드는 모두 `maturity: not-implemented`다.
유일하게 `implemented-candidate`였던 `json-schema-envelope.v1`은 그 구현(adapter messaging의
`JsonSchemaIntegrationEventEncoder`와 `verifyMessagingJsonSchemaV1`)을 2026-09-25에 삭제하면서
`not-implemented`로 내렸다. 남은 evidence producer는 `verifyMessagingContracts` 하나다.
## 왜 Gradle 태스크를 미리 만들어 두지 않는가
@@ -40,8 +42,8 @@ verifyMessagingTargetBindingPreflight
1. 각 시나리오를 실제로 실행하는 Test 태스크.
2. 그 실행 결과(JUnit XML)에서 payload-free manifest를 만드는 producer.
3. `config/messaging/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를
검증하는 finalizer.
검증하는 단계(build-tools `VerifyMessagingEvidenceTask`가 쓰고 바로 검증한다).
4. 위 셋이 모두 생긴 다음에 `verifyMessaging<Scenario>R2` 태스크 등록.
`gradle/qualification/messaging-qualification.gradle`의 `verifyMessagingJsonSchemaV1`이 그 네 단계를
모두 갖춘 예시다.
build-tools `MessagingQualificationPlugin`의 `verifyMessagingContracts`가 그 네 단계를 모두 갖춘
예시다.
+5 -4
View File
@@ -28,10 +28,11 @@ status: stub
2. broker 상태 확인: `APP_MESSAGING_BROKER` 값과 broker endpoint 가용성. 이 키는 활성화 스위치가
아니라 **선택자**다 — messaging을 끄는 것은 `APP_MESSAGING_ENABLED=false`이고, 이 값을 비운다고
messaging이 꺼지지는 않는다.
- `APP_MESSAGING_BROKER`가 공백인 채로 relay가 켜져 있으면 **애플리케이션이 기동하지 않는다**
(`OutboxRelayBrokerRequirementValidator`, MSG-024). 이 조합에서는 publish가 전부
`AdapterDisabledException`으로 실패하며 PENDING row가 DEAD까지 소진되기 때문이다.
기동 실패를 보고 있다면 broker를 설정하거나 `ca-skeleton.outbox.relay-enabled=false`로 둔다.
- relay 스케줄러는 발행 포트(`OutboxMessagePublishPort`, messaging bridge가 제공)가 있을 때만
생긴다. messaging을 고르지 않은 배포에서는 relay가 없고 PENDING row가 그대로 남는다(MSG-024의
"DEAD까지 소진"은 대역 publisher가 있던 때의 이야기다). messaging 모듈이 켜져 있는데
`APP_MESSAGING_BROKER`가 공백이면 기동이 거부된다(messaging `MessagingConfig`, messaging platform
`MessagingProviderSelection`) — broker를 설정하거나 messaging을 끈다.
- 기동은 했는데 실패가 쌓인다면 broker는 설정돼 있고 도달이 안 되는 것이다 — endpoint부터 본다.
3. `outbox.pending.size` status 분포 확인 (FAILED 누적 vs PENDING 누적)
+34 -36
View File
@@ -1,5 +1,14 @@
# GraphQL 인바운드 모듈 완전 해부
> **2026-09-25 이후 달라진 점**: `moduleboundary/`, `architecture/`, `compat/`, `release/`,
> `advanced/release/`, `GraphQlSchemaContractSuite`는 삭제됐다(`docs/capability-status.md` 제거 표).
> 부팅 시 컨트롤러 경계 검사는 `GraphQlTransportBoundaryArchitectureTest`(ArchUnit)로 옮겼다.
> 아래 §2·§18·§20.5·§21·§23.15의 해당 설명은 삭제 전 코드 기준이다.
> §25.1의 "shipped and gated" 배선도 끝났다. GraphQL은 기본 조립에 없고
> `runtimeOnly project(':adapter:inbound:graphql')` 한 줄로 고르며, 모듈이 있으면 켜진다
> (`APP_GRAPHQL_ENABLED` 기본 `true`, `false`면 Spring GraphQL 자동 설정까지 빠진다). §25.5의 끄는 장치
> 테스트도 삭제됐다.
> **성격**: 정책 문서가 아니라 **읽기 기록**이다. `adapter:inbound:graphql` leaf와 그 주변
> (app-bootstrap 배선, 테스트 레인, 아티팩트 게이트, 스모크 스크립트, ADR, 코드 리뷰 문서)에
> 실제로 구현되어 있는 것을 코드 기준으로 하나씩 확인하면서, "무엇이 있는가"와 "왜 그렇게
@@ -1498,26 +1507,24 @@ GraphQL 에러로 남는다.
top-level 에러 하나가 **모든 아이템의 결과를 버린다** — 성공했고 부수효과가 이미 일어난 것들까지.
그래서 `index`를 담아 클라이언트가 상관지을 수 있게 한다.
### 14.3 `GraphQlMutationIdempotencyContext` — 키 하나가 아니라 다섯 개의 스코프
### 14.3 mutation 멱등성 — 2026-09-25 삭제
```
actor × tenant × mutation coordinate × contract version × normalised input
```
GraphQL 전용 mutation 멱등성(`GraphQlMutationIdempotencyInterceptor`,
`GraphQlMutationIdempotencyContext`, `GraphQlIdempotencyKey`, `GraphQlIdempotencyConflictException`,
`GraphQlCanonicalInput`, `GraphQlExtensionsPolicy`의 `idempotencyKey` extension 허용,
`GraphQlMutationContractValidator.requireIdempotency`)은 저장소에 연결된 적이 없어서 삭제했다.
지금 기본 `GraphQlExtensionsPolicy`는 어떤 extension key도 허용하지 않는다.
| 축 | 없으면 |
|---|---|
| actor | 한 클라이언트의 재시도가 다른 클라이언트의 결과를 반환 |
| **tenant** | actor 정체성이 tenant를 함의하지 않음 — 같은 service account가 두 tenant에서 행동 가능 |
| mutation coordinate | 같은 키를 다른 mutation에 보내면 다른 오퍼레이션인데 같은 결과 |
| contract version | 계약이 바뀌면 같은 입력이 다른 의미 |
| normalised input | 같은 키에 다른 입력 = 두 개의 다른 부수효과 |
요청 재생 멱등성이 필요한 mutation은 transport가 아니라 use case 안에서 application
`IdempotencyExecutor`를 쓴다. 스코프는 `IdempotencyScopeDigest`(principal + 클라이언트 key +
operation code의 HMAC)로 만들고, mutation 하나를 멱등 단위로 잡는 원칙은 그대로다 — 한 GraphQL
요청이 여러 root mutation을 나를 수 있으므로 요청 전체를 한 단위로 다루면 전부 replay하거나 전부
안 하거나가 된다. 삭제된 인터셉터가 스코프에 넣던 축(actor, tenant, mutation, contract version,
정규화된 입력)은 digest를 만들 때 여전히 점검할 목록이다.
javadoc이 tenant를 왜 따로 두는지 명시한다: *"Tenant is part of the scope because actor identity
does not imply it."*
### 14.4 `GraphQlCanonicalInput` — 지문 충돌 사건 (삭제된 코드의 기록)
### 14.4 `GraphQlCanonicalInput` — 지문 충돌 사건
**이 leaf에서 가장 교육적인 버그다.**
**이 leaf에서 가장 교육적인 버그다.** 코드는 §14.3과 함께 삭제됐지만 교훈은 남긴다.
이전 정규형은 최상위 키를 정렬하고 `key=value;`로 조인했다. 두 개의 서로 다른 입력이 동일하게
정규화될 수 있었다:
@@ -1533,13 +1540,10 @@ does not imply it."*
§13.4의 커서 프레이밍 버그와 **같은 부류**다: 구분자를 값 안에서 구분할 수 없다. 그리고 같은
레포 안에서 두 번 일어났다. 이게 §27의 원칙 하나가 된다.
### 14.5 `GraphQlIdempotencyKey` — 양쪽이 다 묶인다
### 14.5 (삭제됨) `GraphQlIdempotencyKey`
8~128자. 이유가 양방향이다:
- **너무 짧으면** 무관한 요청 간에 충돌 → 한 호출자의 재시도가 다른 호출자의 결과를 반환
- **무제한이면** 저장·로깅 문제
`GraphQlIdempotencyConflictException`은 **키도 입력도 담지 않는다.**
§14.3 참고. 키 길이 제한(8~128자)을 두던 이유 — 너무 짧으면 무관한 요청끼리 충돌하고,
무제한이면 저장·로깅 문제가 생긴다 — 는 클라이언트 key를 받는 쪽이 여전히 지켜야 한다.
### 14.6 `GraphQlMutationContractValidator` — GraphQL의 serial 실행은 트랜잭션이 아니다
@@ -1558,12 +1562,6 @@ does not imply it."*
> *a transport-level retry would repeat a side effect the client never asked to repeat.*
`GraphQlMutationIdempotencyInterceptor`는 HTTP 요청이 아니라 **mutation 단위**로 스코프한다 —
한 GraphQL 요청이 여러 root mutation을 나를 수 있고, 요청 전체를 하나의 멱등 단위로 다루면
전부 replay하거나 전부 안 하거나가 된다.
현재 등급은 `modelled`다 — 이 인터셉터를 참조하는 configuration이 없다.
---
## 15. `fetch` — over-fetch를 막는 프로파일
@@ -2062,7 +2060,7 @@ override는 **의도적 호환성 레인에서만** 허용 — 조용히 하나
| DataLoader / batching | `wired` | `GraphQlBatchLoaderRegistrationTest` (**50 parent → 3 downstream**) |
| object 인가 | `modelled` | 실행 경로에 연결하는 configuration 없음 |
| **cursor 서명** | `modelled` | **auto-configuration이 `HmacGraphQlCursorCodec`도 `GraphQlCursorKeyRing`도 만들지 않음** — `GraphQlPolicyRequestPathTest`가 고정 |
| mutation 멱등성 | `modelled` | 인터셉터를 참조하는 configuration 없음 |
| mutation 멱등성 | 삭제됨 (2026-09-25) | use case 안에서 application `IdempotencyExecutor` 사용 (§14.3) |
| persisted operation | `modelled` | 중립 `OperationalRecordStorePort` 기반 레지스트리 + 방향성 테스트. durable 구현 미제공 |
| subscription / WebSocket / SSE / RSocket | `modelled` | 정책·상태기계 단위 테스트만. **Spring transport handler 없음 — 그래서 타입 이름도 `*Admission`이다** |
| federation / incremental / codegen / compat | `modelled` | 단위 테스트만 |
@@ -3024,13 +3022,13 @@ if grep -q '"errors"' /tmp/gql.json; then fail "the query returned GraphQL error
| 테스트 | 무엇 |
|---|---|
| `GraphQlDeploymentModeRegistryParityTest` | enum 목록과 운영자용 레지스트리 동기화 (§4.1) |
| `ShippedRuntimeFacadePresenceTest` | shipped facade 존재 |
| `FiveAdapterOffInventoryTest` | 다섯 어댑터 off 상태 인벤토리 |
| `CapabilityDependencyValidatorTest` | capability 의존 검증 |
| `RuntimeMembershipClasspathAgreementTest` | `runtime_memberships`와 실제 classpath 일치 |
| `GraphQlDeploymentModeRegistryParityTest` | enum 목록과 운영자용 레지스트리 동기화 (§4.1). 2026-09-25에 graphql leaf로 이동 |
| `ShippedRuntimeFacadePresenceTest` | shipped facade 존재 (2026-09-25 삭제) |
| `FiveAdapterOffInventoryTest` | 다섯 어댑터 off 상태 인벤토리 (2026-09-25 삭제) |
| `CapabilityDependencyValidatorTest` | capability 의존 검증 (2026-09-25 삭제) |
| `RuntimeMembershipClasspathAgreementTest` | `runtime_memberships`와 실제 classpath 일치 (삭제됨. `verifyRuntimeModuleRegistry`가 대신 본다) |
| `ConditionalTransportQualificationContractTest` | 조건부 전송 계약 |
| `AdapterActivationInventory` / `ShippedCompositionHarness` | 헬퍼 |
| `AdapterActivationInventory`(2026-09-25 삭제) / `ShippedCompositionHarness` | 헬퍼 |
`RuntimeMembershipClasspathAgreementTest`가 특히 §25.1의 drift를 잡아 줄 수 있는 위치다 —
레지스트리와 classpath는 일치하고, 산문 문서만 어긋나 있다.
@@ -3349,7 +3347,7 @@ javadoc 도구는 마지막 것만 연결한다. **`SPRING_DATA` 상수 다음,
|---|---|---|---|
| cursor 서명 | 완성 | 키 재료 출처 | P2 |
| object 인가 | 완성 (`ObjectAccessPolicy` + bridge) | 실행 경로 연결 configuration | **누가 `GraphQlObjectAuthorizationPort`를 제공하나** — leaf 기본값? adopter? |
| mutation 멱등성 | 완성 (5축 스코프) | 인터셉터 참조 configuration | **멱등성 레코드 저장소** — persisted operation과 같은 `OperationalRecordStorePort`를 쓸 수 있나? |
| mutation 멱등성 | 삭제됨 (2026-09-25) | — | 없음. 필요한 mutation은 use case 안에서 application `IdempotencyExecutor`(provider `redis`/`postgresql`)를 쓴다 (§14.3) |
**셋이 같은 모양이다**: 정책은 다 만들었고 **배포가 공급해야 하는 것 하나**가 비어 있다.
`GraphQlPrincipalResolver`(§9.9)가 이미 그 패턴을 확립했으니, 셋 다 같은 방식으로 정리하는 게
+27 -72
View File
@@ -1254,12 +1254,12 @@ credential로 도는데, 그건 설계상 런타임 롤과 다른 롤이다 —
### 7.7 벤더 선택과 H2 대칭
두 벤더 composition이 각각 **같은 네 개의 SPI 빈**을 등록한다.
두 벤더 composition이 각각 **같은 SPI 빈**을 등록한다. (V1 idempotency의
`IdempotencyClaimRepository`와 벤더별 구현 두 개는 2026-09-25에 V1과 함께 삭제됐다.)
| SPI | PostgreSQL | H2 |
|---|---|---|
| `OutboxClaimRepository` | `PostgreSqlOutboxClaimRepository` | `H2OutboxClaimRepository` |
| `IdempotencyClaimRepository` | `PostgreSqlIdempotencyClaimRepository` | `H2IdempotencyClaimRepository` |
| `SqlStateErrorMapping` | `PostgreSqlSqlStateErrorMapping` | `H2SqlStateErrorMapping` |
| `TransactionLocalTimeoutConfigurer` | `PostgreSqlLocalTimeoutConfigurer` | `H2LocalTimeoutConfigurer` |
@@ -1272,27 +1272,14 @@ credential로 도는데, 그건 설계상 런타임 롤과 다른 롤이다 —
부재는 PostgreSQL이다(`matchIfMissing = true`) — 선택자가 생기기 전 모든 배포가 돌던 벤더.
**두 statement가 갈라지고, 이유는 추정이 아니라 측정이다 (H2 2.4.240).**
**H2에서 도는 벤더 statement는 outbox claim 하나이고, 동일하다 (H2 2.4.240, 측정).** H2가
`FOR UPDATE SKIP LOCKED`를 받아들이고 잠긴 행을 진짜로 건너뛴다. 한 커넥션이 row lock을 든
상태에서 동시 `SKIP LOCKED` claim이 블록하거나 락을 뚫고 읽는 게 아니라 **0행을 반환**하는 걸
확인했다. 그래서 claim이 의미를 유지한다. `H2ClaimSqlTest`가 실제 H2에 실행한다.
- **outbox claim은 동일하다.** H2가 `FOR UPDATE SKIP LOCKED`를 받아들이고 잠긴 행을 진짜로
건너뛴다. 한 커넥션이 row lock을 든 상태에서 동시 `SKIP LOCKED` claim이 블록하거나 락을
뚫고 읽는 게 아니라 **0행을 반환**하는 걸 확인했다. 그래서 claim이 의미를 유지한다.
- **idempotency claim은 다르다.** H2에는 `INSERT ... ON CONFLICT ... RETURNING`이 없어서
같은 세 결과를 갖는 `MERGE ... USING`이다. `H2ClaimSqlTest`가 둘 다 실제 H2에 실행한다.
H2의 `MERGE`가 세 결과를 어떻게 만드는지:
| 상황 | 분기 | 반환 |
|---|---|---|
| scope에 행 없음 | `WHEN NOT MATCHED` insert | 1 |
| live 행 | 어느 분기도 발동 안 함 | 0 (live winner에게 짐) |
| expired 행 | `WHEN MATCHED AND expires_at <= now` | 1 (takeover) |
한 statement인 게 SPI의 약속을 지킨다 — **claim 실패가 constraint violation이 아니라 0행**이라
주변 트랜잭션을 오염시키지 않는다.
`RETURNING`이 필요 없는 이유도 적혀 있다: PostgreSQL statement가 반환하는 `EXCLUDED.id`는
양쪽 분기에서 proposed id이므로, claim된 행은 항상 이 caller의 proposed id다.
H2에는 idempotency store가 없다. 남은 idempotency store는 PostgreSQL 전용(§10.1)과 Redis뿐이고,
PostgreSQL provider는 H2 data source에서 기동을 거부한다. 그래서 `bootRunH2`는 provider를
`disabled`나 `redis`로 둔다.
**H2 vendor config에는 Flyway location customizer가 일부러 없다.** H2 등가 트리가 없고,
local profile이 Flyway를 끄고 Hibernate가 엔티티에서 스키마를 만들게 하기 때문. 두 가지
@@ -1530,53 +1517,19 @@ CREATE TABLE idempotency_record (
CREATE INDEX ix_idempotency_record_expires_at ON idempotency_record (expires_at);
```
**`tenant`가 절대 `null`이 아니다** (single-tenant는 빈 문자열).
테이블과 V1 migration은 그대로 남아 있지만, 이 컬럼을 쓰던 V1 코드
(`IdempotencyStoreAdapter`, `IdempotencyClaimRepository`와 벤더 구현, `tryBegin`,
`IdempotencyResponseObjectStore` offload)는 2026-09-25에 삭제됐다. 지금 이 테이블에 쓰는 코드는
owner-safe store(§10.1) 하나이고, `db/migration/jpa/idempotency` stream이 추가한 컬럼
(`scope_hash`, `record_version = 2` 등)을 쓴다. `jdbc` provider 값도 없다.
> PostgreSQL은 NULL을 서로 distinct로 취급하므로, null을 허용하면 single-tenant 행의 unique
> scope dedup이 깨진다.
남은 V1 쪽 코드는 정리용이다. `IdempotencyRecordEntity`/`IdempotencyRecordJpaRepository`를 쓰는
`IdempotencyReaper`(`@Scheduled`, 기본 10분, `deleteExpired` bulk delete)가 `expires_at`이 지난
행을 지운다. store가 완료·실패 때 `expires_at`을 앞으로 옮기므로 reaper는 **테이블 성장을 묶는
backstop**이다. reaper는 provider가 `postgresql`일 때만 돈다.
매퍼가 `null` 애플리케이션 tenant ↔ row의 `""`를 왕복시킨다.
**엔티티에 setter가 없는 것도 의도**다. 상태 전이 때 row를 재구성·재저장한다(Vernon Option A) —
애플리케이션 관점에서 엔티티를 immutable로 유지.
동시성 중재는 unique 제약이다. `tryBegin`:
- SPI(`IdempotencyClaimRepository`)가 있으면 벤더 statement 한 방.
- 없으면 lookup → 만료 행 delete → `saveAndFlush`(flush가 unique 검사를 그 자리에서 강제) →
`DataIntegrityViolationException`이면 `false`.
PostgreSQL SPI:
```sql
INSERT INTO idempotency_record (...) VALUES (..., 'IN_FLIGHT', NULL, NULL, ...)
ON CONFLICT ON CONSTRAINT uq_idempotency_scope
DO UPDATE SET id = EXCLUDED.id, request_hash = EXCLUDED.request_hash, status = 'IN_FLIGHT', ...
WHERE idempotency_record.expires_at <= :now
RETURNING id
```
`DO UPDATE ... WHERE`가 실패하면 행이 반환되지 않는다 → 패자는 `Optional.empty()`.
`tryClaim`이 하는 detach가 중요하다.
```java
if (exactExpiredEntity != null && entityManager.contains(exactExpiredEntity)) {
entityManager.detach(exactExpiredEntity);
}
```
이 statement가 덮어쓰려는 행의 managed 복사본이 있으면 커밋 시점에 claim 위로 flush된다.
만료는 **세 곳**에서 강제된다: read(`find`가 만료 행을 부재로 취급), reclaim(`tryBegin`이
만료 행을 재claim 전에 처리), 그리고 `IdempotencyReaper`(`@Scheduled`, 기본 10분,
`deleteExpired` bulk delete). reaper는 유일한 만료 수단이 아니라 **테이블 성장을 묶는
backstop**이다.
§F responseRef split: payload ≤ 8KB는 row에 inline, 더 크면 `IdempotencyResponseObjectStore`로
offload하고 reference만 보관. object store 빈이 없으면 **경고와 함께 inline으로 안전 degrade**
(D9 프로젝트 선택 — 8KB 임계와 object-store 분리는 cited normative basis가 없고 production
빈도도 미측정).
응답은 8 KiB 이하만 행에 inline으로 저장하고, 넘으면 store가 거부한다. object store offload
경로는 없다.
### 9.2 `outbox_event` (V3)
@@ -1719,7 +1672,7 @@ setter가 아니라 **registry 생성자**에서 설정한다.
### 10.1 `PostgreSqlOwnerSafeIdempotencyStore`
`IdempotencyStorePortV2` 구현. 상태:
`IdempotencyStorePort` 구현. 상태:
`CLAIMED → EXECUTING → COMPLETED | FAILED_RETRYABLE | ABANDONED`.
클래스가 하는 일과 협력자로 분리한 것이 명확히 문서화되어 있다.
@@ -2716,13 +2669,13 @@ JpaPlatformRuntimeAutoConfiguration ← 8개 add-on 빈
```
ca-skeleton.persistence-jpa.enabled = true
ca-skeleton.outbox.enabled = true
ca-skeleton.capabilities.idempotency.provider = jdbc
ca-skeleton.capabilities.idempotency.provider = postgresql
ca-skeleton.lock.multi-instance-enabled = true
notification.platform.enabled && persistence != none
app.fileserver-platform.enabled && transaction-provider != none
```
> 풀은 JPA의 사유물이 아니다. outbox, JDBC idempotency store, multi-instance lock,
> 풀은 JPA의 사유물이 아니다. outbox, PostgreSQL idempotency store, multi-instance lock,
> notification store, Fileserver 트랜잭션 경로가 전부 필요로 하고, "JPA 꺼졌나?"만 물으면
> **아무도 안 쓰는 풀을 열거나, 정당하게 쓰던 capability를 조용히 망가뜨린다.**
@@ -2875,7 +2828,9 @@ Flyway는 세 옵션이 **pin**되어 있다(env-driven 아님): `baseline-on-mi
`ca-skeleton.outbox.*`: `poll-interval: PT5S`, `batch-size: 20`, `in-flight-timeout: PT5M`,
`reaper-interval: PT10M`, `published-retention: P7D`.
`ca-skeleton.idempotency.ttl: 24h`, `reaper-interval: 10m`.
`ca-skeleton.capabilities.idempotency.*`: `provider: disabled`, `processing-lease: 30s`,
`replay-ttl: 24h`(`APP_IDEMPOTENCY_TTL`, 최대 72h), `failure-retention: 24h`,
`reaper-interval: 10m`. 한 record(`IdempotencySettings`)가 전부 바인딩한다.
---
@@ -3338,7 +3293,7 @@ grep -rnE "[0-9]+ ?(개 ?)?-?(leaf|leaves)" docs | grep -v "^docs/superpowers/\|
| 클래스 | 조건 |
|---|---|
| `IdempotencyStoreAdapter` | `@ConditionalOnProperty(ca-skeleton.capabilities.idempotency.provider = jdbc, matchIfMissing = true)` |
| `PostgreSqlIdempotencyStoreConfig` | `@ConditionalOnProperty(ca-skeleton.capabilities.idempotency.provider = postgresql)` |
| `IdempotencyReaper` | 동일 |
| `OutboxStoreAdapter` | **없음** (`@Repository`만) |
| `OutboxReaper` | **없음** (`@Component` + `@Scheduled`) |
@@ -0,0 +1,564 @@
# 부가 기능(capability) 모듈 포장 — 실행 계획
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 부가 기능을 "의존성을 붙이면 켜지고 떼면 사라지는 capability 모듈"로 바꾸고, 템플릿 기본 조립을 web만으로 줄인다. 그 전에 1차 리뷰 Critical을 고치고 리팩터링 잔재를 걷어낸다.
**Architecture:** 서비스 코드는 application-core 포트만 호출한다. 각 capability 모듈은 자기 `AutoConfiguration.imports`로 켜지고, `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 선택된다. bootstrap의 끄는 장치(MasterSwitch, import filter, scan 제외 정규식, 흩어진 validator)는 capability가 모듈 안으로 들어가는 만큼 삭제한다.
**Tech Stack:** Java 21, Spring Boot 4.0.8, Gradle 멀티모듈(registry `src/config/architecture/modules.json`), JUnit 5 + AssertJ + ArchUnit, Testcontainers(PostgreSQL 등), Flyway.
**Spec:** `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md` (확정). 입력 리뷰: `docs/reviews/2026-09-24-src-module-code-review.md`(1차), `docs/reviews/2026-09-24-src-maintainability-review.md`(2차).
## Global Constraints
- 기본 조립 방식: **B — 서비스가 고른 capability만 `runtimeOnly` 한 줄** (spec 10절 1).
- 템플릿 기본 포함: web 인바운드 + 운영 관측 + 코어 + support/identifier. 나머지는 전부 기본 제외 (spec 10절 2).
- HARD-STOP 7개(`AGENTS.md`)는 모든 Wave에서 유지한다. 특히 5번: 모든 project 의존성은 `modules.json`의 `allowed_dependencies` 안에 있어야 한다.
- 커밋은 `human-only`. 에이전트는 stage/commit/amend/push 하지 않는다. Wave마다 `git diff` 스냅샷을 scratchpad에 남겨 추적한다.
- 이미 적용됐을 수 있는 Flyway versioned migration은 바이트를 바꾸지 않는다. 수정은 새 버전으로만 한다.
- 설정 키: 동작하지 않는 옵션은 설정 키 자체를 두지 않는다 (spec 6절 3).
- 문서에 leaf 개수를 적지 않는다 (registry가 SSOT).
- Gradle은 한 작업 트리에서 동시에 하나만 돌린다. 병렬 작업은 별도 복사본에서만 한다.
## Review Focus
사용자가 가장 먼저 부딪힐 입력·조건과 기대 동작. 각 줄의 테스트는 해당 Task에 넣는다.
1. **이미 V9/V13이 적용된 DB로 기동** → checksum mismatch 없이 기동해야 한다. (Task 0-5: 적용 파일 해시 고정 테스트 + 원복)
2. **Docker 빌드 컨텍스트(`src`만 있음)에서 Gradle 실행** → compose 파일이 없어도 설정 단계가 통과해야 한다. (Task 0-3: compose 파일 없는 루트에서 `help` 성공 테스트)
3. **`APP_MESSAGING_PRODUCER_ID`를 비워 둔 채 messaging 활성화** → bridge bean만 생기지 않고 기동은 성공해야 한다. (Task 0-7: 빈 값·공백 값 테스트)
4. **prod에서 `APP_SERVER_ERROR_INCLUDE_STACKTRACE=always` 같은 env override** → 기동이 exit 71로 실패해야 한다. 대소문자(`Prod`, `ALWAYS`)도 같다. (Task 0-8)
5. **capability 한 줄을 지운 빌드** → 그 기능의 bean·설정 바인딩·validator가 전부 사라지고 나머지는 그대로 기동해야 한다. (Wave 4 완료 기준 — 기본 조립 system test)
---
## 실행 방식
- Wave 0: 현재 세션에서 직접 실행(작고 서로 독립).
- Wave 1 이후: Wave마다 시작 시점에 이 문서 아래 "Wave N 상세 Task"를 추가한 뒤 실행한다(rolling-wave). 작업 단위 하나를 구현 subagent 하나에 맡기고, 끝나면 리뷰 subagent가 확인한다. Gradle 충돌을 피하려고 같은 작업 트리에서는 순차로 돌리고, 병렬이 필요하면 `rsync`로 만든 복사본에서 돌린 뒤 diff를 되가져온다.
- 매 Wave 종료 시: focused test + `./gradlew architectureCheck --console=plain` + (영향 범위에 따라) 통합 lane. Wave 종료 기록은 맨 아래 "진행 기록"에 남긴다.
## Wave 개요
| Wave | spec 9절 단계 | 내용 | 완료 기준 |
|---|---|---|---|
| 0 | 1, 2(Wave 0) | 규칙 고정(AGENTS.md) + 결정 불필요 차단 결함 7건 | 7건 각각 회귀 테스트 통과, architectureCheck 통과 |
| 1 | 2(Wave 1) | 데이터·보안 Critical 10건 | 10건 각각 회귀 테스트(가능하면 포트 계약 테스트) 통과 |
| 2 | 3 | 분류 3(잔재) 삭제, 분류 4(실험용 자리) 삭제 | 삭제 후 전체 leaf `check` + architectureCheck 통과 |
| 3 | D1(분류 2) | 분류 2(라이브러리형 API) — 완성해서 포장(동작하지 않는 약속 제거, web 라이브러리는 opt-in leaf로 분리) | 기준 3 위반 0, web 기본 leaf에 라이브러리 없음 |
| 4 | 4 | 분류 1 capability 포장 + 기본 조립 web-only + 끄는 장치 삭제 | spec 6절 완료 기준 7개를 capability마다 충족, 기본 조립 system test 통과 |
| 5 | 5 | 빌드 O3(바로 할 것 1–12 포함) + 테스트 컨벤션(sample부터) | `ci` 통과, build-logic/build-tools 축소 |
---
## Wave 0 — 규칙 고정 + 결정 불필요 차단 결함
### Task 0-1: 결정 기록
**Files:**
- Modify: `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md` (상태, 10절)
- [x] **Step 1:** 10절을 "결정"으로 바꾸고 B안 확정, 기본 포함 목록(web만)과 해석 근거를 적는다.
### Task 0-2: capability 완료 기준과 테스트 컨벤션을 AGENTS.md에 고정
**Files:**
- Modify: `AGENTS.md` (새 절 "부가 기능(capability) 모듈 규칙", "테스트 전략"에 컨벤션)
- Modify: `CLAUDE.md` (Testing 절에 포인터, capability 규칙 한 줄 요약)
- [x] **Step 1: AGENTS.md에 capability 규칙 절 추가** — spec 6절 완료 기준 7개를 그대로 옮기고, 기본 조립 목록(spec 10절 2)과 "기능 추가 = `runtimeOnly` 한 줄 + env" 절차를 적는다. settings 규칙(prefix 하나, `StrictSettingsBinder`, compact constructor 검증)도 여기 둔다.
- [x] **Step 2: AGENTS.md "테스트 전략"에 컨벤션 6개 추가** — 2차 리뷰 TEST 절 "제안 컨벤션" 1–6(이름=행동 문장이고 이름이 약속한 성질을 단언, `@DisplayName` 선택·영어, GWT 주석은 본문 3문장 이상일 때 필수·`// when` 하나, `@Nested` 조건, 단언 규칙, 포트 fake는 포트 소유 모듈 testFixtures에 하나 + fake와 adapter가 같은 `XxxContract` 통과, Mockito는 프레임워크 경계만). 적용 범위: 새로 쓰거나 고치는 테스트. 주석 게이트는 만들지 않는다(이유 한 줄).
- [x] **Step 3: CLAUDE.md 동기화** — Testing 절 끝에 "테스트 작성 규칙과 capability 모듈 규칙은 `AGENTS.md`가 정본" 한 줄, capability 규칙 3줄 요약.
- [x] **Step 4: 확인** — `grep -n "capability" AGENTS.md CLAUDE.md`로 두 문서가 같은 7개 기준을 가리키는지 본다(요약과 정본이 어긋나지 않게).
### Task 0-3: O-1 — compose overlay 확인을 task 실행 시점으로
1차 Critical #1. `DeveloperBootstrapPlugin.apply()`가 compose overlay가 없으면 설정 단계에서 실패해, Docker 빌드 컨텍스트(`src`만 있음)에서 어떤 task도 못 돈다.
**Files:**
- Modify: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/bootstrap/DeveloperBootstrapPlugin.java:40-50`
- Test: `src/build-logic/src/test/java/dev/caskeleton/buildlogic/bootstrap/DeveloperBootstrapPluginFunctionalTest.java`
- [x] **Step 1: 실패하는 테스트 작성** — compose 파일이 하나도 없는 루트에서 `help`가 성공해야 한다. 기존 "없는 profile 거부" 테스트는 `tasks` 대신 `bootstrapDockerPreflight` 실행으로 바꾼다(거부는 task 실행 시점으로 옮겨진다).
```java
@Test
void configurationDoesNotRequireComposeFiles(@TempDir Path temporaryDirectory)
throws IOException {
// The Docker image build copies only src/ into the build context, so the repository root and
// its compose files do not exist there. Configuring the root project must still succeed.
Path projectDirectory = fixtureWithoutComposeFiles(temporaryDirectory);
BuildResult result = run(projectDirectory, "help");
assertThat(result.getOutput()).contains("BUILD SUCCESSFUL");
}
@Test
void aProfileWithNoOverlayIsRefusedAndTheMessageListsTheRealOnes(
@TempDir Path temporaryDirectory) throws IOException {
Path projectDirectory = fixture(temporaryDirectory);
BuildResult failure =
runAndFail(projectDirectory, "bootstrapDockerPreflight", "-PbootstrapProfile=staging");
assertThat(failure.getOutput())
.contains("names no overlay")
.contains("docker-compose.staging.yml")
.contains("[dev, local]");
}
```
`fixtureWithoutComposeFiles`는 `fixture`와 같되 `docker-compose*.yml`을 만들지 않는다(`fixture`가 이것을 호출한 뒤 compose 파일을 추가하도록 나눈다).
- [x] **Step 2: 실패 확인** — `cd src && ./gradlew :build-logic:test --tests '*DeveloperBootstrapPluginFunctionalTest' --console=plain` → `configurationDoesNotRequireComposeFiles` FAIL("names no overlay").
- [x] **Step 3: 구현** — `apply()`의 overlay 확인 블록을 지우고 `bootstrapDockerPreflight`에 `doFirst`로 옮긴다. 캡처하는 값은 `File`/`String`만(configuration cache 호환).
```java
task.doFirst(
ignored -> requireOverlay(overlay, bootstrapProfile, repositoryDirectory));
```
```java
private static void requireOverlay(File overlay, String profile, File repositoryDirectory) {
if (!overlay.isFile()) {
throw new GradleException(
"bootstrap: -P" + PROFILE_PROPERTY + "=" + profile + " names no overlay; expected "
+ overlay.getName() + " beside docker-compose.yml. Available: "
+ availableProfiles(repositoryDirectory));
}
}
```
- [x] **Step 4: 통과 확인** — Step 2 명령 → 5개 테스트 PASS.
### Task 0-4: O-2 — 항상 실패하는 `redis-sdk` CI job 삭제
1차 Critical #2. `--tests '*…'`의 따옴표가 word-split 뒤에도 남아 매칭 0 → 항상 실패, `release-gate`가 success 요구. 같은 테스트는 이미 `:shared-contract:test`로 `ci`에서 돈다.
**Files:**
- Modify: `.github/workflows/ci-quality-gates.yml` (`redis-sdk:` job 블록, `release-gate`의 `needs`·`REDIS_RESULT` 두 줄)
- [x] **Step 1:** `redis-sdk:` job 블록 전체와 `release-gate`의 `- redis-sdk`, `REDIS_RESULT: ...`, `"${REDIS_RESULT}" \` 줄을 지운다.
- [x] **Step 2: 확인** — `grep -n "redis-sdk\|REDIS_RESULT" .github/workflows/ci-quality-gates.yml` → 0건. `python3 -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci-quality-gates.yml'))"` → 오류 없음.
### Task 0-5: E-1 — 적용된 migration 원복 + 새 버전 + 해시 고정
1차 Critical #3. `postgresql/V9`, `postgresql/V13`이 적용 후 제자리 수정됐다(9da00eb7). 기본 Flyway location이라 이전 파일이 적용된 모든 DB가 checksum mismatch로 기동 실패한다.
범위 결정: 세 번째 파일 `jpa/outbox-storage/V1`은 어떤 composition도 location을 설정하지 않은 미조립 V2 outbox 세대다. Wave 2(D2)에서 그 세대를 migration 트리째 삭제하므로 여기서는 손대지 않는다.
**Files:**
- Restore: `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V9__widen_capability_schema_stream.sql` (`9da00eb7^` 바이트)
- Restore: `.../postgresql/V13__outbox_canonical_transport_compatibility.sql` (`9da00eb7^` 바이트)
- Create: `.../postgresql/V16__outbox_canonical_hash_columns_varchar.sql`
- Create: `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`
- Create: `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/AppliedMigrationImmutabilityTest.java`
- Modify: `.../migration/PostgreSqlConstraintMigrationSafetyTest.java` (V13 NOT VALID 단언 → V16 varchar 단언)
- [x] **Step 1: 해시 고정 테스트 작성** — 매니페스트(`<sha256> <db/migration 기준 상대경로>`)에 있는 파일은 바이트가 같아야 하고, 디스크의 모든 `V*.sql`은 매니페스트에 있어야 한다. 줄 끝은 `\n`으로 정규화(CRLF checkout 오탐 방지).
```java
class AppliedMigrationImmutabilityTest {
private static final Path MIGRATIONS = Path.of("src/main/resources/db/migration");
private static final Path MANIFEST = Path.of("src/test/resources/db/applied-migrations.sha256");
@Test
void appliedMigrationsKeepTheBytesTheyWereAppliedWith() throws IOException {
// given
Map<String, String> pinned = pinnedChecksums();
// when
Map<String, String> actual = currentChecksums();
// then
assertThat(actual)
.as("an applied migration changed; add a new version instead of editing it")
.containsAllEntriesOf(pinned);
}
@Test
void everyVersionedMigrationIsPinned() throws IOException {
// given
Map<String, String> pinned = pinnedChecksums();
// when
Map<String, String> actual = currentChecksums();
// then
assertThat(pinned.keySet())
.as("pin a new migration in %s when it is added", MANIFEST)
.containsAll(actual.keySet());
}
// pinnedChecksums(): 매니페스트 파싱, currentChecksums(): Files.walk로 V*.sql 수집 후 정규화 SHA-256
}
```
- [x] **Step 2: 원복** — `git show 9da00eb7^:<path> > <path>`로 V9·V13을 되돌린다.
- [x] **Step 3: 매니페스트 생성** — 원복된 트리에서 모든 `V*.sql`의 정규화 SHA-256을 기록한다(원복 파일이 기준). V16은 Step 4 뒤에 추가.
- [x] **Step 4: V16 작성** — 9da00eb7이 V13에서 바꾼 `char(64)→varchar(64)`를 새 버전으로 옮긴다. 이미 varchar인 DB에서는 no-op.
```sql
-- V13 created the canonical hash columns as char(64). The JPA mapping is String(length = 64),
-- which Hibernate validates as varchar, so ddl-auto=validate rejected a database migrated through
-- V13. Every stored value is exactly 64 hex characters, so widening keeps the data unchanged; on a
-- database whose columns are already varchar(64) this is a no-op.
ALTER TABLE outbox_event
ALTER COLUMN partition_key TYPE varchar(64),
ALTER COLUMN schema_set_hash TYPE varchar(64),
ALTER COLUMN envelope_sha256 TYPE varchar(64),
ALTER COLUMN envelope_schema_hash TYPE varchar(64),
ALTER COLUMN payload_schema_hash TYPE varchar(64);
```
- [x] **Step 5: `PostgreSqlConstraintMigrationSafetyTest` 갱신** — V13 내용 단언(varchar, NOT VALID) 2개를 "V16이 다섯 컬럼을 varchar(64)로 바꾼다" 단언 하나로 교체. V14 단언은 유지.
- [x] **Step 6: 확인** — `./gradlew :adapter:outbound:persistence-jpa:test --console=plain` PASS. Docker lane: `./gradlew :adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '*Migration*' --console=plain` PASS(실제 PostgreSQL에서 V1→V16 적용 + `ddl-auto=validate`).
- [x] **Step 7: 문서** — `docs/` migration 안내(기존 persistence-jpa README의 migration 절)에 "09-23~09-25 사이 새로 만든 개발 DB는 `flyway repair` 필요" 한 줄.
### Task 0-6: L-1 — outbox relay가 `@EnableScheduling` 없이 멈춤
1차 Critical #5. 앱 전체의 `@EnableScheduling`이 `idempotency.provider=jdbc` 조건부 `IdempotencyConfig`에만 있어, outbox relay가 다른 provider 조합에서 조용히 멈춘다.
**Files:**
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java`
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfigTest.java`
- [x] **Step 1: 실패하는 테스트**
```java
@Test
void outboxCapabilityEnablesSchedulingWithoutTheJdbcIdempotencyProvider() {
// given
ApplicationContextRunner runner =
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(OutboxConfig.class))
.withPropertyValues(
"ca-skeleton.outbox.enabled=true", "ca-skeleton.outbox.relay-enabled=false");
// when & then
runner.run(
context ->
assertThat(context)
.hasBean(TaskManagementConfigUtils.SCHEDULED_ANNOTATION_PROCESSOR_BEAN_NAME));
}
```
- [x] **Step 2: 실패 확인** — `./gradlew :app-bootstrap:test --tests '*OutboxConfigTest' --console=plain` → FAIL.
- [x] **Step 3: 구현** — `OutboxConfig`에 `@EnableScheduling` 추가(이미 `ca-skeleton.outbox.enabled`로 gate됨).
- [x] **Step 4: 통과 확인** — Step 2 명령 PASS.
### Task 0-7: H-1 — messaging bridge 조립 순서 + 빈 producer-id
1차 Critical #6. (a) bridge auto-config에 `after` 지정이 없어 알파벳 순서상 platform보다 먼저 평가되고 `@ConditionalOnBean(EncodedMessagePublisher)`가 항상 false. (b) `producer-id: ${APP_MESSAGING_PRODUCER_ID:}`가 빈 문자열로 존재해 `@ConditionalOnProperty`를 통과 → `new ProducerId("")` 예외.
**Files:**
- Modify: `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java`
- Test: `src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java`
- Create (test): `src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java` — 실제 starter 클래스와 같은 FQN의 테스트 대역. 이 leaf의 test classpath에는 starter가 없으므로 충돌하지 않는다. `EncodedMessagePublisher` bean 하나만 등록한다. 목적: Boot의 auto-config 정렬(`afterName`)을 실제로 거치게 해서 (a)를 재현.
- [x] **Step 1: 실패하는 테스트 2개**
```java
@Test
void bridgeIsAssembledAfterThePlatformRootThatProvidesThePublisher() {
// given
ApplicationContextRunner assembled =
new ApplicationContextRunner()
.withConfiguration(
AutoConfigurations.of(
MessagingBridgeRootAutoConfiguration.class,
dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration
.class))
.withBean(FailOpenDependencyLogger.class, FailOpenDependencyLogger::new)
.withPropertyValues(
"app.messaging.enabled=true", "app.messaging.producer-id=portfolio-service");
// when & then
assembled.run(
context -> assertThat(context).hasSingleBean(IntegrationEventPublishPort.class));
}
@ParameterizedTest
@ValueSource(strings = {"", " "})
void blankProducerIdLeavesTheBridgeOutWithoutFailingStartup(String producerId) {
runner
.withPropertyValues("app.messaging.producer-id=" + producerId)
.run(
context -> {
assertThat(context).hasNotFailed();
assertThat(context).doesNotHaveBean(IntegrationEventPublishPort.class);
});
}
```
- [x] **Step 2: 실패 확인** — `./gradlew :adapter:outbound:messaging:test --tests '*MessagingPlatformBridgeAutoConfigurationTest' --console=plain` → 두 테스트 FAIL.
- [x] **Step 3: 구현**
```java
@AutoConfiguration(
afterName = "dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration")
...
@Bean
@ConditionalOnBean(EncodedMessagePublisher.class)
@ConditionalOnMissingBean(IntegrationEventPublishPort.class)
@Conditional(ProducerIdConfigured.class)
public IntegrationEventPublishPort integrationEventPublishPort(...)
/** {@code producer-id} is always present as a key (the yml default is empty), so presence alone is not configuration. */
static final class ProducerIdConfigured extends SpringBootCondition {
@Override
public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) {
String producerId = context.getEnvironment().getProperty("app.messaging.producer-id");
return StringUtils.hasText(producerId)
? ConditionOutcome.match("app.messaging.producer-id is set")
: ConditionOutcome.noMatch("app.messaging.producer-id is blank");
}
}
```
- [x] **Step 4: 통과 확인** — Step 2 명령 PASS.
### Task 0-8: L-2 — prod 에러 상세 노출 차단을 실제 코드로
1차 L-2. `application-prod.yml`은 "`StartupSafetyValidator`가 error-detail 노출을 막는다"고 적지만 그 검사는 9da00eb7에서 지워졌다. `spring.web.error.include-*`는 env로 prod에서도 켜진다.
**Files:**
- Create: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/ErrorDetailExposureSafetyValidator.java`
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/RuntimeSafetyConfig.java` (bean 등록)
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/ErrorDetailExposureSafetyValidatorTest.java`
- Modify(문서): `src/app-bootstrap/src/main/resources/application-prod.yml:13`, `src/app-bootstrap/README.md`(StartupSafetyValidator 절, RuntimeSafetySettings 절), `src/README.md`(Runtime safety 절)
- [x] **Step 1: 실패하는 테스트** — `JpaSchemaSafetyValidatorTest`와 같은 `ApplicationContextRunner` 모양.
```java
@ParameterizedTest
@CsvSource({
"spring.web.error.include-stacktrace, always, APP_SERVER_ERROR_INCLUDE_STACKTRACE",
"spring.web.error.include-stacktrace, ON_PARAM, APP_SERVER_ERROR_INCLUDE_STACKTRACE",
"spring.web.error.include-message, always, APP_SERVER_ERROR_INCLUDE_MESSAGE",
"spring.web.error.include-binding-errors, always, spring.web.error.include-binding-errors",
"spring.web.error.include-exception, true, spring.web.error.include-exception"
})
void prodRefusesToStartWhenErrorDetailsWouldReachClients(String key, String value, String named) {
runner
.withInitializer(context -> context.getEnvironment().setActiveProfiles("Prod"))
.withPropertyValues(key + "=" + value)
.run(
context -> {
assertThat(context).hasFailed();
assertThat(context.getStartupFailure())
.isInstanceOf(ProfileMismatchException.class)
.hasStackTraceContaining(named);
});
}
@Test
void prodStartsWhenEveryErrorDetailStaysHidden() { /* never/never/never/false → hasNotFailed */ }
@Test
void nonProdMayExposeErrorDetailsForDebugging() { /* local + always → hasNotFailed */ }
```
- [x] **Step 2: 실패 확인** — `./gradlew :app-bootstrap:test --tests '*ErrorDetailExposureSafetyValidatorTest' --console=plain` → 컴파일 실패(클래스 없음).
- [x] **Step 3: 구현** — `SmartInitializingSingleton`. prod 판정은 `RuntimeProfileSnapshot.from(environment).isProduction()`(기존 validator와 같음). 위반을 모아 `StartupFailures.profileMismatch(...)` 한 번(exit 71). 키→사용자에게 보여줄 env 이름 표: stacktrace→`APP_SERVER_ERROR_INCLUDE_STACKTRACE`, message→`APP_SERVER_ERROR_INCLUDE_MESSAGE`, binding-errors·exception→property 이름 그대로.
- [x] **Step 4: 등록** — `RuntimeSafetyConfig`에 `@Bean ErrorDetailExposureSafetyValidator`.
- [x] **Step 5: 통과 확인** — Step 2 명령 PASS.
- [x] **Step 6: 문서 4곳 정정** — 거짓 주장("StartupSafetyValidator가 막는다", "shipped 구현이 없다", "5종")을 새 validator 이름과 실제 검사 키로 바꾼다.
### Task 0-9: L-3 — sample actuator `loggers`를 읽기 전용으로
1차 L-3. sample은 `loggers`를 노출하고 모든 경로가 `permitAll`이라 인증 없이 로그 레벨을 바꿀 수 있다.
**Files:**
- Modify: `src/sample-portfolio/src/main/resources/application.yml` (`management.endpoint.loggers.access: read-only`)
- Test: sample의 기존 actuator/설정 테스트에 단언 추가, 없으면 `SampleActuatorLoggersAccessTest`(yml을 `YamlPropertySourceLoader`로 읽어 값 단언).
- [x] **Step 1: 실패하는 테스트** — `management.endpoint.loggers.access`가 `read-only`인지 단언.
- [x] **Step 2: 실패 확인** — `./gradlew :sample-portfolio:test --tests '*Loggers*' --console=plain` → FAIL.
- [x] **Step 3: 구현** — yml에 한 줄.
- [x] **Step 4: 통과 확인** — Step 2 명령 PASS.
### Wave 0 종료 검증
- [x] `cd src && ./gradlew :build-logic:test :adapter:outbound:persistence-jpa:test :adapter:outbound:messaging:test :app-bootstrap:test :sample-portfolio:test --console=plain`
- [x] `./gradlew architectureCheck --console=plain`
- [x] `./gradlew :adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '*Migration*' --console=plain` (Docker)
- [x] `git diff > <scratchpad>/wave-0.patch`, 진행 기록 갱신
---
## Wave 1 — 데이터·보안 Critical 10건
각 항목은 "재현 테스트 먼저 → 수정 → 통과". fake가 결함을 숨긴 포트는 포트 소유 모듈 testFixtures에 추상 계약 테스트(`XxxContract`)를 만들고 fake와 실제 adapter가 둘 다 상속한다(spec 6절 5, 2차 리뷰 권고 순서 1). 상세 Task는 Wave 1 시작 때 이 절 아래에 추가한다.
| # | 결함 (1차 리뷰) | 위치 | 수정 방향 | 회귀 테스트 |
|---|---|---|---|---|
| 1-1 | #4 durable operation 재제출이 PG 25P02 | `persistence-jpa/.../operation/DurableOperationStoreAdapter.java:47-78` | native `INSERT … ON CONFLICT DO NOTHING` 후 0건이면 기존 row 조회(`JpaNotificationRequestStore` 방식) | `DurableOperationStoreContract`(application-core testFixtures) — in-memory fake + PG adapter(Testcontainers)가 같은 이중 submit 시나리오 통과 |
| 1-2 | #12 web이 operation 조회·취소 유스케이스를 대신 수행(HARD-STOP 4) | `web/.../operationasync/OperationQueryService.java` | application-core에 `GetDurableOperationUseCase`(Query), `CancelDurableOperationUseCase`(Command + `@UseCaseCapability`), owner·tenant 판정은 `ObjectAccessPolicy` 뒤로; web은 요청 컨텍스트 변환만 | use case 단위 테스트(fake store), web slice 테스트 |
| 1-3 | #7 outbox relay·DLQ·retry-topic이 인코딩된 메시지를 재인코딩 | `messaging-outbox-jdbc-postgresql/.../OutboxRelay.java:223-229`, `DefaultMessagePublisher.java:177` | 이미 인코딩된 `EncodedMessage`는 raw publish 경로로(재인코딩 없이 transport로) | relay → publisher 경로 테스트: 저장된 row가 PUBLISHED |
| 1-4 | #8 Kafka TLS/SASL 설정이 producer에 적용 안 됨 | `messaging-spring-boot-starter-kafka/.../KafkaMessagingAutoConfiguration.java:109-154` | `KafkaSecurityConfigurer`를 producer properties 생성에 실제로 적용 | producer config에 `security.protocol`/`sasl.*`/`ssl.*`가 들어가는지 단언 |
| 1-5 | #9 알림 recovery/replay가 트랜잭션 없이 `@Modifying` 실행 | `adapter/outbound/notification/.../LeaseRecoveryService.java:106` 외 3곳 | 행 단위 작업을 `TransactionPort.inWrite`로 감쌈 | PG lane에서 `recoverOnce`/`replayOnce` 실제 실행 |
| 1-6 | #10 SNS 서명 검증 우회(호스트, TopicArn, Timestamp) | `.../ses/SnsSignatureVerifier.java:99-109`, `SesProviderCallbackAssembler.java:19` | 호스트 `^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$`, SES callback 켜면 `allowed-topic-arns` 필수, 오래된 Timestamp 거부, 인증서 캐시 상한 | S3 버킷 URL·타 토픽·오래된 메시지 거부 테스트 |
| 1-7 | #11 tus `Upload-Checksum`을 누적 digest와, 커밋 후 비교 | `web-fileserver/.../tus/TusController.java:167-174` | append에 기대 checksum 전달, chunk digest를 커밋 전에 검증, 불일치 시 롤백·460 | 정상 checksum 2번째 chunk 성공 + 불일치 chunk가 offset을 올리지 않음(tus 계약 테스트, fake digest도 chunk 단위로) |
| 1-8 | #13 GraphQL 인가 단계 fragment 재귀 전개 무제한 | `graphql/.../runtime/GraphQlDocumentAuthorizationHandler.java:109-137` | 방문 budget(노드 수 상한) + fragment 전개 memo, 초과 시 거부 | 1.6KB 중첩 fragment 문서가 제한 시간 안에 거부 |
| 1-9 | #14 Redis SCRIPT lane 한도가 동시 lease 수 → 정상 Redis에서도 9번째부터 거부 | `redis-runtime/.../RedisRuntimeOwner.java:134-140`, `RedisSdkSettings.java:687` | lane 한도를 연결(connection) 수에 맞게, lease는 대기 후 획득(짧은 timeout) | 동시 호출 N > 한도에서 정상 Redis면 전부 성공(fake gateway 동시성 테스트) |
| 1-10 | #15 gRPC 멱등성: FAILED_TERMINAL 행에서 claim 없이 PROCEED | `grpc/grpc-policy/.../GrpcIdempotencyInterceptor.java:109-114` | FAILED_TERMINAL은 재claim(새 attempt) 또는 거부로 명시, fake ledger도 같은 전이 규칙 | `GrpcOperationLedgerContract`(grpc-testkit) — fake와 JPA ledger 공통 |
완료 기준: 10건 각각 회귀 테스트가 수정 전 FAIL·수정 후 PASS. 영향 leaf `check` + `architectureCheck` 통과. Docker 필요한 lane(1-1, 1-5, 1-10 JPA ledger)은 실제 실행.
### Wave 1 상세 Task (작업 묶음)
서로 다른 leaf를 건드리는 7개 묶음으로 나눠 복사본에서 병렬 실행한다. 묶음마다 구현 subagent 하나.
| 묶음 | 항목 | 건드리는 leaf | 검증 명령 (`src/`에서) |
|---|---|---|---|
| W1-OP | 1-1, 1-2 | application-core(+testFixtures), persistence-jpa, adapter:inbound:web | `:application-core:check :adapter:outbound:persistence-jpa:check :adapter:inbound:web:check`, PG lane(durable operation) |
| W1-MSG | 1-3, 1-4 | messaging-outbox-jdbc-postgresql, messaging-runtime-core, messaging-spring-boot-starter-kafka | 해당 leaf `check` |
| W1-NOTIF | 1-5, 1-6 | adapter:outbound:notification(+ application-notification 필요 시) | leaf `check` + PG lane(recovery/replay) |
| W1-TUS | 1-7 | adapter:inbound:web-fileserver, application-fileserver, adapter:outbound:fileserver | leaf `check` |
| W1-GQL | 1-8 | adapter:inbound:graphql | leaf `check` |
| W1-REDIS | 1-9 | redis-runtime(+ cache-redis 영향 시) | leaf `check` |
| W1-GRPC | 1-10 | optional build `grpc:grpc-policy`, `grpc:grpc-testkit`, `grpc:grpc-operation-ledger-jpa` | `./gradlew -p optional-platforms <leaf>:check`, ledger PG lane |
공통 절차(각 묶음):
- [x] 재현 테스트 작성 → 실행해서 FAIL 확인(출력 기록)
- [x] 최소 수정 → 같은 테스트 PASS
- [x] fake가 결함을 숨긴 포트는 추상 계약 테스트로 fake·adapter 양쪽 실행
- [x] `spotlessApply`, 영향 leaf `check`, `architectureCheck`
- [x] 복사본 diff를 main 작업 트리에 반영 후 main에서 영향 leaf `check` 재실행
---
## Wave 2 — 분류 3(리팩터링 잔재)·분류 4(실험용 자리) 삭제
원칙(spec 5절, 8절 D2–D4): 한 기능에 한 세대만 남긴다. 삭제한 것은 `docs/capability-status.md`의 "제거된 코드" 표에 마지막으로 존재한 커밋과 함께 한 줄씩 적는다(복구 경로). 분류 4는 SDK가 없거나 기동 시 거부되므로 optional build로 옮기지 않고 삭제한다(2차 리뷰 S7 #1 권고: experimental 4개·Debezium 삭제; rabbit은 기동 거부·운영 채널 구현 없음).
| # | 대상 | 남길 것 | 삭제 | 근거 |
|---|---|---|---|---|
| 2-A | web 2세대·WebFlux | servlet 1세대(`RequestLoggingFilter`, `RateLimitInterceptor`, `ETags`, `PageParams`, Envelope 에러) | `webflux/*`, `advanced/webflux`, `callback/reactive`, web-fileserver reactive; 2세대 conditional/pagination/throttle/admission/access-log, `WebMvcPlatformAutoConfiguration`의 미사용 bean 9개·evidence filter·startup check·`admin/platform`, `cursor/CursorCodec`, main의 `moduleboundary`; WebProblem 어휘는 fixture 전용이면 삭제 | D4, S5 #2–#4, #8 |
| 2-B | outbox 3세대 | v1 `outbox_event` + fencing(owner+token CAS) | app-core `outbox/v2`, persistence-jpa `postgresql/outbox`, `jpa/outbox-storage`·`jpa/outbox-polling` 트리(미조립), `OutboxV2RetryPolicy` | D2, X1 #1. 새 migration `V17` (lease_owner, lease_token) |
| 2-C | 멱등성 2세대 | V2(이름에서 `V2` 제거), 조립 1곳 | v1 executor·port·adapter·H2/PG claim repo·`IdempotencyConfig`, websocket `CommittedResultLedger`, graphql `idempotencyKey` 미연결 allowlist | D3, X1 #2. sample을 V2로 이전 |
| 2-D | notification R1 | R2 platform | application-notification 루트 R1 타입, Reactor facade·의존성, `spring-web` 의존, 미사용 platform 코드(throw 0 예외, security 3종, sms/push/email/webpush), `NotificationOrchestrator`, contract-v1 템플릿 | 1차 B-8, S1 #10 #14 |
| 2-E | messaging adapter R1 | canonical bridge + R0 seam | `envelope`·`contract`·`destination`·`config` R1 체인, `realtime/MessagingDurableFanoutAdapter`, NetworkNT 런타임 의존 | S4 #2 |
| 2-F | fileserver R1/R2 publication | `platform/**` HTTP 파일 서버 | 루트 패키지 publication(31파일), app-core `filepublication`, `FileExportPort`, `app.fileserver.*`·`app.file-export.*` 설정 | S4 #1, X1 #8 |
| 2-G | STOMP 2벌, main의 governance gate | `stomp/` 스택 | `advanced/stomp/**`, `StompBrokerExclusivity`, websocket `moduleboundary`·`evidence`·`release`, graphql `architecture/`(런타임 경계 검사 — ArchUnit이 이미 검사)·`compat/`·`moduleboundary`, grpc 상수 gate·`GrpcStableModuleCatalog` | S5 #7 #11, S6 #1, S7 #4 |
| 2-H | 두 번째 트랜잭션·재시도 엔진, Mongo reactive 쌍둥이 | port 기반 엔진, imperative Mongo | persistence-jpa `SpringJpaTransactionExecutor` 계열, Mongo `reactive/**`·change stream | S2 #3 #5 |
| 2-I | messaging 분류 4 | Kafka | `messaging-pulsar-experimental`, `-nats-experimental`, `-kafka-share-experimental`, `-spring-cloud-stream-bridge`, `-rabbit`, `-starter-rabbit`, Debezium 클래스; starter의 미사용 edge(cloudevents, claim-check) | spec 5절 분류 4, S7 #1 #5 |
| 2-J | 호출자 0 잔재 | — | httpclient `BoundedErrorBody`·`spring7/`·`migration/`, objectstorage legacy adoption(켜면 기동 실패), `UuidCodec`, `CompiledPackageScanner`, app-core `@Deprecated` 캐시 executor 계열(소비자 확인 후), `PolicyTransactionPort` 계열 | 1차 A-9, S1 #3 #8, S3 #8, S4 #10 |
완료 기준: 삭제한 타입의 main 참조 0(`grep -rw`), registry·settings·문서의 참조 정리, 영향 leaf `check` + `architectureCheck` + `:app-bootstrap:architectureTest` 통과, `docs/capability-status.md` 제거 표 갱신.
### Wave 2 상세 Task (작업 묶음)
사전 조사(읽기 전용) 결과로 범위를 확정했다. 조사에서 "아직 쓰인다"로 확인된 것은 삭제 대상에서 뺐다:
`PolicyTransactionPort` 계열(fileserver 보상 트랜잭션이 사용 — 삭제가 아니라 `TransactionPort.inNew`로 교체 후 삭제),
cache 타입 9개(cache-redis 사용), `IdempotencyReaper`와 멱등성 엔티티(V2 행 정리에 필요), v1 패키지의 공용 타입 8개(V2가 사용),
`NotificationSubmissionService`의 진입 메서드, `NotificationPort` bean.
| 묶음 | 대상 | 결정 |
|---|---|---|
| W2-1 | T-F 파일 서버 publication 평면, T-G websocket 중복 STOMP·governance, T-J httpclient/identifier/objectstorage legacy 잔재 | 전부 삭제. MasterSwitch `FILESERVER`(R1 스위치)와 문서·env key 동반 삭제 |
| W2-2 | T-G graphql governance(`architecture/`, `compat/`, `moduleboundary`, `release`), T-E messaging adapter R1 체인, T-I messaging 분류 4 leaf | graphql 부팅 시 경계 검사에서 잃는 규칙 2개(resolver는 transport 타입만 반환, raw `DataFetcher`는 infra에만)는 ArchUnit으로 옮긴다. `IntegrationEventEncoderPort`는 adopter 확장 지점으로 남기고 검증 메시지만 고친다. rabbit·pulsar·nats·kafka-share·stream-bridge·Debezium 삭제 |
| W2-3 | T-A web 2세대·WebFlux·WebProblem | 전부 삭제. WebProblem을 인증하던 fixture lane은 transport 동작을 보는 것(Jetty 호환)은 Envelope 기준으로 고치고, WebProblem 표면만 인증하던 것은 삭제 |
| W2-4 | T-D notification R1, T-H 두 번째 트랜잭션 엔진·Mongo reactive, T-J application-core 잔재(cache 20개, `LeaseWatchdog`, inbox, `EphemeralFanoutPort`, 미사용 lock/write 실행기), `PolicyTransactionPort` 교체 | 삭제 + fileserver 보상 트랜잭션을 `TransactionPort.inNew`로 |
| W2-5 | T-B outbox V2 삭제 + v1 fencing(D2) | V2 코드·`jpa/outbox-storage`·`jpa/outbox-polling` 트리 삭제(어떤 조립도 적용한 적 없음), `V17` lease_owner/lease_token + CAS 완료 처리 |
| W2-6 | T-C 멱등성 v1 삭제(D3) | V2 정본. PostgreSQL provider는 켜지면 자기 migration stream(`jpa/idempotency`)을 적용해야 "켜면 동작"(기준 3)을 충족. 실행기 조립은 한 곳. sample을 V2로 이전. `IdempotencyReaper`는 `postgresql` provider로 재조건 |
조사 원문: scratchpad `w2-inventory-A.md`, `w2-inventory-B.md`(세션 산출물). 순서: W2-1·W2-2·W2-4 병렬 → W2-3 → W2-5 → W2-6(동작 변경).
---
## Wave 3 — 분류 2(라이브러리형 API)
spec 5절: "완성해서 1번처럼 포장하거나 `optional-platforms`로 이동". 대상: redis-sdk, Mongo `advanced` 등, JPA 플랫폼 라이브러리, graphql `advanced`, websocket 플랫폼 라이브러리, web의 기본 경로 밖 라이브러리 패키지.
**확인한 사실 (2026-09-25 실험):** optional build(`src/optional-platforms`)에 `includeBuild('..')`를 넣으면 main build를 composite로 불러와 `dev.caskeleton:<leaf>` 좌표로 받을 수는 있다. 그러나 (1) redis-sdk의 테스트 전체가 cache-redis 테스트 소스에 들어 있어 이동하려면 테스트 이전이 먼저이고, (2) B안에서는 서비스가 고르지 않은 leaf가 jar에 들어가지 않으므로 optional build로 옮겨도 서비스가 내는 비용(jar·CVE·기동)은 줄지 않는다. 줄어드는 것은 main `ci` 시간뿐이다.
**결정:** 분류 2는 "옮기기" 대신 "완성해서 포장"으로 처리한다. 라이브러리는 유지하되:
1. 동작하지 않는 약속은 없앤다(기준 3): 어떤 코드도 바인딩하지 않는 설정 키, 켜면 기동이 실패하는 `Unsupported` 플래그, 구현체 없는 인터페이스, main에 있는 promotion/release/evidence gate, 테스트에서만 쓰는 main 클래스.
2. 남는 라이브러리 API는 leaf README에 "라이브러리 API — 서비스의 어댑터 leaf에서 `implementation`으로 받아 직접 호출"로 적는다(AGENTS.md capability 규칙의 라이브러리형 예외).
3. 기본 조립에 들어가는 leaf(`adapter:inbound:web`)에 있는 라이브러리 패키지는 opt-in leaf `adapter:inbound:web-advanced`로 분리한다. 기본 서비스가 쓰지 않는 코드를 싣지 않게 하기 위해서다.
4. redis-sdk는 이미 독립 leaf다. 테스트를 cache-redis에서 redis-sdk leaf로 옮겨 cache-redis가 테스트에서도 redis-sdk에 의존하지 않게 한다.
| 묶음 | leaf | 내용 |
|---|---|---|
| W3-1 | redis-sdk, cache-redis | SDK 테스트 이전, cache-redis의 redis-sdk test edge 제거, README |
| W3-2 | adapter:inbound:web → web-advanced | 기본 경로 밖 패키지(advanced, admin/route, budget, cache, contract, operation, proxy 등) 분리, registry 등록 |
| W3-2b | web-advanced | W3-2 결과 후속: `advanced/functional`(WebFlux `RouterFunction` — D4상 servlet 전용 템플릿에서 동작 불가)과 운영이 이미 다른 방식으로 하는 기능의 중복 패키지(`proxy`↔`forward-headers-strategy`, `security` 프로필↔`SecurityConfig`, `cache`↔`CacheControlFilter`, `json` factory↔Boot Jackson, `openapi` customizer↔`OpenApiContractConfig`) 삭제 — "한 기능에 한 세대" |
| W3-3 | graphql | 동작하지 않는 약속 제거, 라이브러리 API 문서화 |
| W3-4 | websocket | 같음 |
| W3-5 | persistence-mongo | 같음(구현체 없는 인터페이스 10개, 바인딩 안 되는 `advanced.*.enabled` 등) |
| W3-6 | persistence-jpa | 같음(지원 표면 밖 단일 구현 인터페이스, 호출자 없는 실행기 등) |
완료 기준: 각 leaf에서 기준 3 위반(동작하지 않는 설정·인터페이스·gate) 0건, README에 라이브러리 API 목록, web 기본 leaf에 라이브러리 패키지 없음, 영향 leaf `check` + `architectureCheck` 통과.
---
## Wave 4 — 분류 1 capability 포장 + 기본 조립 web-only
대상 capability와 "한 줄":
| capability | `app-bootstrap/build.gradle` 한 줄 | 모듈로 옮길 bootstrap 코드 |
|---|---|---|
| JPA/PostgreSQL (Flyway, TransactionPort, outbox store, JDBC 멱등성, 분산 락) | `runtimeOnly project(':adapter:outbound:persistence-jpa')` | `autoconfigure/jpa/*`, `autoconfigure/lock/*`, JPA 계열 `runtime/*Validator`, `MigrationStartup*`, `DataSourceRequirement` |
| outbox relay | (JPA + Kafka를 둘 다 고르면 켜짐) | `autoconfigure/outbox/*` → 발행 쪽 capability(messaging)로, `@ConditionalOnBean(OutboxStorePort)` + `afterName` |
| Redis (cache/lock/idempotency/rate-limit) | `runtimeOnly project(':adapter:outbound:cache-redis')` | `autoconfigure/redis/*`, Redis 계열 validator |
| Kafka 발행 | `runtimeOnly project(':adapter:outbound:messaging-kafka')` (bridge + platform starter-kafka를 끌어옴) | `autoconfigure/messaging/*`, `DisabledMessagingSentinelAutoConfiguration` 삭제 |
| 알림 (SES/SMTP) | `runtimeOnly project(':adapter:outbound:notification')` | `autoconfigure/notification/*`; notification persistence를 `persistence-notification` leaf로 추출(S2 #1), web notification HTTP를 `adapter:inbound:web-notification`으로 추출(S5 #9). 미조립 provider 5종 삭제(spec 6절 3) |
| Mongo | `runtimeOnly project(':adapter:outbound:persistence-mongo')` | `MongoOptInAutoConfigurationImportFilter` 삭제, "있으면 켜짐" |
| object storage (S3) | `runtimeOnly project(':adapter:outbound:objectstorage')` | 모듈 자체 auto-config 정리 |
| HTTP client | `runtimeOnly project(':adapter:outbound:httpclient')` | master switch 제거 |
| GraphQL | `runtimeOnly project(':adapter:inbound:graphql')` | `GraphQlOffAutoConfigurationImportFilter` 삭제 |
| WebSocket / gRPC 어댑터 | `runtimeOnly project(':adapter:inbound:websocket')` / `grpc` | conditional-transport qualification을 기본 조립 테스트로 대체 |
| 파일 서버 | `runtimeOnly project(':composition:fileserver-platform')` | bootstrap의 fileserver 스위치·설정·`dependencyPolicy` 항목 삭제 |
capability마다 spec 6절 완료 기준 7개를 체크한다: 포트만 호출 / 자기 `AutoConfiguration.imports` + `enabled`(기본 true) + `afterName` / 켜면 완전히 동작 / prefix 하나 + `StrictSettingsBinder` + compact constructor / 포트 계약 테스트(fake + adapter, Testcontainers 1개 이상) / README(제공·한 줄·env) / bootstrap이 모듈을 모름.
bootstrap에서 삭제: `MasterSwitch`(+ shared-contract `activation`), `MasterSwitchEnvironmentPostProcessor`, `CapabilityDependency*`, `AdapterActivation*`, `CaSkeletonApplication` scan 제외 정규식(scan은 `dev.caskeleton.bootstrap`으로 좁히고 web은 자기 auto-config 공개), 흩어진 startup validator(각 capability로 이동하거나 `StartupRule` 목록 하나로).
아키텍처 검사 분리(spec 7절): `architectureTest` classpath에는 모든 모듈을 테스트 의존으로, 운영 `runtimeClasspath`에는 고른 모듈만.
기본 조립: web + 관측 + 코어 + support/identifier. 나머지 한 줄은 주석으로 목록에 남긴다.
완료 기준:
- 기본 조립으로 `bootRun`/system test 기동 성공, DB·Redis·Kafka 없이.
- capability 한 줄을 추가/삭제하는 system test(대표 3개: JPA, Redis, Kafka)가 bean 생성/부재를 확인.
- 끄는 장치 5종(MasterSwitch, import filter 2, sentinel, scan 정규식)의 main 참조 0.
- sample-portfolio가 자기 조립(JPA, objectstorage, web, identifier 한 줄씩)으로 기동·테스트 통과.
---
### Wave 4 상세 Task (작업 묶음)
조사 결과(세션 산출물 `w4-inventory.md`)로 순서를 정했다. 모두 app-bootstrap을 건드리므로 JPA 계열은 순차, 나머지는 파일이 겹치지 않는 범위에서 병렬.
| 묶음 | 내용 |
|---|---|
| W4-1 | 준비: 옮겨 갈 클래스가 쓰는 bootstrap 전용 helper(`StartupFailures`, `ReadinessGroup` 등)를 `adapter:outbound:support`로, persistence-jpa에 support edge 추가, 연결 안 된 `JpaPlatformAutoConfiguration` 삭제. lock·outbox·Redis 조립 코드를 각 leaf로(outbox relay는 발행 포트 bean이 있을 때만), `DisabledMessagingSentinelAutoConfiguration` 삭제 |
| W4-2 | JPA root(`autoconfigure/jpa/*`, JPA validator, Flyway startup, `application.yml`의 datasource/flyway/jpa 블록, `persistence.yml`)를 persistence-jpa로. `JpaOffAutoConfigurationImportFilter`·`DataSourceRequirement` 삭제. sample이 broad scan 대신 leaf auto-config로 JPA를 받게 |
| W4-3 | 알림: `composition/notification-platform` 신설(조립 클래스 2개 + `notification.yml`), web의 `notification/` callback ingress를 web 밖으로 옮겨 기본 web이 `application-notification`을 싣지 않게 |
| W4-4 | messaging·Mongo·GraphQL·httpclient·objectstorage·websocket·gRPC·파일 서버: import filter 삭제, "있으면 켜짐"(`enabled` 기본 true), 설정 yml을 leaf로, Rabbit 설정 키 제거 |
| W4-5 | 끄는 장치 철거(`MasterSwitch`·activation 패키지·scan 정규식·`CapabilityDependency*`·`AdapterActivation*`), 기본 조립을 web-only로 바꾸고 나머지는 주석 한 줄 목록, architectureTest classpath에 모든 leaf, registry 정리, 관련 테스트 삭제·재작성, 기본 조립 기동 테스트 + capability 한 줄 추가/삭제 테스트(JPA·Redis·Kafka), capability README(제공·한 줄·env) |
## Wave 5 — 빌드 O3 + 테스트 컨벤션
1. 2차 리뷰 BUILD 절 "바로 할 것" 1–12를 순서대로 적용한다(Wave 2–4에서 이미 사라진 대상은 건너뛰고 진행 기록에 적는다).
2. O3: build-logic에는 registry, 방향·순수성 task, 컨벤션, 레인 하나만. 기능별 검사(evidence, readiness, API-surface, family plugin)는 소유 leaf 테스트로 옮기고, 읽는 파일은 `inputs`로 선언한다. build-tools는 비운다.
3. 테스트 컨벤션: `sample-portfolio` 전체 테스트를 AGENTS.md 컨벤션으로 재작성(`WorkLogRepositoryContract`로 fake와 adapter 공통 계약, `TransactionPort` fake는 application-core testFixtures 하나).
완료 기준: `./gradlew ci --console=plain` 통과, build-logic+build-tools 줄 수 감소 기록, sample 테스트 GWT 컨벤션 적용.
---
## 진행 기록
| Wave | 상태 | 검증 | 스냅샷 | 비고 |
|---|---|---|---|---|
| 0 | 완료 (2026-09-25) | build-logic test, persistence-jpa·messaging·app-bootstrap·sample `check`, `architectureCheck`, PG lane `postgresqlMigrationIntegrationTest`·`postgresqlLegacyOutboxRowLifecycleIntegrationTest` 전부 통과 | scratchpad `wave-0.patch` | outbox-storage V1은 Wave 2(D2 삭제)로 넘김. V16 적용 확인(실제 PostgreSQL) |
| 1 | 완료 (2026-09-25) | 10건 모두 재현 테스트 FAIL→PASS. main에서 영향 leaf 20개 `check` + `app-bootstrap:check` + `sample-portfolio:check` + `architectureCheck` + `verifyDependencyLocks` + `verifyEnvKeys` 통과, optional gRPC `check`·ledger PG lane 통과. PG lane(durable operation 계약 24, notification background 7), gRPC ledger 계약 16 실제 DB 통과 | scratchpad `wave-1-cumulative.patch` | 새 env key `APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`(SES 콜백 사용 시 필수). 남은 것: Redis 실제 lane 기존 실패 4건(테스트 ACL에 TIME 권한 없음, 시계 +1h), durable operation 같은 id 재시도 시 outbox 중복, Redis idempotency/lease의 lane 거부 분류가 Indeterminate, Kafka truststore/keystore 설정 키 없음 |
| 2 | 완료 (2026-09-25) | W2-1~W2-6 반영 후 main 전체 `check` + `architectureCheck` + locks + env keys + public path + config contract 통과. W2-5 fencing은 실제 PG에서 중복 전달 재현 후 해결, W2-6 PostgreSQL 멱등성은 빈 DB에서 실패 재현 후 해결 | scratchpad `wt-w2*.patch` | 제거 목록은 `docs/capability-status.md` "제거된 코드" 표 |
| 3 | 완료 (2026-09-25) | W3-1~W3-6, W3-2b 반영 후 main 전체 `check` 통과(Redis/Mongo/websocket/web/JPA/graphql 실제 lane은 각 묶음에서 실행) | scratchpad `wt-w3*.patch` | web 기본 leaf 13.9k→5.3k줄(라이브러리는 opt-in `web-advanced`), graphql 22k→12.8k, websocket 10.2k→1.9k. 추가 수정: notification admin 결과 codec jsonb 공백 결함(기존) |
| 4 | 완료 (2026-09-25) | main 전체 `check` + `architectureCheck` + locks + env keys + public path + config contract + `qualificationBootJar` 통과. 기본 runtimeClasspath = web·identifier·support·domain-core·application-core·shared-contract. `DefaultCompositionBootTest`(local/dev/prod, DB·Redis·Kafka 없이) + capability별 활성화 테스트 | scratchpad `wt-w4*.patch` | 끄는 장치(MasterSwitch·activation·scan 정규식·import filter·sentinel) 제거. CI compose 18 lane 실제 실행 안 함(정적 검증만). `S3AsyncResponseBodyBridgeTest` 부하 시 간헐 실패 |
| 5 | 완료 (2026-09-25) | `check`(481 task), `ci verifyDependencyLocks --warning-mode=fail`, `mainCheck`(14 lane 152 tests), build-logic 80·build-tools 35 tests, bootstrap/sample integration·system, configuration cache 통과 | scratchpad `wt-w51/w52/wfin.patch` | 빌드 코드 17.2k→10.8k줄(바로 할 것 1–12 적용, notification·mongo·messaging·graphql·jpa 검사를 leaf 테스트로). sample 테스트 컨벤션 적용(test 198→283, integration 13→49). 남은 설계 결정: `verifyEnvKeys`·JPA evidence·redis topology lane 이동 여부 |
@@ -0,0 +1,128 @@
# 부가 기능(capability) 제공 방식과 리뷰 후속 정리 — 설계 초안
- 상태: **확정** (2026-09-25 소유자 결정 2건 반영 — 10절). 실행 계획: `docs/superpowers/plans/2026-09-25-capability-module-packaging.md`
- 작성: 2026-09-25
- 입력:
- `docs/reviews/2026-09-24-src-module-code-review.md` (1차, 결함 중심 — Critical 15 / Required 76)
- `docs/reviews/2026-09-24-src-maintainability-review.md` (2차, 구조·SRP·공통 계약·테스트·빌드 비례성)
- 목표: 템플릿에서 새 프로젝트를 만들 때 도메인과 비즈니스 로직을 바로 붙이고, 실무에서 자주 쓰는 부가 기능(Redis, Kafka 등)은 필요할 때 빠르게 붙일 수 있게 한다.
## 1. 전제 (소유자 설명)
2차 리뷰에서 "연결 안 된 코드 약 15만 줄"로 잡힌 코드 상당수는 **의도적으로 넣어 둔 부가 기능**이다. 프로젝트마다 자주 쓰는 외부 기술(Redis, Kafka 등)을 템플릿이 미리 제공하려고 만들었다. 그러다 너무 커져서 지금 리팩터링하는 중이다. 따라서 목표는 부가 기능을 없애는 것이 아니라 **제공 방식을 바꾸는 것**이다.
## 2. 핵심 결론
부가 기능을 제공하는 방향은 유지한다. 문제는 제공 방식이다. 지금은 부가 기능이 두 가지 상태로 흩어져 있다.
- (a) 기본 모듈 안에 섞여 있다.
- (b) 설정으로 켜도 실제로 동작하지 않는 반쪽 상태다.
그래서 그 기능을 쓰지 않는 서비스도 비용을 낸다. 해법은 두 가지다.
- 부가 기능 하나하나를 **"의존성을 붙이면 켜지고, 떼면 사라지는 capability 모듈"**로 포장한다(Spring Boot starter와 같은 방식).
- 각 서비스는 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
## 3. 흐름
```
[도메인·유스케이스 코드] ──(포트만 호출)──▶ application-core 포트 (CachePort, LockPort …)
▲ 구현
app-bootstrap/build.gradle │
runtimeOnly ':adapter:outbound:cache-redis' ──▶ cache-redis 모듈
├─ META-INF/spring/…AutoConfiguration.imports
└─ app.redis.* 설정 + 연결 env
```
기능 추가: `app-bootstrap/build.gradle`에 한 줄을 넣고, `.env`에 연결 정보를 넣는다. 유스케이스는 원래 쓰던 포트를 그대로 호출한다.
기능 제거: 그 한 줄을 지운다. 다른 파일은 손대지 않는다.
```groovy
// app-bootstrap/build.gradle — 이 서비스가 쓰는 부가 기능 목록 (한 곳에서 관리)
dependencies {
runtimeOnly project(':adapter:outbound:cache-redis') // Redis: cache / lock / idempotency / rate-limit
runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
// runtimeOnly project(':adapter:outbound:persistence-mongo')
// runtimeOnly project(':adapter:outbound:objectstorage')
}
```
## 4. 조립 방식 비교
| 방식 | 추가 속도 | 비용 |
|---|---|---|
| A. 모든 모듈을 runtimeOnly로 기본 포함 + 설정으로 on/off | 설정만 바꾸면 됨 | 끄는 장치 필요, 모든 서비스가 모든 의존성·CVE·이미지 크기를 짊어짐 |
| **B. 서비스가 고른 것만 runtimeOnly 한 줄 + "모듈이 있으면 켜짐" (권장)** | 한 줄 + env | 끄는 장치 불필요. upstream(템플릿) merge 시 서비스 쪽 차이는 이 목록 한 곳뿐 |
| C. 각 기능을 버전 붙은 사내 라이브러리로 배포 | 버전 한 줄 | 배포 파이프라인 필요. 파생 서비스가 3개 이상일 때 검토 |
**A를 권하지 않는 이유:** Spring Boot는 "라이브러리가 classpath에 있으면 켠다"가 기본 동작이다. 쓰지 않는 기능을 jar에 넣어 두면 그것을 끄는 장치가 따로 필요하다. 지금 저장소에 있는 아래 목록이 바로 그 장치이고, 2차 리뷰에서 "활성화 규칙 6곳, 기본값 3가지"로 나온 복잡도의 원인이다.
- `MongoOptInAutoConfigurationImportFilter`
- `GraphQlOffAutoConfigurationImportFilter`
- `DisabledMessagingSentinelAutoConfiguration`
- `CaSkeletonApplication`의 scan 제외 정규식(18개 패키지)
- `MasterSwitch`
- 흩어진 startup validator 19개
`runtimeOnly`라는 방식 자체는 맞다. 비즈니스 코드가 어댑터를 import하지 못하게 되기 때문이다. 다만 **서비스가 고른 것만** 넣어야 끄는 장치가 필요 없어진다.
## 5. "연결 안 된 코드" 4분류
| 분류 | 예 | 처리 |
|---|---|---|
| 1. 제공할 부가 기능 (포트 뒤에 있음) | Redis cache/lock/idempotency/rate-limit, Kafka 발행, S3 object storage, SES/SMTP 알림, httpclient, Mongo 기본 연결 | 유지. 6절 완료 기준을 채워 capability 모듈로 포장 |
| 2. 라이브러리형 API (서비스 코드가 직접 호출) | redis-sdk facade(구현체 없음), Mongo advanced 연산, JPA bulk/copy, graphql advanced, websocket 플랫폼 라이브러리 | 완성해서 1번처럼 포장하거나 `optional-platforms`로 이동 |
| 3. 리팩터링 잔재 (이전·병행 세대) | web 2세대, WebFlux 쌍둥이, outbox V2와 v1, 멱등성 v1, notification R1, messaging R1 encoder, fileserver R2 publication, STOMP 스택 2벌, main에 있는 governance gate | 하나만 남기고 삭제. 제공 기능이 줄지 않으면서 크기가 가장 많이 줄어듦 |
| 4. SDK도 없는 실험용 자리 | pulsar, nats, kafka-share, stream-bridge, 기동 시 거부되는 rabbit, grpc-advanced | `optional-platforms`로 이동하거나 삭제 |
모듈별 LOC와 근거는 2차 리뷰의 "조립되지 않은 코드 추정치" 표와 S1–S7 절에 있다.
## 6. capability 모듈 완료 기준
1. 서비스 코드는 application-core의 **포트만** 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다.
2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled` 설정으로 끌 수 있다. 다른 자동 설정에 기대는 경우 순서를 명시한다(`afterName`). 1차 리뷰 Critical #6(messaging bridge)이 이 순서 문제였다.
3. **켜면 완전히 동작한다.** 문서에 적은 옵션은 전부 실제로 동작해야 하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다. 반례: 알림 provider 7종 중 5종은 켜면 기동에 실패한다.
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`로 하고, 값 검증은 설정 record의 compact constructor에서 한다.
5. application-core testFixtures에 있는 **포트 계약 테스트**(추상 클래스)를 fake와 실제 어댑터가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
6. README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 `MasterSwitch` 목록에 등록할 필요가 없고, 한 줄을 지우면 기능이 완전히 사라진다.
## 7. 주의할 점
- **`runtimeOnly`의 한계:** 분류 2처럼 서비스 코드가 모듈 타입을 직접 호출하는 경우에는 `runtimeOnly`로 컴파일되지 않는다. 이런 모듈은 서비스의 어댑터 leaf에서 `implementation`으로 받아야 한다. 부가 기능은 가능한 한 분류 1(포트 뒤) 형태로 만든다.
- **아키텍처 검사 범위:** 운영 jar에 고른 모듈만 들어가면, app-bootstrap architectureTest의 classpath 기준으로 도는 ArchUnit이 빠진 모듈을 보지 못한다. 그래서 둘을 분리한다.
- architectureTest classpath에는 **모든 모듈을 테스트 의존으로** 넣는다.
- 운영 runtimeClasspath에는 고른 모듈만 넣는다.
- 참고로 Gradle 방향 검사는 이미 모든 leaf를 본다.
- 1차 리뷰 L-4에서 sample과 grpc 어댑터가 ArchUnit에서 빠진 것도 같은 원인이다.
## 8. 리뷰 결정 D1–D6 권고 (이 방향 기준)
| # | 결정 | 권고 |
|---|---|---|
| D1 | 연결 안 된 코드 | 5절 4분류를 적용한다: 1은 포장, 2는 완성 또는 이동, 3은 삭제, 4는 이동 |
| D2 | outbox 정본 | 앱 outbox를 하나로 합친다. v1 테이블을 유지하고 V2/V1002의 owner+token fencing을 이식한 뒤 V2를 삭제한다. Kafka capability는 이 outbox를 relay한다. messaging platform outbox는 vendored라 유지한다 |
| D3 | 멱등성 정본 | V2. Redis와 PostgreSQL 두 provider가 같은 포트를 구현하고, executor는 한 곳에서 조립한다 |
| D4 | WebFlux | 템플릿은 servlet(가상 스레드)으로 정하고 WebFlux 쌍둥이 코드는 삭제한다. 필요해지면 capability로 다시 추가한다 |
| D5 | 빌드 목표 | O3. 기능별 검증은 각 capability 모듈의 테스트로 옮기고, build-logic에는 아키텍처 검사와 공통 규칙만 남긴다. 먼저 2차 리뷰 BUILD 절의 "바로 할 것" 1–12를 적용한다 |
| D6 | 테스트 컨벤션 | 2차 리뷰 TEST 절의 제안안을 채택한다. 포트 계약 테스트가 6절 완료 기준 5번과 같은 것이다 |
## 9. 진행 순서
1. capability 완료 기준(6절)과 테스트 컨벤션을 `AGENTS.md`에 고정한다. `CLAUDE.md`는 요약만 동기화한다.
2. 1차 리뷰 Critical을 수정한다. 대부분 제공 기능 자체의 결함이라 먼저 고친다. 수정 PR마다 해당 포트의 계약 테스트를 함께 추가한다.
- Wave 0(결정 불필요): 빌드 plugin(O-1), CI job(O-2), 마이그레이션 원복 + 새 버전(E-1), `@EnableScheduling`(L-1), bridge 순서/producer-id(H-1), prod 에러 상세 validator(L-2), sample loggers read-only(L-3)
- Wave 1: 나머지 데이터·보안 Critical
3. 분류 3·4를 삭제하거나 이동한다. 크기가 가장 많이 줄어든다.
4. 분류 1을 capability 모듈로 하나씩 포장한다. 끝날 때마다 bootstrap의 끄는 장치(import filter, scan 정규식, MasterSwitch 항목, 해당 validator)를 걷어낸다.
5. 빌드를 O3로 옮기고, 테스트 컨벤션을 적용한다(sample-portfolio부터 모범 예제로).
## 10. 결정 (2026-09-25 소유자 확정)
1. 기본 조립 방식은 **B(서비스가 고른 것만 runtimeOnly)**로 확정한다.
2. 템플릿이 처음부터 켜 두는 기능은 **web에서 쓰는 부분뿐**이다.
- 기본 포함: HTTP 인바운드(`adapter:inbound:web` — servlet, 보안, 에러 응답, 요청 로깅), 운영 관측(actuator·metrics·tracing·로그), 도메인·유스케이스 코어(`domain-core`, `application-core`, `shared-contract`), 저장소가 필요 없는 보조(`adapter:outbound:support`, `adapter:outbound:identifier`).
- 기본 제외(한 줄로 추가): JPA/PostgreSQL(Flyway·outbox·JDBC 멱등성·분산 락 포함), Redis, Kafka, 알림, Mongo, object storage, HTTP client, GraphQL, WebSocket, gRPC, 파일 서버.
- 해석 근거: "web에서 사용하는 부분"을 인바운드 HTTP와 그 운영 요소로 읽었다. DB도 기본에서 뺐으므로 새 서비스는 DB가 필요하면 `persistence-jpa` 한 줄을 넣는다. 이 해석이 다르면 `app-bootstrap/build.gradle`의 해당 줄 주석만 푼다(다른 파일 변경 없음 — 6절 7번).
실행 계획: `docs/superpowers/plans/2026-09-25-capability-module-packaging.md` (Wave 0부터).
+1 -1
View File
@@ -71,7 +71,7 @@ Markdown 표와 Gradle source set을 대조하는 parser는 current-state를 또
| Application use case | TEST | fake/stub port, 필요 최소 mock |
| startup validator / settings validation | TEST | `MockEnvironment` 또는 순수 객체 |
| Spring `@Configuration` 한 조각 | TEST | `ApplicationContextRunner` |
| MVC/WebFlux controller 한 slice | TEST | framework slice test |
| MVC controller 한 slice | TEST | framework slice test |
| hermetic serialization/API snapshot | TEST | contract assertion |
| JPA repository + 실제 PostgreSQL | INTEGRATION | Testcontainers/real DB |
| Kafka/Rabbit/Redis/Mongo와 실제 프로토콜 통신 | INTEGRATION | real service/container |
+53 -34
View File
@@ -1,58 +1,77 @@
# Web Advanced: support matrix
Every capability is off unless named. `WebAdvancedPromotionGate.forFeature` is the machine-checked
form of the last two columns; if this table disagrees with it, the code wins.
The Advanced capabilities live in their own leaf, `adapter:inbound:web-advanced`
(`src/adapter/inbound/web-advanced`, package `dev.caskeleton.adapter.inbound.web.advanced`). No
default composition carries it: `app-bootstrap` and `sample-portfolio` do not depend on it. A
service that wants one of these capabilities adds the leaf as `implementation` in its own adapter
leaf and calls the types directly.
| Capability | Flag | What it adds | Required suites | Soak |
| --- | --- | --- | --- | --- |
| `MVC_VIRTUAL_THREADS` | `backend.web.advanced.mvc-virtual-threads.enabled` | A different scheduling model for **every** request | `web:test`, `webCrossStackParityTest`, `virtual-thread-admission`, `pinning-jfr` | 24h |
| `WEBFLUX_BLOCKING_BRIDGE` | `…webflux-blocking-bridge.enabled` | A bounded offload; affects the shared event loop | `web:test`, `blocking-bridge-bounded`, `event-loop-guard` | 24h |
| `JSON_MERGE_PATCH` | `…json-merge-patch.enabled` | RFC 7396, partial documents | `web:test`, `patch-security`, `patch-atomicity` | 8h |
| `JSON_PATCH` | `…json-patch.enabled` | RFC 6902, arbitrary pointers | as merge patch | 8h |
| `SSE` | `…sse.enabled` | Long-lived connections | `web:test`, `streaming-soak-10k`, `slow-consumer-bounded`, `cancellation-propagation`, `pod-drain` | 24h |
| `NDJSON` | `…ndjson.enabled` | Long-lived connections | as SSE | 24h |
| `JSON_SEQUENCE` | `…json-sequence.enabled` | Long-lived connections | as SSE | 24h |
| `FUNCTIONAL_WEBFLUX` | `…functional-webflux.enabled` | Routes with no annotation to scan | `web:test`, `functional-route-parity` | 8h |
| `CBOR` | `…cbor.enabled` | A second decoder | `web:test`, `codec-security`, `codec-budget` | 8h |
| `XML` | `…xml.enabled` | A decoder with dangerous defaults | as CBOR | 8h |
| `OPENAPI_32` | `…openapi-32.enabled` | A parallel description artifact | `web:test`, `openapi-32-toolchain-matrix` | 8h |
| `RATELIMIT_DRAFT_HEADERS` | `…ratelimit-draft-headers.enabled` | Additive response headers | `web:test`, `ratelimit-draft-headers` | 8h |
Three capabilities have a runtime switch, published through the leaf's own
`META-INF/spring/...AutoConfiguration.imports`. Everything else is a library: no property, no bean,
nothing happens until service code calls it.
## Two capabilities change requests that do not use them
| Capability | How it is turned on | What it adds | Tests |
| --- | --- | --- | --- |
| MVC virtual threads | `backend.web.advanced.mvc-virtual-threads.enabled=true` (+ admission limit and budgets) | A different scheduling model for **every** request | `MvcAdvancedConfigurationTest`, `VirtualThreadAdmissionTest` |
| NDJSON streaming | `backend.web.advanced.ndjson.enabled=true` | Long-lived connections | `MvcStreamingWiringTest`, `WebStreamCoreTest`, `WebStreamDrainTest`, `WebStreamingSoakIT` |
| JSON text sequences (RFC 7464) | `backend.web.advanced.json-sequence.enabled=true` | Long-lived connections | as NDJSON |
| JSON Merge Patch (RFC 7396) | library — `JsonMergePatchApplier` | Partial documents | `JsonMergePatchApplierTest` |
| JSON Patch (RFC 6902) | library — `JsonPatchApplier` | Arbitrary pointers | `JsonPatchApplierTest` |
| CBOR / XML codecs | library — `WebCborMapperFactory`, `WebXmlMapperFactory`; the backend jar is the service's choice | A second decoder | `WebCodecMapperTest`, `WebCodecSecurityTest` |
| OpenAPI 3.2 | library — `WebOpenApi32Generator` | A parallel description artifact | `WebOpenApi32GeneratorTest` |
| Stream replay from messaging | library — `MessagingReplayBridge` | Resume after reconnect | `MessagingReplayBridgeTest` |
`WebAdvancedFeature.affectsUnrelatedRequests()` is true for exactly `MVC_VIRTUAL_THREADS` and
`WEBFLUX_BLOCKING_BRIDGE`. A codec affects only requests that negotiate it; a virtual-thread
executor affects every request in the process, and the blocking bridge affects the event loop they
all share. `WebAdvancedFeatureFlags.stableBehaviourPreserved()` reports whether either is on.
The same leaf also holds the web library packages the servlet production path never reaches:
`http` (URI and method policy), `versioning`, `operation`, `budget`, `contract`, `security`
(security-context bridge), `idempotency` (`JsonIdempotentResponseCodec`) and `admin/route`.
That distinction is why those two soak for 24 hours and why their rollback test is the one that
matters most.
`./gradlew :adapter:inbound:web-advanced:test` runs all of it. `webAdvancedTest` is the tagged
subset and fails when the tag selects nothing.
## Removed on 2026-09-25
- The promotion/release gate (`WebAdvancedPromotionGate`, `WebAdvancedReleaseManifest`,
`WebAdvancedFeature`) and the OpenAPI 3.2 promotion report (`OpenApi32CompatibilityReport`,
`OpenApiToolchainMatrix`). They were checks on this repository's release process kept in
production code, and only their own tests called them. The feature catalog also named flags that
no code reads (`…json-merge-patch.enabled`, `…sse.enabled`, `…cbor.enabled` and others).
- `advanced.blockingbridge`: the accounting half of the WebFlux blocking bridge, whose adapter went
with the WebFlux twin.
- `functional` (`FunctionalRouteRegistry`, `WebFunctionalHandlerAdapter`): it built a WebFlux
`RouterFunction`, which nothing serves in a servlet-only template (D4). `spring-webflux` left the
leaf with it.
- Packages that re-implemented what the production web path already does another way, and the
`webNginxProxyTest` lane that certified only one of them:
- `proxy` + `http.External*` — production uses `server.forward-headers-strategy`
(`app-bootstrap/src/main/resources/config/server.yml`).
- `security` CORS/CSRF profiles — production uses `CorsSettings` and `SecurityConfig`.
- `cache` — production uses `CacheControlFilter`.
- `json` (`WebObjectMapperFactory`) — production uses Boot's `JsonMapper`; the streaming encoder
now writes with that bean.
- `openapi.WebOpenApiCustomizer` (+ `WebOpenApiProfile`, `CursorSchemaContributor`) —
production customizes springdoc through `OpenApiContractConfig`.
Recovery paths are in `docs/capability-status.md` (the removed-code table).
## What is refused, and why the row is here
| Refused | Reason |
| --- | --- |
| Virtual threads without an admission limit | The pool size *was* the admission policy. Removing it accepts every arrival and queues them on downstream budgets that did not grow. |
| A blocking offload for an unregistered operation | `boundedElastic()` is reachable from anywhere and unbounded in practice; an unenumerable set of offloads is invisible until the pool is the heap. |
| A merge patch outside its field allowlist | A merge patch is partial, so no DTO's absent fields say "not permitted". Without an allowlist the writable set grows every time somebody adds a field. |
| A JSON Patch pointer above its allowed prefix | Replacing a parent deletes every sibling, so permission on a child cannot grant it. |
| A `move` whose source is unauthorized | Checking only the destination lets a caller relocate data out of a field they may not touch. |
| XML with a DTD or an external entity | Billion-laughs and XXE. Neither errors when it fires; the parse succeeds and the document contains something it should not. |
| A non-JSON representation without all three gates | Flag, route `produces`, and client allowlist. An `Accept` header is not evidence the route was tested against that codec. |
| A non-JSON representation without all three gates | The enabled set the service passes to `RepresentationNegotiationPolicy`, route `produces`, and client allowlist. An `Accept` header is not evidence the route was tested against that codec. |
| Compression-style silent fallback on a 406 | A client that asked only for CBOR and gets JSON parses the bytes as CBOR and fails somewhere far away. |
| Changing HTTP status after commit | The body becomes half stream, half JSON, and the 200 is cached. |
| Unbounded buffering for a slow consumer | It moves the client's slowness into the server's heap. |
## Promotion
## Turning it off
Each capability is promoted on its own evidence. Two conditions apply to all and are not waivable:
- **Rollback exercised.** A flag nobody has turned off is not known to turn off.
- **Stable behaviour unchanged with the feature off.** If it is not, the feature was never optional
and every deployment has it.
Parsers and patch appliers additionally require a security review —
`WebAdvancedPromotionGate.needsSecurityReview` names them.
Removing the dependency removes the capability. With the dependency present, the three switches
default to off; `WebAdvancedRollbackIT` asserts that no Advanced bean exists with no flag set and
with each flag explicitly `false`.
See `docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md`,
`ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md`, and
+10 -35
View File
@@ -9,49 +9,24 @@ The value of an API description is entirely in what consumes it. A document in a
generator does not fully understand does not fail — it produces a client that compiles and is wrong,
which is worse than no document at all.
So 3.1.2 stays the release artifact and 3.2 is generated beside it, with a report.
So 3.1.2 stays the release artifact and 3.2 is generated beside it.
## The invariant
**Generating 3.2 must not change the 3.1 snapshot.** Both come from the same model, so a contributor
that mutates it on the way to 3.2 changes the artifact that is actually shipped — silently, and only
when the experimental lane runs.
when 3.2 is generated.
`OpenApi32CompatibilityReport` hashes the snapshot before and after, and a difference is a promotion
blocker with its own message.
Nothing in this repository checks it any more. `OpenApi32CompatibilityReport` and
`OpenApiToolchainMatrix` — the promotion report that hashed the snapshot and recorded which parser,
linter, generator and client compile had read the 3.2 output — were removed on 2026-09-25: they
lived in production code and only their own tests called them. A service that generates 3.2 with
`WebOpenApi32Generator` (library, `adapter:inbound:web-advanced`) owns that check in its own build.
## The toolchain matrix
Four kinds of tool, checked separately, because passing one says nothing about the others:
| Kind | What it catches | What it misses |
| --- | --- | --- |
| Parser | Structural errors | Anything semantically odd |
| Linter | Style rule violations | Accepts documents a parser rejects |
| Generator | Unsupported constructs — sometimes | Usually emits a wrong-but-valid signature instead of failing |
| Client compile | The wrong signature the generator emitted | Runtime behaviour |
`OpenApiToolchainMatrix.complete()` requires at least one passing tool of each kind.
`gaps()` names the kinds that have none.
"OpenAPI 3.2 works" is not a statement anybody can make. "This document is read correctly by these
four tools at these versions" is.
## Streaming descriptions
The substantive difference between 3.1 and 3.2 for this application is how streaming responses are
described. Those differences are reported separately rather than folded into a pass/fail, because a
green pass hides what changed.
## Promotion
`promotionBlockers(adrAccepted)` always includes the ADR blocker until one is accepted, however
green the matrix is. A machine-checkable matrix cannot decide whether the consumer population is
ready; that is a judgement, and it belongs in
Promotion stays a judgement, recorded in
`docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`.
## Running it
The experimental generation runs in its own workflow and publishes the 3.2 document and the
compatibility report as artifacts. It never runs in the release workflow, so the release artifact
cannot depend on whether it ran.
No workflow in this repository generates 3.2. `OpenApiVersionLane.STABLE_3_1` is the release
artifact; `WebOpenApi32GeneratorTest` covers the generator.
+3 -1
View File
@@ -1,6 +1,8 @@
# Web patch: the client contract
Two patch formats, and they are not interchangeable.
Two patch formats, and they are not interchangeable. Both appliers are library code in
`adapter:inbound:web-advanced` (opt-in): a service adds the leaf and calls `JsonMergePatchApplier`
or `JsonPatchApplier` from its controller.
## Choosing one
+61 -141
View File
@@ -6,6 +6,12 @@ was written against a standalone repository. Four of its assumptions do not hold
document records what each became and why, so a reader comparing the design to the tree is not left
guessing whether a difference is a decision or a mistake.
> **2026-09-25 (D4, Wave 2 W2-3).** The template is servlet (Spring MVC) on virtual threads. The
> WebFlux twin, the second-generation problem-document/budget/throttle/admission platform, the
> durable-operation HTTP projection and the in-leaf module-boundary check were removed. HTTP errors
> are the `Envelope` written by `GlobalExceptionHandler`. What was removed, and the commit it last
> existed in, is listed in `docs/capability-status.md` ("제거된 코드").
## 1. Twenty-three Gradle modules became sub-packages of one leaf
The design lays the platform out as `modules/web/web-core-api`, `web-contract`, `web-mvc` and so on.
@@ -14,20 +20,14 @@ list, and adding twenty-three leaves to it is an architecture decision the desig
repository's behalf. The JPA and GraphQL platforms reached the same fork and resolved it the same
way, so this is the established answer rather than a new one.
The substitution only holds if the boundaries are enforced, because a Gradle dependency gate cannot
see inside a leaf. `WebStableModule` declares each module's identity, package, purity grade and
allowed edges; `WebModuleBoundaryTest` scans the real source tree and fails when the tree and the
declaration disagree **in either direction** — an undeclared edge, an undeclared package, or a
declared module with no source. Four negative fixtures prove each rule can fail.
Each enum constant is already shaped like a leaf specification, so promoting a module to its own
Gradle path later is a registry edit rather than an archaeology exercise.
A Gradle dependency gate cannot see inside a leaf. The in-leaf module map that used to check the
package edges (`WebStableModule`) was removed with the second-generation platform; the ArchUnit
rules in `testkit/arch` (`WebArchitectureRules`) are what remains.
| Design module | Package under `dev.caskeleton.adapter.inbound.web` | Status |
| --- | --- | --- |
| `web-core-api` | `core` | planned (Task 2+) |
| `web-contract` | `contract` | planned |
| `web-validation` | `validation` | planned |
| `web-error` | `error` | present |
| `web-pagination` | `pagination` | present |
| `web-idempotency` | `idempotency` | present |
@@ -38,19 +38,16 @@ Gradle path later is a registry edit rather than an archaeology exercise.
| `web-observability` | `observability` | present |
| `web-openapi` | `openapi` | planned |
| `web-mvc` | `mvc` | planned |
| `web-webflux` | `webflux` | planned |
| `web-webflux` | — | removed (D4: servlet only) |
| `web-admin` | `admin` | planned |
| `web-operation-jpa` | `operation.jpa` | planned |
| `web-operation-messaging` | `operation.messaging` | planned |
| `web-spring-boot-starter-mvc` | `autoconfigure.mvc` | planned |
| `web-spring-boot-starter-webflux` | `autoconfigure.webflux` | planned |
| `web-testkit-*` | `testkit`, `testkit.mvc`, `testkit.webflux`, `testkit.contract` | planned |
| — | `conditional`, `cursor`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | present, pre-dates the design |
| `web-spring-boot-starter-webflux` | — | removed (D4: servlet only) |
| `web-testkit-*` | `testkit`, `testkit.mvc` | present |
| — | `conditional`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | present, pre-dates the design |
| — | `fileserver.*`, `notification.*` | present, feature integrations rather than platform modules |
A module is added to `WebStableModule` at the moment its package gains its first file, never before:
a declared module with no source is a claim about a rename that has not happened.
## 2. Root package
The design uses `io.backend.skeleton.web`. This repository's package root is
@@ -78,10 +75,13 @@ carries the OpenAPI drift gate and the contract lanes the design's sample is spe
## 6. Idempotency: the design's store SPI is already owned by `application-core`
The design gives `web-idempotency` its own `IdempotencyStore`, `IdempotencyRecord`,
`IdempotencyState`, `IdempotencyScope` and `RequestFingerprint`. This repository already has all
five in `application-core/idempotency`, with a JPA adapter
(`PostgreSqlOwnerSafeIdempotencyStore`, `IdempotencyStoreAdapter`) and a Redis cache behind them —
which is what the design's Tasks 39 and 40 ask for, built in the direction the registry permits.
`IdempotencyState`, `IdempotencyScope` and `RequestFingerprint`. This repository already has the
equivalents in `application-core/idempotency` — `IdempotencyStorePort`, `IdempotencyState`,
`IdempotencyScopeDigest` and `RequestFingerprint` — with two provider stores behind the port:
PostgreSQL (`PostgreSqlOwnerSafeIdempotencyStore` in `persistence-jpa`) and Redis
(`RedisIdempotencyStoreAdapter` in `cache-redis`), selected by
`ca-skeleton.capabilities.idempotency.provider`. That is what the design's Tasks 39 and 40 ask for,
built in the direction the registry permits.
Implementing the design's SPI literally would have required
`adapter-outbound-persistence-jpa → adapter-inbound-web`, an edge the registry forbids and one that
@@ -97,7 +97,7 @@ application use-case boundary.
| store / record / scope / claim / replay | `application-core/idempotency` |
| request fingerprint policy | application use case, because only the use case knows which fields define the same work |
| `Idempotency-Key` extraction | concrete inbound endpoint that opts into idempotency |
| replay JSON encoding | `adapter-inbound-web/idempotency/JsonIdempotentResponseCodec` |
| replay JSON encoding | `adapter-inbound-web-advanced/idempotency/JsonIdempotentResponseCodec` |
This avoids two authorities for “same request”. The HTTP adapter does not run its own database
replay policy; it translates the transport input into the application idempotency context and lets
@@ -118,7 +118,7 @@ holding a JPA store for long-running operations, with the port
This is the same shape as §6 and takes the same resolution — the one the repository already used
for idempotency, where `IdempotencyStorePort` lives in `application-core` and
`IdempotencyStoreAdapter` in `persistence-jpa`:
`PostgreSqlOwnerSafeIdempotencyStore` in `persistence-jpa`:
| Design type | Here |
| --- | --- |
@@ -128,15 +128,12 @@ for idempotency, where `IdempotencyStorePort` lives in `application-core` and
| the lease | `application-core/operation/OperationLease` |
| the stored failure | `application-core/operation/OperationFailure` — a code and an already-safe message, never an exception |
| `JpaDurableOperationStore`, `JpaOperationEntity`, `V002__web_operation.sql` | `persistence-jpa/operation/*`, `db/migration/postgresql/V11__durable_operation.sql` |
| `OperationResource`, `OperationStatus`, `OperationProgress`, `OperationId` | web `operationasync` — the HTTP projection |
| — | web `operationasync/OperationResourceFactory`, which is the projection itself |
| `OperationResource`, `OperationStatus`, `OperationProgress`, `OperationId` | removed 2026-09-25 — the web `operationasync` projection and `/api/v1/operations` controller had no production wiring and published failures only as `WebProblem` |
The split is not only a registry workaround; it puts each half where its invariants belong. A
problem document is an HTTP concept and has no business being persisted, so the stored failure is a
code plus a safe message and the factory turns it into a `WebProblem` through the same catalog and
the same sanitiser as every synchronous error. An async failure therefore cannot publish something
a synchronous one would have redacted, and a worker cannot extend the published code vocabulary by
writing a row — an unrecognised code becomes `INTERNAL_ERROR`.
code plus a safe message. An HTTP surface for operations, if one is added again, maps it onto the
`Envelope` error contract.
The state machine is enforced three times on purpose: in `DurableOperation`'s constructor, in the
`CHECK` constraints of `V11__durable_operation.sql`, and in the `WHERE` clause of every statement
@@ -147,6 +144,12 @@ no row and it learns that from the affected count.
## 8. Budget enforcement: what the edge stops and what the application stops
> **Removed 2026-09-25.** The servlet budget filter (`WebMvcBudgetFilter`) and its problem mapping
> were deleted with the second-generation platform. The shipped application no longer enforces the
> application column below; the `budget` catalog (`WebRequestBudget`, `WebBudgetCatalog`) remains as
> library code in `adapter:inbound:web-advanced`, and its unused meter (`WebBudgetMeter` and its
> outcome/violation types) was removed. The edge column still applies.
The design (Task 49) requires that the difference between an edge proxy's limits and the
application's own be written down rather than discovered during an incident. Two limits on the same
dimension always exist, they are never equal, and which one fires decides what the caller sees.
@@ -163,8 +166,9 @@ dimension always exist, they are never equal, and which one fires decides what t
Two consequences worth stating, because both are counterintuitive:
**An edge limit below the application's means clients never see a problem document.** nginx answers
its own HTML error page, so a client that branches on `ProblemCode` gets a body it cannot parse.
**An edge limit below the application's means clients never see the application's error body.**
nginx answers its own HTML error page, so a client that branches on `error.code` gets a body it
cannot parse.
Where a dimension matters to clients, the edge limit must be set *above* the application's so the
application is the one that refuses.
@@ -172,61 +176,19 @@ application is the one that refuses.
the process and a body large enough to matter before the application's own meter has counted it.
Both belong; only their ordering is a decision.
The enforcement itself never materializes a body to measure it. `WebBudgetMeter` counts bytes as
they move — through a wrapped `ServletInputStream` on the servlet side and a `doOnNext` on the
buffer flux on the reactive side — and throws at the byte that crosses. A check that read the body
in order to size it would be the heap exhaustion the check exists to prevent, so the contract asserts
directly that an oversized body never reaches the handler in full.
## 9. The Nginx lane (removed 2026-09-25)
On the way out the split is between committed and not:
The `webNginxProxyTest` lane ran the forwarded-header library (`proxy`, `http.External*`) behind a
Testcontainers `nginx:1.27-alpine`. That library was a second way of doing what the shipped path
does with `server.forward-headers-strategy`, so the library and its lane were removed together
(`docs/capability-status.md`, "제거된 코드").
- **Not committed** — the response is reset, which discards the partial body *and* the meter's
count of it, and the overrun is answered as a problem document. Resetting only the buffer was the
first implementation and it failed: the meter still held the count of the discarded bytes, so the
small problem document was refused too and the client got the container's error page.
- **Committed** — there is no status left to send. The exception propagates, the connection ends
mid-document, and the client sees a truncated response. That is worse for the client than a clean
error and better than a short response it would accept as complete.
Statuses are never restated. `BudgetProblemMapper.statusFor` reads `ProblemCatalog` through the
violation's code; an earlier draft kept its own violation-to-status table and disagreed with the
catalog on two entries, which `requireStatusAgreement` turned into a 500. One table, no drift.
## 9. The Nginx lane: what a real proxy caught that no unit test could
Task 55 asks for the proxy contract to be verified against a real Nginx. It is implemented as a
separate `nginxProxyTest` source set with a Testcontainers-managed `nginx:1.27-alpine`, run by
`./gradlew :adapter:inbound:web:webNginxProxyTest`. Its own lane because it is the only one that
needs Docker; folded into `test`, every developer's `check` would depend on a container runtime,
and the usual end of that is an `@Disabled` nobody notices.
**TLS is terminated in configuration, not in the container.** The design describes an `ssl` listener.
What the application can observe about TLS is exactly one thing — that the edge set
`X-Forwarded-Proto: https` authoritatively — and a proxy that terminates TLS and one that declares
the scheme produce an identical request upstream. Generating a certificate per run would add a
second failure mode to a lane whose subject is header handling. The lane asserts the observable
property; it does not assert that Nginx can do TLS.
**The defect the lane found on its first run.** The first configuration set the forwarded headers
once at the `server` level and added only `X-Forwarded-Prefix` per `location`. Six of the ten cases
failed. Nginx's inheritance rule for array directives is *replacement*: a single `proxy_set_header`
inside a `location` discards every `proxy_set_header` inherited from `server`. So none of the
security headers were sent, the application fell back to the upstream's own `Host`, and a client's
`X-Forwarded-Host` would have been trusted.
That configuration reads as correct, is a shape found throughout the wild, and no test of the
application could detect it — the application's forwarded-header handling is thoroughly unit-tested
and every one of those tests still passed. The bug lived entirely in the seam. The headers now live
in `proxy_headers.conf` and are `include`d by each location.
| Bound | Where it fires | What the client sees |
| --- | --- | --- |
| `client_max_body_size 2m` | Nginx, before the application | Nginx's HTML 413, no problem document |
| application `maxBodyBytes` | the application | RFC 9457 problem, `REQUEST_TOO_LARGE` |
| unknown prefix | Nginx | 404; only `/api/` and `/dev-api/` are routed at all |
The first row is the §8 table's consequence made concrete: an edge limit below the application's
means clients never see a problem document for that dimension.
One finding from that lane still applies to any Nginx in front of this service. Nginx's
inheritance rule for array directives is *replacement*: a single `proxy_set_header` inside a
`location` discards every `proxy_set_header` inherited from `server`. Setting the forwarded headers
once at `server` level and adding only `X-Forwarded-Prefix` per `location` therefore sends none of
the others, and the application falls back to the upstream's own `Host`. Keep the forwarded headers
in one included file and `include` it in every `location`.
## Advanced capabilities
@@ -240,23 +202,15 @@ What the design wanted from the separation is enforced instead by two machine ch
- **`WEB-ARCH-ADV`** in `WebArchitectureRules.stableDoesNotDependOnAdvanced()` fails the build when a
Stable class names an Advanced type. A feature flag decides whether a bean is created; it does
nothing about a compile-time edge, and one such edge makes Stable unbuildable without Advanced.
- **`WebStableModule`** declares eleven Advanced module identities with their own purity and edge
sets, checked by `WebModuleBoundaryTest`. Nine of the eleven are `CORE` — pure policy with no
framework import — which is stricter than the design's Gradle layout would have been.
Two modules are `FRAMEWORK_BOUND` and had to be: `advanced-patch` and `advanced-codec`. Jackson's
tree model is the reason for the first — a merge patch's null-means-delete has no representation in
a Java object, so the applier works on nodes — and `XMLInputFactory` is the reason for the second.
A third, `advanced-stream-encoding`, is separated from the pure `advanced-stream` for the same
reason: framing serializes, and serializing binds to Jackson.
`advanced.patch` and `advanced.codec` bind to a framework and had to: Jackson's tree model is the
reason for the first — a merge patch's null-means-delete has no representation in a Java object, so
the applier works on nodes — and `XMLInputFactory` is the reason for the second.
`advanced.stream.encoding` is separated from `advanced.stream` for the same reason: framing
serializes, and serializing binds to Jackson.
### What was adapted rather than copied
**`WebStreamEnvelope.Error` is named `Failure`.** A nested type called `Error` shadows
`java.lang.Error` inside its own file, so an unrelated `catch (Error e)` there would catch the wrong
thing. Error Prone's `JavaLangClash` refuses it outright, and the rename is the only difference from
the design's sealed hierarchy.
**`WebStreamErrorPolicy`'s factory methods are `startOver` / `resumeFromPosition` / `nothingToDo`.**
The design's names collided with the record's own accessors, which Java rejects.
@@ -288,13 +242,11 @@ coordinate. `RepresentationBackendScopeTest` reads `build.gradle` and fails if e
returns to `implementation`, because nothing else catches it — the codec's own tests pass either
way, and the failure only appears in whatever composes this leaf.
**The framing and the writers are separate, and both exist.** `NdjsonFraming` and
`JsonSequenceFraming` hold the contract; `MvcStreamWriter`, `WebFluxStreamWriter` and
`WebFluxSseAdapter` are what actually put it on a response. There is no MVC SSE writer: this
repository's `NO_SSE_EMITTER` ArchUnit rule forbids `SseEmitter` outright, so the servlet stack
streams NDJSON and JSON-seq and SSE is reactive-only. An earlier pass
stopped after the framing, which left the platform advertising SSE while nothing could serve it —
the same "control reached by nothing" shape this leaf has caught five other times.
**The framing and the writer are separate.** `NdjsonFraming` and `JsonSequenceFraming` hold the
contract; `MvcStreamWriter` is what puts it on a response. There is no MVC SSE writer: this
repository's `NO_SSE_EMITTER` ArchUnit rule forbids `SseEmitter` outright, and the only SSE writer
was the WebFlux one removed on 2026-09-25. So the servlet stack streams NDJSON and JSON-seq, and SSE
is framing-only — nothing serves it until a servlet writer exists.
**`MessagingReplayBridge` is `WebStreamReplaySource`, an interface this module implements nowhere.**
The design's requirement is that the web module store no durable event history; an implementation
@@ -302,50 +254,18 @@ here would be the thing it forbids.
### What the execution layer had to get right
Three of these were only found by building the adapter rather than the policy.
**A merged heartbeat means a finished source never completes.** `Flux.interval` is infinite, so
`source.mergeWith(heartbeat)` holds the connection for the full `maxStreamAge` after the last item —
thirty minutes of keepalives on a stream that ended. `WebFluxSseAdapter` therefore ends at the
terminal envelope (`takeUntil`), and supplies one for a source that finished without emitting its
own.
**`onBackpressureBuffer(n)` does not close anything.** It propagates demand, so a subscriber that
stops requesting simply stops the source and the bound never fires. That is correct for a
well-behaved source and useless as a slow-consumer policy, because the sources this carries push
whether or not anybody asked. The working composition is `onBackpressureBuffer(n)` followed by
`onBackpressureError()`, verified by mutation: removing the second half makes both slow-consumer
tests fail. The merge prefetch is set to the same `n`, because its default of 256 would otherwise
be a larger backlog sitting behind the configured one.
**The blocking bridge's permit cannot be released in `doFinally`.** That fires on the subscriber's
cancel signal, which arrives while the callable is still blocked on a thread — releasing there hands
the permit to another caller while the first still holds the database connection it was accounting
for. Acquire and release are in the same `try`/`finally` inside the callable, and the consequence,
stated rather than hidden, is that cancellation does not interrupt a blocking call.
On the servlet side the equivalent is that there is no disconnect event at all: the first sign a
client is gone is a write that throws, which is why the heartbeat is the probe rather than a
On the servlet stack there is no disconnect event at all: the first sign a client is gone is a write that throws, which is why the heartbeat is the probe rather than a
courtesy and why a failed beat is recorded as disconnect evidence.
### One pre-existing flake was fixed
`HttpThrottleFixture.awaitSlotTaken` polled for a 503 while each probe spent quota, and refilled the
quota only after the loop. On a machine loaded enough that the holding request took a while to
occupy the slot, the quota ran out first and every remaining probe answered 429 — so the loop never
saw its 503 and failed on the deadline, which reads as a capacity bug and is a fixture bug. It now
refills before every probe and fails loudly if a probe is refused for quota immediately after a
refill. Found because the new virtual-thread and blocking-bridge tests load the machine enough to
trigger it.
### Verification
```bash
cd src
./gradlew :adapter:inbound:web:test # 861 tests, Advanced included
./gradlew :adapter:inbound:web:webAdvancedTest # 147, the Advanced lane on its own
./gradlew :adapter:inbound:web:webCrossStackParityTest
./gradlew :adapter:inbound:web:webNginxProxyTest # Docker
./gradlew :adapter:inbound:web:test # the shipped web leaf
./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
./gradlew :adapter:inbound:web:webJettyCompatTest # Jetty, real socket
./gradlew :adapter:inbound:web-advanced:test # the opt-in Advanced leaf
./gradlew :adapter:inbound:web-advanced:webAdvancedTest # the tagged Advanced lane
```
See `docs/web/advanced-capabilities.md`, `docs/web/streaming-contract.md`,
+34 -54
View File
@@ -3,68 +3,48 @@
What an operator needs when the HTTP boundary misbehaves. Organised by what you observe, because
that is what you have at 3am — not by which module owns it.
## Reading the two "too much traffic" answers
## Reading a `429`
The platform never answers these two interchangeably, and the difference tells you where to look.
`RateLimitInterceptor` answers `429 RATE_LIMIT_EXCEEDED` with `Retry-After` when the edge rate
limit refuses a caller. `RATE_LIMIT_UNAVAILABLE` means the rate-limit store could not be reached,
not that the caller exceeded anything — look at the store, not the caller.
| You see | It means | Where to look |
| --- | --- | --- |
| `429 RATE_LIMITED` climbing for one caller | that caller exceeded its quota | the caller. Nothing is wrong with the service. |
| `429` climbing across **all** callers | quota is being charged for requests the service then shed | look at 503 first; see below |
| `503 ADMISSION_REJECTED` | the service has no capacity | saturation: check the admission profile's concurrency and what is holding slots |
## Errors that are not the `Envelope`
The second row is a real consequence of the design and worth knowing before it confuses you. Quota
is charged *before* capacity is requested, deliberately — the reverse order lets a caller who is
about to be rate-limited occupy a slot on the way to being told so. Under sustained overload every
caller's quota therefore drains on requests that never ran. **Rising 429 during an incident is a
symptom of shedding, not of callers misbehaving.** Read the 503 rate first.
Every HTTP error the application writes is the `Envelope` from `GlobalExceptionHandler`
(`spring.mvc.problemdetails.enabled=false`), with an `error.code` a client branches on.
## A control that appears configured and does nothing
This has happened here, and the failure is silent by construction. A configured-but-unwired control
behaves exactly like a working one until it is needed.
- **Check first:** the platform snapshot's `uninstalledControls()`. `WebPlatformStartupValidator`
fails startup on a missing required control, so a running instance with one missing means it was
not in the required list.
- **The instance found the hard way:** the problem catalog was complete, fully unit-tested, and
reached by nothing on the framework's error path. Spring answered failures with its own
`ProblemDetail` — RFC 9457-shaped, so it looked correct — carrying no `code` field. It was found
by a cross-stack parity recording, not by any test of the catalog.
- **How to confirm quickly:** send a request that must fail validation and check the body has a
`code`. No `code` means the platform's handler is not installed.
- **How to confirm quickly:** send a request that must fail validation and check the body has
`error.code`. A body without it (Spring's `ProblemDetail`, or the container's error page) means
the handler is not installed or the response came from the edge.
## A response is truncated or the connection dies mid-document
Two different causes, distinguished by the status the client did receive.
- **Client got a status, then nothing** — the response budget was crossed after commit. The
platform cannot retract a status, so it ends the connection: a truncated response the client
rejects is better than a short one it accepts as complete. Raise `maxResponseBytes` for that
operation's profile, or make the endpoint paginate.
- **Client got nothing at all** — either the request budget was crossed before headers, in which
case there is a problem document, or the proxy refused it. `client_max_body_size` in nginx is
below the application's body budget by default, and nginx answers with its own HTML rather than a
problem document. See `repository-adaptation.md` §8 for which bound fires where.
- **Client got a status, then nothing** — the response failed after commit. The status cannot be
retracted, so the connection ends mid-document.
- **Client got nothing from the application** — the proxy refused it. `client_max_body_size` in
nginx answers with its own HTML rather than the `Envelope`. See `repository-adaptation.md` §8.
## A retried write happened twice
The idempotency key is the control, and there are exactly three ways it fails to apply.
1. **The client did not send one.** The operation profile says `OPTIONAL`, so it ran unguarded.
Change the profile to `REQUIRED` if a duplicate is unacceptable.
2. **The client sent a different body.** Answered `422 IDEMPOTENCY_KEY_REUSED`, never a replay —
replaying would hand back a receipt for a request the caller never made.
1. **The client did not send one.** The endpoint does not require the key, so it ran unguarded.
Require it if a duplicate is unacceptable.
2. **The client sent a different body.** Answered `422 IDEMPOTENT_REQUEST_MISMATCH`, never a
replay — replaying would hand back a receipt for a request the caller never made.
3. **The record expired.** TTL is per-operation with a 72h cap. A retry after expiry is a new
request by definition.
A `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` is not a failure: an earlier attempt is still running and
A `409 IDEMPOTENT_IN_FLIGHT` is not a failure: an earlier attempt is still running and
the caller should retry after `Retry-After`.
## Rolling deploy stalls with instances half-drained
`shutDownGracefully` waits for in-flight work, and on Reactor Netty an open-but-idle keep-alive
connection counts as in-flight. Calling `stop()` while that wait is in progress hangs.
`shutDownGracefully` waits for in-flight work, and an open-but-idle keep-alive connection can count
as in-flight. Calling `stop()` while that wait is in progress hangs.
- **Symptom:** an instance neither serving nor exiting, no error in its log.
- **Cause:** an unbounded graceful wait. `GracefulShutdownProbe` bounds it at a stated grace period
@@ -74,9 +54,8 @@ connection counts as in-flight. Calling `stop()` while that wait is in progress
## Metrics stopped arriving, or the bill jumped
Almost always a high-cardinality tag. `WebMetricCardinalityPolicy` refuses anything off an
eight-name allowlist at the point of recording, so a new tag cannot appear by accident — but a
`routeTemplate` carrying a *resolved* path can, and that is one series per resource.
Almost always a high-cardinality tag — typically a `routeTemplate` carrying a *resolved* path, which
is one series per resource.
- **Check:** the tag values in the metrics backend for `routeTemplate`. Braces mean templates;
identifiers mean the resolved path leaked through.
@@ -85,14 +64,17 @@ eight-name allowlist at the point of recording, so a new tag cannot appear by ac
## Cross-origin requests fail only in the browser
The API answers correctly and the browser refuses the response. Everything below is refused at
startup by `WebCorsPolicyValidator`, so a running instance with one of these means the profile was
built somewhere that does not validate.
The API answers correctly and the browser refuses the response. CORS is `CorsSettings`
(`ca-skeleton.cors.*`) applied by `SecurityConfig`. Startup refuses two settings:
- `*` with credentials — no browser honours it.
- An origin with a path, a trailing slash, or uppercase — never matches what the browser sends.
- `https://*.example.com` — matches nothing; CORS compares origins exactly.
- Wildcard `allowedHeaders` on a credentialed profile — not honoured with credentials.
- `APP_SECURITY_CORS_ENABLED=true` with no origin.
- `*` in `APP_SECURITY_CORS_ORIGINS` with `APP_SECURITY_CORS_ALLOW_CREDENTIALS=true` — no browser
honours it.
Two more start fine and still fail in the browser:
- `https://*.example.com` in the origin list — it is compared as a literal and matches nothing.
- An origin with a path (`https://app.example.com/ui`) — an origin is scheme, host and port only.
A preflight answered `401` means CORS ran after authentication. Preflights carry no credentials by
design; the order is asserted by `WebPipelineOrderContract`.
@@ -109,8 +91,6 @@ both times, and every latency percentile computed from that data is wrong while
```bash
cd src
./gradlew :adapter:inbound:web:test # unit, boundary, architecture
./gradlew :adapter:inbound:web:webCrossStackParityTest # Tomcat vs Jetty vs Reactor Netty
./gradlew :adapter:inbound:web:webNginxProxyTest # real proxy; needs Docker, fails without it
./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
./gradlew :adapter:inbound:web:webJettyCompatTest # second servlet container
./gradlew :adapter:inbound:web:webFluxContractTest # reactive stack
```
+9 -3
View File
@@ -1,6 +1,12 @@
# Web streaming: the client contract
What a client must implement to consume SSE, NDJSON or `application/json-seq` from this platform.
What a client must implement to consume NDJSON or `application/json-seq` from this platform. SSE
framing exists, but since the WebFlux twin was removed (2026-09-25) nothing on the servlet stack
writes it.
The writers ship in `adapter:inbound:web-advanced` (opt-in, switched by
`backend.web.advanced.ndjson.enabled` / `backend.web.advanced.json-sequence.enabled`); no default
composition carries them.
## Three outcomes, not two
@@ -8,8 +14,8 @@ After the first byte the HTTP status is 200 and cannot change. So the status tel
whether the stream succeeded, and a closed connection is ambiguous. There are three endings:
1. **A `Complete` envelope.** The stream finished. `lastSequence` is the final position.
2. **A `Failure` envelope.** Something failed after commit. Carries a `ProblemCode` and a
client-safe message. The status is still 200.
2. **A `Failure` record.** Something failed after commit. Carries an error code and a client-safe
message. The status is still 200.
3. **Neither.** The connection closed mid-stream. The server records this as `ABRUPT_CLOSE`; from
the client's side it is indistinguishable from a completed stream *unless the client is looking
for the terminal envelope*.

Some files were not shown because too many files have changed in this diff Show More