From 3f72ae7df97f200e0a5af1aa99c79f9411661420 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 21:17:39 +0900 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20adapter=20kernel=20?= =?UTF-8?q?=EC=84=A4=EB=AA=85=EC=9D=84=20=EC=8B=A4=EC=A0=9C=20platform=20?= =?UTF-8?q?=ED=8F=B4=EB=8D=94=20=EB=82=B4=EC=9A=A9=EC=97=90=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: layers.md와 .dependency-cruiser.json 규칙 주석은 kernel (src/adapters/platform/**)을 "clock, abort primitive, capacity guard"로만 적는다(0929/05-08). 실제 폴더에는 IndexedDB 연결·트랜잭션, Retry-After, JSON member scanner와 bootstrap만 쓰는 lifecycle runtime·mutation intent factory까지 10개 파일이 있다. 편입 기준("must never own")은 indexeddb-connection.ts 머리 주석에만 있어, 폴더에 무엇을 넣어도 되는지 문서로는 알 수 없다. 고른 방법: 리뷰 5.3절 (b). 두 곳의 설명을 실제 목록으로 고치고, 공유 메커니즘과 bootstrap 전용 서비스를 나눠 적고, 기준이 있는 위치를 가리킨다. 파일을 옮기는 (c)·(d)는 하지 않았다(1101/05-04, 남음). 위험·한계: 문서와 규칙 주석만 바꾼다. 규칙 동작은 같다. 폴더에 무엇을 넣을지를 기계가 보지 않는 것은 그대로다. 검증: check:architecture, verify:documentation 통과. bootstrap 밖에서 lifecycle·mutation intent factory를 쓰는 곳이 없음을 grep으로 확인했다. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-08 --- .dependency-cruiser.json | 2 +- docs/architecture/layers.md | 10 ++++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 133c1641..c3c50d5d 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -251,7 +251,7 @@ }, { "name": "adapters-do-not-know-other-concrete-adapters", - "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (clock, abort primitive, capacity guard), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", + "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", "severity": "error", "from": { "path": "^src/adapters/([^/]+)/" diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index 973e6e6a..63d25c2c 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -80,8 +80,14 @@ passing. which is shared on purpose and is the only adapter code an adapter may reach across a group for: -- `src/adapters/platform/**` — the system clock, the shared abort primitive and - the bounded-capacity guard +- `src/adapters/platform/**` — mechanisms more than one adapter group shares: + the system clock, the shared abort primitive, the bounded-capacity guard, + the IndexedDB connection and transaction helpers, `Retry-After` parsing and + the JSON member scanner. Two bootstrap-only platform services live there + too: the browser lifecycle runtime and the mutation intent factory (no + adapter imports them). A kernel file owns mechanics only, never names, + schemas, failure codes or observation shapes; the full list of what it must + never own is at the top of `indexeddb-connection.ts` - `src/adapters/browser-file-storage/result.ts` — the browser-data result and failure constructors - `src/adapters/cross-context-invalidation/index.ts` — the cross-context