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 runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - 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 - uses: ./.github/actions/setup-gradle-java
- name: Export the live Gradle verification task map - name: Export the live Gradle verification task map
working-directory: src working-directory: src
@@ -54,47 +42,15 @@ jobs:
if-no-files-found: error if-no-files-found: error
# `ci`, not `check`. A leaf's `check` is that leaf's — compile, its tests, Spotless, Checkstyle # `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: # and Error Prone — and the repository-wide gates are named tasks of their own:
# ci = every leaf check + architectureCheck + qualityCheck + configContractCheck + qualificationCheck # ci = every leaf check + architectureCheck + qualityCheck
# so CI runs strictly more than it used to while `./gradlew :domain-core:check` runs strictly # The main-branch stage (`mainCheck`: environment contract, full-boot qualification, public-path
# less. # baseline, API surfaces, transport and messaging lanes) runs in integration-main.yml.
- name: Run the pull-request gate - name: Run the pull-request gate
working-directory: src working-directory: src
run: ./gradlew :ci :verifyPublicPathSnapshot :verifyDependencyLocks --warning-mode=fail --stacktrace run: ./gradlew :ci :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
- name: Verify Compose profile contracts render exactly as declared - name: Verify Compose profile contracts render exactly as declared
run: bash scripts/verify-compose-profile-contracts.sh 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: sample-portfolio:
# The sample is excluded from production architecture/runtime membership policy, but it is still # 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. # the reference implementation adopters copy. Compile/test/OpenAPI drift must therefore block PRs.
@@ -106,19 +62,6 @@ jobs:
working-directory: src working-directory: src
run: ./gradlew :sample-portfolio:check --stacktrace 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: optional-platforms:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
@@ -128,104 +71,11 @@ jobs:
working-directory: src working-directory: src
run: ./gradlew -p optional-platforms ci --stacktrace 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: release-gate:
needs: needs:
- quality-gates - quality-gates
- build-logic
- build-tools
- sample-portfolio - sample-portfolio
- redis-sdk
- jpa-candidate-evidence
- optional-platforms - optional-platforms
- configuration-cache
if: always() if: always()
runs-on: ubuntu-latest runs-on: ubuntu-latest
permissions: permissions:
@@ -234,24 +84,14 @@ jobs:
- name: Require every current blocking job to succeed - name: Require every current blocking job to succeed
env: env:
QUALITY_RESULT: ${{ needs.quality-gates.result }} 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 }} 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 }} OPTIONAL_PLATFORMS_RESULT: ${{ needs.optional-platforms.result }}
CONFIGURATION_CACHE_RESULT: ${{ needs.configuration-cache.result }}
run: | run: |
set -euo pipefail set -euo pipefail
for result in \ for result in \
"${QUALITY_RESULT}" \ "${QUALITY_RESULT}" \
"${BUILD_LOGIC_RESULT}" \
"${BUILD_TOOLS_RESULT}" \
"${SAMPLE_RESULT}" \ "${SAMPLE_RESULT}" \
"${REDIS_RESULT}" \ "${OPTIONAL_PLATFORMS_RESULT}"; do
"${JPA_CANDIDATE_RESULT}" \
"${OPTIONAL_PLATFORMS_RESULT}" \
"${CONFIGURATION_CACHE_RESULT}"; do
if [[ "${result}" != "success" ]]; then if [[ "${result}" != "success" ]]; then
echo "::error::release-gate: required job result was ${result}" echo "::error::release-gate: required job result was ${result}"
exit 1 exit 1
@@ -43,13 +43,6 @@ jobs:
steps: steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java - 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 - name: Run the complete fileserver suite across every leaf
working-directory: src working-directory: src
run: >- run: >-
-1
View File
@@ -108,6 +108,5 @@ jobs:
run: >- run: >-
./gradlew ./gradlew
:adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest' :adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest'
:adapter:inbound:web:test --tests '*DataBufferReleaseTest'
--stacktrace --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 # shared. They now run on every push to main as well as nightly, which is strictly more often
# than before. # than before.
# #
# 2. Lanes that were registered in Gradle and invoked by nothing. Ten Gradle tasks — six MongoDB # 2. Lanes that were registered in Gradle and invoked by nothing — the MongoDB container lanes and
# container lanes, app-bootstrap's Testcontainers `integrationTest`, and the three messaging # app-bootstrap's Testcontainers `integrationTest` — existed, failed closed, and executed in no
# evidence tasks that `verifyMessagingContracts` reaches — existed, failed closed, and executed # workflow. A lane nobody runs is not coverage; it is a file that looks like coverage. They
# 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 # 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. # 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 # What is deliberately NOT here: the web "Advanced capability" nightly lane that used to exist as
# to exist as web-advanced-nightly.yml and websocket-advanced-nightly.yml. Both leaves' build files # web-advanced-nightly.yml (websocket-advanced-nightly.yml went with the websocket Advanced code,
# say it outright — "They also run inside `test`, deliberately ... excluding them from the PR gate to # deleted 2026-09-25). The web leaf's build file says it outright — "They also run inside `test`,
# make this lane look meaningful would mean the PR gate stopped covering a fifth of the leaf" — so # deliberately ... excluding them from the PR gate to make this lane look meaningful would mean the
# `webAdvancedTest` and `websocketAdvancedTest` select tagged tests that `:<leaf>:test` already runs, # PR gate stopped covering a fifth of the leaf" — so `webAdvancedTest` selects tagged tests that
# and `:<leaf>:test` runs inside the root `check` on every pull request and every push to main. The # `:<leaf>:test` already runs, and `:<leaf>:test` runs inside the root `check` on every pull request
# strict lanes themselves survive in release.yml, where their fail-on-nothing-discovered guard is # and every push to main. The strict lane itself survives in release.yml, where its
# worth a job. # fail-on-nothing-discovered guard is worth a job.
on: on:
push: push:
@@ -58,6 +57,93 @@ concurrency:
# answer: does this link resolve. # answer: does this link resolve.
jobs: 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 # 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. # outright — which is exactly the kind of regression a per-PR gate never catches.
web-load-abuse-and-shutdown: web-load-abuse-and-shutdown:
@@ -72,7 +158,6 @@ jobs:
./gradlew ./gradlew
:adapter:inbound:web:test :adapter:inbound:web:test
:adapter:inbound:web:webJettyCompatTest :adapter:inbound:web:webJettyCompatTest
:adapter:inbound:web:webFluxContractTest
--stacktrace --stacktrace
- name: Publish the test reports - name: Publish the test reports
@@ -181,40 +266,6 @@ jobs:
path: src/adapter/outbound/persistence-mongo/build/reports/tests/ path: src/adapter/outbound/persistence-mongo/build/reports/tests/
if-no-files-found: warn 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 # 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 # `./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 # closed is that a source set outside `test` is also outside `check`, so the real-PostgreSQL
@@ -241,9 +292,6 @@ jobs:
steps: steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java - uses: ./.github/actions/setup-gradle-java
- name: RabbitMQ transport contract
working-directory: src
run: ./gradlew :messaging:messaging-rabbit:integrationTest --stacktrace
- name: Inbox PostgreSQL contract - name: Inbox PostgreSQL contract
working-directory: src working-directory: src
run: ./gradlew :messaging:messaging-inbox-jdbc-postgresql:integrationTest --stacktrace run: ./gradlew :messaging:messaging-inbox-jdbc-postgresql:integrationTest --stacktrace
@@ -274,9 +322,6 @@ jobs:
- name: Distributed lock contract - name: Distributed lock contract
working-directory: src working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest --stacktrace 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 - name: Integer lock migration compatibility
working-directory: src working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlIntLockMigrationCompatibilityIntegrationTest --stacktrace 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 # 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 # 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. # 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: compose-runtime-smoke:
runs-on: ubuntu-latest runs-on: ubuntu-latest
timeout-minutes: 180 timeout-minutes: 180
+4 -4
View File
@@ -21,17 +21,17 @@ jobs:
- id: jakarta-persistence-4 - id: jakarta-persistence-4
target: Jakarta Persistence 4 target: Jakarta Persistence 4
coordinate: jakarta.persistence:jakarta.persistence-api:4.x 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 reason: the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it
- id: hibernate-8 - id: hibernate-8
target: Hibernate 8 target: Hibernate 8
coordinate: org.hibernate.orm:hibernate-core:8.x 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 reason: Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it
- id: postgresql-19 - id: postgresql-19
target: PostgreSQL 19 target: PostgreSQL 19
coordinate: postgres:19-alpine 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 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 runs-on: ubuntu-latest
timeout-minutes: 60 timeout-minutes: 60
@@ -61,7 +61,7 @@ jobs:
echo "status=NOT_EXECUTABLE" echo "status=NOT_EXECUTABLE"
echo "probe-result=${PROBE_OUTCOME}" echo "probe-result=${PROBE_OUTCOME}"
echo "reason=${REASON}" 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 }}" echo "sha=${{ github.sha }}"
} > compatibility-evidence/status.properties } > compatibility-evidence/status.properties
echo "::notice::${TARGET} compatibility is NOT_EXECUTABLE: ${REASON}" echo "::notice::${TARGET} compatibility is NOT_EXECUTABLE: ${REASON}"
+1 -4
View File
@@ -114,15 +114,12 @@ jobs:
steps: steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java - 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 working-directory: src
run: >- run: >-
./gradlew ./gradlew
:verifyJpaReleaseGateTasks :verifyJpaReleaseGateTasks
:verifyJpaReadinessRegistry :verifyJpaReadinessRegistry
:verifyCleanArchitectureDependencies
checkstyleMain
:app-bootstrap:architectureTest
:adapter:outbound:persistence-jpa:test --tests '*JpaReleaseManifestTest' :adapter:outbound:persistence-jpa:test --tests '*JpaReleaseManifestTest'
--stacktrace --stacktrace
+12 -21
View File
@@ -22,8 +22,8 @@ on:
- 'src/adapter/outbound/notification/**' - 'src/adapter/outbound/notification/**'
- 'src/adapter/outbound/persistence-jpa/src/**/notification/**' - 'src/adapter/outbound/persistence-jpa/src/**/notification/**'
- 'src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/notification-platform/**' - 'src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/notification-platform/**'
- 'src/adapter/inbound/web/src/**/notification/**' - 'src/adapter/inbound/web-notification/**'
- 'src/app-bootstrap/src/**/notification/**' - 'src/composition/notification-platform/**'
- 'src/app-bootstrap/src/main/resources/application*.yml' - 'src/app-bootstrap/src/main/resources/application*.yml'
- 'src/gradle/notification-*.gradle' - 'src/gradle/notification-*.gradle'
- 'src/config/architecture/modules.json' - 'src/config/architecture/modules.json'
@@ -67,7 +67,7 @@ jobs:
run: ./gradlew :adapter:outbound:notification:test --console=plain run: ./gradlew :adapter:outbound:notification:test --console=plain
- name: Persistence and web - name: Persistence and web
working-directory: src 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 # 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 # 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 # 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) - name: Notification migration upgrade (real PostgreSQL)
working-directory: src working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest --console=plain 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 working-directory: src
run: | run: ./gradlew :adapter:outbound:notification:verifyNotificationApiSurface --console=plain
./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
- name: Static analysis - name: Static analysis
working-directory: src working-directory: src
run: ./gradlew :adapter:outbound:notification:check -x test --console=plain run: ./gradlew :adapter:outbound:notification:check -x test --console=plain
@@ -125,7 +115,8 @@ jobs:
:application-core:test :application-core:test
:adapter:outbound:notification:test :adapter:outbound:notification:test
:adapter:outbound:persistence-jpa:test :adapter:outbound:persistence-jpa:test
:adapter:inbound:web:test :adapter:inbound:web-notification:test
:composition:notification-platform:test
--console=plain --console=plain
# A filter that matches nothing passes. Each --tests filter above names a class that exists # 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. # 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: # 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 # ProviderSandboxSmokeTest itself, and the unsatisfied provider-wire-qualified claim in
# docs/notification/evidence-manifest.json, which verifyNotificationEvidence enforces inside # docs/notification/evidence-manifest.json, which NotificationEvidenceVerifierTest enforces in
# check. When a real sandbox call is implemented, the job comes back with it. # 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. # here is only what `check` does not run.
# #
# What `check` does not run, and therefore what this file is for: # 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 with their own source set — the servlet system contract, a second servlet container,
# * lanes selected by a tag that `test` excludes — the cross-stack parity recording comparison; # a real Nginx;
# * lanes parameterised per run — one PostgreSQL major per job, one HTTP transport per job. # * 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 # Each of those genuinely cannot run inside `check`, which is the test for whether a job belongs
# here at all. # here at all.
@@ -126,10 +126,9 @@ jobs:
'^infra/jpa/' \ '^infra/jpa/' \
"${common}" "${common}"
# The parity gate depends on all three recording lanes and fails when one is missing, so it runs # The servlet system contract on both containers the template supports (Tomcat, Jetty). Real
# them itself rather than trusting a previous job to have left the recordings behind. Its tag is # sockets, so neither lane is part of `check`.
# excluded from `test`, which is why `check` cannot cover it. web-servlet-containers:
web-cross-stack-parity:
needs: changes needs: changes
if: needs.changes.outputs.web == 'true' if: needs.changes.outputs.web == 'true'
runs-on: ubuntu-latest runs-on: ubuntu-latest
@@ -137,39 +136,21 @@ jobs:
steps: steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java - 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 working-directory: src
run: >- run: >-
./gradlew ./gradlew
:adapter:inbound:web:webCrossStackParityTest :adapter:inbound:web:systemTest
:adapter:inbound:web:webJettyCompatTest
--stacktrace --stacktrace
- name: Publish the parity recordings - name: Publish the test reports
if: always() if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with: with:
name: web-contract-parity name: web-servlet-containers-reports
path: src/adapter/inbound/web/build/web-contract-parity/ path: src/adapter/inbound/web/build/reports/tests/
if-no-files-found: error if-no-files-found: warn
# 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
websocket-container-matrix: websocket-container-matrix:
needs: changes needs: changes
+16 -7
View File
@@ -31,6 +31,8 @@ name: redis-sdk-topology
on: on:
pull_request: pull_request:
paths: paths:
- "src/adapter/outbound/redis-runtime/**"
- "src/adapter/outbound/redis-sdk/**"
- "src/adapter/outbound/cache-redis/**" - "src/adapter/outbound/cache-redis/**"
- "infra/redis-sdk/**" - "infra/redis-sdk/**"
- ".github/workflows/redis-sdk-topology.yml" - ".github/workflows/redis-sdk-topology.yml"
@@ -145,10 +147,15 @@ jobs:
working-directory: src working-directory: src
run: | run: |
set -euo pipefail 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 case '${{ matrix.topology }}' in
standalone) port=6379; extra='' ;; standalone) port=6379; extra=''; tasks="$runtime $sdk $semantic" ;;
sentinel) port=27010; extra='-Predis.topology.master=skeleton' ;; sentinel) port=27010; extra='-Predis.topology.master=skeleton'; tasks="$runtime $sdk" ;;
cluster) port=7100; extra='' ;; 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 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 # the lane rather than checked in. A checked-in key is a secret in the repository
# however loudly the file is named "test". # however loudly the file is named "test".
@@ -156,10 +163,11 @@ jobs:
port=6390 port=6390
docker compose -f ../infra/redis-sdk/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem" 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" extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem"
tasks="$runtime"
;; ;;
*) echo "unknown topology"; exit 1 ;; *) echo "unknown topology"; exit 1 ;;
esac esac
./gradlew :adapter:outbound:cache-redis:redisTopologyTest --console=plain \ ./gradlew $tasks --continue --console=plain \
-Predis.topology.host=localhost \ -Predis.topology.host=localhost \
-Predis.topology.port="$port" \ -Predis.topology.port="$port" \
-Predis.topology.mode='${{ matrix.topology }}' \ -Predis.topology.mode='${{ matrix.topology }}' \
@@ -168,7 +176,7 @@ jobs:
if: always() if: always()
run: | run: |
set -euo pipefail set -euo pipefail
out=src/adapter/outbound/cache-redis/build/test-results/redisTopologyTest out=src/build/redis-topology-evidence
mkdir -p "$out" mkdir -p "$out"
cat > "$out/evidence-manifest.txt" <<MANIFEST cat > "$out/evidence-manifest.txt" <<MANIFEST
commit=${{ github.sha }} commit=${{ github.sha }}
@@ -184,8 +192,9 @@ jobs:
with: with:
name: redis-topology-${{ matrix.topology }}-${{ matrix.redis_version }} name: redis-topology-${{ matrix.topology }}-${{ matrix.redis_version }}
path: | path: |
src/adapter/outbound/cache-redis/build/test-results/redisTopologyTest/** src/build/redis-topology-evidence/**
src/adapter/outbound/cache-redis/build/reports/tests/redisTopologyTest/** src/adapter/outbound/*/build/test-results/redisTopologyTest/**
src/adapter/outbound/*/build/reports/tests/redisTopologyTest/**
if-no-files-found: error if-no-files-found: error
retention-days: 90 retention-days: 90
- name: Stop the topology - name: Stop the topology
+10 -11
View File
@@ -59,12 +59,11 @@ jobs:
working-directory: src working-directory: src
run: ./gradlew :releaseCheck --stacktrace run: ./gradlew :releaseCheck --stacktrace
# Every web lane that `check` cannot reach. webCrossStackParityTest depends on `test`, # Every web lane that `check` cannot reach: the servlet system contract on Tomcat (systemTest)
# webJettyCompatTest and webFluxContractTest, so naming it runs all four — which is what # and Jetty (webJettyCompatTest), and the Advanced lane.
# web-advanced-release.yml spent a separate 90-minute job doing by naming the three by hand.
# #
# webAdvancedTest is here rather than in a nightly of its own. Its tests run inside # 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 # 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. # workflow file and a runner every night.
web-stable-release-gate: web-stable-release-gate:
@@ -77,9 +76,9 @@ jobs:
working-directory: src working-directory: src
run: >- run: >-
./gradlew ./gradlew
:adapter:inbound:web:webCrossStackParityTest :adapter:inbound:web:systemTest
:adapter:inbound:web:webNginxProxyTest :adapter:inbound:web:webJettyCompatTest
:adapter:inbound:web:webAdvancedTest :adapter:inbound:web-advanced:webAdvancedTest
--stacktrace --stacktrace
- name: Publish the release evidence - name: Publish the release evidence
@@ -88,8 +87,8 @@ jobs:
with: with:
name: web-release-evidence name: web-release-evidence
path: | path: |
src/adapter/inbound/web/build/web-contract-parity/
src/adapter/inbound/web/build/reports/tests/ src/adapter/inbound/web/build/reports/tests/
src/adapter/inbound/web-advanced/build/reports/tests/
if-no-files-found: error if-no-files-found: error
websocket-stable-release-gate: websocket-stable-release-gate:
@@ -98,15 +97,15 @@ jobs:
steps: steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java - uses: ./.github/actions/setup-gradle-java
- name: Run every websocket lane, Stable and Advanced - name: Run every websocket lane
working-directory: src working-directory: src
run: >- run: >-
./gradlew ./gradlew
:adapter:inbound:websocket:test :adapter:inbound:websocket:test
:adapter:inbound:websocket:systemTest
:adapter:inbound:websocket:websocketJettyTest :adapter:inbound:websocket:websocketJettyTest
:adapter:inbound:websocket:websocketNginxTest :adapter:inbound:websocket:websocketNginxTest
:adapter:inbound:websocket:websocketTransportQualificationTest :adapter:inbound:websocket:websocketTransportQualificationTest
:adapter:inbound:websocket:websocketAdvancedTest
--stacktrace --stacktrace
- name: Publish the release evidence - name: Publish the release evidence
@@ -120,7 +119,7 @@ jobs:
# The three gRPC certification lanes. Their tests already run on every pull request — the # 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-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 # `: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 # 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, # `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. # transport and fault evidence grades claiming coverage that stopped existing.
+69 -9
View File
@@ -49,8 +49,8 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
## Gradle 정책 권위 ## Gradle 정책 권위
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, - `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로,
Gradle path, 허용 production project dependency edge. runtime membership은 실제 resolved Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다: 조립 루트가
runtimeClasspath에서 검증하며 registry에 별도 membership 목록을 복제하지 않는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 — 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 —
산문에 적힌 숫자는 leaf가 추가되는 순간 drift하기 때문이다. 이제 이걸 강제하는 태스크는 없다: 산문에 적힌 숫자는 leaf가 추가되는 순간 drift하기 때문이다. 이제 이걸 강제하는 태스크는 없다:
`verifyDocumentedLeafCount`는 삭제됐다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 `verifyDocumentedLeafCount`는 삭제됐다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬
사유는 아니고, 그 태스크는 모든 `CLAUDE.md`와 `build.gradle`을 정규식으로 훑는 파서였다. 사유는 아니고, 그 태스크는 모든 `CLAUDE.md`와 `build.gradle`을 정규식으로 훑는 파서였다.
@@ -59,10 +59,15 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은
`verifyCleanArchitectureDependencies`가 답한다 — settings에서 죽으면 실행할 수 있는 태스크가 `verifyCleanArchitectureDependencies`가 답한다 — settings에서 죽으면 실행할 수 있는 태스크가
하나도 없다. 하나도 없다.
- `src/build-logic/`: convention plugin. leaf는 `ca.java-library` / `ca.spring-library` / - `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나
`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 (`strictTestLanes`). leaf는 `ca.java-library` / `ca.spring-library` / `ca.platform-module` 중
기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 소유한다. 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `releaseCheck`, `qualityCheck`, `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`)과 버전/리비전 `configContractCheck`, `integrationCheck`)과 버전/리비전
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를 작업 파일의 소유 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`에서 `src/config/architecture/modules.json`이 SSOT다. focused test는 소유 leaf의 `gradle_path`에서
파생한다. 이 문서는 leaf 목록을 복제하지 않고 family 책임만 정의한다. 작업 파일에서는 가장 가까운 파생한다. 이 문서는 leaf 목록을 복제하지 않고 family 책임만 정의한다. 작업 파일에서는 가장 가까운
`src/**/CLAUDE.md`를 함께 읽는다. `src/**/CLAUDE.md`를 함께 읽는다.
@@ -145,6 +150,27 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
- 그 밖의 `adapter:outbound:*`: external capability adapter contract를 검증한다. - 그 밖의 `adapter:outbound:*`: external capability adapter contract를 검증한다.
- `app-bootstrap/settings`: configuration binding, validation, logging 설정을 검증한다. - `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`을 사용한다. - 완료를 주장하기 전에 `superpowers:verification-before-completion`을 사용한다.
@@ -157,9 +183,10 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
cd src cd src
./gradlew <owner-gradle-path>:check --console=plain # 그 leaf만: 컴파일·테스트·포맷·스타일·ErrorProne ./gradlew <owner-gradle-path>:check --console=plain # 그 leaf만: 컴파일·테스트·포맷·스타일·ErrorProne
./gradlew check # 모든 leaf의 check ./gradlew check # 모든 leaf의 check
./gradlew architectureCheck # 의존 방향·런타임 멤버십·application-core 순수성 ./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다) ./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 verifyPublicPathSnapshot
./gradlew :app-bootstrap:verifyEnvKeys ./gradlew :app-bootstrap:verifyEnvKeys
``` ```
@@ -169,6 +196,39 @@ leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름
소유 leaf의 정확한 Gradle path는 `src/config/architecture/modules.json`에서 읽고 focused test 소유 leaf의 정확한 Gradle path는 `src/config/architecture/modules.json`에서 읽고 focused test
명령을 파생한다. root 문서에 leaf별 명령 목록을 복제하지 않는다. 명령을 파생한다. 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 ## Gradle policy authorities
- `src/config/architecture/modules.json`: every registered leaf identity, repository-relative source - `src/config/architecture/modules.json`: every registered leaf identity, repository-relative source
paths, Gradle paths, allowed production project dependency edges, and the exact runtime paths, Gradle paths and allowed production project dependency edges. There is no runtime
memberships of both composition roots. The registry owns the leaf list and its size; no document membership list: what a composition root may take is its `allowed_dependencies`, and the direction
restates the count, because a number written in prose drifts the moment a leaf is added. 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/settings.gradle`: fail-closed registry validation, project inclusion, and directory mapping.
- `src/build.gradle`: `verifyCleanArchitectureDependencies` and the other architecture-wide - `src/build-logic/`: the architecture core (registry, direction and purity tasks), the conventions,
verification tasks. 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. 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. 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 Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity
membership, application-core purity, Git-carryable sources), `qualityCheck` (SpotBugs, FindSecBugs), of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck`
`configContractCheck` (the environment contract), `integrationCheck` (the declared strict test (SpotBugs, FindSecBugs), `configContractCheck` (the environment contract), `integrationCheck` (the
lanes). `ci` is leaf checks + architectureCheck + qualityCheck + configContractCheck + qualificationCheck; `releaseCheck` adds declared strict integration lanes). `ci` (pull request) is leaf checks + architectureCheck +
provenance, archive hygiene and the public-path snapshot. 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` Use public-path and env-key checks only when their surfaces changed. Full `test`, `check` or `ci`
requires the controller's workflow authorization. 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 ## Advisory and reporting
Use dependency-DAG/topological reasoning and 3–5 materially distinct alternatives when that many 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 금지 | | `application-core` | command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 |
| `adapter:inbound:*` | HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 | | `adapter:inbound:*` | HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 |
| `adapter:outbound:persistence-*` | JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration | | `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 개념 저장 금지 | | `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
| `app-bootstrap` | Spring Boot entrypoint와 composition root | | `app-bootstrap` | Spring Boot entrypoint와 composition root |
| `sample-portfolio` | WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 | | `sample-portfolio` | WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 |
@@ -42,7 +42,7 @@ cd src
./gradlew bootstrap ./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 ```bash
curl -fsS http://localhost:8080/api/healthcheck 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)에 있습니다. `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 ```bash
cd src cd src
./gradlew :app-bootstrap:bootRun ./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 | | `dev` | PostgreSQL | Flyway |
| `prod` | 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}" BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
GIT_SHA: "${GIT_SHA:-0000000}" GIT_SHA: "${GIT_SHA:-0000000}"
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}" 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 # 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 # 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 # 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 # 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 - Date: 2026-08-11
- Design: §19.2 - Design: §19.2
+7 -4
View File
@@ -1,6 +1,8 @@
# ADR-JPA-003 — Completion unknown is never retried # 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 - Date: 2026-08-11
- Design: §17 - 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 `TransactionCompletionUnknownException` is never retried, automatically or otherwise. It is
produced only by a failure observed while the transaction phase is `COMMITTING`, and only for 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 SQLSTATE `40003`, a connection-class (`08*`) state, or a transport break. Recovery is
domain-specific reconciliation through `TransactionCompletionResolver`. domain-specific reconciliation.
## Consequences ## Consequences
@@ -37,5 +39,6 @@ which idempotency record, business row, or outbox entry proves the write happene
## Enforcement ## Enforcement
`JpaFailureContextTest`; `DefaultJpaRetryPolicyTest`; `CommitFailureClassifierTest`; release gate `JpaFailureContextTest`;
`completion-unknown-no-retry`. `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 ## Enforcement
`JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate`; `JpaDangerousConfigurationGuard`; `FlywaySchemaPolicy`; `FlywayValidationGate` (testkit, used by the
`PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and `runtime-role-no-ddl`. migration contract tests); `PostgreSqlRuntimeRoleVerifier`; release gates `flyway-validate` and
`runtime-role-no-ddl`.
@@ -3,6 +3,13 @@
- **Status:** Accepted - **Status:** Accepted
- **Date:** 2026-08-13 - **Date:** 2026-08-13
- **Design source:** design §2 (D-15), §3.2–§3.3; Advanced expansion plan Task 15 - **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 ## Context
@@ -19,15 +19,16 @@ retention, its own eviction and its own opinion about ordering.
## Decision ## Decision
**Three outcomes, expressed in the stream rather than in the status.** `WebStreamEnvelope` is sealed **Three outcomes, expressed in the stream rather than in the status.** The wire record (for NDJSON,
over `Item`, `Failure` and `Complete`. A client that sees neither terminal envelope has been cut off, `NdjsonRecord`) is an item, a failure or a completion. A client that sees neither terminal record
and that third case is recorded as `ABRUPT_CLOSE` rather than counted as a completion — which is has been cut off, and that third case is recorded as `ABRUPT_CLOSE` rather than counted as a
where a rising rate of mid-stream failures would otherwise hide. completion — which is where a rising rate of mid-stream failures would otherwise hide.
**Nothing writes a problem document onto a committed response.** `WebStreamTerminationMapper` **Nothing writes an error body onto a committed response.** Before commit, a failure is an ordinary
branches on whether any byte has been written. Before commit, an RFC 9457 problem with a real HTTP error (the `Envelope`) with a real status; after, a terminal record. Attempting both produces a
status; after, a terminal record. Attempting both produces a body that is half stream and half JSON, body that is half stream and half JSON, which no client parses and every proxy caches as a success.
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 **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 repeated or regressing position. A client deduplicating on position would silently drop the second
@@ -6,8 +6,9 @@
## Context ## Context
Advanced Task 2 offers a virtual-thread executor for MVC; Task 3 offers a bounded blocking bridge Advanced Task 2 offers a virtual-thread executor for MVC; Task 3 offered a bounded blocking bridge
for WebFlux. 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 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 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 in time, because otherwise a slow dependency's callers accumulate until the heap does and the fast
dependencies starve behind them. 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 **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 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 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 silently, and only when the experimental lane runs. `OpenApi32CompatibilityReport` compares the
snapshot hash before and after and makes a difference a promotion blocker. 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 **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 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; 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 # 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 - Date: 2026-08-25
- Scope: `:adapter:inbound:websocket` - 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 # 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 - Date: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.resume`, `advanced.cluster`, `advanced.presence` - 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 # 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 - Date: 2026-08-25
- Scope: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit` - Scope: `adapter:inbound:websocket` — `advanced.stomp`, `advanced.stomp.rabbit`
+1 -234
View File
@@ -5,180 +5,22 @@
# split into capability artifacts. # split into capability artifacts.
# Update only after review with: # Update only after review with:
# ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange # ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange
# types: 401 # types: 168
dev.caskeleton.adapter.inbound.graphql.HealthGraphqlController 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.GraphQlClientProfile
dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfileName
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationId dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationId
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationName dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationName
dev.caskeleton.adapter.inbound.graphql.api.GraphQlSchemaCoordinate 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.GraphQlActivationEnvironmentPostProcessor
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlDeploymentMode 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.GraphQlPlatformAutoConfiguration
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformConfigurationException 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.GraphQlPlatformRuntime
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformSettings dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformSettings
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformStartupValidator dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformStartupValidator
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRetiredSafetyAxis dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRetiredSafetyAxis
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRootAutoConfiguration dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRootAutoConfiguration
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRuntimeTransport 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.ActorRef
dev.caskeleton.adapter.inbound.graphql.context.GraphQlCommandAttribution dev.caskeleton.adapter.inbound.graphql.context.GraphQlCommandAttribution
dev.caskeleton.adapter.inbound.graphql.context.GraphQlDeadline 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.GraphQlDocumentShape
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentShapeAnalyzer dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentShapeAnalyzer
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlFieldCostDescriptor 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.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.GraphQlStructuralLimitException
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitPolicy dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitPolicy
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimits 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.GraphQlErrorCode
dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext
dev.caskeleton.adapter.inbound.graphql.error.GraphQlExceptionResolver 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.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.error.GraphQlWireError
dev.caskeleton.adapter.inbound.graphql.execution.BoundedPreparsedDocumentProvider dev.caskeleton.adapter.inbound.graphql.execution.BoundedPreparsedDocumentProvider
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlAnonymousOperationException 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.GraphQlExecutionPipeline
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineException dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineValidator dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineValidator
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfile
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionProfileException 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.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.GraphQlOperationSelection
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheKey dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheKey
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheMetrics dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheMetrics
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCachePolicy dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCachePolicy
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlRequestCancelledException 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.execution.GraphQlTimeoutPolicy
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfile dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfile
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileClassifier 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.GraphQlSelectionSetView
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionSignature dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionSignature
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlUnmappedSelectionException 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.GraphQlExtensionsPolicy
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpContractException 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.GraphQlHttpOutcome
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpProfile
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpRequestEnvelope 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.GraphQlJsonStructurePolicy
dev.caskeleton.adapter.inbound.graphql.http.GraphQlJsonValues 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.GraphQlRequestEnvelopeValidator
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestFormatException dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestFormatException
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestSize dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestSize
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestTooLargeException 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.GraphQlBatchMutationItemResult
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlBusinessResult 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.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.GraphQlMutationContractException
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationContractValidator dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationContractValidator
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationCoordinate 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.GraphQlMutationPayload
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationResultMapper dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationResultMapper
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlDataLoaderObservationConvention 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.GraphQlObservationContractException
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlObservationNames dev.caskeleton.adapter.inbound.graphql.observation.GraphQlObservationNames
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlOperationNameCardinality 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.GraphQlRequestObservationConvention
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlResolverObservationConvention dev.caskeleton.adapter.inbound.graphql.observation.GraphQlResolverObservationConvention
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlSensitiveAttributeFilter 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.GraphQlPageInfo
dev.caskeleton.adapter.inbound.graphql.pagination.HmacGraphQlCursorCodec dev.caskeleton.adapter.inbound.graphql.pagination.HmacGraphQlCursorCodec
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlClientPolicy 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.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.GraphQlBatchLoaderRegistrar
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridge dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridge
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBlockingBridgeFullException 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.InstantScalar
dev.caskeleton.adapter.inbound.graphql.scalar.LongScalar dev.caskeleton.adapter.inbound.graphql.scalar.LongScalar
dev.caskeleton.adapter.inbound.graphql.scalar.UuidScalar 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.GraphQlScalarDefinition
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarManifest dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarManifest
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarPolicy 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.ApplicationObjectAuthorization
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticatedPrincipal dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticatedPrincipal
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticationContextFactory 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.GraphQlAuthorizationInterceptor
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationPolicy dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationPolicy
dev.caskeleton.adapter.inbound.graphql.security.GraphQlBatchContext 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.GraphQlContextPropagator
dev.caskeleton.adapter.inbound.graphql.security.GraphQlObjectAuthorizationPort dev.caskeleton.adapter.inbound.graphql.security.GraphQlObjectAuthorizationPort
dev.caskeleton.adapter.inbound.graphql.security.GraphQlTenantIsolationException 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.failure.SqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.fileserver.FileserverSchemaActivation dev.caskeleton.adapter.outbound.persistence.fileserver.FileserverSchemaActivation
dev.caskeleton.adapter.outbound.persistence.hibernate.HibernateProviderPolicy 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.migration.FlywaySchemaPolicy
dev.caskeleton.adapter.outbound.persistence.outbox.OutboxClaimRepository 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.PostgreSqlOutboxClaimRepository
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlPersistenceConfig dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlSqlStateErrorMapping dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlSqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.security.DatabasePrivilegeReport dev.caskeleton.adapter.outbound.persistence.security.DatabasePrivilegeReport
dev.caskeleton.adapter.outbound.persistence.security.PostgreSqlRuntimeRoleVerifier dev.caskeleton.adapter.outbound.persistence.security.PostgreSqlRuntimeRoleVerifier
dev.caskeleton.adapter.outbound.persistence.transaction.TransactionLocalTimeoutConfigurer
+2 -99
View File
@@ -5,7 +5,7 @@
# root yet. # root yet.
# Update only after review with: # Update only after review with:
# ./gradlew :adapter:outbound:persistence-jpa:updateJpaApiSurface -PapproveJpaApiSurfaceChange # ./gradlew :adapter:outbound:persistence-jpa:updateJpaApiSurface -PapproveJpaApiSurfaceChange
# types: 311 # types: 214
dev.caskeleton.adapter.outbound.persistence.api.PersistenceOperationName dev.caskeleton.adapter.outbound.persistence.api.PersistenceOperationName
dev.caskeleton.adapter.outbound.persistence.api.capability.CapabilitySupport dev.caskeleton.adapter.outbound.persistence.api.capability.CapabilitySupport
dev.caskeleton.adapter.outbound.persistence.api.capability.JpaCapability 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.SchemaMismatchException
dev.caskeleton.adapter.outbound.persistence.api.error.SerializationFailureException dev.caskeleton.adapter.outbound.persistence.api.error.SerializationFailureException
dev.caskeleton.adapter.outbound.persistence.api.error.SqlExceptionSqlStateResolver 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.TransactionCompletionUnknownException
dev.caskeleton.adapter.outbound.persistence.api.error.TransactionTimeoutException dev.caskeleton.adapter.outbound.persistence.api.error.TransactionTimeoutException
dev.caskeleton.adapter.outbound.persistence.api.error.UniqueConstraintViolationException 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.CursorPayloadCodec
dev.caskeleton.adapter.outbound.persistence.api.query.KeysetPageRequest dev.caskeleton.adapter.outbound.persistence.api.query.KeysetPageRequest
dev.caskeleton.adapter.outbound.persistence.api.query.KeysetSlice 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.QueryScope
dev.caskeleton.adapter.outbound.persistence.api.query.SignedJsonCursorCodec dev.caskeleton.adapter.outbound.persistence.api.query.SignedJsonCursorCodec
dev.caskeleton.adapter.outbound.persistence.api.query.SortDirection 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.TransactionCompletionEvidence
dev.caskeleton.adapter.outbound.persistence.api.transaction.TransactionProfile
dev.caskeleton.adapter.outbound.persistence.audit.AuditContextPort dev.caskeleton.adapter.outbound.persistence.audit.AuditContextPort
dev.caskeleton.adapter.outbound.persistence.audit.AuditableEntity dev.caskeleton.adapter.outbound.persistence.audit.AuditableEntity
dev.caskeleton.adapter.outbound.persistence.audit.DomainContextAuditContextPort 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.EntityRevision
dev.caskeleton.adapter.outbound.persistence.envers.EnversConfigurationGuard dev.caskeleton.adapter.outbound.persistence.envers.EnversConfigurationGuard
dev.caskeleton.adapter.outbound.persistence.envers.EnversHistoryPolicy 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.EnversRevisionMetadata
dev.caskeleton.adapter.outbound.persistence.envers.HibernateEnversHistoryReader 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.TenantDataSourceLifecycle
dev.caskeleton.adapter.outbound.persistence.experimental.database.TenantDataSourceRegistry 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.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.ConsistencyAwareDataSourceRouter
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ConsistencyToken dev.caskeleton.adapter.outbound.persistence.experimental.replica.ConsistencyToken
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ReadConsistency 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.ReplicaRoutingDecision
dev.caskeleton.adapter.outbound.persistence.experimental.replica.ReplicaTarget dev.caskeleton.adapter.outbound.persistence.experimental.replica.ReplicaTarget
dev.caskeleton.adapter.outbound.persistence.experimental.replica.TransactionContext 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.RlsPolicyVerifier
dev.caskeleton.adapter.outbound.persistence.experimental.rls.RlsTenantSessionBinder dev.caskeleton.adapter.outbound.persistence.experimental.rls.RlsTenantSessionBinder
dev.caskeleton.adapter.outbound.persistence.experimental.schema.SchemaMultiTenantConnectionProvider 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.schema.TenantMigrationStatus
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantAwareRepositoryGuard dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantAwareRepositoryGuard
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantContext 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.experimental.tenant.TenantId
dev.caskeleton.adapter.outbound.persistence.failure.PersistenceExceptionTranslator dev.caskeleton.adapter.outbound.persistence.failure.PersistenceExceptionTranslator
dev.caskeleton.adapter.outbound.persistence.failure.SqlStateErrorMapping dev.caskeleton.adapter.outbound.persistence.failure.SqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.failure.StandardSqlStateErrorMapping 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.H2OutboxClaimRepository
dev.caskeleton.adapter.outbound.persistence.h2.H2PersistenceConfig dev.caskeleton.adapter.outbound.persistence.h2.H2PersistenceConfig
dev.caskeleton.adapter.outbound.persistence.h2.H2SqlStateErrorMapping 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.BatchExecutionResult
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.HibernateBatchConfigurationGuard dev.caskeleton.adapter.outbound.persistence.hibernate.batch.HibernateBatchConfigurationGuard
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.HibernateJpaBatchExecutor 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.JpaBatchProfile
dev.caskeleton.adapter.outbound.persistence.hibernate.batch.JpaBatchProfileRegistry
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.AffectedRowsExpectation 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.BulkDmlResult
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.BulkOperationName dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.BulkOperationName
dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.HibernateBulkDmlExecutor dev.caskeleton.adapter.outbound.persistence.hibernate.bulk.HibernateBulkDmlExecutor
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.HibernateStatelessSessionRunner dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.HibernateStatelessSessionRunner
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.StatelessRowCapExceededException 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.StatelessWorkName
dev.caskeleton.adapter.outbound.persistence.hibernate.stateless.StatelessWorkResult 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.IdempotencyReaper
dev.caskeleton.adapter.outbound.persistence.idempotency.IdempotencyRecordJpaRepository 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.entity.IdempotencyRecordEntity
dev.caskeleton.adapter.outbound.persistence.idempotency.mapper.IdempotencyRecordEntityMapper
dev.caskeleton.adapter.outbound.persistence.liveevent.JpaLiveEventReplayAdapter dev.caskeleton.adapter.outbound.persistence.liveevent.JpaLiveEventReplayAdapter
dev.caskeleton.adapter.outbound.persistence.liveevent.LiveEventJpaRepository dev.caskeleton.adapter.outbound.persistence.liveevent.LiveEventJpaRepository
dev.caskeleton.adapter.outbound.persistence.liveevent.entity.LiveEventEntity dev.caskeleton.adapter.outbound.persistence.liveevent.entity.LiveEventEntity
dev.caskeleton.adapter.outbound.persistence.lock.DistributedLockPersistenceConfig dev.caskeleton.adapter.outbound.persistence.lock.DistributedLockPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.lock.LockRegistryDistributedLockAdapter dev.caskeleton.adapter.outbound.persistence.lock.LockRegistryDistributedLockAdapter
dev.caskeleton.adapter.outbound.persistence.lock.LockSettings 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.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.SchemaManagementMode
dev.caskeleton.adapter.outbound.persistence.migration.SchemaVersionSnapshot
dev.caskeleton.adapter.outbound.persistence.notification.NotificationJpaPersistenceConfig dev.caskeleton.adapter.outbound.persistence.notification.NotificationJpaPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.notification.NotificationSchemaActivation dev.caskeleton.adapter.outbound.persistence.notification.NotificationSchemaActivation
dev.caskeleton.adapter.outbound.persistence.notification.NotificationSchemaStream dev.caskeleton.adapter.outbound.persistence.notification.NotificationSchemaStream
dev.caskeleton.adapter.outbound.persistence.notification.configuration.NotificationJpaPersistenceFacade 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.AdminAuditEntity
dev.caskeleton.adapter.outbound.persistence.notification.platform.AdminAuditJpaRepository dev.caskeleton.adapter.outbound.persistence.notification.platform.AdminAuditJpaRepository
dev.caskeleton.adapter.outbound.persistence.notification.platform.ConsentEntity 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.InboxOutboxRecordFactory
dev.caskeleton.adapter.outbound.persistence.notification.platform.inbox.JpaNotificationInbox dev.caskeleton.adapter.outbound.persistence.notification.platform.inbox.JpaNotificationInbox
dev.caskeleton.adapter.outbound.persistence.observation.JpaMetricTags 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.LowCardinality
dev.caskeleton.adapter.outbound.persistence.observation.MicrometerQueryObservation dev.caskeleton.adapter.outbound.persistence.observation.MicrometerQueryObservation
dev.caskeleton.adapter.outbound.persistence.observation.SqlDiagnosticRedactor 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.OutboxReaper
dev.caskeleton.adapter.outbound.persistence.outbox.OutboxStoreAdapter dev.caskeleton.adapter.outbound.persistence.outbox.OutboxStoreAdapter
dev.caskeleton.adapter.outbound.persistence.outbox.entity.OutboxEventEntity 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.PostgreSqlOutboxClaimRepository
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlPersistenceConfig dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlPersistenceConfig
dev.caskeleton.adapter.outbound.persistence.postgresql.PostgreSqlSqlStateErrorMapping 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.CopyLimits
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.CopyOperationName dev.caskeleton.adapter.outbound.persistence.postgresql.copy.CopyOperationName
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.CopyResult 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.RegisteredCopyStatement
dev.caskeleton.adapter.outbound.persistence.postgresql.copy.RegisteredPostgreSqlCopyLoader 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.PostgreSqlExceptionTranslator
dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlFailureClassifier dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlFailureClassifier
dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlServerErrorFields dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlServerErrorFields
dev.caskeleton.adapter.outbound.persistence.postgresql.error.PostgreSqlState 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.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.JsonDocument
dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonDocumentCodec dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonDocumentCodec
dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonPathName dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonPathName
dev.caskeleton.adapter.outbound.persistence.postgresql.json.PostgreSqlJsonQuerySupport 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.PostgreSqlLockExceptionTranslator
dev.caskeleton.adapter.outbound.persistence.postgresql.lock.PostgreSqlLockOptions 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.PgRange
dev.caskeleton.adapter.outbound.persistence.postgresql.range.PgRangeCodec 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.PredicatePolicy
dev.caskeleton.adapter.outbound.persistence.querydsl.QueryPage 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.DatabasePrivilegeReport
dev.caskeleton.adapter.outbound.persistence.security.DatabaseRolePolicy dev.caskeleton.adapter.outbound.persistence.security.DatabaseRolePolicy
dev.caskeleton.adapter.outbound.persistence.security.PostgreSqlRuntimeRoleVerifier dev.caskeleton.adapter.outbound.persistence.security.PostgreSqlRuntimeRoleVerifier
dev.caskeleton.adapter.outbound.persistence.security.SearchPathPolicy dev.caskeleton.adapter.outbound.persistence.security.SearchPathPolicy
dev.caskeleton.adapter.outbound.persistence.springdata.EntityGraphCatalog 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.FetchPlanApplier
dev.caskeleton.adapter.outbound.persistence.springdata.FetchPlanName dev.caskeleton.adapter.outbound.persistence.springdata.FetchPlanName
dev.caskeleton.adapter.outbound.persistence.springdata.JpaKeysetQuerySupport 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.SafeSortMapper
dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortRegistry dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortRegistry
dev.caskeleton.adapter.outbound.persistence.springdata.ScrollPolicy 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.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. # root yet.
# Update only after review with: # Update only after review with:
# ./gradlew :adapter:outbound:persistence-mongo:updateMongoApiSurface -PapproveMongoApiSurfaceChange # ./gradlew :adapter:outbound:persistence-mongo:updateMongoApiSurface -PapproveMongoApiSurfaceChange
# types: 346 # types: 271
dev.caskeleton.adapter.outbound.mongo.MongoOptInAutoConfigurationImportFilter dev.caskeleton.adapter.outbound.mongo.MongoDefaultsEnvironmentPostProcessor
dev.caskeleton.adapter.outbound.mongo.MongoPersistenceConfig dev.caskeleton.adapter.outbound.mongo.MongoPersistenceConfig
dev.caskeleton.adapter.outbound.mongo.MongoPersistenceSettings dev.caskeleton.adapter.outbound.mongo.MongoPersistenceSettings
dev.caskeleton.adapter.outbound.mongo.MongoRootAutoConfiguration 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.MongoAdvancedCapabilityGuard
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedEntryPoint dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedEntryPoint
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedPolicy 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.MongoCsfleClientFactory
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.csfle.MongoCsfleFieldPolicy 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.MongoCsfleMode
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.csfle.MongoCsfleProfile 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.MongoEncryptedFieldDescriptor
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoEncryptionMetadataOwnership dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoEncryptionMetadataOwnership
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryShape 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.MongoQueryableEncryptionCollectionManager
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryableEncryptionProfile dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryableEncryptionProfile
dev.caskeleton.adapter.outbound.mongo.advanced.encryption.qe.MongoQueryableEncryptionQueryType 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.MongoRoutingClassification
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.ShardAwareQueryValidator dev.caskeleton.adapter.outbound.mongo.advanced.sharding.ShardAwareQueryValidator
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.ShardKeyDescriptor 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.ShardKeyAnalyzer
dev.caskeleton.adapter.outbound.mongo.advanced.sharding.admin.ShardKeyReadinessReport 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.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.MongoTenantLifecyclePolicy
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.database.MongoTenantMigrationCheckpointStore 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.database.MongoTenantMigrationCoordinator
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.shared.MongoTenantContext 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.MongoTenantManifestValidator
dev.caskeleton.adapter.outbound.mongo.advanced.tenancy.shared.MongoTenantPredicateInjector 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.MongoAggregationPlan
dev.caskeleton.adapter.outbound.mongo.aggregation.MongoAggregationProfile dev.caskeleton.adapter.outbound.mongo.aggregation.MongoAggregationProfile
dev.caskeleton.adapter.outbound.mongo.aggregation.MongoAggregationRisk 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.MongoConsistencyGuarantee
dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyProfile dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyProfile
dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyRegistry 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.MongoConnectionException
dev.caskeleton.adapter.outbound.mongo.api.error.MongoCursorException dev.caskeleton.adapter.outbound.mongo.api.error.MongoCursorException
dev.caskeleton.adapter.outbound.mongo.api.error.MongoDataSchemaUnsupportedException 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.MongoBigIntegerRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoDecimalRepresentation dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoDecimalRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoEnumRepresentation 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.MongoTemporalRepresentation
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoTypeMetadataPolicy dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoTypeMetadataPolicy
dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoTypeRepresentationManifest 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.MongoProfileProperties
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoStartupValidator dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoStartupValidator
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoTopologyProbe 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.client.MongoClientSettingsFactory
dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureClassifier dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureClassifier
dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureTranslator 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.MongoKeysetSlice
dev.caskeleton.adapter.outbound.mongo.query.pagination.MongoKeysetSort dev.caskeleton.adapter.outbound.mongo.query.pagination.MongoKeysetSort
dev.caskeleton.adapter.outbound.mongo.query.pagination.MongoNullSortOrdering 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.MongoIndexApplyPolicy
dev.caskeleton.adapter.outbound.mongo.schema.index.MongoIndexDescriptorView dev.caskeleton.adapter.outbound.mongo.schema.index.MongoIndexDescriptorView
dev.caskeleton.adapter.outbound.mongo.schema.index.MongoIndexDiff 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.MongoTransactionScope
dev.caskeleton.adapter.outbound.mongo.transaction.MongoTransactionSession dev.caskeleton.adapter.outbound.mongo.transaction.MongoTransactionSession
dev.caskeleton.adapter.outbound.mongo.transaction.MongoTransactionSessionFactory 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.SpringMongoTransactionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.SpringMongoTransactionSessionFactory 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.MongoCommitReconciler
dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoRetryBudget dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoRetryBudget
dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoRetryDecision dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoRetryDecision
dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoTransactionRetryCoordinator dev.caskeleton.adapter.outbound.mongo.transaction.retry.MongoTransactionRetryCoordinator
dev.caskeleton.adapter.outbound.mongo.transaction.session.MongoCausalSessionContext dev.caskeleton.adapter.outbound.mongo.transaction.session.MongoCausalSessionContext
dev.caskeleton.adapter.outbound.mongo.transaction.session.MongoCausalSessionExecutor dev.caskeleton.adapter.outbound.mongo.transaction.session.MongoCausalSessionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.session.ReactiveMongoCausalSessionExecutor
dev.caskeleton.adapter.outbound.mongo.transaction.session.SpringMongoCausalSessionExecutor dev.caskeleton.adapter.outbound.mongo.transaction.session.SpringMongoCausalSessionExecutor
+227 -22
View File
@@ -9,7 +9,7 @@ real provider."
| Column | The question | Who decides it | | Column | The question | Who decides it |
| --- | --- | --- | | --- | --- | --- |
| **IMPLEMENTED** | Does this repository contain the capability? | `src/config/architecture/modules.json` — the leaf is registered | | **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 | | **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. 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 ## 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` | | 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) | `APP_PERSISTENCE_MONGO_ENABLED` | yes | yes | yes | six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `mongo-container-lanes` | | 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 (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. | | 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` | yes | yes | yes | `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml` | | 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. |
| 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. | | 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. |
| 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. | | 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. |
| 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` | | 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. |
| Outbound HTTP client | `APP_HTTPCLIENT_ENABLED` | yes | yes | yes | `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `integration-main.yml` → `httpclient-fault-injection` | | 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` |
| 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. | | 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` |
| 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. | | 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. | | 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 ## Reading the "no" rows
A **no** in WIRED is not a defect. It is the review's Build Composition principle working: the A **yes** in WIRED means "present when its line is selected": uncommenting the one line is the whole
repository holds more capabilities than any one derived service should ship, and a capability that change, and deleting it removes the module's beans, settings and dependencies together. It does not
is absent from the artifact holds no beans, no connections and no threads whatever its configuration mean the default artifact ships the capability — none of the **yes** rows is in the default
says. The three **no** rows are the ones where that choice has been made and is enforced by a test. 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 A **no** in WIRED is not a defect either. It marks a capability with no one-line selection: the gRPC
is a weaker guarantee — correct, but it depends on the switch being honest rather than on the code platform is a separate Gradle build, and the web-advanced library is taken as `implementation` by a
being absent. Moving more rows to **no** is what `app-bootstrap`'s composition-ownership work is for. service's own adapter leaf, never by a composition root.
## Keeping this honest ## Keeping this honest
`CapabilityStatusDocumentTest` derives the switch list from `MasterSwitch` and fails when a switch `CapabilityStatusDocumentTest` checks that the column sources above are named — the module
has no row here. That is deliberately the only automated check: a table of facts that a parser 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, 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. 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 # Fileserver configuration
Every key below lives under `app.fileserver-platform` (environment form Every key below lives under `app.fileserver-platform` (environment form
`APP_FILESERVER_PLATFORM_*`). That namespace is the HTTP platform's alone: `app.fileserver.*` `APP_FILESERVER_PLATFORM_*`).
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.
While `app.fileserver-platform.enabled` is false none of these keys is bound at all — the 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 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 | | `416` | unsatisfiable Range; carries the real length |
| `422` | digest, signature, or scanner rejection | | `422` | digest, signature, or scanner rejection |
| `429` | transfer admission or rate limit | | `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 | | `503` | storage or scanner unavailable |
| `504` | downstream timeout | | `504` | downstream timeout |
| `507` | out of storage capacity | | `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` | | Local filesystem (ext4) content store | Stable | `fileserver-local-ext4-contract` |
| Spring MVC transport (raw, multipart, batch, download) | Stable | `fileserver-http-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` | | Path, filename, range, and problem-detail hardening | Stable | `fileserver-security-suite` |
| Bounded-memory transfer | Stable | `fileserver-bounded-memory` | | Bounded-memory transfer | Stable | `fileserver-bounded-memory` |
| Application and architecture invariants | Stable | `fileserver-unit-and-architecture` | | 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` | | Full release verification | Stable | `fileserver-full-verification` |
| HTTP resumable uploads draft-12 | Experimental | `fileserver-http-contract` | | 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` The reactive router and handlers (`web.fileserver.reactive`) were removed on 2026-09-25 (D4: the
contributes the scheduler, the handlers and a `RouterFunction` bean under template is servlet on virtual threads). The shipped composition could never select them — the web
`@ConditionalOnWebApplication(type = REACTIVE)` plus the platform master switch. Previously nothing leaf puts `DispatcherServlet` on the classpath, so Boot resolves SERVLET.
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.
## Explicitly not claimed ## 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 | | 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 The module is on when present: a service adds `runtimeOnly project(':adapter:outbound:httpclient')`
a package the composition root's component scan excludes, so while the switch is absent or false the to `app-bootstrap/build.gradle`, and the module's own `config/module-defaults/httpclient.yml` (loaded at the lowest
class is never processed and neither is anything it imports: no property is bound, and no transport 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 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 malformed HTTP client setting cannot fail the startup of a deployment that switched it off.
HTTP.
Anything that is not exactly `true` — `yes`, `1`, blank — leaves the platform off. Turning it on Anything that is not exactly `true` — `yes`, `1`, blank — turns the platform off. On with no client
with no client declared is a startup failure carrying `HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`: a declared is a startup failure carrying `HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`: a platform with nothing
platform with nothing to call still holds transport providers and gateways no caller can reach. to call still holds transport providers and gateways no caller can reach.
## Declaring clients from the environment ## 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. - [ ] Logical calls and attempts are separate metrics with no forbidden label.
- [ ] DNS, pool, TLS, reset, partial response, and HTTP/2 GOAWAY are reproducible. - [ ] DNS, pool, TLS, reset, partial response, and HTTP/2 GOAWAY are reproducible.
- [ ] Thread, heap, direct memory, pool, and retry budget bounds hold. - [ ] 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 ## 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-webclient` | `…httpclient.webclient` | `…outbound.httpclient.webclient` |
| `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` | | `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` |
| `httpclient-dynamic-target` | `…httpclient.dynamic` | `…outbound.httpclient.dynamic` | | `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-jetty-http3-experimental` | `…httpclient.http3` | `…outbound.httpclient.http3` |
| `httpclient-spring-boot-starter` | `…httpclient.autoconfigure` | `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` | | `httpclient-spring-boot-starter` | `…httpclient.autoconfigure` | `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` |
| `httpclient-testkit` | `…httpclient.testkit` | `…outbound.httpclient.testkit` (`testkit` source set) | | `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 | | 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. | | 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. | | `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 §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 | | 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 | | `RestClient` | Stable | Blocking execution | Bounded concurrency and an effective deadline are mandatory |
| `WebClient` | Stable | Reactive, streaming, SSE | No blocking work on the event loop | | `WebClient` | Stable | Reactive, streaming, SSE | No blocking work on the event loop |
| HTTP Service Client (`@HttpExchange`) | Default | Declarative typed client | Operation metadata is mandatory | | 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 | | 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 | | Dynamic Target (H3) | Restricted | User-supplied URL | Separate SSRF policy; inherits no credential |
| Native engine | Internal | Engine-specific configuration | Never an application-facing API | | 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 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 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` packages must not reference any Spring 7-only type, and no class uses
is confined to `…httpclient.spring7`. Executing the suite against an actual 6.2 distribution `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 requires a host project on that line. This limitation is stated rather than hidden behind a passing
check. check.
+3 -1
View File
@@ -1,6 +1,8 @@
# Experimental Promotion Checklist # 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 ## Technical evidence
+15 -15
View File
@@ -1,22 +1,22 @@
# Experimental Support Matrix # Experimental Support Matrix
Everything here is off unless its `backend.jpa.experimental.*` flag is explicitly true, and none of Experimental code is library code in `dev.caskeleton.adapter.outbound.persistence.experimental`.
it is part of the Stable composition. 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 | | Feature | Entry point | Evidence (PostgreSQL lane unless noted) | State |
|---|---|---| |---|---|---|---|
| Shared-schema multi-tenancy (column) | `backend.jpa.experimental.multitenancy-column` | Experimental | | Shared-schema multi-tenancy (column) | `tenant.TenantContext`, `tenant.TenantAwareRepositoryGuard` | `TenantColumnIsolationTest` | Experimental |
| PostgreSQL RLS multi-tenancy | `backend.jpa.experimental.multitenancy-rls` | Experimental | | PostgreSQL RLS multi-tenancy | `rls.RlsTenantSessionBinder`, `rls.RlsPolicyVerifier` | `RlsIsolationFailureTest` | Experimental |
| Schema-per-tenant | `backend.jpa.experimental.multitenancy-schema` | Experimental | | Schema-per-tenant | `schema.SchemaMultiTenantConnectionProvider`, `schema.SchemaTenantMigrationOrchestrator` | `SchemaTenantMigrationContractTest` | Experimental |
| Database-per-tenant | `backend.jpa.experimental.multitenancy-database` | Experimental | | Database-per-tenant pool budget | `database.TenantDataSourceRegistry`, `database.TenantPoolBudget` | `TenantPoolCapacityContractTest` | Experimental |
| Consistency-aware read replica | `backend.jpa.experimental.read-replica` | Experimental | | Consistency-aware read replica | `replica.ConsistencyAwareDataSourceRouter` (you implement `ReplicaLagMonitor`) | `ReadAfterWriteRoutingContractTest` | Experimental |
| Jakarta Persistence 4.0 lane | `backend.jpa.experimental.jakarta-persistence-4` | 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 |
| Hibernate ORM 8 lane | `backend.jpa.experimental.hibernate-8` | Experimental |
| PostgreSQL 19 lane | `backend.jpa.experimental.postgresql-19` | Experimental |
Presence on the classpath is not consent. `ExperimentalFeatureGate` fails startup when a module is The `backend.jpa.experimental.*` flags and `ExperimentalFeatureGate` that used to front these were
present and its flag is not set, because an experimental module can arrive transitively and a removed on 2026-09-25: no code read the flags from configuration, so setting one did nothing, and
tenant-isolation feature that switched itself on would be the worst possible default. the gate only checked a map the caller built itself.
## Known constraints ## Known constraints
+9 -7
View File
@@ -18,8 +18,10 @@ whichever instance started first.
## Validation fails closed and never repairs ## Validation fails closed and never repairs
`FlywayValidationGate` throws `SchemaMismatchException` on a checksum mismatch, a missing migration, At startup Flyway's own validation (and Hibernate `ddl-auto=validate`) refuses a checksum mismatch,
or a schema Hibernate disagrees with. It never calls `repair`. 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 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 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 executeInTransaction=false
``` ```
`ConcurrentIndexMigrationInspector` fails validation without it, and additionally requires the The testkit's `ConcurrentIndexMigrationInspector` checks a script for this in a migration test
migration to contain nothing else. A failed concurrent build leaves an invalid index behind; (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 recovering is a single `DROP INDEX` when the migration did nothing else, and a manual reconstruction
of partial state when it did. of partial state when it did.
An invalid index is not merely useless — the planner ignores it while every write still maintains 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 it. [runbooks.md](runbooks.md) has the query that finds them. Nothing drops them automatically: an
not drop them: an invalid index can also mean a build is still running, and the two are invalid index can also mean a build is still running, and the two are indistinguishable from the
indistinguishable from the catalog alone. catalog alone.
## Upgrade scenarios ## Upgrade scenarios
+34 -37
View File
@@ -2,55 +2,52 @@
Design §37. What is measured, and what must never appear in a measurement. 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 ## Bounded tags, always
Every JPA metric carries exactly five tags: persistence unit, operation, query, outcome, failure Every meter `MicrometerQueryObservation` records carries exactly five tags: persistence unit,
category. All five are registered identifiers, validated by `LowCardinality` at construction rather operation, query, outcome, failure category (`JpaMetricTags`). All five are registered identifiers,
than at the registry — so an unbounded value fails where it was introduced instead of surviving validated by `LowCardinality` at construction rather than at the registry — so an unbounded value
until a dashboard stops loading. 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 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 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. 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 ## Query names in SQL
`NamedStatementInspector` prefixes each statement with its registered query name as a SQL comment, `JpaRepositoryFragmentSupport` sets the registered query name as the `org.hibernate.comment` hint;
which travels into `pg_stat_activity`, `auto_explain`, and the slow-query log. Without it, "which Hibernate writes it into the SQL only when `hibernate.use_sql_comments=true`. The alternative is
endpoint issues this query" is answered by grepping the codebase for fragments of SQL. `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 ## Diagnostics
`SqlDiagnosticRedactor` removes string literals, numbers, and anything email-shaped before SQL `SqlDiagnosticRedactor.redact(sql)` removes string literals, numbers, and anything email-shaped. It is
reaches a log. Redaction is blunt on purpose: preserving "harmless" values would require knowing a utility for code that is about to log SQL; nothing in the platform logs SQL through it. Redaction
which columns hold personal data. is blunt on purpose: preserving "harmless" values would require knowing which columns hold personal
data.
## The actuator endpoint ## 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 the first leaves the transaction alive and the caller in control; the second has already been rolled
back by the server. 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 ## JSONB
`JsonDocument` carries a schema name and version alongside the payload. A JSONB column is schemaless `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 ## Named queries
Every registered query carries a `QueryName`. It becomes the metric tag, the trace attribute, and Every registered query carries a `QueryName`. It is the tag `MicrometerQueryObservation` records
the SQL comment that appears in `pg_stat_activity` and the slow-query log — which is the only thing under and the SQL comment that appears in `pg_stat_activity` and the slow-query log — which is the
that connects a statement on the server back to the use case that issued it. The format rejects raw 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 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. 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 | | 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. | | `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 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-spring-data` | `…jpa.springdata` | `…persistence.springdata` |
| `jpa-querydsl` | `…jpa.querydsl` | `…persistence.querydsl` | | `jpa-querydsl` | `…jpa.querydsl` | `…persistence.querydsl` |
| `jpa-hibernate` | `…jpa.hibernate` (+ `.batch`, `.bulk`, `.stateless`) | `…persistence.hibernate` (+ same subpackages) | | `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-postgresql-copy` | `…jpa.postgresql.copy` | `…persistence.postgresql.copy` |
| `jpa-migration-flyway` | `…jpa.migration` | `…persistence.migration` | | `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-envers` | `…jpa.envers` | `…persistence.envers` |
| `jpa-cache-hibernate` | `…jpa.cache` | `…persistence.cache` | | `jpa-cache-hibernate` | `…jpa.cache` | `…persistence.cache` |
| `jpa-observability` | `…jpa.observation` | `…persistence.observation` | | `jpa-observability` | `…jpa.observation` | `…persistence.observation` |
| `jpa-security` | `…jpa.security` | `…persistence.security` | | `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-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 The existing `…persistence.transaction` and `…persistence.postgresql` packages already hold this
leaf's `TransactionPort` implementation and PostgreSQL vendor composition. The platform types are 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) | | `TransactionCompletionEvidence` | `jpa-transaction` | `…persistence.api.transaction` | `TransactionCompletionUnknownException` (design §17.3 types the field) |
| `ConstraintCode` | `jpa-postgresql` | `…persistence.api.error` | `ConstraintViolationDetails` (design §22.4) | | `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`) The ArchUnit rule pack (`JpaArchitectureRules`, `EntityMappingCondition`, `EntityExposureCondition`)
is placed in the `testkit` source set rather than in `…persistence.security` production code. ArchUnit 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 - **§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 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 commit record may already be in the WAL when it arrives. The classifier that encoded this
`57P01`/`57P02`/`57P03` as completion-unknown alongside `40003`, class `08`, and transport breaks. (`CommitFailureClassifier`) was removed with the second transaction engine on 2026-09-25;
`CommitAmbiguityContractTest` asserts the SQLSTATE directly so the rule cannot silently narrow `PostgreSqlConcurrencyFailureContractTest` still pins the injection points.
again.
- **Schema-per-tenant status must be read back, not inferred from the run.** `MigrateResult`'s - **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 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 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. `ddl-auto` never mutates a deployed schema.
- `CREATE INDEX CONCURRENTLY` requires an explicit non-transactional migration marker. - `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. - 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, - Experimental features (multi-tenancy, RLS, schema/database tenancy, read replica) are library code
Hibernate 8, PostgreSQL 19) stay behind `backend.jpa.experimental.*` flags and never enter the a deployment constructs itself and never enter the Stable composition. JPA 4, Hibernate 8 and
Stable composition. 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 ## A transaction reported completion unknown
**Signal:** `jpa.transaction.completion.unknown` incremented; a `CompletionUnknownRecord` in the **Signal:** a write use case failed with a commit-phase error (connection lost, `57P01`, class
reconciliation channel. `08`) from `TransactionPort`.
**What it means:** the commit may or may not have happened. It is not a rollback. **What it means:** the commit may or may not have happened. It is not a rollback.
@@ -14,31 +14,26 @@ reason.
**Procedure:** **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. 2. Check the idempotency record for that key.
3. Check the business row the use case would have written. 3. Check the business row the use case would have written.
4. Check the outbox for a corresponding event. 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. 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 7. If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome;
answer is a legitimate outcome; guessing is not. guessing is not.
A record with no `transactionKey` cannot be resolved automatically — use the operation name and
timestamp.
## Deadlock or serialization rate rising ## 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. inconsistent lock order.
2. For deadlocks, check whether two operations take the same rows in opposite orders — that is a 2. For deadlocks, check whether two operations take the same rows in opposite orders — that is a
code fix, not a tuning one. code fix, not a tuning one.
3. For serialization failures under `SERIALIZABLE`, confirm the isolation is actually required. 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 ## 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 ## 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. 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. 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. 3. Re-apply the index migration.
The platform does not drop these automatically: on a rolling deploy every instance would race to 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 | | sort field | part of ORDER BY | `SafeSortRegistry` allowlist |
| JSON path | part of the statement | registered `JsonPathName` | | JSON path | part of the statement | registered `JsonPathName` |
| schema name | an identifier | registered `SchemaTenantRegistry` | | schema name | an identifier | registered `SchemaTenantRegistry` |
| upsert conflict target | an identifier list | registered `UpsertConflictTarget` |
| COPY table | an identifier | registered `RegisteredCopyStatement` | | COPY table | an identifier | registered `RegisteredCopyStatement` |
| queue claim SQL | a whole statement | registered `WorkQueueDefinition` |
Values are always bound. Identifiers are always registered. 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 16 | Stable | full contract suite, release lane (own matrix job) |
| PostgreSQL 17 | 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 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 | | 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 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 ## 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 | | Capability | Level |
|---|---| |---|---|
| Full-transaction retry | Stable |
| Commit completion evidence | Stable |
| Keyset pagination | Stable | | Keyset pagination | Stable |
| JDBC batch | Stable |
| Flyway schema gate | Stable | | Flyway schema gate | Stable |
| Runtime role verification | Stable | | Runtime role verification | Stable |
| Observability | Stable | | Commit completion evidence | Advanced |
| PostgreSQL native write (`ON CONFLICT`/`RETURNING`) | Advanced | | JDBC batch | Advanced |
| PostgreSQL work claim (`SKIP LOCKED`) | Advanced | | Observability (query metrics, redaction) | Advanced |
| PostgreSQL JSONB | Advanced | | PostgreSQL JSONB | Advanced |
| PostgreSQL array and range | Advanced | | PostgreSQL array and range | Advanced |
| Bulk DML | 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 | | `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 | | `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, `audit/AuditableEntity` is the only one: `created_*`/`updated_*`, a 256-character actor, stamped
stamped explicitly by the repository adapter. It is what the sample entities extend and what the explicitly by the repository adapter. It is what the sample entities extend and what the migrations
migrations were written for. 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 The mechanism does not reach a bulk or native update. It stamps on an ordinary save in the adapter,
(`modified_*`), a different actor length (64) and a different capture lifecycle (Spring Data so a statement that goes straight to the database leaves the audit columns showing the previous save.
listeners). Nothing embeds it and nothing composes `JpaAuditingConfiguration`, which is why it is A bulk update of an audited entity must therefore set the audit column in the statement, which
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
`JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit` checks over the production graph. `JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit` checks over the production graph.
## Explicitly unsupported ## 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 ## The application service owns the boundary
Repository adapters do not open transactions. The use case does, through `TransactionPort` or Repository adapters do not open transactions. The use case does, through `TransactionPort`,
`JpaTransactionExecutor`, because the unit of work is a business decision and only the use case because the unit of work is a business decision and only the use case knows where it starts and
knows where it starts and ends. 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 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. why `JpaDangerousConfigurationGuard` fails startup rather than trusting configuration review.
## Profiles `REQUIRES_NEW` acquires a second physical connection while pinning the first, so the pool must
satisfy:
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:
```text ```text
maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1 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 `SpringTransactionPort` runs the action once. A failure rolls back and propagates, translated to
Persistence Context for every attempt. That granularity is the whole point: an optimistic conflict the shared persistence error codes where the SQLSTATE is known. A caller that decides to retry must
means the state the attempt computed against is no longer the committed state, so re-issuing the re-run the whole use case in a new transaction — never re-issue one statement — because an
same statement would compute the same wrong answer. The domain rules have to run again against optimistic conflict or a serialization failure means the state the attempt computed against is no
reloaded data. longer the committed state.
Retryable: serialization failure (`40001`), deadlock (`40P01`), optimistic conflict. A second engine with named policies, deadline budgets, transaction-local timeouts and automatic
Not retryable: constraint violations, schema mismatch, query timeout, and anything unclassified. full-transaction retry (`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`,
`PolicyTransactionPort`) existed next to this one and was removed on 2026-09-25. Its last commit is
Two additional refusals, independent of budget: recorded in `docs/capability-status.md`.
- 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.
## Completion unknown ## Completion unknown
`TransactionCompletionUnknownException` is never retried, and the type system enforces it twice: A connection can break while a commit is in flight; the server may have committed and only the
`JpaFailureContext` refuses to represent a retryable completion-unknown failure, and the exception acknowledgement was lost. `TransactionCompletionUnknownException` is never retried, and the type
rebuilds its context through the safe factory whatever it is handed. 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
`EvidenceAwareJpaTransactionManager` marks the phase `COMMITTING` immediately before delegating to (`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried`).
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.
Recovery is reconciliation, not retry: Recovery is reconciliation, not retry:
```text ```text
record the transaction key -> check the idempotency record check the idempotency record -> check the business row -> check the outbox
-> check the business row -> still undetermined? escalate
-> check the outbox
-> still undetermined? reconciliation queue
``` ```
`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`은 `APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED` / `ca-skeleton.outbox.canonical-transport-enabled`은
기존 `outbox_event` writer/claim/status authority를 유지한 채 canonical row의 **transport만** platform 기존 `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 `true`일 때는 `OutboxAppendPort`가 `ValidatedIntegrationEvent`의 exact envelope bytes와 canonical
metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다. metadata를 기존 outbox row에 저장하고, claim된 canonical row는 `IntegrationEventPublishPort`로 간다.
@@ -135,9 +135,10 @@ app:
## Broker profile ## Broker profile
브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`이 어느 계열의 설정이 적용되는지 브로커는 `app.messaging.brokers` 아래에 한 번만 기술한다. `type`은 `kafka`만 받는다 — transport가
결정하며, 다른 계열의 키(Kafka 항목의 `prefetch` 같은)는 무시되지 않고 부팅 실패로 거절된다 — 있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(`addresses`, `prefetch`, `quorum-queues` 등)와
무시하면 그 줄을 쓴 사람은 무언가가 적용됐다고 믿게 된다. `type: rabbitmq`는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라,
지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다.
### Kafka ### Kafka
@@ -160,30 +161,9 @@ app:
authentication-enabled: false # production이면 필수 authentication-enabled: false # production이면 필수
``` ```
### RabbitMQ `production: true`인 Kafka 브로커는 `tls-enabled`와 `authentication-enabled`가 모두 참이어야 하고,
그렇지 않으면 `KafkaProfileValidator`가 부팅을 거절한다. `app.messaging.broker`로 고를 수 있는 값은
```yaml `kafka`뿐이다. 위 예시가
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: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다. `production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다.
## 보안 ## 보안
@@ -211,20 +191,13 @@ app:
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는 연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다. 서로 다른 `credential-id`를 써야 하며, 같으면 부팅에 실패한다.
## Experimental / Optional Kafka producer는 이 항목을 실제 클라이언트 설정(`security.protocol`, `sasl.mechanism`,
`sasl.jaas.config`, `ssl.enabled.protocols=TLSv1.3,TLSv1.2`, hostname 검증)으로 옮긴다. 평문으로
기본값은 전부 `false`다. 조용히 넘어가지 않도록 다음 경우 부팅에 실패한다: 브로커가 `tls-enabled`나
`authentication-enabled`를 켰는데 `app.messaging.security.<broker>`가 없을 때, security 항목은
```yaml 있는데 `CredentialProvider` bean이 없을 때, 같은 브로커에 맞는 항목이 둘 이상일 때.
app: 한계: truststore/keystore 설정 키가 없어 TLS는 JVM 기본 truststore를 쓰고, `MUTUAL_TLS`는 클라이언트
messaging: 인증서를 제출할 수 없다(미지원).
experimental:
kafka-share: false
pulsar: false
nats: false
bridge:
spring-cloud-stream: false
```
## Backpressure ## Backpressure
+3 -2
View File
@@ -27,8 +27,9 @@
`PublishResult` → `OutboxPublishOutcome`. registry에 leaf를 추가하는 변경이라 별도 커밋. `PublishResult` → `OutboxPublishOutcome`. registry에 leaf를 추가하는 변경이라 별도 커밋.
- golden contract 테스트: event/message ID, type, schema revision, partition/order/correlation/ - golden contract 테스트: event/message ID, type, schema revision, partition/order/correlation/
causation/tenant/trace, payload digest, wire version이 bytes 단위로 보존되는지. causation/tenant/trace, payload digest, wire version이 bytes 단위로 보존되는지.
- 단일 publication authority: 기존 `OutboxPublicationAuthority` fence를 재사용해 writer/relay가 - 단일 publication authority: writer/relay가 동시에 ACTIVE가 되지 않도록 하는 fence. 이 용도로 쓰려던
동시에 ACTIVE가 되지 않도록. **dual write/publish는 금지** — 한 business fact가 두 durable store와 outbox V2의 `OutboxPublicationAuthority`는 한 번도 조립되지 않은 채 2026-09-25에 삭제됐으므로
(`docs/capability-status.md` "제거된 코드") cutover가 자기 fence를 새로 가져야 한다. **dual write/publish는 금지** — 한 business fact가 두 durable store와
두 relay로 나가는 상태가 cutover에서 가장 위험하다. 두 relay로 나가는 상태가 cutover에서 가장 위험하다.
- 첫 cutover 범위는 **transport만** 교체(저장소는 기존 유지). storage migration은 shadow read → - 첫 cutover 범위는 **transport만** 교체(저장소는 기존 유지). storage migration은 shadow read →
authority switch → old backlog drain 순서로 별도 release. authority switch → old backlog drain 순서로 별도 release.
+9 -48
View File
@@ -17,24 +17,22 @@ stopsAcceptingNewWorkDuringShutdown
**Experimental**은 아직 그 증명이 끝나지 않은 어댑터다. **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. 기본 비활성 ### 1. 기본 비활성
```yaml 새 Experimental 어댑터는 자기 활성화 플래그를 가지고 기본값은 `false`다.
messaging.experimental.kafka-share: false
messaging.experimental.pulsar: false
messaging.experimental.nats: false
```
활성화하지 않으면 validator가 `MessagingCapabilityUnavailableException`을 던진다. 활성화하지 않으면 validator가 `MessagingCapabilityUnavailableException`을 던진다.
Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다. Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다.
### 2. Stable 모듈이 Experimental 모듈에 의존하지 않는다 ### 2. Stable 모듈이 Experimental 모듈에 의존하지 않는다
Gradle 의존 그래프로 강제된다. `messaging-spring-boot-starter`의 `allowed_dependencies`에 Gradle 의존 그래프로 강제된다. Experimental leaf는 `messaging-spring-boot-starter`의
`messaging-kafka-share-experimental`, `messaging-pulsar-experimental`, `allowed_dependencies`에 넣지 않는다.
`messaging-nats-experimental`, `messaging-spring-cloud-stream-bridge`가 **없다**.
`verifyCleanArchitectureDependencies`가 위반을 빌드 실패로 만든다. `verifyCleanArchitectureDependencies`가 위반을 빌드 실패로 만든다.
@@ -45,45 +43,8 @@ Experimental 어댑터는 브로커의 차이를 `MessagingCapabilities`로 표
### 4. 없는 기능을 광고하지 않는다 ### 4. 없는 기능을 광고하지 않는다
| 어댑터 | 광고하지 않는 것 | 이유 | Contract Suite로 증명하지 않은 capability는 `MessagingCapabilities`에서 `false`로 둔다.
|---|---|---| `false`인 capability를 요구하는 profile은 startup에서 실패한다. 조용히 약화되지 않는다.
| 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를 쓴다. 거기서만 실제로 강제되기 때문이다.
## 승격 조건 ## 승격 조건
+1 -2
View File
@@ -3,8 +3,7 @@
## 배포 전 체크 ## 배포 전 체크
```bash ```bash
./gradlew verifyCleanArchitectureDependencies --console=plain ./gradlew architectureCheck --console=plain
./gradlew verifyRuntimeModuleMembership --console=plain
./gradlew checkstyleMain --console=plain ./gradlew checkstyleMain --console=plain
``` ```
+4 -6
View File
@@ -107,13 +107,11 @@ message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째
broker의 최대 redelivery window보다 **길어야** 한다. broker의 최대 redelivery window보다 **길어야** 한다.
row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다. row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
## Debezium CDC 대안 ## CDC 대안
polling relay 대신 WAL을 읽는다. polling interval과 lease 경합이 사라지지만 relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는
인프라와 그 자체의 실패 모드가 추가된다. 곳이 없어 2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표). `messaging_outbox`의
`routing_key` 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다.
wire contract는 동일하다. `DebeziumOutboxEventRouter`가 polling relay와 같은 reserved header를
방출하므로 consumer는 어느 쪽이 발행했는지 구분할 수 없고, 전환은 배포 결정일 뿐 계약 변경이 아니다.
## Claim Check ## Claim Check
+25 -47
View File
@@ -4,10 +4,12 @@
여기 없는 조합은 지원되지 않는다. 여기 없는 조합은 지원되지 않는다.
> **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된 > **등급은 증거를 따른다.** `CompatibilityMatrix.Entry.hasLiveBrokerCertification()`은 선언된
> boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. RabbitMQ가 Stable에서 내려온 > boolean이 아니라 `CertifiedEvidence`가 가진 레인 증거에서 파생된다. 레인이 생겨 증거를 내면 등급은
> 이유가 이것이다 — 어댑터는 공유 contract 7개를 통과하고 `RabbitBrokerIT`가 실 컨테이너에서 정상 > 코드 수정 없이 따라 올라간다.
> 경로를 돌리지만, 이 저장소의 Stable 기준인 **장애 시나리오 증거**가 하나도 없다. 레인이 생겨
> 증거를 내면 등급은 코드 수정 없이 따라 올라간다. > **삭제된 어댑터.** 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이었다 — 표와 > Kafka 4.2/4.3을 선언했지만 fixture는 `apache/kafka:4.1.0`, lockfile client는 4.1.1이었다 — 표와
@@ -29,10 +31,7 @@
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 | | 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|---|---|---|---|---| |---|---|---|---|---|
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group은 Experimental | | Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group 미지원 |
| 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 없음(플랫폼이 대행), 기본 비활성 |
| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 | | Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 |
## Capability 매트릭스 ## Capability 매트릭스
@@ -40,27 +39,20 @@
`MessagingCapabilities`가 런타임에 선언하는 값이다. `false`인 기능을 요구하는 destination profile은 `MessagingCapabilities`가 런타임에 선언하는 값이다. `false`인 기능을 요구하는 destination profile은
**startup에서 실패**하며, 조용히 약화되지 않는다. **startup에서 실패**하며, 조용히 약화되지 않는다.
| Capability | Kafka | Kafka Share | RabbitMQ | Pulsar | NATS JS | | Capability | Kafka |
|---|---|---|---|---|---| |---|---|
| brokerAcknowledgement | O | O | O | O | O | | brokerAcknowledgement | O |
| replicationOrPersistenceEvidence | O | O | O | O | O | | replicationOrPersistenceEvidence | O |
| perMessageSettlement | O | O | O | O | O | | perMessageSettlement | O |
| batchSettlement | O | X | X | O | O | | batchSettlement | O |
| orderedStream | O | **X** | X | X | O | | orderedStream | O |
| keyedOrdering | O | **X** | X | Key_Shared만 | X | | keyedOrdering | O |
| replay | O | X | X | O | O | | replay | O |
| delayedDelivery | X | X | retry queue로 대행 | O | X | | delayedDelivery | X |
| brokerTransaction | O | X | X | 미승격 | X | | brokerTransaction | O |
| deduplicatedPublish | O | X | X | X | O | | deduplicatedPublish | O |
| nativeDeadLetter | X | X | O | O | **X** | | nativeDeadLetter | X |
| topologyManagement | O | X | O | O | O | | topologyManagement | 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를 직접 수행한다.
## 기능 등급 ## 기능 등급
@@ -73,8 +65,6 @@ NATS JetStream의 `nativeDeadLetter=X`도 마찬가지다. JetStream은 delivery
| Batch / Manual settlement / Pause·Resume / Delayed / Replay 요청 | M2 | | Batch / Manual settlement / Pause·Resume / Delayed / Replay 요청 | M2 |
| Broker transaction / partition / routing / subscription | M3 | | Broker transaction / partition / routing / subscription | M3 |
| Replay 실행 / Redrive / offset reset / purge / delete | M4 Admin | | Replay 실행 / Redrive / offset reset / purge / delete | M4 Admin |
| Kafka Share Group, Pulsar, NATS | Experimental |
| Spring Cloud Stream bridge | Optional |
## 무엇이 "Stable"을 증명하는가 ## 무엇이 "Stable"을 증명하는가
@@ -82,7 +72,7 @@ Stable 등급은 두 가지를 **모두** 통과해야 한다. `CompatibilityMat
### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개) ### 1. 공유 Contract Suite (`MessagingAdapterContract`, 7개)
Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로 Kafka가 7개 테스트를 변경 없이 통과한다. 결정적 하네스를 쓰므로
확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다. 확인 유실·settlement 유실 같은 장애를 요청 시점에 재현할 수 있다.
### 2. 실 브로커 인증 (Testcontainers) ### 2. 실 브로커 인증 (Testcontainers)
@@ -92,7 +82,6 @@ Kafka와 RabbitMQ가 동일한 7개 테스트를 변경 없이 통과한다. 결
| `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit | | `KafkaBrokerIT` | `acks=all`이 실제 replication 증거를 만든다 / 잘못된 토픽은 `REJECTED` / 발행-소비 왕복에서 identity 보존 및 contiguous commit |
| `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) | | `KafkaAmbiguityChaosIT` | 브로커를 `docker pause`로 멈춘 상태의 publish가 **`AMBIGUOUS`** 로 보고된다 (broker acceptance 없음, confirmation level `NONE`, 비-retryable) |
| `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 | | `KafkaBrokerCertificationIT` | 인증 레인. Toxiproxy를 broker 앞에 두고 connection cut / confirm 유실 / 지연 / settlement 유실을 각각 주입하고, 통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을 manifest에 쓴다 |
| `RabbitBrokerIT` | exchange가 confirm했는데 어떤 큐에도 바인딩되지 않은 publish가 **`REJECTED` + `UNROUTABLE`** 로 보고된다 |
| `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 | | `OutboxPostgresIT` | 롤백된 트랜잭션은 발행 가능한 행을 남기지 않는다 / `SKIP LOCKED` lease가 두 relay를 분리한다 / ambiguous 행이 같은 `messageId`로 재클레임된다 |
| `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 | | `InboxPostgresIT` | 재전달이 side effect를 두 번 적용하지 않는다 / 롤백은 예약도 되돌린다 |
@@ -137,7 +126,7 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
1. **Outbox `IN_FLIGHT` 고아 행** — lease 쿼리가 `PENDING`/`AMBIGUOUS`만 클레임 대상으로 봐서, 1. **Outbox `IN_FLIGHT` 고아 행** — lease 쿼리가 `PENDING`/`AMBIGUOUS`만 클레임 대상으로 봐서,
publish 도중 죽은 relay가 남긴 행이 lease 만료 후에도 영영 회수되지 않았다. publish 도중 죽은 relay가 남긴 행이 lease 만료 후에도 영영 회수되지 않았다.
2. **Rabbit confirm 경합** — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서 2. **Rabbit confirm 경합**(2026-09-25에 삭제된 Rabbit transport) — transport가 publish *후에* confirm을 등록해서, 연결 스레드에서
confirm이 먼저 도착하면 유실되고 호출자가 무한 대기했다. confirm이 먼저 도착하면 유실되고 호출자가 무한 대기했다.
둘 다 인메모리 double이 실제보다 관대해서 통과하고 있었다. 둘 다 인메모리 double이 실제보다 관대해서 통과하고 있었다.
@@ -154,21 +143,10 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
- DLQ publish 확인 전 source ACK - DLQ publish 확인 전 source ACK
## R1 compiler status ### Optional mapping utilities
`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
- `messaging-cloudevents`는 starter runtime에 자동 편입되지 않는 **opt-in mapping utility**다. - `messaging-cloudevents`는 starter runtime에 자동 편입되지 않는 **opt-in mapping utility**다.
내부 envelope와 CloudEvent 객체 사이의 제한된 profile mapping을 제공하지만 binary/structured 내부 envelope와 CloudEvent 객체 사이의 제한된 profile mapping을 제공하지만 binary/structured
CloudEvents wire mode 전체를 구현하거나 임의 CloudEvents producer와의 1.0 interoperability를 CloudEvents wire mode 전체를 구현하거나 임의 CloudEvents producer와의 1.0 interoperability를
인증하지 않는다. 인증하지 않는다.
- `messaging-spring-cloud-stream-bridge`는 현재 `ChannelSend` seam과 publish-evidence 판단을 제공하는 - `messaging-claim-check`도 starter에 편입되지 않는 opt-in utility다.
framework-neutral bridge contract다. Spring Cloud Stream `StreamBridge` dependency/auto-configuration은
제공하지 않으므로 shipped Spring Cloud Stream integration으로 분류하지 않는다.
@@ -12,7 +12,6 @@ ca-skeleton:
topology: REPLICA_SET topology: REPLICA_SET
production: true production: true
stable-api-strict: true stable-api-strict: true
consistency-default: PRIMARY_MAJORITY
server-selection-timeout: 3s server-selection-timeout: 3s
connect-timeout: 2s connect-timeout: 2s
socket-read-timeout: 5s socket-read-timeout: 5s
@@ -21,7 +20,5 @@ ca-skeleton:
pool-max-size: 40 pool-max-size: 40
pool-max-wait-time: 500ms pool-max-wait-time: 500ms
uuid-representation: STANDARD uuid-representation: STANDARD
decimal-representation: DECIMAL128
runtime-auto-create-indexes: false
tls-required: true tls-required: true
authentication-required: true authentication-required: true
+6 -4
View File
@@ -1,8 +1,9 @@
# Advanced — CSFLE and Queryable Encryption # Advanced — CSFLE and Queryable Encryption
**Capabilities:** `MongoCapability.CSFLE`, `MongoCapability.QUERYABLE_ENCRYPTION` **Capabilities:** `MongoCapability.CSFLE`, `MongoCapability.QUERYABLE_ENCRYPTION`
**Properties:** `ca-skeleton.persistence-mongo.advanced.csfle.enabled`, **Enablement:** library API, no configuration property. The service's own adapter constructs the
`ca-skeleton.persistence-mongo.advanced.queryable-encryption.enabled` entry point with a `MongoAdvancedCapabilityGuard` built from `MongoAdvancedCapabilityFlags` that
enables the capability; construction is refused otherwise.
**Status:** Advanced. **Status:** Advanced.
## Requirements ## Requirements
@@ -18,7 +19,8 @@
`MongoCsfleProfile` binds a collection to its `MongoCsfleFieldPolicy` list, a key vault `MongoCsfleProfile` binds a collection to its `MongoCsfleFieldPolicy` list, a key vault
`MongoCredentialReference` and the key vault namespace. `MongoCsfleClientFactory` builds the encrypted `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`: `MongoCsfleMode`:
@@ -87,5 +89,5 @@ an outage.
Per [ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md), promotion requires the 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 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. 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), **Capabilities:** `MongoCapability.SHARED_COLLECTION_TENANCY` (Advanced),
`MongoCapability.DATABASE_PER_TENANT` (Experimental) `MongoCapability.DATABASE_PER_TENANT` (Experimental)
**Properties:** `ca-skeleton.persistence-mongo.advanced.shared-collection-tenancy.enabled`, **Enablement:** library API, no configuration property. The service's own adapter constructs the
`ca-skeleton.persistence-mongo.advanced.database-per-tenant.enabled` 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 ## 1. Shared collection
Every tenant's documents live in one collection, discriminated by a tenant field. Every tenant's documents live in one collection, discriminated by a tenant field.
`MongoTenantContext` carries the tenant. `MongoTenantPredicateInjector` adds the tenant predicate to `MongoTenantContext` carries the tenant. `MongoTenantPredicateInjector` adds the tenant predicate to
every query, every atomic filter and the **first** aggregation stage. `TenantScopedMongoOperations` every query, every atomic filter and the **first** aggregation stage. The adopter's repository calls
is the entry point, so a caller cannot construct an unscoped operation by forgetting. the injector on every tenant-scoped path; there is no tenant-scoped operations facade in this leaf.
Three details are load-bearing: 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) ## 2. Database per tenant (Experimental)
`MongoTenantDatabaseResolver` maps a tenant to its database; `MongoTenantClientRegistry` holds the `MongoTenantClientRegistry` holds one client per tenant under a cap with idle eviction; mapping a
clients. 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 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 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 | | 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. | | 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. | | 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. | | 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 # Advanced — Sharding
**Capability:** `MongoCapability.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. **Status:** Advanced. Reshard orchestration remains Experimental.
## Requirements ## 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 ## 3. Consistency profiles
`MongoConsistencyProfile` names the read/write concern pair; `MongoConsistencyRegistry` binds a `MongoConsistencyProfile` names the read/write concern pair; `MongoConsistencyRegistry` binds a
profile to an operation or collection, and `MongoConsistencyBinder` / profile to an operation or collection, and `MongoConsistencyBinder` applies it at execution.
`ReactiveMongoConsistencyBinder` apply it at execution.
| Profile | Meaning | Use for | | Profile | Meaning | Use for |
|---|---|---| |---|---|---|
@@ -47,17 +46,14 @@ without a registered profile is rejected rather than defaulting.
## 4. Causal sessions ## 4. Causal sessions
`MongoCausalSessionContext` plus `SpringMongoCausalSessionExecutor` / `MongoCausalSessionContext` plus `SpringMongoCausalSessionExecutor` carry the cluster time and
`ReactiveMongoCausalSessionExecutor` carry the cluster time and operation time between operations, so operation time between operations, so
"write then read" returns the write even when the read lands on a different node. Without a causal "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. 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 ## 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 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 `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 `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 `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 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. 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 ## 4. Identity
`DomainDocumentId` and `MongoIdRepresentation` fix how a domain identifier becomes `_id`. Pick the `DomainDocumentId` is written to `_id` as a BSON string by `DomainIdWriteConverter`. Any other
representation once per collection and record it in the manifest: 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. - `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 - `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 `MongoCollectionProfileRegistry` binds a `CollectionProfileName` to its consistency profile, budget
and allowlist. A collection that is not registered cannot be reached through 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. unreviewed collection from appearing in production by accident.
## 8. What to write down before the first insert ## 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 `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. pipeline whose shape should be reviewed.
## 6. Reactive execution and cursors ## 6. Geospatial
`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
`MongoGeoQuery` + `MongoGeoPoint` + `MongoGeoDistance` over a `2dsphere` index. Distances are metres `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 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; from the equator. `SpringMongoGeospatialOperations` is the Spring Data binding;
`MongoGeospatialOperations` is the port. `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 When a registered operation genuinely needs something outside the Stable API, it goes through
`MongoNativeCapabilityGateway` (`PolicyAwareMongoNativeGateway`), never through the driver directly. `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. 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 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: and said nothing about the rest, so edges outside the design's DAG existed and passed, among them
`reactive → imperative`, `reactive → query`, `transaction → reactive` and `geo → imperative`. They `geo → imperative`. They are declared in the matrix now rather than removed — each is a real coupling the code relies on, and
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. the point of recording them is that the next one is a decision instead of an accident.
## 2. Package mapping ## 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-core-api` | `…outbound.mongo.api` (+ `.capability`, `.consistency`, `.error`, `.mapping`, `.observation`, `.profile`, `.schema`) |
| `mongodb-spring-data` | `…outbound.mongo.mapping` (+ `.type`), `…outbound.mongo.failure` | | `mongodb-spring-data` | `…outbound.mongo.mapping` (+ `.type`), `…outbound.mongo.failure` |
| `mongodb-imperative` | `…outbound.mongo.imperative` (+ `.atomic`, `.bulk`, `.revision`) | | `mongodb-imperative` | `…outbound.mongo.imperative` (+ `.atomic`, `.bulk`, `.revision`) |
| `mongodb-reactive` | `…outbound.mongo.reactive` (+ `.cursor`) |
| `mongodb-query` | `…outbound.mongo.query` (+ `.budget`, `.pagination`) | | `mongodb-query` | `…outbound.mongo.query` (+ `.budget`, `.pagination`) |
| `mongodb-aggregation` | `…outbound.mongo.aggregation` | | `mongodb-aggregation` | `…outbound.mongo.aggregation` |
| `mongodb-transaction` | `…outbound.mongo.transaction` (+ `.retry`, `.session`) | | `mongodb-transaction` | `…outbound.mongo.transaction` (+ `.retry`, `.session`) |
| `mongodb-index-schema` | `…outbound.mongo.schema` (+ `.index`, `.manifest`, `.model`, `.ttl`, `.validation`) | | `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-geospatial` | `…outbound.mongo.geo` |
| `mongodb-migration-core` | `…outbound.mongo.migration` | | `mongodb-migration-core` | `…outbound.mongo.migration` |
| `mongodb-migration-flamingock` | `…outbound.mongo.migration.flamingock` | | `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 | | Design module | Repository package |
|---|---| |---|---|
| `mongodb-sharding` | `…outbound.mongo.advanced.sharding` (+ `.admin` for the D4 shard plane) | | `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-csfle` | `…outbound.mongo.advanced.encryption.csfle` |
| `mongodb-queryable-encryption` | `…outbound.mongo.advanced.encryption.qe` | | `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-shared` | `…outbound.mongo.advanced.tenancy.shared` |
| `mongodb-tenancy-database` | `…outbound.mongo.advanced.tenancy.database` | | `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-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 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 (`stableNeverDependsOnAdvanced`). Every Advanced entry point takes a `MongoAdvancedCapabilityGuard`
`MongoAdvancedCapabilityFlags` to have the matching capability enabled and refuses construction and refuses construction unless its `MongoAdvancedCapabilityFlags` enable the matching capability.
otherwise. Being on the classpath is not being enabled. 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 ## 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 - Registered operation names and manifests for query, aggregation and index; no free-form JSON query
and no unbounded pipeline. and no unbounded pipeline.
- Keyset pagination with an authenticated cursor and a unique tie-breaker requirement. - 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. - 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. - 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. - 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 - The Stable release gate's evidence categories. The Advanced promotion requirements
actual-topology evidence. (actual-topology evidence) are a review obligation in ADR-MONGO-ADV-001; no class checks them.
## 5. Verification ## 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: `MongoStartupValidator` runs at context refresh, before the first request:
1. `MongoTopologyProbe` reports the actual `MongoTopology`. 1. `MongoTopologyProbe` reports the actual `MongoTopology` and its `MongoCapabilitySet`.
2. Each declared `MongoTopologyRequirement` is checked against it — a transaction, causal-session or 2. Every profile's declared topology must match it, and a production profile on `STANDALONE` fails.
change-stream requirement fails closed on `STANDALONE`. 3. With `platform.transactions=true`, the probe must report `TRANSACTION` as `STABLE`; on
3. `MongoSecurityProfileValidator` checks credentials and TLS. `STANDALONE` it does not, so startup fails.
4. `MongoCapabilitySupport` checks declared capabilities against the server version, with 4. `MongoSecurityProfileValidator` checks credentials and TLS, and that the admin credential differs
`MongoSupportLevel` distinguishing `STABLE` / `ADVANCED` / `EXPERIMENTAL` / `UNSUPPORTED`. from the runtime one; the `MongoSchemaVersionRange` must not be inverted.
5. `MongoPlatformHealthIndicator` reports the outcome for the readiness probe. 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 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. 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 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. | | 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. | | 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. | | Micrometer | 1.16.0 | Driver-native observability. |
| Testcontainers | 2.0.2 | Replica-set, failover, migration and compatibility lanes. | | 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 | | 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. | | 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. | | 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 ## 4. Stable API and client generations
| Plane | Stable API | Purpose | | Plane | Stable API | Purpose |
|---|---|---| |---|---|---|
| D1 Standard document persistence | V1, `apiStrict=true` | Repositories, typed queries, atomic updates, optimistic revision. | | 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. | | D2 Advanced document operations | V1, `apiStrict=true` | `MongoTemplate`, transactions, bulk, aggregation, keyset cursors. |
| D3 Explicit Mongo capability | Not strict | Native BSON, time series, search/vector, CSFLE/QE, shard-aware operations — each behind a registered capability. | | 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. | | 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 → D3 is not a raw-client escape. Every call passes capability registration → database profile →
@@ -83,9 +82,10 @@ feature request:
| Tier | Capabilities | Enablement | | 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`. | | 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`. |
| 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`. | | 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. |
| 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). | | 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 Search, vector search, time series and GridFS compatibility were interfaces with no implementation
capability; the table above is its prose form. and were removed on 2026-09-25 (`docs/capability-status.md`).
@@ -4,6 +4,13 @@
Accepted (2026-08-15). NTF-018 대응. 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 모델이 **두 개** 있다. 같은 저장소에 notification 모델이 **두 개** 있다.
+6 -142
View File
@@ -1,6 +1,8 @@
# NTF-022 — public type surface of the notification platform. # 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 # Every top-level public type under the platform packages. Growth is a reviewed change.
# change: ./gradlew updateNotificationApiSurface -PapproveNotificationApiChange # Update only after review with:
# ./gradlew :adapter:outbound:notification:updateNotificationApiSurface -PapproveNotificationApiSurfaceChange
# types: 416
dev.caskeleton.adapter.outbound.notification.NotificationConfig dev.caskeleton.adapter.outbound.notification.NotificationConfig
dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings
dev.caskeleton.adapter.outbound.notification.core.FailOpenNotificationProvider 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.CredentialProbe
dev.caskeleton.adapter.outbound.notification.platform.dispatch.CredentialValidationException dev.caskeleton.adapter.outbound.notification.platform.dispatch.CredentialValidationException
dev.caskeleton.adapter.outbound.notification.platform.dispatch.JacksonRoutingPlanCodec 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.LoggingInboxSignalPublisher
dev.caskeleton.adapter.outbound.notification.platform.dispatch.MapTemplateRendererRegistry dev.caskeleton.adapter.outbound.notification.platform.dispatch.MapTemplateRendererRegistry
dev.caskeleton.adapter.outbound.notification.platform.dispatch.NotificationBackgroundWorkers 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.WebPushProviderProperties
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushReceiptCapability dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushReceiptCapability
dev.caskeleton.adapter.outbound.notification.platform.provider.webpush.WebPushRequestMapper 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.AesGcmCallbackPayloadProtection
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmContactPointProtector dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmContactPointProtector
dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmNotificationPayloadProtection 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.SlackClient
dev.caskeleton.adapter.outbound.notification.slack.webhook.SlackNotificationAdapterConfig dev.caskeleton.adapter.outbound.notification.slack.webhook.SlackNotificationAdapterConfig
dev.caskeleton.adapter.outbound.notification.slack.webhook.SlackWebhookProvider 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.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.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.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.AdminAccessDeniedException
dev.caskeleton.application.notification.platform.admin.AdminActor dev.caskeleton.application.notification.platform.admin.AdminActor
dev.caskeleton.application.notification.platform.admin.AdminAuthorizationGuard 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.NormalizedProviderEvent
dev.caskeleton.application.notification.platform.api.NotificationAcceptance dev.caskeleton.application.notification.platform.api.NotificationAcceptance
dev.caskeleton.application.notification.platform.api.NotificationId 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.NotificationPlan
dev.caskeleton.application.notification.platform.api.NotificationReceipt dev.caskeleton.application.notification.platform.api.NotificationReceipt
dev.caskeleton.application.notification.platform.api.NotificationSnapshot 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.EvidenceLevel
dev.caskeleton.application.notification.platform.api.delivery.RecipientDeliveryState dev.caskeleton.application.notification.platform.api.delivery.RecipientDeliveryState
dev.caskeleton.application.notification.platform.api.delivery.SubmissionOutcome 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.AttachmentIntegrityException
dev.caskeleton.application.notification.platform.api.error.AttachmentUnavailableException 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.CallbackValidationException
dev.caskeleton.application.notification.platform.api.error.FailureCategory dev.caskeleton.application.notification.platform.api.error.FailureCategory
dev.caskeleton.application.notification.platform.api.error.IdempotencyConflictException 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.NotificationException
dev.caskeleton.application.notification.platform.api.error.NotificationExpiredException dev.caskeleton.application.notification.platform.api.error.NotificationExpiredException
dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode
dev.caskeleton.application.notification.platform.api.error.NotificationFailureDescriptor 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.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.ProviderConfigurationException
dev.caskeleton.application.notification.platform.api.error.ProviderPayloadLimitException 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.ProviderUnavailableException
dev.caskeleton.application.notification.platform.api.error.ReconciliationException
dev.caskeleton.application.notification.platform.api.error.TemplateNotFoundException dev.caskeleton.application.notification.platform.api.error.TemplateNotFoundException
dev.caskeleton.application.notification.platform.api.error.TemplateRenderingException dev.caskeleton.application.notification.platform.api.error.TemplateRenderingException
dev.caskeleton.application.notification.platform.api.error.TemplateVariableValidationException 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.PhoneNumber
dev.caskeleton.application.notification.platform.contact.WebPushSubscriptionValue dev.caskeleton.application.notification.platform.contact.WebPushSubscriptionValue
dev.caskeleton.application.notification.platform.dispatch.AcceptNotificationApplicationUseCase 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.AttachmentIntegrityGuard
dev.caskeleton.application.notification.platform.dispatch.CancelNotificationApplicationUseCase dev.caskeleton.application.notification.platform.dispatch.CancelNotificationApplicationUseCase
dev.caskeleton.application.notification.platform.dispatch.CanonicalNotificationPlanEncoder 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.DispatchPipeline
dev.caskeleton.application.notification.platform.dispatch.DuplicateIdempotencyKeyException dev.caskeleton.application.notification.platform.dispatch.DuplicateIdempotencyKeyException
dev.caskeleton.application.notification.platform.dispatch.GetNotificationApplicationUseCase 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.MessageDigestPort
dev.caskeleton.application.notification.platform.dispatch.NotificationDispatchService dev.caskeleton.application.notification.platform.dispatch.NotificationDispatchService
dev.caskeleton.application.notification.platform.dispatch.NotificationIdGeneratorPort 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.SyntheticEventFingerprint
dev.caskeleton.application.notification.platform.dispatch.TemplateRendererRegistry dev.caskeleton.application.notification.platform.dispatch.TemplateRendererRegistry
dev.caskeleton.application.notification.platform.dispatch.TenantContextPort 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.CreateInboxItemCommand
dev.caskeleton.application.notification.platform.inbox.InboxContentCodecPort dev.caskeleton.application.notification.platform.inbox.InboxContentCodecPort
dev.caskeleton.application.notification.platform.inbox.InboxCursor 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.ReconciliationResult
dev.caskeleton.application.notification.platform.provider.ResolvedAttachment dev.caskeleton.application.notification.platform.provider.ResolvedAttachment
dev.caskeleton.application.notification.platform.provider.TraceContext 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.AccessContext
dev.caskeleton.application.notification.platform.security.ContactPointProtector dev.caskeleton.application.notification.platform.security.ContactPointProtector
dev.caskeleton.application.notification.platform.security.NotificationPayloadProtection dev.caskeleton.application.notification.platform.security.NotificationPayloadProtection
dev.caskeleton.application.notification.platform.security.NotificationPayloadUnreadableException 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.ProtectedContactPoint
dev.caskeleton.application.notification.platform.security.SafeDiagnosticContext
dev.caskeleton.application.notification.platform.security.SecretKeyMaterial dev.caskeleton.application.notification.platform.security.SecretKeyMaterial
dev.caskeleton.application.notification.platform.security.SecretMaterialProvider dev.caskeleton.application.notification.platform.security.SecretMaterialProvider
dev.caskeleton.application.notification.platform.security.SecretPurpose 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.NotificationTemplateRenderer
dev.caskeleton.application.notification.platform.template.NotificationTemplateVersion dev.caskeleton.application.notification.platform.template.NotificationTemplateVersion
dev.caskeleton.application.notification.platform.template.RenderCommand 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.TemplateVariableValidator
dev.caskeleton.application.notification.platform.template.TemplateVersionConflictException dev.caskeleton.application.notification.platform.template.TemplateVersionConflictException
dev.caskeleton.application.notification.platform.template.VariableSchema 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 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 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 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. code signs a cursor with (GQL-INT-003). Adding a second would make the pattern a habit.
## Consequence ## Consequence
+12 -6
View File
@@ -1,20 +1,25 @@
# Configuration reference # Configuration reference
The notification delivery platform binds under `ca-skeleton.notification.platform`. The tree lives in 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 `src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`,
an inline default so a deployment that leaves the platform off supplies nothing. 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`, 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 `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 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 variable names from Boot's relaxed binding. `NotificationEnvironmentRegistryTest`
when this page, the YAML tree and `docs/registries/env-keys.yaml` disagree. (`:composition:notification-platform:test`) now fails when the shipped YAML and
`docs/registries/env-keys.yaml` disagree.
## Master switch ## Master switch
| Property | Environment variable | Default | Meaning | | 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 | | `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch |
## 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.enabled` | `APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED` | `false` | boolean |
| `callbacks.max-body-bytes` | `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES` | `65508` | 1..65508 | | `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 | | `callbacks.trusted-proxies` | `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` | *(empty)* | CSV of peer addresses |
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다. 여러 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.sender-identity` | verified SES From identity |
| `ses.access-key-id` | AWS access key id; identifier only, not secret material | | `ses.access-key-id` | AWS access key id; identifier only, not secret material |
| `ses.configuration-set` | optional SES configuration-set name | | `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 | | `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 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", "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", "continue-on-error. So the strongest claim in the document rested on the weakest evidence in",
"the pipeline, and nothing connected the two.", "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." "test classes that exist, and refuses a grade whose claims are not all satisfied."
], ],
"claims": { "claims": {
+4 -6
View File
@@ -37,11 +37,9 @@ R1 public type 100개를 어떻게 할 것인지 다루지 않았다. 그래서
문서 어디에도 답이 없었다. 문서 어디에도 답이 없었다.
- **canonical은 `..notification.platform..`이다.** NOTIF-ADR-005가 근거와 함께 정한다. - **canonical은 `..notification.platform..`이다.** NOTIF-ADR-005가 근거와 함께 정한다.
- **application R1 public contract는 남지만 새 production consumer를 받지 않는다.** 삭제 계획은 - **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은
별개이며, R0 삭제와 함께 사라지지 않는다. 단순 알림 포트 `NotificationPort`·`Notification`·`NotificationChannel`뿐이다.
- R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의 - R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의
`catalog/`, `provider/`, `template/` 실험 구현은 제거했다. 실제 runtime은 `catalog/`, `provider/`, `template/` 실험 구현도 제거했다. 실제 runtime은
`dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다. `dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
- **전수 분류표는 `docs/notification/module-mapping.md`에 있다** (replace / bridge / retain / delete). - 삭제 목록과 마지막 커밋은 `docs/capability-status.md`의 「제거된 코드」 표에 있다.
- **두 namespace 간 production dependency는 0건이며 ArchUnit이 강제한다.** 변환이 필요하면
`dev.caskeleton.application.notification.compatibility.r1` 한 곳에만 둔다.
+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-policy` | `application-core` | `…platform.policy` |
| `notification-provider-spi` | `application-core` | `…platform.provider` | | `notification-provider-spi` | `application-core` | `…platform.provider` |
| `notification-callback-api` | `application-core` | `…platform.callback` | | `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-inbox-api` | `application-core` | `…platform.inbox` |
| `notification-admin-api` | `application-core` | `…platform.admin` | | `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-observability` (ports) | `application-core` | `…platform.observation` |
| `notification-dispatch-runtime` | `adapter:outbound:notification` | `dev.caskeleton.adapter.outbound.notification.platform.dispatch` | | `notification-dispatch-runtime` | `adapter:outbound:notification` | `dev.caskeleton.adapter.outbound.notification.platform.dispatch` |
| `notification-security` (AES-GCM/HMAC impl) | `adapter:outbound:notification` | `…platform.security` | | `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-webhook-extension` | `adapter:outbound:notification` | `…platform.provider.webhook` |
| `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` | | `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` |
| `notification-admin-runtime` | `adapter:outbound:notification` | `…platform.admin` | | `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-spring-boot-starter` | `adapter:outbound:notification` | `…platform.autoconfigure` |
| `notification-persistence-jpa` | `adapter:outbound:persistence-jpa` | `dev.caskeleton.adapter.outbound.persistence.notification.platform` | | `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-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-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.callback` |
| `notification-callback-webflux` | `adapter:inbound:web` | `…callback.reactive` | | `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` | | `notification-testkit` | test source sets of the owning leaves | `…platform.testkit` |
## Dependency-direction consequences ## Dependency-direction consequences
@@ -66,9 +62,11 @@ by the leaf DAG that the registry already enforces:
```text ```text
application-core (all *-api, provider SPI, policy, callback contracts) application-core (all *-api, provider SPI, policy, callback contracts)
↑ ↑ ↑ ↑ ↑ ↑
adapter:outbound:notification adapter:outbound:persistence-jpa adapter:inbound:web adapter:outbound:notification adapter:outbound:persistence-jpa adapter:inbound:web-notification
↑ ↑ ↑ ↑ ↑ (→ adapter:inbound:web)
app-bootstrap └──────────── composition:notification-platform ────┘
↑
app-bootstrap (one line)
``` ```
Two plan edges cannot be expressed as project edges in this repository, and are replaced by ports: 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` 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. 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 NOTIF-ADR-005 made `..notification.platform..` canonical. The R1 types directly under
without new consumers. The ADR owns the rule; this table owns the list, so the two do not drift `dev.caskeleton.application.notification` had no production consumer and were removed on
apart by being written twice. 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`,
`NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER` in `ApplicationBoundaryArchitectureTest` enforces the `NotificationChannel`. The removed types and their last commit are listed in
boundary: production dependencies between the two namespaces are zero, and the only permitted `docs/capability-status.md` under "제거된 코드".
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.
+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 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. credentials, unsubscribe tokens, attachment URLs, raw callback payloads and raw provider request ids.
Two mechanisms enforce this rather than convention: `CardinalityGuard` enforces this for metrics rather than convention: it validates every metric tag
against a closed allowlist.
- `CardinalityGuard` validates every metric tag against a closed allowlist.
- `SafeDiagnosticContext` rejects any structured-diagnostic field outside its allowlist.
An allowlist rather than a denylist, because the failure mode of a denylist is that the one field 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. 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 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 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 `NotificationEvidenceVerifierTest` (in `:adapter:outbound:notification:test`) refuses a grade whose
exists. Raising a grade means adding the artifact first. 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 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 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 | | Provider family | Dispatch assembler in shipped composition | Callback assembler | Current use |
|---|---|---|---| |---|---|---|---|
| SMTP | **yes** | no | EMAIL dispatch reference family | | 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 | | Twilio | no | no | contract implementation / extension wiring |
| FCM | no | no | contract implementation / extension wiring | | FCM | no | no | contract implementation / extension wiring |
| APNs | 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 env: APP_OBJECT_STORAGE_LEGACY_PATH_STYLE_ACCESS
- field: legacy.auto-create-bucket - field: legacy.auto-create-bucket
env: APP_OBJECT_STORAGE_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 - field: scan-maintenance.enabled
env: APP_OBJECT_STORAGE_SCAN_MAINTENANCE_ENABLED env: APP_OBJECT_STORAGE_SCAN_MAINTENANCE_ENABLED
+1 -1
View File
@@ -1,6 +1,6 @@
# Command policy # 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 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. 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 ## 1. Command metadata diff
Run the catalog drift check against the new server. Every command the server reports must be Compare `COMMAND DOCS` / `COMMAND INFO` from the new server with the policy by hand: every command
classified in `src/adapter/outbound/cache-redis/src/main/resources/redis-sdk/redis-command-policy.yml`. 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 *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 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 ## 2. ACL regression
+84 -707
View File
@@ -1,7 +1,7 @@
# Registry: Env Keys # Registry: Env Keys
# Schema owner: feature-contract-registry-governance # Schema owner: feature-contract-registry-governance
# Owner branch: feature-env-driven-runtime-configuration # Owner branch: feature-env-driven-runtime-configuration
# Last updated: 2026-07-28 # Last updated: 2026-09-25
# #
# Conventions: # Conventions:
# - Application-owned env uses `APP_` prefix, fully unified (D2, 2026-06-05): # - 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 required_test: rate-limit-contract:cleanup-grace-bounded
- name: APP_IDEMPOTENCY_TTL - name: APP_IDEMPOTENCY_TTL
# source: feature-rate-limit-idempotency-contract 2026-05-22 # ca-skeleton.capabilities.idempotency.replay-ttl: how long a completed response stays
# "idempotency TTL default = 24h. long-running use case는 use case 선언으로 72h까지 override 가능" # replayable. One value for every provider; IdempotencySettings refuses more than 72h at startup.
type: duration type: duration
default: 24h default: 24h
allowed_values: null allowed_values: null
@@ -1617,17 +1617,21 @@ env_keys:
required_test: idempotency-contract:ttl-applied required_test: idempotency-contract:ttl-applied
- name: APP_IDEMPOTENCY_PROVIDER - name: APP_IDEMPOTENCY_PROVIDER
# postgresql selects the owner-safe V2 store on the primary data source. Provider selection is # ca-skeleton.capabilities.idempotency.provider. redis and postgresql each contribute only the
# explicit and disabled by default; no implementation wins merely by being on the classpath. # 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 type: enum
default: disabled default: disabled
allowed_values: [disabled, jdbc, redis, postgresql] allowed_values: [disabled, redis, postgresql]
classification: public-config classification: public-config
required: false required: false
reload_policy: restart-only reload_policy: restart-only
owner_branch: redis-production-capability-completion owner_branch: redis-production-capability-completion
validation: enum_strict validation: enum_strict
compatibility_impact: additive compatibility_impact: breaking
required_test: redis-idempotency-contract:provider-exclusive required_test: redis-idempotency-contract:provider-exclusive
- name: APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET - name: APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET
@@ -1756,14 +1760,16 @@ env_keys:
required_test: redis-cache:canonical-cache-role-composition required_test: redis-cache:canonical-cache-role-composition
- name: APP_REDIS_ENABLED - 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, # 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 # 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 property: app.redis.enabled
owner_module: app-bootstrap owner_module: adapter-outbound-cache-redis
type: boolean type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -1772,7 +1778,7 @@ env_keys:
owner_branch: redis-optionality-and-composition owner_branch: redis-optionality-and-composition
validation: boolean_strict validation: boolean_strict
compatibility_impact: behavior-change 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 - name: APP_CACHE_REDIS_POSITIVE_HARD_TTL
@@ -1879,52 +1885,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated 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 - name: APP_REDIS_BLOCKING_MAX_CONNECTIONS
property: app.redis.blocking.max-connections property: app.redis.blocking.max-connections
owner_module: adapter-outbound-redis-runtime owner_module: adapter-outbound-redis-runtime
@@ -1956,171 +1916,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated 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 - name: APP_REDIS_MODE
# standalone | sentinel | cluster. # standalone | sentinel | cluster.
property: app.redis.mode property: app.redis.mode
@@ -2198,67 +1993,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated 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 - name: APP_REDIS_TIMEOUT_BATCH
property: app.redis.timeout.batch property: app.redis.timeout.batch
owner_module: adapter-outbound-redis-runtime owner_module: adapter-outbound-redis-runtime
@@ -2274,21 +2008,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated 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 - name: APP_REDIS_TIMEOUT_FAST
# Single-key command profile; above 5s produces a startup warning. # Single-key command profile; above 5s produces a startup warning.
property: app.redis.timeout.fast property: app.redis.timeout.fast
@@ -2406,21 +2125,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates 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 - name: APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_COMMANDS
property: app.redis.capacity.maximum-in-flight-commands property: app.redis.capacity.maximum-in-flight-commands
owner_module: adapter-outbound-cache-redis owner_module: adapter-outbound-cache-redis
@@ -2452,21 +2156,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-runtime:script-lane-physical-connections-bounded 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 - 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. # 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 property: app.redis.capacity.reject-when-disconnected
@@ -2514,6 +2203,7 @@ env_keys:
required_test: redis-sdk:runtime-composition-binds-and-validates required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_LIFECYCLE_ACQUIRE_TIMEOUT - 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 property: app.redis.lifecycle.acquire-timeout
owner_module: adapter-outbound-cache-redis owner_module: adapter-outbound-cache-redis
type: duration type: duration
@@ -2604,21 +2294,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates 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 - name: APP_REDIS_PUBSUB_BUFFER_CAPACITY
property: app.redis.pubsub.buffer-capacity property: app.redis.pubsub.buffer-capacity
owner_module: adapter-outbound-cache-redis owner_module: adapter-outbound-cache-redis
@@ -2634,22 +2309,6 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates 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 - name: APP_REDIS_SENTINEL_CREDENTIAL_REFERENCE
property: app.redis.sentinel.credential-reference property: app.redis.sentinel.credential-reference
owner_module: adapter-outbound-cache-redis owner_module: adapter-outbound-cache-redis
@@ -3264,7 +2923,8 @@ env_keys:
# (app.messaging.broker=<brokerId>); blank = messaging disabled. Replaces the former # (app.messaging.broker=<brokerId>); blank = messaging disabled. Replaces the former
# Kafka-binary APP_MESSAGING_KAFKA_ENABLED. Adding a broker is new files only. # Kafka-binary APP_MESSAGING_KAFKA_ENABLED. Adding a broker is new files only.
type: string 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 allowed_values: null
classification: public-config classification: public-config
required: false required: false
@@ -3292,6 +2952,8 @@ env_keys:
- name: APP_MESSAGING_KAFKA_BROKERS - name: APP_MESSAGING_KAFKA_BROKERS
# source: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter" # source: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter"
# (broker 활성화 시 endpoint 필요) # (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 type: csv_list
default: null default: null
allowed_values: null allowed_values: null
@@ -3331,90 +2993,9 @@ env_keys:
compatibility_impact: behavior-change compatibility_impact: behavior-change
required_test: adapter-contract:notification-email-provider-selection 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.*) === # === 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 # 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 # 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 # 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. # HttpClientPlatformEnvManifestTest, and an APP_HTTPCLIENT_ variable with no field fails startup.
- name: APP_HTTPCLIENT_ENABLED - 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 # 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. # gateway exists, and a malformed HTTP client setting cannot fail this deployment's startup.
type: boolean type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -3451,16 +3035,15 @@ env_keys:
required_test: httpclient-platform:off-state-zero-side-effects-and-env-manifest-parity required_test: httpclient-platform:off-state-zero-side-effects-and-env-manifest-parity
# === Fileserver HTTP platform (app.fileserver-platform.*) === # === 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 - 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. # binds it is not processed, so no bean, route, thread, schema check or filesystem call exists.
type: boolean type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -3948,7 +3531,7 @@ env_keys:
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
- name: APP_FILESERVER_PLATFORM_ADMIN_ENABLED - 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. # enabling it alone now does nothing instead of half-building a bean graph.
type: boolean type: boolean
default: false default: false
@@ -4042,7 +3625,7 @@ env_keys:
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
- name: APP_FILESERVER_PLATFORM_TUS_ENABLED - 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 type: boolean
default: false default: false
allowed_values: [true, false] allowed_values: [true, false]
@@ -4055,7 +3638,7 @@ env_keys:
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
- name: APP_FILESERVER_PLATFORM_HTTPBIS_DRAFT12_ENABLED - 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 type: boolean
default: false default: false
allowed_values: [true, false] allowed_values: [true, false]
@@ -4197,12 +3780,14 @@ env_keys:
# supplies nothing. Reference: docs/notification/configuration.md. # supplies nothing. Reference: docs/notification/configuration.md.
- name: APP_PERSISTENCE_JPA_ENABLED - name: APP_PERSISTENCE_JPA_ENABLED
# source: five-adapter-runtime-remediation §5.1 — master switch for relational persistence. # source: five-adapter-runtime-remediation §5.1 — switch for relational persistence, shipped by
# false means no DataSource, no entity scan, no repositories, no Hibernate, no Flyway and no DB # the persistence-jpa module itself (config/module-defaults/persistence-jpa.yml). The module is
# health contributor; the old app.jpa-platform.enabled gated three add-on beans while reading # selected by one build line and is on while present; false switches off this module's beans
# like this one and defaulting to on. # (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 type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -4287,9 +3872,12 @@ env_keys:
required_test: jpa-contract:hibernate-runtime-settings required_test: jpa-contract:hibernate-runtime-settings
- name: APP_PERSISTENCE_MONGO_ENABLED - 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 type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -4329,10 +3917,13 @@ env_keys:
required_test: adapter-contract:persistence-mongo-connection-source required_test: adapter-contract:persistence-mongo-connection-source
- name: APP_MESSAGING_ENABLED - 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. # APP_MESSAGING_BROKER selects which transport and is no longer the de-facto switch.
type: boolean type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -4347,10 +3938,13 @@ env_keys:
# decision and these rows do not imply runtime membership. # decision and these rows do not imply runtime membership.
- name: APP_WEBSOCKET_ENABLED - 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 property: app.websocket.enabled
owner_module: adapter-inbound-websocket owner_module: adapter-inbound-websocket
type: boolean type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -4402,249 +3996,14 @@ env_keys:
compatibility_impact: behavior-change compatibility_impact: behavior-change
required_test: websocket-contract:canonical-property-namespace 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 - 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. # false publishes no /graphql route, including the one Spring GraphQL would publish by itself.
type: boolean type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -4864,9 +4223,12 @@ env_keys:
compatibility_impact: behavior-change compatibility_impact: behavior-change
required_test: adapter-contract:outbox-relay-dependency required_test: adapter-contract:outbox-relay-dependency
- name: APP_NOTIFICATION_PLATFORM_ENABLED - 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 type: boolean
default: false default: true
allowed_values: [true, false] allowed_values: [true, false]
classification: public-config classification: public-config
required: false required: false
@@ -5288,8 +4650,23 @@ env_keys:
compatibility_impact: additive compatibility_impact: additive
required_test: adapter-contract:notification-ses-provider-assembled 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 - 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 type: boolean
default: false default: false
allowed_values: [true, false] allowed_values: [true, false]
+4 -3
View File
@@ -348,12 +348,13 @@ metrics:
- name: event_type - name: event_type
cardinality_limit: 50 cardinality_limit: 50
- name: outcome - name: outcome
cardinality_limit: 4 cardinality_limit: 5
allowed_values: [PUBLISHED, FAILED, DEAD, IN_FLIGHT] # 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 percentiles: null
histogram_buckets: null histogram_buckets: null
alert_severity_thresholds: 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 owner_branch: feature-domain-event-outbox-contract
log_field_mapping: [event_type, outcome, event_id] log_field_mapping: [event_type, outcome, event_id]
compatibility_impact: additive 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 태스크 없음 - 대응하는 Test 태스크 없음
- 공통 스키마 validator 없음 - 공통 스키마 validator 없음
따라서 `config/messaging/readiness-cards.yaml`의 카드는 `verifyMessagingContracts`와 따라서 `config/messaging/readiness-cards.yaml`의 카드는 모두 `maturity: not-implemented`다.
`verifyMessagingJsonSchemaV1` 두 개를 제외하면 모두 `maturity: not-implemented`다. 유일하게 `implemented-candidate`였던 `json-schema-envelope.v1`은 그 구현(adapter messaging의
`JsonSchemaIntegrationEventEncoder`와 `verifyMessagingJsonSchemaV1`)을 2026-09-25에 삭제하면서
`not-implemented`로 내렸다. 남은 evidence producer는 `verifyMessagingContracts` 하나다.
## 왜 Gradle 태스크를 미리 만들어 두지 않는가 ## 왜 Gradle 태스크를 미리 만들어 두지 않는가
@@ -40,8 +42,8 @@ verifyMessagingTargetBindingPreflight
1. 각 시나리오를 실제로 실행하는 Test 태스크. 1. 각 시나리오를 실제로 실행하는 Test 태스크.
2. 그 실행 결과(JUnit XML)에서 payload-free manifest를 만드는 producer. 2. 그 실행 결과(JUnit XML)에서 payload-free manifest를 만드는 producer.
3. `config/messaging/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를 3. `config/messaging/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를
검증하는 finalizer. 검증하는 단계(build-tools `VerifyMessagingEvidenceTask`가 쓰고 바로 검증한다).
4. 위 셋이 모두 생긴 다음에 `verifyMessaging<Scenario>R2` 태스크 등록. 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 가용성. 이 키는 활성화 스위치가 2. broker 상태 확인: `APP_MESSAGING_BROKER` 값과 broker endpoint 가용성. 이 키는 활성화 스위치가
아니라 **선택자**다 — messaging을 끄는 것은 `APP_MESSAGING_ENABLED=false`이고, 이 값을 비운다고 아니라 **선택자**다 — messaging을 끄는 것은 `APP_MESSAGING_ENABLED=false`이고, 이 값을 비운다고
messaging이 꺼지지는 않는다. messaging이 꺼지지는 않는다.
- `APP_MESSAGING_BROKER`가 공백인 채로 relay가 켜져 있으면 **애플리케이션이 기동하지 않는다** - relay 스케줄러는 발행 포트(`OutboxMessagePublishPort`, messaging bridge가 제공)가 있을 때만
(`OutboxRelayBrokerRequirementValidator`, MSG-024). 이 조합에서는 publish가 전부 생긴다. messaging을 고르지 않은 배포에서는 relay가 없고 PENDING row가 그대로 남는다(MSG-024의
`AdapterDisabledException`으로 실패하며 PENDING row가 DEAD까지 소진되기 때문이다. "DEAD까지 소진"은 대역 publisher가 있던 때의 이야기다). messaging 모듈이 켜져 있는데
기동 실패를 보고 있다면 broker를 설정하거나 `ca-skeleton.outbox.relay-enabled=false`로 둔다. `APP_MESSAGING_BROKER`가 공백이면 기동이 거부된다(messaging `MessagingConfig`, messaging platform
`MessagingProviderSelection`) — broker를 설정하거나 messaging을 끈다.
- 기동은 했는데 실패가 쌓인다면 broker는 설정돼 있고 도달이 안 되는 것이다 — endpoint부터 본다. - 기동은 했는데 실패가 쌓인다면 broker는 설정돼 있고 도달이 안 되는 것이다 — endpoint부터 본다.
3. `outbox.pending.size` status 분포 확인 (FAILED 누적 vs PENDING 누적) 3. `outbox.pending.size` status 분포 확인 (FAILED 누적 vs PENDING 누적)
+34 -36
View File
@@ -1,5 +1,14 @@
# GraphQL 인바운드 모듈 완전 해부 # 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와 그 주변 > **성격**: 정책 문서가 아니라 **읽기 기록**이다. `adapter:inbound:graphql` leaf와 그 주변
> (app-bootstrap 배선, 테스트 레인, 아티팩트 게이트, 스모크 스크립트, ADR, 코드 리뷰 문서)에 > (app-bootstrap 배선, 테스트 레인, 아티팩트 게이트, 스모크 스크립트, ADR, 코드 리뷰 문서)에
> 실제로 구현되어 있는 것을 코드 기준으로 하나씩 확인하면서, "무엇이 있는가"와 "왜 그렇게 > 실제로 구현되어 있는 것을 코드 기준으로 하나씩 확인하면서, "무엇이 있는가"와 "왜 그렇게
@@ -1498,26 +1507,24 @@ GraphQL 에러로 남는다.
top-level 에러 하나가 **모든 아이템의 결과를 버린다** — 성공했고 부수효과가 이미 일어난 것들까지. top-level 에러 하나가 **모든 아이템의 결과를 버린다** — 성공했고 부수효과가 이미 일어난 것들까지.
그래서 `index`를 담아 클라이언트가 상관지을 수 있게 한다. 그래서 `index`를 담아 클라이언트가 상관지을 수 있게 한다.
### 14.3 `GraphQlMutationIdempotencyContext` — 키 하나가 아니라 다섯 개의 스코프 ### 14.3 mutation 멱등성 — 2026-09-25 삭제
``` GraphQL 전용 mutation 멱등성(`GraphQlMutationIdempotencyInterceptor`,
actor × tenant × mutation coordinate × contract version × normalised input `GraphQlMutationIdempotencyContext`, `GraphQlIdempotencyKey`, `GraphQlIdempotencyConflictException`,
``` `GraphQlCanonicalInput`, `GraphQlExtensionsPolicy`의 `idempotencyKey` extension 허용,
`GraphQlMutationContractValidator.requireIdempotency`)은 저장소에 연결된 적이 없어서 삭제했다.
지금 기본 `GraphQlExtensionsPolicy`는 어떤 extension key도 허용하지 않는다.
| 축 | 없으면 | 요청 재생 멱등성이 필요한 mutation은 transport가 아니라 use case 안에서 application
|---|---| `IdempotencyExecutor`를 쓴다. 스코프는 `IdempotencyScopeDigest`(principal + 클라이언트 key +
| actor | 한 클라이언트의 재시도가 다른 클라이언트의 결과를 반환 | operation code의 HMAC)로 만들고, mutation 하나를 멱등 단위로 잡는 원칙은 그대로다 — 한 GraphQL
| **tenant** | actor 정체성이 tenant를 함의하지 않음 — 같은 service account가 두 tenant에서 행동 가능 | 요청이 여러 root mutation을 나를 수 있으므로 요청 전체를 한 단위로 다루면 전부 replay하거나 전부
| mutation coordinate | 같은 키를 다른 mutation에 보내면 다른 오퍼레이션인데 같은 결과 | 안 하거나가 된다. 삭제된 인터셉터가 스코프에 넣던 축(actor, tenant, mutation, contract version,
| contract version | 계약이 바뀌면 같은 입력이 다른 의미 | 정규화된 입력)은 digest를 만들 때 여전히 점검할 목록이다.
| normalised input | 같은 키에 다른 입력 = 두 개의 다른 부수효과 |
javadoc이 tenant를 왜 따로 두는지 명시한다: *"Tenant is part of the scope because actor identity ### 14.4 `GraphQlCanonicalInput` — 지문 충돌 사건 (삭제된 코드의 기록)
does not imply it."*
### 14.4 `GraphQlCanonicalInput` — 지문 충돌 사건 **이 leaf에서 가장 교육적인 버그다.** 코드는 §14.3과 함께 삭제됐지만 교훈은 남긴다.
**이 leaf에서 가장 교육적인 버그다.**
이전 정규형은 최상위 키를 정렬하고 `key=value;`로 조인했다. 두 개의 서로 다른 입력이 동일하게 이전 정규형은 최상위 키를 정렬하고 `key=value;`로 조인했다. 두 개의 서로 다른 입력이 동일하게
정규화될 수 있었다: 정규화될 수 있었다:
@@ -1533,13 +1540,10 @@ does not imply it."*
§13.4의 커서 프레이밍 버그와 **같은 부류**다: 구분자를 값 안에서 구분할 수 없다. 그리고 같은 §13.4의 커서 프레이밍 버그와 **같은 부류**다: 구분자를 값 안에서 구분할 수 없다. 그리고 같은
레포 안에서 두 번 일어났다. 이게 §27의 원칙 하나가 된다. 레포 안에서 두 번 일어났다. 이게 §27의 원칙 하나가 된다.
### 14.5 `GraphQlIdempotencyKey` — 양쪽이 다 묶인다 ### 14.5 (삭제됨) `GraphQlIdempotencyKey`
8~128자. 이유가 양방향이다: §14.3 참고. 키 길이 제한(8~128자)을 두던 이유 — 너무 짧으면 무관한 요청끼리 충돌하고,
- **너무 짧으면** 무관한 요청 간에 충돌 → 한 호출자의 재시도가 다른 호출자의 결과를 반환 무제한이면 저장·로깅 문제가 생긴다 — 는 클라이언트 key를 받는 쪽이 여전히 지켜야 한다.
- **무제한이면** 저장·로깅 문제
`GraphQlIdempotencyConflictException`은 **키도 입력도 담지 않는다.**
### 14.6 `GraphQlMutationContractValidator` — GraphQL의 serial 실행은 트랜잭션이 아니다 ### 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.* > *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를 막는 프로파일 ## 15. `fetch` — over-fetch를 막는 프로파일
@@ -2062,7 +2060,7 @@ override는 **의도적 호환성 레인에서만** 허용 — 조용히 하나
| DataLoader / batching | `wired` | `GraphQlBatchLoaderRegistrationTest` (**50 parent → 3 downstream**) | | DataLoader / batching | `wired` | `GraphQlBatchLoaderRegistrationTest` (**50 parent → 3 downstream**) |
| object 인가 | `modelled` | 실행 경로에 연결하는 configuration 없음 | | object 인가 | `modelled` | 실행 경로에 연결하는 configuration 없음 |
| **cursor 서명** | `modelled` | **auto-configuration이 `HmacGraphQlCursorCodec`도 `GraphQlCursorKeyRing`도 만들지 않음** — `GraphQlPolicyRequestPathTest`가 고정 | | **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 구현 미제공 | | persisted operation | `modelled` | 중립 `OperationalRecordStorePort` 기반 레지스트리 + 방향성 테스트. durable 구현 미제공 |
| subscription / WebSocket / SSE / RSocket | `modelled` | 정책·상태기계 단위 테스트만. **Spring transport handler 없음 — 그래서 타입 이름도 `*Admission`이다** | | subscription / WebSocket / SSE / RSocket | `modelled` | 정책·상태기계 단위 테스트만. **Spring transport handler 없음 — 그래서 타입 이름도 `*Admission`이다** |
| federation / incremental / codegen / compat | `modelled` | 단위 테스트만 | | 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) | | `GraphQlDeploymentModeRegistryParityTest` | enum 목록과 운영자용 레지스트리 동기화 (§4.1). 2026-09-25에 graphql leaf로 이동 |
| `ShippedRuntimeFacadePresenceTest` | shipped facade 존재 | | `ShippedRuntimeFacadePresenceTest` | shipped facade 존재 (2026-09-25 삭제) |
| `FiveAdapterOffInventoryTest` | 다섯 어댑터 off 상태 인벤토리 | | `FiveAdapterOffInventoryTest` | 다섯 어댑터 off 상태 인벤토리 (2026-09-25 삭제) |
| `CapabilityDependencyValidatorTest` | capability 의존 검증 | | `CapabilityDependencyValidatorTest` | capability 의존 검증 (2026-09-25 삭제) |
| `RuntimeMembershipClasspathAgreementTest` | `runtime_memberships`와 실제 classpath 일치 | | `RuntimeMembershipClasspathAgreementTest` | `runtime_memberships`와 실제 classpath 일치 (삭제됨. `verifyRuntimeModuleRegistry`가 대신 본다) |
| `ConditionalTransportQualificationContractTest` | 조건부 전송 계약 | | `ConditionalTransportQualificationContractTest` | 조건부 전송 계약 |
| `AdapterActivationInventory` / `ShippedCompositionHarness` | 헬퍼 | | `AdapterActivationInventory`(2026-09-25 삭제) / `ShippedCompositionHarness` | 헬퍼 |
`RuntimeMembershipClasspathAgreementTest`가 특히 §25.1의 drift를 잡아 줄 수 있는 위치다 — `RuntimeMembershipClasspathAgreementTest`가 특히 §25.1의 drift를 잡아 줄 수 있는 위치다 —
레지스트리와 classpath는 일치하고, 산문 문서만 어긋나 있다. 레지스트리와 classpath는 일치하고, 산문 문서만 어긋나 있다.
@@ -3349,7 +3347,7 @@ javadoc 도구는 마지막 것만 연결한다. **`SPRING_DATA` 상수 다음,
|---|---|---|---| |---|---|---|---|
| cursor 서명 | 완성 | 키 재료 출처 | P2 | | cursor 서명 | 완성 | 키 재료 출처 | P2 |
| object 인가 | 완성 (`ObjectAccessPolicy` + bridge) | 실행 경로 연결 configuration | **누가 `GraphQlObjectAuthorizationPort`를 제공하나** — leaf 기본값? adopter? | | 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)가 이미 그 패턴을 확립했으니, 셋 다 같은 방식으로 정리하는 게 `GraphQlPrincipalResolver`(§9.9)가 이미 그 패턴을 확립했으니, 셋 다 같은 방식으로 정리하는 게
+27 -72
View File
@@ -1254,12 +1254,12 @@ credential로 도는데, 그건 설계상 런타임 롤과 다른 롤이다 —
### 7.7 벤더 선택과 H2 대칭 ### 7.7 벤더 선택과 H2 대칭
두 벤더 composition이 각각 **같은 네 개의 SPI 빈**을 등록한다. 두 벤더 composition이 각각 **같은 SPI 빈**을 등록한다. (V1 idempotency의
`IdempotencyClaimRepository`와 벤더별 구현 두 개는 2026-09-25에 V1과 함께 삭제됐다.)
| SPI | PostgreSQL | H2 | | SPI | PostgreSQL | H2 |
|---|---|---| |---|---|---|
| `OutboxClaimRepository` | `PostgreSqlOutboxClaimRepository` | `H2OutboxClaimRepository` | | `OutboxClaimRepository` | `PostgreSqlOutboxClaimRepository` | `H2OutboxClaimRepository` |
| `IdempotencyClaimRepository` | `PostgreSqlIdempotencyClaimRepository` | `H2IdempotencyClaimRepository` |
| `SqlStateErrorMapping` | `PostgreSqlSqlStateErrorMapping` | `H2SqlStateErrorMapping` | | `SqlStateErrorMapping` | `PostgreSqlSqlStateErrorMapping` | `H2SqlStateErrorMapping` |
| `TransactionLocalTimeoutConfigurer` | `PostgreSqlLocalTimeoutConfigurer` | `H2LocalTimeoutConfigurer` | | `TransactionLocalTimeoutConfigurer` | `PostgreSqlLocalTimeoutConfigurer` | `H2LocalTimeoutConfigurer` |
@@ -1272,27 +1272,14 @@ credential로 도는데, 그건 설계상 런타임 롤과 다른 롤이다 —
부재는 PostgreSQL이다(`matchIfMissing = true`) — 선택자가 생기기 전 모든 배포가 돌던 벤더. 부재는 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`를 받아들이고 잠긴 행을 진짜로 H2에는 idempotency store가 없다. 남은 idempotency store는 PostgreSQL 전용(§10.1)과 Redis뿐이고,
건너뛴다. 한 커넥션이 row lock을 든 상태에서 동시 `SKIP LOCKED` claim이 블록하거나 락을 PostgreSQL provider는 H2 data source에서 기동을 거부한다. 그래서 `bootRunH2`는 provider를
뚫고 읽는 게 아니라 **0행을 반환**하는 걸 확인했다. 그래서 claim이 의미를 유지한다. `disabled`나 `redis`로 둔다.
- **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 vendor config에는 Flyway location customizer가 일부러 없다.** H2 등가 트리가 없고, **H2 vendor config에는 Flyway location customizer가 일부러 없다.** H2 등가 트리가 없고,
local profile이 Flyway를 끄고 Hibernate가 엔티티에서 스키마를 만들게 하기 때문. 두 가지 local profile이 Flyway를 끄고 Hibernate가 엔티티에서 스키마를 만들게 하기 때문. 두 가지
@@ -1530,53 +1517,19 @@ CREATE TABLE idempotency_record (
CREATE INDEX ix_idempotency_record_expires_at ON idempotency_record (expires_at); 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 남은 V1 쪽 코드는 정리용이다. `IdempotencyRecordEntity`/`IdempotencyRecordJpaRepository`를 쓰는
> scope dedup이 깨진다. `IdempotencyReaper`(`@Scheduled`, 기본 10분, `deleteExpired` bulk delete)가 `expires_at`이 지난
행을 지운다. store가 완료·실패 때 `expires_at`을 앞으로 옮기므로 reaper는 **테이블 성장을 묶는
backstop**이다. reaper는 provider가 `postgresql`일 때만 돈다.
매퍼가 `null` 애플리케이션 tenant ↔ row의 `""`를 왕복시킨다. 응답은 8 KiB 이하만 행에 inline으로 저장하고, 넘으면 store가 거부한다. object store offload
경로는 없다.
**엔티티에 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
빈도도 미측정).
### 9.2 `outbox_event` (V3) ### 9.2 `outbox_event` (V3)
@@ -1719,7 +1672,7 @@ setter가 아니라 **registry 생성자**에서 설정한다.
### 10.1 `PostgreSqlOwnerSafeIdempotencyStore` ### 10.1 `PostgreSqlOwnerSafeIdempotencyStore`
`IdempotencyStorePortV2` 구현. 상태: `IdempotencyStorePort` 구현. 상태:
`CLAIMED → EXECUTING → COMPLETED | FAILED_RETRYABLE | ABANDONED`. `CLAIMED → EXECUTING → COMPLETED | FAILED_RETRYABLE | ABANDONED`.
클래스가 하는 일과 협력자로 분리한 것이 명확히 문서화되어 있다. 클래스가 하는 일과 협력자로 분리한 것이 명확히 문서화되어 있다.
@@ -2716,13 +2669,13 @@ JpaPlatformRuntimeAutoConfiguration ← 8개 add-on 빈
``` ```
ca-skeleton.persistence-jpa.enabled = true ca-skeleton.persistence-jpa.enabled = true
ca-skeleton.outbox.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 ca-skeleton.lock.multi-instance-enabled = true
notification.platform.enabled && persistence != none notification.platform.enabled && persistence != none
app.fileserver-platform.enabled && transaction-provider != 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 꺼졌나?"만 물으면 > notification store, Fileserver 트랜잭션 경로가 전부 필요로 하고, "JPA 꺼졌나?"만 물으면
> **아무도 안 쓰는 풀을 열거나, 정당하게 쓰던 capability를 조용히 망가뜨린다.** > **아무도 안 쓰는 풀을 열거나, 정당하게 쓰던 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`, `ca-skeleton.outbox.*`: `poll-interval: PT5S`, `batch-size: 20`, `in-flight-timeout: PT5M`,
`reaper-interval: PT10M`, `published-retention: P7D`. `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` | 동일 | | `IdempotencyReaper` | 동일 |
| `OutboxStoreAdapter` | **없음** (`@Repository`만) | | `OutboxStoreAdapter` | **없음** (`@Repository`만) |
| `OutboxReaper` | **없음** (`@Component` + `@Scheduled`) | | `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 | | Application use case | TEST | fake/stub port, 필요 최소 mock |
| startup validator / settings validation | TEST | `MockEnvironment` 또는 순수 객체 | | startup validator / settings validation | TEST | `MockEnvironment` 또는 순수 객체 |
| Spring `@Configuration` 한 조각 | TEST | `ApplicationContextRunner` | | 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 | | hermetic serialization/API snapshot | TEST | contract assertion |
| JPA repository + 실제 PostgreSQL | INTEGRATION | Testcontainers/real DB | | JPA repository + 실제 PostgreSQL | INTEGRATION | Testcontainers/real DB |
| Kafka/Rabbit/Redis/Mongo와 실제 프로토콜 통신 | INTEGRATION | real service/container | | Kafka/Rabbit/Redis/Mongo와 실제 프로토콜 통신 | INTEGRATION | real service/container |
+53 -34
View File
@@ -1,58 +1,77 @@
# Web Advanced: support matrix # Web Advanced: support matrix
Every capability is off unless named. `WebAdvancedPromotionGate.forFeature` is the machine-checked The Advanced capabilities live in their own leaf, `adapter:inbound:web-advanced`
form of the last two columns; if this table disagrees with it, the code wins. (`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 | 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,
| `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 | nothing happens until service code calls it.
| `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 |
## 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 The same leaf also holds the web library packages the servlet production path never reaches:
`WEBFLUX_BLOCKING_BRIDGE`. A codec affects only requests that negotiate it; a virtual-thread `http` (URI and method policy), `versioning`, `operation`, `budget`, `contract`, `security`
executor affects every request in the process, and the blocking bridge affects the event loop they (security-context bridge), `idempotency` (`JsonIdempotentResponseCodec`) and `admin/route`.
all share. `WebAdvancedFeatureFlags.stableBehaviourPreserved()` reports whether either is on.
That distinction is why those two soak for 24 hours and why their rollback test is the one that `./gradlew :adapter:inbound:web-advanced:test` runs all of it. `webAdvancedTest` is the tagged
matters most. 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 ## What is refused, and why the row is here
| Refused | Reason | | 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. | | 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 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 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. | | 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. | | 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. | | 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. | | 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. | | 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: 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
- **Rollback exercised.** A flag nobody has turned off is not known to turn off. with each flag explicitly `false`.
- **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.
See `docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md`, See `docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md`,
`ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md`, and `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, 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. 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 ## The invariant
**Generating 3.2 must not change the 3.1 snapshot.** Both come from the same model, so a contributor **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 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 Nothing in this repository checks it any more. `OpenApi32CompatibilityReport` and
blocker with its own message. `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 Promotion stays a judgement, recorded in
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
`docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`. `docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`.
## Running it ## Running it
The experimental generation runs in its own workflow and publishes the 3.2 document and the No workflow in this repository generates 3.2. `OpenApiVersionLane.STABLE_3_1` is the release
compatibility report as artifacts. It never runs in the release workflow, so the release artifact artifact; `WebOpenApi32GeneratorTest` covers the generator.
cannot depend on whether it ran.
+3 -1
View File
@@ -1,6 +1,8 @@
# Web patch: the client contract # 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 ## 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 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. 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 ## 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. 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 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. 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 A Gradle dependency gate cannot see inside a leaf. The in-leaf module map that used to check the
see inside a leaf. `WebStableModule` declares each module's identity, package, purity grade and package edges (`WebStableModule`) was removed with the second-generation platform; the ArchUnit
allowed edges; `WebModuleBoundaryTest` scans the real source tree and fails when the tree and the rules in `testkit/arch` (`WebArchitectureRules`) are what remains.
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.
| Design module | Package under `dev.caskeleton.adapter.inbound.web` | Status | | Design module | Package under `dev.caskeleton.adapter.inbound.web` | Status |
| --- | --- | --- | | --- | --- | --- |
| `web-core-api` | `core` | planned (Task 2+) | | `web-core-api` | `core` | planned (Task 2+) |
| `web-contract` | `contract` | planned | | `web-contract` | `contract` | planned |
| `web-validation` | `validation` | planned |
| `web-error` | `error` | present | | `web-error` | `error` | present |
| `web-pagination` | `pagination` | present | | `web-pagination` | `pagination` | present |
| `web-idempotency` | `idempotency` | 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-observability` | `observability` | present |
| `web-openapi` | `openapi` | planned | | `web-openapi` | `openapi` | planned |
| `web-mvc` | `mvc` | planned | | `web-mvc` | `mvc` | planned |
| `web-webflux` | `webflux` | planned | | `web-webflux` | — | removed (D4: servlet only) |
| `web-admin` | `admin` | planned | | `web-admin` | `admin` | planned |
| `web-operation-jpa` | `operation.jpa` | planned | | `web-operation-jpa` | `operation.jpa` | planned |
| `web-operation-messaging` | `operation.messaging` | planned | | `web-operation-messaging` | `operation.messaging` | planned |
| `web-spring-boot-starter-mvc` | `autoconfigure.mvc` | planned | | `web-spring-boot-starter-mvc` | `autoconfigure.mvc` | planned |
| `web-spring-boot-starter-webflux` | `autoconfigure.webflux` | planned | | `web-spring-boot-starter-webflux` | — | removed (D4: servlet only) |
| `web-testkit-*` | `testkit`, `testkit.mvc`, `testkit.webflux`, `testkit.contract` | planned | | `web-testkit-*` | `testkit`, `testkit.mvc` | present |
| — | `conditional`, `cursor`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | present, pre-dates the design | | — | `conditional`, `http`, `filter`, `envelope`, `config`, `controller`, `ratelimit`, `settings` | present, pre-dates the design |
| — | `fileserver.*`, `notification.*` | present, feature integrations rather than platform modules | | — | `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 ## 2. Root package
The design uses `io.backend.skeleton.web`. This repository's package root is 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` ## 6. Idempotency: the design's store SPI is already owned by `application-core`
The design gives `web-idempotency` its own `IdempotencyStore`, `IdempotencyRecord`, The design gives `web-idempotency` its own `IdempotencyStore`, `IdempotencyRecord`,
`IdempotencyState`, `IdempotencyScope` and `RequestFingerprint`. This repository already has all `IdempotencyState`, `IdempotencyScope` and `RequestFingerprint`. This repository already has the
five in `application-core/idempotency`, with a JPA adapter equivalents in `application-core/idempotency` — `IdempotencyStorePort`, `IdempotencyState`,
(`PostgreSqlOwnerSafeIdempotencyStore`, `IdempotencyStoreAdapter`) and a Redis cache behind them — `IdempotencyScopeDigest` and `RequestFingerprint` — with two provider stores behind the port:
which is what the design's Tasks 39 and 40 ask for, built in the direction the registry permits. 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 Implementing the design's SPI literally would have required
`adapter-outbound-persistence-jpa → adapter-inbound-web`, an edge the registry forbids and one that `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` | | 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 | | 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 | | `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 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 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 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 for idempotency, where `IdempotencyStorePort` lives in `application-core` and
`IdempotencyStoreAdapter` in `persistence-jpa`: `PostgreSqlOwnerSafeIdempotencyStore` in `persistence-jpa`:
| Design type | Here | | Design type | Here |
| --- | --- | | --- | --- |
@@ -128,15 +128,12 @@ for idempotency, where `IdempotencyStorePort` lives in `application-core` and
| the lease | `application-core/operation/OperationLease` | | the lease | `application-core/operation/OperationLease` |
| the stored failure | `application-core/operation/OperationFailure` — a code and an already-safe message, never an exception | | 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` | | `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 | | `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` |
| — | web `operationasync/OperationResourceFactory`, which is the projection itself |
The split is not only a registry workaround; it puts each half where its invariants belong. A 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 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 code plus a safe message. An HTTP surface for operations, if one is added again, maps it onto the
the same sanitiser as every synchronous error. An async failure therefore cannot publish something `Envelope` error contract.
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`.
The state machine is enforced three times on purpose: in `DurableOperation`'s constructor, in the 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 `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 ## 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 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 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. 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: Two consequences worth stating, because both are counterintuitive:
**An edge limit below the application's means clients never see a problem document.** nginx answers **An edge limit below the application's means clients never see the application's error body.**
its own HTML error page, so a client that branches on `ProblemCode` gets a body it cannot parse. 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 Where a dimension matters to clients, the edge limit must be set *above* the application's so the
application is the one that refuses. 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. 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. Both belong; only their ordering is a decision.
The enforcement itself never materializes a body to measure it. `WebBudgetMeter` counts bytes as ## 9. The Nginx lane (removed 2026-09-25)
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.
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 One finding from that lane still applies to any Nginx in front of this service. Nginx's
count of it, and the overrun is answered as a problem document. Resetting only the buffer was the inheritance rule for array directives is *replacement*: a single `proxy_set_header` inside a
first implementation and it failed: the meter still held the count of the discarded bytes, so the `location` discards every `proxy_set_header` inherited from `server`. Setting the forwarded headers
small problem document was refused too and the client got the container's error page. once at `server` level and adding only `X-Forwarded-Prefix` per `location` therefore sends none of
- **Committed** — there is no status left to send. The exception propagates, the connection ends the others, and the application falls back to the upstream's own `Host`. Keep the forwarded headers
mid-document, and the client sees a truncated response. That is worse for the client than a clean in one included file and `include` it in every `location`.
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.
## Advanced capabilities ## 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 - **`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 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. 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 `advanced.patch` and `advanced.codec` bind to a framework and had to: Jackson's tree model is the
tree model is the reason for the first — a merge patch's null-means-delete has no representation in reason for the first — a merge patch's null-means-delete has no representation in a Java object, so
a Java object, so the applier works on nodes — and `XMLInputFactory` is the reason for the second. 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 `advanced.stream.encoding` is separated from `advanced.stream` for the same reason: framing
reason: framing serializes, and serializing binds to Jackson. serializes, and serializing binds to Jackson.
### What was adapted rather than copied ### 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`.** **`WebStreamErrorPolicy`'s factory methods are `startOver` / `resumeFromPosition` / `nothingToDo`.**
The design's names collided with the record's own accessors, which Java rejects. 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 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. way, and the failure only appears in whatever composes this leaf.
**The framing and the writers are separate, and both exist.** `NdjsonFraming` and **The framing and the writer are separate.** `NdjsonFraming` and `JsonSequenceFraming` hold the
`JsonSequenceFraming` hold the contract; `MvcStreamWriter`, `WebFluxStreamWriter` and contract; `MvcStreamWriter` is what puts it on a response. There is no MVC SSE writer: this
`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, and the only SSE writer
repository's `NO_SSE_EMITTER` ArchUnit rule forbids `SseEmitter` outright, so the servlet stack was the WebFlux one removed on 2026-09-25. So the servlet stack streams NDJSON and JSON-seq, and SSE
streams NDJSON and JSON-seq and SSE is reactive-only. An earlier pass is framing-only — nothing serves it until a servlet writer exists.
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.
**`MessagingReplayBridge` is `WebStreamReplaySource`, an interface this module implements nowhere.** **`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 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 ### What the execution layer had to get right
Three of these were only found by building the adapter rather than the policy. 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
**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
courtesy and why a failed beat is recorded as disconnect evidence. 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 ### Verification
```bash ```bash
cd src cd src
./gradlew :adapter:inbound:web:test # 861 tests, Advanced included ./gradlew :adapter:inbound:web:test # the shipped web leaf
./gradlew :adapter:inbound:web:webAdvancedTest # 147, the Advanced lane on its own ./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
./gradlew :adapter:inbound:web:webCrossStackParityTest ./gradlew :adapter:inbound:web:webJettyCompatTest # Jetty, real socket
./gradlew :adapter:inbound:web:webNginxProxyTest # Docker ./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`, 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 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. 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 | ## Errors that are not the `Envelope`
| --- | --- | --- |
| `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 |
The second row is a real consequence of the design and worth knowing before it confuses you. Quota Every HTTP error the application writes is the `Envelope` from `GlobalExceptionHandler`
is charged *before* capacity is requested, deliberately — the reverse order lets a caller who is (`spring.mvc.problemdetails.enabled=false`), with an `error.code` a client branches on.
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.
## A control that appears configured and does nothing - **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
This has happened here, and the failure is silent by construction. A configured-but-unwired control the handler is not installed or the response came from the edge.
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.
## A response is truncated or the connection dies mid-document ## A response is truncated or the connection dies mid-document
Two different causes, distinguished by the status the client did receive. 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 - **Client got a status, then nothing** — the response failed after commit. The status cannot be
platform cannot retract a status, so it ends the connection: a truncated response the client retracted, so the connection ends mid-document.
rejects is better than a short one it accepts as complete. Raise `maxResponseBytes` for that - **Client got nothing from the application** — the proxy refused it. `client_max_body_size` in
operation's profile, or make the endpoint paginate. nginx answers with its own HTML rather than the `Envelope`. See `repository-adaptation.md` §8.
- **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.
## A retried write happened twice ## A retried write happened twice
The idempotency key is the control, and there are exactly three ways it fails to apply. 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. 1. **The client did not send one.** The endpoint does not require the key, so it ran unguarded.
Change the profile to `REQUIRED` if a duplicate is unacceptable. Require it if a duplicate is unacceptable.
2. **The client sent a different body.** Answered `422 IDEMPOTENCY_KEY_REUSED`, never a replay — 2. **The client sent a different body.** Answered `422 IDEMPOTENT_REQUEST_MISMATCH`, never a
replaying would hand back a receipt for a request the caller never made. 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 3. **The record expired.** TTL is per-operation with a 72h cap. A retry after expiry is a new
request by definition. 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`. the caller should retry after `Retry-After`.
## Rolling deploy stalls with instances half-drained ## Rolling deploy stalls with instances half-drained
`shutDownGracefully` waits for in-flight work, and on Reactor Netty an open-but-idle keep-alive `shutDownGracefully` waits for in-flight work, and an open-but-idle keep-alive connection can count
connection counts as in-flight. Calling `stop()` while that wait is in progress hangs. as in-flight. Calling `stop()` while that wait is in progress hangs.
- **Symptom:** an instance neither serving nor exiting, no error in its log. - **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 - **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 ## Metrics stopped arriving, or the bill jumped
Almost always a high-cardinality tag. `WebMetricCardinalityPolicy` refuses anything off an Almost always a high-cardinality tag — typically a `routeTemplate` carrying a *resolved* path, which
eight-name allowlist at the point of recording, so a new tag cannot appear by accident — but a is one series per resource.
`routeTemplate` carrying a *resolved* path can, and that is one series per resource.
- **Check:** the tag values in the metrics backend for `routeTemplate`. Braces mean templates; - **Check:** the tag values in the metrics backend for `routeTemplate`. Braces mean templates;
identifiers mean the resolved path leaked through. 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 ## Cross-origin requests fail only in the browser
The API answers correctly and the browser refuses the response. Everything below is refused at The API answers correctly and the browser refuses the response. CORS is `CorsSettings`
startup by `WebCorsPolicyValidator`, so a running instance with one of these means the profile was (`ca-skeleton.cors.*`) applied by `SecurityConfig`. Startup refuses two settings:
built somewhere that does not validate.
- `*` with credentials — no browser honours it. - `APP_SECURITY_CORS_ENABLED=true` with no origin.
- An origin with a path, a trailing slash, or uppercase — never matches what the browser sends. - `*` in `APP_SECURITY_CORS_ORIGINS` with `APP_SECURITY_CORS_ALLOW_CREDENTIALS=true` — no browser
- `https://*.example.com` — matches nothing; CORS compares origins exactly. honours it.
- Wildcard `allowedHeaders` on a credentialed profile — not honoured with credentials.
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 A preflight answered `401` means CORS ran after authentication. Preflights carry no credentials by
design; the order is asserted by `WebPipelineOrderContract`. 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 ```bash
cd src cd src
./gradlew :adapter:inbound:web:test # unit, boundary, architecture ./gradlew :adapter:inbound:web:test # unit, boundary, architecture
./gradlew :adapter:inbound:web:webCrossStackParityTest # Tomcat vs Jetty vs Reactor Netty ./gradlew :adapter:inbound:web:systemTest # Tomcat, real socket
./gradlew :adapter:inbound:web:webNginxProxyTest # real proxy; needs Docker, fails without it
./gradlew :adapter:inbound:web:webJettyCompatTest # second servlet container ./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 # 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 ## 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: 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. 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 2. **A `Failure` record.** Something failed after commit. Carries an error code and a client-safe
client-safe message. The status is still 200. message. The status is still 200.
3. **Neither.** The connection closed mid-stream. The server records this as `ABRUPT_CLOSE`; from 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 the client's side it is indistinguishable from a completed stream *unless the client is looking
for the terminal envelope*. for the terminal envelope*.

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