feat: 가상화 문서들 추가

2026-09-10 08:54:05 +09:00
parent e9f6a93327
commit 43e1aadef0
695 changed files with 153404 additions and 12754 deletions
@@ -1,106 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="680" height="809" viewBox="0 0 680 809" role="img" aria-labelledby="diagram-title diagram-description">
-<title id="diagram-title">커밋 요청 뒤의 결과 판정</title>
-<desc id="diagram-description">tracker 가 COMMIT_REQUESTED 를 관측한 뒤 provider commit 을 호출한다. 예외가 없으면 Committed 다. RuntimeException 이 오면 먼저 commitAcknowledged 를 보고, 이미 afterCommit 이 왔으면 CommittedWithPostCommitFailure 다. 그렇지 않으면 rolledBack 과 UnexpectedRollbackException 과 replay 후보 여부를 보고, 하나라도 성립하면 DeterminateRollback 이다. 어느 것도 성립하지 않으면 Indeterminate 로 남는다.</desc>
-<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;commit-evidence-phase-machine&quot;,&quot;profile&quot;:&quot;component-flow&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;docs/clean-architecture-backend-template/final/document.md&quot;,&quot;document_sha256&quot;:&quot;74b4986fd8621f6fd61791232777dc0e6c8ef999cbc2343df050bd5921ea03ac&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;heading&quot;,&quot;value&quot;:&quot;3.2 트랜잭션 — `application-core` 포트에서 PostgreSQL local timeout까지&quot;,&quot;line&quot;:352}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
-<defs>
-  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-    <path d="M 0 0 L 10 5 L 0 10 z" />
-  </marker>
-  <style>
-    :root { color-scheme: light; }
-    text { font-family: Inter, Pretendard, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #111827; }
-    .canvas { fill: #ffffff; }
-    .group-box { fill: #ffffff; stroke: #9ca3af; stroke-width: 1.4; stroke-dasharray: 7 5; }
-    .group-label-bg { fill: #ffffff; }
-    .group-label { font-size: 13px; font-weight: 650; fill: #374151; }
-    .edge { fill: none; stroke: #374151; stroke-width: 1.8; stroke-linejoin: round; stroke-linecap: round; marker-end: url(#arrow); }
-    .edge.style-dashed, .edge.semantic-dashed, .edge.assumption { stroke-dasharray: 7 5; }
-    .edge.style-dotted { stroke-dasharray: 2 5; }
-    .edge.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
-    .edge.emphasis-muted { stroke: #9ca3af; }
-    .edge.emphasis-warning, .edge.kind-failure, .edge.kind-error { stroke: #dc2626; stroke-width: 2.2; }
-    .edge-label-bg { fill: #ffffff; }
-    .edge-label { font-size: 12px; font-weight: 560; text-anchor: middle; }
-    .node-shape { fill: #ffffff; stroke: #4b5563; stroke-width: 1.7; }
-    .node-shape.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
-    .node-shape.emphasis-muted { stroke: #9ca3af; fill: #f9fafb; }
-    .node-shape.emphasis-warning { stroke: #d97706; stroke-width: 2; fill: #fffdf5; }
-    .node-shape.kind-database, .node-shape.kind-datastore, .node-shape.kind-storage { fill: #f8fafc; }
-    .node-shape.kind-queue, .node-shape.kind-event, .node-shape.kind-topic { fill: #fafafa; }
-    .node-shape.assumption { stroke-dasharray: 4 4; }
-    .storage-bottom, .controller-divider { fill: none; stroke: #4b5563; stroke-width: 1.4; }
-    .controller-led { fill: #4b5563; }
-    .actor-symbol { fill: none; stroke: #4b5563; stroke-width: 1.8; stroke-linecap: round; }
-    .actor-symbol.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
-    .node-label { font-size: 14px; font-weight: 650; text-anchor: middle; }
-    .node-role { font-size: 10px; letter-spacing: 0.04em; text-anchor: middle; fill: #6b7280; }
-    .node-detail-divider { stroke: #d1d5db; stroke-width: 1; }
-    .node-detail { font-size: 11px; fill: #374151; }
-    .assumption-badge { font-size: 9px; font-weight: 700; fill: #92400e; }
-    .failure-mark { stroke: #dc2626; stroke-width: 4; stroke-linecap: round; }
-    .lifeline { stroke: #9ca3af; stroke-width: 1.2; stroke-dasharray: 5 5; }
-    .timeline-axis { stroke: #374151; stroke-width: 1.8; marker-end: url(#arrow); }
-    .timeline-stem { stroke: #6b7280; stroke-width: 1.3; }
-    .timeline-marker { fill: #ffffff; stroke: #374151; stroke-width: 1.7; }
-    .timeline-marker.primary { fill: #2563eb; stroke: #2563eb; }
-    .timeline-marker.warning { fill: #dc2626; stroke: #dc2626; }
-    .timeline-label { font-size: 13px; font-weight: 650; text-anchor: middle; }
-    .timeline-detail { font-size: 11px; fill: #4b5563; text-anchor: middle; }
-  </style>
-</defs>
-<rect class="canvas" width="680" height="809" />
-<polyline class="edge kind-data style-solid emphasis-normal" points="202.0,444.0 202.0,492.0 192.0,492.0 192.0,540.0" data-evidence="401-402" />
-<rect class="edge-label-bg" x="141.1" y="450.0" width="111.8" height="22" rx="3" />
-<text class="edge-label" x="197.0" y="465.0">afterCommit 도착</text>
-<polyline class="edge kind-request style-solid emphasis-normal" points="316.0,124.0 316.0,172.0 316.0,172.0 316.0,220.0" data-evidence="397-399" />
-<rect class="edge-label-bg" x="284.1" y="158.0" width="111.8" height="22" rx="3" />
-<text class="edge-label" x="340.0" y="173.0">commit(status)</text>
-<polyline class="edge kind-response style-solid emphasis-normal semantic-dashed" points="325.0,284.0 325.0,332.0 426.0,332.0 426.0,380.0" data-evidence="388-388,396-400" />
-<rect class="edge-label-bg" x="349.8" y="290.0" width="51.5" height="22" rx="3" />
-<text class="edge-label" x="375.5" y="305.0">예외 없음</text>
-<polyline class="edge kind-data style-solid emphasis-primary" points="477.0,604.0 477.0,652.0 429.5,652.0 429.5,700.0" data-evidence="409-409" />
-<rect class="edge-label-bg" x="417.4" y="610.0" width="71.6" height="22" rx="3" />
-<text class="edge-label" x="453.2" y="625.0">판정 근거 없음</text>
-<polyline class="edge kind-data style-solid emphasis-normal" points="220.0,444.0 220.0,492.0 468.0,492.0 468.0,540.0" data-evidence="403-404" />
-<rect class="edge-label-bg" x="322.0" y="450.0" width="44.0" height="22" rx="3" />
-<text class="edge-label" x="344.0" y="465.0">미도착</text>
-<polyline class="edge kind-data style-solid emphasis-normal" points="459.0,604.0 459.0,652.0 211.0,652.0 211.0,700.0" data-evidence="404-407" />
-<rect class="edge-label-bg" x="302.6" y="610.0" width="64.9" height="22" rx="3" />
-<text class="edge-label" x="335.0" y="625.0">하나라도 성립</text>
-<polyline class="edge kind-response style-solid emphasis-normal semantic-dashed" points="307.0,284.0 307.0,332.0 211.0,332.0 211.0,380.0" data-evidence="400-401" />
-<rect class="edge-label-bg" x="196.4" y="290.0" width="125.2" height="22" rx="3" />
-<text class="edge-label" x="259.0" y="305.0">RuntimeException</text>
-<g id="node-commit-requested">
-<rect class="node-shape kind-process emphasis-normal role-source" data-evidence="397-397" x="241.0" y="60.0" width="150.0" height="64.0" rx="7" />
-<text class="node-label" x="316.0" y="90.0">COMMIT_REQUESTED</text>
-</g>
-<g id="node-provider-commit">
-<rect class="node-shape kind-service emphasis-normal role-service" data-evidence="398-400" x="241.0" y="220.0" width="150.0" height="64.0" rx="7" />
-<text class="node-label" x="316.0" y="250.0">provider commit</text>
-</g>
-<g id="node-ack-check">
-<rect class="node-shape kind-process emphasis-normal role-service" data-evidence="401-401" x="131.0" y="380.0" width="160.0" height="64.0" rx="7" />
-<text class="node-label" x="211.0" y="410.0">commitAcknowledged</text>
-</g>
-<g id="node-committed">
-<rect class="node-shape kind-result emphasis-normal role-sink" data-evidence="388-388,396-400" x="351.0" y="380.0" width="150.0" height="64.0" rx="7" />
-<text class="node-label" x="426.0" y="410.0">Committed</text>
-</g>
-<g id="node-post-commit-failure">
-<rect class="node-shape kind-result emphasis-normal role-sink" data-evidence="402-402" x="70.0" y="540.0" width="244.0" height="64.0" rx="7" />
-<text class="node-label" x="192.0" y="570.0">CommittedWithPostCommitFailure</text>
-</g>
-<g id="node-rollback-check">
-<rect class="node-shape kind-process emphasis-normal role-service" data-evidence="404-406" x="374.0" y="540.0" width="188.0" height="64.0" rx="7" />
-<text class="node-label" x="468.0" y="570.0">rolledBack · replay 후보</text>
-</g>
-<g id="node-determinate-rollback">
-<rect class="node-shape kind-result emphasis-normal role-sink" data-evidence="407-407" x="127.5" y="700.0" width="167.0" height="64.0" rx="7" />
-<text class="node-label" x="211.0" y="730.0">DeterminateRollback</text>
-</g>
-<g id="node-indeterminate">
-<rect class="node-shape kind-result emphasis-primary role-sink" data-evidence="391-391,409-409" x="354.5" y="700.0" width="150.0" height="64.0" rx="7" />
-<text class="node-label" x="429.5" y="730.0">Indeterminate</text>
-</g>
-</svg>
@@ -16,6 +16,7 @@ source:
  - src/app-bootstrap/src/main/resources/META-INF/spring.factories
  - final/document.md#a19
  - final/document.md#a05
+  - final/document.md#10-3
 ---

 # 마스터 스위치는 루트 하나가 소유하고 자식 설정은 조건을 갖지 않는다
@@ -13,6 +13,7 @@ source:
  - src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/persistencejpa/DataSourceRequirement.java
  - final/document.md#a05
  - final/document.md#a18
+  - final/document.md#10-3
 ---

 # 풀이 필요한지는 "JPA가 켜졌나"가 아니라 "커넥션이 필요한 capability가 있나"로 묻는다
@@ -13,6 +13,7 @@ source:
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/api/query/SignedJsonCursorCodec.java
  - src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/policy/streaming/GrpcResumeTokenCodec.java
  - final/document.md#a05
+  - final/document.md#10-4
 ---

 # 커서에 서명하는 이유는 기밀성이 아니라 무결성이다
@@ -16,6 +16,7 @@ source:
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/tenant/TenantId.java
  - final/document.md#a02
  - final/document.md#a05
+  - final/document.md#10-4
 ---

 # tenant id는 메트릭 태그가 되지 않는다
@@ -11,8 +11,7 @@ studio: ""
 lastVerifiedOn: 2026-08-29
 source:
  - final/document.md#4-1
-  - final/document.md#a05 §136
-  - final/document.md#a05 §139
+  - final/document.md#a05
 sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
 evidence:
  - ../../../final/evidence/raw/050-jpa-commit-ambiguity-probe.txt
@@ -16,7 +16,7 @@ source:
 sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
 assets:
  - key: commit-evidence-phase-machine
-    file: ../../../final/assets/tech-log-studio/commit-evidence-phase-machine.svg
+    file: ../../../final/assets/commit-evidence-phase-machine/commit-evidence-phase-machine.svg
 ---

 # 트랜잭션 결과 대수 — 다섯 변형이 각각 답하는 질문
@@ -16,6 +16,7 @@ source:
  - final/document.md#a05
  - final/document.md#a19
  - final/document.md#a20
+  - final/document.md#10-5
 ---

 # 지원 등급은 추론이 아니라 선언이고 증거 없이는 올라가지 않는다
@@ -15,6 +15,8 @@ source:
  - src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/DefaultRetryEligibilityEngine.java
  - docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md
  - final/document.md#a11
+  - final/document.md#10-2
+  - final/document.md#a20-grpc-core-api
 ---

 # 재시도 안전성은 증거에 기반해 판정한다
@@ -15,6 +15,7 @@ source:
  - src/grpc/CLAUDE.md
  - docs/compatibility/grpc-support-matrix.md
  - final/document.md#a20
+  - final/document.md#2-3
 ---

 # gRPC 플랫폼은 build-only로 두고 애플리케이션 도달 경로를 먼저 정한다
@@ -13,6 +13,7 @@ source:
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/ExperimentalFeatureGate.java
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/multitenancy/RlsTenantSessionBinder.java
  - final/document.md#a05
+  - final/document.md#10-3
 ---

 # 클래스패스에 있는 것은 실행 동의가 아니다
@@ -13,6 +13,7 @@ source:
  - src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V6__capability_schema_registry_adoption.sql
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/NotificationSchemaActivation.java
  - final/document.md#a05
+  - final/document.md#4-1
 ---

 # capability는 스키마 적용과 사용 승인을 분리한다
@@ -13,6 +13,7 @@ source:
  - src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlPersistenceConfig.java
  - final/document.md#a05
+  - final/document.md#4-1
 ---

 # Flyway가 스키마를 소유하고 런타임 롤은 DDL 권한을 갖지 않는다
@@ -14,6 +14,7 @@ source:
  - src/gradle/jpa-evidence.gradle
  - final/document.md#a16
  - final/document.md#a19
+  - final/document.md#10-5
 ---

 # 능력 등급은 코드가 아니라 실행된 증거에서 파생한다
@@ -9,7 +9,7 @@
  },
  "ssotSha256": "74b4986fd8621f6fd61791232777dc0e6c8ef999cbc2343df050bd5921ea03ac",
  "sourceRevision": "21234e38cdb9a926cbc92bb97a2aee2e4a7d2916",
-  "generatedAt": "2026-09-07",
+  "generatedAt": "2026-09-08",
  "candidateScope": {
    "document": "final/document.md",
    "sections": [
@@ -852,7 +852,8 @@
            "decision-status": "`ADOPTED`",
            "source": [
              "`final/document.md#10-3`",
-              "`final/document.md#a05` §14.1"
+              "`final/document.md#a05` §14.1",
+              "`final/document.md#a18` §5"
            ],
            "decision-evidence": [
              "`.../app-bootstrap/.../persistencejpa/DataSourceRequirement.java`의 `reasons(environment)` 6개 조건과 javadoc"
@@ -3420,7 +3421,7 @@
            "readiness": "READY",
            "decision-status": "`ADOPTED`",
            "source": [
-              "`final/document.md#4-1`, `#10-3`",
+              "`final/document.md#4-1`",
              "`final/document.md#a05` §8.1, §12.1"
            ],
            "decision-evidence": [
@@ -3826,7 +3827,7 @@
            "source": [
              "`final/document.md#10-2`",
              "`final/document.md#a11` §51",
-              "`final/document.md#a20` §2.4"
+              "`final/document.md#a20-grpc-core-api` §1"
            ],
            "decision-evidence": [
              "`.../httpclient/.../TransportFailure.java`의 `notSent`/`sentNoResponse` 팩토리와 그 javadoc",
@@ -5207,7 +5208,7 @@
      "id": "P1-flyway-owns-the-schema",
      "kindCandidate": "DECISION",
      "sourceRefs": [
-        "`final/document.md#4-1`, `#10-3`"
+        "`final/document.md#4-1`"
      ],
      "summary": "Flyway가 스키마를 소유하고 런타임 롤은 DDL 권한을 갖지 않는다",
      "disposition": "PROMOTE",
@@ -12,6 +12,7 @@ decidedOn: 2026-08-30
 source:
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java
  - final/document.md#a05
+  - final/document.md#3-2
 ---

 # inRootWrite는 suspend하지 않고 fail-fast한다
@@ -12,6 +12,7 @@ decidedOn: 2026-08-30
 source:
  - src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java
  - final/document.md#a05
+  - final/document.md#3-2
 ---

 # 트랜잭션 템플릿은 모드별로 미리 만들어 둔다
@@ -13,6 +13,7 @@ source:
  - src/gradle/jpa-evidence.gradle
  - src/config/jpa/readiness-cards.yaml
  - final/document.md#a05
+  - final/document.md#6-5
 ---

 # 후보 증거는 통과해도 R1에 머무르고 R2는 별도 게이트가 판정한다
@@ -14,6 +14,7 @@ source:
  - .github/workflows/messaging-certification.yml
  - src/build-logic/src/main/groovy/ca.strict-test-lane.gradle
  - final/document.md#a19
+  - final/document.md#6-4
 ---

 # 인증 레인만 Docker 가드를 달지 않는다
@@ -14,6 +14,7 @@ source:
  - src/adapter/outbound/persistence-jpa/build.gradle
  - final/document.md#a20
  - final/document.md#a05
+  - final/document.md#10-5
 ---

 # 성능 측정은 릴리스 게이트에 넣지 않는다