feat: redis, fileserver, httpclient 런타임 시점 구현 추가

docs/superpowers/specs/2026-07-20-harness-policy-engine-design.md

@@ -1,3 +1,7 @@
+> **SUPERSEDED — HISTORICAL PROVENANCE ONLY (2026-07-25):** The user-approved harness-free
+> Mode B amendment supersedes this design. Retain the body as historical provenance; it is not
+> executable instruction.
+
 # Harness Policy Engine Refactoring Design
 
 - **Date:** 2026-07-20

docs/superpowers/specs/2026-07-25-application-outbox-failure-reporting-harness-free-design.md

@@ -0,0 +1,87 @@
+# Application Outbox Failure Reporting — Harness-Free Design
+
+## Context
+
+`application-core` currently carries Spring Boot and SLF4J only because
+`PublishPendingOutboxEventsUseCase` renders relay failures itself. That reverses the diagnostic
+dependency direction and also permits a duplicate WARN in `OutboxMessagePublishAdapter`.
+
+This change is harness-free: `src/config/architecture/modules.json`, Gradle, ArchUnit, and focused
+module tests are the policy and evidence authorities. No `.harness` files or public paths change.
+
+## Boundary
+
+`application-core` owns a specific `OutboxRelayFailureReportPort` and an immutable
+`OutboxRelayFailureReport`. The report is an allowlist containing only:
+
+- `OperationalError code`
+- event, aggregate, and correlation identifiers
+- event type, attempt count, optional next-attempt time
+- the originating `RuntimeException`
+
+It never carries the payload, idempotency key, message template, severity, arbitrary fields, or the
+whole `OutboxEvent`. Factories and record invariants admit only retryable
+`OUTBOX_PUBLISH_FAILED` reports with a next-attempt time and terminal `OUTBOX_DEAD_LETTER` reports
+without one.
+
+`adapter:outbound:messaging` owns `Slf4jOutboxRelayFailureReportAdapter`. It maps the typed report to
+one canonical SLF4J 2 fluent ERROR with fixed key names and runbook links. Bootstrap only wires the
+port.
+
+## Ordering and Failure Semantics
+
+The persisted FAILED or DEAD transition is authoritative:
+
+1. broker publication fails;
+2. the application calculates the transition;
+3. the store transition succeeds inside `TransactionPort`;
+4. only then is the typed report emitted.
+
+A transition failure propagates and emits no report. A reporter `RuntimeException` is contained by
+both the adapter and the use case, so it cannot change the relay outcome or prevent later events
+from running. Successful publication and `markPublished` failures emit no failure report.
+
+There is no production no-op reporter. `MessagingConfig` always contributes exactly one reporter
+bean, using the configured broker name or `disabled` when blank. `OutboxMessagePublishAdapter`
+becomes mapping/send-only: runtime failures propagate, checked failures are wrapped with their
+cause, and it emits no success or failure log. The general `OutboundMessagePublisher` retains its
+existing fail-open dependency logging.
+
+## Structured ERROR Contract
+
+Every confirmed transition produces one ERROR with the common fields:
+
+`error.code`, `error.category`, `dependency_name`, `dependency_type=messaging`, `outcome`,
+`event_id`, `event_type`, `aggregate_id`, `correlation_id`, `attempt_count`, and `runbook_link`.
+
+Retryable failures additionally carry `next_attempt_at`. Mappings are:
+
+| Code | Outcome | Runbook |
+| --- | --- | --- |
+| `OUTBOX_PUBLISH_FAILED` | `FAILED` | `runbook://outbox/publish-failed` |
+| `OUTBOX_DEAD_LETTER` | `DEAD` | `runbook://outbox/dead-letter` |
+
+The originating exception is attached as the throwable. Payload, idempotency key, envelope data,
+message templates derived from the exception, and arbitrary exception fields are forbidden.
+The adapter's fail-open boundary also applies to invalid direct calls: `report(null)` must never
+throw. The focused structured-adapter test pins this behavior.
+
+## Enforcement and Tests
+
+- Value tests enforce invariants and reflectively pin the exact record component allowlist.
+- Relay tests pin transition-before-report ordering, no-report paths, exact cardinality, and
+  reporter containment.
+- Messaging tests capture Logback events and pin level, fields, throwable, and unsafe-data absence.
+- `verifyApplicationCoreDependencyPurity` rejects non-project production declarations and forbidden
+  Spring/logging/metrics groups on resolved application classpaths.
+- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK` bans SLF4J, JUL, Logback, Log4j, and Micrometer from
+  the exact `dev.caskeleton.application..` scope. Its dedicated violation fixture also resides
+  inside that scope, under `dev.caskeleton.application.architecture.violations`, proving the rule
+  is non-vacuous.
+- `application-core` test dependencies are reduced to JUnit Jupiter and AssertJ; all other leaves
+  keep the shared Spring Boot test baseline.
+
+## Scope
+
+No public path, CI workflow, module-registry edge, payload shape, outbox persistence schema, or
+general publisher logging behavior changes. Agents do not stage, commit, amend, or push.

docs/superpowers/specs/2026-07-25-harness-free-mode-b-amendment.md

@@ -0,0 +1,59 @@
+# Harness-Free Mode B Amendment
+
+- **Date:** 2026-07-25
+- **Status:** Approved scope amendment
+- **Mode:** B — controlled reconstruction from repository evidence
+- **Supersedes:** `2026-07-20-harness-policy-engine-design.md` and
+  `2026-07-20-harness-policy-engine.md` in full as executable guidance; both superseded documents
+  remain only as historical provenance
+
+## Decision
+
+The repository will recover Gradle configuration and Clean Architecture dependency enforcement
+without reconstructing the absent development harness. A Gradle-owned JSON registry at
+`src/config/architecture/modules.json` becomes the single source of truth for the current 19 leaf
+modules, their repository-relative source paths, Gradle paths, and allowed production project
+dependencies.
+
+Both `src/settings.gradle` and `verifyCleanArchitectureDependencies` consume that file. Settings
+validation fails closed for malformed, empty, duplicate, unsafe, or missing module entries. The
+dependency gate continues to require complete leaf coverage and reject unapproved production
+project edges; production leaves may never depend on the `sample-portfolio` fixture consumer.
+
+## Evidence and provenance
+
+Registry entries are reconstructed from the checked-in Gradle topology and each leaf
+`build.gradle`'s `api`, `implementation`, `compileOnly`, and `runtimeOnly` project dependencies.
+Test-only and fixture-only configurations are not architecture production edges. This is Mode B
+provenance: it restores the repository's observable build contract, not unavailable historical
+artifacts.
+
+The pre-change RED command is:
+
+```bash
+cd src
+./gradlew help --console=plain
+```
+
+It fails because `src/settings.gradle` requires the absent
+`.harness/project/modules.yaml`.
+
+## Explicit non-goals
+
+- No `.harness/` tree, task resolver, task packet, or policy-hash runtime.
+- No `.agents/`, `.claude/`, `.codex/`, agent plugin, hook, renderer, or platform parity
+  reconstruction.
+- No production Java or runtime behavior change.
+- No byte-identical restoration claim.
+- No claim that the earlier Harness Policy Engine plan or the broader refactor is complete.
+
+## Enforcement and workflow
+
+Gradle and CI gates replace harness runtime dependencies for module discovery and dependency
+policy. Root and module guidance point to the Gradle-owned registry and retain the eight local
+HARD-STOP meanings, architecture responsibilities, focused-test discipline, human-only git
+policy, and LLM Wiki capture workflow.
+
+Acceptance requires successful Gradle `help`, `projects`, and
+`verifyCleanArchitectureDependencies`, an independent deterministic 19-leaf registry check,
+`git diff --check`, and a reviewed working-tree status.

docs/superpowers/specs/2026-07-25-harness-free-quality-security-ci-design.md

@@ -0,0 +1,97 @@
+# Harness-Free Quality and Security CI Design
+
+- **Date:** 2026-07-25
+- **Status:** Approved Mode B reconstruction
+- **Scope:** Repository-internal quality, dependency-vulnerability, and link-check controls
+
+## Decision and provenance
+
+Mode B reconstructs observable CI contracts from the current Gradle build, active documentation,
+and the incomplete `/home/donghyeon/dev/ca-tmpl` checkout. The candidate checkout is evidence, not
+an authoritative or byte-identical restoration source. Its useful policy is adapted to the current
+`main` branch and current tasks; stale `master`, feature-branch ownership, and absent workflow
+claims are removed.
+
+`.github/workflows/` is the canonical workflow path. No `.gitea/workflows` shadow is created. The
+origin is Gitea, but server-side Actions is externally disabled, so these files define repository
+controls without claiming that remote jobs currently execute.
+
+Every external `uses:` reference is pinned to a verified 40-character commit SHA. Its immutable
+release tag remains beside the SHA as an inline review label; moving major-version tags are not an
+execution authority.
+
+## Scope boundary
+
+This slice owns:
+
+- pinned Java tool evidence and text/binary normalization;
+- structured Trivy suppression governance and CODEOWNERS review surfaces;
+- the quality-gate matrix and its drift verifier;
+- quality, filesystem vulnerability, and documentation-link workflows;
+- human-readable dependency severity, suppression, network, and forge-compatibility policy.
+
+The development harness remains excluded: no `.harness`, `.agents`, `.claude`, or `.codex`
+runtime is reconstructed. Build/release supply-chain, tag release, image scanning, signing,
+provenance, SBOM, retention, and Docker root-context work belongs to the later Phase A2 slice and
+is not represented as a present workflow job.
+
+## Considered approaches
+
+1. Copy the candidate files unchanged. Rejected because they target `master`, refer to missing
+   supply-chain scripts/jobs, and describe obsolete branch ownership.
+2. Reconstruct a minimal current control plane from repository evidence. Selected because every
+   gate can be checked against a present Gradle task, test, script, or workflow job.
+3. Merge all checks into one workflow. Rejected because GitHub-only dependency APIs need forge
+   guards, scheduled vulnerability scans have different triggers, and link checks are path-scoped.
+
+## Components and gate flow
+
+`ci-quality-gates.yml` runs three required jobs: the aggregate Gradle quality suite, the sample-off
+axis, and gate-matrix lint. Before Java setup or Gradle, the quality job requires
+`docs/security/public-paths-snapshot.txt` to be committed and non-empty. The worktree now contains
+the canonical baseline for `/api/healthcheck`; because agents do not stage or commit, a human must
+track and commit it before CI's `git ls-files` precondition can pass. This prevents
+`verifyPublicPathSnapshot` from creating a first-run baseline inside CI and passing without
+comparison.
+
+`release-gate` uses `if: always()` and accepts only `success` from those three jobs; the advisory
+quarantine job is deliberately outside its `needs`.
+
+The quality aggregate runs `check`, `verifyPublicPathSnapshot`, and `verifyDependencyLocks`
+explicitly. `check` already pulls in Clean Architecture dependency enforcement, environment/readme
+drift checks, Trivy-ignore governance, format/static analysis, normal tests, and quarantine sunset.
+
+`dependency-vulnerability.yml` keeps GitHub Dependency Graph operations behind
+`github.server_url == 'https://github.com'`. Platform-neutral `trivy-fs` runs for PR, `main` push,
+daily schedule, and manual dispatch. Trivy and jq install into `${RUNNER_TEMP}` and expose their
+directories through `${GITHUB_PATH}`. Every Trivy scan names `.trivyignore.yaml`; High/Critical and
+KEV matches block, while Medium/Low only report. The KEV gate first rejects blank metadata,
+non-positive/non-integral or mismatched counts, empty arrays, invalid CVE identifiers, and duplicate
+identifiers. It separately rejects malformed/empty Trivy JSON before extracting candidate IDs.
+Dependency review reports through its check only and does not request permission to write a PR
+summary comment. Vulnerability DB, tool release, malformed/empty KEV or Trivy data, and KEV feed
+network failures remain blocking unless internal mirrors are configured.
+
+`link-check.yml` is path-scoped for PR and `main` push, and remains manually runnable.
+
+## Drift verification and failure behavior
+
+`.github/ci-gate-matrix.yml` lists only current mechanisms/jobs. The verifier resolves the
+repository root from its own physical location, rejects incomplete/duplicate records, and checks
+referenced Gradle custom tasks, plugins, contract-test files, workflow files, and job IDs.
+Delegated-pending is supported only when a row is explicitly marked; no absent supply-chain job is
+invented in this slice.
+
+The CI release fan-in fails for failed, cancelled, or unexpectedly skipped required jobs. Trivy's
+KEV feed cross-check is fail-closed. GitHub-only jobs may skip by their explicit forge/event
+conditions and are not dependencies of the quality release fan-in.
+
+## Verification
+
+Acceptance requires the prescribed RED for the absent `.trivyignore.yaml`, GREEN
+`verifyTrivyignore`, proof that the snapshot precondition rejects missing, empty, or untracked
+baselines, and a human-tracked canonical snapshot for CI. It also requires strict synthetic KEV
+catalog negative/positive cases, shell syntax and matrix verification, workflow YAML/static checks,
+evidence that `main` is the only active branch trigger, Trivy ignorefile coverage, exact release
+fan-in, absence of harness/Gitea shadow workflows, `git diff --check`, and reviewed working-tree
+status. Network Trivy scans are intentionally not run locally.

docs/superpowers/specs/2026-07-25-module-gradle-hygiene-harness-free-design.md

@@ -0,0 +1,173 @@
+# Harness-Free Module and Gradle Hygiene Design
+
+- **Date:** 2026-07-25
+- **Status:** Approved
+- **Mode:** B reconstruction without `.harness`
+- **Scope:** all 19 Gradle leaves, dependency declarations, test baselines, Mongo scaffolding,
+  runtime-composition documentation, and dependency locks
+- **Topology SSOT:** `src/config/architecture/modules.json`
+
+## 1. Context
+
+The 19-leaf project dependency graph obeys the registered allowed edges, and the three core
+production source sets are free of Spring, persistence, transport, logging, and metrics imports.
+The audit nevertheless found a wider declared graph than the source graph, Spring WebMVC test
+libraries on pure-core test classpaths, Boot 3-era OpenAPI tooling on Spring Boot 4, example-domain
+code in the production Mongo adapter, and direct MDC access in sample application services.
+
+This design follows the user-approved Mode B reconstruction. It does not recreate or depend on
+`.harness`; settings and verification continue to consume the JSON registry.
+
+## 2. Goals
+
+1. Keep the exact 19 leaves and all allowed project edges in the JSON registry.
+2. Remove only dependencies proven unnecessary by source/test inspection plus focused
+   compile/test verification.
+3. Give `domain-core`, `application-core`, and `shared-contract` JUnit/AssertJ-only test
+   classpaths.
+4. Keep Spring Boot 4.0.0 and replace `springdoc-openapi` 2.x with the Boot 4-compatible 3.0.0
+   line.
+5. Remove unused direct Jackson 2 declarations from GraphQL and WebSocket.
+6. Require the Spring configuration processor exactly in leaves whose main source declares
+   `@ConfigurationProperties`.
+7. Remove adapter-local `Example*` business concepts from `persistence-mongo`; retain only
+   opt-in Mongo infrastructure and typed enablement settings.
+8. Replace sample application-layer MDC reads with an application-owned correlation-context port
+   implemented by the inbound web adapter.
+9. Remove tracked jqwik runtime state and ignore future `.jqwik-database` files.
+10. Describe the default bootstrap as the default runtime composition, not as wiring every
+    optional leaf.
+11. Regenerate only affected strict dependency locks and finish with the full release gates.
+
+## 3. Non-goals
+
+- No endpoint, persistence schema, public response, outbox transition, or sample-domain behavior
+  change.
+- No version catalog, convention-plugin, `buildSrc`, module rename, or registry schema expansion.
+- No automatic addition of GraphQL, gRPC, WebSocket, Mongo, file server, or object storage to the
+  default `app-bootstrap` runtime.
+- No stage, commit, amend, or push.
+
+## 4. Approved dependency decisions
+
+An allowed registry edge is permission, not an obligation to declare it.
+
+| Leaf | Remove after focused proof | Preserve |
+| --- | --- | --- |
+| `application-core` | unused `domain-core` edge | `shared-contract` |
+| `inbound:web` | unused `domain-core` edge | application/shared and transport dependencies |
+| `inbound:graphql` | application/domain edges, direct Jackson 2, unused processor | shared and GraphQL/web test transport |
+| `inbound:grpc` | application/domain edges, unused annotations/direct protobuf declarations | shared, netty, services, configuration processor |
+| `inbound:websocket` | application/shared edges, direct Jackson 2 | domain, WebSocket, configuration processor |
+| `outbound:support` | domain/application/shared edges | autoconfigure and SLF4J API |
+| `outbound:cache-redis` | domain/application, unused Groovy/Spock | shared/support |
+| `outbound:httpclient` | domain/application | shared/support, actual Groovy/Spock tests |
+| `outbound:identifier` | domain, `uuid-creator` | application, actual Groovy/Spock tests |
+| `outbound:messaging` | domain, unused Groovy/Spock | application/shared/support/SLF4J |
+| `outbound:notification` | domain, unused Groovy/Spock | application/shared/support/web/SLF4J |
+| `outbound:persistence-jpa` | domain; explicit Flyway core only if focused compile proves the starter sufficient | application/shared/JPA/PostgreSQL |
+| `outbound:persistence-mongo` | application/shared, `Example*`, example Testcontainers tests | Mongo opt-in infrastructure/settings |
+| `outbound:fileserver` | broad Boot starter | application/shared, autoconfigure, SLF4J |
+| `outbound:objectstorage` | broad Boot starter | application/shared/AWS, autoconfigure, SLF4J, vendor IT |
+
+Production composition-root dependencies remain even when bootstrap source does not statically
+import their types: their purpose is runtime assembly. Duplicate test declarations may be removed
+only when the focused test classpath continues to compile and execute.
+
+## 5. Pure-core test and verification policy
+
+`domain-core`, `application-core`, and `shared-contract` receive only JUnit Jupiter, AssertJ, and
+the JUnit launcher from the root convention. All other leaves keep the existing Spring test
+baseline in this change; family-wide convention plugins are out of scope.
+
+The existing application dependency-purity gate remains. A new registry-driven configuration
+processor parity gate applies this Boolean invariant to every leaf and is wired into `check`:
+main source contains one or more exact `@ConfigurationProperties(` occurrences if and only if the
+leaf `build.gradle` contains exactly one Spring configuration-processor declaration. It must ignore
+`@ConfigurationPropertiesScan`; the number of settings classes is not compared with the number of
+processor declarations.
+
+## 6. Spring Boot 4 compatibility
+
+The web adapter changes
+`org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.6` to `3.0.0`, the first stable
+springdoc line released for Spring Boot 4.0.0. The existing sample tests that boot a real server
+and call `/v3/api-docs` are the behavior gate. Snapshot changes are accepted only if they are a
+deterministic library-version result and retain the public API contract.
+
+Springdoc 3 otherwise widens `ApiError.details` from the committed `type: object` to an
+unconstrained OAS 3.1 schema. A web-adapter-owned `OpenApiCustomizer` must restore the object schema
+in the final generated document. Both real-server test applications import that production
+configuration. `shared-contract` remains free of Swagger annotations and dependencies.
+
+GraphQL and WebSocket remove direct `com.fasterxml.jackson` declarations because neither source
+set imports them and Spring Boot 4 owns its JSON stack through the relevant starters.
+The web adapter retains the `JsonNullable` value type, but its `0.2.6` artifact also declares
+Jackson 2 transitively while this repository supplies explicit Jackson 3 serializers. Before and
+after dependency insight plus focused present/null/undefined serialization tests determine whether
+that transitive edge can be excluded. Exclusion is applied only if those tests and the real-server
+OpenAPI tests pass; springdoc/Swagger's independently required JSON graph is not removed by
+assumption.
+
+## 7. Mongo production boundary
+
+Delete the adapter-local `ExampleRecord`, document, mapper, repository, repository adapter, and
+their tests. `MongoPersistenceConfig` remains conditional on
+`ca-skeleton.persistence-mongo.enabled=true` and explicitly imports the Mongo client/data
+auto-configurations without owning a fake business repository.
+
+The starter also registers Mongo auto-configuration directly through Boot metadata, independently
+of `MongoPersistenceConfig`. A module-level `AutoConfigurationImportFilter`, registered through
+Boot 4's `META-INF/spring.factories` discovery path, must exclude the Boot 4 sync/reactive client,
+data, repository, health, and metrics Mongo auto-configurations while the enable property is absent
+or false. It must allow them unchanged when the property is true; consumers must not need to set
+`spring.autoconfigure.exclude`.
+
+Replacement tests must prove:
+
+- an actual `@EnableAutoConfiguration` context in default/false mode creates no Mongo
+  infrastructure;
+- properties bind the enable flag;
+- enabled mode can create the infrastructure with a supplied mock `MongoClient`, without a real
+  network connection;
+- production source contains no `Example*` type.
+
+The Testcontainers dependencies leave this module when the example repository IT is removed.
+
+## 8. Correlation context boundary
+
+`application-core` owns a framework-free `CorrelationIdPort` whose read result is optional.
+`adapter:inbound:web` implements it from the sanitized request MDC correlation key.
+`CreateWorkLogUseCase` and `PosterEventPublisher` depend only on the port and preserve the current
+fallback to the generated event id when no correlation id exists.
+
+Tests first pin present/blank/absent behavior and prove the sample application packages no longer
+import SLF4J/MDC. Diagnostic storage remains an adapter concern.
+
+## 9. Runtime composition and generated state
+
+`app-bootstrap` keeps its current default runtime modules. Its build description and README must
+state that optional leaves require an explicit registry and composition-root dependency change.
+Optional adapters remain independently buildable and testable.
+
+The tracked four-byte `src/sample-portfolio/.jqwik-database` is generated runtime state. Delete it
+and add `.jqwik-database` to `src/.gitignore`; retain jqwik itself because property tests use it.
+
+## 10. Verification
+
+Run focused compile/tests before and after each dependency group. Regenerate locks only through
+each affected leaf's `:leaf-path:resolveAndLockAll --write-locks` task, then run:
+
+```bash
+cd src
+./gradlew check --console=plain
+./gradlew test --console=plain
+./gradlew verifyCleanArchitectureDependencies --console=plain
+./gradlew verifyApplicationCoreDependencyPurity --console=plain
+./gradlew verifyConfigurationPropertiesProcessor --console=plain
+./gradlew verifyDependencyLocks --console=plain
+./gradlew verifyPublicPathSnapshot verifyEnvKeys --console=plain
+```
+
+Completion requires fresh review, `git diff --check`, and an LLM Wiki branch note or an explicit
+capture blocker for the mandated exact vault path.

docs/superpowers/specs/2026-07-28-fileserver-r2-control-plane-provider-selection-design.md

@@ -0,0 +1,415 @@
+# Fileserver R2 Control Plane and Provider Selection Design
+
+- Date: 2026-07-28
+- Status: 승인된 설계, 구현 전
+- Scope: provider-neutral R2 control plane, explicit destination/provider selection, first
+  `local-persistent` qualification provider
+- Parent:
+  [Fileserver Production Capability Deep Design](2026-07-26-fileserver-production-capability-design.md)
+
+## 1. 목표
+
+현재 `LocalFilePublicationAdapter`의 single-node process-restart R1을 운영 topology의 기본값으로
+승격하지 않는다. 이번 increment는 다음을 구현한다.
+
+1. application에는 기존 provider-neutral `FilePublicationPort`만 유지한다.
+2. adapter 내부에 destination binding, provider descriptor, durable operation/manifest/reference
+   control plane을 둔다.
+3. 활성화된 Fileserver는 정확한 destination과 provider를 명시해야 하며 implicit local fallback을
+   금지한다.
+4. 첫 qualification provider로 pre-provisioned persistent filesystem을 사용하는
+   `local-persistent`를 구현한다.
+5. `shared-mounted`와 `sftp`가 같은 control-plane state machine을 재사용할 수 있게 하되 이번
+   increment에서 가짜 provider나 동작하지 않는 bean을 만들지 않는다.
+
+`local-persistent`는 container writable layer나 임시 디렉터리를 의미하지 않는다. 단일 노드 또는
+node-attached persistent volume과 private owner boundary가 증명된 환경만 대상으로 한다.
+
+## 2. 비범위
+
+이번 increment에 포함하지 않는다.
+
+- NFS 또는 다른 shared mount의 multi-client correctness;
+- SFTP SDK, connection pool, credential, OpenSSH qualification;
+- cross-node producer fencing;
+- background reaper, retention delete, quota reservation;
+- metrics/tracing/health implementation;
+- optional content read/delete/list API;
+- object storage. Object storage는 별도 outbound leaf의 책임이다.
+
+이 항목은 seam만 만들지 않는다. 실제 semantic provider를 구현하는 후속 increment에서만
+dependency, bean, setting을 추가한다.
+
+## 3. 검토한 접근
+
+### A. 현재 local adapter를 바로 R2로 표시
+
+설정과 change surface는 작지만 provider selector, terminal manifest, opaque-reference direct
+lookup과 strict startup evidence가 없다. R2를 과장하므로 선택하지 않는다.
+
+### B. Local, NFS, SFTP를 동시에 구현
+
+최종 기능은 많지만 서로 다른 보장과 real-service CI가 한 change surface에 결합된다. NFS와
+OpenSSH 인프라가 없으면 검증되지 않은 provider가 남으므로 선택하지 않는다.
+
+### C. Provider-neutral control plane + local-persistent 첫 qualification
+
+공통 state machine과 binding을 먼저 고정하고 한 provider를 실제 crash/security 테스트로
+qualification한다. 이후 provider가 control-plane 계약을 재사용하면서도 각자의 보장을 별도로
+증명할 수 있다. 이 접근을 선택한다.
+
+## 4. 계층과 모듈 경계
+
+```text
+application-core
+  FilePublicationPort
+  FilePublishRequest
+  FilePublishReceipt
+          |
+          v
+adapter:outbound:fileserver
+  RoutingFilePublicationAdapter
+          |
+          +-- DestinationBindingRegistry
+          +-- FilePublicationProviderRegistry
+          +-- DurablePublicationCoordinator
+          +-- ProviderControlPlane
+                    |
+                    +-- LocalPersistentPublicationProvider
+```
+
+- application/domain에는 provider ID, filesystem path, manifest locator, Spring 또는 NIO 타입을
+  추가하지 않는다.
+- `RoutingFilePublicationAdapter`만 production `FilePublicationPort` bean이다.
+- provider와 control-plane SPI는 fileserver package 내부 타입이다. 범용 filesystem/SDK API를
+  public bean으로 노출하지 않는다.
+- `shared-mounted`와 `sftp` 타입 값은 구현 전까지 accepted setting으로 등록하지 않는다.
+
+## 5. Application 계약 변경
+
+기존 request와 opaque reference를 유지한다. R2 provider가 달성한 보장을 정확히 보고할 수 있도록
+`FilePublishReceipt.DurabilityGuarantee`에 다음 값만 추가한다.
+
+```text
+FILE_AND_DIRECTORY_SYNC
+```
+
+이 값은 startup probe와 process-crash qualification을 모두 통과한 provider만 반환한다.
+호출한 sync가 물리 device, volume replica 또는 storage-controller power-loss protection까지
+완료됐다는 뜻은 아니다. 그 축은 deployment/storage evidence로 별도 판정한다.
+`PROCESS_LOCAL_SYNC` 또는 `PROVIDER_ACK_ONLY`를 요구 보장보다 약한 상태에서 자동으로 R2 값으로
+올리지 않는다.
+
+새 opaque reference 형식은 다음 의미를 가지되 application은 내부 segment를 해석하지 않는다.
+
+```text
+fsr1.<route-token>.<file-id>.<check-digits>
+```
+
+- `route-token`: startup에서 생성된 bounded destination route allowlist 값;
+- `file-id`: CSPRNG 128-bit 이상;
+- `check-digits`: accidental truncation/corruption 검출;
+- provider locator, operation ID, tenant/user ID, host/path는 포함하지 않는다.
+
+Reference는 authorization token이 아니다. authorization은 application use case의 책임이다.
+
+## 6. 명시적 설정과 선택
+
+새 canonical prefix는 `app.fileserver`다.
+
+```yaml
+app:
+  fileserver:
+    enabled: false
+    destinations:
+      local-export:
+        provider-ref: local-primary
+        required-publication: unique-atomic-create
+        required-durability: file-and-directory-sync
+        maximum-rows: 1000000
+        maximum-encoded-bytes: 1073741824
+    providers:
+      local-primary:
+        type: local-persistent
+        root-directory: ${APP_FILESERVER_LOCAL_ROOT:}
+        auto-create: false
+        strict-path-security: true
+        expected-file-store-name: ${APP_FILESERVER_LOCAL_EXPECTED_FILE_STORE_NAME:}
+        expected-file-store-type: ${APP_FILESERVER_LOCAL_EXPECTED_FILE_STORE_TYPE:}
+        mount-sentinel-name: .ca-fileserver-volume
+        mount-sentinel-sha256: ${APP_FILESERVER_LOCAL_MOUNT_SENTINEL_SHA256:}
+        expected-owner: ${APP_FILESERVER_LOCAL_EXPECTED_OWNER:}
+        maximum-root-mode: "0750"
+```
+
+규칙:
+
+- `enabled=true`이면 destination과 provider가 각각 하나 이상 필요하다.
+- 모든 destination은 존재하는 provider 하나를 참조한다.
+- request destination에 binding이 없으면 producer 호출 전에 실패한다.
+- provider type의 기본값은 없다.
+- `local-persistent` root는 absolute, existing, pre-provisioned directory여야 한다.
+- `auto-create=true`는 `local-persistent`에서 거부한다.
+- root와 mount sentinel은 operator가 미리 만든다. Root attestation이 끝난 뒤 adapter가 private
+  top-level control/data directory와 bounded hash shard를 restrictive POSIX creation mode로
+  생성할 수 있으며, 생성할 때마다 parent identity와 directory sync를 확인한다.
+- container ephemeral 경로를 위한 `local-dev`는 별도 후속 profile이다. production 설정과
+  같은 guarantee를 공유하지 않는다.
+- 기존 `ca-skeleton.fileserver.*`는 R1/legacy compatibility selector로만 남는다. 새 R2 설정과
+  동시에 활성화되면 startup을 실패시킨다. 암묵 migration이나 precedence를 두지 않는다.
+
+## 7. Startup capability compilation
+
+application traffic을 받기 전에 destination별 effective descriptor를 한 번 compile한다.
+
+`local-persistent`는 다음을 모두 검증한다.
+
+1. root와 모든 ancestor가 symbolic link가 아니다.
+2. root real path가 설정 absolute path와 일치한다.
+3. configured owner와 실제 owner가 일치한다.
+4. POSIX permission이 configured maximum보다 넓지 않고 group/world writable이 아니다.
+5. `FileStore.name()`과 `type()`이 설정 값과 일치한다.
+6. mount sentinel이 regular no-follow file이고 configured SHA-256와 일치한다.
+7. data, staging, operations, manifests, references, quarantine directory가 같은
+   `FileStore`에 있다.
+8. control directory는 private owner boundary이며 symlink가 아니다.
+9. `SecureDirectoryStream`을 열 수 있다.
+10. exclusive create, file force, hard-link create, directory force가 private probe directory에서
+    성공한다.
+
+Probe artifact는 unique name만 사용하며 successful cleanup과 parent directory force까지
+완료해야 한다. Probe 실패는 capability downgrade가 아니라 startup failure다.
+
+JDK가 directory-relative hard-link primitive를 제공하지 않으므로 hard-link publish는 다음
+boundary에서만 허용한다.
+
+- root/control/data directories가 adapter owner 전용이고 untrusted writer가 없음;
+- publish 직전과 직후 root identity, directory file key, mount sentinel을 다시 확인;
+- target은 CSPRNG unique name;
+- pre/post identity가 바뀌면 성공을 반환하지 않고 `PUBLISH_INDETERMINATE`;
+- privileged host administrator 또는 same-owner malicious process와의 경쟁은 guarantee 범위가
+  아니며 deployment isolation requirement로 기록한다.
+
+untrusted writer가 같은 root에 entry를 만들 수 있는 환경은 strict local R2가 아니다.
+
+## 8. Durable control plane
+
+```text
+.ca-fileserver/
+  operations/<prefix>/<operation-id>.json
+  manifests/<prefix>/<file-id>.json
+  references/<prefix>/<file-id>.json
+  staging/<prefix>/<operation-id>.part
+  quarantine/
+  probe/
+data/<prefix>/<generated-file-name>
+```
+
+모든 locator는 validated single segment 또는 adapter가 생성한 bounded relative segment다.
+Caller path를 받지 않는다.
+
+### 8.1 Operation journal v2
+
+필수 필드:
+
+```text
+schemaVersion
+stateRevision
+state
+operationId
+requestFingerprint
+effectivePolicyRevision
+effectivePolicyDigest
+destinationId
+providerId
+fileId
+routeToken
+publishedFileName
+stageFileName
+byteSize
+rowCount
+columnCount
+sha256
+formulaMitigatedCount
+manifestDigest
+referenceDigest
+createdAt
+sealedAt
+publishedAt
+lastFailureCode
+receiptSnapshot
+```
+
+State는 `WRITING`, `SEALED`, `DATA_PUBLISHED`, `MANIFEST_PUBLISHED`,
+`REFERENCE_PUBLISHED`, `PUBLISHED`, `QUARANTINED`다.
+
+### 8.2 Private manifest v1
+
+Manifest는 operation/file/provider/reference/fingerprint, schema·format·policy digest, byte/count,
+SHA-256, achieved guarantees, internal relative locator를 기록한다. Absolute path, raw row/cell,
+credential, raw tenant/user ID는 저장하지 않는다.
+
+### 8.3 Reference index v1
+
+Reference index는 opaque `file-id`에서 operation ID, file version, manifest digest와 internal
+relative locator로 direct lookup한다. Directory scan은 receipt restoration의 authority가 아니다.
+
+### 8.4 Record update
+
+각 control record는:
+
+1. sibling private temp file을 `CREATE_NEW`;
+2. bounded canonical JSON encoding;
+3. file `force(true)`;
+4. same-directory atomic replace;
+5. parent directory force;
+6. read-back schema/revision/digest verification;
+
+순서로 갱신한다. 낮은 revision, fingerprint mismatch, newer schema는 자동 덮어쓰지 않는다.
+
+## 9. Publication ordering
+
+```text
+J-WRITING
+  -> stage stream/force
+J-SEALED
+  -> exclusive hard-link data publish
+  -> data directory force
+J-DATA_PUBLISHED
+  -> private manifest publish/force
+J-MANIFEST_PUBLISHED
+  -> reference index publish/force
+J-REFERENCE_PUBLISHED
+  -> terminal journal + receipt snapshot publish/force
+J-PUBLISHED
+  -> receipt return
+```
+
+- Producer는 accepted attempt에서 최대 한 번 호출한다.
+- `SEALED` 이후 retry/recovery는 staged bytes만 사용한다.
+- terminal journal force 전에는 receipt를 반환하지 않는다.
+- target collision, digest mismatch 또는 root identity change는 자동 overwrite하지 않는다.
+- final data가 있어도 manifest/reference가 없으면 아직 terminal success가 아니다.
+
+## 10. Deterministic recovery
+
+Recovery는 operation ID direct lookup으로 실행하며 startup full scan에 의존하지 않는다.
+
+| 확인된 상태 | 조치 |
+| --- | --- |
+| terminal journal + matching manifest/reference/data | 저장된 receipt 복원 |
+| SEALED + valid stage, data 없음 | data publication부터 재개 |
+| SEALED + matching data | manifest publication부터 재개 |
+| DATA_PUBLISHED + matching data | manifest publication 재개 |
+| MANIFEST_PUBLISHED + matching manifest/data | reference publication 재개 |
+| REFERENCE_PUBLISHED + all matching | terminal journal 완성 |
+| data digest mismatch | `QUARANTINED`, integrity failure |
+| marker/manifest/reference schema newer | 보존 후 fail-fast/quarantine |
+| fingerprint conflict | typed conflict, 기존 artifact 보존 |
+| root/mount identity change | indeterminate, write/recovery 중단 |
+
+Truth priority:
+
+```text
+matching data + private manifest + reference
+  > terminal operation record
+  > non-terminal operation record
+  > in-memory state
+```
+
+모순이 있으면 임의 성공이나 삭제 대신 quarantine evidence를 기록한다.
+
+## 11. Compatibility
+
+- R1 journal schema v1은 읽을 수 있어야 한다.
+- R1 terminal receipt는 기존 `PROCESS_LOCAL_SYNC` 보장 그대로 복원한다.
+- R1 artifact를 자동으로 R2 manifest/reference로 승격하지 않는다.
+- R2 writer는 journal v2만 생성한다.
+- 기존 overwrite-capable legacy port는 별도 root와 opt-in을 유지하며 R2 control plane에 접근하지
+  않는다.
+- R1과 R2 selector가 동시에 활성화되면 ambiguous composition으로 startup을 실패시킨다.
+
+## 12. Failure semantics
+
+- 설정/보장 mismatch: startup failure;
+- destination 없음: producer 전 deterministic request failure;
+- stage 이전 capacity/validation failure: not applied;
+- stage/write failure: failed, partial stage는 recovery evidence가 아니면 정리;
+- sealed 이후 filesystem timeout/IO/root identity change: indeterminate;
+- published data와 metadata 불일치: integrity/quarantine;
+- journal/control record corruption: provider exception을 노출하지 않고 typed indeterminate;
+- guarantee를 낮춰 성공시키는 fallback은 없다.
+
+## 13. 테스트와 증거
+
+### 13.1 Unit/contract
+
+- exact destination/provider selection과 no-default;
+- R1/R2 simultaneous activation rejection;
+- reference grammar/check digits/forged route rejection;
+- journal v2, manifest, reference canonical round-trip;
+- state revision과 fingerprint conflict;
+- achieved durability value invariants.
+
+### 13.2 Local integration
+
+- pre-provisioned root requirement;
+- owner/mode/FileStore/sentinel mismatch startup failure;
+- symlink ancestor/control/data rejection;
+- staging/final/control same `FileStore`;
+- successful capability probe와 cleanup;
+- partial final visibility 0건;
+- same operation concurrency와 producer once;
+- target collision no overwrite;
+- data/manifest/reference digest mismatch quarantine.
+
+### 13.3 Crash qualification
+
+Forked JVM helper를 사용해 다음 force boundary 직후 process를 강제 종료하고 새 JVM에서 같은
+operation을 재시도한다.
+
+```text
+J-WRITING
+stage force
+J-SEALED
+data link
+data directory force
+manifest force
+manifest directory force
+reference force
+reference directory force
+terminal journal force
+terminal journal directory force
+```
+
+각 boundary에서 결과는 다음 중 하나여야 한다.
+
+- producer 재실행 없이 동일 receipt 복원;
+- verified sealed bytes로 publication 완성;
+- typed indeterminate/quarantine.
+
+partial final, overwrite, 다른 receipt, silent guarantee downgrade는 허용하지 않는다.
+
+### 13.4 플랫폼
+
+- Linux/POSIX + `SecureDirectoryStream` + directory force qualification lane에서만
+  `FILE_AND_DIRECTORY_SYNC`을 검증한다.
+- capability가 없는 일반 unit-test filesystem에서는 R1 보장만 테스트하며 R2 service test를
+  skip 성공으로 처리하지 않는다.
+
+## 14. 완료 기준
+
+이번 increment의 완료는 “Fileserver 전체가 모든 운영환경에서 R2”라는 뜻이 아니다.
+
+완료를 주장하려면:
+
+1. provider 기본값 없이 exact binding이 동작한다.
+2. `local-persistent` startup probe가 모든 required capability를 증명한다.
+3. terminal manifest/reference direct lookup이 구현된다.
+4. 모든 publication force boundary의 crash test가 deterministic result를 낸다.
+5. strict path/mount identity/security tests가 통과한다.
+6. public path와 clean architecture gate가 통과한다.
+7. R1 compatibility artifact를 R2로 자동 승격하지 않는다.
+8. 문서와 receipt는 `local-persistent` qualification만 R2라고 표시한다.
+
+후속 순서는 Phase 3 maintenance/resource limits, Phase 4 SFTP, Phase 5 shared-mounted/NFS evidence다.