문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
adapter:outbound:objectstorage — design-decision reference
Object-storage driven adapter under
dev.caskeleton.adapter.outbound.objectstorage. It implements the semantic contracts in
dev.caskeleton.application.objectstorage and keeps provider keys, paths, SDK types, and control
records behind the application boundary.
The allowed production dependencies are owned by
src/config/architecture/modules.json. Module rules live in CLAUDE.md, the full design
in docs/superpowers/specs/2026-07-28-objectstorage-production-capability-design.md, and exact
evidence claims in docs/registries/object-storage-readiness.yaml.
For when to use this capability rather than the HTTP Fileserver platform, see
docs/storage-capability-boundary.md.
Current readiness
Batch B implements the provider-neutral namespace/control kernel and
filesystem-local-dev managed single upload/download at R1. R1 means bounded local functional
evidence only:
- immutable streamed create with exact SHA-256 and exact version inspection;
- full/range bounded reads;
- strict canonical control-record codecs and single-process CAS;
- same-operation replay without invoking the producer again;
- restart/path/symlink/corruption/fault characterization;
- exactly-once selected-provider lifecycle.
It does not prove multi-node CAS, power-loss durability, production credentials/TLS/IAM/encryption,
S3 response-loss behavior, or R2 readiness. Direct transfer, multipart, quarantine, retention, and
production reconciliation cards remain R0. Direct transfer and multipart have no code: the unassembled
implementation was removed (recovery path in docs/capability-status.md 「제거된 코드」).
제공하는 것 · 추가할 한 줄 · env 키
-
제공: application-objectstorage의 semantic port 구현(
ManagedObjectPublicationPort, 읽기/변경 routing adapter),filesystem-local-dev와 S3 provider. 진입점은 모듈 자신의AutoConfiguration.imports에 있는ObjectStorageAutoConfiguration하나이고, 설정 바인딩도 그 안에서 한다(composition root의 properties scan에 기대지 않는다). -
추가할 한 줄(기본 조립에는 없다):
// app-bootstrap/build.gradle runtimeOnly project(':adapter:outbound:objectstorage') // 객체 저장소 (S3/로컬)이 줄을 지우면 port 구현, provider, 설정 바인딩이 모두 함께 빠진다.
-
켜기와 끄기: 모듈이 있으면 켜진다.
app.object-storage.enabled=false로만 끄고, 그때 모듈은 아무 bean도 두지 않는다. -
env 키: 전용
APP_*키는 없다. provider·destination이 map 구조라 배포의application-*.yml에app.object-storage.{default-destination, providers.<id>.*, destinations.<id>.*}를 적는다(아래 「Activation and routing」). 빠지면 기동 시 binding compile이 실패한다.
Activation and routing
The canonical namespace is app.object-storage. It is on when the module is present and off only
with app.object-storage.enabled=false. On requires an explicit provider, exact provider version,
logical destination, route token, binding/policy revisions, and bounded sizes. Settings compile fully before any selected provider creates a
directory, client, thread, scheduler, or credential lookup.
filesystem-local-dev is rejected under prod/production. Normal composition contributes only
managed publication, inspection/transfer, retirement, and operation-resolution ports. Scanner
maintenance composition stays separate. There is no purge or direct-grant port.
S3 retirement deletes the exact version a HEAD verified (DeleteObject with versionId). An
If-Match condition on DELETE is not used: the qualified MinIO release ignores it (the MinIO lane
shows a stale ETag still deleting), and the SDK documents it for directory buckets only. A version-id
DELETE cannot touch an overwrite that landed after the HEAD, so it is conditional without relying on
the vendor honouring a header. It needs a bucket with versioning enabled: an S3 operation profile
that claims CONDITIONAL_RETIREMENT makes startup read GetBucketVersioning and refuse anything
but Enabled, and a retire that finds no version id is refused rather than turned into a by-key
delete.
The local provider maps provider-neutral logical control keys to .record leaf files. This permits
object-store-valid pairs such as reference and reference/lifecycle without a filesystem
file/directory collision; callers and durable control records retain the canonical logical keys.
Provider and dependency scope
The AWS SDK v2 BOM stays module-scoped because Spring Boot does not manage
software.amazon.awssdk:*. The whole-byte[] ObjectStoragePort generation and its filesystem/S3
adapters were removed; the canonical semantic ports are the only generation (recovery path in
docs/capability-status.md 「제거된 코드」).
Verification
Focused contracts cover codecs/state machines, local provider behavior, fail-closed binding, composition side effects/lifecycle, routing replay/read behavior, and the readiness registry.
cd src
./gradlew :adapter:outbound:objectstorage:check --console=plain
Provider contract for a new provider
ObjectStorageProviderContract is in this leaf's test fixtures, because the ObjectStorageProvider
SPI is this leaf's own. The local-dev provider (LocalDevObjectStorageProviderTest) and the S3
provider against MinIO (MinioS3ManagedObjectProviderContractTest) both extend it. A provider a
derived service adds extends the same class instead of copying it:
testImplementation testFixtures(project(':adapter:outbound:objectstorage'))
MinIO qualification lanes
objectStorageMinioContractTest and objectStorageMinioFaultTest run a real MinIO and Toxiproxy.
They run in the root integrationCheck (main push and nightly) and in
.github/workflows/object-storage-qualification.yml on pull requests that touch object storage —
not in this leaf's mainCheck, which ran them a second time on every main push. Their images are read from one file,
src/test/resources/object-storage/minio-provider-evidence.json, whose image digest is the
release the status, excludedProfiles and limitations beside it were measured on.
MinioQualificationImage (in src/test, checked by the leaf's test without Docker) reads it.
- The image is pulled before any container is built. If it cannot be pulled the lane fails with
pinned image unavailable: <reference>: a supply failure, not an adapter defect. The lane does not skip, because a skipped vendor lane would be green with no vendor evidence. - A mirror of the same digest is set with
OBJECT_STORAGE_MINIO_IMAGEor-PobjectStorageMinioImage=<registry>/<repo>@sha256:<evidence digest>. A value that does not end in the evidence digest is refused: a different build is a new measurement, made by re-running the lanes and rewriting the evidence file (image and findings together). - The local compose runtime (
docker-compose.infra.yml,LOCAL_MINIO_IMAGE) uses the same digest.ComposeMinioImageMatchesEvidenceTest(leaftest) fails when the compose default and the evidence disagree; change both together. - The contract lane also runs
MinioS3ManagedObjectProviderContractTest: the S3 adapter itself under the provider contract the local-dev provider inherits, on the production client factory, over TLS with a certificate made for the run (a binding only accepts HTTPS). Its first run found two adapter defects the mocked unit tests could not: every create failed because the SDK cancels the request body once it holds Content-Length bytes (and at once for an empty body), and every read with a consumer chunk below the network buffer size failed because Netty delivers 8 KiB buffers. Both are fixed (S3AsyncRequestBodyBridge,S3AsyncResponseBodyBridge.TRANSPORT_BUFFER_CEILING_BYTES).
Image source (review 05-09, measured 2026-11-02)
Docker Hub minio/minio and quay.io/minio/minio stopped serving MinIO, so the measured digest of
the old release (2024-01-16) could not be mirrored. Two maintained builds were pulled and measured
with the same requests (create-only PUT twice, stale and current If-Match PUT, create-only
multipart completion onto an existing key, stale If-Match DELETE):
| Candidate | Result | Decision |
|---|---|---|
pgsty/minio@sha256:b6bfe723… (community fork on Docker Hub, RELEASE.2026-08-04T00-00-00Z) |
412 / 412, 200 / 412; DELETE ignores If-Match |
Chosen. Named release tags, pgsty/mc with a shell for the compose bucket bootstrap, runs as root like the old image |
cgr.dev/chainguard/minio@sha256:0a011000… (RELEASE.2026-10-23T20-06-51Z) |
Same results | Rejected: the free tier offers only a moving latest tag, it runs as uid 65532 (the compose volume would need re-owning), and cgr.dev/chainguard/minio-client has no shell |
The new release refuses create-only overwrites, which the old one accepted. So the evidence is now
status: SUPPORTED for the managed create-only profiles (supportedProfiles), the direct
(presigned) profiles stay excluded because they were not measured, and the adapter allowlist gained
the provider type s3-compatible-minio-pgsty-release-2026-08-04t00-00-00z (version
release-2026-08-04t00-00-00z-sdk-2.30.0). Only that release may claim IMMUTABLE_CREATE; no MinIO
release may claim MULTI_NODE_LINEARIZABLE_CAS or RESPONSE_LOSS_RESOLUTION, because the evidence
is one single-node container. The 2024-01-16 type stays for servers that still run it, with its
old restrictions.
The compose client minio-init uses pgsty/mc by digest (LOCAL_MINIO_MC_IMAGE overrides it).
cd src
./gradlew :adapter:outbound:objectstorage:objectStorageMinioContractTest --console=plain