Merge branch 'main' into fix/session-subject-required

This commit is contained in:
2026-11-05 10:33:28 +00:00
467 changed files with 33365 additions and 4867 deletions
+81 -31
View File
@@ -2,6 +2,7 @@
"forbidden": [
{
"name": "domain-is-framework-neutral",
"comment": "domain holds framework-neutral models and pure policies. Keep the dependency out: move the code to application, or pass the value in from there.",
"severity": "error",
"from": {
"path": "^src/domain"
@@ -12,6 +13,7 @@
},
{
"name": "application-does-not-know-concrete-runtime",
"comment": "application owns use cases and the ports they need. Declare a port under src/application/ports and let src/bootstrap pass the concrete adapter.",
"severity": "error",
"from": {
"path": "^src/application"
@@ -22,6 +24,7 @@
},
{
"name": "presentation-does-not-know-adapters",
"comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.",
"severity": "error",
"from": {
"path": "^src/presentation/(?!adapters/query)"
@@ -32,6 +35,7 @@
},
{
"name": "page-templates-own-layout-only",
"comment": "Page templates own layout only. Take data and actions as props from the page that uses the template.",
"severity": "error",
"from": {
"path": "^src/presentation/templates"
@@ -42,6 +46,7 @@
},
{
"name": "icon-vendor-is-facade-only",
"comment": "VD-05. lucide-react is imported by the icon vendor facade only; product code uses the semantic icons from the design-system index, so replacing the vendor touches one file.",
"severity": "error",
"from": {
"path": "^src",
@@ -51,8 +56,34 @@
"path": "^lucide-react$"
}
},
{
"name": "zod-is-reached-through-contracts-zod",
"comment": "F-7 (13-08). src/contracts/zod.ts sets zod jitless before any schema is built, so the production CSP never sees zod's Function probe. Schema code imports z from there.",
"severity": "error",
"from": {
"path": "^src",
"pathNot": "^src/contracts/zod\\.ts$"
},
"to": {
"path": "^zod$"
}
},
{
"name": "design-system-is-reached-through-its-index",
"comment": "VD-05, 12-08. Code outside src/presentation/design-system imports its public index.ts only, so the primitives can change behind it. Named facades: src/presentation/components/ui/*.ts re-export the canonical primitives under their pre-VD-05 paths (VD-05 Rollback). Exception: src/presentation/templates/page-templates.tsx reads PaginationLandmarkContext, which index.ts does not export. Owner: frontend-platform. Revisit: export it from index.ts or move the page templates into the design system.",
"severity": "error",
"from": {
"path": "^src/",
"pathNot": "^src/presentation/(design-system/|components/ui/[^/]+\\.ts$|templates/page-templates\\.tsx$)"
},
"to": {
"path": "^src/presentation/design-system/",
"pathNot": "^src/presentation/design-system/index\\.ts$"
}
},
{
"name": "adapters-do-not-know-presentation",
"comment": "An adapter implements an application port. It never imports UI or the composition root; pass what it needs through the port or its factory arguments.",
"severity": "error",
"from": {
"path": "^src/adapters"
@@ -63,6 +94,7 @@
},
{
"name": "feature-domain-is-framework-neutral",
"comment": "A feature's domain is framework-neutral, like src/domain. Move the code to the feature's application, or pass the value in from there.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/domain"
@@ -73,6 +105,7 @@
},
{
"name": "feature-application-does-not-know-runtime",
"comment": "A feature's application declares the ports it needs. Put the port in the feature's application and implement it in the feature's adapters/; bootstrap wires the two.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/application"
@@ -83,6 +116,7 @@
},
{
"name": "feature-presentation-does-not-know-outbound-adapters",
"comment": "Feature presentation calls its application API. The feature's adapters/ are wired by bootstrap, so import the application facade instead.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/presentation"
@@ -93,6 +127,7 @@
},
{
"name": "feature-adapters-do-not-know-presentation",
"comment": "A feature adapter implements the feature's ports and never imports UI or the composition root. Pass what it needs through the port.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/adapters"
@@ -103,6 +138,7 @@
},
{
"name": "concrete-adapters-compose-only-in-bootstrap",
"comment": "Only src/bootstrap constructs concrete adapters. Depend on the application port or facade; bootstrap composes the adapter behind it.",
"severity": "error",
"from": {
"path": "^src/(domain|application|presentation|contracts)"
@@ -113,7 +149,7 @@
},
{
"name": "external-contract-package-single-import-path",
"comment": "§4.1: a generated service package may only be imported from src/features/<feature>/contracts/*-contract-contribution.ts",
"comment": "§4.1: a generated service package may only be imported from src/features/<feature>/contracts/*-contract-contribution.ts. Owner: frontend-platform.",
"severity": "error",
"from": {
"path": "^src",
@@ -125,7 +161,7 @@
},
{
"name": "presentation-does-not-fetch-directly",
"comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself",
"comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself. Call the application API; bootstrap composes the adapter behind it.",
"severity": "error",
"from": {
"path": "^src/(presentation|features/[^/]+/presentation)"
@@ -134,9 +170,20 @@
"path": "^src/adapters/(http|realtime|service-worker|web-worker|storage)"
}
},
{
"name": "unselected-realtime-runtime-is-not-composed",
"comment": "§9.2 / 12-10. Realtime and Web Push are NOT_SELECTED in the template (src/features/installed-runtime-capabilities.ts), so the composition root and the installed-feature registries do not import their concrete adapters. A project that selects one replaces this rule when it wires the runtime. Owner: frontend-platform.",
"severity": "error",
"from": {
"path": "^src/(bootstrap/|features/installed-feature-)"
},
"to": {
"path": "^src/adapters/(realtime|web-push)/"
}
},
{
"name": "generic-worker-has-no-network-or-credentials",
"comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth",
"comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth. Do the network call on the page side and post the data to the worker.",
"severity": "error",
"from": {
"path": "^src/adapters/web-worker"
@@ -180,7 +227,7 @@
},
{
"name": "generic-presentation-does-not-compose-the-product",
"comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Generic presentation reads the installed registries directly today; the paths below are the exact set that does so, frozen so the coupling cannot spread while the assembly is lifted into bootstrap.",
"comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Exception: the generic presentation modules in pathNot read the installed registries today. The list names exact files, so a new module that reads a registry fails the gate. Owner: frontend-platform. Revisit when the assembly is lifted into bootstrap; remove each file from the list as it stops reading the registries.",
"severity": "error",
"from": {
"path": "^src/presentation/",
@@ -192,7 +239,7 @@
},
{
"name": "adapters-do-not-know-other-concrete-adapters",
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. Only the adapter kernel is shared — `src/adapters/platform` (clock, abort primitive, capacity guard) and the browser-data result helpers. `query-cache` still reads two collaborator types from `cross-context-invalidation`; that edge is named here rather than left silent, and closes when those types are lifted to a port.",
"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/.",
"severity": "error",
"from": {
"path": "^src/adapters/([^/]+)/"
@@ -204,7 +251,7 @@
},
{
"name": "adapter-groups-are-reached-through-their-barrel",
"comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 도착점에서 1단계 중첩 index.ts를 허용한 이유는 storage/indexeddb와 storage/opfs가 각자 독립적으로 제거 가능한 런타임이고(scripts/test-browser-file-storage-runtime-removal.ts), 그래서 각자의 배럴이 곧 경계이기 때문이다.",
"comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 예외: 도착점에서 storage/indexeddb/index.ts와 storage/opfs/index.ts만 서브배럴로 허용한다. 두 폴더는 browser-file-storage 번들의 런타임이고, 제거 드릴(scripts/test-browser-file-storage-runtime-removal.ts)은 그 번들 전체(browser-file-storage, browser-files, browser-transfer, cache-storage, storage/indexeddb, storage/opfs)를 함께 지운다. 최상위 storage 배럴(Web Storage)은 그 뒤에도 남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개 경계다. 다른 2단계 index.ts는 공개 배럴이 아니다(리뷰 12-07). 담당: frontend-platform. 재검토: 새 런타임을 따로 제거할 수 있게 만들 때 그 서브배럴을 이 목록에 추가한다.",
"severity": "error",
"from": {
"path": "^src/",
@@ -212,7 +259,7 @@
},
"to": {
"path": "^src/adapters/[^/]+/",
"pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/[^/]+/[^/]+/index\\.ts$"
"pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/storage/(indexeddb|opfs)/index\\.ts$"
}
},
{
@@ -239,6 +286,30 @@
"pathNot": "^src/contexts/$1/"
}
},
{
"name": "feature-and-app-roots-do-not-reach-adapters",
"comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers the files outside a feature's layer folders (src/features/*.ts, src/features/<feature>/*.ts), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.",
"severity": "error",
"from": {
"path": "^src/(features/[^/]+\\.tsx?$|features/[^/]+/[^/]+\\.tsx?$|contexts/|apps/)",
"pathNot": "^src/features/feature-adapter-contribution\\.ts$"
},
"to": {
"path": "^src/adapters/"
}
},
{
"name": "presentation-does-not-import-apps-or-contexts",
"comment": "12-03. Apps and contexts compose features, including their runtime, so presentation importing them is a path around presentation-does-not-know-adapters. Exception: src/presentation/routes/app-router.tsx mounts the deployable app's route tree (src/apps/template-app.ts). Owner: frontend-platform. Revisit when the router is assembled in bootstrap together with the frozen generic-presentation-does-not-compose-the-product list.",
"severity": "error",
"from": {
"path": "^src/(presentation/|features/[^/]+/presentation/)",
"pathNot": "^src/presentation/routes/app-router\\.tsx$"
},
"to": {
"path": "^src/(apps|contexts)/"
}
},
{
"name": "observability-vendors-live-behind-adapters",
"comment": "Spec §24. Features, platform, application, domain, contracts and presentation emit observability only through the provider-neutral TelemetryPort. A vendor telemetry SDK may be imported only by an adapter-side transport under src/adapters.",
@@ -253,7 +324,7 @@
},
{
"name": "platform-kernel-is-product-neutral",
"comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Routing composes deployable-app descriptors by type and is the one named exception.",
"comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.",
"severity": "error",
"from": {
"path": "^src/platform/",
@@ -265,33 +336,12 @@
},
{
"name": "no-circular-dependencies",
"comment": "A cycle makes the modules impossible to load or remove one at a time. Move the shared part into a lower module that both import.",
"severity": "error",
"from": {},
"to": {
"circular": true
}
}
],
"options": {
"doNotFollow": {
"path": "node_modules"
},
"exclude": {
"path": "^(dist|artifacts|tests/fixtures)"
},
"enhancedResolveOptions": {
"exportsFields": [
"exports"
],
"conditionNames": [
"import",
"require",
"node",
"default"
]
},
"tsConfig": {
"fileName": "tsconfig.app.json"
}
}
]
}
+1 -1
View File
@@ -6,7 +6,7 @@
# Runtime configuration — API endpoints, auth mode, telemetry, capability
# switches — is NOT here. It lives in `config/runtime/<profile>.json` and is
# materialized into `dist/config.json` at build time, so it can be changed
# without rebuilding. See docs/architecture/layers.md.
# without rebuilding. See the "Runtime configuration" section of README.md.
#
# Copy to `.env.local` (git-ignored) to override locally.
+16 -6
View File
@@ -3,7 +3,7 @@ name: frontend-quality-gates
on:
push:
branches: [develop]
branches: [main, develop]
tags: ["v*"]
pull_request:
workflow_dispatch:
@@ -83,16 +83,14 @@ jobs:
if: ${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}
runs-on: ubuntu-latest
timeout-minutes: 45
env:
HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}"
strategy:
fail-fast: false
matrix:
include:
- { gate: FE-GATE-012, name: bundle, browser: false }
- { gate: FE-GATE-014, name: config-compatibility, browser: false }
- { gate: FE-GATE-019, name: hosting-header, browser: false }
- { gate: FE-GATE-026, name: lab-performance, browser: true }
- { gate: FE-GATE-028, name: manual-accessibility-review, browser: false }
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
@@ -142,6 +140,8 @@ jobs:
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Build candidate once and verify local evidence
run: corepack pnpm ci:gate -- FE-GATE-015
- name: Admit the candidate to the declared release target
run: corepack pnpm ci:gate -- FE-GATE-027
- name: Archive and validate the exact candidate file set
id: candidate
run: |
@@ -368,15 +368,18 @@ jobs:
production_gate:
name: "${{ matrix.gate }} / ${{ matrix.name }}"
needs: promotion
needs: [immutable_build, promotion]
if: ${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}
runs-on: ubuntu-latest
timeout-minutes: 45
env:
HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}"
CANDIDATE_ARCHIVE_SHA256: "${{ needs.immutable_build.outputs.archive_sha256 }}"
strategy:
fail-fast: false
matrix:
include:
- { gate: FE-GATE-016, name: rollback-drill }
- { gate: FE-GATE-019, name: hosting-header }
- { gate: FE-GATE-021, name: runbook-boot-config }
- { gate: FE-GATE-022, name: runbook-chunk-mismatch }
- { gate: FE-GATE-023, name: runbook-api-degradation }
@@ -393,6 +396,13 @@ jobs:
run: |
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Download promoted release
uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7
with:
name: "promoted-release-${{ gitea.run_id }}-${{ gitea.run_attempt }}"
path: .release/promoted
- name: Verify and extract the candidate through one inode-bound operation
run: node scripts/verify-ci-candidate-archive.ts --archive ".release/promoted/release-candidate.tar.gz" --extract-to ".release/promoted-release"
- name: Run blocking gate
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
- name: Upload production gate evidence
+2 -2
View File
@@ -1,2 +1,2 @@
engine-strict=true
save-exact=true
# pnpm 11 reads engineStrict and saveExact from pnpm-workspace.yaml, not from
# this file (review 13-09). Keep only npm-level settings such as registry auth here.
+88
View File
@@ -0,0 +1,88 @@
# 변경 이력
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다.
- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다.
- **[보안]** 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다.
- **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트).
- 표시가 없으면 템플릿 안에서 끝나는 수정이다.
- 괄호 안 ID는 리뷰 발견 ID다. 근거와 재현 조건은 해당 리뷰 문서에 있다.
- 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25` 기준이다. 병합 방식에 따라 `main`에서는 해시가 다를 수 있으니 ID로 찾는다(`git log --grep '03-03'`).
## 0.2.0 — 태그 `v0.2.0` (2026-09-27)
2026-09-25 성숙도 리뷰(`docs/reviews/2026-09-25-maturity-review/`) 수정 묶음이다.
기준은 `main` `4626b73`이다. `package.json`의 `version`은 `0.2.0`이다.
### 보안·계약 변경
먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다.
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 모든 V3 HTTP 요청이 논리 실행마다 `x-correlation-id` 헤더를 하나 보낸다. 다른 origin API는 preflight `Access-Control-Allow-Headers`에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 `Access-Control-Expose-Headers`에도 넣는다 (03-03) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts`, `src/bootstrap/runtime-adapters.ts`, `docs/operations/api-contract-and-server-state-recovery.md` | `c5da3cf`, `f0a6495` |
| [계약] | 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (03-01, 08-03) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx` | `dfb1b9e` |
| [계약] | 명령의 401/403/429를 기능 패키지가 분류할 수 있다(`classifyStatus`, 선택 필드). 재로그인이 먼저다 (03-02) | `src/adapters/http/http-effect-certainty.ts`, `src/adapters/http/http-execution-v3.ts`, `src/contracts/errors.ts`, `src/contracts/external-contract-runtime.ts` | `2afee67` |
| [계약] | 422 problem body의 필드 오류(`path`, `code`)를 폼까지 전달한다 (03-04) | `src/adapters/http/feature-http-binding.ts`, `src/features/reference-feature/contracts/reference-schemas.ts` | `479acd5` |
| [계약] | 텔레메트리 수집기 이벤트마다 `build_id`, `release_id`가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (13-11, 03-05) | `src/adapters/telemetry/telemetry-collector.ts`, `src/bootstrap/runtime-adapters.ts` | `43e47f4`, `e14c613` |
| [보안] | 번들이 읽지 않는 `VITE_*` 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, `ENV_REGISTRY`에 없는 `VITE_*` 이름은 빌드를 멈춘다 (13-06) | `src/contracts/env.ts`, `vite.config.ts`, `eslint.config.ts` | `2ec59ad` |
| [보안] | 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (05-03, 05-04) | `src/adapters/platform/indexeddb-connection.ts`, `src/adapters/storage/indexeddb/indexeddb-runtime.ts`, `src/adapters/storage/opfs/opfs-byte-store-adapter.ts`, `src/application/ports/browser-file-storage/` | `3e37fbf`, `6ab564f` |
| [계약] | `RELEASE_TARGET`이 `APP_PROFILE`과 다르면 배포 승인이 거절된다 (12-02, 13-01) | `scripts/check-release-admission.ts`, `.gitea/workflows/quality-gates.yml` | `239b22a` |
| [계약] | 설정·매니페스트 URL이 `VITE_ROUTER_BASE_PATH`를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (13-07) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts`, `vite.config.ts` | `e215c84` |
| [계약] | `VITE_PRODUCT_FEATURES`는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (09-02) | `scripts/generate-product-feature-index.ts`, `src/contracts/product-features.ts` | `a8111f7` |
| [계약] | `src/features/<id>/`에 `feature-module.ts`도 `NOT_INSTALLED` 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 `--feature=<id>`를 받는다 (09-07, 14-03) | `scripts/generate-product-feature-index.ts`, `scripts/test-sample-removal.ts`, `config/contracts/registry-governance.json`, `docs/architecture/starter-experience.md` | `ad0e83c` |
| [계약] | 기능 루트·context·app 파일은 `src/adapters`를 import할 수 없다. presentation은 app·context를 import할 수 없다(`app-router.tsx` 예외) (12-03) | `scripts/check-architecture.ts`, `.dependency-cruiser.json`, `docs/architecture/layers.md` | `f8b6a36` |
| [계약] | CI 계약의 게이트 수·해시가 `config/ci/contract-baseline.json`으로 옮겨졌다. 게이트를 바꾸면 `update:ci-contract-baseline`로 갱신한다 (14-02) | `config/ci/contract-baseline.json`, `scripts/check-ci-contract.ts` | `0114b1e` |
| [계약] | 모든 테스트 파일은 어떤 게이트가 돌리거나 `config/ci/ungated-tests.json`에 이유가 있어야 한다 (12-04, 09-11, 11-03) | `config/ci/gates.json`, `config/ci/ungated-tests.json`, `scripts/lib/ungated-tests.ts` | `840de45`, `45ee231` |
| [계약] | 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 `UNVERIFIED`(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (08-06, 11-01, 13-03, 13-05) | `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `scripts/drill-runbook.ts`, `docs/operations/ci-quality-gates.md` | `7298275`, `7f889a6`, `a263d8c` |
| [계약] | `engineStrict`, `saveExact`를 `pnpm-workspace.yaml`로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (13-09) | `pnpm-workspace.yaml`, `.npmrc` | `a5dc851` |
| [계약] | 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (08-01) | `src/presentation/forms/form-contracts.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/forms/form-components.tsx` | `9894a70` |
| [계약] | browser-transfer 포트: `upload()` 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 `resourceId`를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-transfer/`, `src/adapters/browser-transfer/` | `648fe4e`, `7b2cefb`, `5a6665a`, `426b6b8` 외 |
| [계약] | IndexedDB·OPFS 포트: 미래 스키마는 `INCOMPATIBLE`, 빈 receipt는 없음으로 본다 (05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-file-storage/`, `src/adapters/storage/` | `7f45afa`, `47cf040`, `8fc816e` 외 |
| [계약] | 외부 세션 owner의 `readSubject()`와 `SessionGateway.getSubject()`가 필수가 됐다. `readSubject`가 없는 owner는 `integration-failed`로 닫힌다. 토큰 갱신마다 서버 상태 캐시가 비워지던 문제를 막는다 | `src/adapters/auth/external-session-adapter.ts`, `src/application/ports/`, `docs/architecture/starter-experience.md` | `c6300e9` |
| [보안] | 운영 CSP(`unsafe-eval` 없음) 아래에서 zod가 eval을 시험하지 않는다. `src/`의 코드는 zod를 `src/contracts/zod.ts`로만 가져온다(dependency-cruiser 규칙) (13-08, F-7) | `src/contracts/zod.ts`, `.dependency-cruiser.json`, `tests/e2e/production-csp.spec.ts` | `9dc95ca` |
| [계약] | 레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014) (07-02, 13-10) | `src/contracts/compatibility.ts`, `scripts/check-registries.ts`, `config/contracts/` | `17d617a` |
| [계약] | 오류 레지스트리에서 읽지 않는 필드를 뺐다. 호환 별칭과 V1 reader에 `@deprecated`와 제거 조건을 붙였다 (07-04, 07-07) | `src/contracts/errors.ts`, `src/contracts/` | `aff5f43`, `9e616d3` |
| [계약] | staging·production 빌드는 `VITE_BUILD_ID`가 없으면 실패한다 (13-15, F-6) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts` | `063375e` |
| [계약] | Service Worker 빌드가 `public/config.json` 대신 프로필에서 만든 `dist/config.json`을 읽고, `APP_ENV`가 `APP_PROFILE`과 다르면 빌드를 멈춘다 (06-10, F-8) | `vite.service-worker.config.ts`, `scripts/lib/service-worker-build-input.ts` | `cefb0b2` |
| [계약] | Web Push: 탭 사이 구독 제어를 Web Lock으로 직렬화하고, 새 세션이 다른 계정의 push fence를 넘겨받는다. `REMOVE_REGISTRATION`은 스스로 등록을 해지하는 worker를 배포한다 (06-02, 06-06, 06-03) | `src/adapters/web-push/`, `scripts/lib/self-unregistering-service-worker.ts`, `docs/runbooks/` | `e6c683e`, `996a959`, `9f2305a` |
| [계약] | realtime: 세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다. SSE `Retry-After`를 따른다. 등록되지 않은 이벤트 종류는 registry mismatch로 끝난다 (04-01~04-08). realtime recipe를 쓰는 프로젝트만 해당. 레시피 번들 예산은 40,900 bytes로 올렸다 | `src/adapters/realtime/`, `config/recipes/frontend-capability-recipes.json` | `bcad7b0`, `02d3fdf`, `7e37660`, `2c5e268` 외 |
| [계약] | browser-files 포트: 같은 턴의 abort는 `ABORTED`, 닫은 선택 창은 `DISMISSED`, 소진된 object URL lease는 재시도 가능으로 보고한다. Cache Storage는 후보 항목을 검증한 뒤에만 verified로 보고한다 (02-01~02-09). browser-files recipe를 쓰는 프로젝트만 해당 | `src/adapters/browser-file-storage/`, `src/adapters/cache-storage/` | `c9be8d6`, `d76653b`, `0b41cb3`, `55c0bf5` 외 |
| [계약] | 샘플 상세 경로가 `/examples/reference-resources/items/:resourceId`로 옮겨졌다. ID가 `new`·`status`인 항목도 상세가 열린다 (08-13) | `src/features/reference-feature/contracts/reference-feature-contract.ts`, `config/contracts/registry-change-evidence.json` | `d7b81c6` |
| [계약] | `tsconfig.base.json`에 `noUnusedLocals`를 켰다. 복사한 프로젝트의 쓰지 않는 import·변수가 `check:types`에서 실패한다 (12-12) | `tsconfig.base.json` | `49413af` |
### 그 밖의 수정
- 부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (09-03, 09-04, 09-10). `src/bootstrap/`, `src/presentation/boundaries/boot-error-shell.tsx`
- 부트: `FEATURE_OVERRIDES`의 모르는 키를 진단으로 남긴다 (09-09). `src/bootstrap/runtime-adapters.ts`, `scripts/check-release-admission.ts`
- 빌드: `dist` 파일을 다른 사용자도 읽을 수 있게 한다 (13-02). `scripts/lib/dist-permissions.ts`
- 공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (13-12, 13-04). `scripts/lib/vite-module-inventory.ts`, `scripts/verify-exact-promotion-bundle.ts`
- 아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (12-05~12-11). `scripts/check-architecture.ts`
- 기능 조립: `needs` 검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (09-01, 09-05, 09-06, 09-08, 09-12, 00-02). `src/features/`, `src/bootstrap/runtime-adapters.ts`
- 테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (13-08, 01-04, 05-08, 10-03)
- 샘플 제거: `test:sample-removal`이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (14-01, 14-08, 00-01, 10-01). `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts`
- 문서: README에 런타임 프로필·배포 변수·우선순위를 적고 `verify:documentation`이 변수 목록을 검사한다 (13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (13-13, 13-14, 03-06, 03-08).
- 화면: 오류 종류마다 문구가 있고, 실패 화면에 지원 참조와 다음 행동이 나온다. 언어를 바꾸면 폼 오류도 다시 번역된다. 조회 실패의 인증·권한·없음 화면이 갤러리와 같은 컴포넌트다. 수정키 클릭은 브라우저에 맡긴다. 스크롤·해시 이동을 복원한다 (07-01, 08-02, 08-04, 08-07~08-12, F-10). `src/presentation/`, `src/presentation/i18n/`
- 접근성·visual 검사가 로그인 뒤 실제 화면을 상태별로 검사한다 (08-05, 11-02). `tests/e2e/accessibility.spec.ts`
- 계약 테스트: V2/V3 일치, 두 번째 기능의 레지스트리 통과, validator 결과 검사 (07-03, 07-05, 07-06, 09-07, F-3). `tests/unit/`, `src/contracts/`
- Service Worker: 알림 클릭, kill switch, drain 시간 초과, 이전 릴리스 fallback, 거절 클릭 경로, 시작 실패 텔레메트리 (06-01, 06-04, 06-05, 06-07~06-09). `src/adapters/web-push/`, `src/adapters/service-worker/`, `src/bootstrap/`
- 테스트 체계: 부하에 강한 대기, 커버리지 정책, 파일 하나 실행, 실제 타이머 복원, 포커스 테스트 금지, reference 데이터 E2E, 실제 모양 기능 규모 측정, SW 없는 구 탭 청크 복구, 성능 측정 중앙값, 모듈 평가 실패 부트 화면 (10-02, 10-04~10-07, 11-04~11-08, F-2). `tests/`, `scripts/scale/`, `scripts/lib/lab-performance.ts`
- 테스트 fixture가 공유 `node_modules`를 다시 쓰지 않고, 임시 폴더를 지운다 (F-4, F-12, 00-03). `scripts/lib/removal-fixture.ts`, `tests/unit/`
- 문서: 손으로 적은 게이트 수와 LOC를 지우고 `verify:documentation`의 검사 범위를 적었다 (14-07)
### 알려진 제한
- Playwright spec은 chromium·firefox·webkit에서 확인했다. WebKit에서만 난 실패 1건(구 탭 청크 복구 spec의 콘솔 문구 허용 목록)은 `b1a36ab`로 고쳤다.
- 사용자 몫(SPEC "범위 밖" U-1~U-5, F-11)은 이 버전에 들어 있지 않다.
## 0.1.0 — `main` `4626b73` (2026-09-24)
태그가 없는 `main`이고 `package.json` 버전은 `0.1.0`이다. 이 커밋보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다.
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [보안] | 자격증명 헤더 값은 제어 문자가 없는 ByteString만 받는다. 대소문자만 다른 헤더 이름은 거절한다 (R-3.4) | `src/adapters/http/http-contract-bridge.ts`, `src/adapters/auth/external-session-adapter.ts` | `5e62b7e` |
| [보안] | REST v2 COMMAND는 POST/PUT/PATCH/DELETE만 쓴다. GET으로 선언된 명령이 CSRF 보호 없이 나가던 문제다 (R-7.4) | `src/contracts/api-operations.ts` | `f26fd18` |
| [보안] | 텔레메트리 리댁션이 문자열 중간의 토큰, URL 비밀 파라미터, 이메일을 가린다 (R-9.3) | `src/platform/telemetry/redact-telemetry.ts` | `4e0745c` |
+26
View File
@@ -0,0 +1,26 @@
# CLAUDE.md
## 리뷰 기준 (모든 리뷰에 적용)
이 repo를 리뷰할 때는 전체 리뷰든 모듈·PR·diff 리뷰든 [`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`](docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md)를 기준으로 한다.
- 발견 사항은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다(0.3절). 같은 결함을 여러 번 세지 않는다.
- 성격(확인된 결함 / 구조적 위험 / 미검증 / 개선 제안), 심각도(Critical~Low), 우선순위(P0~P3), 통제 수준(M0~M4), 증거(E0~E4)를 따로 적는다(35절). 확인하지 못한 것은 M0가 아니라 `미확인`이다.
- 발견 사항은 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다.
- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다.
- 리뷰에서는 코드를 고치지 않는다. 고치는 작업은 리뷰 문서를 근거로 별도로 진행한다.
### 이 repo의 리뷰 전제
- 이 repo는 템플릿(reference implementation)이다. repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 다만 갈라진 중복 복사본은 문제로 본다.
- adapter 배럴(`src/adapters/*/index.ts`)이 공개 경계다.
- adapter끼리 import할 수 있는 예외는 `.dependency-cruiser.json`의 kernel 예외(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 제안하지 않는다.
- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다.
### 전체 리뷰 절차
1. 기준 커밋과 가이드 0.1절 전제 표를 먼저 고정한다.
2. 게이트를 직접 실행하고 결과를 기록한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`, `verify:documentation`, `check:adapter-inventory`, `check:ci`.
3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 재사용한다.
4. 각 에이전트는 `docs/reviews/<YYYY-MM-DD>-maturity-review/NN-<영역>.md`에 결과를 쓴다.
5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다.
+179 -7
View File
@@ -21,8 +21,54 @@ corepack pnpm install --frozen-lockfile
corepack pnpm dev
```
Runtime-public settings live in `public/config.json` and are validated before
the product tree mounts. Client secrets are forbidden.
## Runtime configuration
Runtime-public settings are validated against one schema before the product
tree mounts (`runtimeConfigV2ArtifactSchema` in
`src/contracts/release-artifacts.ts`). Client secrets are forbidden.
The source of truth is `config/runtime/<profile>.json`, one file per
environment: `local`, `development`, `staging`, `production`. `corepack pnpm
build` writes `dist/config.json` from the selected profile
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
profile for `corepack pnpm dev`; the build replaces it, so settings put there
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
`BUILD_ID: local-build` and `RELEASE_ID: local-release`;
`tests/unit/deployment-admission.test.ts` fails when the two differ.
Build and deploy variables, lowest precedence first:
| Variable | Sets | Default |
| --- | --- | --- |
| `APP_PROFILE` | which `config/runtime/<profile>.json` is used | `local`; an empty value fails the build |
| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile | the profile value |
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | the profile value |
| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` |
| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` |
| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it |
`verify:documentation` fails if this table stops naming a variable the build or
admission reads (`scripts/verify-documentation-readiness.ts`).
Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything
else changes by editing the profile file. Staging and production reject demo
auth and non-HTTPS endpoints.
A production build and its admission check:
```bash
APP_PROFILE=production \
RUNTIME_API_BASE_URL=https://api.example.com/ \
RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
```
With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires
`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a
gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable
list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
## Included starter experience
@@ -45,6 +91,46 @@ owner described in
The client route policy is user experience only; server authorization remains
authoritative.
## Support scope
Four tiers. The status words on the right are the ones the catalogs and
design documents use; the next table maps them.
| Tier | What it covers | Status words |
| --- | --- | --- |
| Default | In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), the typed message catalog, and the removable reference feature. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. `src/features/local-draft-feature` is an architecture sample, not installed | `DESIGNED_NOT_IMPLEMENTED` |
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` |
The rows come from
[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md),
[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md)
and
[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md).
| Status word | Where it appears | Meaning | Tier |
| --- | --- | --- | --- |
| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default |
| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional |
| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a `src/features/<id>/NOT_INSTALLED` marker file | not part of the build | Optional (recipe) or Experimental (feature) |
| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional |
| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental |
| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported |
| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are
verdicts on evidence, not support tiers.
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
iOS 16.4. That is the higher of Vite 8's default JavaScript target
(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older
versions inside the target range and real mobile browsers are not tested.
## Architecture
This repository is a **Frontend Application Foundation**: a starter/composition
@@ -98,6 +184,30 @@ project-owned integrations. They are target designs and review findings; a
capability is not treated as implemented until its branch acceptance criteria
and executable gates pass.
## Documentation
[`docs/README.md`](docs/README.md) sorts the documents into current contracts,
target designs and work history.
### Files you can delete after copying
These record how the template was built. Nothing in the build or the gates
reads them, except the one file noted below
(`tests/unit/deletable-history-documents.test.ts` checks this).
| Path | Contents |
| --- | --- |
| `docs/superpowers/` | past plans and specs |
| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it |
| `SPEC.md`, `tasks/` | requirements and task list of the 2026-09-25 review fix round |
| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own |
The reference feature is not in this list: deleting its directory alone
leaves tests, policy entries and CI scripts behind that fail the gates.
`scripts/test-sample-removal.ts` removes it from a copy of
the repository and lists everything that has to go with it (its header comment
and `SAMPLE_EXTRAS`); do the same in your project and run the gates.
## Verification
Common local checks:
@@ -123,6 +233,11 @@ corepack pnpm drill:runbooks
corepack pnpm check:ci
```
`drill:runbooks` stops at the first drill that is not `PASS`. Without provider
evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports
a check it could not run locally as `PASS`; see "Runbook jobs" in
[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
`test:all` is the ordinary product-development loop and intentionally excludes
host-level CI-runner assurance. Run `corepack pnpm test:system` only on the
compatible Linux assurance host described in
@@ -152,21 +267,25 @@ corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review
for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`,
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
keyboard/focus/screen-reader review for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`,
`EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`, `NOT_FOUND`,
`REFERENCE_RESOURCE_LIST`, `REFERENCE_RESOURCE_DETAIL`,
`REFERENCE_RESOURCE_FORM` and `REFERENCE_RESOURCE_STATUS`.
`verify:documentation` derives that list from the route registry and fails if
this paragraph falls behind it.
this paragraph falls behind it. The merge gate FE-GATE-009 runs only
`review:a11y-manual -- --format-only`, which checks that every route record
keeps the template's fields, reviewed or still pending.
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
eligible-sample threshold and 28 days of production data exist.
Live release verification additionally requires `HOSTING_BASE_URL`.
Live hosting verification (FE-GATE-019, production stage) requires
`HOSTING_BASE_URL` and a deployed promoted release; without it the result is
`UNVERIFIED`, not `PASS`.
## CI and evidence
The 27-gate registry is `config/ci/gates.json`; the Gitea workflow is
The gate registry is `config/ci/gates.json`; the Gitea workflow is
`.gitea/workflows/quality-gates.yml`. It follows:
```text
@@ -174,8 +293,61 @@ MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
```
`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning.
The workflow runs on pull requests, pushes to `main` and `develop`, and `v*`
tags. The Git host of this repository may not have Actions enabled, so a pull
request can show no gate status at all; no status is not a pass. Until the
host runs the workflow and marks the merge gates as required checks, run the 13
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
browsers):
```bash
for gate in 001 002 003 004 005 006 007 008 009 010 011 013 020; do
corepack pnpm ci:gate -- "FE-GATE-$gate" || break
done
```
Machine-readable evidence is written below `artifacts/`; generated evidence is
ignored by Git while `.gitkeep` files preserve the taxonomy.
Operational details are in `docs/operations/`, with incident procedures in
`docs/runbooks/`.
## Updating a copied project
Template versions are Git tags `vX.Y.Z`. [`CHANGELOG.md`](CHANGELOG.md) lists
the changes between tags, marks security fixes **[보안]** and contract changes
**[계약]** (backend, deployment, CI or feature code must change too), and names
the affected paths.
Record where you started. Right after copying, commit a one-line
`.template-origin` file at the root of your project with the template tag (or
commit) you copied and the date, for example `v0.2.0 2026-09-26`.
Take a template fix with Git. `cherry-pick` works even when your repository
does not share the template's history, because it merges against the picked
commit's parent:
```bash
git remote add template <template repository URL>
git fetch template --tags
git log --oneline <your origin>..template/main # what changed since you copied
git cherry-pick -x <commit> # one fix; -x records its origin
```
When the files have moved or diverged too far for a clean pick, read the
change as a diff and apply it by hand:
```bash
git diff <commit>^ <commit> -- <paths from CHANGELOG>
```
Afterwards run the local merge gates from "CI and evidence", apply the
backend or deployment change a **[계약]** row names, and update
`.template-origin` once you have caught up to a tag. `git revert` undoes a pick.
Defects: if a problem reproduces on an unmodified checkout of your
`.template-origin` commit, it is a template defect. Report it on the template
repository with that commit and the reproduction; the template maintainer
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
your changes to reproduce belongs to your project, and applying a template fix
to your copy is your project's job.
+52 -213
View File
@@ -1,228 +1,67 @@
# SPEC: src 리뷰(2026-09-24) 긴급·필수 항목 수정
# SPEC: 성숙도 리뷰(2026-09-25) 전 항목 반영
## 목적
`docs/reviews/2026-09-24-src-full-review.md`의 **긴급 1건 + 필수 46건**을 고친다. 권장·사소 항목은 이번 범위가 아니다.
`docs/reviews/2026-09-25-maturity-review/`의 발견 사항 **138건 전부**를 해결한다. 대상은 High 8 · Medium 57 · Low 73이다. 영역 문서 142건에서 같은 결함 4쌍과 포함 관계 1건을 합치고, 오케스트레이터 발견 00-01을 더한 수다.
각 요구사항 ID(R-x.y)는 리뷰 문서의 섹션 번호(6.x-y)와 같다. 문제 설명, 근거 코드, 실패 시나리오는 리뷰 문서를 기준으로 한다. 이 문서에는 **무엇이 되면 완료인지**와 **방향이 여러 개인 항목의 결정**만 적는다.
요구사항 ID는 리뷰의 발견 ID와 같다(예: `03-01`). 이 문서에는 세 가지만 적는다. 문제 설명·근거·발생 조건은 리뷰 문서를 기준으로 한다.
## 범위 밖
- 모든 요구사항에 공통인 완료 기준
- 리뷰에서 방향이 여러 개였던 항목의 결정
- repo 밖이라 이 작업이 끝낼 수 없는 항목
- 리뷰의 권장·사소 항목. 단, 같은 코드 줄을 고치다가 자연히 해결되는 경우는 예외다.
- `src/` 밖의 리팩터링. 단, R-0이 요구하는 스크립트와 설정 변경, 그리고 버그를 고정하고 있는 기존 테스트의 수정은 포함한다.
- 공개 포트 시그니처의 파괴적 변경. 추가만 허용한다.
**완료 기준의 기준은 해당 발견 항목의 "완료 기준" 칸이다.** 아래 결정 표가 그 칸과 다르게 정한 경우에만 결정 표를 따른다.
## 범위 밖 (repo 밖 · 사람이 해야 함)
이 항목들은 코드로 끝낼 수 없다. repo 쪽 준비만 하고, 나머지는 `tasks/todo.md` "사용자 몫"에 남긴다.
| ID | 사용자 몫 | repo 쪽에서 하는 것 |
|---|---|---|
| U-1 (12-01, 14-01) | Gitea 저장소 Actions 활성화, runner 연결, branch protection에 merge 게이트를 required check로 지정 | push 트리거에 `main` 추가, README에 CI 상태와 머지 전 로컬 명령 명시 |
| U-2 (08-06) | 릴리스 후보 하나로 10개 라우트 수동 접근성 검토 수행·서명 | 결정 D-8 |
| U-3 (14-04) | 태그 push | CHANGELOG, README 업데이트 절, 로컬 태그 |
| U-4 (14-03, 13-13) | 작성자 외 사람의 기능 추가 수행 기록, staging에서 공급망 end-to-end smoke | 문서 정비, "provider 없는 구성" 문서화 |
| U-5 (03-01) | 백엔드 멱등 키 보관·충돌 계약 확인 | 클라이언트는 같은 키 재전송만 보장 |
## 공통 완료 기준 (모든 요구사항)
1. 버그를 재현하는 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이는 재현할 수 없는 항목은 fake/fixture로 조건을 만들어 재현한다.
2. `corepack pnpm check:architecture`, `check:types:app`, `check:types:test`, `lint`, `test:unit`, `test:component`이 통과한다.
3. adapter 파일을 추가하거나 이동하면 `docs/reviews/adapters/INVENTORY.md`를 함께 고치고 `check:adapter-inventory`가 통과한다.
4. adapter 간 공용 로직은 `src/adapters/platform/`(kernel)으로, 공유 어휘는 `src/contracts/`로 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
5. 요구사항 하나에 커밋 하나. 커밋 메시지에 R-ID를 적는다.
1. 동작을 바꾸는 요구사항은 재현 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이 재현할 수 없는 항목은 fake·fixture로 조건을 만든다. 리뷰가 Playwright 검증을 요구한 항목은 spec 하나를 추가한다.
2. 테스트 검출력이 문제였던 항목(변이 생존)은 리뷰에 적힌 변이를 다시 넣었을 때 새 테스트가 실패하는 것까지 확인한다.
3. 작업마다 다음 게이트가 통과한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`.
4. 레인이 끝날 때와 통합 때는 3번에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build`도 통과한다.
5. adapter 파일을 추가하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 함께 고친다.
6. 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새 파일 단위 예외 규칙은 만들지 않는다.
7. 공개 포트는 추가만 한다. 기존 시그니처를 깨야 하면 결정 표에 적는다.
8. 작업 하나에 커밋 하나. 커밋 메시지에 발견 ID를 적는다. 그 작업이 바꾼 파일만 스테이징한다.
9. 문서 요구사항은 문서의 각 주장이 코드 위치를 가리키는 것으로 확인한다.
## 요구사항
## 결정
### R-0 빌드 기반 (긴급)
- 깨끗한 체크아웃(`src/.generated/` 없음)에서 `dev`, `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 사전 수동 명령 없이 동작한다.
- CI 게이트도 같은 조건에서 통과한다.
리뷰가 대안을 제시한 항목에 대해 기본값을 정했다. 계획 승인은 이 표의 승인이다.
### R-1 browser-transfer
- R-1.1 `dispose()`가 deadline 초과로 실패한 뒤 작업이 끝나면, 다시 호출할 때 store를 닫고 `CLOSED`가 된다.
- R-1.2 opaque ID 문법은 한 곳에서 정의한다. control plane이 받은 ID는 presigned 계층도 받는다.
- R-1.3 동시성 정책 검증은 `partSize × maxConcurrency × copyFactor`를 기준으로 한다. 기본 정책은 이 검증을 통과하고, createSession은 **실제 worker 수**를 요청한다.
- R-1.4 크기나 part 수 한도 초과는 `LIMIT_EXCEEDED`로 보고된다.
### R-2 browser-files / cache-storage / cross-context
- R-2.1 BOUNDED_OBJECT_URL 전략에서 source open이 실패하거나 abort되면 `deliver()`는 reject하지 않고 Result를 반환한다. 늦게 온 lease는 닫힌다.
- R-2.2 source별 sequence watermark는 이벤트 TTL로 지워지지 않는다. 60초 넘게 쉰 뒤의 seq N+1은 `NEXT`다.
- R-2.3 broadcast 발행이 실패해도 수신 listener는 유지된다. broadcast를 받을 수 없는 탭은 `DEGRADED`로 보고된다.
- R-2.4 picker/save picker 함수는 options 객체에 bind되지 않는다. `window` 함수를 그대로 주입해도 동작한다.
- R-2.5 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 받아들인다. `content-type`이 허용 응답 헤더에 없는 정책은 정책 검증에서 거부된다.
### R-3 http / query-cache / auth
- R-3.1 경로 값 `.`과 `..`는 V3와 V2 모두에서 `PATH_VALUE_INVALID`(V2는 `PATH_PARAMETER_INVALID`)로 거부된다.
- R-3.2 세션 알림은 (상태, 주체)가 바뀔 때만 scope fence를 건다. demo 어댑터는 같은 값이면 알리지 않는다. V3의 요청 전 자격증명 없음은 `onUnauthenticated()`를 부르지 않는다. 서버 401만 부른다. **[고위험: 인증·캐시]**
- R-3.3 5xx/408/425 응답의 problem 바디가 유효하지 않으면 HTTP status를 담은 서버 장애로 분류된다. 요청 쪽 위반은 서버 응답 오류(`ENVELOPE_MISMATCH`)로 매핑되지 않는다.
- R-3.4 자격증명 헤더 값은 전송 전에 ByteString(제어문자 없음)으로 검증된다. 실패는 요청 전 단계의 인증 결함으로 분류된다. 대소문자만 다른 중복 헤더는 거부된다. **[고위험: 인증]**
- R-3.5 feature 바인딩에서 `mapSuccess`/`mapProblem`이 던지면 `MAPPING_CONTRACT_VIOLATION` Result로 반환되고 effect가 보존된다.
### R-4 realtime
- R-4.1 `await quiescence` 뒤 DRAINING이면 recovery는 authority를 호출하지 않고 실패한다.
- R-4.2 `retryable:true`인 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`는 서버 hint가 없어도 재연결 대상이다(reconnect와 polling 모두).
- R-4.3 barrier가 필요 없는 recovery(barrier NONE)는 전송을 닫지 않고 계속된다.
- R-4.4 SSE 파서는 문자마다 인코딩하지 않는다. 250KB chunk 처리가 기존 대비 10배 이상 빨라진다(수동 측정 기록).
### R-5 storage
- R-5.1 orphan 후보 목록은 커서로 이어서 볼 수 있다. 참조 중 청크가 100개를 넘어도 뒤의 orphan이 지워진다. **[고위험: 삭제]**
- R-5.2 dedup으로 재사용한 청크는 grace period 보호를 다시 받는다(mtime 갱신). **[고위험: 삭제]**
- R-5.3 mutation lock 대기 시간은 60초 RPC 타임아웃에 포함되지 않는다. lock 대기는 별도 상한 정책값으로 제한된다.
- R-5.4 파티션 purge는 손상 행이 있어도 끝까지 지운다. 손상은 observe로 보고한다. **[고위험: 삭제]**
- R-5.5 prepared-object 검증은 한 모듈에서 한다. 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증되고, 현재 정책값은 새로 쓰는 데이터에만 적용된다. **[고위험: 데이터 판독]**
### R-6 service-worker / web-push
- R-6.1 확정 이후 메시지(ACCEPTED/RELOAD_REQUIRED)는 `registration.waiting`이 비어도 성공으로 처리된다. 메시지는 nonce/kind로 먼저 거른다.
- R-6.2 drain 요청과 응답은 요청자 빌드와 무관하게 워커 buildId + nonce로 짝을 맞춘다. 다른 빌드 탭이 있어도 활성화가 끝난다.
- R-6.3 앱이 `reloadRequired`/`updateWaiting`을 구독할 수 있다. current 캐시에 없는 asset은 previous 캐시에서 찾는다.
- R-6.4 첫 방문에서 설치 중인 워커는 `ACTIVE`로 보고되지 않는다.
- R-6.5 JavaScript MIME 동의어를 허용한다. `content-encoding`이 있으면 Content-Length와 압축 해제 크기를 비교하지 않는다.
- R-6.6 fetch 핸들러는 manifest에 있는 same-origin GET(비 navigate) 요청에만 `respondWith`를 부른다.
- R-6.7 reconcile에서 서버가 `ABSENT`이면, local association이 ACTIVE였던 경우에만 재등록한다. 그 밖에는 native 구독을 해제한다. **[고위험: 동의]**
### R-7 contracts
- R-7.1 멱등 키는 `^[\x21-\x7E]{1,256}$`만 허용한다. 이 버그를 고정한 기존 테스트도 고친다.
- R-7.2 FEATURE_OVERRIDES의 키(기능 ID)는 설정 이름 금지어 검사 대상이 아니다.
- R-7.3 릴리스 매니페스트 URL은 해석 뒤 origin과 pathname이 입력과 같아야 한다. 탭, 개행, 인코딩된 점 세그먼트는 거부된다.
- R-7.4 REST V2의 COMMAND는 POST/PUT/PATCH/DELETE만 허용된다. `semantics`/`replayPolicy`는 enum으로 검증된다. **[고위험: CSRF]**
- R-7.5 operationId 문법은 contracts 한 곳에서 정의하고 텔레메트리와 진단이 재사용한다. V3가 받는 operationId의 실패 이벤트는 드롭되지 않는다.
### R-8 presentation
- R-8.1 청크 복구 실패 상태는 라우트가 바뀌면 초기화된다. 실패 화면에 "한 번 새로고침" 버튼이 있다.
- R-8.2 WebKit(`Importing a module script failed`)과 Vite CSS preload 실패가 청크 실패로 인식된다.
- R-8.3 선택한 로케일이 preferences에 저장되고 새로고침 뒤에도 유지된다. 세션이 바뀌어도 로케일과 테마는 초기화되지 않는다. unmount 시 router가 dispose된다.
- R-8.4 로케일 변경은 제목과 문구만 갱신한다. 포커스 이동, 스크롤, route 변경 보고는 일어나지 않는다.
- R-8.5 인증필요/잘못된 주소/비활성 기능 화면에서도 제목, 포커스, route 텔레메트리가 동작한다.
- R-8.6 모바일 드로어에서 링크로 이동하면 포커스가 새 페이지(h1/main)로 간다. 메뉴 버튼으로 가지 않는다.
- R-8.7 context 라우트 게이트웨이는 context가 바뀌면 이전 routes로 매칭하지 않는다. 모듈 로드 청크 실패는 `recoverChunk`를 거친다.
- R-8.8 `enabled:false` 쿼리는 로딩으로 표시되지 않는다.
### R-9 bootstrap / platform
- R-9.1 TTL 안에 reload 마커가 있으면 키와 상관없이 자동 reload하지 않는다(세션당 최대 1회). 번갈아 오는 키 테스트를 추가하고, 연속 reload를 기대하던 테스트를 고친다.
- R-9.2 dedup 창 안의 중복 발생 횟수가 수집기로 전달된다.
- R-9.3 리댁션은 문자열 중간의 자격증명, URL 쿼리의 토큰, 이메일을 가린다. 키 목록에 `pwd`, `pass`, `auth`, `otp`, `pin` 계열을 추가한다. **[고위험: 보안]**
## 결정 (방향이 여러 개였던 항목의 기본값)
| ID | 결정 | 이유 |
| ID | 대상 | 결정 |
|---|---|---|
| D-1 (R-0) | 생성 파일을 커밋하지 않는다. 생성 파일을 읽는 진입점(스크립트 또는 package script) 앞에서 생성기를 실행한다. | 6f6c48e가 앱별 생성(`PRODUCT_APP_ID`)을 의도했으므로 gitignore를 유지한다. |
| D-2 (R-1.3) | 기본 `maxConcurrency`를 실제 동작값에 맞춘다. 메모리 한도(`maxInFlightBytes`)는 올리지 않는다. | 지금 기본 동작(동시 1)을 바꾸지 않고, 문서와 코드만 일치시킨다. 다운스트림이 올릴 수 있다. |
| D-3 (R-5.3) | lock 범위는 줄이지 않는다(GC·dedup 정합성). lock 대기만 RPC 타임아웃에서 빼고, 별도 상한을 둔다. | 범위를 줄이면 R-5.2 같은 경합이 새로 생긴다. |
| D-4 (R-2.3) | 발행 쪽 이중 쓰기(broadcast + storage)는 하지 않는다. 수신 유지 + DEGRADED 보고만 한다. | 가장 작은 변경으로 흔한 경로(발행 1회 실패)를 고친다. |
| D-5 (R-8.3) | 로케일 저장은 테마와 같은 `preferences` 경로를 쓴다. Locale/Theme provider는 scope fence 바깥으로 올린다. | 이미 있는 테마 패턴을 재사용한다. |
| D-6 (R-9.2) | 누적 count는 dedup 창이 닫힐 때나 다음 flush 때 요약 이벤트의 `occurrences`로 보낸다. | 기존 이벤트 스키마(`occurrences`)를 그대로 쓴다. |
| D-7 (R-6.3) | previous 캐시 fallback은 hashed URL에만 적용한다. | hashed URL은 같은 URL이면 같은 내용이라 안전하다. |
| D-1 | 03-01, 08-03 | 결과 불명(`UNKNOWN`) admission의 intent를 보관한다. 같은 canonical input으로 다시 저장하면 그 intent(같은 `Idempotency-Key`)로 보내고, 입력이 바뀌면 새 키를 쓴다. 결과 불명 화면의 "변경되지 않음으로 확인"은 "같은 요청으로 다시 보내기"로 바꾸고, 목록 새로고침 링크를 둔다. "변경됨으로 확인"은 유지한다. |
| D-2 | 03-02, 08-01 | `CommandEffectDescriptor`에 선택 필드 `classifyStatus(status)`를 추가한다. 없으면 지금처럼 `MAYBE_APPLIED`다. `AUTH_REQUIRED`는 effect와 무관하게 재로그인을 먼저 안내한다. reference 생성 계약은 401·403·429를 `NOT_APPLIED`로 선언한다. 폼은 `reauth-required`·`forbidden`·`retry-later` 상태를 가진다. |
| D-3 | 05-01 | 트랜잭션별 Web Lock을 begin부터 complete까지 잡는다. reconcile은 `ifAvailable`로 잠기지 않은 행만 처리한다. |
| D-4 | 06-02 | Web Locks(`web-push-control`)로 enable·reconcile·revoke를 origin 단위로 직렬화한다. native `unsubscribe`는 그 호출이 새로 만든 구독에만 한다. |
| D-5 | 06-03 | 운영 문서를 코드에 맞춘다. 부팅을 막는 워커용 비상 경로로 "자기 해제 워커" 빌드 모드를 만들고, `REMOVE_REGISTRATION`이 이 워커를 내보내게 한다. |
| D-6 | 07-02, 13-10 | 경계별 호환 규칙 표를 문서에 넣는다. 분류기는 모르는 변경(타입·enum·nullable)을 `breaking`으로 답한다(fail-closed). FE-GATE-014는 커밋한 기준 스키마와 현재 빌드 스키마를 비교한다. |
| D-7 | 07-03 | V2 행과 V3 descriptor의 일치 테스트를 추가한다. V2를 V3에서 생성하는 작업은 하지 않는다. |
| D-8 | 08-06 | `review:a11y-manual`을 release 단계 게이트로 옮긴다. merge 단계에는 기록 형식 검사만 남긴다. 실제 수동 검토는 U-2다. |
| D-9 | 09-02 | 생성기(`generate-product-feature-index.ts`)가 `VITE_PRODUCT_FEATURES`를 읽어 선택된 기능만 인덱스에 넣는다. 잘못된 값은 생성 단계에서 실패한다. |
| D-10 | 09-07, 14-03 | 생성기는 `src/features/<f>/`에 `feature-module.ts`가 없고 `NOT_INSTALLED` 표식 파일도 없으면 실패한다. 제거 스크립트는 기능 ID를 인자로 받는다. |
| D-11 | 12-05 | dependency-cruiser 실행을 뺀다. `.dependency-cruiser.json`은 이름을 그대로 두고 규칙 파일로 쓴다(스크립트·문서·메모리 참조가 많다). 문서 3곳을 고친다. |
| D-12 | 12-10, 12-08 | 새 시스템을 만들지 않고 줄인다. import 관련 정규식 규칙(icon vendor, realtime import, design-system deep import)은 그래프 규칙으로 옮기고 정규식을 지운다. workflow 계약에는 "모든 gate id가 run step에 있다" 불변식을 둔다. `package-script-graph.ts`는 막는 위험이 `--ignore-scripts`·`allowBuilds`로 이미 막히는지 확인한다. 막히면 줄이고, 아니면 이유를 기록한다. |
| D-13 | 14-02 | CI 계약의 개수·해시를 코드 상수에서 `config/ci/contract-baseline.json`(owner·reason 포함)으로 옮긴다. 갱신 스크립트 `update:ci-contract-baseline`을 제공한다. 제거 스크립트는 완화 모드 대신 갱신 절차를 거쳐 canonical `check:ci`를 통과한다. |
| D-14 | 11-01, 13-03, 13-05 | 로컬에서 확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다. 코드에 상수 `true` 판정을 두지 않는다. 운영 승격은 live·provider 증거를 요구한다. FE-GATE-016과 025의 중복을 정리한다. |
| D-15 | 14-04 | CHANGELOG, README "원본 업데이트 반영" 절, 로컬 태그 `v0.2.0`. 태그 push는 U-3이다. |
| D-16 | 14-05 | `docs/README.md` 색인을 만든다(현재 계약 / 목표 설계 / 작업 이력). `SPEC.md`와 `tasks/`는 이 작업에서 쓰므로 옮기지 않고, 색인에서 이력으로 표시한다. |
| D-17 | 12-01 | repo 쪽만 한다(U-1 참조). |
| D-18 | 11-04 | reference feature를 복제한 실제 모양 기능 25개·100개로 측정한다. 400개는 시간이 허용하면 측정한다. 호스트 부하 조건을 함께 기록한다. |
| D-19 | 12-12 | `noUnusedLocals`를 켠다. 여러 영역 파일을 건드리므로 모든 레인을 통합한 뒤 마지막 작업으로 한다. |
---
## 요구사항 목록
# 2차 라운드: 권장·사소 항목과 1차 후속 결정
1차 라운드(R-0 ~ R-9.3)는 `9bef702`로 main에 병합했다. 2차 라운드에서는 리뷰의 **권장·사소 항목 전부**와 1차에서 남긴 결정 두 건을 처리한다. 요구사항 ID는 `Q-<리뷰 섹션>` 형식이다(예: Q-6.1-5 = 리뷰 6.1-5).
## 공통 완료 기준 (2차)
1차 공통 기준과 같다. 여기에 두 가지를 더한다.
- **동작을 바꾸지 않는 정리(파일 분리, 중복 합치기)**: 새 RED 테스트 대신 기존 테스트가 안전망이다. 해당 경로에 테스트가 없으면 현재 동작을 고정하는 테스트(characterization)를 먼저 추가한다.
- **번들**: 정리가 끝난 뒤 `check:optional-recipes`가 통과해야 한다. 예산은 올리지 않는다(D-11).
## 요구사항
### browser-transfer
- Q-6.1-5 worker 하나가 실패하면 transfer 단위 abort로 나머지 worker를 즉시 멈춘다.
- Q-6.1-6 해석할 수 없는 checkpoint 행이 있어도 abort는 그 행을 지우고 ORPHANED로 보고한다.
- Q-6.1-7 PRIMARY_REQUIRED probe를 쓰는 preset은 fit이 cover/contain/fill일 때만 정책을 통과한다(D-12).
- Q-6.1-8 probe의 decode는 EXIF/irot 회전을 적용하지 않는다(`imageOrientation: "none"`).
- Q-6.1-9 presigned HTTP helper를 한 모듈로 합친다. statusFailure recovery를 통일하고, 쓰지 않는 `compensateLateResponse`는 삭제한다. download Content-Length를 엄격하게 파싱하고, runtime attempt는 kernel `createAbortableOperation`을 쓴다.
- Q-6.1-3b part마다 일어나는 방어적 복사 중 겹치는 것(`Uint8Array.from`과 `slice()`)을 하나로 줄인다.
- Q-6.1-10 `resumable-upload-runtime.ts`에서 서버 응답 검증과 의존성 snapshot 래퍼를 별도 모듈로 분리한다. 동작은 바꾸지 않는다.
- Q-6.1-11 vault `register`는 snapshot 값만 읽는다.
### browser-files / cache-storage / cross-context
- Q-6.2-6 cache 조회 비용: JSON은 chunk를 모아 읽고, 검증된 marker는 메모리에 캐시하고, asset 탐색은 Map으로 한다.
- Q-6.2-7 browser-files의 abort race를 kernel `race`와 compensate로 교체한다. 늦게 도착한 lease와 writable은 닫는다.
- Q-6.2-8 native `cancel`을 한 번이라도 관찰했으면 focus fallback을 끈다.
- Q-6.2-9 host factory가 비활성으로 끝날 때 observe로 보고한다. epoch는 releaseId를 인코딩해서 만든다.
- Q-6.2-10 파일명 자르기를 O(n)으로 바꾸고, 중복 호출을 하나로 줄인다.
- Q-6.2-11 `public-response-cache-adapter.ts`와 `download-delivery-adapter.ts`에서 코덱·검증 모듈을 분리한다. 동작은 바꾸지 않는다.
- Q-6.2-12 `MEDIA_TYPE`/opaque 정규식과 `positiveSafeInteger` 중복을 합치고, `object-url-lease.ts`의 죽은 분기를 지운다.
### http / browser-rpc / query-cache / auth
- Q-6.3-6 요청 종료 사유 판정을 `terminalOutcomeFor` 하나로 모은다. 백오프 중 scope fence는 scope 종료로 분류된다.
- Q-6.3-7 명령의 최종 effect는 누적 certainty와 합친다. `MAYBE_APPLIED`면 재시도하지 않는다.
- Q-6.3-8 namespace 무효화를 병렬로 실행한다.
- Q-6.3-9 RPC 명령이 전송 뒤 실패하면 `MAYBE_APPLIED`로 보고한다. 재시도 전에 scope를 확인하고, 소비자가 abort한 stream은 정리한다.
- Q-6.3-11 V2 401 복구를 재시도 예산과 분리한다. "롤백 가능 seam" 문서의 잘못된 주장을 고친다(V2와 V3는 wire 형식이 다르다).
- Q-6.3-12 cursor pagination의 누적 직렬화와 `push(...)` 한도 문제를 고친다. 쓰지 않는 `validTransportFailure`를 삭제하고, 따옴표가 닫히지 않은 `W/"` ETag를 거부한다.
- Q-6.3-3b V2도 5xx/408/425의 HTML/빈 바디를 status를 담은 서버 장애로 분류하고 재시도 대상으로 둔다.
### realtime
- Q-6.4-5 chunk당 item 상한을 넘으면 실패하지 않고 다음 처리로 넘긴다. COMMENT는 상수 객체를 쓴다.
- Q-6.4-6 dedupe는 FIFO로 제거하고, fingerprint는 해시로 저장하고, prune은 `break`한다. 가득 차도 전체 recovery를 하지 않는다.
- Q-6.4-7 재시도 예산은 유효 신호가 있고 `stableOpenMs`가 지났을 때만 초기화한다.
- Q-6.4-8 realtime 내부의 DataSnapshot과 abort/timeout race 헬퍼를 한 벌로 합친다. Retry-After 파싱과 JSON 중복 키 스캐너는 kernel(`src/adapters/platform/`)로 올리고, http retry-policy와 web-push codec도 이를 쓴다.
- Q-6.4-9 반복되는 attempt 정리를 `endAttempt()`로 뽑고, 무시되던 `_recovery` 파라미터를 없앤다.
- Q-6.4-10 probe 버퍼 상한을 현재 버퍼 기준으로 계산한다.
- Q-6.4-11 사소 항목: poll execute가 throw하면 retryable OFFLINE으로 둔다. BOM은 한 번만 제거하고, 이중 encode와 이벤트마다 만드는 TextEncoder를 없애고, 잘못 붙은 JSDoc을 옮긴다.
### storage
- Q-6.5-6 openObject는 사전 검증에서 manifest만 대조하고, root digest는 스트림 끝에서 확인한다.
- Q-6.5-7 IndexedDB 저장 행 타입·검증기·측정 공식을 `indexeddb-records.ts` 하나로 모은다. 동작은 바꾸지 않는다.
- Q-6.5-8 삭제 후 재생성하면 revision/generation이 다시 시작한다는 점을 port 주석과 문서에 명시한다(D-13).
- Q-6.5-9 보상이 실패해도 put의 원래 실패 코드를 유지하고, recovery만 RECONCILE로 바꾼다.
- Q-6.5-10 kernel: `succeed` 뒤에 온 `fail`이 이기도록 하고, settle된 뒤의 upgrade는 abort한다.
### service-worker / web-push
- Q-6.6-6b fetch 가로채기를 "same-origin GET, navigate 아님, 해시 파일명 또는 manifest URL"로 넓힌다. previous 캐시 fallback이 옛 빌드 chunk에 실제로 동작해야 한다(1차 T29/T32 후속, 사용자 결정).
- Q-6.6-8 후보 캐시 이름이 active 캐시와 같으면 설치 실패 시 지우지 않는다.
- Q-6.6-9 activate는 오래된 캐시부터 지우고, marker 쓰기 실패가 삭제를 막지 않는다.
- Q-6.6-10b 페이지 쪽 활성화 deadline에 워커 drain 시간과 여유분을 더한다.
- Q-6.6-11 알림 클릭이 거절되면 handoff 데이터 없이 앱 루트를 연다. 조용한 push drop은 트레이드오프를 문서에 명시한다(D-14).
- Q-6.6-12 web-push codec primitive(base64url, OPAQUE_ID, validAuthority, exactRecord)를 한 모듈로 합친다. page controller가 주입받은 document를 쓴다.
### contracts
- Q-6.7-6 exact-key/스냅샷 구현을 `exact-snapshot.ts` 하나로 모으고 배열 스냅샷을 추가한다. iterator·getter 우회를 막는다.
- Q-6.7-7 검증된 인덱스·레지스트리는 `createReadOnlyRegistry`를 쓰고 row마다 스냅샷해서 얼린다.
- Q-6.7-8 검증기 프로토콜과 `MappingResult`의 기준 모양을 하나로 정하고, 나머지는 호환 alias나 어댑터로 둔다(D-15).
- Q-6.7-9 REST 인증 프로필은 설치된 레지스트리 하나를 기준으로 한다. V2 resolve도 검증된 레지스트리를 쓴다.
- Q-6.7-10 배포 승인은 IPv6 loopback·ULA·link-local, IPv4-mapped, CGNAT, `0.0.0.0/8`, `.internal`/`.local`을 사설 주소로 본다. 로컬 호스트 목록은 한 곳에 둔다.
- Q-6.7-11 레지스트리 조회는 `Object.hasOwn`으로 한다. 목록에 없는 offline 전이는 false를 반환한다.
- Q-6.7-12 release-tokens는 비교하지 않은 값을 통과로 보고하지 않는다. contract-set 중복은 실패 코드로 반환한다. query-keys 정렬은 필요할 때만 한다. dependency-cruiser에 contracts → presentation/bootstrap 금지 규칙을 추가한다.
### presentation
- Q-6.8-9 디자인시스템 링크(`PageActionBar`, `Breadcrumbs`, `LinkButton`)는 router `Link`로 렌더한다. Pagination은 다른 검색 파라미터를 보존한다.
- Q-6.8-10 로딩·인증필요·404 화면을 하나씩으로 합치고, 세션 액션은 hook 하나로 묶는다. reject 시 멈추던 임시 로딩도 고친다.
- Q-6.8-11 Tooltip: `aria-describedby`를 포커스되는 자식에 붙이고, Escape로 닫는다.
- Q-6.8-12 Pagination은 현재 페이지 주변과 처음·끝만 보여주고(windowing), landmark 중첩을 없앤다.
- Q-6.8-13a 플랫폼 라우트의 `none` 코덱은 모르는 쿼리 파라미터를 거부하지 않고 무시한다(D-16).
- Q-6.8-13b 폼 제출은 비동기 검증 중에도 두 번 일어나지 않는다. 저장 직후 이동할 때 dirty guard가 뜨지 않는다.
- Q-6.8-13c 기본 fallback 문구는 현재 로케일을 따른다. SearchField를 지우면 입력으로 포커스를 돌려준다.
- Q-6.8-13d `theme.css`를 여러 파일로 나눈다. 빌드 결과 CSS 바이트가 달라지지 않아야 한다.
### application / features / bootstrap / platform (+ telemetry adapter)
- Q-6.9-4 텔레메트리 전송 계층을 하나로 합친다(rate limit, credentials `omit`, `pagehide` flush, dispose abort). best-effort fetch에 타임아웃을 둔다(6.3-10 포함).
- Q-6.9-5 킬스위치로 끈 feature는 `features.get()`이 API를 돌려주지 않는다.
- Q-6.9-6 adapter contribution의 featureId가 중복되거나 소속 module과 다르면 throw한다.
- Q-6.9-7 execution context interaction에 완료/정리 API를 두어 부모 signal listener가 남지 않게 한다.
- Q-6.9-8 부트 중에 정적 boot shell(로딩 표시, `aria-busy`)을 보여준다.
- Q-6.9-9 chunk와 boot의 "한 번만 reload" 가드를 공용 guard 하나로 합친다.
- Q-6.9-10 검증을 통과한 config 값만 safe 에러에 싣는다.
- Q-6.9-11 텔레메트리 버퍼는 필요한 공간이 확보될 때만 낮은 severity를 지운다. 주석을 코드와 맞춘다.
- Q-6.9-12 re-export만 하는 `reference-feature-runtime.tsx`를 삭제한다. CI 전용 정책(`promotion-readiness`, `performance-budgets`)은 src 소비자가 없으면 `scripts/`로 옮긴다. 메시지 로케일은 하드코딩하지 않고 카탈로그에서 도출한다.
### 통합
- Q-B 번들 예산: 모든 레인을 병합한 뒤 `check:optional-recipes`를 통과시킨다. 필요하면 해당 번들 코드를 줄인다(D-11).
## 결정 (2차)
| ID | 결정 |
|---|---|
| D-11 | 번들 예산은 올리지 않는다. 코드를 줄여 맞춘다(사용자 결정). |
| D-12 | PRIMARY_REQUIRED는 fit cover/contain/fill만 허용한다. 비율을 유지하는 fit은 probe를 쓰지 않는 preset에서만 허용한다. |
| D-13 | 삭제 뒤 revision 재시작(ABA)은 스키마를 바꾸지 않고 문서로 계약을 명시한다. tombstone 도입은 저장 스키마 변경이라 범위 밖이다. |
| D-14 | 클릭 실패 시 앱 루트를 연다. push drop은 설계 의도로 두고 문서에 명시한다. |
| D-15 | `external-contract-runtime`의 모양을 기준으로 삼는다. 다른 쪽은 호환 alias나 어댑터로 유지한다(공개 타입을 삭제하지 않음). |
| D-16 | 플랫폼 라우트의 모르는 쿼리 파라미터는 무시한다(strip). URL은 건드리지 않는다. |
---
# 3차 라운드: 남은 문제 8건
2차 뒤에 남은 문제 8건을 처리한다(사용자 결정 2026-09-24). ID는 `R3-n`이다.
- R3-1 HTTP V2: 408/425 응답을 안전하거나 멱등인 요청에 한해 재시도한다. `client.ts`의 Retry-After 파싱은 kernel `platform/retry-after.ts`를 쓴다.
- R3-2 업로드 fetch transport의 Retry-After 파싱도 kernel을 쓴다. file-transfer 번들은 동작을 바꾸지 않는 축소로 예산 대비 여유를 546B(1%) 이상 확보한다. 예산은 바꾸지 않는다.
- R3-3 세션 subject: demo 어댑터가 subject를 제공해서, 같은 사용자의 인증 상태 알림(토큰 갱신 등)은 캐시를 비우지 않는다. subject를 주지 않는 외부 owner는 fail-closed로 동작하고, 그 사실과 `readSubject` 구현 방법을 문서에 적는다.
- R3-4 꺼 둔(`enabled:false`) 쿼리는 `idle` 상태로 표시한다. loading이나 empty가 아니다. `AsyncSurface`는 idle에서 로딩이나 빈 상태 문구를 보여주지 않는다.
- R3-5 SSE 파서는 디코딩 전 바이트 단위로 줄 경계를 찾는다. 멀티바이트 입력에서도 원래 파서 대비 10배 이상 빨라진다(수동 벤치로 측정).
- R3-6 실제 브라우저 검증: 모바일 드로어 이동 후 포커스, bind하지 않은 picker 호출, 서비스 워커 두 빌드 간 업데이트와 옛 chunk의 이전 캐시 fallback, `application/javascript`와 gzip 응답의 static 설치, 실제 Cache API의 `Vary: Accept-Encoding`을 Playwright 스펙으로 확인한다. 여러 탭 OPFS 경합은 결정적으로 재현할 수 있으면 넣고, 없으면 그 이유를 기록한다.
- R3-7 WebKit: 시스템 라이브러리를 설치한 뒤 Playwright 스위트 전체를 WebKit으로 돌린다(Safari 청크 오류 메시지 포함).
- R3-8 원격 반영: 3차가 끝나면 브랜치를 push하고 Gitea PR을 만든다(사용자 결정).
138건과 작업의 대응은 `tasks/todo.md`에 있다. 모든 발견 ID가 정확히 한 작업에 속한다. 같은 결함 쌍(03-01=08-03, 12-02=13-01, 11-01=13-03, 07-01=08-02)과 포함 관계(09-11⊂12-04)는 한 작업에서 함께 닫는다.
-38
View File
@@ -1,38 +0,0 @@
{
"schemaVersion": 1,
"layers": {
"domain": {
"root": "src/domain",
"mayImport": ["src/domain"]
},
"application": {
"root": "src/application",
"mayImport": ["src/application", "src/domain", "src/contracts"]
},
"presentation": {
"root": "src/presentation",
"mayImport": ["src/presentation", "src/application", "src/domain", "src/contracts"]
},
"adapters": {
"root": "src/adapters",
"mayImport": ["src/adapters", "src/application", "src/domain", "src/contracts"]
},
"bootstrap": {
"root": "src/bootstrap",
"mayImport": ["src"]
}
},
"forbidden": [
["domain", "application"],
["domain", "presentation"],
["domain", "adapters"],
["domain", "bootstrap"],
["application", "presentation"],
["application", "adapters"],
["application", "bootstrap"],
["presentation", "adapters"],
["presentation", "bootstrap"],
["adapters", "presentation"],
["adapters", "bootstrap"]
]
}
+11
View File
@@ -0,0 +1,11 @@
{
"schemaVersion": 1,
"owner": "frontend-platform",
"reason": "13-03: production_gate downloads the promoted archive and FE-GATE-021..025 drill it with --release-root instead of rebuilding",
"gates": 27,
"commands": 98,
"commandReferences": 103,
"artifacts": 109,
"stages": 5,
"gateShapeSha256": "630e801239de5d175fd1049b2527851dabe06f139ba8ff6a98de7f09f7a257c2"
}
+124 -79
View File
@@ -177,9 +177,14 @@
{
"id": "check-types-fixture-diagnostics",
"script": "check:types:fixture:diagnostics",
"expect": "pass"
},
{
"id": "check-types-fixture-image-resolve-signal",
"script": "check:types:fixture:image-resolve-signal",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "UNKNOWN_DIAGNOSTIC_EVENT"
"expectedDiagnosticId": "error TS2741:"
},
{
"id": "test-runtime-schema",
@@ -208,6 +213,11 @@
"expectedExitCode": 1,
"expectedDiagnosticId": "Risk coverage failed:"
},
{
"id": "check-scale-pr",
"script": "check:scale:pr",
"expect": "pass"
},
{
"id": "test-component",
"script": "test:component",
@@ -285,11 +295,30 @@
"script": "review:a11y-manual",
"expect": "pass"
},
{
"id": "check-a11y-manual-format",
"script": "review:a11y-manual",
"args": [
"--",
"--format-only"
],
"expect": "pass"
},
{
"id": "check-architecture",
"script": "check:architecture",
"expect": "pass"
},
{
"id": "check-request-fanout",
"script": "check:request-fanout",
"expect": "pass"
},
{
"id": "check-app-build-input",
"script": "check:app-build-input",
"expect": "pass"
},
{
"id": "check-design-system",
"script": "check:design-system",
@@ -382,6 +411,11 @@
"expectedExitCode": 1,
"expectedDiagnosticId": "duplicates routeId=DUPLICATE"
},
{
"id": "check-adapter-inventory",
"script": "check:adapter-inventory",
"expect": "pass"
},
{
"id": "build",
"script": "build",
@@ -397,6 +431,11 @@
"script": "check:bundle",
"expect": "pass"
},
{
"id": "check-app-build-input-bundle",
"script": "check:app-build-input:bundle",
"expect": "pass"
},
{
"id": "check-optional-recipes",
"script": "check:optional-recipes",
@@ -447,7 +486,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-005"
"FE-RB-005",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -491,7 +532,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-001"
"FE-RB-001",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -500,7 +543,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-002"
"FE-RB-002",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -509,7 +554,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-003"
"FE-RB-003",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -518,7 +565,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-004"
"FE-RB-004",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -1097,55 +1146,37 @@
"id": "artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"path": "artifacts/tests/a11y-manual/APP_HOME.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-EXAMPLES-UI-md",
"path": "artifacts/tests/a11y-manual/EXAMPLES_UI.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-EXAMPLES-STATES-md",
"path": "artifacts/tests/a11y-manual/EXAMPLES_STATES.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-EXAMPLES-AUTH-md",
"path": "artifacts/tests/a11y-manual/EXAMPLES_AUTH.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-REFERENCE-RESOURCE-LIST-md",
"path": "artifacts/tests/a11y-manual/REFERENCE_RESOURCE_LIST.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"path": "artifacts/tests/a11y-manual/NOT_FOUND.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-report-json",
@@ -1499,12 +1530,6 @@
"build-release-candidate"
]
},
{
"id": "artifact-artifacts-quality-gates-FE-GATE-016-txt",
"path": "artifacts/quality/gates/FE-GATE-016.txt",
"schemaId": "text",
"production": "runner-generated"
},
{
"id": "artifact-artifacts-runbooks-FE-RB-005-record-json",
"path": "artifacts/runbooks/FE-RB-005/record.json",
@@ -1705,6 +1730,12 @@
"path": "artifacts/quality/gates/FE-GATE-027.txt",
"schemaId": "text",
"production": "runner-generated"
},
{
"id": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
"path": "artifacts/quality/gates/FE-GATE-028.txt",
"schemaId": "text",
"production": "runner-generated"
}
],
"gates": [
@@ -1760,7 +1791,8 @@
"check-types-fixture-icon-button",
"check-types-fixture-i18n-key",
"check-types-fixture-i18n-params",
"check-types-fixture-diagnostics"
"check-types-fixture-diagnostics",
"check-types-fixture-image-resolve-signal"
],
"logArtifactId": "artifact-artifacts-quality-check-types-txt",
"evidenceArtifactIds": [
@@ -1787,7 +1819,8 @@
"test-unit",
"test-contract",
"test-coverage",
"check-coverage-fixture"
"check-coverage-fixture",
"check-scale-pr"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-005-txt",
"evidenceArtifactIds": [
@@ -1864,18 +1897,11 @@
"name": "accessibility",
"commandIds": [
"test-a11y",
"review-a11y-manual"
"check-a11y-manual-format"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-009-txt",
"evidenceArtifactIds": [
"artifact-artifacts-tests-a11y-json",
"artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-UI-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-STATES-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-AUTH-md",
"artifact-artifacts-tests-a11y-manual-REFERENCE-RESOURCE-LIST-md",
"artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-report-json"
"artifact-artifacts-tests-a11y-json"
],
"retentionClassId": "merge-cycle"
},
@@ -1884,6 +1910,8 @@
"name": "architecture",
"commandIds": [
"check-architecture",
"check-request-fanout",
"check-app-build-input",
"check-design-system",
"check-design-system-fixture",
"check-i18n",
@@ -1900,6 +1928,7 @@
"check-registries-baseline-fixture",
"check-registries-fixture",
"check-routes-fixture",
"check-adapter-inventory",
"check-ci"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-010-txt",
@@ -1944,6 +1973,7 @@
"commandIds": [
"build",
"check-bundle",
"check-app-build-input-bundle",
"check-optional-recipes"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-012-txt",
@@ -2011,19 +2041,6 @@
],
"retentionClassId": "release-coherence"
},
{
"id": "FE-GATE-016",
"name": "rollback-drill",
"commandIds": [
"build",
"drill-runbook"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-016-txt",
"evidenceArtifactIds": [
"artifact-artifacts-runbooks-FE-RB-005-record-json"
],
"retentionClassId": "prod-drill"
},
{
"id": "FE-GATE-017",
"name": "diagram-review",
@@ -2063,7 +2080,7 @@
"evidenceArtifactIds": [
"artifact-artifacts-release-hosting-headers-json"
],
"retentionClassId": "release-coherence",
"retentionClassId": "prod-drill",
"requiresEnvironment": [
"HOSTING_BASE_URL"
]
@@ -2090,7 +2107,6 @@
"id": "FE-GATE-021",
"name": "runbook-boot-config",
"commandIds": [
"build",
"drill-runbook-2"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-021-txt",
@@ -2103,7 +2119,6 @@
"id": "FE-GATE-022",
"name": "runbook-chunk-mismatch",
"commandIds": [
"build",
"drill-runbook-3"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-022-txt",
@@ -2116,7 +2131,6 @@
"id": "FE-GATE-023",
"name": "runbook-api-degradation",
"commandIds": [
"build",
"drill-runbook-4"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-023-txt",
@@ -2129,7 +2143,6 @@
"id": "FE-GATE-024",
"name": "runbook-telemetry",
"commandIds": [
"build",
"drill-runbook-5"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-024-txt",
@@ -2142,7 +2155,6 @@
"id": "FE-GATE-025",
"name": "runbook-release-rollback",
"commandIds": [
"build",
"drill-runbook"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-025-txt",
@@ -2175,6 +2187,24 @@
"artifact-artifacts-release-deployment-admission-json"
],
"retentionClassId": "release-coherence"
},
{
"id": "FE-GATE-028",
"name": "manual-accessibility-review",
"commandIds": [
"review-a11y-manual"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
"evidenceArtifactIds": [
"artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-UI-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-STATES-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-AUTH-md",
"artifact-artifacts-tests-a11y-manual-REFERENCE-RESOURCE-LIST-md",
"artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-report-json"
],
"retentionClassId": "release-coherence"
}
],
"stages": [
@@ -2208,9 +2238,9 @@
"FE-GATE-012",
"FE-GATE-014",
"FE-GATE-015",
"FE-GATE-019",
"FE-GATE-026",
"FE-GATE-027"
"FE-GATE-027",
"FE-GATE-028"
]
},
{
@@ -2220,7 +2250,7 @@
"release"
],
"gateIds": [
"FE-GATE-016",
"FE-GATE-019",
"FE-GATE-021",
"FE-GATE-022",
"FE-GATE-023",
@@ -2314,18 +2344,13 @@
"gateIds": [
"FE-GATE-012",
"FE-GATE-014",
"FE-GATE-019",
"FE-GATE-026"
"FE-GATE-026",
"FE-GATE-028"
],
"browserGateIds": [
"FE-GATE-026"
],
"environment": [
{
"name": "HOSTING_BASE_URL",
"value": "${{ vars.HOSTING_BASE_URL }}"
}
],
"environment": [],
"steps": [
{
"kind": "checkout"
@@ -2745,12 +2770,13 @@
"displayName": "${{ matrix.gate }} / ${{ matrix.name }}",
"kind": "gate-matrix",
"needs": [
"immutable_build",
"promotion"
],
"condition": "production",
"timeoutMinutes": 45,
"gateIds": [
"FE-GATE-016",
"FE-GATE-019",
"FE-GATE-021",
"FE-GATE-022",
"FE-GATE-023",
@@ -2758,7 +2784,16 @@
"FE-GATE-025"
],
"browserGateIds": [],
"environment": [],
"environment": [
{
"name": "HOSTING_BASE_URL",
"value": "${{ vars.HOSTING_BASE_URL }}"
},
{
"name": "CANDIDATE_ARCHIVE_SHA256",
"value": "${{ needs.immutable_build.outputs.archive_sha256 }}"
}
],
"steps": [
{
"kind": "checkout"
@@ -2769,6 +2804,16 @@
{
"kind": "frozen-install"
},
{
"kind": "download",
"transferId": "promoted-release",
"path": ".release/promoted"
},
{
"kind": "extract",
"archivePath": ".release/promoted/release-candidate.tar.gz",
"targetRoot": ".release/promoted-release"
},
{
"kind": "run-gate"
},
+73
View File
@@ -0,0 +1,73 @@
{
"schemaVersion": 1,
"entries": [
{
"script": "check:feature-index",
"reason": "The generated indexes (src/.generated/) are not committed, and every gate script regenerates them first (generate-product-feature-index.ts), so --check can only tell a developer that the local copy is stale."
},
{
"script": "check:http-scenario-evidence",
"reason": "Run by scripts/run-http-scenario-evidence.ts, which is test:http-scenario-evidence in FE-GATE-007; that runner calls it by name after the scenario catalog."
},
{
"script": "check:http-scenario-evidence:fixture",
"reason": "Negative fixture run by scripts/run-http-scenario-evidence.ts (test:http-scenario-evidence, FE-GATE-007), which requires it to fail with TEST-EVIDENCE-EXECUTION-ID-MISSING."
},
{
"script": "check:remediation-ledger",
"reason": "Checks the prose ledger of the 2026-08-14 adapter re-review (docs/operations/adapter-remediation-ledger.md) against test-file markers and the file-transfer bundle budget. Later fixes removed those markers and the budget is re-set at integration, so the check reports stale claims at this commit. It is a history record run by hand, not a current contract; wiring it into a gate first needs the ledger or the markers brought up to date."
},
{
"script": "check:scale:baseline",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:main",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:nightly",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:release",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:test-evidence",
"reason": "Local all-in-one run. CI splits it: check:test-evidence:browser (--skip-scenario-executions) in FE-GATE-008 after the browser suites, and the scenario part through test:http-scenario-evidence in FE-GATE-007."
},
{
"script": "check:test-evidence:source",
"reason": "--source-only is a subset of check:test-evidence:browser (FE-GATE-008), for a quick local run without browser results."
},
{
"script": "drill:runbooks",
"reason": "Local shortcut for all five drills. CI runs each drill as its own production gate (FE-GATE-021 to FE-GATE-025) through drill:runbook."
},
{
"script": "test:all",
"reason": "Local aggregate of suites the gates run one by one (FE-GATE-004 to FE-GATE-007). The removal checks in FE-GATE-020 run it inside their fixtures through scripts/lib/removal-fixture.ts, not through the package script graph."
},
{
"script": "test:e2e:dev",
"reason": "Runs tests/e2e against the Vite dev server (playwright.dev.config.ts) for local debugging. FE-GATE-008 runs the same specs against the production build (test:e2e)."
},
{
"script": "test:extreme-scale:focused",
"reason": "Part of verify:extreme-scale. All its paths run in FE-GATE-005 except tests/scale/global-local-independence.test.ts, which belongs to the main scale tier (see config/ci/ungated-tests.json)."
},
{
"script": "test:visual:update",
"reason": "Rewrites the visual snapshots; it is an update command, not a check. FE-GATE-008 runs test:visual."
},
{
"script": "verify:extreme-scale",
"reason": "Local aggregate of 24 scripts (scripts/verify-extreme-scale.ts). Its CPU-independent parts run in gates; the main, nightly and release scale tiers need the baseline CPU (see check:scale:main)."
},
{
"script": "verify:promotion",
"reason": "Re-verifies a promotion bundle archived by an earlier run (13-04, --archived) with provider trust keys and EXPECTED_PROMOTION_* inputs of that run. In CI the promotion job verifies the same bundle through scripts/stage-verified-promotion.ts before it uploads it."
}
]
}
+29
View File
@@ -0,0 +1,29 @@
{
"schemaVersion": 1,
"entries": [
{
"path": "tests/scale/composition-scale.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/global-local-independence.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/session/long-session.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/session/network-flap.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/telemetry/telemetry-storm.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/tsc-diagnostics-parser.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
}
]
}
+57 -53
View File
@@ -1,63 +1,67 @@
{
"schemaVersion": 1,
"families": {
"api": {
"additive": {
"before": { "required": ["id"], "properties": { "id": {} } },
"after": {
"required": ["id"],
"properties": { "id": {}, "displayName": {} }
}
},
"breaking": {
"before": { "required": ["id"], "properties": { "id": {} } },
"after": {
"required": ["id", "name"],
"properties": { "id": {}, "name": {} }
}
"schemaVersion": 2,
"cases": [
{
"id": "tolerant-reader-optional-field",
"expected": "additive",
"before": { "required": ["id"], "properties": { "id": {} } },
"after": {
"required": ["id"],
"properties": { "id": {}, "displayName": {} }
}
},
"config": {
"additive": {
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
"after": {
"required": ["APP_ENV"],
"properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }
}
{
"id": "strict-reader-optional-field",
"expected": "breaking",
"before": {
"required": ["APP_ENV"],
"properties": { "APP_ENV": {} },
"additionalProperties": false
},
"breaking": {
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
"after": {
"required": ["APP_ENV", "NEW_REQUIRED"],
"properties": { "APP_ENV": {}, "NEW_REQUIRED": {} }
}
"after": {
"required": ["APP_ENV"],
"properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} },
"additionalProperties": false
}
},
"storage": {
"additive": {
"before": { "properties": { "theme": {} } },
"after": { "properties": { "theme": {}, "contrast": {} } }
},
"breaking": {
"before": { "properties": { "theme": {} } },
"after": { "properties": {} }
{
"id": "required-field-added",
"expected": "breaking",
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
"after": {
"required": ["buildId", "assetManifestHash"],
"properties": { "buildId": {}, "assetManifestHash": {} }
}
},
"release": {
"additive": {
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
"after": {
"required": ["buildId"],
"properties": { "buildId": {}, "builtAt": {} }
}
},
"breaking": {
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
"after": {
"required": ["buildId", "assetManifestHash"],
"properties": { "buildId": {}, "assetManifestHash": {} }
}
}
{
"id": "field-removed",
"expected": "breaking",
"before": { "properties": { "theme": {} } },
"after": { "properties": {} }
},
{
"id": "type-changed",
"expected": "breaking",
"before": { "properties": { "id": { "type": "string" } } },
"after": { "properties": { "id": { "type": "number" } } }
},
{
"id": "enum-narrowed",
"expected": "breaking",
"before": { "properties": { "state": { "enum": ["A", "B"] } } },
"after": { "properties": { "state": { "enum": ["A"] } } }
},
{
"id": "nullable-added",
"expected": "breaking",
"before": { "properties": { "note": { "type": "string" } } },
"after": { "properties": { "note": { "type": ["string", "null"] } } }
},
{
"id": "unchanged",
"expected": "none",
"before": { "required": ["id"], "properties": { "id": { "type": "string" } } },
"after": { "properties": { "id": { "type": "string" } }, "required": ["id"] }
}
}
]
}
@@ -0,0 +1,140 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"APP_ENV": {
"type": "string",
"enum": [
"local",
"development",
"staging",
"production"
]
},
"API_BASE_URL": {
"type": "string",
"format": "uri"
},
"REQUEST_TIMEOUT_MS": {
"default": 10000,
"type": "integer",
"minimum": 100,
"maximum": 60000
},
"MAX_RETRY_ATTEMPTS": {
"default": 2,
"type": "integer",
"minimum": 0,
"maximum": 2
},
"TELEMETRY_ENABLED": {
"type": "boolean"
},
"TELEMETRY_ENDPOINT": {
"type": "string",
"format": "uri"
},
"AUTH_MODE": {
"type": "string",
"enum": [
"external",
"demo"
]
},
"RELEASE_MANIFEST_URL": {
"default": "/release-manifest.json",
"type": "string",
"minLength": 1
},
"RELEASE_ID": {
"type": "string",
"minLength": 1
},
"BUILD_ID": {
"type": "string",
"minLength": 1
},
"CONFIG_SCHEMA_VERSION": {
"type": "string",
"const": "2.0"
},
"CAPABILITY_OVERRIDES": {
"default": {
"REALTIME": "DEFAULT",
"WEB_WORKER": "DEFAULT",
"SERVICE_WORKER": "DEFAULT",
"OFFLINE_COMMANDS": "DEFAULT"
},
"type": "object",
"properties": {
"REALTIME": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
},
"WEB_WORKER": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
},
"SERVICE_WORKER": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
},
"OFFLINE_COMMANDS": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
}
},
"required": [
"REALTIME",
"WEB_WORKER",
"SERVICE_WORKER",
"OFFLINE_COMMANDS"
],
"additionalProperties": false
},
"FEATURE_OVERRIDES": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,63}$"
},
"additionalProperties": {
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
}
}
},
"required": [
"APP_ENV",
"API_BASE_URL",
"REQUEST_TIMEOUT_MS",
"MAX_RETRY_ATTEMPTS",
"TELEMETRY_ENABLED",
"AUTH_MODE",
"RELEASE_MANIFEST_URL",
"CONFIG_SCHEMA_VERSION",
"CAPABILITY_OVERRIDES",
"FEATURE_OVERRIDES"
],
"additionalProperties": false
}
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"snapshotDigest": "96b95ef1d50cce36e9fca8a98776a9e2e9e3a5dca24a6288ad83bf29c94aebd8",
"snapshotDigest": "83d11f848b8b2f67bcb657403f112d4baaf05481ab6bcee94ebc6851c32e2159",
"owner": "frontend-platform",
"reason": "Baseline canonical invalidation graph and topic-version contracts after FE-REG-QUERY retirement",
"approvedAt": "2026-08-01T15:15:45.537Z"
"reason": "07-04: FE-REG-ERROR drops severity, telemetryEvent and redaction, which nothing read",
"approvedAt": "2026-09-25T15:11:58.763Z"
}
+56 -473
View File
@@ -640,7 +640,7 @@
"registryId": "FE-REG-ENV",
"owner": "feature-frontend-env-runtime-config-contract",
"source": "src/contracts/env.ts",
"rowCount": 14,
"rowCount": 16,
"contract": {
"requiredFields": [
"phase",
@@ -706,6 +706,12 @@
"phase": "runtime",
"required": true
},
"FEATURE_OVERRIDES": {
"classification": "public",
"defaultValue": null,
"phase": "runtime",
"required": false
},
"MAX_RETRY_ATTEMPTS": {
"classification": "public",
"defaultValue": 2,
@@ -748,6 +754,12 @@
"phase": "build",
"required": false
},
"VITE_PRODUCT_FEATURES": {
"classification": "compile-time",
"defaultValue": null,
"phase": "build",
"required": false
},
"VITE_ROUTER_BASE_PATH": {
"classification": "compile-time",
"defaultValue": "/",
@@ -766,7 +778,7 @@
"registryId": "FE-REG-STORAGE",
"owner": "feature-frontend-storage-registry-contract",
"source": "src/contracts/storage-keys.ts",
"rowCount": 4,
"rowCount": 7,
"contract": {
"requiredFields": [
"logicalName",
@@ -847,6 +859,19 @@
"ttl": null,
"valueCodec": "none"
},
"CACHE_INVALIDATION_PULSE": {
"backend": "localStorage",
"classification": "opaque-cache",
"logicalName": "CACHE_INVALIDATION_PULSE",
"migration": "discard",
"name": "pulse",
"physicalKey": "ca-frontend:cache-invalidation:v1:pulse",
"quotaFallback": "no-persist",
"schemaVersion": 1,
"scope": "cache-invalidation",
"ttl": null,
"valueCodec": "opaque-string-v1"
},
"CHUNK_RELOAD_GUARD": {
"backend": "sessionStorage",
"classification": "opaque-cache",
@@ -873,6 +898,19 @@
"ttl": null,
"valueCodec": "color-scheme-v1"
},
"LOCALE": {
"backend": "localStorage",
"classification": "public-preference",
"logicalName": "LOCALE",
"migration": "discard",
"name": "locale",
"physicalKey": "ca-frontend:preference:v1:locale",
"quotaFallback": "memory",
"schemaVersion": 1,
"scope": "preference",
"ttl": null,
"valueCodec": "opaque-string-v1"
},
"QUERY_PERSISTENCE": {
"backend": "disabled",
"classification": "sensitive-forbidden",
@@ -885,6 +923,19 @@
"scope": "cache",
"ttl": null,
"valueCodec": "none"
},
"RELEASE_MISMATCH_RECOVERY": {
"backend": "sessionStorage",
"classification": "opaque-cache",
"logicalName": "RELEASE_MISMATCH_RECOVERY",
"migration": "discard",
"name": "boot-mismatch-recovery",
"physicalKey": "ca-frontend:release:v1:boot-mismatch-recovery",
"quotaFallback": "no-persist",
"schemaVersion": 1,
"scope": "release",
"ttl": "session",
"valueCodec": "opaque-string-v1"
}
}
},
@@ -897,30 +948,19 @@
"requiredFields": [
"kind",
"defaultRetryable",
"severity",
"userMessageKey",
"action",
"telemetryEvent",
"redaction"
"action"
],
"fieldTypes": {
"kind": "string",
"defaultRetryable": "boolean",
"severity": "string",
"userMessageKey": "string",
"action": "string",
"telemetryEvent": "string",
"redaction": "array"
"action": "string"
},
"uniqueFields": [
"kind"
],
"allowedValues": {
"severity": [
"info",
"warning",
"error"
],
"action": [
"retry",
"reauth",
@@ -935,8 +975,7 @@
"breakingFields": [
"kind",
"userMessageKey",
"action",
"telemetryEvent"
"action"
]
},
"rows": {
@@ -944,684 +983,228 @@
"action": "contact-support",
"defaultRetryable": false,
"kind": "API_CONTRACT_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.api_contract_mismatch"
},
"ASSET_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "ASSET_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.asset_mismatch"
},
"AUTH_INTEGRATION_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "AUTH_INTEGRATION_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.auth_integration_failure"
},
"AUTH_REQUIRED": {
"action": "reauth",
"defaultRetryable": false,
"kind": "AUTH_REQUIRED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.auth_required"
},
"BOOT_CONFIG_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "BOOT_CONFIG_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.boot_config_failure"
},
"BUILD_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "BUILD_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.build_mismatch"
},
"CHUNK_LOAD_FAILURE": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "CHUNK_LOAD_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.chunk_load_failure"
},
"CONFIG_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "CONFIG_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.config_mismatch"
},
"CONFLICT": {
"action": "retry",
"defaultRetryable": false,
"kind": "CONFLICT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.conflict"
},
"CONTENT_TYPE_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "CONTENT_TYPE_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.content_type_mismatch"
},
"DEPLOY_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "DEPLOY_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.deploy_mismatch"
},
"DUPLICATE_IN_FLIGHT": {
"action": "none",
"defaultRetryable": false,
"kind": "DUPLICATE_IN_FLIGHT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.duplicate_in_flight"
},
"ENVELOPE_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "ENVELOPE_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.envelope_mismatch"
},
"FORBIDDEN": {
"action": "navigate",
"defaultRetryable": false,
"kind": "FORBIDDEN",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.forbidden"
},
"IDENTITY_INTERN_LIMIT_EXCEEDED": {
"action": "retry",
"defaultRetryable": false,
"kind": "IDENTITY_INTERN_LIMIT_EXCEEDED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.identity_intern_limit_exceeded"
},
"MALFORMED_JSON": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "MALFORMED_JSON",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.malformed_json"
},
"MAPPING_CONTRACT_VIOLATION": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "MAPPING_CONTRACT_VIOLATION",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.mapping_contract_violation"
},
"NETWORK_UNREACHABLE": {
"action": "retry",
"defaultRetryable": true,
"kind": "NETWORK_UNREACHABLE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.network_unreachable"
},
"NOT_FOUND": {
"action": "navigate",
"defaultRetryable": false,
"kind": "NOT_FOUND",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.not_found"
},
"PAGINATION_CONTRACT_VIOLATION": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "PAGINATION_CONTRACT_VIOLATION",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.pagination_contract_violation"
},
"QUERY_CACHE_FAILURE": {
"action": "retry",
"defaultRetryable": false,
"kind": "QUERY_CACHE_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "query.cache.failed",
"userMessageKey": "error.query_cache_failure"
},
"RATE_LIMITED": {
"action": "retry",
"defaultRetryable": true,
"kind": "RATE_LIMITED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.rate_limited"
},
"RELEASE_MANIFEST_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "RELEASE_MANIFEST_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.release_manifest_failure"
},
"RELEASE_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "RELEASE_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.release_mismatch"
},
"RENDER_FAILURE": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "RENDER_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "ui.render.failed",
"userMessageKey": "error.render_failure"
},
"REQUEST_ABORTED": {
"action": "none",
"defaultRetryable": false,
"kind": "REQUEST_ABORTED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.request_aborted"
},
"REQUEST_TIMEOUT": {
"action": "retry",
"defaultRetryable": true,
"kind": "REQUEST_TIMEOUT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.request_timeout"
},
"RESPONSE_BODY_LIMIT": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "RESPONSE_BODY_LIMIT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.response_body_limit"
},
"RESULT_LIMIT_EXCEEDED": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "RESULT_LIMIT_EXCEEDED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.result_limit_exceeded"
},
"SCHEMA_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "SCHEMA_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.schema_mismatch"
},
"SCOPE_GENERATION_CHANGED": {
"action": "none",
"defaultRetryable": false,
"kind": "SCOPE_GENERATION_CHANGED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.scope_generation_changed"
},
"SERVER_FAILURE": {
"action": "retry",
"defaultRetryable": true,
"kind": "SERVER_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.server_failure"
},
"STORAGE_QUOTA_EXCEEDED": {
"action": "none",
"defaultRetryable": false,
"kind": "STORAGE_QUOTA_EXCEEDED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "storage.operation.failed",
"userMessageKey": "error.storage_quota_exceeded"
},
"STORAGE_UNAVAILABLE": {
"action": "none",
"defaultRetryable": false,
"kind": "STORAGE_UNAVAILABLE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "storage.operation.failed",
"userMessageKey": "error.storage_unavailable"
},
"TELEMETRY_FAILURE": {
"action": "none",
"defaultRetryable": false,
"kind": "TELEMETRY_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "telemetry.delivery.dropped",
"userMessageKey": "error.telemetry_failure"
},
"UNKNOWN_CLIENT_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "UNKNOWN_CLIENT_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.unknown_client_failure"
},
"UNKNOWN_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "UNKNOWN_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.unknown_failure"
},
"VALIDATION_REJECTED": {
"action": "none",
"defaultRetryable": false,
"kind": "VALIDATION_REJECTED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.validation_rejected"
}
}
@@ -104,6 +104,22 @@
"compatibilityWindow": "No wire, storage or runtime-config format changes: the old id was never emitted by any producer, so no consumer could observe it.",
"rollback": "Restore the previous telemetryEvent string on QUERY_CACHE_FAILURE in src/contracts/errors.ts and widen ErrorObservationEvent back to string.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-ENV:VITE_BUILD_ID:defaultValue:field-type-changed",
"versionBump": "F-6 (13-15): the registry now records the local-build fallback that getBuildConfig and the build scripts already applied; the value itself did not change.",
"migration": "None for local builds. A staging or production build without VITE_BUILD_ID now fails in scripts/generate-runtime-config.ts instead of shipping the placeholder that admission refused.",
"compatibilityWindow": "No runtime document or wire format changes: BUILD_ID was already local-build whenever VITE_BUILD_ID was unset.",
"rollback": "Restore defaultValue null on VITE_BUILD_ID in src/contracts/env.ts and drop the public-target check in scripts/generate-runtime-config.ts.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-ROUTE:REFERENCE_RESOURCE_DETAIL:path:field-changed",
"versionBump": "The reference detail route moves from /examples/reference-resources/:resourceId to /examples/reference-resources/items/:resourceId (maturity review 08-13), so a server id equal to the static segments new or status opens its detail instead of the form or status screen.",
"migration": "The only in-app link (reference-resource-page.tsx) builds the new path from the contract route. The reference feature is a sample; downstream features that copied it keep their own paths.",
"compatibilityWindow": "None for bookmarked sample detail URLs: an old /examples/reference-resources/<id> URL no longer matches the detail route; new and status keep opening the form and status screens.",
"rollback": "Restore the previous path in src/features/reference-feature/contracts/reference-feature-contract.ts and the link in reference-resource-page.tsx, then drop this entry.",
"owner": "frontend-platform"
}
]
}
+7 -14
View File
@@ -193,8 +193,8 @@
],
"consumerIdentityField": "operationId",
"consumerDirectories": [
"src/features/reference-feature/adapters",
"src/features/reference-feature/application"
"src/features/*/adapters",
"src/features/*/application"
],
"breakingFields": [
"method",
@@ -234,8 +234,8 @@
"consumerIdentityField": "schemaId",
"consumerDirectories": [
"src/presentation/routes",
"src/features/reference-feature/presentation",
"src/features/reference-feature/contracts"
"src/features/*/presentation",
"src/features/*/contracts"
],
"breakingFields": ["schemaId", "boundary", "runtime"]
},
@@ -344,24 +344,17 @@
"requiredFields": [
"kind",
"defaultRetryable",
"severity",
"userMessageKey",
"action",
"telemetryEvent",
"redaction"
"action"
],
"fieldTypes": {
"kind": "string",
"defaultRetryable": "boolean",
"severity": "string",
"userMessageKey": "string",
"action": "string",
"telemetryEvent": "string",
"redaction": "array"
"action": "string"
},
"uniqueFields": ["kind"],
"allowedValues": {
"severity": ["info", "warning", "error"],
"action": [
"retry",
"reauth",
@@ -377,7 +370,7 @@
"token": "failure("
}
],
"breakingFields": ["kind", "userMessageKey", "action", "telemetryEvent"]
"breakingFields": ["kind", "userMessageKey", "action"]
},
{
"registryId": "FE-REG-QUERY-INVALIDATION",
@@ -67,7 +67,7 @@
"lifecycleMethods": ["close-or-dispose", "unsubscribe", "cancel-via-AbortSignal", "bounded-poll-lease", "revoke-push-association"],
"owner": "project-owner-required",
"securityPrivacy": ["Validate every event envelope and closed transport frame before application effects.", "Bind stream state to the current opaque scope generation and advance checkpoints only after committed effects or authoritative recovery.", "Use fixed same-origin endpoints and an exact WebSocket subprotocol; never place credentials, cursors, subscription material or scope bindings in URLs or telemetry.", "Treat Web Push as a notification hint, fence registration and revocation with one durable compare-and-swap control record, and allow only registry-owned notification and route intents.", "Keep every queue, parser, reconnect, poll, notification and storage operation bounded and abortable."],
"bundleBudgetGzipBytes": 40000,
"bundleBudgetGzipBytes": 40900,
"fallback": "Bounded polling or explicitly stale UI.",
"removal": ["Disable admission and close active readers, sockets, poll leases and worker handlers.", "Revoke and purge only the owned Web Push association and notification state.", "Remove composition, registries, adapters and any selected vendor dependency.", "Run realtime boundary, runtime-removal and production-bundle gates."],
"serverStatePolicy": "query-cache-owned"
@@ -109,7 +109,7 @@
"lifecycleMethods": ["close", "cancel-via-AbortSignal", "enforce-bounded-lifecycle-batch", "prune-expired-receipts", "reconcile", "enforcePolicies-with-composition-authority"],
"owner": "project-owner-required",
"securityPrivacy": ["Classify every persisted field and binary namespace.", "Encrypting in the same client is not a credential protection boundary.", "Keep database schema and record codec versions separate.", "Derive the physical IndexedDB name only from registry-issued authority, namespace and partition tokens; readable namespace, business and account IDs are forbidden.", "Persist and revalidate an immutable scope plus full BrowserStoragePolicy binding during upgrade, post-open and maintenance; missing or mismatched existing bindings fail closed.", "Use the actual IndexedDB wire split: StoredRecord contains only key, codecVersion, revision and payload; writtenAtEpochMs, synchronization, measuredBytes and eligibleAtEpochMs belong to the retention sidecar, while idempotency receipts and governance binding/budget use separate stores.", "Include every store registered in lifecycleMetadataStores in bounded full-partition purge while retaining immutable governance identity.", "Measure conservative logical bytes through the codec and atomically enforce dataset usedBytes plus receiptCount with record, lifecycle and migration writes.", "Enforce TTL before sweep visibility, delete UNTIL_SYNCED only after explicit confirmation, and require a composition-authorized short-lived proof for every deleting IndexedDB lifecycle batch.", "Bound idempotency receipt retention to 31 days and configured count to the implementation ceiling of 1000000; bound migration to old-writer-drained batches no larger than 500 rows or 30000ms.", "Bind OPFS readable and physical scopes in both directions and use only /ca-frontend-opfs-v1/authorities/<authorityToken>/<namespaceToken>/<partitionToken>/ for physical dataset layout.", "For OPFS LOGOUT, UNTIL_SYNCED and ACCOUNT_DELETION maintenance, composition must provide both requestMaintenanceAuthority and consumeMaintenanceAuthority; issue a fresh proof bound to the exact frozen reason, scope and policy for at most five minutes, then atomically consume it to reject replay.", "Never expose an OPFS authority proof through the application request, persistence, diagnostics or telemetry.", "Never place user file names or identifiers in OPFS paths or diagnostics."],
"bundleBudgetGzipBytes": 36000,
"bundleBudgetGzipBytes": 36900,
"fallback": "Read-only or online-only query path; OPFS may degrade to a size-capped IndexedDB Blob only when the product policy approves it.",
"removal": ["Stop writes and background migration.", "Reconcile or export unsynced data, then purge only governance-bound owned partitions and OPFS namespaces through authorized bounded lifecycle operations.", "Close all database, channel, worker and file handles.", "Remove repository composition and dependency."],
"serverStatePolicy": "reference-or-command-only"
@@ -192,10 +192,10 @@
"port": "FilePickerPort / FileContentPort / TransientPreviewPort / DownloadDeliveryPort / PresignedDownloadSourcePort / PresignedUploadPartPort / ResumableUploadPort / ImageCdnPresentationPort",
"fake": "Memory file/preview/download adapters plus injected deterministic capability, upload-control-plane, part-executor and image-verifier test doubles",
"failureKinds": ["dismissed", "permission-denied", "count-or-size-rejection", "type-or-signature-rejection", "file-changed", "abort", "integrity-failure", "partial-save", "expired-or-revoked-capability", "part-or-session-conflict", "checkpoint-conflict", "quarantined", "image-policy-rejection"],
"lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime"],
"lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime", "dispose-browser-file-runtime-on-logout-or-account-switch"],
"owner": "project-owner-required",
"securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."],
"bundleBudgetGzipBytes": 54600,
"bundleBudgetGzipBytes": 55700,
"fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation.",
"removal": ["Stop new capability and upload-session issuance, then cancel active reads and transfers.", "Reconcile or explicitly abort active multipart sessions and let backend TTL cleanup remove ambiguous orphans.", "Remove non-secret checkpoints according to account and retention policy.", "Release file references, revoke preview object-URL leases and dispose file, capability and image runtimes.", "Remove transfer/image feature facades and composition, then prove browser-transfer sources are absent from the production module inventory."],
"serverStatePolicy": "query-cache-metadata-only"
+41
View File
@@ -0,0 +1,41 @@
{
"schemaVersion": 1,
"baseline": "config/scale/feature-shape-growth.json",
"ceilings": {
"contextMaxFeatures": 200,
"appMaxContexts": 20
},
"summary": "The ceilings bound the count; they are not a verified capacity. The practical limit of one app is the initial JavaScript budget, then typecheck memory. 400 features were not measured (D-18 makes it optional).",
"axes": [
{
"axis": "Typecheck of one app",
"verified": "Linear, about 115k instantiations and 37 MB of tsc memory per feature, up to 100 features",
"condition": "Reference-shaped features, tsconfig.app.json, the host recorded in the baseline",
"notVerified": "200 features (one full context) and beyond; 4,000 (20 x 200) would need on the order of 150 GB by the same slope"
},
{
"axis": "Production build",
"verified": "Completes at 100 features in seconds",
"condition": "Same",
"notVerified": "Beyond 100"
},
{
"axis": "Initial JavaScript",
"verified": "Grows by about 2.9 KB gzip and one file per feature: every installed feature's contracts and module load at boot",
"condition": "Same",
"notVerified": "The initial budget (204,800 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling"
},
{
"axis": "Lazy JavaScript",
"verified": "About 6.8 KB gzip and six files per feature, every file far below the 120 KiB lazy-chunk budget",
"condition": "Same",
"notVerified": "Download cost of many lazy files"
},
{
"axis": "Routes",
"verified": "4 per feature, composed without conflict",
"condition": "Same",
"notVerified": "Router matching cost at runtime"
}
]
}
+210
View File
@@ -0,0 +1,210 @@
{
"schemaVersion": 1,
"measuredAt": "2026-09-27T04:03:00.821Z",
"command": "node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100 --repeats=2",
"environment": {
"node": "24.14.0",
"platform": "linux",
"arch": "x64",
"cpuModel": "Intel(R) Core(TM) i5-10400F CPU @ 2.90GHz",
"logicalCpus": 12,
"availableParallelism": 12,
"typescript": "Version 7.0.2",
"vite": "vite/8.1.5 linux-x64 node-v24.14.0"
},
"sourceFeature": "src/features/reference-feature",
"runs": [
{
"repeat": 1,
"addedFeatures": 0,
"routes": 10,
"tsc": {
"passed": true,
"firstError": null,
"files": 840,
"types": 284678,
"symbols": 802946,
"instantiations": 712089,
"memoryKb": 520454,
"wallMs": 3408
},
"build": {
"wallMs": 1208,
"initialJavascriptFiles": 13,
"initialJavascriptGzipBytes": 200001,
"lazyJavascriptFiles": 14,
"lazyJavascriptGzipBytes": 24938
},
"loadBefore": [
25.05,
16.88,
7.75
],
"loadAfter": [
26.4,
17.3,
7.93
]
},
{
"repeat": 2,
"addedFeatures": 0,
"routes": 10,
"tsc": {
"passed": true,
"firstError": null,
"files": 840,
"types": 284678,
"symbols": 802946,
"instantiations": 712089,
"memoryKb": 520395,
"wallMs": 3930
},
"build": {
"wallMs": 1526,
"initialJavascriptFiles": 13,
"initialJavascriptGzipBytes": 200001,
"lazyJavascriptFiles": 14,
"lazyJavascriptGzipBytes": 24938
},
"loadBefore": [
26.4,
17.3,
7.93
],
"loadAfter": [
27.65,
17.71,
8.12
]
},
{
"repeat": 1,
"addedFeatures": 25,
"routes": 110,
"tsc": {
"passed": true,
"firstError": null,
"files": 1366,
"types": 1055723,
"symbols": 2831441,
"instantiations": 3579093,
"memoryKb": 1422337,
"wallMs": 8121
},
"build": {
"wallMs": 1676,
"initialJavascriptFiles": 39,
"initialJavascriptGzipBytes": 274493,
"lazyJavascriptFiles": 165,
"lazyJavascriptGzipBytes": 171638
},
"loadBefore": [
27.65,
17.71,
8.12
],
"loadAfter": [
27.17,
17.93,
8.29
]
},
{
"repeat": 2,
"addedFeatures": 25,
"routes": 110,
"tsc": {
"passed": true,
"firstError": null,
"files": 1366,
"types": 1055723,
"symbols": 2831441,
"instantiations": 3579093,
"memoryKb": 1422431,
"wallMs": 8714
},
"build": {
"wallMs": 2140,
"initialJavascriptFiles": 39,
"initialJavascriptGzipBytes": 274493,
"lazyJavascriptFiles": 165,
"lazyJavascriptGzipBytes": 171638
},
"loadBefore": [
27.17,
17.93,
8.29
],
"loadAfter": [
27.55,
18.46,
8.62
]
},
{
"repeat": 1,
"addedFeatures": 100,
"routes": 410,
"tsc": {
"passed": true,
"firstError": null,
"files": 2941,
"types": 3349868,
"symbols": 8940533,
"instantiations": 12157304,
"memoryKb": 4195900,
"wallMs": 31315
},
"build": {
"wallMs": 6010,
"initialJavascriptFiles": 114,
"initialJavascriptGzipBytes": 490658,
"lazyJavascriptFiles": 615,
"lazyJavascriptGzipBytes": 704938
},
"loadBefore": [
27.43,
18.59,
8.71
],
"loadAfter": [
29.72,
20.12,
9.64
]
},
{
"repeat": 2,
"addedFeatures": 100,
"routes": 410,
"tsc": {
"passed": true,
"firstError": null,
"files": 2941,
"types": 3349868,
"symbols": 8940533,
"instantiations": 12157304,
"memoryKb": 4195704,
"wallMs": 43234
},
"build": {
"wallMs": 3702,
"initialJavascriptFiles": 114,
"initialJavascriptGzipBytes": 490658,
"lazyJavascriptFiles": 615,
"lazyJavascriptGzipBytes": 704938
},
"loadBefore": [
29.72,
20.12,
9.64
],
"loadAfter": [
35.75,
22.97,
11.09
]
}
]
}
@@ -1,6 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "ART-FE-RUNBOOK-DRILL@1",
"$id": "ART-FE-RUNBOOK-DRILL@2",
"type": "object",
"required": [
"schemaVersion",
@@ -14,29 +14,39 @@
"recoveryAssertions",
"negativeFixtureFailedAsExpected",
"windowObservedBucket",
"passed"
"providerVerificationRequired",
"result"
],
"$defs": {
"verdict": { "enum": ["PASS", "FAIL", "UNVERIFIED"] }
},
"properties": {
"schemaVersion": { "const": 1 },
"schemaVersion": { "const": 2 },
"runbookId": { "pattern": "^FE-RB-00[1-5]$" },
"releaseId": { "type": "string", "minLength": 1 },
"drillTimestamp": { "type": "string", "format": "date-time" },
"triggerInjected": { "type": "string" },
"triggerAsserted": { "type": "boolean" },
"containmentAsserted": { "type": "boolean" },
"escalationPathAsserted": { "type": "boolean" },
"triggerAsserted": { "$ref": "#/$defs/verdict" },
"containmentAsserted": { "$ref": "#/$defs/verdict" },
"escalationPathAsserted": { "$ref": "#/$defs/verdict" },
"recoveryAssertions": {
"type": "array",
"minItems": 4,
"items": {
"type": "object",
"required": ["assertion", "evidence", "passed"]
"required": ["assertion", "evidence", "result"],
"properties": {
"assertion": { "type": "string", "minLength": 1 },
"evidence": { "type": "string", "minLength": 1 },
"result": { "$ref": "#/$defs/verdict" }
},
"additionalProperties": false
}
},
"negativeFixtureFailedAsExpected": { "type": "boolean" },
"negativeFixtureFailedAsExpected": { "$ref": "#/$defs/verdict" },
"windowObservedBucket": { "type": "string" },
"providerVerificationRequired": { "type": "boolean" },
"passed": { "type": "boolean" }
"result": { "$ref": "#/$defs/verdict" }
},
"additionalProperties": false
}
+34 -1
View File
@@ -178,6 +178,36 @@
"functions": 90,
"branches": 80
}
},
{
"path": "src/adapters/http/http-contract-bridge.ts",
"owner": "http-runtime",
"minimum": {
"lines": 85,
"statements": 79,
"functions": 100,
"branches": 73
}
},
{
"path": "src/adapters/http/http-retry-lifecycle.ts",
"owner": "http-runtime",
"minimum": {
"lines": 100,
"statements": 100,
"functions": 100,
"branches": 100
}
},
{
"path": "src/adapters/storage/indexeddb/indexeddb-runtime.ts",
"owner": "storage-runtime",
"minimum": {
"lines": 79,
"statements": 76,
"functions": 73,
"branches": 72
}
}
],
"highRiskPaths": [
@@ -197,7 +227,10 @@
"src/bootstrap/read-bounded-boot-json.ts",
"src/contracts/diagnostics.ts",
"src/features/reference-feature/adapters/reference-http-gateway.ts",
"src/presentation/adapters/query/application-query.ts"
"src/presentation/adapters/query/application-query.ts",
"src/adapters/http/http-contract-bridge.ts",
"src/adapters/http/http-retry-lifecycle.ts",
"src/adapters/storage/indexeddb/indexeddb-runtime.ts"
],
"waivers": []
}
+72
View File
@@ -0,0 +1,72 @@
# 문서 색인
`docs/`의 문서를 세 묶음으로 나눈다.
```text
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
```
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
## 1. 현재 계약
처음 읽을 입구 문서 6개다.
| 문서 | 정하는 것 |
|---|---|
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
| `architecture/review-ledger.json`, `architecture/review-evidence.md`, `accessibility/manual-checklist.md` | `verify:documentation` (FE-GATE-017) |
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
## 2. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](architecture/browser-data-capability-completion-ledger.md)
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](architecture/frontend-platform-capability-review.md), [`architecture/frontend-platform-implementation-roadmap.md`](architecture/frontend-platform-implementation-roadmap.md)
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](architecture/frontend-ports-adapters-and-boundaries.md), [`architecture/typescript-state-and-data-flow.md`](architecture/typescript-state-and-data-flow.md), [`architecture/routing-pages-and-patterns.md`](architecture/routing-pages-and-patterns.md)
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](architecture/api-contract-schema-mapper-and-server-state.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](architecture/protobuf-browser-transport-and-rest-gateway.md)
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](architecture/client-cache-and-storage.md), [`architecture/browser-file-and-origin-storage.md`](architecture/browser-file-and-origin-storage.md), [`architecture/presigned-transfer-and-image-cdn.md`](architecture/presigned-transfer-and-image-cdn.md), [`architecture/server-file-capability-infrastructure.md`](architecture/server-file-capability-infrastructure.md)
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](architecture/realtime-events-web-push-and-bounded-polling.md)
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](styling/design-system-platform.md), [`testing/frontend-platform-testing-strategy.md`](testing/frontend-platform-testing-strategy.md)
- 결정 기록(ADR): [`architecture/decisions/`](architecture/decisions/) `VD-*.md`
## 3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
| [`reviews/`](reviews/) | 리뷰 결과와 리뷰 가이드. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다 |
| [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 `docs/` 밖에 그대로 둔다 |
+19
View File
@@ -10,6 +10,12 @@ registry: `APP_HOME`, `EXAMPLES_PLATFORM`, `EXAMPLES_UI`, `EXAMPLES_STATES`,
blank identity/timestamp/signature fields, pending verdicts, mismatched release
IDs, or missing routes.
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
it is required once per release candidate, not on every merge. The merge gate
FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
and a record marked `reviewed` must be complete.
This list is not maintained by hand: `verify:documentation` compares it against
the installed route registry and fails when a registered route is absent. It
said six routes while ten were registered, which put the platform overview and
@@ -57,3 +63,16 @@ The reviewer must verify:
not be marked not-applicable on that route. Passing automated evidence means
only that tested pages had no critical or serious axe findings under the
recorded Chromium, Firefox, and WebKit runs.
What the automated run scans:
- Every registered route, after the route's own `h1` is on screen, so the scan
never lands on the app shell's loading surface
(`tests/e2e/accessibility.spec.ts`). A public route's `h1` must equal its
catalog title.
- Protected routes after the demo sign-in, never the sign-in prompt. Their API
calls answer an empty list there.
- The reference sample's list in its success, empty and error states, its
detail, its form with submit errors and its status page, each after that
state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the
sample).
@@ -206,7 +206,7 @@ src/shared/api
### 1.2 계층 방향
현재 `config/architecture/layers.json`의 방향을 유지한다.
현재 방향을 유지한다. 기준은 `.dependency-cruiser.json` 하나이고 `check:architecture`가 강제한다(`config/architecture/layers.json`은 아무도 읽지 않는 낡은 사본이라 지웠다, 리뷰 12-09).
```text
domain -> domain only
@@ -635,6 +635,7 @@ export interface CommandEffectDescriptor<Problem> {
status: number;
problem: Problem;
}>): "NOT_APPLIED" | "APPLIED_CONFIRMED" | "MAYBE_APPLIED";
classifyStatus?(status: 401 | 403 | 429): "NOT_APPLIED" | "MAYBE_APPLIED";
}
```
@@ -647,6 +648,8 @@ export interface CommandEffectDescriptor<Problem> {
- frontend는 inspect request/response wire shape나 problem effect meaning을 작성하지 않는다;
- `classifyProblem`은 package가 제공한 pure bounded classifier다;
- classifier가 throw/unknown을 반환하면 effect는 fail-safe `MAYBE_APPLIED`이고 contract runtime failure를 기록한다;
- 401·403·429는 본문을 읽기 전에 판정하므로 `classifyProblem`을 거치지 않는다. package가 `classifyStatus`를 주면 그 판정을 쓰고, 없거나 `NOT_APPLIED` 외 값·throw면 전송 뒤 `MAYBE_APPLIED`다(`src/adapters/http/http-effect-certainty.ts` `classifyStatusEffect`);
- `AUTH_REQUIRED`는 effect가 `MAYBE_APPLIED`여도 action이 `reauth`다(`src/contracts/errors.ts` `unknownEffectAction`);
- feature gateway가 package의 inspect operation을 application-safe outcome으로 mapping한다.
### 4.5 event contribution
@@ -253,7 +253,9 @@ Cross-origin bearer provider 최소 CORS:
- exact allow-origin 목록과 bounded preflight cache
- `Authorization`, `Content-Type`, `Idempotency-Key`,
`X-Correlation-ID`, 향후 `If-None-Match`, `If-Match` 허용
- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose
- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose.
`X-Correlation-ID`를 expose하면 V3 실패의 `AppFailure.requestId`가 된다
(`src/adapters/http/feature-http-binding.ts`)
- redirect login page, HTML error body와 wildcard credential 금지
## 6. Command와 idempotency
@@ -593,6 +595,21 @@ query invalidate hint로만 쓸지 operation별 reducer contract가 필요하다
- rate limit key는 principal/tenant/operation과 abuse policy에 binding하며 raw
credential/IP를 metric label에 넣지 않는다.
### 16.1 전송별 재시도·타임아웃 규칙 (2026-09-25 코드 기준)
같은 이름의 정책이라도 전송마다 동작이 다르다. operation을 다른 전송으로 옮기면
이 표로 동작 변화를 확인한다.
| 규칙 | V3 contract executor (기본 경로) | V2 client (기본 조합에 없음) | Browser RPC |
|---|---|---|---|
| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | 네트워크·타임아웃·429·408/425/502/503/504 뒤 같은 키로 다시 보낸다. 전송 여부를 보지 않는다 (`src/adapters/http/retry-policy.ts` `shouldRetry`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) |
| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | `MAX_RETRY_ATTEMPTS`, 기본 2 (`client.ts` `maxRetryAttempts`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) |
| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | 30초를 넘으면 재시도하지 않는다. 이하면 max(backoff, hint)만큼 기다린다 (`retry-policy.ts`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) |
| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 기본값이다. operation `timeoutMs`가 있으면 그 값을 쓰고, 더 길 수도 있다 (`client.ts` `defaultTimeoutMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 |
결과 불명 뒤 사용자 재전송은 전송과 무관하게 같은 intent·같은 키를 쓴다
(`src/presentation/adapters/query/application-query.ts` `resendUnknownEffect`).
## 17. Observability와 privacy
허용되는 공통 dimension:
@@ -353,8 +353,23 @@ digest 또는 별도 검토된 streaming hash adapter를 사용한다.
- one-shot 작은 download는 click handoff 뒤 cross-engine scheduling을 위해 기본
30초 grace를 두고 revoke한다. feature/runtime dispose는 grace를 기다리지 않고
모든 active lease를 즉시 revoke한다.
- preview와 download는 runtime 하나의 lease registry를 같이 쓴다
(`src/adapters/browser-files/create-browser-file-runtime.ts:154`, `:163`).
lease 개수나 합계 바이트 한도가 차면 둘 다 `LIMIT_EXCEEDED`를
`retryable: true`, `recovery: "RETRY"`로 반환한다
(`src/adapters/browser-files/object-url-lease.ts:48-73`, `:131-139`). download
lease는 grace(`download-delivery-adapter.ts:149`)가 끝나면 풀리므로 잠시 뒤
다시 시도하면 된다. Blob 하나가 단일 lease 상한을 넘으면 재시도 불가다.
- URL을 global state, IndexedDB, query cache, log, analytics에 보관하지 않는다.
- Service Worker에서 object URL을 사용하지 않는다.
- 로그아웃·계정 전환에서는 runtime 전체를 dispose한다. browser file runtime은
세션을 모른다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`).
`runtime.dispose()`(`:177-185`)가 이전 사용자가 고른 File 참조, preview lease,
진행 중 download(`download-delivery-adapter.ts:385-391`)를 한 번에 닫는다.
runtime을 route·feature보다 오래 사는 곳에서 만들었다면 server-state scope
reset participant(`src/adapters/query-cache/server-state-scope-runtime.ts:19`,
등록 예 `src/bootstrap/runtime-adapters.ts:410-416`)로 `dispose()`를 등록하고
다음 세대에서 새 runtime을 만든다. dispose한 runtime은 다시 쓸 수 없다.
- SVG, HTML, untrusted PDF 같은 active content를 same-origin object URL iframe에
직접 preview하지 않는다. 별도 격리 origin 또는 안전한 decode/re-encode 결과,
아니면 attachment-only 정책을 사용한다.
@@ -759,7 +774,7 @@ CLEANED -> journal 제거
- journal row와 budget reservation은 physical cleanup effect가
`CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash,
malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를
malformed response, worker cleanup 실패는 성공이 아니며 `PREPARING`/`FILES_READY`를
그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면
`QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다
(Q-6.5-9). journal rollback이 실패해도 같다.
@@ -15,15 +15,16 @@ The existing reference feature is the executable REST consumer.
It covers list/detail/create behavior, mapping, typed operation inputs,
application ports and an optimistic mutation path.
Current source size:
The feature-owned boundary and application source is these four files:
| Feature-owned area | LOC |
| --- | ---: |
| `application/reference-feature-api.ts` | 91 |
| `contracts/reference-mapper.ts` | 109 |
| `adapters/reference-http-gateway.ts` | 65 |
| `adapters/create-reference-feature-input.ts` | 41 |
| Total measured boundary/application source | 306 |
- `application/reference-feature-api.ts`
- `contracts/reference-mapper.ts`
- `adapters/reference-http-gateway.ts`
- `adapters/create-reference-feature-input.ts`
This document does not keep their line counts; a hand-typed count drifted
from the code (review 14-07). Measure them with
`wc -l src/features/reference-feature/{application/reference-feature-api.ts,contracts/reference-mapper.ts,adapters/reference-http-gateway.ts,adapters/create-reference-feature-input.ts}`.
The important boundary metric is not the raw total. It is what those files need
to know about the platform.
@@ -48,20 +49,19 @@ its business requirement.
## Scenario B — IndexedDB local draft
The original executable consumer probe remains at:
The executable consumer probe is:
`tests/contract/consumer-experience/indexeddb-local-draft.test.ts`
with its isolated fixture:
It runs and reads the one Local Draft implementation under
`src/features/local-draft-feature`; the isolated fixture copy it used to probe
had drifted from `src` and was removed (09-12).
`tests/contract/consumer-experience/fixtures/local-draft-feature.ts`
The architecture is now also exercised by a real vertical slice under:
`src/features/local-draft-feature`
It owns the Local Draft domain/application API and binds an
`IndexedDbRepositoryPort<LocalDraft, never>` in its feature adapter. The
The feature owns the Local Draft domain/application API and declares the slice
of the repository it calls (`LocalDraftRepository` in
`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts`). The
host hands in an `IndexedDbRepositoryPort<LocalDraft, never>` through the
`indexedDb` capability; the port satisfies that slice structurally. The
cross-capability composition contract lives at:
`tests/contract/reusable-capability/feature-adapter-composition.test.ts`
@@ -80,25 +80,24 @@ It runs against native browser IndexedDB. The test creates the platform
save/find/remove through the feature API. The Local Draft feature still does
not import the IndexedDB runtime or native browser API.
Measured probe result:
Measured on `src/features/local-draft-feature` (09-12):
| Metric | Result |
| --- | ---: |
| feature-owned fixture LOC | 97 |
| platform import statements | 1 |
| feature LOC (all `.ts` files) | 295 |
| import statements leaving the feature (`contracts/errors`, `contracts/result`, `application-api`, `feature-adapter-contribution`) | 7 |
| native IndexedDB API references | 0 |
| `src/adapters/storage/indexeddb/**` imports | 0 |
| runtime-internal IndexedDB types imported by feature | 0 |
| `src/application/ports/browser-file-storage/**` imports | 0 |
The feature depends only on the public application boundary:
`src/application/ports/browser-file-storage/index.ts`
and specifically `IndexedDbRepositoryPort<LocalDraft, never>`.
The feature does not import the storage runtime or its port, so removing the
browser file/storage runtime (`test:browser-file-storage-removal`) leaves it
compiling.
The contract test rejects feature source that reaches for
`globalThis.indexedDB`, `IDBFactory`, `IDBDatabase`, `IDBTransaction`,
`IDBObjectStore` or the concrete IndexedDB adapter directory.
`IDBObjectStore`, the concrete IndexedDB adapter directory or the
browser-file-storage port.
## What this does and does not prove
+23 -10
View File
@@ -41,8 +41,8 @@
| `NOT_SELECTED` | 제품 요구·owner·policy가 승인되지 않았다. |
| `PLATFORM_LIMITED` | browser/platform이 요구 의미를 cross-browser로 보장하지 못한다. |
현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 한 runtime당
`QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을
현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 server-state
generation마다 `QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을
기본값으로 사용한다. `src/bootstrap/runtime-adapters.ts`와
`src/bootstrap/runtime-application.tsx`가 이 client를 실제 provider tree에
조립한다.
@@ -79,13 +79,26 @@ native two-page browser spec은 BroadcastChannel primary와 localStorage fallbac
delivery/cleanup을 검증한다. 다만 production QueryClient/coordinator까지 연결한
account transition, bfcache/StrictMode lifecycle E2E는 없고, 현재 보존 artifact도
Chromium/Firefox만 통과해 WebKit을 포함한 promotion evidence는 충족하지 않는다.
localStorage fallback physical key는 아직 storage registry 밖의 상수이고 native
`StorageEvent.storageArea`도 facade에서 검증하지 않는다.
localStorage fallback physical key는 storage registry의
`CACHE_INVALIDATION_PULSE` 항목에서 온다(`src/contracts/storage-keys.ts:102`,
`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:36-37`).
host facade는 native `StorageEvent.storageArea`를 캡처한 `localStorage` 객체와
동일성으로 비교하고(`browser-cross-context-host.ts:286-296`), core는
`EXPECTED_LOCAL_STORAGE`로 표시된 pulse만 받는다
(`browser-cross-context-invalidation.ts:197-201`).
현재 epoch 구현은 `release.<releaseId>` 하나다. session/account epoch, opaque
account partition, scope 전환 시 새 QueryClient 생성과 durable namespace epoch는
아직 구현되지 않았다. 따라서 현재 cross-tab event는 같은 release의 등록 query
topic을 빠르게 stale 처리하는 용도에 한정된다.
현재 epoch는 release 하나다. `cacheEpoch`는 release ID의 64-bit FNV-1a digest를
`release.<16자리 hex>`로 쓴 값이다(`browser-cross-context-host.ts:45-51`, 조립
`src/bootstrap/runtime-adapters.ts:364-366`). 세션 identity가 바뀌면 scope
runtime이 다음 server-state generation을 열고
(`src/adapters/query-cache/server-state-scope-runtime.ts:148`), generation마다
새 `QueryClient`와 새 cross-context transport(새 `sourceId`·`sourceEpoch`)를
만든다(`src/bootstrap/server-state-generation-store.ts:50-57`,
`runtime-adapters.ts:359-372`). 이전 generation의 transport는 coordinator
dispose에서 닫힌다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:276-280`).
session/account epoch, opaque account partition과 durable namespace epoch는
아직 없다. wire event에 사용자·세션 scope가 없으므로 현재 cross-tab event는 같은
release의 등록 query topic을 빠르게 stale 처리하는 용도에 한정된다.
`QUERY_REGISTRY`의 모든 현재 entry와
`createTanStackCacheCoordinator()`는 `persistence: "disabled"`만 허용한다.
@@ -113,10 +126,10 @@ blocked/versionchange를 다루는 reference runtime이 있다. 이 설계는
| capability | primary current status | current implementation | target delta | delta implementation status |
| --- | --- | --- | --- | --- |
| memory QueryClient | `COMPOSED` | runtime별 생성, global stale/gc/retry default | session/account scope owner, generation fence, per-query policy | `DESIGNED_NOT_IMPLEMENTED` |
| memory QueryClient | `COMPOSED` | server-state generation별 생성(session identity 변경 시 FENCED 뒤 새 client), global stale/gc/retry default | per-query policy | `DESIGNED_NOT_IMPLEMENTED` |
| application query bridge | `COMPOSED` | AbortSignal, stale error, optimistic rollback/conflict surface | old-generation query/mutation callback 폐기 | `DESIGNED_NOT_IMPLEMENTED` |
| Web Storage | `COMPOSED` | 두 key, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` |
| cross-tab invalidation | `COMPOSED` | release epoch, versioned hint, duplicate/gap, BC→localStorage | composite scope epoch, registered pulse, storageArea, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` |
| cross-tab invalidation | `COMPOSED` | release epoch(FNV-1a digest), versioned hint, duplicate/gap, BC→localStorage, registry pulse key, storageArea 동일성 검사, generation별 transport | composite scope epoch, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` |
| generic IndexedDB | `AVAILABLE_NOT_COMPOSED` | reusable repository/maintenance runtime | product dataset schema/codec/query/policy composition | product selection `NOT_SELECTED` |
| query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | 없음, registry가 disabled 강제 | stable per-query record, bounded restore, namespace epoch/CAS | `DESIGNED_NOT_IMPLEMENTED` |
| product persistence | `NOT_SELECTED` | owner/query allowlist 없음 | measured need와 explicit composition | `NOT_SELECTED` |
@@ -50,7 +50,10 @@ architecture/security/type negative input으로 전환했다. 이는 7번 결정
- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
- TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
- ESLint와 `check:architecture`의 import 그래프(`scripts/check-architecture.ts`)가
TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을
해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05).
`.dependency-cruiser.json`은 이름만 남은 규칙 파일이고 그래프가 읽는다.
- registry scanner는 TS registry의 required field, uniqueness와 reference를
검증한다.
- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
@@ -18,7 +18,8 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
2. Zod presentation schema, application command mapper와 domain invariant는 서로
다른 소유물로 유지한다.
3. page와 feature는 `useAppForm`, `Form`, `FormField`, `ErrorSummary`,
`mapValidationFailureToFields`, `useDirtyNavigationGuard`만 사용한다.
`FormFailureStatus`, `mapValidationFailureToFields`, `useDirtyNavigationGuard`만
사용한다.
4. 422 details는 승인된 `path`와 `code`만 HTTP 경계에서 투영한다. backend
message와 알 수 없는 field는 field에 전달하지 않고 안전한 form-level
error로 이동한다.
@@ -27,6 +28,16 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
dirty 상태를 해제한다.
7. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`는
layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다.
8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다.
`useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`,
`action: "retry"`를 `retry-later`로, 나머지 입력 외 실패를 `unavailable`로 구분하고
그 실패를 `failure`로 낸다(F-10). 화면은
`FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은
입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`,
`form-components.tsx`).
9. (2026-09-25, 03-01) 결과 불명 저장은 사용자가 "변경되지 않음"을 판정하지 않는다.
`resendUnknown(mutation.resendUnknownEffect)`로 같은 intent·같은
`Idempotency-Key`를 다시 보낸다(`src/presentation/adapters/query/application-query.ts`).
## React Hook Form 도입 조건
@@ -38,9 +38,18 @@
## 경계와 검증
- 제품 코드는 `presentation/design-system/index`만 import한다.
- design-system 검사기는 direct icon/headless import, deep import, raw palette,
undefined token과 tooltip-only required information fixture를 거절한다.
- 제품 코드는 `presentation/design-system/index`만 import한다. 예외는 규칙에
이름으로 적는다. `presentation/components/ui/*.ts`는 아래 Rollback의 재수출
facade이고, `presentation/templates/page-templates.tsx`는 index가 내보내지
않는 `PaginationLandmarkContext`를 읽는다.
- deep import와 direct icon import는 `check:architecture` 그래프 규칙
`design-system-is-reached-through-its-index`, `icon-vendor-is-facade-only`
(`.dependency-cruiser.json`)가 거절한다. 경로 해석이 끝난 간선을 보므로
presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는
`tests/fixtures/architecture/dependency-graph/import-boundaries`다.
- design-system 검사기(`scripts/check-design-system.ts`)는 headless vendor
import, raw palette, undefined token과 tooltip-only required information
fixture를 거절한다.
- type negative fixture는 accessible name 없는 `IconButton`을 거절한다.
- component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를
검증한다.
@@ -66,9 +66,15 @@ route/form/failure 의미 값
## 검증
- `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
backend message JSX 렌더링과 raw HTML 사용을 검사한다.
- `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
- `check:i18n`은 catalog key와 placeholder parity, 화면 코드의 한국어 literal,
backend message JSX 렌더링과 raw HTML 사용을 검사한다. 검사 범위는 공통 UI
디렉터리, `src/presentation/pages`, 모든 `src/features/*/presentation`이다.
컴포넌트 갤러리 `src/presentation/examples`는 일부러 뺐다
(`scripts/check-i18n.ts`의 `commonDirectories`, `featurePresentationDirectories`).
- `check:i18n:fixture`는 같은 탐색 규칙을 `tests/fixtures/i18n/forbidden` 트리에
돌린다. fixture 파일 하나라도 거절되지 않으면 종료 코드 2로 실패한다.
- `tests/unit/i18n-contract.test.ts`는 `ERROR_REGISTRY`의 모든 `userMessageKey`가
ko-KR·en-US catalog에 있는지 확인한다.
- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
- unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
list/plural/select의 결정성을 검증한다.
@@ -43,13 +43,17 @@ vendor 결정 전에는 안전한 기본값이 아니다.
`createHttpObservationProjector`가 유일한 projection authority다. observation은
arbitrary context map이 아니며 projector는 `route_id`, `operation_id`,
`operation`, `outcome`, `error_kind`, `http_status_group`,
`attempt_count_bucket`, `duration_bucket`만 사용한다. raw attempt count,
`attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만
`correlation_id`(서버가 돌려준 `x-correlation-id`, 없으면 실행이 보낸 요청 ID)를
더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`). raw attempt count,
duration, status, URL, intent, key, input identity와 내부 `terminalReason`은
sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty`
key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만
전달한다.
5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한
번 남기고 `api.request.failed`는 발행하지 않는다.
번 남기고 `api.request.failed`는 발행하지 않는다. 자격증명이 없어 한 번도
보내지 않은 `UNAUTHENTICATED`(응답 status 없음)도 같다(03-07,
`src/bootstrap/runtime-adapters.ts` `isTerminalNonAbortFailure`).
5-3. `routeId`는 installed operation-executor 경계의 필수 입력이다. feature
gateway가 소유한 low-cardinality route identity를 URL에서 재구성하지 않는다.
6. `app.boot.failed`, `ui.render.failed`, `release.mismatch.detected`,
@@ -72,6 +76,11 @@ vendor 결정 전에는 안전한 기본값이 아니다.
아니거나 1 미만이거나 문서화된 ceiling(각각 `MAX_TELEMETRY_QUEUE`,
`MAX_DIAGNOSTIC_ENTRIES` = 10,000)을 넘으면 `TypeError`로 거절한다. NaN/Infinity가
조용히 eviction을 비활성화하는 경로를 남기지 않는다.
7-5. (2026-09-25) 두 telemetry port는 collector 하나로 보낸다
(`src/adapters/telemetry/telemetry-collector.ts`). collector는 본문을 60KiB 아래로
나누고, 진행 중인 keepalive 본문 합이 64KiB를 넘으면 그 부분은 keepalive 없이
보낸다(03-05). 조합 루트가 release manifest의 `buildId`·`releaseId`를 넘기면 모든
이벤트에 `build_id`·`release_id`를 붙인다(13-11, `src/bootstrap/runtime-adapters.ts`).
8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition,
storage/cache fallback과 React error surface를 바꾸지 않는다.
9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로
@@ -255,15 +255,20 @@ reconnect는 capped full-jitter exponential backoff를 사용한다. base/max de
max attempts와 max elapsed는 immutable registry/implementation ceiling으로
제한한다.
- stable-open window 또는 valid heartbeat/event 뒤에만 attempt reset
- valid heartbeat/event와 stable-open window를 둘 다 충족한 뒤에만 attempt와
elapsed budget reset. session의 모든 종료 경로(server close, offline,
`waitClosed` throw)에서 확인한다
- valid server hint는 local delay보다 이른 retry를 금지하는 not-before bound
- server hint가 implementation max/remaining elapsed budget을 넘으면 낮춰
clamp하지 않고 degraded/stale로 종료
- offline에서는 timer retry를 멈춤
- offline에서는 timer retry를 멈춤. offline 대기 시간은 elapsed budget에 넣지
않고 online 복귀 시 elapsed budget을 다시 시작한다. attempt 상한은 유지한다
- auth expiry는 session owner single-flight recovery 한 번
- forbidden/protocol/schema failure는 terminal
- 외부 rate/provider failure는 exact bounded server not-before hint가 있을 때만
retry하고, hint가 없으면 terminal
- retry 여부는 transport가 보고한 `retryable`이 정한다. retryable 실패는 hint가
없어도 bounded retry한다. hint가 꼭 필요한 실패(SSE `429`/`503`, WebSocket
`OVERLOADED`)는 hint가 없으면 transport가 terminal로 보고한다. SSE
`502`/`504`와 WebSocket `RESTART`·`NETWORK_LOST`는 hint 없이 bounded retry
- retry budget 소진 뒤 declared Polling fallback 또는 stale UI
- reconnect는 realtime coordinator, auth는 session owner, Poll cadence는 poll
coordinator가 소유하고 Poll-bound HTTP/Query retry는 비활성
@@ -456,7 +461,7 @@ push hint와 worker deadline을 제한한다. 제품 config는 더 작게만 설
2026-07-28 reference-runtime amendment로, RT-01~RT-04 source 전체를
tree-shaking 없이 합성하는 optional-recipe gzip 예산을 40,000 bytes로
고정한다. 이는 production bundle 허용량이 아니며 미선택 production asset의
고정한다(2026-09-27 성숙도 리뷰 반영으로 40,900 bytes로 올림. 근거는 `config/recipes/frontend-capability-recipes.json` 변경 커밋). 이는 production bundle 허용량이 아니며 미선택 production asset의
realtime module 허용량은 계속 0이다. SSE replay-open과 WebSocket
`SUBSCRIBED`가 exact recovery checkpoint를 증명하고 common barrier가 확인될
때까지 event admission을 막는 readiness gate는 attempt당 최대 30초다.
@@ -138,6 +138,17 @@ browser-capability test composes the feature over the real
`createIndexedDbRuntime` and native IndexedDB, proving that this seam is not
limited to an in-memory contract fixture.
The bootstrap does not build `indexedDb`: IndexedDB is an opt-in reference
runtime (`productionComposition: false` in
`config/recipes/frontend-capability-recipes.json`). The composition example is
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`
(`createLocalDraftIndexedDbCapability`, exercised by
`tests/recipes/indexeddb-feature-capability.test.ts`). A product that installs a
feature with `needs: ["indexedDb"]` copies it and adds `indexedDb` to the feature
capabilities in `src/bootstrap/runtime-adapters.ts`. Until it does, that object
fails the app typecheck, and `composeFeatureAdapterInputs()` rejects the
composition with `feature <id> needs indexedDb, which the host did not provide`.
## Presentation consumer surface
`ApplicationProvider` remains the composition root for presentation, but new
@@ -65,7 +65,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 |
| --- | --- | --- | --- |
| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
| 계층 의존 방향 | 준비됨 | dependency-cruiser + TS-aware static graph, unresolved/parse/layer/cycle negative fixture | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
| 계층 의존 방향 | 준비됨 | TS-aware static graph(`scripts/check-architecture.ts`, 규칙 `.dependency-cruiser.json`), unresolved/parse/layer/cycle negative fixture. dependency-cruiser 자체는 TS 7을 해석하지 못해 실행하지 않음(12-05) | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
| application facade | 준비됨 | module-augmented feature input registry, typed output catalog, provider, production composition test | feature별 input contribution과 제거 gate 유지 |
| REST HTTP client | 준비됨 + hardening delta | reference vertical의 path/search/body projection, attempt timeout/retry, abort/cleanup은 `COMPOSED` | auth fail-close/final invariant, total deadline, bounded decoder, status/media/CSRF/conditional/pagination은 `DESIGNED_NOT_IMPLEMENTED` |
| Browser RPC 공통 계약/runtime | 준비됨/미조립 | V3 operation/profile registry, typed application port, bounded unary/server-stream lifecycle와 unavailable adapter는 `AVAILABLE_NOT_COMPOSED` | actual descriptor/generated client, protocol transport, proxy/provider/browser conformance |
+40 -13
View File
@@ -25,6 +25,15 @@ The following edges are forbidden:
- an adapter to presentation, bootstrap internals, or another concrete adapter
- feature domain/application to its presentation or outbound adapter, and
feature presentation to its outbound adapter
- a module presentation may import to a concrete adapter: files outside a
feature's layer folders (`src/features/*.ts`, `src/features/<id>/*.ts`),
`src/contexts` and `src/apps` (`feature-and-app-roots-do-not-reach-adapters`).
The graph checks one edge at a time, so a re-export there would carry an
adapter into presentation with every other rule passing. The one exception is
the type-only `src/features/feature-adapter-contribution.ts`
- presentation to `src/apps` or `src/contexts`, except
`src/presentation/routes/app-router.tsx`, which mounts the app's route tree
(`presentation-does-not-import-apps-or-contexts`)
## The adapter kernel
@@ -35,14 +44,25 @@ purpose and is the only adapter code an adapter may reach across a group for:
the bounded-capacity guard
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
failure constructors
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
invalidation transport and its types. Any adapter may import it; today
`query-cache` does
Each rule above is enforced by `check:architecture`, including the kernel
carve-out, so this table and the executable rules cannot drift apart. Two edges
are still open and are named explicitly in `.dependency-cruiser.json` rather
than left silent: the generic presentation modules that read the installed
registries today, and the two collaborator types `query-cache` reads from
`cross-context-invalidation`. Both lists are frozen — a new edge of either kind
fails the gate.
carve-out, so this table and the executable rules cannot drift apart.
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
exempted path in `pathNot`, and the reason, owner and revisit condition in
`comment` (review 12-07). Besides the kernel, the exceptions are:
- the generic presentation modules that read the installed registries today
(`generic-presentation-does-not-compose-the-product`). The list names exact
files, so a new module that reads a registry fails the gate
- `src/presentation/adapters/query`, the TanStack Query binding
(`presentation-does-not-know-adapters`)
- `src/presentation/routes/app-router.tsx` importing the app
(`presentation-does-not-import-apps-or-contexts`)
- the design-system facades (`design-system-is-reached-through-its-index`)
## 어댑터 그룹의 공개 경계
@@ -63,10 +83,15 @@ fails the gate.
위한 것이다.
`storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지
않는다. 두 런타임이 각자 독립적으로 제거 가능하고
(`test:browser-file-storage-removal`), 그래서 각 서브배럴이 곧 경계다.
규칙의 도착점 정규식이 1단계 중첩 `index.ts`를 배럴로 인정하는 이유가
이것이다.
않는다. 두 폴더는 browser-file-storage 번들의 런타임이다. 제거 드릴
(`test:browser-file-storage-removal`)은 그 번들 전체(`browser-file-storage`,
`browser-files`, `browser-transfer`, `cache-storage`, `storage/indexeddb`,
`storage/opfs`)를 함께 지운다. 최상위 `storage` 배럴(Web Storage)은 그 뒤에도
남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개
경계다.
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
@@ -83,8 +108,9 @@ application APIs augment the generic typed input registry. Concrete output
ports are composed in bootstrap and stay hidden behind the application facade.
Project-selected capabilities still implement the same output boundaries.
`check:architecture` keeps dependency-cruiser's report and adds the
authoritative TypeScript-aware graph below it:
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
parse TypeScript 7 and checked zero modules (review 12-05):
```json
{
@@ -103,7 +129,8 @@ authoritative TypeScript-aware graph below it:
```
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
and JSDoc import references. It applies the path rules from
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
source imports, and fails closed on JavaScript-family source/specifiers,
unsupported rule shapes, unresolved imports, parse failures, error-severity
@@ -106,6 +106,30 @@ type은 facade 밖으로 노출하지 않는다.
SSOT다. 문서와 catalog가 다르면 gate가 검사하는 catalog를 우선 고치고 이 표도
같이 갱신한다.
Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6과 2의 시작 실패
이벤트만 갖고 있다.
1. `src/features/installed-runtime-capabilities.ts`의 `SERVICE_WORKER`를
`ACTIVE`로 바꾼다. `scripts/build-frontend.ts`가 worker 빌드를 추가로 돈다.
2. 관측: `createRuntimeComposition`이 텔레메트리 포트를 optional host에 넘긴다
(`src/bootstrap/create-runtime-composition.ts`). 시작 결과가 `FAILED`나
`INCOMPATIBLE`이면 `service-worker.start.failed`가 1건 남는다
(`src/bootstrap/optional-runtime-host.ts`). 실제 composition에서 첫 설치가
실패하면 이벤트가 1건 나가는 것은
`tests/component/runtime-composition-service-worker-telemetry.test.ts`가
확인한다. 템플릿이 연결하지 않은 것은 셋이다. 업데이트 설치 실패
(`watchForUpdates`, `src/adapters/service-worker/service-worker-page-controller.ts`)는
이벤트를 남기지 않는다. page controller의 `observe`는 composition이 넘기지
않는다. `OptionalRuntimeHost.health()`는 `src` 안에서 읽는 코드가 없다.
필요하면 다운스트림이 `createRuntimeComposition`에서 연결한다.
3. blockers: 저장하지 않은 편집이 있는 탭이 활성화를 거절하게
`createOptionalRuntimeHost`에 `blockers`를 넘긴다. 템플릿은 넘기지 않는다.
4. 활성화 UI: `ServiceWorkerRuntimeHost.onUpdateWaiting`을 구독하고, 사용자가
동의하면 `requestActivation()`을 부른다(`src/contracts/service-worker.ts`).
5. reload 처리: `onReloadRequired`를 구독해 reload를 안내한다.
6. 끄기·롤백·제거: `docs/operations/release-cache-rollback.md`의 Service Worker
절차. `service-worker.js`는 `Cache-Control: no-cache`로 서빙한다.
Web Push target은 현재 13번째 설치 recipe가 아니다. 기존 `realtime`,
`service-worker-pwa`, `browser-permission`의 인접 경계를 조합해야 하는 별도
`NOT_SELECTED` capability다. 실제 선택 전 VD-10 amendment와 machine-readable
@@ -130,6 +154,15 @@ Web Push를 함께 설치하지 않는다.
integration test를 작성한다.
9. runtime config schema, dependency inventory/approval, SBOM, bundle budget,
browser support와 runbook을 갱신한다.
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
아래 기능을 막는다(리뷰 13-08).
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
`img-src`에 `blob:`을 더한다.
- 이미지 CDN: `img-src`에 CDN origin을 더한다.
바꾼 CSP 아래에서 `tests/e2e/production-csp.spec.ts`가 그 기능의 화면을 열도록
smoke를 늘린다.
10. 실제 provider integration과 negative behavior가 통과한 뒤에만 catalog 상태를
별도 project catalog에서 `INSTALLED`로 바꾼다.
+3 -2
View File
@@ -53,8 +53,9 @@ and exact input type.
Route contracts/codecs, the route-input provider, and lazy runtime modules are
separate modules so feature pages do not import the router that loads them.
Expected application failures use the shared `Result`/`AppFailure` contract.
The architecture gate analyzes TS/TSX imports independently of
dependency-cruiser, rejects local JavaScript-family specifiers and executable
The architecture gate analyzes TS/TSX imports with its own graph (the rules
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
JavaScript-family files, and fails on unresolved imports, parse failures,
forbidden layer edges, or cycles. The remaining project-owned work includes
selecting and verifying real hosting, identity, telemetry, vulnerability and
@@ -164,8 +164,24 @@ URL을 발급하면 안 된다.
- capability를 async 대기하는 동안 caller 입력과 dependency method를 snapshot한다.
- 사용 전에 만료뿐 아니라 최소 잔여 lifetime도 검사한다.
- 기기 시계가 서버보다 `maxClockSkewMs`(기본 60초)까지 늦어도 수명 상한 검사는
거절하지 않는다. 서버는 session 수명을 `maxSessionLifetimeMs` 이하, capability
수명을 `maxCapabilityTtlMs` 이하로 주면 된다(`upload-response-validation.ts`
`validateSession`, `presigned-capability-http-provider.ts` `maxClockSkewMs`).
하한은 느슨하게 하지 않는다. 기기 시계가 빠르면 수명이 그만큼 짧아 보이므로
서버 capability 수명은 `minimumRemainingLifetimeMs + maxClockSkewMs`와
`capabilityRefreshSkewMs + maxClockSkewMs`보다 길어야 한다. 기기 시계가 이보다
더 빠르면 그 기기에서는 capability가 만료로 보인다.
- 만료/403은 임의 retry가 아니라 control plane의 새 capability 발급으로 복구한다.
- ambiguous network failure 뒤 upload part를 새 bytes로 덮어쓰지 않는다.
- 실행기의 `put()`·`open()`은 받은 capability를 어떤 경로로 끝나든 vault에서
뺀다. 성공하면 `consume()`이 빼고, 그 밖의 모든 경로(잘못된 입력, 이미 중단된
signal, 바이트 길이 불일치, 바인딩 거절, 만료, replay claim 실패, digest 중단이나
불일치, 전송 실패)는 공개 메서드의 `finally`가 `revoke()`로 뺀다
(`presigned-transfer-executor.ts`의 `release`). 실행기에 닿기 전에
버려진 capability(runtime 응답 검증 실패, part 실행기 사전 검사 실패, fail-fast로
`put()` 전에 멈춘 형제 worker)는 만료까지 `maxActiveCapabilities` 자리를
차지하고, 다음 `register()`가 만료 항목을 정리한다.
- client-side single-use map은 UX 최적화일 뿐이다. cross-tab/replay authority는
server 또는 composition-owned atomic consumer다.
- signed response의 URL, query, raw header와 exception text를 관측성에 남기지 않는다.
@@ -198,6 +214,15 @@ capability는 앞 절의 별도 fixed BFF endpoint를 redirect 금지로 사용
response envelope 및 request/response의 `UPLOAD_PART` binding protocol이
`PRESIGNED_MULTIPART_V1`인지 대조한다.
part 수 상한과 byte cap은 서로 맞아야 한다. complete 요청과 status 응답에는 part
receipt가 모두 들어간다. 조립할 때 runtime 정책의 `maxPartCount`를 전송의
`maxPartCount`로 넘기면, 전송 factory가 최악의 receipt(모든 필드가 문법 최대,
token 512자, part당 691바이트)로 계산해 들어가지 않는 조합을 `TypeError`로
거절한다(`fetch-json-transport.ts` `MAX_RECEIPT_JSON_BYTES`). 기본값(1,024 part,
요청 1MiB, 응답 2MiB)은 들어간다. 요청 1MiB로는 약 1,500 part, 최대치 4MiB로는
약 6,000 part까지다. 넘기지 않으면 검사하지 않고, 넘치는 upload는 모든 part를
보낸 뒤 complete에서 `LIMIT_EXCEEDED`로 끝난다.
Session은 적어도 opaque ID, protocol version, exact total bytes, media type,
part size, part count, concurrency ceiling, checksum algorithm과 expiry를 묶는다.
part number는 1부터 연속적이어야 하고 마지막 part를 제외한 part length는
@@ -261,6 +286,16 @@ session state 검사를 대체하지 않는다.
- 429/모든 `5xx`/network retry는 composition의 bounded attempt, bounded
`Retry-After`와 abortable backoff 안에서만 수행한다.
- 만료/authorization failure는 최대 정책 범위 안에서 capability를 재발급한다.
object store PUT의 401/403/409/410과 실행기의 만료 판정(`REISSUE_CAPABILITY`)은
`maxRetries` 안에서 다음 시도가 새 capability로 다시 보낸다. BFF 발급 단계의
401/403은 재시도하지 않는다(`resumable-upload-runtime.ts` `uploadPartWithRetry`).
- part PUT 한 번의 제한 시간은 `providerAttemptTimeoutMs + part 바이트 /
minTransferBytesPerSecond`다. 기본값은 30초 + 5MiB ÷ 64KiB/s = 110초다
(`runtime-policy.ts`). 즉 지원하는 최저 업링크는 기본 약 0.5Mbit/s이고, 이보다
느리면 정책의 `minTransferBytesPerSecond`를 낮춘다. fetch는 업로드 진행을 알려
주지 않으므로 PUT에는 idle 제한이 없고 이 크기 비례 제한이 멈춘 연결을 끊는다.
presigned 실행기도 `timeoutMs`에 같은 식의 바이트 몫을 더한다
(`presigned-transfer-executor.ts`, `http-common.ts` `transferAllowanceMs`).
- upload response의 opaque receipt/ETag를 whole-file digest로 해석하지 않는다.
- PUT capability는 성공 status, receipt header와
`expectedResponseByteLength`를 묶는다. runtime은 exact `Content-Length`를
@@ -299,6 +334,12 @@ resume 시 checkpoint만 신뢰하지 않는다.
전환한다.
5. 새 part만 업로드한 뒤 전체 ordered set을 다시 reconcile한다.
재개 때 서버 session은 저장된 checkpoint 값(session ID, 동시성, 만료 시각)과
일치하는지만 본다. 정책 상한(`maxConcurrency`, `maxSessionLifetimeMs`)은 새
session을 만들 때만 검사한다. 그래서 정책을 낮춘 빌드도 이전 빌드가 시작한
업로드를 이어 간다. worker 수는 `min(현재 정책, session 동시성)`이다
(`upload-response-validation.ts` `validateSession`의 `stage`).
`GET_STATUS`가 HTTP `404` 또는 `410`을 반환하거나 decoded status가
`NOT_FOUND`/`EXPIRED`이면 해당 session은 terminal이다. runtime은 CAS revision을
확인해 checkpoint를 제거하고 새 session으로 restart하거나
@@ -324,6 +365,42 @@ signed URL이나 receipt를 포함하거나 저장하지 않으며 server state
reconcile에서 server 상태를 확인한다. backend는 만료된 orphan multipart를
정리하는 TTL job을 가져야 한다.
complete 결과를 모를 때 클라이언트는 다음처럼 동작한다.
- complete 응답을 잃으면(시간 초과, 연결 끊김) `upload()`는 같은 COMPLETE key로
`maxRetries`번 다시 보낸 뒤 `UNAVAILABLE/UPLOAD_COMPLETE, retryable:true`를
돌려준다. 모든 part가 수락된 checkpoint는 남는다
(`resumable-upload-runtime.ts` `completeUpload`).
- 같은 파일로 `upload()`를 다시 부르면 `GET_STATUS`가 `QUARANTINED`일 때
resourceId와 `replayed:true`를 돌려준다. `ACTIVE`이면 같은 key로 complete를
다시 보낸다.
- `abort()`에 서버가 `ALREADY_COMPLETED`로 답하면 checkpoint를 지우기 전에
`GET_STATUS`로 resourceId를 읽어 `{ state: "ALREADY_COMPLETED", resourceId }`로
돌려준다. status 조회가 일시적으로 실패하면 `ABORT_PENDING` checkpoint를 남기고
실패를 돌려준다. `abort()`를 다시 부르면 된다. 서버가 session을 모르면(404/410)
resourceId 없이 닫는다(`resumable-upload-runtime.ts` `readCompletedResourceId`).
- 서버가 complete를 반영한 뒤 로컬 checkpoint 삭제가 실패해도(IndexedDB 오류,
complete 직후 caller abort) `upload()`는 성공을 돌려준다. 남은 행은 다음
`upload()`나 `abort()`가 같은 자원으로 정리한다.
서버 계약 — complete 진행 중(`ResumableUploadControlPlane.complete` 주석):
- 같은 COMPLETE key의 complete가 아직 끝나지 않았으면 서버는 `429`와
`Retry-After`로 답한다. 값은 전송과 runtime의 `maxRetryAfterMs`(기본 30초)
이하여야 한다. 클라이언트는 이것을 `UNAVAILABLE, retryable:true`로 읽고 그만큼
기다린 뒤 같은 key로 다시 보낸다(`fetch-json-transport.ts` `statusFailure`).
`Retry-After`가 없거나 상한을 넘으면 재시도하지 않는다. `503`도 재시도되지만
`Retry-After`는 읽지 않는다.
- `409`는 쓰지 않는다. 클라이언트는 `409`를 `CONFLICT, retryable:false`로 읽고
멈춘다.
- 그동안 `GET_STATUS`는 `ACTIVE`(모든 part 수락)를 유지하고, 자원이 확정된 뒤에만
`QUARANTINED`와 resourceId를 준다. 클라이언트 status 계약(`UploadSessionStatus`)에는
"완료 중" 값이 없고, 모르는 state는 `INTEGRITY_FAILED`로 거절한다.
- 서버 문서의 `OPERATION_IN_PROGRESS`(`server-file-capability-infrastructure.md`
8.2, 11.1)는 이 wire 표현으로 내보낸다.
- 재시도가 모두 끝나도 진행 중이면 `upload()`는 `UNAVAILABLE/RESUME`을 돌려주고
checkpoint가 남는다. 다음 `upload()`나 `abort()`가 위 순서로 조정한다.
application-facing upload 성공값은 `state`, opaque `resourceId`, `byteLength`,
`replayed`만 반환한다. control-plane 검증에 사용한 `sessionId`,
`requestBindingSha256`와 file fingerprint는 public outcome에 노출하지 않는다.
@@ -400,6 +477,11 @@ Streaming download는 server resource를 전체 `Blob`/`ArrayBuffer`로 material
- abort/consumer early return에서 reader를 cancel하고 lock/capability lease를
해제한다.
- byte source는 기본 one-shot이며 두 번째 stream 소비를 거절한다.
- 전체 제한과 idle 제한을 따로 둔다. 전체 제한은 `timeoutMs + byteLength /
minTransferBytesPerSecond`(기본 64KiB/s)라 느리지만 진행하는 큰 download는
끝까지 받는다. chunk 하나를 기다리는 시간은 `idleTimeoutMs`(기본 `timeoutMs`)가
상한이고, 진행이 멈추면 여기서 `UNAVAILABLE/REISSUE_CAPABILITY`로 끝난다
(`presigned-transfer-executor.ts` `readChunk`, `http-common.ts` `readWithSignal`).
File System Access save picker가 있으면 user activation 안에서 destination을 먼저
열고 stream을 쓴다. close와 integrity verification이 끝난 경우만 `SAVED`다.
@@ -565,6 +647,14 @@ probe는 decode 크기가 primary 후보의 pixel 크기와 정확히 같아야
- private rendition은 짧은 expiry와 필수 `no-store`를 쓴다.
- CDN cache hit 여부는 authorization이나 asset safety proof가 아니다.
`PRIMARY_REQUIRED` preset(private asset은 항상)의 `resolve()`는 primary candidate를
preset의 encoded·decoded 예산까지 내려받아 decode한다. private 응답은 `no-store`라
`<img>`가 같은 URL을 한 번 더 받는다. 그래서 runtime은 같은 asset reference와
preset에 대해 통과한 probe를 capability가 유효한 동안 재사용하고, 동시에 도는
probe를 `maxConcurrentProbes`(기본 4, 최대 32)개로 제한한다. 넘는 호출은 자리를
기다리며, 기다리다 abort하면 자리를 차지하지 않는다(`image-cdn-runtime.ts`
`passedProbes`, `acquireProbeSlot`).
image probe의 단일 bounded deadline은 response header fetch, streamed body read와
native decode 전체를 포함한다. timeout/cancel/error 시 reader를 cancel하고,
abort 뒤 늦게 resolve한 response body도 cancel하며 늦게 생성된 `ImageBitmap`도
@@ -630,12 +720,31 @@ analytics는 제품 presentation이 소유한다.
| image capability verification concurrency ceiling | `LIMIT_EXCEEDED` | 진행 작업 종료 대기 또는 runtime 부하 조사 |
| closed Image CDN runtime 사용 | `UNAVAILABLE` | 새 runtime composition |
| network/429/모든 5xx | `UNAVAILABLE` | bounded retry/backoff |
| complete 응답 유실·진행 중 | `UNAVAILABLE`(`UPLOAD_COMPLETE`, retryable) | 같은 파일로 `upload()` 재호출, 또는 `abort()`가 resourceId와 함께 `ALREADY_COMPLETED` 반환(4.3) |
관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과
`ResumableUploadPort.upload()` 실패의 `recovery`는 호출자가 할 행동 하나를
가리킨다(`resumable-upload.ts` port 주석, `resumable-upload-runtime.ts`
`toUploadAction`). 이 다섯 값 밖의 값은 `upload()`에서 나오지 않는다.
| recovery | 호출자 행동 |
| --- | --- |
| `RESUME` | 같은 파일·key로 `upload()`를 다시 부른다. `retryable:true`면 자동 재시도해도 된다. capability 재발급이 필요한 실패도 여기로 온다 |
| `RECONCILE` | `upload()`를 다시 부른다. 서버 상태를 먼저 읽는다(예: 다른 문맥이 checkpoint를 먼저 씀) |
| `RESTART` | `abort()` 뒤 `upload()`로 새 session을 연다. abort가 남아 있음(operation `UPLOAD_ABORT`), 읽을 수 없는 checkpoint 행, 서버 part가 파일과 다름 |
| `RESELECT` | 파일을 다시 고르거나, 다른 파일이면 새 key를 쓴다 |
| `NONE` | 이 요청으로 할 행동이 없다. 잘못된 입력, 상한·정책·권한 거절, 호출자 자신의 abort, 다시 불러도 같은 답이 오는 서버 응답(정책보다 긴 session 등) |
관측성에는 operation, safe outcome, byte/candidate bucket, retry bucket과
failure code만 기록한다. capability ID, URL, query, asset/resource/session ID,
file name, digest, raw ETag, receipt와 backend message는 log/diagnostics/telemetry에
기록하지 않는다. 앞 절의 strict checkpoint allowlist만 durable 예외다.
같은 observer를 두 계층에 넘겨도 한 사건은 한 번만 센다. resumable runtime은
part마다 최종 결과 하나를 `UPLOAD_PART`로 남기고, 그 part에 쓴 시도 수를
`countBucket`에 넣는다(retry bucket). presigned 실행기의 PUT 시도 하나하나는
`PRESIGNED_TRANSFER`로 따로 남는다(`resumable-upload-runtime.ts`
`transferMissingParts`, `presigned-transfer-executor.ts` `uploadParts.put`).
## 8. 조합 조건
현재 `src/adapters/browser-transfer/index.ts`는 개별 presigned, upload와 Image CDN
@@ -765,21 +765,38 @@ effectiveDelay = max(localDelay, validServerNotBefore)
budget을 넘으면 낮춰 clamp하지 않고 reconnect/poll을 종료해
`DEGRADED`/`STALE`로 전환한다.
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. valid
heartbeat/event를 받았고 stable-open window도 지났을 때만 reset한다(둘 중
하나만으로는 reset하지 않는다).
heartbeat/event를 받았고 stable-open window도 지났을 때만 attempt 수와
elapsed budget을 reset한다(둘 중 하나만으로는 reset하지 않는다,
`reconnect-policy.ts:131-149`). 이 확인은 server close뿐 아니라 offline과
`waitClosed` throw를 포함한 session의 모든 종료 경로에서 한다
(`reconnect-coordinator.ts:886-900`). valid heartbeat는 SSE `onComment`와
WebSocket `HEARTBEAT_ACK` 관측이다. 조합 코드가 이를
`markValidHeartbeatOrEvent`로 넘긴다.
- stream reconnect는 realtime recovery coordinator, credential recovery는
session owner, Poll attempt 사이 cadence는 poll coordinator가 각각 소유한다.
Poll-bound REST transport retry와 Query retry는 끈다. 같은 logical recovery의
effect writer나 timer가 둘 이상 활성화되지 않게 generation으로 배타화한다.
- `offline` 상태에서는 timer로 재시도하지 않고 online hint를 기다린다.
`navigator.onLine`은 실제 backend reachability authority가 아니다.
offline 대기 시간은 elapsed budget에 넣지 않는다. online으로 돌아오면
elapsed budget을 다시 시작하고 attempt 상한은 유지한다
(`reconnect-coordinator.ts:550-559`).
- auth expiry는 session owner의 single-flight recovery를 한 번 요청한다.
실패하면 `AUTH_REQUIRED`로 멈춘다.
- protocol/schema/forbidden/policy failure는 retry하지 않는다.
- 외부 close/result의 rate limit/provider unavailable은 유효한 bounded server
not-before hint가 있을 때만 재시도한다. hint가 없거나 ceiling 밖이면
terminal이다. adapter 내부 provider throw처럼 server 응답이 아닌 실패만
남은 retry budget 안에서 local full-jitter를 사용할 수 있다.
- 재시도 여부는 transport가 보고한 `retryable`이 정한다. reconnect
coordinator는 retryable인 `CONNECT_TIMEOUT`·`IDLE_TIMEOUT`·`OFFLINE`·
`PROVIDER_UNAVAILABLE`·`RATE_LIMITED`를 server hint가 없어도 남은 budget
안에서 local full-jitter로 재시도한다(`reconnect-coordinator.ts:1582-1593`).
server hint가 꼭 필요한 실패는 transport가 hint 없을 때 `retryable: false`로
보고해 terminal이 된다. SSE `429`/`503`에 유효한 `Retry-After`가 없을 때
(`sse/fetch-sse-connection.ts:592-616`)와 WebSocket `OVERLOADED`
(`websocket/websocket-connection.ts:1818-1823`)가 여기 해당한다. SSE
`502`/`504`와 WebSocket `RESTART`·`NETWORK_LOST`는 hint 없이 bounded
재시도한다. hint가 있으면 not-before bound이고, ceiling을 넘으면 terminal이다.
SSE `Retry-After`는 `onRetryHint`로만 나오므로 `readSseForReconnect`로 읽어야
reconnect coordinator의 `serverNotBeforeMs`에 닿는다
(`sse/fetch-sse-connection.ts:488-506`).
- budget을 소진하면 infinite reconnect가 아니라 `DEGRADED`와 명시된 fallback
또는 stale UI로 전환한다.
@@ -803,6 +820,17 @@ attempt당 상한은 30초다.
### 5.4 Visibility, page lifecycle와 network
5.4~5.6의 "기본 동작"은 조합 코드가 해야 하는 일이다. reference runtime은 이
동작을 강제하지 않는다.
- reconnect coordinator가 따르는 환경 신호는 online 하나다
(`reconnect-coordinator.ts:106-113`). SSE와 WebSocket 연결에는 visibility 입력이
없다. visibility를 직접 듣는 것은 polling뿐이다
(`polling/bounded-poll-coordinator.ts:202-205`).
- registry의 `hiddenPolicy`, `killSwitchId`, `fallback`은 검증만 하고 읽지 않는다
(`src/contracts/realtime-streams.ts:74-79`). hidden·`pagehide`·logout 때 닫기,
kill switch, fallback 전환은 조합 코드가 한다.
| signal | 기본 동작 |
| --- | --- |
| `visibilitychange -> hidden` | 새 Polling 중지, configured grace 뒤 live connection pause/close |
@@ -846,10 +874,17 @@ session authority announces local transition
late socket event, poll response, auth recovery, snapshot, notification handoff와
Service Worker message는 old generation/scope면 적용하지 않는다.
reference runtime에서 위 흐름의 "close SSE/WebSocket"은 조합 코드가 reconnect
coordinator의 `close()`를 불러야 일어난다. `isCurrent`는 attempt·sleep·waitClosed
경계에서만 확인하므로, 열린 채 조용한 session은 다음 event나 server close까지
남는다(`reconnect-coordinator.ts:175-181`). 그동안 도착한 event는 stream
coordinator의 scope fence가 막는다.
long-lived connection은 connect-time authorization만 신뢰하지 않는다. backend는
active subscription의 permission/session revoke를 control event 또는 close로
전파하고, registry-owned `maxConnectionAge`/reauth deadline 안에 current
credential로 재연결하게 한다. SSE처럼 별도 subscribe command가 없는 transport는
credential로 재연결하게 한다. `maxConnectionAge`는 아직 registry 필드가 아니다.
채택하는 제품이 조합 코드에서 정한다. SSE처럼 별도 subscribe command가 없는 transport는
권한 변경 시 server가 stream을 종료해야 한다. server hint는 client hard
connection-age ceiling을 늘릴 수 없다.
@@ -875,7 +910,7 @@ best-effort hint다.
- tab 하나당 selected primary transport physical connection 1개
- WebSocket logical subscription multiplexing 또는 SSE single-feed local dispatch
- hidden tab close/pause 정책
- hidden tab close/pause 정책(조합 코드가 적용한다. 5.4 참조)
- visible 복귀 시 authoritative snapshot
SharedWorker나 leader election으로 origin 전체 connection을 하나로 만드는 기능은
@@ -1006,8 +1041,8 @@ Last-Event-ID = approved current cursor, CURSOR profile only
| `401` | session recovery 한 번, 실패 시 `AUTH_REQUIRED` |
| `403` | `FORBIDDEN`, retry 금지 |
| `409`/`410` with exact reset contract | cursor expired, snapshot resync |
| `429` | bounded `Retry-After`, retry budget 소비 |
| `502`/`503`/`504` | bounded provider backoff |
| `429`/`503` | 유효한 `Retry-After`가 있으면 그 시각 이후 bounded 재시도, retry budget 소비. 없거나 상한 밖이면 terminal |
| `502`/`504` | hint 없이 bounded provider backoff |
| redirect, wrong type, malformed stream | protocol/policy failure, fail-closed |
generic HTTP client의 전체-body decoder와 retry를 우회하되 credential, diagnostics,
@@ -1150,7 +1185,7 @@ closed category로 mapping한다.
| --- | --- | --- |
| `NORMAL` | intentional close/drain | 아니오 |
| `RESTART` | server deploy/restart | bounded |
| `OVERLOADED` | server capacity/rate | exact server hint가 있을 때만 bounded; 없으면 terminal |
| `OVERLOADED` | server capacity/rate | exact server hint가 있을 때만 bounded; 없으면 terminal. 현재 closed protocol에는 hint 필드가 없어 항상 terminal이다 |
| `AUTH_REQUIRED` | session expired | single-flight recovery 뒤 한 번 |
| `FORBIDDEN` | policy/authorization | 아니오 |
| `PROTOCOL_MISMATCH` | version/schema/subprotocol | 아니오 |
@@ -1281,6 +1316,16 @@ user opt-in
`matchAll()`이 signal을 따르지 않거나 `waitUntil()`이 동기 예외를 내도 늦은
`postMessage`를 허용하지 않고 degraded observation으로 닫는다.
- re-subscribe가 실패하면 notification을 끄고 foreground fallback을 유지한다.
- 여러 tab은 native subscription(worker registration당 1개)과 origin의 fence
record를 공유한다. 그래서 `enable`·`reconcile`·`revoke`는 origin 단위 Web Lock
`web-push-control` 안에서 하나씩 실행한다. `inspect`는 읽기만 하므로 lock을
잡지 않는다. composition이 `navigator.locks`를 `lockManager`로 넘기고, Web
Locks가 없으면 `PUSH_UNSUPPORTED`로 보고한다
(`src/adapters/web-push/push-subscription-adapter.ts`의 `exclusive`,
`supportReadiness`). activate 실패나 session binding 불일치의 보상은 backend
association을 revoke하지만 native `unsubscribe()`는 그 호출이 새로 만든
subscription에만 한다. 이미 있던 subscription은 다른 tab의 association일 수
있다(`activateCommit`, 06-02).
`associationEpoch`은 backend registration authority가 발급한다.
`releaseEpoch`은 signed/verified release manifest에서 온다. backend registration
@@ -1300,6 +1345,26 @@ logout/account switch:
찾아 best-effort close한다.
6. 새 account opt-in은 기존 consent와 association 정책을 다시 평가한다.
logout 없이 account가 바뀐 경우(session 만료, cookie 삭제, logout 중 crash)에는
새 session이 이전 authority를 모른다. 그래서 `revoke`를 부를 수 없고, `enable`과
`reconcile`은 `STALE_AUTHORITY`로 막힌다. 이때는 `revokeForeign({ nextAuthority })`
를 한 번 부른다(`src/application/ports/out/web-push-control.ts`). 다른
`fenceGeneration`이 가진 fence를 `nextAuthority`의 `REVOKED`로 회전하고, 그 fence가
갖던 association을 revoke하고, native subscription과 그 association의 notification을
위 1~5 순서로 정리한다. 그 뒤 새 account의 opt-in이 가능하다. `nextAuthority`의
`fenceGeneration`이 이미 가진 fence(같은 session의 다른 tab이 opt-in한 경우 등)는
건드리지 않고 `inspect` 결과를 돌려준다(`push-subscription-adapter.ts`
`revokeForeign`, 06-06). 이 연산은 저장된 authority를 증명으로 요구하지 않는다.
그래서 BFF가 방금 확인한 현재 session의 authority로만 부른다. 오래된 session을 가진
tab이 부르면 현재 account의 association을 revoke하게 된다.
Web Push를 채택하려면 server 쪽에 다음 두 가지가 있어야 한다. 비정상 전환에서
client revoke가 늦거나 실패해도 이전 account의 push를 막는 것은 이 둘뿐이다.
- 짧은 association TTL: 갱신되지 않은 association은 server가 스스로 만료시킨다.
- send-time authorization: 보낼 때마다 association의 account와 session binding이
아직 유효한지 확인한다.
backend revoke가 ambiguous하면 server subscription은 짧은 association TTL,
session/account epoch 확인과 send-time authorization으로 추가 방어한다.
local `REVOKED` transaction이 실패하면 “late push를 반드시 drop했다”고 주장하지
@@ -1456,7 +1521,10 @@ worker가 종료·재시작된 뒤에도 click을 처리할 수 있도록 이 bo
envelope만 `NotificationOptions.data`에 넣는다. click handler는 codec/size/expiry,
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch
(만료, fence·release 불일치, fence 읽기 실패, 모르는 route)는 notification을 닫고
요청한 route 대신 **앱 루트(`<origin>/`)를 handoff 데이터 없이 연다**(D-14).
요청한 route 대신 **앱 루트를 handoff 데이터 없이 연다**(D-14). 앱 루트는 worker의
`registration.scope`, 즉 router base path다(예: `/app/`). scope를 모르면
`<origin>/`을 쓴다(`src/adapters/web-push/service-worker-scope-host.ts`,
`inbound/notification-click-adapter.ts`의 `appRootUrl`, 06-09).
사용자의 탭이 아무 반응 없이 사라지지 않게 하되, 거절된 click의 route와
notification 정보는 페이지로 넘기지 않는다. 결과는 여전히 실패로 보고하고
(`web_push_click_dispatched` `FAILED` + reason, `nativeEffect`는 루트 창의
@@ -1731,7 +1799,7 @@ task는 run을 fail-closed로 끝내되 underlying task가 settle할 때까지 l
`DRAINING`으로 유지하여 다음 physical connection을 허용하지 않는다.
미선택 reference source 전체를 tree-shaking 없이 합성하는 optional-recipe
측정의 gzip 상한은 40,000 bytes다. 이 값은 production bundle 허용량이 아니라
측정의 gzip 상한은 40,900 bytes다(2026-09-27 성숙도 리뷰 04-x·06-x 반영 뒤 측정값 40,886을 100바이트 단위로 올림). 이 값은 production bundle 허용량이 아니라
RT-01~RT-04 reference runtime의 회귀 예산이며, production asset에는 계속
미선택 realtime module이 0이어야 한다.
@@ -1850,6 +1918,13 @@ drop-only malformed 처리는 명시적으로 non-state-bearing heartbeat/contro
허용하며, threshold를 넘으면 protocol close한다. state-bearing event나 unknown
event type을 버리고 freshness를 `CURRENT`로 유지하지 않는다.
stream을 찾은 뒤 decode가 실패하면 consumer가 그 stream의 freshness를 `UNKNOWN`으로
바꾼다. 다음 event는 recovery부터 한다(`event-consumer.ts:89-90`,
`stream-coordinator.ts:998-1001`). registry에 없는 event type은 `MALFORMED_EVENT`가
아니라 `PROTOCOL_MISMATCH`(operation `REGISTRY`)로 닫는다(`event-codec.ts:172-175`).
event type 추가는 이전 bundle에는 호환 변경이 아니다. 조합 코드는 operation
`REGISTRY` 실패를 "구버전 client"로 보고 reload를 유도한다.
### 13.2 Effect certainty
| effect | certainty |
@@ -1905,6 +1980,23 @@ push:
- `web_push_click_dispatched`
- `web_push_association_revoked`
reference runtime의 관측 지점은 다음과 같다. 조합 코드는 attempt나 session을
감싸지 않고 이 관측을 위 event로 옮긴다.
| runtime 관측 | 만들 수 있는 event |
| --- | --- |
| reconnect `ATTEMPT_STARTED` | `realtime_connect_attempted` |
| reconnect `SESSION_OPENED`, 또는 open 전의 `RETRY_SCHEDULED`·`RUN_ENDED` | `realtime_connect_finished` |
| reconnect `SESSION_CLOSED` | `realtime_connection_closed` |
| reconnect `RETRY_SCHEDULED`(실패 kind, 대기 bucket), `RUN_ENDED`(`EXHAUSTED`·`TERMINAL`·`ABORTED`·`COMPLETED`) | 14.2 재연결 시도·대기·소진 비율 |
| WebSocket `HEARTBEAT_ACK` | `realtime_heartbeat_observed` |
| polling `LEASE_STARTED`, `ATTEMPT_FINISHED`(`VALUE`·`UNCHANGED`·실패 kind), `LEASE_STOPPED` | `bounded_poll_*` |
근거는 `reconnect-coordinator.ts:128-182`,
`polling/bounded-poll-coordinator.ts:87-113`,
`websocket/websocket-connection.ts:376-378`이다. sink가 throw해도 제어 흐름은
바뀌지 않는다(`result.ts`의 `observeRealtime`).
모든 event는 semantic registry에 등록하고 arbitrary payload를 받지 않는다.
diagnostics sink failure는 connection, worker handler, poll lease와 cleanup을
실패시키지 않으며 재귀 telemetry를 만들지 않는다.
@@ -1941,7 +2033,7 @@ server-side metric을 함께 사용한다.
- CURSOR/non-CURSOR discriminated codec와 conditional cursor commit
- effect failure 뒤 cursor 미commit
- deterministic fake clock/random의 full-jitter backoff
- stable-open 이후에만 retry attempt reset
- valid heartbeat/event와 stable-open을 둘 다 충족한 뒤에만 retry attempt reset
- queue/dedupe/reorder ceiling
- old-generation late callback drop와 current scope-binding protocol violation 분리
- effect/recovery callback lease의 `isCurrent()` commit 직전 확인과 callback
@@ -280,6 +280,18 @@ chunk recovery 순서:
4. 안전한 support surface와 trace/build ID를 표시한다.
5. recovery 결과를 redacted diagnostics에 기록한다.
지원 참조는 사용자가 문의할 때 말하는 값이고, 진단 이벤트에서 같은 값을 찾을
수 있다.
- 라우트 렌더 실패: `buildId:incidentId`. 같은 incident ID가 `ui.render.failed`
진단의 `correlation_id`에 남는다(`render-error-boundary.tsx`의
`newIncidentId`, `create-application.ts`의 `reportRenderFailure`). 화면에는
"한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`).
- 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의
`onUnrecovered`가 같은 ID로 `ui.render.failed`를 기록한다.
- 조회 실패: `AppFailure.requestId`. HTTP 진단의 `correlation_id`와 같은 값이다
(`async-surface.tsx`의 `TerminalErrorSurface`).
custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는
`location.key` 또는 route ID가 바뀌면 적절히 reset된다.
@@ -289,9 +301,15 @@ custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary
- mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus
indication을 전역으로 제거하지 않음
- modal/drawer가 닫히면 opener에 focus 복원
- backward/forward navigation은 저장한 scroll 복원
- backward/forward navigation은 저장한 scroll 복원. 복원은 브라우저가 하고,
`RouteLifecycle`은 POP이 아닐 때만 top으로 보낸다(`app-router.tsx`).
`PageHeader`의 heading focus는 `preventScroll`이라 복원된 위치를 옮기지 않는다
- 새 primary route는 top으로 이동
- hash target은 fixed header offset과 focus 가능 여부를 처리
- hash target은 fixed header offset과 focus 가능 여부를 처리. 페이지가 그려진 뒤
`PageHeader`가 대상으로 스크롤하고, 대상이 focus 가능하면 대상에, 아니면
heading에 focus한다(`page-header.tsx`). header 높이는 `html`의
`scroll-padding-top`으로 뺀다(`shell.css`). 브라우저 검증은
`tests/e2e/scroll-restoration.spec.ts`
- screen reader용 route title/live announcement는 중복 발표를 피함
### 6.4 취소와 dirty form
+74 -22
View File
@@ -26,14 +26,10 @@ remain stable in the shell.
## Registered routes
| ID | Path | Access | Surface |
| --- | --- | --- | --- |
| `APP_HOME` | `/` | public | readiness dashboard |
| `EXAMPLES_UI` | `/examples/ui` | public | interactive primitives and tokens |
| `EXAMPLES_STATES` | `/examples/states` | public | async and access state matrix |
| `EXAMPLES_AUTH` | `/examples/auth` | public | session integration controls |
| `REFERENCE_RESOURCE_LIST` | `/examples/reference-resources` | session-required | removable vertical slice |
| `NOT_FOUND` | `*` | public | safe navigation recovery |
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
the platform routes of `src/contracts/routes.ts` plus the routes of every
installed feature. The platform overview page (`/examples/platform`) shows the
composed list at runtime, so this document does not keep a copy of it.
Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
maintain a second route list. The client access decision never claims to be
@@ -81,25 +77,81 @@ or `SessionGateway` directly must add `getSubject()` the same way.
## Extending the starter
The steps below describe the current extension path. New platform work should follow
New platform work should follow
[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
and the
[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
rather than adding another independent route or data-loading convention.
1. Add a serializable contribution under the feature ownership boundary and
install it through `src/features/installed-feature-contracts.ts`.
2. Add the lazy component and route codecs through
`src/features/installed-feature-runtimes.tsx`.
3. Compose feature application inputs and outbound gateways only through
`src/features/installed-feature-adapters.ts`.
4. Use the semantic tokens, UI primitives, and state surfaces before adding a
project-specific variant.
5. Add component behavior, all-engine E2E, automated axe, and signed manual
route evidence.
6. Run `test:sample-removal` to prove the generic starter typechecks, passes
architecture/registry/tests/coverage/source-evidence/home smoke, and builds
without the complete reference feature.
### Ownership declarations
Features, contexts and apps are discovered by
`scripts/generate-product-feature-index.ts`. Each boundary declares only its
parent, as exported string or integer literals the generator reads:
| File | Exports |
| --- | --- |
| `src/apps/<app>/app-module.ts` | `APP_MODULE_ID`, `APP_MAX_CONTEXTS` |
| `src/contexts/<context>/context-module.ts` | `CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES` |
| `src/features/<feature>/feature-module.ts` | `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE` |
| `src/features/<feature>/context-routes.ts` | `FEATURE_CONTEXT_ROUTES` |
The generator writes `src/.generated/` (git-ignored): the feature index the
installed catalogs import, the context index the router loads lazily, and the
selected app. Every build and check script runs it first; run it yourself with
`corepack pnpm generate:feature-index`. It fails, naming the file, when:
- a directory under `src/features/` has no `feature-module.ts` and no
`NOT_INSTALLED` marker file (`src/features/local-draft-feature/NOT_INSTALLED`
is the one intentional example);
- a feature names an undeclared context, or a context an undeclared app;
- a context or app exceeds its declared budget;
- `VITE_PRODUCT_FEATURES` names a feature the app does not declare. The
variable narrows the installed set here, before anything is compiled.
### Adding a feature
1. Create `src/features/<feature>/feature-module.ts`. Build `FEATURE_MODULE`
with `defineFeatureModule` (`src/features/feature-module.ts`): the feature's
contract (routes, route runtime contracts, API operations, invalidation,
schemas, runtime schemas, mappers), its adapter contributions
(`defineFeatureAdapterContribution`, with `needs` naming the platform
capabilities it receives), its runtime descriptor (route codecs), its message
catalogs and its contract contributions.
`src/features/reference-feature/feature-module.ts` is the complete example.
2. Create `src/features/<feature>/context-routes.ts` exporting
`FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here; the
owning context loads this file only when its route root is visited
(`src/features/reference-feature/context-routes.ts`).
3. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or
add `src/contexts/<context>/context-module.ts` owned by the app.
4. If the feature has application input, augment `ApplicationFeatureInputs`
from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`).
5. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`,
`corepack pnpm check:registries` and the tests. `tests/unit/two-feature-install-typecheck.test.ts`
keeps the installed catalogs compiling with more than one feature.
6. Run `corepack pnpm test:sample-removal -- --feature=<feature id>` to prove
the product still builds and passes its gates without the feature.
Files outside the feature directory:
| File | Change |
| --- | --- |
| `src/.generated/*` | regenerated automatically |
| `src/contexts/<context>/context-module.ts` | only when the feature needs a new context |
| `config/runtime/<profile>.json` | optional `FEATURE_OVERRIDES` entry to switch the feature off |
| `src/bootstrap/runtime-adapters.ts` | only when `needs` includes `indexedDb`: add the capability, built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts` |
The central catalogs (`src/features/installed-*.ts`) and the registry
governance file do not change: consumer directories there are globs over every
feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`).
### Before shipping
- Use the semantic tokens, UI primitives, and state surfaces before adding a
project-specific variant.
- Add component behavior, all-engine E2E, automated axe, and signed manual
route evidence.
Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
tokens and other secrets remain forbidden storage keys.
+5
View File
@@ -29,5 +29,10 @@ sequenceDiagram
CI->>Browser: boot, route, API, and reload-loop smoke
```
In this repository the workflow stops at promotion. The upload, pointer switch
and smoke steps above belong to the project's provider adapter; after it has
deployed the promoted release, FE-GATE-019 probes the live headers (review
13-05, [`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
Rollback changes the active pointer only after confirming that the prior
immutable release has a coherent HTML/assets/config/API/manifest tuple.
@@ -52,7 +52,9 @@ TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파
1. ESLint가 product와 negative fixture의 `ts`/`tsx`를 모두 검사한다.
2. React Hooks 규칙을 추가하고 TypeScript/ESLint parser와 JSX accessibility
도구는 설치된 compiler/linter의 공식 peer 범위 안에서 선택한다.
3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다.
3. `check:architecture`의 import 그래프가 TS/TSX를 해석한다. 규칙은
`.dependency-cruiser.json`에 있지만 dependency-cruiser는 실행하지 않는다.
TypeScript 7을 해석하지 못해 0개 모듈을 검사했기 때문이다(리뷰 12-05).
4. `scripts/check-registries.ts`가 TS/TSX를 검색한다.
5. `config/contracts/registry-governance.json`과 승인 baseline은 `.ts/.tsx`
source 경로를 사용한다.
@@ -597,6 +599,7 @@ Form 또는 TanStack Form adapter를 평가한다.
- `Description`
- `FieldError`
- `ErrorSummary`
- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도·그 밖의 저장 불가 실패)
- `useAppForm`
- `mapValidationFailureToFields`
- `useDirtyNavigationGuard`
@@ -620,6 +623,7 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다.
3. submitting 중 중복 제출 방지
4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리
5. 409 conflict는 validation error로 위장하지 않음
5a. 401·403·429와 404 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시(`use-app-form.ts`의 `STATUS_RESULTS`)
6. 취소와 route 이탈 시 dirty policy 적용
7. form value → application command mapper를 별도 함수로 둠
8. browser autofill, IME composition, paste, password manager를 방해하지 않음
+55 -2
View File
@@ -3,13 +3,66 @@
The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
assetManifestHash, releaseId)`. Versions are parsed numerically.
1. additive changes preserve current required fields
2. breaking changes require a major version bump
1. a change is additive only when it adds an optional field that every
reader of the previous version tolerates; see the boundary table below
2. breaking changes require a major version bump or a reader-first deployment
3. persisted cache is discarded unless an explicit tested migration exists
4. an incompatible config or API contract blocks product mount
5. rollback restores HTML, assets, runtime config, API compatibility, and
release manifest as one coherent set
## Per-boundary rules
Whether "add a field" is safe depends on the reader, not on the writer. Old
readers stay alive: several tabs, cached app shells and rollbacks are all
supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the
reader that accepts it must ship before any writer sends it.
| Boundary | Reader policy | Adding a field or value | Code |
|---|---|---|---|
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `src/contracts/release-artifacts.ts:163-171` |
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `src/contracts/release-artifacts.ts:50-63` |
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `src/contracts/release-artifacts.ts:65-80` |
| Release manifest V2 | strict object | breaking | `src/contracts/release-artifacts.ts:200-208` |
| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `src/adapters/http/schema-registry.ts:12-34` |
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` |
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` |
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` |
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:138-140` |
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
vary per build because each downstream project installs its own features, and
one shared config document may cover several builds. The capability set is
fixed by the platform version, so an unknown capability means the config was
written for a newer platform; it is treated like any other strict config
addition.
## Schema change classifier and FE-GATE-014
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts:110`) answers
for a reader built against `before`. It is fail-closed: only a new property
under a reader without `additionalProperties: false` is `additive`. A removed
or changed property (type, enum, nullable, format, ...), a different required
set, or any other changed keyword is `breaking`. Nothing differs: `none`.
FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`)
runs `scripts/check-compatibility.ts`. It does two things:
1. Classifies the hand-written cases in `config/compatibility/fixtures.json`
and fails if any result differs from `expected`.
2. Compares the committed baseline
`config/compatibility/runtime-config.schema.baseline.json` with the current
runtime config schema, which is the same `z.toJSONSchema` output the build
writes to `dist/runtime-config.schema.json`
(`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate.
The baseline stands for the schema that readers of the previous release
accept. When a breaking config change is intended, deploy the reader first (or
bump the config major version), then run
`corepack pnpm verify:compatibility --update-baseline` and commit the new
baseline with the change. The result is recorded in
`artifacts/release/compatibility.json`.
The current `apiContractVersion` check proves release/config coherence, not
provider conformance by itself. The target multi-protocol contract set binds
REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests,
@@ -4,7 +4,7 @@
schema/cache 절차 분리
- backend 구조와 handoff:
[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)
- 기준일: 2026-07-28
- 기준일: 2026-07-28, 1절·5.1·6.0·6.3은 2026-09-25 V3 코드 기준으로 갱신
- 설계:
[API contract, Schema, Mapper와 Server State](../architecture/api-contract-schema-mapper-and-server-state.md)
- browser Protobuf/gateway 설계:
@@ -12,18 +12,28 @@
## 1. 적용 범위
현재 reference REST → Schema → Mapper → TanStack Query vertical은 `COMPOSED`다.
하지만 다음 target delta는 아직 `DESIGNED_NOT_IMPLEMENTED`다.
현재 reference REST → Schema → Mapper → TanStack Query vertical은 V3 contract
executor(`src/adapters/http/http-execution-v3.ts`)로 `COMPOSED`다. 조합 위치는
`src/bootstrap/runtime-adapters.ts`의 `createContractHttpExecutor`다. 이 문서의
"current v1"은 V2 client(`src/adapters/http/client.ts`) 시절에 쓴 말이다. V2는
기본 조합에 없다(`createRuntimeHttpClient` 호출처 없음).
- REST v2 auth fail-close/final invariant
- total logical deadline와 bounded response decoder
- complete cursor/conditional request
- typed schema/mapper registry
- strict query/mutation definition과 concurrency coordinator
- GraphQL reference adapter
- Connect-Web reference adapter
- gRPC-Web reference adapter
- Protobuf REST Gateway
2026-09-25 코드 기준 상태:
| 항목 | 상태 | 코드 위치 |
| --- | --- | --- |
| auth fail-close / final request invariant | 구현됨. 자격증명 없음·owner 장애·scope 불일치면 fetch 0회. 전송 직전 최종 요청을 다시 검사 | `runtime-adapters.ts` `attachCredentials`, `http-execution-v3.ts` credential patch 처리, `src/adapters/http/http-contract-bridge.ts` `checkFinalInvariants` |
| total logical deadline | 구현됨. 자격증명·lease·fetch·본문·backoff가 마감 하나를 공유. `REQUEST_TIMEOUT_MS`는 상한 | `http-execution-v3.ts` `effectiveDeadlineMs`, lifetime signal |
| bounded response decoder | 구현됨. 선언 길이 → 스트림 바이트 → JSON 구조 → 스키마 순 | `src/adapters/http/bounded-body-reader.ts`, `bounded-json.ts`, `http-execution-v3.ts` `admitResponse` |
| typed schema/mapper | 구현됨. 계약별 input/output/problem validator와 feature mapper | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/feature-http-binding.ts` |
| strict query/mutation definition과 concurrency coordinator | 구현됨 | `src/contracts/server-state.ts` `bindQuery`·`BoundMutation`, `src/presentation/adapters/query/application-query.ts` |
| 결과 불명 command의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다 | `application-query.ts` `resendUnknownEffect` (6.3) |
| cursor pagination | runtime만 있다. 설치된 operation이 쓰지 않는다 | `src/adapters/query-cache/cursor-pagination-runtime.ts` |
| conditional request | validator store만 조합됐다. V3는 `If-None-Match`/`If-Match`를 보내지 않는다 | `src/adapters/query-cache/conditional-validator-store.ts` |
| GraphQL reference adapter | 구현 안 됨 | 없음 |
| Connect-Web / gRPC-Web reference adapter | provider 중립 Browser RPC runtime만 있다. 조합되지 않았다 | `src/adapters/browser-rpc/` |
| Protobuf REST Gateway | 구현 안 됨 | 없음 |
| operation별 `TrafficAdmission` switch | 구현 안 됨 | 없음 |
GraphQL/Connect/gRPC-Web/REST Gateway 절차는 해당 runtime과 actual provider가
구현·조합된 뒤에만 운영 gate로 활성화한다. 문서나 fake fixture만으로 capability를
@@ -142,11 +152,14 @@ artifact에서 access-controlled하게 비교한다.
### 5.1 Auth-required request가 무자격으로 전송됨
현재 v1은 external auth integration이 unavailable이어도 unchanged request가
전송될 수 있으므로 target v2 전까지 제품 auth-required traffic을 provider
evidence 없이 활성화하지 않는다.
V3는 자격증명이 없거나(`UNAUTHENTICATED`), auth owner가 장애거나
(`integration-failed` → `CREDENTIAL_OWNER_UNAVAILABLE`), scope가 준비되지 않았으면
fetch 없이 끝난다(`src/bootstrap/runtime-adapters.ts` `attachCredentials`,
`src/adapters/http/http-execution-v3.ts` credential patch 처리). 전송 0회 미인증은
diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그래도 무자격
전송이 보이면 V3가 아닌 경로(V2 client 직접 조합, 외부 SDK)를 먼저 의심한다.
target 점검:
점검:
1. session state가 authenticated인지 확인한다.
2. auth owner가 `CredentialPatch`만 반환하는지 또는 final request invariant를
@@ -168,26 +181,37 @@ target 점검:
3. cross-origin allow-origin/credentials/method/header/expose가 exact한지 확인한다.
4. wildcard credential, redirect와 unexpected origin을 복구한다.
5. CSRF token/header 값을 ticket에 기록하지 않는다.
6. V3 요청은 논리 실행마다 `x-correlation-id` 하나를 보낸다(재시도도 같은 값,
`src/adapters/http/http-execution-v3.ts` `createRequestId`). cross-origin API면
preflight `Access-Control-Allow-Headers`에 `x-correlation-id`가 있어야 요청이
나간다. 응답의 `x-correlation-id`를 `AppFailure.requestId`와 diagnostics
`correlation_id`로 쓰려면 `Access-Control-Expose-Headers`에도 넣는다
(`src/adapters/http/feature-http-binding.ts` `projectExecutionOutcome`,
`src/bootstrap/runtime-adapters.ts` `createHttpObservationProjector`). telemetry에는
넣지 않는다.
## 6. REST incident
### 6.0 Current v1 available checks
### 6.0 V3에서 바로 쓸 수 있는 점검
1. current per-attempt timeout/bounded retry, Query retry off, AbortSignal과 401
recovery observation을 확인한다.
2. installed request/envelope/payload Zod schema와 mapper failure kind를 확인하되
current `Response.json()`이 body cap 증거가 아님을 기록한다.
1. 전체 마감 하나와 재시도 상한 min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2)을
확인한다. TanStack Query 재시도는 꺼져 있다(`http-execution-v3.ts`,
`src/adapters/query-cache/tanstack-query-cache.ts`). 전송별 차이는
[backend contract 16.1절](../architecture/backend-api-and-server-state-contract.md)
표를 본다.
2. 본문은 `bounded-body-reader.ts`가 상한을 적용한 뒤 계약 validator와 feature
mapper를 거친다. 실패 kind로 어느 단계인지 좁힌다.
3. QueryClient/coordinator로 affected read를 cancel/invalidate/clear한다.
4. cursor response/page runtime, APP_ETAG와 total deadline은 아직 없으므로 해당
control을 실행했다고 기록하지 않는다.
5. command effect는 backend와 reconcile한다. basic optimistic snapshot 문제가
의심되면 runtime switch를 가정하지 말고 no-optimistic/known-good release로
rollback한다.
4. cursor runtime과 conditional request는 설치된 operation에 조합되지 않았으므로
해당 control을 실행했다고 기록하지 않는다(1절 표).
5. 문의 식별자는 `AppFailure.requestId`와 diagnostics `correlation_id`로 서버 로그와
잇는다(5.2절 6항).
아래 6.1~6.5는 target v2 coordinator가 해당 operation에 composed된 뒤에만
운영 절차로 활성화한다.
6.1·6.2는 V3 operation에 적용한다. 항목 중 V3에 없는 control은 실행했다고
기록하지 않는다. 6.4·6.5는 해당 runtime이 operation에 조합된 뒤에만 운영 절차로
활성화한다.
### 6.1 Timeout/retry storm — target v2
### 6.1 Timeout/retry storm
1. Query retry가 꺼지고 REST transport 하나만 network retry하는지 확인한다.
2. total logical deadline 안에 auth, fetch, body, mapper, recovery와 sleep이 모두
@@ -202,7 +226,7 @@ target 점검:
7. timer/listener/reader leak가 있는 cohort는 traffic을 닫는다.
8. keyed command는 backend dedupe evidence 없이는 retry를 끈다.
### 6.2 Body/media/schema failure — target v2
### 6.2 Body/media/schema failure
1. final URL/status/content type을 확인한다.
2. present/valid Content-Length advisory preflight와 actual browser-visible decoded
@@ -219,15 +243,24 @@ target 점검:
10. backend/frontend artifact가 coherent하지 않으면 operation traffic을 닫고
N/N-1 compatible set으로 rollback한다.
### 6.3 Idempotency/ambiguous command — target v2
### 6.3 Idempotency/ambiguous command
1. principal/operation/payload digest/key tuple과 backend TTL/status를
access-controlled evidence에서 확인한다.
2. 같은 key + 다른 payload가 거절되는지 확인한다.
3. concurrent same-key request가 duplicate commit을 만들지 않았는지 확인한다.
4. `UNKNOWN` effect에 새 key를 생성해 retry하지 않는다.
5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다.
6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다.
4. `UNKNOWN` effect에 새 key를 생성해 retry하지 않는다. 클라이언트는 결과 불명
admission의 intent를 보관하고, 같은 canonical input의 재저장과 "같은 요청으로
다시 보내기"는 그 intent와 같은 `Idempotency-Key`로 보낸다. 입력이 바뀌면 새
key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts`
`submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`).
5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. 화면의
"변경됨으로 확인"이 이 경로다.
6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는
"변경되지 않음" 확정을 주지 않고 목록 새로고침 링크를 준다.
7. 한계: 결과 불명 admission은 메모리에만 있다. 새로고침·로그아웃·계정 전환 뒤
같은 입력의 저장은 새 key다. 서버 key 보관 기간이 지난 뒤의 재전송도 중복될
수 있다. 두 경우는 backend 도메인 유일성 제약이나 status 조회로 막는다.
### 6.4 Cursor loop — target v2
+104 -18
View File
@@ -16,15 +16,24 @@ primitive를 coordinator 완료 증거로 사용하지 않는다.
## OPFS 보상 실패와 reconcile (STO-01)
`put()`이 실패했는데 보상 cleanup effect가 확인되지 않으면 runtime은 실패를
`OBJECT_RECONCILE` / `CONFLICT`(recovery `RETRY`)로 보고하고 journal row를 남긴다.
이는 결함이 아니라 설계된 상태다.
`put()`이 commit 전에 실패하면 coordinator가 그 transaction의 staging을 지우고
journal row를 되돌린다(보상). 보상의 worker cleanup이나 journal rollback이 끝나지
않으면 put은 자기 실패 코드(`QUOTA_EXCEEDED`, `ABORTED` 등)와 operation
`OBJECT_WRITE`를 그대로 두고 recovery만 `RECONCILE`로 바꿔 반환한다. journal
row(`PREPARING`/`FILES_READY`)는 남는다(`opfs-byte-store-adapter.ts`
`compensatePreparedPut`, Q-6.5-9). 이는 결함이 아니라 설계된 상태다. worker가
cleanup 결과를 확인하지 못하면 성공 값이 아니라 실패로 답한다. 별도의 "결과 불명"
값은 없다(05-09).
1. journal에 `PREPARING` 또는 `FILES_READY` row가 남아 있는지 확인한다. 남아
있다면 staging bytes가 아직 존재할 수 있다는 뜻이다.
2. `maintenance.reconcile()`을 실행한다. reconcile은 같은 exact physical
generation token만 삭제하고, effect가 여전히 `EFFECT_UNKNOWN`이면 journal을
유지한 채 다시 `OBJECT_RECONCILE`을 반환한다.
2. `maintenance.reconcile()`을 실행한다. reconcile은 exact physical generation
token만 삭제한다. report에서 다음을 본다.
- `skippedLiveTransactions`: 어느 tab에서든 아직 진행 중인 put/delete의 row다.
reconcile은 transaction별 Web Lock을 `ifAvailable`로 잡지 못한 row를 건드리지
않는다(05-01, `reconcile`의 `holdTransactionLock`). 결함이 아니다.
- `failedTransactions`: 이번에 정리하지 못해 journal에 남긴 row 수다. 나머지
row와 orphan GC는 계속 돈다(05-02). 같은 row가 계속 실패하면 §7을 본다.
3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할
근거가 사라지고 quota만 누수된다.
4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지
@@ -36,6 +45,9 @@ primitive를 coordinator 완료 증거로 사용하지 않는다.
incident 중에도 다음 작업은 금지한다.
- 자동 또는 일괄 `deleteDatabase()`
- 예외는 하나다. authority가 승인한 LOGOUT/ACCOUNT_DELETION이 손상된
governance 때문에 dataset을 열 수 없을 때, runtime이 그 partition의 DB
하나만 지운다(§5 "database 전체 삭제" 참고).
- origin의 모든 `caches.keys()` 삭제
- user-authored/unsynced IndexedDB 또는 OPFS data 자동 purge
- schema version downgrade
@@ -154,6 +166,12 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
- `versionchange` 뒤 connection이 남음
- repeated reload/update loop
- open/maintenance의 `POLICY_REJECTED`: immutable dataset binding missing/mismatch
- open의 `UNSUPPORTED` / `ONLINE_ONLY`와 status `INCOMPATIBLE`: 더 새 release가
schema를 올린 DB를 이전 bundle이 열었다(05-06). migration 실패가 아니므로 §5로
가지 않는다. 이 bundle은 그 dataset을 읽지도 쓰지도 않고 online-only로
동작하며, 새 release로 reload하면 풀린다
(`indexeddb-runtime.ts` open의 `VersionError` 분기). OPFS journal도 같은 답을
낸다(`indexeddb-opfs-journal.ts` `translateFor`)
### 확인 순서
@@ -170,7 +188,8 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
6. 모든 connection에 `versionchange`/forced-close handler가 설치됐는지 확인한다.
7. BroadcastChannel prepare hint는 참고만 하고 실제 open/connection registry를
확인한다.
8. N-1 bundle이 future schema를 read-only/online-only로 처리하는지 확인한다.
8. N-1 bundle이 future schema를 `INCOMPATIBLE` / `ONLINE_ONLY`로 처리하는지
확인한다. reference runtime은 read-only가 아니라 online-only로 닫는다.
### 안전한 조치
@@ -196,6 +215,12 @@ remote tab 강제 종료, database 삭제, 무한 reload는 금지한다.
- `MIGRATION_FAILED`, unknown codec, schema postcondition failure
- `CORRUPT_DATA`, `NOT_READABLE`, forced close
- `RETENTION_SWEEP`(`INDEXEDDB_WRITE`)과 `pruneExpiredReceipts`
(`INDEXEDDB_MIGRATE`)의 `CORRUPT_DATA` 관측은 실패가 아니다. 손상 행을 지우지
않고 건너뛴 수이고, 나머지 정상 행은 정리된다(05-05,
`indexeddb-runtime.ts` `purgeEligibleRecords`,
`indexeddb-maintenance.ts` `pruneExpiredReceipts`). budget이 삭제 bytes나
receipt 수를 감당하지 못하면 그 값은 내리지 않고 둔다
- transaction request success 후 commit failure
- `LIMIT_EXCEEDED`: dataset logical byte/receipt budget 초과
- lifecycle batch가 proof 없이 실행되거나 TTL/UNTIL_SYNCED record가 잘못 노출·삭제
@@ -248,7 +273,21 @@ remote tab 강제 종료, database 삭제, 무한 reload는 금지한다.
proof를 운영자가 수동 생성·재사용하지 않음
database 전체 삭제는 data owner가 export/recovery와 영향 scope를 승인한 별도
action이다.
action이다. runtime이 스스로 DB를 지우는 경우는 하나뿐이다(05-03).
- 조건: `enforceLifecycleBatch`의 action이 `LOGOUT` 또는 `ACCOUNT_DELETION`이고,
`authorizeLifecycle`이 proof를 내준 뒤, open이 `POLICY_REJECTED` 또는
`CORRUPT_DATA`로 실패했을 때(budget/binding 행 손상, 바뀐 policy). 행 단위
purge는 open이 필요해서 이 상태에서는 영영 돌 수 없다
(`src/adapters/storage/indexeddb/indexeddb-runtime.ts` `deleteUnadmittedDataset`).
- 범위: 세 opaque token에서 만든 그 partition의 DB 이름 하나
(`indexeddb-governance.ts` `indexedDbPhysicalDatabaseName`). 다른 partition과
origin의 다른 DB는 건드리지 않는다.
- 결과: 지워지면 receipt `COMPLETE`와 `datasetDeleted: true`(행 수는 세지
않는다). 다른 context가 연결을 닫지 않아 blocked deadline이 지나면 `BLOCKED`
/ `RELOAD_OTHER_CONTEXTS`를 반환한다. 이때 삭제 요청은 브라우저에 살아 있어
나중에 적용될 수 있으므로 다른 tab을 닫고 같은 purge를 다시 호출한다.
- governance가 정상이면 지금처럼 행 단위 purge만 하고 DB는 지우지 않는다.
성공 판정:
@@ -336,6 +375,11 @@ VD-15 목표 runtime을 먼저 구현한다.
- committed logical row와 physical manifest/file 불일치
- digest/length mismatch
- worker crash, handle lock timeout, `NoModificationAllowedError`
- put의 retryable `NOT_READABLE`: source가 `putIdleTimeoutMs`(기본 2분) 동안 다음
bytes를 주지 않아 put을 끝내고 origin mutation lock을 풀었다(05-07,
`opfs-worker-client.ts` `preparePut`, `opfs-policy.ts`). OPFS 쓰기는 origin
전체에서 한 번에 하나라서, 이 bound가 없으면 멈춘 source 하나가 모든 tab의 쓰기를
`mutationLockWaitTimeoutMs` 뒤 `BLOCKED`로 만든다
- sensitive policy maintenance의 `POLICY_REJECTED`, proof replay/expiry 또는
authority provider/consumer unavailable
@@ -371,12 +415,25 @@ VD-15 목표 runtime을 먼저 구현한다.
### recovery
- `PREPARING`: partial staging 검증 후 idempotent resume 또는 purge
- `FILES_READY`: expected generation/digest 일치 시 logical commit, 아니면
quarantine
- `PREPARING`: reconcile은 resume하지 않는다. staging receipt가 가리키는 그
transaction의 physical generation과 staging을 지우고 journal row를 rollback한다.
receipt가 없거나 0바이트면(첫 receipt 쓰기가 quota나 crash로 끝나지 못함) 지울
generation이 없으므로 staging만 지운다(05-02). 읽을 수 없는 receipt는 지우지
않고 그 row를 `failedTransactions`로 남긴다
(`opfs-byte-store-adapter.ts` `reconcileTransaction`,
`opfs-worker-runtime.ts` `cleanupTransactionLocked`)
- `FILES_READY`: worker가 manifest와 모든 chunk digest를 다시 검증한다. 맞으면
logical commit 뒤 finalize한다. 맞지 않으면 quarantine하지 않고 그 generation과
staging을 지운 뒤 rollback한다. 지워지는 것은 commit 전 staging뿐이다
- `COMMITTED` + file missing/corrupt: reconstructable만 server rehydrate;
user-created private는 read-only/export/recovery
- stale staging/orphan chunk는 grace period와 bounded mark/sweep 후 제거
- `LOGOUT`/`ACCOUNT_DELETION` purge는 객체를 모두 지운 뒤 그 partition의 chunk를
grace 없이 sweep한다(05-04, `opfs-byte-store-adapter.ts` `enforcePolicies`).
journal이나 staging receipt가 참조하는 chunk는 이때도 지우지 않는다. report의
`chunkSweep`이 `COMPLETED`여야 bytes가 지워진 것이다. `DEADLINE_REACHED`면 같은
purge를 다시 호출하고, `STAGING_STATE_UNREADABLE`이면 읽을 수 없는 staging부터
처리한다
- lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only
- scope binding mismatch면 affected scope를 read-only로 격리하고 registry/
composition을 forward fix; 다른 token path로 bytes를 이동하거나 추측 복구 금지
@@ -403,8 +460,11 @@ committed object를 sync handle로 in-place repair하지 않는다. 새 generati
## 8. Cache Storage/Service Worker stale or poisoned release
public static Cache release runtime은 존재하지만 cursor/count/deadline이 있는
bounded inspect/cleanup과 Service Worker waiting/client-drain controller는 아직
없다. Service Worker는 제품이 PWA/offline fetch를 별도로 선택한 경우에만 아래
bounded inspect/cleanup은 아직 없다. Service Worker의 waiting/client-drain
활성화는 page controller의 `requestActivation()` 핸드셰이크로 구현돼 있다
(`src/adapters/service-worker/service-worker-page-controller.ts`). 템플릿에는 이를
부르는 화면이 없다. Service Worker는 제품이 static selection
(`src/features/installed-runtime-capabilities.ts`)을 `ACTIVE`로 바꾼 경우에만 아래
worker 절차를 적용한다.
### 신호
@@ -449,12 +509,38 @@ static Cache-only 조합:
invocation을 추가 budget으로 반복 실행하지 않는다. VD-15 bounded cursor
runtime 구현 전에는 큰 namespace를 자동 sweep하지 않는다.
Service Worker를 별도 선택한 조합에서만 추가:
Service Worker를 별도 선택한 조합에서만 추가. 워커의 fetch 가로채기만 끄는
스위치는 없다. 끄는 경로는 아래 둘이다.
- fetch interception을 network-only kill switch로 전환
- new worker activation 중지
- 필요하면 unregister + 다음 navigation cleanup migration
- old controlled client가 drain되기 전 해당 release cleanup 금지
- 페이지가 부팅하면: runtime config에 `CAPABILITY_OVERRIDES.SERVICE_WORKER:
"DISABLED"`를 넣는다. 재빌드는 필요 없다. 다음 부팅 때 page controller가 scope와
script가 정확히 일치하는 등록만 unregister하고, 새 등록은 하지 않는다
(`src/contracts/runtime-capabilities.ts` `resolveRuntimeCapabilities`,
`service-worker-page-controller.ts` `start()`의 `disabledCleanup` 분기). 소유
캐시는 지우지 않는다. unregister는 이미 열린 탭의 제어를 끊지 않으므로, 그 탭은
닫히거나 다시 load될 때까지 현재 워커를 쓴다.
- 워커 때문에 페이지가 부팅하지 못하면: static selection을
`{ mode: "REMOVE_REGISTRATION", scriptPath: "service-worker.js" }`로 바꾼
release를 배포한다. 이 release는 같은 URL에 자기 해제 `service-worker.js`를 낸다
(`scripts/build-frontend.ts`, `scripts/lib/self-unregistering-service-worker.ts`).
페이지 코드가 돌지 않아도 브라우저 update 검사(내비게이션 때, 등록은
`updateViaCache: "none"`)가 이 파일을 받아 설치한다. 설치 즉시
`skipWaiting()`하고, 활성화 때 `registration.unregister()`한다. fetch handler가
없어서 그동안의 요청은 모두 네트워크로 간다. 다음 load부터는 제어받지 않는다.
브라우저 확인: `tests/e2e/service-worker-recovery.spec.ts`.
- 이 경로가 동작하려면 `service-worker.js`를 `Cache-Control: no-cache`로 서빙해야
한다. `verify:hosting-headers`는 파일이 있는지만 보고 이 헤더는 보지 않는다
(`scripts/lib/hosting-probe.ts` `checkPublicServiceWorkers`).
- 새 워커는 install에서 `skipWaiting()`하지 않는다(`service-worker-entry.ts`).
활성화는 페이지의 `requestActivation()`으로만 일어나므로, 새 worker 활성화를
멈추려고 따로 할 일은 없다.
- 제거는 `ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null` 순서로
release를 나눈다(`src/contracts/service-worker.ts`
`InstalledServiceWorkerSelection`). 소유 캐시는 `PURGE_OWNED_RESOURCES` release의
page controller가 지운다(`service-worker-removal.ts` `purgeOwnedResources`).
old controlled client가 drain되기 전에는 이 release를 배포하지 않는다. 캐시가
사라지면 그 탭의 워커는 요청을 네트워크로 넘기고(`service-worker-entry.ts`
fetch 리스너의 `cached ?? fetch(request)`), 서버에 없는 옛 청크는 404가 된다.
hosting/CDN purge는 두 branch와 분리된 provider 절차로 실행한다.
+120 -6
View File
@@ -1,6 +1,6 @@
# CI quality-gate orchestration
`config/ci/gates.json` is the executable registry for all 26 gates and the sole
`config/ci/gates.json` is the executable registry for every gate and the sole
workflow model. `.gitea/workflows/quality-gates.yml` is generated from that
strict v2 contract; it is not an independent configuration authority. Update
the registry, run `corepack pnpm generate:ci-workflow`, and commit the generated
@@ -10,6 +10,65 @@ checking, the typed contract checker, and this workflow drift check. The Gitea
adapter runs each gate as an independent matrix check with full fan-out and no
soft-fail wiring.
## 기준선 갱신과 새 프로젝트 시작 시 초기화할 기준선
게이트 계약의 크기와 모양은 코드 상수가 아니라 `config/ci/contract-baseline.json`에
있다. 이 파일에는 게이트 수, 명령 정의 수, 명령 참조 수, 산출물 수, stage 수,
게이트 모양 SHA-256과 함께 `owner`·`reason`이 들어 있다. 계약을 불러올 때 현재
`gates.json`과 이 파일이 다르면 실패한다(`scripts/contracts/ci-gates.ts`의
`assertCiContractBaseline`). 그래서 게이트·명령·산출물을 추가하거나 지운 뒤에는
다음 순서로 커밋한다.
```
# 1. config/ci/gates.json 수정
CI_CONTRACT_BASELINE_OWNER=<팀> CI_CONTRACT_BASELINE_REASON=<이유> corepack pnpm update:ci-contract-baseline
corepack pnpm generate:ci-workflow
corepack pnpm check:ci
```
`update:ci-contract-baseline`은 `scripts/update-ci-contract-baseline.ts`를 실행한다.
리뷰는 `contract-baseline.json`의 diff로 변경을 승인한다. 샘플·recipe·런타임 제거
검증(`test:*-removal`)도 같은 절차를 쓴다. 줄인 계약을 기준선으로 기록한 뒤
canonical `check:ci`를 돌린다(`scripts/lib/removal-fixture.ts`의
`pruneRemovalFixtureCiContract`). 완화 모드는 없다.
`check:ci`는 `tests/` 아래 테스트 파일(`tests/fixtures` 제외)이 모두 CI 게이트
명령에서 실행되는지도 확인한다. 게이트 명령이 닿는 package script의 Vitest 경로와
Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests.ts`).
`run-scale-profile.ts <tier>`를 부르는 명령은 그 tier의 Vitest 경로로 센다.
게이트가 돌리지 않는 테스트는 `config/ci/ungated-tests.json`에 이유와 함께 적어야
한다. 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
package script도 같은 방식으로 확인한다(`scripts/lib/ungated-scripts.ts`).
`check:*`·`verify:*`·`test:*`·`drill:*`·`review:*` 스크립트는 게이트 명령에서
package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경로만 다시 돌려야
한다. 둘 다 아니면 `config/ci/ungated-scripts.json`에 이유와 함께 적는다. 게이트가
닿는 스크립트를 이 목록에 남겨 두면 실패한다. 두 목록에 남은 항목과 이유는 각
파일에 있다.
규모 테스트는 이렇게 나뉜다(리뷰 11-03, `scripts/scale/run-scale-profile.ts`).
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
검사하므로 CPU가 달라도 결과가 같다. S0~S2 조합 증가 검사가 여기 있다. S0/S1만
재면 모든 workload가 noise floor 아래라 이차 누적을 놓친다. 조합 timing은
산출물(`artifacts/scale/pr/composition-s0-s2.json`)에 기록만 한다.
- `main`·`nightly`·`release` tier는 CI에서 돌지 않는다. 이 tier들은
`baseline-regression`을 포함한다. 이 단계는 `config/scale/benchmark-baseline.json`을
기록한 CPU 모델에서만 timing을 비교하고, 다른 CPU에서는 `incomplete`로 끝난다.
이 tier에만 있는 테스트는 `ungated-tests.json`에, tier를 실행하는 `check:scale:*`
스크립트는 `ungated-scripts.json`에 이유와 함께 남아 있다.
템플릿을 복사해 새 프로젝트를 시작하면 아래 기준선은 템플릿의 값이다. 샘플을
지우거나 구조를 바꾸면 프로젝트 값으로 다시 찍는다.
| 기준선 | 파일 | 갱신 방법 | 검사 위치 |
|---|---|---|---|
| CI 계약 크기·게이트 모양 | `config/ci/contract-baseline.json` | `update:ci-contract-baseline` (`CI_CONTRACT_BASELINE_OWNER`·`_REASON` 필수) | `scripts/contracts/ci-gates.ts` `assertCiContractBaseline` |
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가 | `scripts/check-registries.ts`의 baseline 비교 |
| 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" |
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 없음. 남은 키는 조용히 무시된다(리뷰 09-09) |
| 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` |
Contract loading validates every registered command entry against the
authoritative root package-script graph and lifecycle/install policy before the
runner enters its execution callback. Foreign cwd/workspace script dispatch,
@@ -43,6 +102,16 @@ The gate runner checks the same inherited environment names before loading the
contract or entering the execution callback, so they cannot reach a child gate
process.
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다.
첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture).
`allowBuilds`는 pnpm의 의존성 build script만 제한한다. 루트 프로젝트의 install
hook과 npm/yarn 설치는 `--ignore-scripts`가 없으면 그대로 돈다. 둘째, 게이트가
부르는 이름이 다른 manifest의 script로 바뀌는 경로다(`--prefix`, `--filter`,
`-C`, npm pre/post hook, `npm_config_*`). 이것은 설치 옵션과 관계가 없다. 이유는
파일 머리 주석에도 있다.
The dependency graph is:
```text
@@ -54,9 +123,22 @@ MERGE_READY
DOCUMENTATION_READY (off-chain)
```
`check:architecture`는 dependency-cruiser 결과와 별도로 Babel parser/Node
resolver 기반 `staticImportGraph`를 `artifacts/quality/dependency-report.json`에
기록한다. TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
(`scripts/verify-documentation-readiness.ts`).
- diagram 리뷰 ledger(`docs/architecture/review-ledger.json`)와
`review-evidence.md`가 같은 경로·해시·점수를 담는지
- README와 `docs/accessibility/manual-checklist.md`가 설치된 route ID를 모두
적는지
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
문서의 다른 내용(수치, 목록, 설명)이 코드와 맞는지는 검사하지 않는다(리뷰 14-07).
`check:architecture`는 Babel parser/Node resolver 기반 `staticImportGraph`를
`artifacts/quality/dependency-report.json`에 기록한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser는 실행하지 않는다.
dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고
통과했다(리뷰 12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
로컬 source import에는 실제 TypeScript 확장자를 요구한다. 실행 source나 로컬
specifier에 `.js/.jsx/.mjs/.cjs`가 있거나 unresolved dependency, parse failure,
error-severity layer violation, cycle 또는 지원하지 않는 architecture rule
@@ -229,7 +311,28 @@ promotion, and field evidence through aggregation.
Runbook jobs write to the stable path
`artifacts/runbooks/<runbook-id>/record.json`; the dynamic release identity is
stored inside the record. This keeps gate evidence lookup independent from
stored inside the record.
A runbook drill (`drill:runbook`, FE-GATE-021..025) records each verdict as
`PASS`, `FAIL` or `UNVERIFIED` (`scripts/drill-runbook.ts`, record schema in
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL` means the drill checked
it against a built `dist/`; it reads no `public/` placeholder, so a missing build
fails. In CI the production stage does not rebuild: `production_gate` downloads
the `promoted-release` artifact of the promotion job, extracts its
`release-candidate.tar.gz` to `.release/promoted-release` after checking it
against the `archive_sha256` of `immutable_build`
(`scripts/verify-ci-candidate-archive.ts`), and each drill command passes
`--release-root .release/promoted-release` (`config/ci/gates.json`). The CI
contract rejects a production drill gate that builds or omits the release root
(`scripts/contracts/ci-gates.ts`, 13-03). Run locally without `--release-root`,
a drill checks the local build. Browser boot, live API traffic, smoke after a provider
switch, and anything the runbook marks as needing provider verification are
`UNVERIFIED`. One `FAIL` makes the drill `FAIL` (exit 1). Otherwise any
`UNVERIFIED` makes it `UNVERIFIED` (exit 3), and the gate is not `PASS`. So
without provider evidence the production stage stays open. That is the intended
result: a local drill cannot show that the promoted release can be rolled back.
FE-GATE-016 (`rollback-drill`) is retired because it ran the same FE-RB-005
drill as FE-GATE-025 (`RETIRED_GATE_IDS` in `scripts/contracts/ci-gates.ts`). This keeps gate evidence lookup independent from
slashes or other provider-specific characters in `RELEASE_ID`, while each
workflow artifact remains scoped to its own run.
@@ -295,7 +398,18 @@ Repository variables required by higher tiers:
- `RUNNER_IMAGE_DIGEST` for the immutable job-container image digest used by the
`ubuntu-latest` runner label; the workflow exposes it to gates as
`CI_RUNNER_IMAGE` (required by every tier)
- `HOSTING_BASE_URL` for live header verification
- `HOSTING_BASE_URL` for live header verification of the deployed promoted
release (FE-GATE-019, production stage). Without it the gate fails; the
local fixture result is `UNVERIFIED`
- `APP_PROFILE` for the runtime profile the release candidate is built from
(`local`, `development`, `staging`, `production`;
`scripts/generate-runtime-config.ts`). An unset value builds `local`; an empty
value fails the build.
- `RELEASE_TARGET` for the environment FE-GATE-027 admits the candidate to
(`scripts/check-release-admission.ts`). It has no default. The immutable_build
job runs FE-GATE-015 and then FE-GATE-027, and FE-GATE-027 refuses the
candidate when `APP_PROFILE` is set and differs from `RELEASE_TARGET`. Both are
repository-wide variables, so set them together for each release.
- `FIELD_WEB_VITALS_INPUT` for the privacy-approved field sample document
- `MIN_ELIGIBLE_SAMPLES` after the baseline decision
- `VULNERABILITY_PROVIDER_COMMAND` and `PROVENANCE_PROVIDER_COMMAND` for the
+54
View File
@@ -10,6 +10,60 @@ Performance evidence is deliberately split by measurement context:
release-specific production samples over 28 days and evaluates p75 LCP, CLS,
and INP against 2.5 s, 0.10, and 200 ms.
## 번들 예산의 기준선과 여유
리뷰 13-14. 예산은 `config/performance/budgets.json`에 있고
`scripts/check-bundle.ts`가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의
96%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다.
| 항목 | 값 |
|---|---|
| 초기 JS 예산 | 204,800 gzip bytes(200 KiB) |
| 템플릿 기준선(2026-09-25 측정) | 196,573 gzip bytes. 빌드 ID가 번들에 들어가므로 빌드마다 수백 바이트 달라진다(196,386~196,623 관측) |
| 여유 | 약 8,200 bytes(4%) |
| lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 가장 큰 lazy chunk는 약 8 KB |
초기 JS 9개 파일 중 세 개가 대부분이다. `index` 93.5 KB, `design-system`
65.6 KB, `preload-helper` 28.5 KB(zod 포함). 나머지 여섯은 합쳐 9 KB 정도다.
측정 조건:
- 초기 파일은 Vite manifest의 entry와 그 static import다
(`scripts/lib/classify-vite-bundle.ts`). dynamic import chunk는 lazy다.
- 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.5 KB gzip)는 예산에 들어가지
않는다.
- gzip은 Node `zlib.gzipSync` 기본 수준(6)으로 잰다
(`scripts/lib/release-candidate.ts`). 호스팅이 brotli로 보내면 전송 크기는 더
작다. 예산은 gzip 기준 그대로 둔다.
- Node·pnpm·runner 이미지는 `artifacts/performance/bundle.json`의 `context`에
기록된다.
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를
`vite preview --strictPort`로 띄워 잰다(리뷰 11-07).
- 포트는 `LAB_PERFORMANCE_PORT`(기본 4173)다. 서버를 띄우기 전에 그 포트가
이미 응답하면 실패하고, 응답하는 `/release-manifest.json`의 build·release가
로컬 `dist/release-manifest.json`과 다르면 실패한다
(`scripts/lib/lab-performance.ts`, `tests/unit/lab-performance.test.ts`).
- 새 브라우저 context에서 `--runs=N`(기본 5)번 재고, 예산은 중앙값으로
판정한다. 모든 측정값과 최소·최대는 `lab.json`의 `context.sampling`에 남는다.
- named interaction은 페이지 안의 시계로 잰다. 클릭 이벤트의 `timeStamp`부터
대상 heading이 DOM에 들어온 시각까지다. Playwright 왕복 시간은 들어가지 않고,
lazy chunk 다운로드(200 KB/s 제한)는 들어간다. 클릭의 Event Timing entry
길이(INP의 입력값)는 `context.sampling.clickEventDurationMs`에 따로 남는다.
- CPU 모델, 논리 CPU 수, 측정 전후 loadavg를 `context.runner`에 남긴다.
- preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다.
`corepack`에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다.
2026-09-27 한 빌드를 10회 잰 결과(i5-10400F 12 CPU, loadavg 11~17): 중앙값
LCP 2,386ms, interaction 184.5ms로 통과했다. 한 번씩 판정했다면 interaction
10회 중 4회(최대 274ms), LCP 10회 중 2회(최대 2,644ms)가 실패였다. 같은
빌드를 loadavg 7~9에서 다시 10회 재면 interaction 120~148ms, LCP
1,968~2,072ms로 모두 통과했다. 한 번 측정한 판정은 호스트 부하에 따라
뒤집히고, 중앙값 판정은 두 번 모두 통과였다.
The field minimum eligible-sample threshold is intentionally unresolved until
a privacy-approved telemetry baseline exists. Therefore the field command
fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
+83 -8
View File
@@ -12,6 +12,32 @@ cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
HTML alone, or declaring recovery from cache-purge completion is prohibited.
Recovery is established by old/new reachability probes.
Before deploying a promoted release later, or rolling back to one, re-verify
its promoted bundle (the five files uploaded by the `promotion` job) with the
archived mode (review 13-04). Provider evidence expires two hours after issue,
so the normal mode refuses any release promoted before that. The archived mode
still checks signatures, digests and the exact five members, and judges
freshness at the release's recorded promotion time
(`promotion-verification.json` `verifiedAt`, which may not lie in the future).
New promotion never uses it (`scripts/lib/exact-promotion-bundle.ts`).
```bash
VULNERABILITY_PUBLIC_KEY_PATH=... VULNERABILITY_KEY_ID=... \
PROVENANCE_PUBLIC_KEY_PATH=... PROVENANCE_KEY_ID=... \
EXPECTED_PROMOTION_RUN_ID=<run id> EXPECTED_PROMOTION_RUN_ATTEMPT=<attempt> \
EXPECTED_PROMOTION_SOURCE_REVISION=<commit> \
EXPECTED_PROMOTION_ARCHIVE_SHA256=<archive sha256> \
corepack pnpm verify:promotion -- --root <promoted bundle directory> --archived
mkdir <release dir> && tar -xzf <promoted bundle directory>/release-candidate.tar.gz -C <release dir>
corepack pnpm drill:runbook -- FE-RB-005 --release-root <release dir>
```
The expected values come from the release record, not from the bundle. The
drill then checks that release's build/config/manifest tuple and its assets,
not the local build. It ends `UNVERIFIED` until the provider switch and smoke
are recorded, because those happen outside this repository.
The provider-independent cache defaults are:
- hashed assets: `public, max-age=31536000, immutable`
@@ -19,16 +45,65 @@ The provider-independent cache defaults are:
- runtime config and release manifest: `no-store`
- public source maps: disabled
- service worker/offline cache: disabled, unless the static selection in
`src/features/installed-runtime-capabilities.ts` is `ACTIVE`; then `dist`
holds exactly the selected `service-worker.js`
`src/features/installed-runtime-capabilities.ts` is `ACTIVE` or
`REMOVE_REGISTRATION`; then `dist` holds exactly the selected
`service-worker.js`, served `no-cache` so the browser's update check sees
each release's worker
HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
to the declared allowlist; a cache-correct response with a mismatched
`Content-Type` still fails the hosting gate.
`corepack pnpm verify:hosting-headers` uses a deterministic fixture locally.
Set `HOSTING_BASE_URL` to probe deployed responses; production promotion
requires the artifact to report `mode: "live"`. The live target must be its
canonical, non-loopback HTTPS root URL. Each required surface must return HTTP
200 without leaving that origin before its cache, content-type, and security
headers can count as deployment evidence.
`corepack pnpm verify:hosting-headers` compares the declared headers with a
deterministic fixture when `HOSTING_BASE_URL` is unset. That only shows the
declarations agree with each other, so its result is `UNVERIFIED` (exit 3), not
`PASS` (review 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). Only
`mode: "live"` can pass. The live target must be its canonical, non-loopback
HTTPS root URL. Each required surface must return HTTP 200 without leaving that
origin before its cache, content-type, and security headers can count as
deployment evidence. The hashed asset it requests is the entry script named by
the served `index.html`, so it checks the release that is actually deployed.
FE-GATE-019 is therefore a production-stage gate (`production_gate` job,
`PROD_PROMOTION_READY`). It runs after `promotion` and after the project has
deployed the promoted release. This repository's workflow stops at promotion:
uploading the release, switching the active pointer, and the post-switch smoke
are the project's provider adapter, chosen with the hosting provider.
Keep a retired release's hashed assets reachable while any open tab may still
request them. The minimum is the previous release while the next one is
active (the rolling window modeled in `tests/release/release-fixture.ts`).
Size it to the longest session the product supports; a tab older than that
depends on the reload-once recovery (FE-RB-002).
## Service Worker steps (only when the static selection is not `null`)
The worker is part of the release tuple: `service-worker.js` comes from the
same build as the HTML and assets it caches.
1. **Rollback N+1 → N.** Switching the tuple serves N's `service-worker.js`.
The browser's update check installs it; the worker never calls
`skipWaiting()` on install (`src/adapters/service-worker/service-worker-entry.ts`),
so it waits until every tab of the scope closes or a page calls
`requestActivation()`. The template has no page that calls it. The cache
name is the asset-set digest, so if N's cache is still there as the
retained previous cache, the install reuses it and never deletes it on
failure (`service-worker-static-assets.ts` `installStaticAssets`). Tabs still on N+1 keep worker N+1, so N+1's assets
stay reachable for the rolling window above.
2. **Turn the worker off without a rebuild.** Set
`CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` in the runtime config. The
next boot unregisters the owned registration and registers nothing; owned
caches stay (`src/contracts/runtime-capabilities.ts`
`resolveRuntimeCapabilities`, `service-worker-page-controller.ts` `start()`).
This needs a page that boots.
3. **A worker stops the page from booting.** Deploy a release whose static
selection is `REMOVE_REGISTRATION`. It ships a self-unregistering
`service-worker.js` (`scripts/build-frontend.ts`,
`scripts/lib/self-unregistering-service-worker.ts`): the update check
installs it over the broken worker, it skips waiting, unregisters on
activation and answers no fetch. The next load is uncontrolled
(`tests/e2e/service-worker-recovery.spec.ts`). Runbook:
`docs/operations/browser-file-storage-recovery.md` §8.
4. **Removing the worker** takes three releases:
`REMOVE_REGISTRATION` → `PURGE_OWNED_RESOURCES` (deletes owned caches) →
`null` (`src/contracts/service-worker.ts` `InstalledServiceWorkerSelection`).
@@ -8,7 +8,7 @@ Plan bundle: `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/`. One
| 2 | Composition does not contain known quadratic accumulation patterns. | 완료 | `src/platform/cardinality/compose-unique-record.ts`; `tests/platform/cardinality/compose-unique-record.test.ts`; `tests/platform/cardinality/extreme-scale-registry.test.ts`; growth gate `scripts/scale/run-composition-scale.ts` + `src/platform/cardinality/growth-regression.ts` (`tests/scale/composition-scale.test.ts`, `tests/scale/growth-regression.test.ts`, artifact `artifacts/scale/main/composition-s0-s2.json`); stored-baseline gate `pnpm check:scale:baseline` (`config/scale/benchmark-baseline.json`) |
| 3 | Membership checks on scale-sensitive paths use appropriate indexed structures. | 완료 | `src/contracts/product-features.ts` (`Set` membership); `tests/unit/product-features.test.ts`; `tests/features/product-features-scale.test.ts`; 100k selection/resolution in `tests/platform/cardinality/extreme-scale-registry.test.ts`; workloads `product-feature-selection`/`product-feature-resolution` in `scripts/scale/composition-workloads.ts` |
| 4 | Concrete imports across unrelated features fail architecture checks. | 완료 | `.dependency-cruiser.json` rules `features-do-not-import-other-features`, `contexts-do-not-import-other-contexts`; rejected fixtures `tests/fixtures/architecture/dependency-graph/cross-boundary/`; assertions in `scripts/check-architecture.ts`; `pnpm check:architecture` |
| 5 | Context/app cardinality ceilings are explicit and testable. | 완료 | `src/platform/cardinality/cardinality-budget.ts`; `src/contexts/bounded-context-module.ts`; `src/apps/deployable-app-module.ts`; `tests/architecture/topology-cardinality.test.ts`; `tests/architecture/module-hierarchy.test.ts`; `tests/platform/cardinality/cardinality-budget.test.ts` |
| 5 | Context/app cardinality ceilings are explicit and testable. | 완료 | `src/platform/cardinality/cardinality-budget.ts`; `src/contexts/bounded-context-module.ts`; `src/apps/deployable-app-module.ts`; `tests/architecture/topology-cardinality.test.ts`; `tests/architecture/module-hierarchy.test.ts`; `tests/platform/cardinality/cardinality-budget.test.ts`. The ceilings are declared limits, not a measured capacity: see "Growth inside one app" below (11-04) |
| 6 | An unchanged local app does not grow materially when global logical topology grows toward S3/S4 fixtures. | 완료 | (1) Ownership source: `src/apps/template-app/app-module.ts`, `src/contexts/reference-context/context-module.ts`, `FEATURE_CONTEXT_ID`. (2) Production projection: `scripts/generate-product-feature-index.ts` selects one app (`--app=`/`PRODUCT_APP_ID`) → `src/.generated/{product-feature-index,product-context-index,product-app}.ts` → `src/apps/template-app.ts`. (3) S0→S4 invariant: `tests/scale/global-local-independence.test.ts` — S0/S1/S2 real on-disk repos through the generator command (identical generated files, sha256 and reachable source graph); S0→S4 through the same `selectAppIndexes` (identical feature/context ids, route roots, generated files, hashes and compile-input paths; only App A's declarations read at 1M), pinned to the filesystem source by an equivalence test. (4) Build-input gate: `scripts/check-app-build-input.ts` (`pnpm check:app-build-input`, and `check:app-build-input:bundle` on the fresh production bundle), negative fixtures in `tests/architecture/app-build-input.test.ts` |
| 7 | Initial routing is hierarchical/lazy rather than a product-wide flat feature table. | 완료 | `src/platform/routing/context-route-module.ts`; `src/presentation/routes/app-router.tsx` (`ContextRouteGateway`); `tests/platform/routing/context-route-module.test.ts`; `tests/architecture/context-lazy-loading.test.ts`; `tests/features/reference-feature/installed-context-routing.test.ts` |
| 8 | User interactions carry bounded request, retry, concurrency, cancellation, and deadline semantics. | 완료 | `src/platform/execution/execution-context.ts`; `src/platform/traffic/{request-budget,concurrency-budget,traffic-budget}.ts`; `src/platform/resilience/{retry-budget,deadline}.ts`; enforcement in `src/adapters/http/http-execution-v3.ts`; operation policy `HttpExecutionPolicy.traffic` (`src/contracts/external-contract-runtime.ts`); `tests/platform/traffic/http-budget-integration.test.ts`; `tests/platform/traffic/traffic-amplification.test.ts`; `pnpm check:traffic` |
@@ -20,10 +20,34 @@ Plan bundle: `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/`. One
| 14 | Telemetry failure does not fail business behavior. | 완료 | `tests/platform/telemetry/telemetry-pipeline.test.ts` (transport throw/reject); `tests/platform/telemetry/telemetry-port.test.ts` (`failOpenTelemetryPort`); `tests/features/reference-feature/reference-telemetry.test.ts`; collector outage in `tests/scale/telemetry/telemetry-storm.test.ts` |
| 15 | Failure boundaries prevent one feature/context from unnecessarily collapsing unrelated UI. | 완료 | `src/platform/errors/{scoped-error-boundary,feature-error-boundary,context-error-boundary}.tsx`; wiring in `src/presentation/routes/app-router.tsx`; `tests/platform/errors/failure-boundary.test.tsx` |
| 16 | Spike and sustained-load tests detect request, retry, telemetry, and memory amplification. | 완료 | `tests/scale/traffic/*`, `tests/scale/telemetry/telemetry-storm.test.ts`, `tests/scale/session/*`; real Chromium soak `scripts/scale/browser-soak.ts` against the fresh build with telemetry on and a 503 API: 2,012 cycles, heap/listeners/timers/storage stable, 0 in-flight at end, 1.43 API requests per reference visit (≤ 3), telemetry ≤ 14 posts/min (≤ 40), checks in `artifacts/scale/nightly/browser-soak.json`; evaluator tests `tests/scale/browser-soak.contract.test.ts`; skipped ⇒ tier `incomplete` (non-zero). Platform telemetry adapter now send-rate limited (`src/adapters/telemetry/best-effort-telemetry.ts`, tests in `tests/unit/telemetry.test.ts`) |
| 17 | Multi-replica release tests verify fail-closed coherence and old-asset reachability. | 완료 | `src/platform/release/release-coherence.ts` (delegated to by `src/bootstrap/load-runtime-config.ts`, `src/bootstrap/load-release-manifest.ts`); `src/platform/release/release-mismatch-recovery.ts` + `src/bootstrap/boot-release-recovery.ts`; `tests/platform/release/*.test.ts`; `tests/release/{old-asset-reachability,mixed-replica,release-matrix}.test.ts`; `pnpm check:release-coherence` |
| 17 | Multi-replica release tests verify fail-closed coherence and old-asset reachability. | 완료 | `src/platform/release/release-coherence.ts` (delegated to by `src/bootstrap/load-runtime-config.ts`, `src/bootstrap/load-release-manifest.ts`); `src/platform/release/release-mismatch-recovery.ts` + `src/bootstrap/boot-release-recovery.ts`; `tests/platform/release/*.test.ts`; `tests/release/{mixed-replica,release-matrix}.test.ts`; `pnpm check:release-coherence`. Old-asset reachability is a hosting provider duty (`docs/operations/release-cache-rollback.md`); `tests/release/old-asset-reachability.test.ts` checks only the in-memory hosting fixture against `config/hosting/cache-policy.json`. An old tab of the default build (no Service Worker) whose chunk is gone after a deploy is checked in real browsers by `tests/e2e/old-tab-chunk-recovery.spec.ts`: one reload into the new build, no second reload (11-05) |
Overall: **완료** — every spec §54 criterion is `완료`.
## Growth inside one app (11-04)
The rows above show that one app does not change when the *global* topology grows. What one app costs as its *own* feature count grows is measured separately, with copies of the real reference feature: `scripts/scale/measure-feature-shape-growth.ts` copies `src/features/reference-feature` N times with every feature-owned identifier renamed (feature id, routes, operations, schemas, query namespace, invalidation topic, messages), into contexts of 200 features each, and proves that the copies compose (the registries throw at module evaluation on any duplicate). The baseline is `config/scale/feature-shape-growth.json`, re-created with `node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100 --repeats=2 --write` and checked by `tests/unit/feature-shape-growth.test.ts`.
Measured 2026-09-27, two runs per size, Intel i5-10400F (12 logical CPUs), Node 24.14.0, TypeScript 7.0.2, Vite 8.1.5. Load average 25–30 during the runs (other agents were building in parallel), so wall times are upper bounds; counts and bytes are identical in both runs.
| Added features | Routes | tsc instantiations | tsc memory | tsc wall (run 1 / 2) | vite build wall | Initial JS files / gzip | Lazy JS files / gzip |
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 0 | 10 | 712,089 | 0.5 GB | 3.4 s / 3.9 s | 1.2 s / 1.5 s | 13 / 200,001 B | 14 / 24,938 B |
| 25 | 110 | 3,579,093 | 1.4 GB | 8.1 s / 8.7 s | 1.7 s / 2.1 s | 39 / 274,493 B | 165 / 171,638 B |
| 100 | 410 | 12,157,304 | 4.2 GB | 31.3 s / 43.2 s | 6.0 s / 3.7 s | 114 / 490,658 B | 615 / 704,938 B |
What this means for the declared ceilings (`CONTEXT_MAX_FEATURES = 200`, `src/contexts/reference-context/context-module.ts:10`; `APP_MAX_CONTEXTS = 20`, `src/apps/template-app/app-module.ts:7`). The table below is a copy of `config/scale/feature-shape-ceilings.json`, which `tests/unit/feature-shape-growth.test.ts` checks against the baseline path and both constants; this document may be deleted after copying the template, the JSON file may not:
| Growth axis | Verified | Condition | Not verified |
| --- | --- | --- | --- |
| Typecheck of one app | Linear, about 115k instantiations and 37 MB of tsc memory per feature, up to 100 features | Reference-shaped features, `tsconfig.app.json`, the host above | 200 features (one full context) and beyond; 4,000 (20 × 200) would need on the order of 150 GB by the same slope |
| Production build | Completes at 100 features in seconds | Same | Beyond 100 |
| Initial JavaScript | Grows by about 2.9 KB gzip and one file per feature: every installed feature's contracts and module load at boot | Same | — the initial budget (204,800 B, `config/performance/budgets.json`) (about 196.5 KB used by `check:bundle`) is exceeded after about three more reference-shaped features, far below the context ceiling |
| Lazy JavaScript | About 6.8 KB gzip and six files per feature, every file far below the 120 KiB lazy-chunk budget | Same | Download cost of many lazy files |
| Routes | 4 per feature, composed without conflict | Same | Router matching cost at runtime |
So the ceilings bound the *count*; they are not a verified capacity. The practical limit of one app today is the initial JavaScript budget, then typecheck memory. 400 features were not measured (D-18 makes it optional; at the observed slope a run needs about 16 GB of tsc memory).
## Executable evidence (supported runtime)
Re-run on Node **v24.11.0** / pnpm 11.17.0 inside the `workmachine` container (whose default Node v22.23.2 is below `engines.node`):
@@ -0,0 +1,340 @@
# browser-transfer 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/adapters/browser-transfer/` 전체 27파일 약 12.4k줄(`resumable-upload/` 13, `presigned/` 6, `image-cdn/` 7, 배럴 1), 이 영역이 구현하는 port `src/application/ports/browser-transfer/*`(766줄), 영역 단위 테스트 14파일
> 영역 판정(35.8): **조건부 사용 가능** — 기본 production 구성에는 조립돼 있지 않다(`AVAILABLE_NOT_COMPOSED`). 다운스트림이 조립할 때 01-01~01-05의 조건을 관리해야 한다.
## 1. 결론
- **막혀 있는 것.** presigned capability는 URL이 아닌 1회용 식별 handle이고 HTTPS·redirect 금지·자격증명 제외·경로 이중 인코딩 차단이 걸려 있다. 재시도는 runtime 한 계층에만 있다. dispose·fail-fast·ABORT_PENDING·complete 결과 불명 조정이 구현돼 있고 테스트가 잡는다. 직전 리뷰 6.1-1~6.1-11은 모두 현재 코드에 반영돼 있다.
- **고칠 것(Medium, P2).** object store PUT이 401/403을 돌려주거나 실행기가 capability 만료를 판정하면 capability를 다시 받지 않는다. 그 대신 `upload()` 전체가 `PERMISSION_DENIED`/`EXPIRED_RESOURCE`, `retryable:false`로 끝난다. 설계 문서 3.2·4.2절과 반대다(01-01).
- **결과 불명(29.2).** complete 응답을 잃으면 `UNAVAILABLE/RESUME` 실패가 되고 checkpoint는 남는다. 같은 파일로 `upload()`를 다시 부르면 서버 상태로 조정된다. 하지만 그 밖에는 상태를 볼 방법이 없다. `abort()`를 부르면 `ALREADY_COMPLETED`만 돌려받고, resourceId와 checkpoint를 함께 잃는다(01-02).
- **검증 공백.** 이 조정을 받치는 규칙은 "재시도·재개 때 같은 idempotency key를 쓴다"이다. 그런데 이 규칙을 고정한 테스트가 없다. key를 시도마다 바꾸는 변형을 넣어도 168개 테스트가 모두 통과했다(01-04).
- **시간 제한이 바이트 수와 무관하다.** part 전송 한 번의 제한 시간은 기본 30초, part 크기는 기본 5MiB다. 업링크가 약 1.4Mbit/s보다 느리면 업로드가 전혀 진행되지 않는다. download는 본문 전체에 deadline이 하나뿐이다(01-03). 또 호출자가 실패의 `recovery` 값만 보고 할 일을 고를 수 없다(01-05).
- **미검증.** 실제 브라우저 스펙 3개(Playwright), 실제 object store·BFF의 403/재발급/complete 소요 시간, part 버퍼 메모리 실측은 확인하지 않았다.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 | `src/adapters/browser-transfer/**`, `src/application/ports/browser-transfer/**`, 영역을 쓰는 kernel(`src/adapters/platform/abortable-operation.ts`, `indexeddb-connection.ts`) |
| 커밋·상태 | `main` `4626b73`. 주 워킹트리에서 수정한 파일 없음 |
| 읽은 코드 | resumable-upload 13파일 전부(runtime·정책·검증·checkpoint store·lock·취소 채널·HTTP control plane·fetch 전송·part 실행기), presigned 6파일 전부, image-cdn은 runtime·probe 요지·정책 상한·README |
| 읽은 문서(주장으로만 사용) | `docs/architecture/presigned-transfer-and-image-cdn.md`, `server-file-capability-infrastructure.md` 8·10절, `browser-data-capability-completion-ledger.md` 4.4, `SPEC.md`, `tasks/todo.md`, 직전 리뷰 6.1 |
| 실행한 테스트 | `node scripts/run-vitest.ts run` + 영역 단위 테스트 14파일(image-cdn 3, presigned 4, resumable 6, 취소 채널 1) → **14 files / 199 tests 통과** |
| 실험(분리 worktree) | `git worktree add --detach <scratchpad>/01/wt HEAD`로 분리했다. 끝난 뒤 제거했다. 사용한 파일: 실험 테스트 `zz-area01-experiments.test.ts`(scratchpad 보관), 변형 스크립트 `mutate.sh` |
| 실험 X1 | 첫 PUT만 403과 같은 실패(`PERMISSION_DENIED, retryable:false, REISSUE_CAPABILITY`)를 내고 둘째는 성공하는 실행기를 붙였다. 결과: `upload()` → `{code:PERMISSION_DENIED, operation:UPLOAD_PART, retryable:false, recovery:REISSUE_CAPABILITY}`. PUT 1회, 발급 1회 |
| 실험 X2 | complete가 서버에는 반영되지만 응답은 timeout과 같은 실패를 낸다. 결과: `upload()` → `UNAVAILABLE/UPLOAD_COMPLETE/retryable:true/RESUME`. 이어서 `abort()` → `{state:"ALREADY_COMPLETED"}`, checkpoint 0행 |
| 실험 X3 | 기본 attempt 제한 30초 조건에서 PUT에 42초(5MiB를 1Mbit/s로 보내는 시간)가 걸리게 했다. 결과: PUT 4번 시작, `UNAVAILABLE/UPLOAD_PART/retryable:true/RESUME` |
| 변형 검출 | 아래 표. 대상은 resumable·presigned 테스트 11파일 168개 |
| SHA-256 대조 | `presigned/incremental-sha256.ts`와 `node:crypto`를 0~299바이트, 블록 경계, 1MiB+1 입력으로 대조했다. 무작위 chunk 분할을 포함해 1,830건 비교, 불일치 0건 |
| 확인하지 못한 범위 | Playwright 스펙(`tests/browser-capabilities/resumable-upload.spec.ts`, `presigned-streaming.spec.ts`, `image-cdn.spec.ts`): 브라우저 실행이 필요하다. `test:browser-file-storage-removal`: `.tmp`에 fixture를 만들고 pnpm을 실행하는 무거운 스크립트라 동시 작업 중에 돌리지 않았다. `check:architecture`·`check:types`: 오케스트레이터 담당 |
| 직전 리뷰와 비교 | 6.1-1~11을 현재 코드에서 다시 확인했다. 모두 반영돼 있다(아래 표) |
**변형 검출 결과** (코드 한 곳을 일부러 틀리게 바꾸고 테스트가 실패하는지 본 것)
| ID | 바꾼 것 | 결과 |
| --- | --- | --- |
| M1 | PART/COMPLETE/ABORT idempotency key에 호출마다 난수 추가 (`upload-byte-source.ts:301`) | **168 통과 — 검출 못 함** |
| M6 | complete key를 재시도 시도마다 바꿈 (`resumable-upload-runtime.ts:1070`) | **168 통과 — 검출 못 함** |
| M7 | create key를 재시도 시도마다 바꿈 (`resumable-upload-runtime.ts:649`) | **168 통과 — 검출 못 함** |
| M2 | worker 실패 시 형제 abort 제거 (`:772`) | 1 실패 — 검출 |
| M3 | abort에서 `ABORT_PENDING` 기록 생략 (`:1135`) | 1 실패 — 검출 |
| M4 | status `QUARANTINED` 조정 제거 (`:560`) | 1 실패 — 검출 |
| M5 | provider 실패 재시도 금지 (`:1397`) | 2 실패 — 검출 |
**직전 리뷰 6.1 재확인**: 6.1-1 `drain = null` 재시도(`resumable-upload-runtime.ts:294-302`), 6.1-2 `SAFE_TRANSFER_ID`가 `SAFE_OPAQUE_ID`의 상위 집합(`checkpoint-schema.ts:15-22`), 6.1-3 `partSize×maxConcurrency×copyFactor` 검증과 기본 동시성 1(`runtime-policy.ts:52-55, 89-92`), 6.1-4 `LIMIT_EXCEEDED`(`resumable-upload-runtime.ts:341-348`), 6.1-5 fail-fast(`:758-773`), 6.1-6 `removeUnreadable`(`:1115-1129`), 6.1-7 fit 제한(`image-cdn-policy.ts:492-495`), 6.1-8 `imageOrientation:"none"`(`browser-image-probe.ts:60`), 6.1-9 `presigned/http-common.ts` 통합·엄격 Content-Length·kernel attempt, 6.1-10 runtime 2298→1629줄, 6.1-11 vault snapshot만 읽음(`presigned-capability-vault.ts:278-287`). 모두 반영.
### 2.1 대표 호출 추적 — complete 응답을 잃은 경우 (29.2)
```text
upload(request)
→ 파일 전체 읽기 + part별 SHA-256 (manifest) resumable-upload-runtime.ts:349
→ checkpoint 읽기 → getStatus(ACTIVE) → 빠진 part PUT :371, :394, :406
→ complete(같은 COMPLETE key) ── 서버 반영, 응답 유실(30초 timeout)
→ 같은 key로 최대 3번 더 → 모두 timeout :1059-1074
← { UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME } checkpoint(ACTIVE, 모든 part 수락) 남음
경로 A: 같은 파일로 upload() 다시 → 파일 전체 재해시 → getStatus = QUARANTINED
→ checkpoint 삭제 → { QUARANTINED, resourceId, replayed:true } :560-577
경로 B: 사용자가 취소 → abort() → ABORT_PENDING 기록 → 서버 abort = ALREADY_COMPLETED
→ checkpoint 삭제 → { state: ALREADY_COMPLETED } (resourceId 없음) :1204-1216
```
경로 A는 동작하고 테스트도 있다(`tests/unit/resumable-upload-runtime.test.ts:990`). 경로 B는 실험 X2로 확인했다.
### 2.2 29.4 문장 — `ResumableUploadRuntime.upload()`
> 이 호출은 **서버 control plane**에 upload session을 만들고(요청 binding에서 유도한 고정 `CREATE` key), part마다 **object store**에 presigned PUT으로 bytes를 쓰고, complete로 서버에 `QUARANTINED` 자원을 만든다. 그리고 **브라우저 IndexedDB**(계정 partition DB)에 checkpoint 행을 쓰고, 성공하면 지운다.
> **기다리는 시간**: 호출 전체 deadline은 없고 caller signal이 유일한 상한이다. 외부 호출 한 번은 `providerAttemptTimeoutMs`(기본 30초) 안에 끝나야 한다. fetch 전송 자체도 30초, presigned 실행기는 composition이 준 `timeoutMs`를 쓴다. 같은 uploadKey의 Web Lock 대기에는 상한이 없다.
> **재시도**: runtime 한 계층에서만, `retryable:true` 실패에 대해 최대 `maxRetries`(기본 3)번 한다. 간격은 250ms~5s 지수 backoff에 jitter를 섞고, 30초 이하의 `Retry-After`를 따른다. 재시도에는 같은 idempotency key를 쓴다. PUT의 401/403과 실행기의 만료 판정은 재시도하지 않는다(01-01).
> **동시 실행**: 같은 uploadKey는 Web Lock으로 한 번에 하나만 실행하고, checkpoint는 revision 비교(CAS)로 갱신한다. 다른 탭에서 abort하면 BroadcastChannel로 진행 중 작업을 끊는다.
> **응답을 잃으면**: `UNAVAILABLE/RESUME` 실패를 반환한다. 모든 part가 수락된 ACTIVE checkpoint가 남는다.
> **확인·조정**: 같은 파일로 `upload()`를 다시 부르는 방법뿐이다. 그러면 전체 파일을 다시 해시한 뒤 `getStatus`로 조정한다. 파일 없이 상태를 조회하는 API는 없다. `abort()`는 resourceId 없이 `ALREADY_COMPLETED`를 준다(01-02).
## 3. 확인된 강점
1. **presigned capability가 새지 않는다.** 등록 객체를 한 번만 복사해 검증한다. handle은 WeakMap identity로 관리하고, 1회 claim 뒤 consume한다. HTTPS만 허용하고 ambient 자격증명 헤더를 금지한다(`presigned-capability-vault.ts:167-330`). 데이터 요청은 `credentials:"omit"`, `redirect:"error"`, `no-referrer`, 응답 URL 정확 일치를 쓴다(`presigned-transfer-executor.ts:343-363, 1011-1021`). 경로 퍼센트 인코딩 재해석도 막는다(`presigned-capability-http-provider.ts:991-1036`). checkpoint에는 정확한 key 목록만 저장할 수 있어 URL·자격증명이 들어갈 수 없다(`checkpoint-schema.ts:29-143`, 테스트 `resumable-upload-checkpoint.test.ts:295`).
2. **재시도 중첩이 없다.** fetch 전송(`fetch-json-transport.ts:144-276`), 발급 provider, presigned 실행기는 재시도하지 않는다. 재시도는 runtime의 `callWithRetry`/`uploadPartWithRetry`만 하며 상한·jitter·`Retry-After` 상한이 있다(`resumable-upload-runtime.ts:1235-1404`). idempotency key는 요청 binding과 session·part에서 결정적으로 만들어진다(`upload-byte-source.ts:289-326`).
3. **결과 불명인 complete·abort를 버리지 않는다.** 모든 part가 수락된 checkpoint를 남기고, 다음 호출에서 서버 상태로 조정한다(`resumable-upload-runtime.ts:560-577`). abort는 먼저 `ABORT_PENDING`을 기록하고, 서버 확인 뒤에만 지운다(`:1135-1151`). 둘 다 테스트가 있고 변형 M3·M4를 잡았다.
4. **수명과 동시성.** worker 하나가 실패하면 형제를 즉시 끊는다(`:758-773`, M2 검출). receipt 저장은 한 줄로 직렬화하고 revision CAS를 쓴다(`:708-750`). `dispose()`는 wrapper뿐 아니라 실제 provider 작업까지 기다리고, 시간 초과로 실패하면 나중에 다시 부를 수 있다(`:279-332`, 테스트 `resumable-upload-runtime-teardown.test.ts:191`).
5. **메모리 상한을 시작 전에 검사한다.** `partSize × maxConcurrency × copyFactor ≤ maxInFlightBytes`(`runtime-policy.ts:89-92`)를 본다. JSON 응답·발급 응답·업로드 응답 본문을 hard cap 안에서 읽는다(`fetch-json-transport.ts:413-517`, `presigned-capability-http-provider.ts:761-813`, `presigned-transfer-executor.ts:876-933`). download chunk는 `hardMaxChunkBytes`로 다시 자르고, 직접 구현한 SHA-256으로 스트리밍 검증한다(대조 1,830건 일치).
6. **계정 범위와 삭제.** checkpoint DB 이름은 opaque scope token 3개를 길이 접두어로 묶고, 열 때 governance 행으로 scope를 대조한다(`indexeddb-checkpoint-store.ts:172-182, 565-599`). `deletePartition()`은 연결을 닫고 삭제를 보낸다. 삭제 요청이 막히면 성공인 척하지 않고 `PENDING/UNKNOWN`으로 보고한다(`:457-507`).
## 4. 발견 사항 (36.3)
### 01-01 object store PUT의 401/403과 실행기의 만료 판정이 capability 재발급 없이 `upload()` 전체 실패로 끝난다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(설계 문서의 계약과 구현 불일치) |
| 관련 관점 | 6, 5, 17, 24 |
| 근거 | PUT 응답 401/403은 `PERMISSION_DENIED, retryable:false, recovery:REISSUE_CAPABILITY`가 된다(`presigned/http-common.ts:141-143`). 실행기가 잔여 수명 부족을 판정하면 `EXPIRED_RESOURCE, retryable:false`다(`presigned-transfer-executor.ts:990-996`). part 실행기는 이 값을 그대로 넘긴다(`resumable-upload/presigned-upload-part-executor.ts:105`). runtime은 `retryable`만 보고 바로 반환한다(`resumable-upload-runtime.ts:1017-1020`). 같은 루프는 시도마다 capability를 새로 발급한다(`:938-954`). 따라서 재시도만 허용하면 재발급이 된다. 지금은 runtime이 스스로 만료를 판정한 경우만 재발급한다(`:968-980`). 문서는 반대로 말한다. `presigned-transfer-and-image-cdn.md:167` "만료/403은 … control plane의 새 capability 발급으로 복구한다", `:263` "만료/authorization failure는 최대 정책 범위 안에서 capability를 재발급한다". 실험 X1에서 재현했다 |
| 발생 조건 | presigned URL이 표기된 만료보다 먼저 무효가 되는 경우(서명에 쓴 임시 자격증명 만료 — 문서 3.1이 인정). 기기 시계와 object store 시계가 다른 경우. 실행기 `minimumRemainingLifetimeMs`가 runtime `capabilityRefreshSkewMs`(기본 5초)보다 큰 조합. 두 값은 서로 검사하지 않는다 |
| 영향 | part 하나의 일시적 403으로 파일 업로드가 끝난다. 호출자는 "권한 없음"으로 읽히는 코드를 `retryable:false`로 받아 자동 재개하지 않는다. checkpoint는 남으므로 `upload()`를 다시 부르면 이어진다. 데이터 손상은 없다 |
| 심각도·우선순위 | Medium · P2 — 흔한 운영 조건에서 사용자 흐름이 끊기지만 재호출로 복구되고 데이터 피해는 없다. 조립하는 다운스트림에 그대로 복제된다 |
| 통제·증거 | M1(문서만 있고 구현이 반대) · E2(실험 X1). 관련 테스트 없음 |
| 확실성과 남은 가정 | 코드 경로와 실험으로 확인했다. 실제 S3/GCS가 어떤 조건에서 403을 내는지는 이 repo 밖이다 |
| 최소 개선 방향 | `uploadPartWithRetry`에서 PUT 단계의 `recovery === "REISSUE_CAPABILITY"` 실패(401/403/만료)를 `maxRetries` 안에서 재시도 대상으로 본다. 다음 시도가 새 capability를 받는다. BFF 발급 단계의 401/403은 지금처럼 멈춘다 |
| 비용·부작용 | 몇 줄. 진짜 권한 박탈이면 발급 요청이 최대 `maxRetries`번 더 나간다(상한 있음) |
| 완료 기준 | 첫 PUT 403, 둘째 성공이면 `upload()`가 성공하고 발급이 2회 일어난다. 발급 endpoint의 403은 재시도 없이 실패한다 |
| 검증 방법 | 실험 X1을 단위 테스트로 옮긴다. 실제 `createPresignedTransferExecutor`에 403을 주는 fetch fake를 붙인 조합으로 한 번 더 확인한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-02 완료됐거나 완료 여부를 모르는 업로드가 일반 실패로 보고되고, resourceId를 되찾는 길이 "같은 파일로 `upload()` 재실행"뿐이다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(한 경로는 확인된 결함) |
| 관련 관점 | 6, 5, 17, 28, 11 |
| 근거 | ① complete 응답 유실: 전송 timeout은 `UNAVAILABLE, retryable:true, RESUME`이다(`fetch-json-transport.ts:586-593`). runtime은 같은 key로 재시도한 뒤 그대로 반환한다(`resumable-upload-runtime.ts:1059-1074`). 실패 타입에는 "결과 불명" 값이 없다(`application/ports/browser-file-storage/shared.ts:8-27, 67-80`). 문서 실패표도 네트워크 오류와 합친다(`presigned-transfer-and-image-cdn.md:632`). ② **확인된 결함**: 서버가 resourceId를 이미 돌려줬는데도 로컬 checkpoint 삭제가 실패하면 실패를 반환하고 resourceId를 버린다(`resumable-upload-runtime.ts:1098-1103`). complete 직후 caller signal이 abort되면 삭제가 `ABORTED`로 끝나 같은 결과가 된다. ③ `abort()`는 서버가 `ALREADY_COMPLETED`를 주면 checkpoint를 지우고 state만 반환한다(`:1204-1216`). 반환 타입 `UploadAbortOutcome`에 resourceId가 없다(`application/ports/browser-transfer/resumable-upload.ts:93-95`). 실험 X2로 확인했다. ④ port에 상태 조회 메서드가 없다(`resumable-upload.ts:97-105`). 조정은 `upload()`가 파일 전체를 다시 읽고 해시한 뒤(`resumable-upload-runtime.ts:349-359`) `getStatus`로만 한다. ⑤ 서버 complete가 30초를 넘기는 경우를 표현할 수단이 없다. status 계약에 "완료 중" 상태가 없다(`resumable-upload.ts:138-150`). 서버 문서가 정의한 `OPERATION_IN_PROGRESS`(`server-file-capability-infrastructure.md:897, 1125`)에도 wire 표현과 클라이언트 처리가 없다. 409로 오면 `CONFLICT, retryable:false`가 된다(`fetch-json-transport.ts:534-536`) |
| 발생 조건 | 큰 파일의 complete가 30초를 넘김(서버가 최종 길이·digest를 검증). 모바일에서 연결이 끊김. complete 직후 사용자 취소(signal abort와 `abort()`를 함께 부르는 흔한 취소 구현). IndexedDB 일시 실패 |
| 영향 | 앱은 실패를 보여 준다. 다시 시도하면 파일 전체를 재해시한 뒤 `replayed:true`로 성공한다(5GiB면 수 분). 취소하면 서버에는 `QUARANTINED` 자원이 남고, 클라이언트는 그 ID를 알 방법이 없다. 업무 레코드에 연결되지 않은 고아 자원이 생긴다. 같은 파일을 다시 올리면 서버 idempotency 보관 기간에 따라 중복 자원이 생길 수 있다 |
| 심각도·우선순위 | Medium · P2 — 부작용 중복 실행은 같은 key로 막혀 있어 High 조건(무방비 재실행)은 아니다. 피해는 고아 자원과 거짓 실패 표시다 |
| 통제·증거 | 재개 경로 M2 · E2(테스트 `resumable-upload-runtime.test.ts:990`). 손실 경로 M0(통제 없음 확인) · E2(실험 X2) |
| 확실성과 남은 가정 | ②·③은 코드와 실험으로 확정했다. ⑤의 서버 응답 코드는 서버 구현에 달려 있어 미확인이다 |
| 최소 개선 방향 | (1) complete가 성공한 뒤의 로컬 정리 실패는 성공으로 반환하고, 정리는 다음 호출에 맡긴다. (2) abort 결과가 `ALREADY_COMPLETED`이면 checkpoint를 지우기 전에 `getStatus`로 resourceId를 읽어 함께 반환한다. (3) 서버 계약에 complete 진행 중 상태(status 값 또는 retryable 응답 코드)를 정한다. (4) 선택: 파일 없이 uploadKey로 상태를 확인하는 port 메서드를 추가한다(비파괴 추가) |
| 비용·부작용 | (1)(2)는 작다. (3)은 서버와 wire 변경이라 버전 관리가 필요하다. (4)는 port 추가 |
| 완료 기준 | X2 시나리오에서 `abort()` 결과로 resourceId를 알 수 있다. complete 성공 뒤 삭제 실패를 주입하면 `upload()`가 성공을 반환한다 |
| 검증 방법 | X2와 "complete 성공 + remove 실패" 주입 테스트. 실제 서버 conformance는 control-plane fake로 in-progress 응답을 흉내 낸다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-03 전송 시간 제한이 바이트 수나 진행과 무관한 고정 값이다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 14, 19 |
| 근거 | 기본 part 5MiB, `providerAttemptTimeoutMs` 30초다(`runtime-policy.ts:49, 64`). PUT 한 번(실행기 해시 포함)이 이 deadline 하나에 들어간다(`resumable-upload-runtime.ts:983-1001, 1308-1311`). 정책 검증은 part 크기와 제한 시간의 관계를 보지 않는다(`runtime-policy.ts:75-121`). 허용 최대치(64MiB part, 120초)끼리 짝지으면 4.5Mbit/s가 필요하다. 시간 초과 뒤 다음 시도는 같은 part를 처음부터 다시 보낸다. 실험 X3: PUT 4번 시작 후 `UNAVAILABLE/retryable:true`. download는 stream 시작부터 본문 끝까지 deadline이 하나이고, 진행이 있어도 연장되지 않는다(`presigned-transfer-executor.ts:543, 636-642`). 같은 `timeoutMs`를 PUT part와 전체 download가 함께 쓴다(`:60-78`) |
| 발생 조건 | 업링크가 약 1.4Mbit/s(5MiB/30초)보다 느림: 혼잡한 모바일, 약전계. download는 파일 크기를 `timeoutMs`로 나눈 속도보다 느린 경우 |
| 영향 | 업로드가 첫 미완료 part에서 멈춰 끝나지 않는다. `upload()`를 부를 때마다 part를 4번 보내고 버린다(기본 20MiB 낭비). `retryable:true`라 앱이 자동 재시도하면 이것이 반복된다. download는 큰 파일이 거의 끝날 무렵 실패할 수 있다 |
| 심각도·우선순위 | Medium · P2 — 해당 네트워크의 사용자에게는 기능이 동작하지 않는다. 기본값이 그대로 복제된다 |
| 통제·증거 | 처리량을 고려한 제한 M0(없음 확인) · E2(실험 X3) |
| 확실성과 남은 가정 | 산술과 실험으로 확인했다. 실제 사용자 업링크 분포는 미확인이다 |
| 최소 개선 방향 | attempt 제한을 "기본 시간 + part 바이트 / 최저 처리량"으로 계산하거나, 진행이 멈췄을 때만 끊는 idle timeout을 둔다. download는 idle 제한과 전체 상한을 분리한다. 정책 문서에 필요한 최저 처리량을 적는다 |
| 비용·부작용 | 작음~중간. idle timeout은 kernel(`src/adapters/platform/abortable-operation.ts`)에 없어서 kernel 확장이 필요하다 |
| 완료 기준 | 1Mbit/s 모의 환경에서 5MiB part가 성공한다. 진행이 멈춘 연결은 idle 제한 안에 끊긴다 |
| 검증 방법 | fake timer로 X3을 재현하는 테스트. download는 느린 chunk 스트림 fake |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-04 결과 불명 재시도의 핵심 규칙(같은 idempotency key 재사용)을 어떤 테스트도 고정하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(테스트 검출력) |
| 관련 관점 | 10, 6, 21 |
| 근거 | 변형 M1·M6·M7은 key를 호출마다 또는 시도마다 바꾸는 변형이다. resumable·presigned 11파일 168개 테스트가 모두 통과했다. 같은 조건에서 M2~M5는 잡혔다. key 관련 단언은 "새 session이면 key가 다르다"뿐이다(`tests/unit/resumable-upload-runtime.test.ts:441-444`). 다른 공백도 있다. PUT 403 경로(01-01) 테스트가 없다. runtime에 실제 provider·vault·실행기를 붙인 단위 테스트가 없다(단위 테스트는 fake harness `resumable-upload-runtime-fixture.ts`, 실제 조합은 Playwright 정상 경로 1개 `tests/browser-capabilities/resumable-upload.spec.ts:42`). 직접 구현한 SHA-256의 표준 벡터는 "abc" 1개다(`tests/unit/presigned-transfer.test.ts:31-35`). 나머지 기대값은 검사 대상 함수로 직접 계산한다(`tests/unit/presigned-transfer-fixture.ts:16` 등). 구현 자체는 대조 1,830건에서 맞았다 |
| 발생 조건 | key 유도를 리팩터링할 때(시도 번호 포함, 요청마다 UUID 등) |
| 영향 | 게이트를 통과한 채 "결과 불명 쓰기를 새 식별자로 재실행"(가이드 6절 위험 신호)이 들어갈 수 있다. 그러면 서버에 session·complete가 중복된다. 템플릿이라 다운스트림이 그대로 가져간다 |
| 심각도·우선순위 | Medium · P2 — 현재 코드는 옳다. 다만 회귀가 나면 High급 피해 경로가 열리는데 검출 수단이 없다 |
| 통제·증거 | 구현 M2, 자동 검출 없음 · E2(변형 실행) |
| 확실성과 남은 가정 | 변형 실행으로 확정했다. Playwright 스펙이 key를 단언하는지는 읽은 범위에서 없었다 |
| 최소 개선 방향 | 테스트 3개를 추가한다. (a) complete 첫 시도 timeout, 둘째 성공 → 두 호출의 key가 같다. (b) 첫 `upload()`에서 complete 응답 유실 → 둘째 `upload()`의 complete key가 같다(재개해도 유지). (c) part 재시도 사이 발급 key가 같다. 01-01 테스트도 추가한다. SHA-256은 2블록 NIST 벡터와 `node:crypto` 대조를 추가한다 |
| 비용·부작용 | 작음 |
| 완료 기준 | M1·M6·M7 변형이 각각 테스트 하나 이상을 실패시킨다 |
| 검증 방법 | `scratchpad/01/mutate.sh`와 같은 방식으로 변형을 다시 실행한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-05 실패의 `recovery` 값이 호출자가 할 수 있는 행동과 1:1로 이어지지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 5, 17, 24, 8 |
| 근거 | port에는 `upload()`와 `abort()`뿐이다(`resumable-upload.ts:97-105`). 그런데 `upload()`는 할 일이 서로 다른 여러 경우에 `RECONCILE`을 돌려준다. ABORT_PENDING이면 `abort()`를 불러야 한다(`resumable-upload-runtime.ts:388-392`). IndexedDB CAS 충돌이면 `upload()`를 다시 부르면 된다(`indexeddb-checkpoint-store.ts:372-381`). 서버 상태와 manifest가 다르면(`INTEGRITY_FAILED`) `abort()` 후 재시작해야 한다(`upload-response-validation.ts:96-115`). 읽을 수 없는 행(`CORRUPT_DATA`)이면 `abort()`를 불러야 한다(`indexeddb-checkpoint-store.ts:336-341`). 앞의 둘은 실패값이 완전히 같다: `{CONFLICT, UPLOAD_RECONCILE, retryable:false, RECONCILE}`. `REISSUE_CAPABILITY`는 호출자가 직접 할 수 없는 동작인데 `retryable:false`와 함께 온다(01-01). 서버가 정책 상한보다 긴 session을 주면 `EXPIRED_RESOURCE/RESTART`인데(`upload-response-validation.ts:229-240`, 테스트 `resumable-upload-runtime-contract.test.ts:254`), 재시작해도 같은 응답이 온다. recovery→행동 표는 문서에 없다(`presigned-transfer-and-image-cdn.md:619-632`는 code 기준 표) |
| 발생 조건 | abort가 서버 확인 전에 실패해 ABORT_PENDING이 남음. 다른 문맥이 checkpoint를 먼저 씀. 서버 응답과 정책 불일치 |
| 영향 | 다운스트림 UI는 recovery를 보고 버튼을 고르게 된다. ABORT_PENDING에서 "다시 시도"를 누르면 같은 실패가 반복된다. 반대로 `CONFLICT`에 `abort()`를 붙이면 CAS 충돌 상황에서 정상 진행 중인 업로드를 서버에서 중단시킬 수 있다 |
| 심각도·우선순위 | Medium · P2 — 막다른 UX와 잘못된 조치로 이어질 수 있다. 데이터 손상은 없다 |
| 통제·증거 | M1 부분(개별 주석) · E1 |
| 확실성과 남은 가정 | 정적 확인. 실제 CAS 충돌 빈도는 Web Lock 때문에 낮을 것으로 보이며 미측정 |
| 최소 개선 방향 | port 주석에 `upload()` 실패의 recovery→행동 표를 둔다(`upload()` 다시 / `abort()` 필요 / 다른 파일 또는 키 / 없음). ABORT_PENDING 실패는 operation을 `UPLOAD_ABORT`로 바꿔 구분한다(공유 enum 변경 없음). session 수명 초과는 `RESTART` 대신 재시작으로 풀리지 않는 값으로 둔다 |
| 비용·부작용 | 작음. recovery 값이 바뀌므로 기존 테스트 기대값이 바뀐다 |
| 완료 기준 | `upload()`의 실패 경로마다 recovery가 port에서 실행할 수 있는 행동 하나에 대응한다. ABORT_PENDING과 CAS 충돌의 실패값이 다르다 |
| 검증 방법 | 실패 경로별 표 테스트(each) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-06 서버가 준 만료 시각을 기기 시계로 여유 없이 비교한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 17, 19, 23 |
| 근거 | session: `expiresAt - now > maxSessionLifetimeMs`이면 `EXPIRED_RESOURCE/RESTART`이고, 재개 중이면 `INTEGRITY_FAILED`다(`upload-response-validation.ts:96-115, 229-240`). capability: `remaining > maxCapabilityTtlMs`이면 `POLICY_REJECTED`, `< minimumRemainingLifetimeMs`이면 `EXPIRED_RESOURCE`이고 둘 다 `retryable:false`다(`presigned-capability-http-provider.ts:532-550`). runtime(`upload-response-validation.ts:60-68`)과 실행기(`presigned-transfer-executor.ts:976-997`)도 같다. 같은 영역의 image-cdn은 `maxClockSkewMs`를 둔다(`image-cdn-policy.ts:55, 143`; `image-cdn-runtime.ts:305-307`) |
| 발생 조건 | 서버의 session·capability 수명이 클라이언트 상한과 같거나 가깝고 기기 시계가 서버보다 늦은 경우. 또는 기기 시계가 capability 수명보다 더 빠른 경우. 기본 `maxSessionLifetimeMs`는 24시간이라, 서버가 24시간 session을 주면 시계가 조금만 늦어도 걸린다. 브라우저 스펙의 조립값(5분 session, 10분 상한)에는 여유가 있다 |
| 영향 | 해당 기기에서는 업로드가 매번 실패한다. 오류가 `EXPIRED_RESOURCE/RESTART`나 `POLICY_REJECTED`라 시계 문제로 보이지 않는다 |
| 심각도·우선순위 | Low · P2 — 설정 여유에 달린 좁은 조건이다. 하지만 걸리면 그 사용자는 업로드를 못 하고 진단도 어렵다 |
| 통제·증거 | 시계 오차 허용 M0 · E1 |
| 확실성과 남은 가정 | 비교식은 확인했다. 실제 서버 수명 설정은 다운스트림에 달려 있다 |
| 최소 개선 방향 | upload·presigned 정책에 `maxClockSkewMs`를 두고 상한·하한 비교에 반영한다(image-cdn과 같은 이름). 문서에 "서버 수명 < 클라이언트 상한 − skew" 조건을 적는다 |
| 비용·부작용 | 작음 |
| 완료 기준 | 기기 시계 ±skew 안에서 session·capability가 거절되지 않는다 |
| 검증 방법 | `now`를 주입해 ±skew 경계 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-07 발급됐지만 쓰지 못한 upload capability를 vault에서 회수하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 12, 14, 22 |
| 근거 | vault는 `consume()`에서만 항목을 지우고, 만료 항목은 다음 `register()` 때만 정리한다(`presigned-capability-vault.ts:138-147, 277-287, 348-360`). `revoke()`(`:362-365`)를 부르는 곳이 src에 없다. runtime은 capability를 제네릭으로 다뤄 되돌릴 수 없고, 늦게 도착한 값을 처리할 `compensate`도 넘기지 않는다(`resumable-upload-runtime.ts:1325`). 쓰지 못한 capability가 생기는 경로는 넷이다. runtime 응답 검증 실패(`upload-response-validation.ts:45-74`), part 실행기 사전 검사 실패(`presigned-upload-part-executor.ts:55-81`), 실행기 digest 도중 abort·timeout(claim 전, `presigned-transfer-executor.ts:305-331`), fail-fast로 중단된 형제 worker |
| 발생 조건 | 위 실패가 반복되고 capability 수명이 긴 경우 |
| 영향 | 쓰지 못한 항목이 만료 전까지 `maxActiveCapabilities` 자리를 차지한다(브라우저 스펙 조립값은 8). 자리가 차면 발급이 `LIMIT_EXCEEDED`(`retryable:false`)로 실패한다. 이 코드는 파일 크기 초과처럼 읽힌다. 서버가 같은 key에 같은 receipt를 다시 주면 `CONFLICT`로 막히지만, 서버 문서가 발급을 매번 새 작업으로 규정하므로(`server-file-capability-infrastructure.md:1030`) 가능성은 낮다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0(회수 경로 없음) · E1 |
| 확실성과 남은 가정 | 경로는 확인했다. 실제로 자리가 차는 빈도는 미측정이다 |
| 최소 개선 방향 | presigned 실행기 `put()`이 capability를 resolve한 뒤에는 어떤 경로로 끝나든 `finally`에서 vault 항목을 정리하게 한다. runtime 검증 실패분은 만료까지 두는 것을 문서화한다 |
| 비용·부작용 | 작음 |
| 완료 기준 | `put()`이 어느 경로로 끝나도 vault 항목 수가 원래대로 돌아온다 |
| 검증 방법 | digest abort·사전 검사 실패를 주입하고 vault 크기를 비교한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-08 재개할 때 저장된 session을 현재 정책으로 다시 검사해, 정책을 낮춘 배포 뒤 기존 업로드가 막힌다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 18, 3, 11 |
| 근거 | 재개 때 status를 검증하는 코드가 `validateSession`을 부른다(`upload-response-validation.ts:96-115`). 이 함수는 `session.maxConcurrency > policy.maxConcurrency`(`:219-221`)이거나 수명이 정책 상한을 넘으면(`:229-240`) `INTEGRITY_FAILED/RECONCILE`을 낸다. worker 수는 이미 `min(policy, session)`이라(`resumable-upload-runtime.ts:776-780`) 거절할 이유가 없다. 이 repo의 R-1.3 수정이 기본 `maxConcurrency`를 1로 낮춘 것이 바로 이 조건이다 |
| 발생 조건 | 다운스트림이 `maxConcurrency`나 `maxSessionLifetimeMs`를 낮춘 빌드를 배포하고, 이전 빌드에서 시작한 checkpoint를 session 수명(기본 상한 24h) 안에 재개할 때 |
| 영향 | 그 uploadKey는 `abort()`하기 전까지 매번 `INTEGRITY_FAILED`가 난다. 사용자는 이미 올린 part를 버리고 처음부터 다시 올려야 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E1 |
| 확실성과 남은 가정 | 경로는 확인했다. 실제 배포 이력은 없다(조립되지 않음) |
| 최소 개선 방향 | 재개 경로에서는 저장된 checkpoint 값과 일치하는지만 보고, 정책 상한 검사는 새 session을 만들 때만 한다 |
| 비용·부작용 | 작음 |
| 완료 기준 | 정책을 3→1로 낮춘 runtime이 동시성 3으로 만든 checkpoint를 재개한다 |
| 검증 방법 | 두 runtime(정책 다름)이 checkpoint store 하나를 공유하는 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-09 part 수 상한과 control-plane 요청·응답 바이트 상한을 서로 검사하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 19, 13, 14 |
| 근거 | 정책은 part를 10,000개까지 허용한다(`runtime-policy.ts:35, 80-81`). fetch 전송의 요청 상한은 기본 1MiB이고, 넘으면 `LIMIT_EXCEEDED, retryable:false`다(`fetch-json-transport.ts:62, 169-188`). 실제 JSON으로 complete 요청 크기를 계산했다: 1,024 part ≈ 199KB, 5,400 part ≈ 1.06MB(1MiB 초과), 10,000 part ≈ 1.96MB. 응답 상한 기본 2MiB도 10k part status에 가깝다. 두 값은 서로 다른 factory에 들어가 교차 검증이 없다 |
| 발생 조건 | 기본값(최대 1,024 part)에서는 생기지 않는다. `maxFileBytes`를 키워 part가 약 5,300개를 넘는 설정 |
| 영향 | 모든 part를 올린 뒤 complete에서 영구 실패한다(재개해도 같다). 큰 파일일수록 늦게 드러난다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E1(크기 계산) |
| 확실성과 남은 가정 | 요청 크기는 receipt token 32자 기준. token이 길면 더 빨리 넘는다 |
| 최소 개선 방향 | 조립 helper나 문서에서 `maxPartCount`와 전송 `maxRequestBytes`·`maxResponseBytes`를 함께 검사한다. 또는 정책 해석 시 필요한 요청 크기를 계산해 알린다 |
| 비용·부작용 | 작음 |
| 완료 기준 | part 수 상한에 맞지 않는 전송 상한 조합이 조립 시점에 거절된다 |
| 검증 방법 | 조합 검증 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-10 `UPLOAD_PART` 관측이 두 계층에서 같은 이름으로 기록되고, 문서가 말한 retry·part bucket은 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서와 구현 불일치, 중복 집계) |
| 관련 관점 | 7, 8 |
| 근거 | 실행기는 PUT 시도마다(`presigned-transfer-executor.ts:435-442`), runtime은 part 최종 결과마다(`resumable-upload-runtime.ts:808-813, 871-876`) `UPLOAD_PART`를 기록한다. 같은 observer를 넘기면 성공 part 하나가 SUCCEEDED 2건이 된다. 재시도 한 번 뒤 성공하면 FAILED 1건과 SUCCEEDED 2건이 된다. `observeTransferResult`(`presigned/http-common.ts:208-221`)는 retry·duration·count bucket을 넣지 않는다. 문서 `presigned-transfer-and-image-cdn.md:634`는 part·retry bucket을 기록한다고 적는다 |
| 발생 조건 | 실행기와 runtime에 같은 observer를 줄 때(자연스러운 조립) |
| 영향 | 실패율과 건수가 부풀려진다. 재시도 증폭을 관측할 수 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1(문서) · E1 |
| 확실성과 남은 가정 | 정적 확인. 실제 수집 파이프라인은 다른 영역 |
| 최소 개선 방향 | 실행기 기록은 `PRESIGNED_TRANSFER`로 두고 `UPLOAD_PART`는 runtime만 기록한다. 최종 결과에 시도 수 `countBucket`을 넣는다 |
| 비용·부작용 | 작음. 관측 이름이 바뀐다 |
| 완료 기준 | 재시도 1회 뒤 성공한 part가 `UPLOAD_PART` 1건(시도 수 bucket 포함)으로 기록된다 |
| 검증 방법 | observer 기록 단언 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 01-11 이미지 `resolve()`가 `PRIMARY_REQUIRED` preset이면 호출마다 원본 후보 전체를 내려받아 decode하며, 동시 실행 상한과 결과 재사용이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 14, 5 |
| 근거 | `resolve()`는 호출마다 probe를 실행한다(`image-cdn-runtime.ts:544-614`). 동시 상한은 서명 검증에만 있다(`:338-347`). probe(`browser-image-probe.ts`)에도 상한이 없다. private 응답은 `no-store`가 필수라(`browser-image-probe.ts:322-325`) `<img>`가 같은 URL을 한 번 더 받는다. private asset은 `PRIMARY_REQUIRED`가 강제된다(`image-cdn-runtime.ts:511-518`). port 주석(`application/ports/browser-transfer/image-cdn.ts:167-180`)에는 이 네트워크·decode 비용이 적혀 있지 않다 |
| 발생 조건 | private 이미지가 많은 목록 화면. 재렌더링 때마다 `resolve()` 호출 |
| 영향 | 메모리를 동시 probe 수 × (encoded + decoded 상한)만큼 쓴다(README 예시 기준 이미지당 약 4.5MiB, 구현 상한은 최대 80MiB). 전송량은 2배가 된다 |
| 심각도·우선순위 | Low · P3 — 비용 문제이고 안전 문제는 아니다 |
| 통제·증거 | M0 · E1 |
| 확실성과 남은 가정 | 코드로 확인했다. 실제 화면 부하는 미측정 |
| 최소 개선 방향 | probe에 서명 검증과 같은 방식의 동시 상한을 두고, port 주석에 비용을 적는다. 같은 asset+preset 결과를 capability 만료까지 재사용한다 |
| 비용·부작용 | 작음~중간 |
| 완료 기준 | 동시 probe 수가 상한을 넘지 않고, 같은 요청을 반복하면 네트워크를 다시 쓰지 않는다 |
| 검증 방법 | probe fake로 동시 호출 수 단언 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 — checkpoint·session 상태 전이 | 목표 M3 / 확인 M3: exact-key decoder, revision CAS, `ACTIVE→ABORT_PENDING→삭제` | E2(199 테스트, M3·M4 검출) | 충족 |
| 2 | 구조적 성숙도 | 적용 — 배럴·port·kernel import | 목표 M3 / 확인 M2: 배럴 3개, adapter 간 import는 kernel(`platform/`, `browser-file-storage/result.ts`)만 | E1(import 목록). `check:architecture`는 오케스트레이터 | 충족(게이트 결과 제외) |
| 3 | 변경 용이성 | 적용 — 정책 변경의 전파 | M2: runtime을 검증·snapshot·정책 모듈로 분리 | E1 | 부분 충족 — 정책을 낮추면 기존 checkpoint가 막힌다(01-08) |
| 4 | 인지 부하 | 적용 | M2: 파일 분리, 주석에 요구 ID | E1 | 부분 충족 — 실패→행동 매핑을 코드 전체에서 찾아야 한다(01-05) |
| 5 | 위험 가시성 | 적용 — 29.4 문장 작성 | M1~M2 | E2 | 부분 충족 — 결과 불명 표현 없음(01-02), recovery 모호(01-05), resolve 비용 미표시(01-11) |
| 6 | 실패 성숙도 | 적용 — 중점 | M2~M3: 재시도 단일 계층·상한·jitter·고정 key, 결과 불명 checkpoint | E2(X1~X3, M2~M5) | 부분 충족 — 01-01, 01-02, 01-03, 01-06 |
| 7 | 운영 성숙도 | 적용(연결점만) | M1: observer seam, 안전 bucket | E1 | 부분 충족 — 중복 집계, retry bucket 없음(01-10) |
| 8 | 디버깅 가능성 | 적용 | M2: 닫힌 code·operation·recovery 분류, 민감정보 미기록 | E1 | 부분 충족 — 같은 실패값이 다른 원인(01-05). 상관 ID는 설계상 제외 |
| 9 | 유지보수 성숙도 | 적용 | M2: 직전 리뷰 11건 반영, HTTP helper 통합 | E1 | 부분 충족 — 작은 갈라진 복사본이 남음(`isAbortSignal`이 `checkpoint-schema.ts:195`는 duck typing, `http-common.ts:186`은 brand 검사. `MEDIA_TYPE` 길이 규칙 2종) |
| 10 | 테스트 성숙도 | 적용 — 중점 | 목표 M3 / 확인: 주요 분기 일부만 M3 | E2(199 통과, 변형 7종 중 3종 생존) | 부분 충족 — 01-04 |
| 11 | 데이터 성숙도 | 적용 — checkpoint 수명·범위·삭제 | M2~M4: 저장 key allowlist, 계정 partition 결속, 성공·abort·terminal 때 삭제, partition 삭제는 PENDING/UNKNOWN 정직 보고 | E2(checkpoint 테스트 14개) | 부분 충족 — TTL·inventory 없음(문서 4.4가 미구현으로 선언, 결함 아님). 완료된 자원과의 연결을 잃는 경로(01-02). lock·BroadcastChannel 이름은 계정으로 나뉘지 않음(uploadKey 충돌 시에만 영향) |
| 12 | 동시성 성숙도 | 적용 — 중점 | M3: Web Lock, revision CAS, receipt 직렬화, fail-fast, dispose가 실제 작업까지 대기 | E2(M2 검출, teardown 테스트) | 충족 — 잔여: vault 미회수(01-07). `close()`만 쓰면 drain이 시간 초과된 뒤 store를 닫을 주체가 없다(`resumable-upload-runtime.ts:266-270, 294-302`) |
| 13 | 확장성 | 부분 적용 — part 수 증가 | M1 | E1 | 부분 충족 — 01-09 |
| 14 | 성능 성숙도 | 적용 — 중점(in-flight 바이트) | M3: 시작 전 in-flight 검사, 본문 hard cap | E1. copyFactor 4는 추정이고 실측 없음 | 부분 충족 — 01-03, 01-11. part당 SHA-256을 3번 계산한다(manifest, runtime, 실행기) |
| 15 | 보안 성숙도 | 적용 | M4: vault identity, HTTPS·redirect·credential·header 금지, checkpoint allowlist | E2(presigned 테스트 4파일) | 충족 — 인가는 서버 책임(문서 3.1) |
| 16 | 의존성 성숙도 | 적용(제한) — 외부 패키지 없음 | M2: WebCrypto와 직접 구현한 SHA-256 | E2(대조 1,830건) | 충족 — 자체 암호 코드 유지 비용은 01-04 테스트로 보완 필요 |
| 17 | API / Contract 성숙도 | 적용 — 중점(presigned 서버 계약) | M3: strict exact-key decode, protocol literal, `singleUse:true` 강제 | E2 | 부분 충족 — complete 진행 중 표현 없음(01-02), recovery 의미(01-05), 시계 오차(01-06), BFF 429의 `Retry-After` 미반영(`http-common.ts:135-167`) |
| 18 | 배포 성숙도 | 적용 — 구버전 checkpoint 공존 | M2: `schemaVersion:1` 고정, 모르는 schema는 abort로 제거 | E2 | 부분 충족 — 정책 변경 skew(01-08) |
| 19 | 설정 성숙도 | 적용 | M3: 정책·레지스트리를 조립 시점에 검증(TypeError) | E2 | 부분 충족 — factory 사이의 값(timeout, 최소 잔여 수명 vs refresh skew, part 수 vs 요청 상한)을 서로 검사하지 않음(01-01, 01-03, 01-09) |
| 20 | 개발자 경험 | 적용 | M1: image-cdn README 예제. upload 조립 예는 Playwright 스펙에만 | E1 | 부분 충족 — resumable upload 조립 예제 문서 없음 |
| 21 | Guardrail 성숙도 | 부분 적용 | M3: 조립 시 정책·레지스트리 거절. 경계 검사는 다른 영역 | E1 | 부분 충족 — idempotency 규칙 자동 검출 없음(01-04) |
| 22 | 추상화 성숙도 | 적용 — 중점(abort kernel 등) | M3: runtime attempt·fetch 전송·presigned scope·image가 모두 `createAbortableOperation` 사용(6.1-9 해결) | E2 | 부분 충족 — 제네릭 Capability 탓에 미사용 capability를 회수할 수 없음(01-07). 실패 타입이 결과 불명을 숨김(01-02). `startDrain`은 kernel이 아닌 직접 타이머 |
| 23 | 일관성 | 적용 | M2 | E1 | 부분 충족 — 시계 오차 처리가 image-cdn에만 있음(01-06). `Retry-After`는 control 전송에만 있음 |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 | E1 | 부분 충족 — `RESTART`로 풀리지 않는 실패, `REISSUE_CAPABILITY`+`retryable:false`(01-05) |
| 25 | 조직 확장성 | 구조적 준비만 평가(팀 1인) | port와 adapter가 분리됨 | E1 | 적용 제외 — 실제 검증 대상 아님 |
| 26 | Ownership 성숙도 | 부분 적용 | M1: 서버 책임을 `server-file-capability-infrastructure.md`에 기술 | E0 | 부분 충족 — 클라이언트·서버 계약 공백(01-02 ⑤)의 결정 주체가 없음 |
| 27 | 삭제 가능성 | 적용 | M3 주장: `scripts/test-browser-file-storage-runtime-removal.ts`가 이 폴더를 지우고 게이트 실행 | E0(미실행) | 미검증 |
| 28 | 회복 가능성 | 적용 — 중점(중단 후 재개·정리) | M2~M3: checkpoint 재개, 서버 상태 조정, ABORT_PENDING, 읽을 수 없는 행 제거 | E2 | 부분 충족 — 완료 자원과의 연결을 잃는 경로(01-02), 전진 불가 재시도(01-03). 버려진 checkpoint 정리는 선언된 미구현 |
## 6. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 실제 브라우저 동작(Web Locks, IndexedDB, BroadcastChannel, fetch 스트림) | Playwright 스펙 3개를 실행하지 않음 | `test:browser-capabilities`로 `resumable-upload.spec.ts`, `presigned-streaming.spec.ts`, `image-cdn.spec.ts` 실행 |
| 두 탭의 동시 업로드·abort | 단위 테스트는 메모리 fake 채널·lock만 사용 | 실제 브라우저 두 page에서 같은 uploadKey로 upload/abort |
| object store·BFF 실제 계약: PUT 403 발생 조건, 같은 key 재발급 시 receipt, complete 소요 시간, `OPERATION_IN_PROGRESS` wire 표현 | repo 밖 시스템 | provider conformance 테스트(서버 문서 10.2 retry matrix 기준) |
| part 버퍼 실제 메모리(copyFactor 4 추정) | 측정 환경 없음 | 브라우저 메모리 프로파일로 동시성 N, part 5MiB일 때 최대 사용량 측정 |
| 저속 업링크의 실제 영향 | 실험은 fake timer | 네트워크 throttling(1Mbit/s)으로 실제 업로드 |
| Web Locks 미지원 브라우저 처리 | 문서가 "unsupported lock decision"을 미결정으로 선언 | 지원 브라우저 결정 또는 fallback 설계 |
| 삭제 가능성 | `test:browser-file-storage-removal`은 `.tmp`에 fixture를 만들고 pnpm을 실행해 동시 작업 중 실행하지 않음 | 단독 환경에서 실행 |
| 아키텍처·타입 게이트 | 오케스트레이터 담당 | `check:architecture`, `check:types` 결과 참조 |
| logout 시 checkpoint partition 삭제 연결 | 조립 코드가 repo에 없음(`AVAILABLE_NOT_COMPOSED`) | 다운스트림 조립에서 dispose → `deletePartition` 순서 검증 |
@@ -0,0 +1,295 @@
# browser-files / cache-storage / cross-context-invalidation 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/adapters/browser-files/` (10파일, 약 4.8k줄), `src/adapters/cache-storage/` (5파일, 약 2.3k줄), `src/adapters/cross-context-invalidation/` (3파일, 약 1.1k줄). 합계 약 8.1k줄. 이 영역을 검증하는 unit 테스트 11개 파일(약 6.6k줄)과 browser-capabilities spec 4개.
> 영역 판정(35.8): **조건부 사용 가능**
## 1. 결론
- cross-context-invalidation은 기본 조립 경로(`src/bootstrap/runtime-adapters.ts:346`)에 들어가 있고, 직전 리뷰의 순서·fallback 결함(6.2-2, 6.2-3, 6.2-9)은 현재 코드에서 고쳐져 있다. 여러 탭의 중복·역순·BroadcastChannel 미지원은 그대로 써도 된다.
- browser-files는 기본 번들 밖의 opt-in runtime이다. 도입 전에 고칠 것은 **preview를 만든 직후 호출자가 abort하면 object URL lease가 새는 문제(02-01)** 하나다. lease 한도(기본 16)를 preview와 download가 같이 쓰므로, 16개가 새면 그 탭에서는 preview와 소형 download가 모두 `LIMIT_EXCEEDED`로 실패한다. Node에서 실제 adapter 코드로 재현했다.
- cache-storage는 요청을 익명(`credentials: "omit"`, `mode: "same-origin"`)으로 보내고 private·cookie 계열 응답을 거부한다. 그래서 로그아웃·사용자 전환 때 Cache Storage를 지울 필요가 없다. 다만 **이 익명 요청 규칙을 고정하는 테스트가 없다(02-02)**. 두 줄을 지워도 테스트가 전부 통과한다.
- 변이 22개를 넣어 테스트 검출력을 확인했다. 11개는 테스트가 잡았고, 4개는 다른 검사가 막아 결과가 같았다. 나머지 6개 규칙은 테스트가 잡지 못했다(02-02, 02-08).
- 미검증: 실제 브라우저 3종에서의 동작(Playwright spec 실행 불가), Safari의 30초 object URL grace 충분성, 다른 탭에서 계정이 바뀐 뒤 이 탭이 받는 무효화 hint의 영향(auth 영역 의존).
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, 영역 02 |
| 커밋·상태 | `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 가이드 문서뿐 |
| 지원 구성 | 브라우저 SPA. cross-context-invalidation은 `COMPOSED`, browser-files·cache-storage는 `AVAILABLE_NOT_COMPOSED`(recipe, `config/recipes/frontend-capability-recipes.json:128`, `:176`) |
| 읽은 코드 | 위 3개 폴더 전체, 관련 port(`src/application/ports/browser-file-storage/{shared,file,cache-storage-ports}.ts`), kernel(`src/adapters/browser-file-storage/result.ts`, `src/adapters/platform/abortable-operation.ts`), wire 계약(`src/contracts/cache-invalidation.ts`), 조립·소비 코드(`src/bootstrap/runtime-adapters.ts`, `src/bootstrap/server-state-generation-store.ts`, `src/adapters/query-cache/tanstack-cache-coordinator.ts`) |
| 읽은 문서(주장) | `docs/architecture/browser-file-and-origin-storage.md` 1·3·5·8절, `docs/architecture/client-cache-and-storage.md` 0절, recipe catalog |
| 실행한 테스트 | `node scripts/run-vitest.ts run` 로 영역 unit 11개 파일 → **11 files, 121 tests 통과** |
| 실험 1 | `scratchpad/02/preview-abort.ts`: 실제 `BrowserFileVault`·`BrowserTransientPreview`에 가짜 URL API를 주입. `create()` 직후 같은 turn에 abort를 16번 → 16번 모두 `ok:true` lease 반환, `activeLeaseCount 16`, revoke 0회. 17번째와 abort 없는 새 요청 모두 `LIMIT_EXCEEDED` |
| 실험 2 | `scratchpad/02/shared-registry.ts`: `createBrowserFileRuntime`으로 `BOUNDED_OBJECT_URL` 다운로드 17번(30초 grace 타이머 미발화 상태) → 16번 `BROWSER_HANDOFF`, 17번째 `LIMIT_EXCEEDED` |
| 실험 3 | 분리 worktree에서 규칙 하나씩 제거하는 변이 22개 → 결과는 02-02, 02-08과 관점 10 행에 적었다. worktree는 삭제했다 |
| 확인 못 한 것 | `test:browser-capabilities`(Playwright, dev 서버 필요, 지시서상 실행 범위 밖). `artifacts/tests/browser-capabilities/results.xml`(2026-09-24, webkit 17건 통과)은 이전 실행이라 증거로 쓰지 않았다. `check:architecture`·`lint` 등 전체 게이트는 오케스트레이터 담당 |
### 2.1 직전 리뷰(6.2) 항목 재확인
현재 코드에서 다시 확인했다. 고쳐진 항목은 아래 발견에 다시 올리지 않았다.
| 직전 ID | 현재 상태 | 근거 |
|---|---|---|
| 6.2-1 bounded open 실패 시 reject | 해결 | `download-delivery-adapter.ts:745-756` try 안에서 호출, `:859-862` finally에서 close. 테스트 `browser-file-download.test.ts:781` |
| 6.2-2 watermark TTL 삭제 | 해결 | `browser-cross-context-invalidation.ts:156-158` TTL 없음, `:556-560` prune은 seenEvents만. 테스트 `cross-tab-invalidation.test.ts:525` |
| 6.2-3 fallback 탭 수신 중단 | 해결 | `:188-190`, `:340-364` 발행 실패 뒤에도 채널 유지. 열기 실패는 `DEGRADED_STORAGE_FALLBACK`(`:284-286`) |
| 6.2-4 picker bind | 해결 | `browser-file-picker.ts:430-431`, `download-delivery-adapter.ts:234-235` `bind(undefined)` |
| 6.2-5 Vary/content-type | 해결 | `public-cache-response-validation.ts:186`, `public-cache-policy.ts:142` |
| 6.2-6 조회 비용 | **일부 남음** → 02-07 | marker 메모·Map 탐색은 적용. `keys()` 2회와 본문 복사 4회는 남음 |
| 6.2-7 abort race | 해결 | kernel `createAbortableOperation` 사용(`download-delivery-adapter.ts:276`, `:600-608`, `:916-928`, `browser-file-vault.ts:515`) |
| 6.2-8 focus fallback | 해결 | `browser-file-picker.ts:107`, `:339-341` |
| 6.2-9 host 조용한 비활성 | 해결 | `browser-cross-context-host.ts:45-51`, `:68-91` |
| 6.2-10 파일명 O(n²) | 해결 | `file-policy.ts:418-430` 단일 패스 |
| 6.2-11 큰 파일 분리 | 해결(분리됨) | codec 656줄·검증 239줄·입력 검증 367줄로 분리. 본 파일은 여전히 각 1.1k줄대 |
| 6.2-12 중복 정규식 | 대부분 해결 | `file-policy.ts:49-55`로 통합. `public-cache-policy.ts:191`의 `positiveSafeInteger` 한 벌은 남음(의미 동일, 발견으로 올리지 않음) |
### 2.2 32절 시나리오 추적 (이 영역 관점)
**로그아웃 중 응답 도착**
```text
세션 변경 → server-state scope reset → activateNext()
→ 이전 coordinator.dispose() → crossContext.close() (tanstack-cache-coordinator.ts:276-280)
→ 새 generation: 새 QueryClient + 새 crossContext(새 sourceId·sourceEpoch)
(server-state-generation-store.ts:50-57, runtime-adapters.ts:343-383)
```
- cross-context: 닫힌 인스턴스에 늦게 도착한 메시지는 `closed` 검사에서 버린다(`browser-cross-context-invalidation.ts:445`, `:458`). 이전 세대 탭 ID로 보낸 이벤트는 새 세대에서 새 source로 보인다. 테스트 `cross-tab-invalidation.test.ts:809`. **이전 세션 응답이 다음 세대 상태로 들어가는 경로는 이 영역에서 찾지 못했다.**
- cache-storage: stage 중 로그아웃돼도 요청이 익명이라 사용자 응답이 저장되지 않는다(`public-cache-response-validation.ts:227-238`, `:54-66`). 단 이 규칙은 테스트가 고정하지 않는다(02-02).
- browser-files: runtime이 세션을 모른다. 진행 중 download는 호출자가 abort하지 않으면 로그아웃 뒤에도 끝까지 저장된다. vault의 File 참조와 preview object URL은 runtime dispose 전까지 남는다(02-03).
**사용자·테넌트 전환**
- Cache Storage: 저장 대상이 익명 공개 응답뿐이라 사용자별 분리가 필요 없다. 캐시 키에 `authorization`·`cookie` 요청 헤더를 넣을 수 없다(`public-cache-codec.ts:254-278`).
- cross-context: wire 이벤트에 사용자·세션 scope가 없다. 문서가 "session/account epoch는 미구현, 같은 release의 stale hint 용도로 한정"이라고 선언한다(`docs/architecture/client-cache-and-storage.md:85-88`). 다른 탭에서 계정이 바뀐 뒤 이 탭이 hint를 받아 refetch하면, 이 탭의 이전 사용자 세대 캐시에 새 쿠키 응답이 들어갈 수 있다. 원인은 탭 간 세션 변경 감지(auth 영역)이고 hint는 그 시점을 앞당길 뿐이다. 비지원이 선언돼 있어 결함으로 세지 않고 6절 미검증에 적었다.
- browser-files: 02-03과 같다.
## 3. 확인된 강점
1. **캐시에 사용자 데이터가 들어갈 경로를 여러 겹으로 막는다.** 요청은 `credentials: "omit"`, `mode: "same-origin"`, `redirect: "error"`(`public-cache-response-validation.ts:227-238`). 응답은 `private`/`no-store`/`no-cache`, `Set-Cookie`, `WWW-Authenticate`, `Vary: Cookie|Authorization|*`면 거부한다(`:54-66`, `:187-193`). 요청 헤더에서 `authorization`·`cookie`·`range`를 금지하고(`public-cache-codec.ts:254-259`), query는 allowlist만 받는다(`:231-245`). 본문은 manifest의 SHA-256·길이·Content-Type과 정확히 맞아야 한다(`public-cache-response-validation.ts:71-96`).
2. **파일 이름·MIME을 신뢰하지 않는다.** 저장 파일 확장자는 정책의 `safeExtension`만 붙고, 이름 안의 실행 확장자는 `_exe`처럼 무력화하며, bidi 제어 문자·경로·Windows 예약어를 제거한다(`file-policy.ts:310-376`). preview의 MIME은 `File.type`이 아니라 헤더 바이트로 찾은 signature에서 오고, 그 타입으로 새 Blob을 만든다(`object-url-lease.ts:263-285`). SVG·HTML·XML·PDF는 정책으로도 풀 수 없다(`:173-180`, `:204-213`).
3. **사용자 취소·abort·권한 거부를 Result에서 구분한다.** picker 취소는 `DISMISSED` 성공, 호출자 abort는 `ABORTED`, user activation 없음·`NotAllowedError`·`SecurityError`는 `PERMISSION_DENIED`다(`browser-file-picker.ts:249-254`, `:526-546`, `download-delivery-adapter.ts:529-575`, `result.ts:54-66`). 이미 close된 저장은 늦은 abort로 실패 처리하지 않는다(`download-delivery-adapter.ts:667-669`).
4. **자원 상한이 조립 시점에 검증되고 호출자는 낮추기만 한다.** 선택 개수·파일·누적 바이트, 보관 참조 32개, object URL 16개·합계, 전송·버퍼 바이트(`create-browser-file-runtime.ts:199-242`, `browser-file-policy-registry.ts:492-507`). 캐시는 entry 16 MiB·release 128 MiB·500개·control JSON 2 MiB(`public-cache-policy.ts:43-82`, `public-cache-codec.ts:291-357`).
5. **여러 탭의 중복·역순·전송 수단 실패를 명시적으로 처리한다.** eventId 중복 제거, source별 watermark로 역순 폐기, 끊기면 `GAP`으로 전체 무효화, 자기 echo 폐기(`browser-cross-context-invalidation.ts:469-514`). storage 이벤트는 캡처한 localStorage 객체와 동일성으로만 받는다(`:197-201`, `browser-cross-context-host.ts:286-296`). 두 수단이 모두 없으면 부팅을 막지 않고 `DEGRADED_LOCAL_ONLY`로 진단을 남긴다(`:377-396`, `runtime-adapters.ts:358-373`).
6. **캐시 교체가 부분 실패에도 서비스 중 release를 지운다.** 새로 만든 candidate만 실패 시 삭제하고, 기존 candidate는 교체본 검증 전 지우지 않는다(`public-response-cache-adapter.ts:445-490`, `:563-571`). abort 뒤에는 asset·marker 쓰기를 막는다(`:414-430`).
## 4. 발견 사항 (36.3)
### 02-01 preview를 만든 직후 abort하면 object URL lease가 반환되고 다시 회수되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 12, 14, 23, 5 |
| 근거 | `object-url-lease.ts:235-236`에서만 abort를 보고, `:250` `await resolveVerifiedFile(...)` 뒤에는 dispose만 확인한다(`:258-262`). 그 뒤 `:285`에서 lease를 만들고 성공으로 반환한다. 같은 runtime의 vault는 await 뒤 abort를 다시 보고(`browser-file-vault.ts:355-359`, `:469-470`), download는 늦게 온 자원을 kernel race로 닫는다(`download-delivery-adapter.ts:916-928`). 실험 1: `create()` 호출 직후 같은 turn에 abort → `ok:true` lease, 16번 반복 뒤 `activeLeaseCount 16`, revoke 0회, 17번째와 abort 없는 새 요청 모두 `LIMIT_EXCEEDED` |
| 발생 조건 | 호출자가 `create()`를 부른 같은 task 안에서 abort한다. React StrictMode 개발 모드의 effect 두 번 실행(effect → cleanup → effect)에서 매번 일어난다. 운영에서는 같은 task에서 요청을 교체·취소하는 코드에서 일어난다 |
| 영향 | 호출자는 abort된 결과를 버리므로 lease를 release하지 않는다. lease는 runtime dispose까지 남는다. 한도(기본 16개, `create-browser-file-runtime.ts:219-220`)를 preview와 download가 같은 registry로 쓰므로(`:109-120`, `:151-168`) 한도가 차면 그 탭에서 preview와 `BOUNDED_OBJECT_URL` download가 모두 `LIMIT_EXCEEDED`로 실패한다. 새는 동안 사용자 파일 Blob도 메모리에 남는다 |
| 심각도·우선순위 | Medium · P2 — 탭 하나의 기능 실패이고 dispose·새로고침으로 회복된다. runtime은 기본 번들 밖(opt-in)이지만 preview를 조립하는 다운스트림에는 그대로 복제된다 |
| 통제·증거 | M1(문서 3.5절 "unmount에서 한 번 revoke"는 호출자 책임으로만 적힘) · E2(Node 재현 실험) |
| 확실성과 남은 가정 | 코드 경로와 재현 결과는 확정. 실제 React 화면에서의 발생 빈도는 호출 코드에 달려 있다(현재 repo 안 소비자 없음) |
| 최소 개선 방향 | `:257` 이후와 `:285` 직전에 `abortedResult(input.signal, "PREVIEW")`를 다시 확인해 `ABORTED`를 반환한다. lease 생성 후 반환 전에 abort가 확인되면 `lease.release()`를 부른다 |
| 비용·부작용 | 몇 줄. 기존 성공 경로 동작은 같다 |
| 완료 기준 | `create()` 직후 같은 turn에 abort하면 `ABORTED`가 오고 `activeLeaseCount`가 늘지 않는다 |
| 검증 방법 | `tests/unit/browser-file-content.test.ts`에 실험 1과 같은 테스트 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 02-02 Cache Storage의 익명 요청 규칙을 테스트가 고정하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(테스트 공백) |
| 관련 관점 | 10, 11, 15 |
| 근거 | stage 요청은 `createNativeRequest`(`public-cache-response-validation.ts:223-238`)가 `credentials: "omit"`, `mode: "same-origin"`으로 만든다. unit 3개 파일과 browser spec 어디에도 `credentials`·`mode` 검증이 없다(grep 0건). 변이 실험: `credentials`를 `"include"`로 바꿔도, 두 줄을 모두 지워도 캐시 테스트 34개가 전부 통과했다 |
| 발생 조건 | 누군가 두 줄을 지우거나 기본값으로 되돌린다. `Request`의 기본 `credentials`는 `"same-origin"`이라, 같은 origin asset 요청에 쿠키가 실린다 |
| 영향 | 서버가 인증된 응답에 `Cache-Control: private`을 빠뜨리면 사용자별 응답이 origin 공용 Cache Storage에 저장되고 로그아웃 뒤에도 남는다. 이 adapter는 로그아웃 purge 경로가 없으므로(설계상 불필요) 이 두 줄이 사용자 분리의 유일한 전제다 |
| 심각도·우선순위 | Low · P2 — 현재 코드는 맞다. 회귀가 조용히 들어올 수 있고, 들어오면 데이터 분리가 깨진다 |
| 통제·증거 | M2(구현) · E1, 검출은 M0 확인(변이 실험) |
| 확실성과 남은 가정 | 실제 누출은 서버 헤더에 달려 있다 |
| 최소 개선 방향 | stage 테스트에서 fetcher가 받은 `Request`의 `credentials === "omit"`, `mode === "same-origin"`, `redirect === "error"`를 단언한다 |
| 비용·부작용 | 테스트 몇 줄 |
| 완료 기준 | 위 변이가 테스트에서 실패한다 |
| 검증 방법 | 같은 변이를 다시 넣어 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 02-03 browser-file runtime이 인증 scope와 연결되지 않고, 연결 방법도 문서에 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 11, 15, 5 |
| 근거 | runtime은 세션을 모르는 feature factory다(`create-browser-file-runtime.ts:89-92`, dispose `:177-186`). 선택 정책의 `classification: PERSONAL/CONFIDENTIAL`은 검증만 하고 동작에 쓰지 않는다(`file-policy.ts:15`, `:112-117`, `browser-file-policy-registry.ts:357`). recipe lifecycle(`config/recipes/frontend-capability-recipes.json:195`)과 문서 3.5절(`docs/architecture/browser-file-and-origin-storage.md:347-356`)은 release·unmount·feature dispose만 말하고 로그아웃·계정 전환은 말하지 않는다. 세션 변경 시 자원을 닫는 연결점(`runtime-adapters.ts:394-400` `participants`)은 있지만 이 runtime을 거기에 붙이라는 안내가 없다 |
| 발생 조건 | 다운스트림이 runtime을 앱 수명(세대 전환보다 바깥)에 만들고, 사용자 A가 파일을 고르거나 preview·download 중에 로그아웃한 뒤 같은 탭에서 B가 로그인한다 |
| 영향 | A가 고른 File 참조(기본 보관 상한 = 전송 상한), preview object URL, 진행 중 download가 B의 세션까지 남는다. 참조는 추측 불가능한 난수라 B가 port로 꺼낼 경로는 확인하지 못했다. 같은 기기 안의 잔존·메모리 문제다 |
| 심각도·우선순위 | Low · P3 — 직접 노출 경로 없음, 같은 기기·같은 탭 한정 |
| 통제·증거 | M0(scope 연결 규칙 부재 확인) · E1 |
| 확실성과 남은 가정 | 실제 영향은 다운스트림이 runtime을 어디서 만들지에 달려 있다 |
| 최소 개선 방향 | 문서 3.5절과 recipe에 "세션·계정 변경 시 runtime.dispose()(또는 scope participant 등록)"를 한 줄 추가한다. 코드 변경은 필요 없다 |
| 비용·부작용 | 문서 수정 |
| 완료 기준 | recipe lifecycle과 문서에 로그아웃 처리가 명시된다 |
| 검증 방법 | 문서 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 02-04 object URL 한도를 preview와 download가 공유하고, 30초 대기 중 초과하면 재시도 불가로 보고한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 14, 22 |
| 근거 | 한 registry를 preview와 download에 같이 넘긴다(`create-browser-file-runtime.ts:109-120`, `:151-168`, 기본 16개 `:219-220`). download lease는 handoff 뒤 30초 유지된다(`download-delivery-adapter.ts:148`, `:835-838`). 한도 초과는 `FileTooLargeError` → `LIMIT_EXCEEDED`(`object-url-lease.ts:97-110`, `download-delivery-adapter.ts:1034-1035`)이고 기본값이 `retryable:false`, `recovery:"NONE"`이다(`result.ts:28-29`). 실험 2: 30초 안 17번째 다운로드가 `LIMIT_EXCEEDED` |
| 발생 조건 | 30초 안에 소형 다운로드를 16번 넘게 하거나(일괄 내보내기), 다운로드 여러 번 직후 preview를 연다 |
| 영향 | 시간이 지나면 풀리는 상태를 "재시도 불가"로 알려, 화면이 잘못된 안내를 한다. download 폭주가 preview를 막는다 |
| 심각도·우선순위 | Low · P3 — 설정으로 한도를 올릴 수 있고 30초 뒤 회복된다 |
| 통제·증거 | M2(상한 구현) · E2(Node 재현 실험) |
| 확실성과 남은 가정 | 기본값 기준. 실제 사용 패턴은 다운스트림 몫 |
| 최소 개선 방향 | lease 한도 초과만 `retryable:true, recovery:"RETRY"`로 보고한다. 필요하면 preview와 download 한도를 나눈다 |
| 비용·부작용 | 실패 코드의 retry 의미 변경 |
| 완료 기준 | 한도 초과 결과가 재시도 가능으로 보고된다 |
| 검증 방법 | 실험 2를 unit 테스트로 옮겨 `retryable` 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 02-05 `inspect()`가 marker만 읽고 candidate를 `verified: true`로 보고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(보장 범위 과장) |
| 관련 관점 | 24, 5, 8 |
| 근거 | `public-response-cache-adapter.ts:857-875`는 marker JSON과 그 안의 digest만 확인하고 모든 candidate에 `verified: true`를 넣는다. 같은 파일의 원칙 주석은 "marker는 staging이 끝났다는 주장일 뿐, entry가 남아 있다는 증거가 아니다"라고 적고 stage·activate에서는 entry를 다시 검증한다(`:471-481`, `:665-684`). port 타입은 `verified: boolean`이지만(`cache-storage-ports.ts:46-50`) 실제 값은 항상 `true`다 |
| 발생 조건 | 브라우저가 candidate의 entry 일부를 지웠거나 손상됐는데 marker는 남아 있다 |
| 영향 | `inspect()`로 롤백 대상이나 상태를 판단하는 운영자·조립 코드가 쓸 수 없는 candidate를 검증됨으로 본다. activate가 다시 검증하므로 잘못 활성화되지는 않는다 |
| 심각도·우선순위 | Low · P3 — 진단 정보 오류, 실제 활성화는 막힌다 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 코드로 확정. 현재 소비자 없음 |
| 최소 개선 방향 | 필드를 `markerValid`처럼 실제 보장으로 바꾸거나, entry 재검증 결과(`verifyReleaseCandidate`)를 반영한다 |
| 비용·부작용 | 재검증을 넣으면 inspect 비용이 entry 수에 비례해 는다. 이름만 바꾸면 port 타입 변경 |
| 완료 기준 | entry가 없는 candidate가 검증됨으로 보고되지 않는다 |
| 검증 방법 | entry 하나를 지운 뒤 `inspect()` 결과 확인하는 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 02-06 다운로드 취소와 browser handoff 성공이 관측 기록에서 똑같이 보인다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(진단 정보 손실) |
| 관련 관점 | 8, 6 |
| 근거 | file observer가 `DISMISSED`를 `SUCCEEDED`로 바꾼다(`file-observer.ts:32-33`). `BROWSER_MANAGED` 성공은 바이트 수가 없어 byteBucket이 빠진다(`download-delivery-adapter.ts:470-478`, 기본 `bytes = null` `:1097`). 저장 대화상자 취소도 byteBucket 없이 기록된다(`:535-541`, `:557-562`). 두 경우 모두 `{operation: "DOWNLOAD", outcome: "SUCCEEDED"}` 한 가지로 남는다 |
| 발생 조건 | 기본 동작 |
| 영향 | 저장 대화상자 취소율과 handoff 성공률을 관측으로 나눌 수 없다. 문서는 취소를 error telemetry로 남기지 말라고 하지만(`browser-file-and-origin-storage.md` 3.2절), 성공으로 합치라는 뜻은 아니다 |
| 심각도·우선순위 | Low · P3 — Result는 구분된다. 관측만 문제 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | 코드로 확정 |
| 최소 개선 방향 | `BrowserDataObservation.outcome`에 `DISMISSED`를 추가하거나, 취소는 관측하지 않는다 |
| 비용·부작용 | 관측 타입 변경(공용 port) |
| 완료 기준 | 두 경우가 서로 다른 관측으로 남는다 |
| 검증 방법 | observer 기록을 비교하는 unit 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 02-07 캐시 조회 한 번의 비용이 여전히 크다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 14 |
| 근거 | `matchActiveExact` 한 번에 `caches.keys()` 2번(`readActivePointer` `public-response-cache-adapter.ts:992`, `:260`), active pointer JSON 읽기·파싱, 본문 전체 읽기(`:338-344`), 본문 SHA-256, 본문 복사 4번(읽기 버퍼, digest 입력 `Uint8Array.from` `:180-186`, `byteSourceFrom` 저장 `:1011`, stream마다 `:1019`)이 일어난다. entry 상한은 16 MiB라 조회 한 번에 최대 약 64 MiB를 할당한다 |
| 발생 조건 | Service Worker처럼 요청마다 조회하는 소비자를 붙일 때 |
| 영향 | 페이지 로드 한 번에 asset 수 × 본문 크기 × 4의 할당과 GC 부담 |
| 심각도·우선순위 | Low · P3 — 현재 소비자 없음(`AVAILABLE_NOT_COMPOSED`). 문서가 "static asset handler에서 재사용"을 목표로 적어 도입 시 비용이 된다 |
| 통제·증거 | M1 · E1(측정 안 함) |
| 확실성과 남은 가정 | 복사 횟수는 코드로 확정. 실제 지연·메모리는 미측정 |
| 최소 개선 방향 | `byteSourceFrom`이 읽은 버퍼를 그대로 쓰고(복사 2번 제거), `readActivePointer`가 받은 이름 목록을 재사용한다 |
| 비용·부작용 | 반환 버퍼를 호출자가 수정할 수 있게 되므로 stream에서 한 번만 복사하거나 freeze 규칙을 문서화 |
| 완료 기준 | 조회당 `keys()` 1번, 본문 복사 2번 이하 |
| 검증 방법 | 가짜 CacheStorage의 `keys` 호출 수를 세는 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 부분 해결 |
| 직전 리뷰 | 6.2-6 일부 미해결(marker 메모·Map은 해결) |
### 02-08 보안·자원 규칙 5개가 다른 조건에 가려 테스트에서 검출되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(테스트 공백) |
| 관련 관점 | 10, 15, 12 |
| 근거 | 변이 실험에서 아래 규칙을 지워도 관련 테스트가 전부 통과했다. (1) browser-managed download의 다른 origin 거부 `download-input-validation.ts:346` — 유일한 테스트 `browser-file-download.test.ts:294-323`이 다른 origin과 query를 한 URL에 같이 넣어 query 검사가 대신 막는다. (2) vault 누적 보관 바이트 상한 `browser-file-vault.ts:713-718` — `browser-file-content.test.ts:685-713`이 참조 개수 상한 1을 같이 걸어 개수 검사가 먼저 막는다. (3) preview Blob을 검증된 타입으로 다시 만드는 규칙 `object-url-lease.ts:280-285`. (4) native picker의 user activation 검사 `browser-file-picker.ts:249-254`. (5) 처음 보는 source의 첫 이벤트 seq>1을 `GAP`으로 보는 규칙 `browser-cross-context-invalidation.ts:509` |
| 발생 조건 | 리팩터링으로 해당 줄이 빠진다 |
| 영향 | (1)은 서버가 준 href가 다른 origin이어도 handoff하게 되고, (5)는 탭이 놓친 이벤트를 한 topic 무효화로만 처리하게 된다. 나머지는 방어 규칙 약화 |
| 심각도·우선순위 | Low · P3 — 현재 코드는 맞다 |
| 통제·증거 | M2 · 검출 M0 확인(변이 실험) |
| 확실성과 남은 가정 | 같은 실험에서 결과가 같았던 변이 4개(redirect 검사, Vary cookie, forbidden query, eventId 중복 제거)는 다른 검사가 대신 막아 공백으로 세지 않았다 |
| 최소 개선 방향 | 규칙마다 그 규칙만 걸리는 입력으로 테스트 하나씩 추가한다(예: query 없는 다른 origin href, 참조 상한은 넉넉하고 바이트만 넘는 선택) |
| 비용·부작용 | 테스트 5개 |
| 완료 기준 | 위 5개 변이가 각각 테스트에서 실패한다 |
| 검증 방법 | 같은 변이 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 02-09 cross-tab 무효화 설계 문서가 현재 구현보다 뒤처져 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서 불일치) |
| 관련 관점 | 9, 17 |
| 근거 | `docs/architecture/client-cache-and-storage.md:82-84`는 "pulse key가 storage registry 밖 상수, storageArea 미검증"이라 적지만 코드는 registry key(`browser-cross-context-host.ts:36-37`)와 storageArea 동일성 검사(`browser-cross-context-invalidation.ts:197-201`)를 쓴다. `:85`의 epoch 형식 `release.<releaseId>`는 현재 FNV-1a 해시(`browser-cross-context-host.ts:45-51`)다. `:86`은 "scope 전환 시 새 QueryClient 생성 미구현"이라 적지만 `server-state-generation-store.ts:50-57`이 세대마다 새로 만든다. `:119` 표도 "registered pulse, storageArea"를 미구현으로 둔다. 문서 마지막 수정 2026-08-01, host 코드 마지막 수정 2026-09-24 |
| 발생 조건 | 다운스트림이 문서로 지원 범위를 판단할 때 |
| 영향 | 이미 있는 기능을 다시 구현하거나, 반대로 남은 미구현(session/account epoch)을 구분하기 어렵다 |
| 심각도·우선순위 | Low · P3 — 실제보다 적게 주장하는 방향이라 위험은 작다 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 코드와 문서 대조로 확정 |
| 최소 개선 방향 | 해당 문단과 표 한 행을 현재 코드에 맞춘다 |
| 비용·부작용 | 문서 수정 |
| 완료 기준 | 문서의 현재 상태 설명이 코드와 일치한다 |
| 검증 방법 | `verify:documentation` 범위에 포함되는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | 목표 M2 / 확인 M2 — 정책 깊은 snapshot, 닫힌 실패 코드, 조립 시 상한 검증 | E1, E2 | 부분 충족 — preview abort 계약 위반(02-01) |
| 2 | 구조적 성숙도 | 적용 | M3 목표 — adapter 간 import는 kernel(`browser-file-storage/result.ts`, `platform/abortable-operation.ts`)만, 외부는 port·contracts | E1(import 전수 확인) | 충족 — 게이트 실행은 오케스트레이터 |
| 3 | 변경 용이성 | 적용 | M2 — 새 파일 정책은 composition의 profile 추가, 새 topic은 registry 추가 | E1 | 충족 |
| 4 | 인지 부하 | 적용 | — | E1 | 부분 충족 — 본 파일 2개가 각 1.1k줄대, 주석에 리뷰 ID(Q-6.2-x, STO-RR-05, TR-RR-04)가 많아 규칙보다 이력을 먼저 읽게 된다 |
| 5 | 위험 가시성 | 적용 | M1~M2 — `BROWSER_HANDOFF`/`SAVED`, `integrity: NOT_PROVIDED`, 닫힌 recovery 어휘 | E1 | 부분 충족 — 02-01(abort 계약 불명), 02-05 |
| 6 | 실패 성숙도 | 적용 | M2 — 취소·abort·권한 거부를 Result에서 구분, 늦은 자원 보상 | E1, E2 | 부분 충족 — 02-04(재시도 의미), 02-06(관측). picker는 cancel·focus가 모두 안 오는 엔진에서 signal이 없으면 `BLOCKED`로 남을 수 있음(현 지원 엔진에서는 미확인) |
| 7 | 운영 성숙도 | 적용(연결점) | M2 — file·cache·cross-context observer, cross-context는 bootstrap이 diagnostics로 연결(`runtime-adapters.ts:358-373`) | E1 | 부분 충족 — file·cache observer는 recipe 조립 몫 |
| 8 | 디버깅 가능성 | 적용 | M2 — 개인정보 없는 닫힌 관측(파일명·URL·키 미포함) | E1 | 부분 충족 — 02-05, 02-06 |
| 9 | 유지보수 성숙도 | 적용 | M1 | E1 | 부분 충족 — 02-09 문서 불일치 |
| 10 | 테스트 성숙도 | 적용 | M3 목표 | E2(121 통과), 변이 22개: 검출 11, 동등 4, 미검출 규칙 6 | 부분 충족 — 02-02, 02-08. 실제 브라우저 spec은 미실행 |
| 11 | 데이터 성숙도 | 적용 | M2 — Cache Storage는 익명 공개 응답만, 로그아웃 purge 불필요 | E1 | 부분 충족 — 규칙 테스트 없음(02-02), file runtime scope 미연결(02-03) |
| 12 | 동시성 성숙도 | 적용 | M3 — 탭 간 중복·역순·gap, 캐시 변경은 Web Lock, picker별 pending | E2(cross-tab 17개 테스트) | 부분 충족 — 02-01(같은 turn abort 경쟁). stage 후 activate 전 cleanup이 candidate를 지우는 창은 설계상 허용·문서화됨(`browser-file-and-origin-storage.md` 8.3절) |
| 13 | 확장성 | 적용(구조) | M2 — source 256·dedupe 1024 LRU, profile ≤128, entry ≤500 | E1 | 충족 — 부하 측정 없음 |
| 14 | 성능 성숙도 | 적용 | M2 — 모든 바이트·개수 상한 | E1, E2 | 부분 충족 — 02-07, 02-04. `BOUNDED_OBJECT_URL`은 chunk 복사+Blob 생성으로 최대 약 2×`maxBufferedBytes`가 잠시 필요(문서 식의 copy factor에 값이 없음) |
| 15 | 보안 성숙도 | 적용 | M2 — 파일명 무력화, MIME은 signature 기준, active content 금지, 불투명 참조, canonical handoff URL, 캐시 익명 요청 | E1, 변이 실험 | 부분 충족 — 규칙 일부가 테스트로 고정되지 않음(02-02, 02-08). download 정책의 `safeExtension`·`mediaType` 위험값(`.html`, `text/html`)은 composition 신뢰로 허용(문서화된 선택) |
| 16 | 의존성 성숙도 | 적용 제외 — 세 폴더 모두 외부 패키지 import 없음(브라우저 API와 repo 내부 모듈만) | — | E1 | 적용 제외 |
| 17 | API / Contract 성숙도 | 적용 | M2 — port 타입, wire protocol version·크기·TTL·epoch 검사 | E1, E2 | 부분 충족 — 02-05, 02-09. `DownloadOutcome` 타입에 의미 주석이 없어 설계 문서를 봐야 함 |
| 18 | 배포 성숙도 | 적용 | M2 — release별 cacheEpoch, 캐시 release stage/activate/이전 release 보존 | E1 | 부분 충족 — release가 다른 탭끼리는 무효화 hint가 오가지 않음(설계상 선언, focus refetch가 완화) |
| 19 | 설정 성숙도 | 적용 | M3 — 잘못된 상한·정책은 조립 시 TypeError | E2 | 충족 |
| 20 | 개발자 경험 | 다른 영역 — 전체 DX는 오케스트레이터/문서 영역 | — | — | 적용 제외 |
| 21 | Guardrail 성숙도 | 적용 | eslint·dependency-cruiser·`check:optional-recipes` 대상에 포함(`eslint.config.ts:521-524`, `:684-687`) | E0(이번에 실행 안 함) | 미검증 — 게이트 결과는 오케스트레이터 |
| 22 | 추상화 성숙도 | 적용 | — | E1 | 부분 충족 — 네이티브 API를 조립 시 bind·snapshot하는 facade는 목적이 분명함. lease registry 공유가 preview와 download의 한도를 묶음(02-04) |
| 23 | 일관성 | 적용 | — | E1 | 부분 충족 — preview만 await 뒤 abort를 다시 보지 않음(02-01). cache 관측(`PublicCacheSafeObservation`, bucket `1B_1MiB`)과 file 관측(`BrowserDataObservation`, bucket `LT1MIB`)의 어휘가 다름 |
| 24 | 네이밍 / 의미 | 적용 | — | E1 | 부분 충족 — `deliver`의 결과 `BROWSER_HANDOFF`/`SAVED`, `matchActiveExact`, `cleanupOwned`는 보장과 맞음. `inspect().verified`만 과장(02-05) |
| 25 | 조직 확장성 | 적용 제외 — 1인 관리. 구조적 준비만: feature별 정책 reference, topic registry | — | E1 | 적용 제외 |
| 26 | Ownership | 다른 영역 — recipe owner는 `project-owner-required` | — | E1 | 적용 제외 |
| 27 | 삭제 가능성 | 적용 | M3 목표 — topic 0개면 host가 브라우저 기능을 조회조차 안 함(`browser-cross-context-host.ts:62`), recipe 제거 스크립트 존재 | E1 | 미검증 — `test:browser-file-storage-removal`·`check:optional-recipes` 미실행 |
| 28 | 회복 가능성 | 적용 | M2 — 캐시 이전 release 보존·재활성화, `REHYDRATE` 복구 코드, GAP 시 전체 무효화 | E1, E2 | 부분 충족 — 실제 브라우저 eviction 뒤 복구는 미확인 |
## 6. 미검증 목록
| 항목 | 확인하려면 |
|---|---|
| 실제 Chromium·Firefox·WebKit에서 picker·download·Cache API·BroadcastChannel/storage fallback 동작 | `test:browser-capabilities`를 현재 커밋에서 3개 엔진으로 실행하고 결과 보존 |
| Safari에서 blob URL 다운로드 30초 grace가 충분한지, runtime dispose 직후 handoff가 살아남는지 | WebKit 실제 다운로드 실험 |
| 다른 탭에서 계정이 바뀐 뒤 이 탭이 받는 무효화 hint가 이전 사용자 세대 캐시에 새 세션 응답을 채우는지 | auth 영역의 탭 간 세션 변경 감지 여부 확인 후 2탭 E2E(탭 A 로그아웃·B 로그인 → 탭 B mutation → 탭 A 상태 확인) |
| picker의 `cancel`·window `focus`가 모두 오지 않는 엔진 존재 여부(있다면 signal 없는 `select()`가 `BLOCKED`로 남음) | 지원 브라우저 목록 확정 후 실기기 확인 |
| Chrome `showSaveFilePicker`가 확정 시 빈 파일을 먼저 만드는지(이후 source 실패 시 0바이트 파일 잔존) | Chromium 실기 실험 |
| 캐시 조회 비용(02-07)의 실제 지연·메모리 | SW 소비자를 붙인 뒤 asset 수·크기별 측정 |
| 삭제 가능성·guardrail 게이트 | `check:optional-recipes`, `test:browser-file-storage-removal`, `check:architecture` 실행(오케스트레이터) |
@@ -0,0 +1,248 @@
# HTTP·서버 상태·인증·진단 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/adapters/http/`(4.6k줄), `src/adapters/browser-rpc/`(2.0k줄), `src/adapters/query-cache/`(1.1k줄), `src/adapters/auth/`(0.2k줄), `src/adapters/diagnostics/`(0.1k줄), `src/adapters/telemetry/`(0.5k줄) — 약 8.5k줄. 흐름 추적을 위해 조합 루트(`src/bootstrap/runtime-adapters.ts`, `server-state-generation-store.ts`), reference feature의 HTTP 경로, `presentation/adapters/query/application-query.ts`의 mutation 경로를 함께 읽었다.
> 영역 판정(35.8): **조건부 사용 가능** — 조회(query)·로그아웃·인증 세대·전송 상한은 그대로 복제해도 된다. 쓰기(command) 샘플은 03-01을 고치기 전까지 "결과 불명 쓰기의 처리 방식" 예제로 복제하지 않는다.
## 1. 결론
- **조회 경로는 튼튼하다.** V3 실행기는 전체 마감 하나, 재시도 권한 하나, 응답 본문 상한, 인증 세대 확인(전송 전·응답 후)을 모두 갖췄다. 로그아웃 중 도착한 응답은 버려지고, 세대마다 QueryClient를 새로 만든다. 핵심 규칙 4개에 일부러 결함을 넣었을 때 테스트가 모두 잡았다.
- **결과 불명인 쓰기의 복구가 비어 있다(03-01, High).** 계약은 `commandRecovery: IDEMPOTENCY_REPLAY`(같은 키로 다시 보내기)를 선언하지만 실행하는 코드가 없다. 화면은 사용자에게 "변경됨/변경되지 않음"을 **추측**하게 하고, 다시 저장하면 **새 멱등 키**가 만들어진다. 504 같은 응답 유실 뒤에 중복 생성이 가능하다. 설계 문서(§8.8~8.9)와 runbook(6.3-4)이 금지한 동작이다.
- **명령의 401/403/429가 무조건 "결과 불명"이 된다(03-02).** 세션 만료 중 저장하면 "재로그인" 대신 "지원 문의"가 뜨고, 429는 03-01의 추측 화면으로 이어진다.
- **문의 식별자가 서버 기록까지 이어지지 않는다(03-03).** V3는 응답의 `x-correlation-id`를 읽고 버린다. 기본 요청에는 요청 식별자 헤더도 없다. V2에는 있던 연결이 권장 경로(V3)에서 끊겼다.
- 나머지: V3로는 422 필드 오류가 폼까지 가지 못한다(03-04). 텔레메트리 배치 크기가 브라우저 keepalive 한도(64KiB)와 맞지 않는다(03-05, 3개 엔진에서 거절 재현).
- 미검증: 실제 백엔드의 멱등 키 보관·충돌 처리, 외부 auth owner의 갱신 동작, 여러 탭 동시 로그아웃, 게이트웨이 리다이렉트형 세션 만료.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 리뷰 가이드뿐 |
| 목적과 실행 구성 | 프론트엔드 템플릿. 브라우저 SPA, SSR 없음. 인증 `demo`/`external`. 여러 탭 지원 |
| 읽은 코드 | 범위 6개 폴더 전체. 추가로 `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/server-state-generation-store.ts`, `src/contracts/errors.ts`, `src/contracts/external-contract-runtime.ts`(계약 검증부), `src/platform/telemetry/trace-context.ts`, `src/adapters/platform/browser-mutation-intent-factory.ts`, reference feature(`contracts/`, `adapters/`, `application/`, `presentation/`), `src/presentation/adapters/query/application-query.ts`(mutation 부분), `src/presentation/forms/{form-contracts,use-app-form}.ts`, `src/presentation/components/async-surface.tsx` |
| 읽은 문서 | `docs/operations/api-contract-and-server-state-recovery.md`, `docs/architecture/starter-experience.md`(외부 owner), `docs/architecture/decisions/VD-07-*.md`, 설계서 `2026-07-30-...-closed-deep-design.md` §4.4, §8.3~8.10 |
| 실행한 테스트 | `node scripts/run-vitest.ts run` 로 영역 테스트 45개 파일(unit: http·bridge·retry·scope·coordinator·telemetry·auth·cursor·conditional·body-reader·query-cache·diagnostics·browser-rpc·runtime-adapters, integration: `http-*`·`auth-recovery`·`legacy-http-credential-authority`, contract: `feature-http-binding`, `tests/features/reference-feature`) → **45 passed / 480 tests passed** |
| 결함 주입 실험 | 분리 worktree에서 7개 변형 → 결과는 아래 표. 실험 후 worktree 삭제 |
| 브라우저 실험 | Playwright(chromium·firefox·webkit)로 로컬 서버에 `telemetry-collector.ts`와 같은 옵션(`keepalive:true`, JSON POST)을 보냄 → 60KB 성공, 70KB는 **세 엔진 모두 거절**, 40KB 두 개 동시 전송은 chromium·firefox에서 둘 다, webkit에서 하나 거절 |
| 측정 | `api.request.failed` 이벤트 1건 직렬화 288B, 100건 배치 28.9KB(`projectTelemetryEvent` 실제 출력) |
| 확인하지 못한 범위 | 실제 백엔드·외부 auth owner·RPC provider와의 통합, 여러 탭 동시 시나리오, 브라우저에서 앱 전체를 띄운 E2E(다른 영역 담당) |
| 이전 리뷰와 비교 | `2026-09-24-src-full-review.md` 6.3-1~12를 현재 코드에서 다시 확인했다. 모두 고쳐졌다(아래) |
결함 주입 결과(관점 10):
| 변형 | 결과 |
|---|---|
| M1 응답 검증 뒤 scope 확인 제거(`http-execution-v3.ts:1341`) | 통과(생존). 같은 경우를 lifetime signal 경로(`:992`)가 먼저 잡는 중복 방어라 실제 위험은 아님 |
| M2 `MAYBE_APPLIED` 응답도 재전송 허용(`:999`) | 검출 — `http-execution-v3.test.ts` |
| M3 요청 전 미인증에도 `onUnauthenticated` 호출(`runtime-adapters.ts:543`) | 검출 — `reference-runtime-composition.test.ts` |
| M4 같은 (상태, 주체) 알림에도 fence(`server-state-scope-runtime.ts:102`) | 검출 — 3건 |
| M5 경로 값 `.`/`..` 검사 제거(`http-contract-bridge.ts:203`) | 검출 — 2건 |
| M6 KEYED를 전송 후에도 재시도(`http-retry-lifecycle.ts:27`) | 실행기 테스트는 생존, 순수 함수 단위 테스트(`http-retry-lifecycle.test.ts`)만 검출 |
| M7 응답 `x-correlation-id` 수집 제거(`http-execution-v3.ts:1590`) | 생존 — 소비자가 없어 아무것도 깨지지 않음(03-03 근거) |
직전 리뷰(6.3) 재확인: 6.3-1(`http-contract-bridge.ts:200-208`, `request-builder.ts:73-86`), 6.3-2(`server-state-scope-runtime.ts:96-108`, `runtime-adapters.ts:543`, `external-session-adapter.ts:122-128`), 6.3-3(`feature-http-binding.ts:378-397`), 6.3-4(`http-contract-bridge.ts:58`, `:393-399`), 6.3-5(`feature-http-binding.ts:300-333`), 6.3-6(`http-execution-v3.ts:603-619`), 6.3-7(`:995-1037`), 6.3-8(`tanstack-cache-coordinator.ts:79-92`), 6.3-9(`browser-rpc-runtime.ts:303-309`, `:357-371`), 6.3-10(`telemetry-collector.ts:77-105`), 6.3-11(`client.ts:340-344`), 6.3-12(`cursor-pagination-runtime.ts:112-126`, `conditional-validator-store.ts:139-151`) 모두 수정 확인. 6.3-4의 잔여로 auth 어댑터의 자체 검증(`external-session-adapter.ts:31-56`, CR/LF만 검사)이 bridge와 규칙이 다르게 남아 있지만, bridge가 전송 전에 최종 판정하므로 결과는 안전하다. 별도 항목으로 올리지 않는다.
## 3. 확인된 강점
1. **대기 전체를 하나의 마감과 하나의 재시도 권한이 관리한다.** 자격증명 조회, 동시성 lease, fetch, 본문 읽기, 백오프가 모두 같은 lifetime signal과 경쟁한다(`http-execution-v3.ts:519-564`, `:713-723`, `:922-926`, `:967-989`). 재시도 상한은 `min(계약 retryBudget, MAX_RETRY_ATTEMPTS, 하드 상한 2)`이다(`:792-796`). TanStack의 query·mutation 재시도는 꺼져 있어 중첩 재시도가 없다(`tanstack-query-cache.ts:12-19`). `Retry-After`는 5초를 넘으면 기다리지 않고, 기다릴 때도 jitter를 더해 동시 재시도를 흩는다(`http-retry-lifecycle.ts:54-66`). `REQUEST_TIMEOUT_MS`는 계약 마감을 줄일 수만 있다(`http-execution-v3.ts:428-433`).
2. **인증 세대(로그인 상태가 바뀌기 전후를 구분하는 클라이언트 내부 번호)가 실제로 늦은 응답을 막는다.** (상태, 주체)가 바뀔 때만 세대를 올리고, 진행 중 요청을 abort하고, QueryClient를 통째로 새로 만든다(`server-state-scope-runtime.ts:96-179`, `server-state-generation-store.ts:50-58`). V3는 전송 직전과 응답 검증 뒤에 세대를 다시 확인한다(`http-execution-v3.ts:813-819`, `:882-906`, `:1341-1346`). 서버 401만 세션 판정으로 넘긴다(`runtime-adapters.ts:540-545`). 빠른 필터 변경은 필터별 query key로 분리돼 늦은 응답이 현재 화면을 덮지 않는다.
3. **쓰기 결과의 확실성을 타입으로 나눈다.** 전송 시점부터 `MAYBE_APPLIED`로 올라가고 내려가지 않는다(`http-effect-certainty.ts:36-73`, `http-execution-v3.ts:916-921`). `MAYBE_APPLIED` 응답은 자동 재전송하지 않는다(`:995-1003`). `createFailure`는 `MAYBE_APPLIED`면 `retryable:false`로 바꾼다(`contracts/errors.ts:292-296`).
4. **자격증명 경계가 좁다.** 설치된 auth profile이 `credentials` 모드와 허용·필수 헤더를 정한다. 값은 ByteString으로 검사하고 `new Headers()`로 미리 만들어 본다(`http-contract-bridge.ts:58-106`, `:344-410`). 요청은 `redirect:"error"`, `referrerPolicy:"no-referrer"`, `cache:"no-store"`로 나간다(`http-execution-v3.ts:869-880`). 브라우저 HTTP 캐시에 사용자 응답이 남지 않는다. 토큰 보관은 외부 owner 책임이고(`docs/architecture/starter-experience.md:52-68`), demo는 비밀이 아닌 고정 marker를 쓴다(`external-session-adapter.ts:106`).
5. **텔레메트리 라벨은 값 종류가 끝없이 늘어나지 않는다.** 속성은 닫힌 allowlist와 값 문법을 통과해야 한다(`contracts/telemetry.ts:4-13`, `:110-132`). HTTP projector는 route/operation ID와 버킷만 보낸다(`runtime-adapters.ts:233-240`). 수집기 전송은 타임아웃·`credentials:"omit"`·전송률 제한을 공유한다(`telemetry-collector.ts:48-105`).
6. **응답 본문을 순서대로 제한한다.** 선언 길이 → 스트림 누적 바이트 → JSON 구조 예산 → 스키마 검증 순이다(`bounded-body-reader.ts:57-110`, `http-execution-v3.ts:1230-1338`). 오류 본문은 64KiB로 따로 제한한다(`:1474-1478`).
## 4. 발견 사항 (36.3)
### 03-01 결과 불명인 KEYED 쓰기: 선언된 "같은 키 재전송" 복구가 없고, 사용자 추측 뒤 새 멱등 키로 다시 보낸다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 12, 17, 24, 28, 5 |
| 근거 | ① reference 생성 계약이 `retrySemantics:"KEYED"`, `commandRecovery:{mode:"IDEMPOTENCY_REPLAY", operationIdentityField:"idempotencyKey"}`를 선언한다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:169-176`). ② 이 descriptor는 설치 때 존재 여부만 검사되고(`src/contracts/external-contract-runtime.ts:473-485`) 실행 코드가 읽는 곳이 없다(grep: 그 외 소비처는 예제 화면 표시 `src/presentation/examples/platform-overview-page.tsx:272`뿐). ③ `MAYBE_APPLIED`가 되면 화면은 "변경 결과를 확인할 수 없습니다" + "변경됨으로 확인 / 변경되지 않음으로 확인" 버튼만 준다(`src/presentation/components/async-surface.tsx:155-167`, `src/presentation/i18n/catalog.ts:14-15`, `:60`). 사용자가 서버 상태를 확인할 수단은 없다. ④ "변경되지 않음"을 누르면 폼 값이 그대로 남고(`src/presentation/forms/use-app-form.ts:170-176`) 다시 저장하면 `submit`마다 새 intent를 만든다(`src/presentation/adapters/query/application-query.ts:509-514`). 키는 매번 `randomUUID()`다(`src/adapters/platform/browser-mutation-intent-factory.ts:36-40`). ⑤ 설계서는 "같은 submit의 transport retry/reconcile에는 동일 intent/key, form value가 변경되면 새 intent"(`docs/architecture/2026-07-30-...-closed-deep-design.md:1707-1708`)와 "recovery descriptor 확인 → inspect → no effect일 때만 사용자 재시도"(`:1714-1724`)를 요구하고, runbook은 "`UNKNOWN` effect에 새 key를 생성해 retry하지 않는다"(`docs/operations/api-contract-and-server-state-recovery.md:228`)고 적는다 |
| 발생 조건 | 생성 요청이 서버에 도착한 뒤 응답을 잃는다: 게이트웨이 504(빈 본문), 네트워크 끊김, 전체 마감 초과(`http-execution-v3.ts:1479-1491`, `:916-921`). 사용자가 "변경되지 않음"을 누르고 같은 값으로 다시 저장한다. 03-02의 401/403/429도 같은 화면으로 들어온다 |
| 영향 | 첫 요청이 실제로 반영됐으면 서버에 같은 리소스가 두 번 생긴다. 서버가 멱등 키를 지원해도 키가 달라 막을 수 없다. 반대로 "변경됨"을 잘못 고르면 사용자의 입력이 저장된 것으로 처리돼 사라진다(`use-app-form.ts:164-168`). 탐지가 어렵다(사용자는 성공한 줄 안다). |
| 심각도·우선순위 | High · P1 — 지원하는 장애 조건(응답 유실)에서 쓰기 중복이 가능하고, 가이드 35.2의 "결과 불명 작업의 무방비 재실행"에 해당한다. 유일한 쓰기 샘플이라 다운스트림의 모든 KEYED 명령에 그대로 복제된다. 즉시 피해가 난 증거는 없으므로 P0는 아니다 |
| 통제·증거 | M1(설계서·runbook에 규칙 명시, 구현 없음) · E1(정적 확인. 이 경로를 재현하는 테스트는 없다) |
| 확실성과 남은 가정 | 코드 경로는 확정. 실제 중복 생성 여부는 백엔드가 키 없이 같은 입력을 두 번 받아들이는지에 달려 있다(도메인 유일성 제약이 있으면 409로 끝난다) |
| 최소 개선 방향 | ① `UNKNOWN` 상태의 admission이 가진 intent를 보관하고, 같은 입력으로 다시 저장하면 **그 intent(같은 `Idempotency-Key`)로** 보낸다. 이것이 `IDEMPOTENCY_REPLAY`의 최소 구현이다. ② `INSPECT_OPERATION` descriptor가 없으면 "변경되지 않음으로 확인" 버튼을 없애거나 "같은 요청으로 다시 보내기"로 바꾼다. 대안: 목록 재조회로 사용자가 확인하게 하는 링크(서버 조회 없이 추측하게 두는 것보다 낫다) |
| 비용·부작용 | presentation mutation 코디네이터와 intent 수명 변경(영역 08과 겹침). 서버 멱등 키 보관 기간보다 늦은 재전송은 여전히 중복될 수 있어 그 한계를 문서에 적어야 한다 |
| 완료 기준 | `MAYBE_APPLIED` 뒤 같은 입력의 재전송이 첫 요청과 같은 `Idempotency-Key`를 보낸다. 입력이 바뀌면 새 키. 근거 없는 "변경되지 않음" 확정 경로가 없다 |
| 검증 방법 | 모의 서버: 첫 POST에 504 빈 본문 → 화면에서 재시도 → 두 요청의 `Idempotency-Key` 헤더가 같은지 단언하는 통합 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음(6.7-1은 키 공백 문제로 별개) |
### 03-02 명령의 401/403/429가 패키지 분류기를 거치지 않고 `MAYBE_APPLIED`로 고정돼, 세션 만료 저장이 "지원 문의"로 끝난다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(설계 원칙과 사용자 행동 계약의 충돌) |
| 관련 관점 | 6, 15, 17, 5 |
| 근거 | 401·403·429는 `admitProblem`/`classifyProblemEffect`에 가기 전에 처리되고 명령이면 `certaintyForAbandonedAttempt("RESPONSE_HEADERS")` = `MAYBE_APPLIED`가 된다(`src/adapters/http/http-execution-v3.ts:1147-1180`). 패키지 분류기(`CommandEffectDescriptor.classifyProblem`)는 이 세 상태를 볼 기회가 없다. 바인딩은 `AUTH_REQUIRED`에 이 effect를 실어 보내고(`feature-http-binding.ts:341-344`), `createFailure`는 `MAYBE_APPLIED`면 action을 `contact-support`로 덮는다(`contracts/errors.ts:315-320`). 테스트 카탈로그가 이 값을 고정한다(`tests/mocks/scenarios/catalog.ts`의 `unauthenticated-401`·`forbidden-403`·`rate-limited-429` 명령 기대값 `MAYBE_APPLIED`) |
| 발생 조건 | 저장 중 토큰 만료(401), 권한 회수(403), 요청 제한(429) |
| 영향 | 32절 "세션 만료" 시나리오의 다음 행동이 "재로그인"이 아니라 "지원 문의"다. 외부 owner가 같은 주체로 조용히 갱신하면(세대 fence 없음) 401이 03-01의 추측 화면으로 들어간다. 429는 거의 항상 "처리 안 됨"인데도 사용자에게 추측을 요구한다. 데이터 손상은 없고 사용자 행동이 틀어진다 |
| 심각도·우선순위 | Medium · P2 — 흔한 조건(세션 만료)에서 안내가 틀리고 03-01의 발생 빈도를 키운다. 보수적 기본값 자체는 설계 원칙(`http-effect-certainty.ts:9-11`)이라 High로 올리지 않는다 |
| 통제·증거 | M2(의도된 구현) · E2(카탈로그 테스트 통과) |
| 확실성과 남은 가정 | 경로 확정. 실제 서버가 401/403/429에서 쓰기를 반영하지 않는다는 점은 서버 계약에 달려 있어, 그 판단을 패키지 분류기에 맡기자는 것이 제안의 요지다 |
| 최소 개선 방향 | `CommandEffectDescriptor`에 본문 없는 상태용 분류(예: `classifyStatus(status)`)를 선택적으로 추가해 401/403/429도 패키지가 판정하게 한다. 없으면 지금처럼 `MAYBE_APPLIED`. 별도로 `AUTH_REQUIRED`는 effect와 무관하게 `reauth`를 먼저 안내한다 |
| 비용·부작용 | 계약 타입 1개 필드 추가, 카탈로그 기대값 조정 |
| 완료 기준 | reference 생성 계약이 401/429를 `NOT_APPLIED`로 선언하면 화면이 재로그인/재시도를 안내하고 unknown 화면이 뜨지 않는다 |
| 검증 방법 | 시나리오 카탈로그의 명령 401/429 기대값 변경 + mutation 화면 컴포넌트 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 03-03 권장 경로(V3)에서 문의 식별자 → 서버 기록 연결이 끊겼다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 7 |
| 근거 | V3는 응답의 `x-correlation-id`를 `metadata.correlationReference`로 읽지만(`http-execution-v3.ts:1583-1595`) 이 값을 쓰는 곳이 src 전체에 없다(grep: 정의 `:75`와 대입 `:1591`뿐). 바인딩의 `failure()`는 `requestId`를 넘기지 않고(`feature-http-binding.ts:437-450`), projector도 diagnostics에 correlation을 넣지 않는다(`runtime-adapters.ts:233-250`). VD-07은 diagnostics에 correlation ID를 허용한다(`docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md` 결정 4). 요청 쪽도 비어 있다: `x-correlation-id`/`traceparent`는 `context.execution.trace`가 있을 때만 붙는데(`http-execution-v3.ts:786-790`) 운영 코드에서 trace를 가진 ExecutionContext를 만드는 곳이 없다(`createExecutionContext` 호출은 실행기 내부 `:461-475`뿐, trace 없음). 결과적으로 `AppFailure.requestId`(`contracts/errors.ts:254`)는 V3에서 항상 비고, "지원 문의" 화면은 고정 문자열 `REFERENCE-STATUS-DEMO`를 보여 준다(`reference-resource-status-page.tsx`). V2는 매 요청 `X-Correlation-ID`를 보내고 `requestId`를 채운다(`client.ts:599-602`, `:1008`). 결함 주입 M7(수집 제거)이 어떤 테스트도 깨지 않았다 |
| 발생 조건 | V3로 실행된 모든 요청의 실패 문의 |
| 영향 | 사용자 문의나 프론트 오류 한 건을 서버 로그의 요청 한 건과 이을 수 없다. 원인 좁히기가 시각·경로 추정에 의존한다 |
| 심각도·우선순위 | Medium · P2 — 가이드 35.2 Medium의 "주요 진단 정보 부족". 기본 경로라 모든 다운스트림에 복제된다 |
| 통제·증거 | M0(V3 경로의 연결 수단 없음) · E1 + E2(M7 생존) |
| 확실성과 남은 가정 | 확정. 서버가 `x-correlation-id`를 돌려주는지는 백엔드 계약에 달렸다 |
| 최소 개선 방향 | ① 바인딩에서 `metadata.correlationReference`를 `requestId`로 넘긴다. ② 논리 실행마다 요청 식별자 하나를 만들어 `x-correlation-id`로 보낸다(암묵 ExecutionContext의 `interactionId`는 지금 상수 `"implicit-operation"`이라 그대로 쓰면 안 된다). ③ projector diagnostics에 `correlation_id`를 넣는다(telemetry에는 넣지 않는다) |
| 비용·부작용 | 헤더 1개 추가로 CORS 허용 헤더에 `x-correlation-id`가 필요하다 |
| 완료 기준 | V3 실패의 `AppFailure.requestId`가 서버 응답 헤더 값과 같다. 매 요청에 요청 식별자가 있다 |
| 검증 방법 | 모의 서버가 `x-correlation-id`를 돌려주는 실패 시나리오에서 바인딩 결과·diagnostics 기록을 단언 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 03-04 V3로는 서버 422 필드 오류가 폼까지 가지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 17, 3, 22 |
| 근거 | 기능의 문제 매핑 타입이 `{ kind, code }`뿐이다(`feature-http-binding.ts:73-76`). 바인딩은 `validationIssues`를 채우지 않는다(`:327-340`, `:437-450`). reference 문제 스키마는 `type/title/status/code` 외를 버린다(`reference-schemas.ts:41-48`). 폼은 `validationIssues`가 비면 일반 문구만 낸다(`presentation/forms/form-contracts.ts:63-67`). 그런데 reference 폼은 서버 필드 매핑(`allowedServerFields: ["name","note"]`, `reference-resource-form-page.tsx:40`)과 "422 정책을 실행합니다"(`:76`)를 보여 준다. 필드 매핑 테스트는 `createFailure`로 issues를 직접 만든 실패를 넣어서 V3를 거치지 않는다(`tests/component/form-foundation.test.tsx:118-124`) |
| 발생 조건 | 서버가 422에 필드별 오류를 돌려줄 때 |
| 영향 | 사용자는 어느 필드가 틀렸는지 모른다. 다운스트림은 샘플이 동작한다고 믿고 복제한 뒤 바인딩 계약을 따로 넓혀야 한다 |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없지만 모든 폼 기능에서 반복 비용이 생기고, 샘플의 주장과 실제 동작이 다르다 |
| 통제·증거 | M0 · E1 |
| 확실성과 남은 가정 | 확정 |
| 최소 개선 방향 | `FeatureHttpProblemMapping`에 선택 필드 `validationIssues`를 추가하고 바인딩이 `projectValidationIssues`로 한정해 넘긴다. reference 문제 스키마에 상한 있는 `issues`를 추가한다 |
| 비용·부작용 | 공개 타입 1개 확장(기존 기능은 영향 없음) |
| 완료 기준 | 모의 서버 422(필드 오류 포함) → V3 → 바인딩 → 폼에서 해당 필드 오류 표시 |
| 검증 방법 | reference feature 통합 테스트 1건 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 03-05 텔레메트리 배치 크기가 브라우저 keepalive 한도(64KiB)와 맞지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 7, 14 |
| 근거 | 수집기는 모든 POST에 `keepalive:true`를 붙인다(`src/adapters/telemetry/telemetry-collector.ts:88-96`). Fetch 표준은 진행 중인 keepalive 요청 본문 합이 64KiB를 넘으면 네트워크 오류로 끝낸다. 반면 기능 텔레메트리 예산은 버퍼 256KiB·배치 50건이고(`src/platform/telemetry/telemetry-pipeline.ts:56-65`), 이벤트 하나는 키 64개·문자열 256자까지 허용한다(`redact-telemetry.ts:16-22`). 애플리케이션 큐는 한 번에 최대 100건을 보낸다(`best-effort-telemetry.ts:79`, `:203`). `pagehide`에는 두 큐가 동시에 보낸다(`:224-226`, `feature-telemetry.ts:104-106`). 실험: 70KB 단일 POST는 chromium·firefox·webkit 모두 거절, 40KB 두 개 동시 전송은 chromium·firefox에서 둘 다 거절. `api.request.failed` 100건 배치는 28.9KB라 기본 샘플만으로는 한도에 닿지 않는다 |
| 발생 조건 | 기능 이벤트 페이로드가 평균 약 1.3KB를 넘거나, 페이지 이탈 때 두 큐의 합이 64KiB를 넘을 때 |
| 영향 | 배치 전체가 `sink-failure`로 버려진다. 장애로 이벤트가 몰릴 때 가장 크게 잃는다. 버린 수는 집계된다(`best-effort-telemetry.ts:112-141`) |
| 심각도·우선순위 | Medium · P3 — 관측 손실이지만 기본 샘플에서는 발생하지 않는다 |
| 통제·증거 | M0(64KiB 기준의 크기 제한 없음) · E3(실험실 브라우저 3종) |
| 확실성과 남은 가정 | 거절 동작은 재현했다. 실제 기능 페이로드 크기는 다운스트림에 달렸다 |
| 최소 개선 방향 | 수집기에서 직렬화한 본문을 약 60KiB 이하로 나눠 보내거나, `keepalive`는 `pagehide` flush에만 쓰고 그 배치만 제한한다 |
| 비용·부작용 | 수집기 함수 하나 수정 |
| 완료 기준 | 64KiB를 넘는 큐가 여러 POST로 나뉘어 모두 전달된다 |
| 검증 방법 | 단위 테스트: 70KB 분량 이벤트 → 각 POST 본문이 한도 이하인지 단언 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 03-06 "KEYED" 재시도 규칙과 `REQUEST_TIMEOUT_MS`의 의미가 전송마다 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 23, 6, 19, 4 |
| 근거 | V3는 KEYED 명령을 전송 후 자동 재시도하지 않는다(`http-retry-lifecycle.ts:21-34`). V2는 keyed를 타임아웃·5xx 뒤 같은 키로 다시 보낸다(`retry-policy.ts:38-60`, `client.ts:263-306`). Browser RPC도 `KEYED_COMMAND`를 같은 키로 재시도한다(`browser-rpc-runtime.ts:1513-1527`). `Retry-After` 상한도 V3 5초·V2 30초·RPC 프로필값으로 다르다. `REQUEST_TIMEOUT_MS`는 V3에서 상한(`runtime-adapters.ts:469`), V2에서 기본값이라 오퍼레이션이 더 길게 잡을 수 있다(`client.ts:154`, `:212`) |
| 발생 조건 | 오퍼레이션을 V2↔V3↔RPC로 옮기거나, 같은 설정으로 두 경로를 함께 쓸 때 |
| 영향 | 같은 이름의 정책이 중복 쓰기 동작을 조용히 바꾼다. 읽는 사람이 세 규칙을 따로 기억해야 한다 |
| 심각도·우선순위 | Low · P3 — V2는 기본 구성에서 조합되지 않고(`createRuntimeHttpClient` 호출처 없음) 각 규칙은 따로 보면 방어 가능하다 |
| 통제·증거 | M1(각 파일 주석) · E1 |
| 확실성과 남은 가정 | 확정 |
| 최소 개선 방향 | 전송별 KEYED 재시도·Retry-After·타임아웃 의미를 한 표로 문서화하고, V2 `timeoutMs` 옵션 설명에 "상한 아님"을 적는다 |
| 비용·부작용 | 문서 변경 |
| 완료 기준 | 한 곳에서 세 전송의 규칙을 비교할 수 있다 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 03-07 요청 전에 거절된 미인증(전송 0회)이 `api.request.failed`로 집계된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 7 |
| 근거 | 자격증명이 없으면 fetch 없이 `UNAUTHENTICATED`(metadata 없음)가 된다(`http-execution-v3.ts:740-743`). `isTerminalNonAbortFailure`는 이 경우를 걸러내지 않아 `api.request.failed`를 보낸다(`runtime-adapters.ts:279-294`). 같은 파일은 이 결과를 "세션 판정이 아니다"라며 로그아웃 알림에서는 제외한다(`:540-545`) |
| 발생 조건 | 로그아웃·`recovery-pending` 상태에서 인증 필요 쿼리가 실행될 때 |
| 영향 | API 실패율 지표가 클라이언트 상태만으로 오른다. 증상 기반 알림이 오탐한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | 집계 경로는 확정. 실제 빈도는 route 정책이 인증 전 쿼리를 막는 범위에 달렸다 |
| 최소 개선 방향 | `outcome === "UNAUTHENTICATED" && status === undefined`를 텔레메트리에서 제외(diagnostics는 유지) |
| 비용·부작용 | 조건 1줄 |
| 완료 기준 | 전송 0회 미인증은 diagnostics 1건, telemetry 0건 |
| 검증 방법 | `http-execution-v3-observability.test.ts`에 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 03-08 HTTP 복구 runbook이 현재 코드보다 오래됐다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서) |
| 관련 관점 | 9, 26, 7 |
| 근거 | `docs/operations/api-contract-and-server-state-recovery.md`(기준일 2026-07-28)는 "auth fail-close/final invariant", "total logical deadline와 bounded response decoder"를 아직 `DESIGNED_NOT_IMPLEMENTED`라고 적고(`:16-21`), "external auth integration이 unavailable이어도 unchanged request가 전송될 수 있다"고 적는다(`:145`). 현재 V3는 전체 마감(`http-execution-v3.ts:458-484`), 본문 상한(`bounded-body-reader.ts`), 자격증명 없음·owner 장애 시 전송 0회(`http-execution-v3.ts:740-749`, `runtime-adapters.ts:479-484`)를 구현했다 |
| 발생 조건 | 장애 대응자가 runbook을 따를 때 |
| 영향 | 이미 있는 통제를 없는 것으로 보고 우회 조치를 하거나, 코드와 다른 전제로 원인을 찾는다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 확정 |
| 최소 개선 방향 | 1절 상태 목록과 5.1·6.0절을 V3 기준으로 갱신한다. 6.3절 규칙은 03-01 수정 뒤 구현 위치를 연결한다 |
| 비용·부작용 | 문서 변경 |
| 완료 기준 | runbook의 "구현 안 됨" 목록이 코드와 일치 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 — effect 확실성·intent 검증이 도메인 규칙 | M2 / M2(lattice는 단조 증가만) | E2 | 충족 — 확실성 규칙은 생성·재시도 경로에서 일관 |
| 2 | 구조적 성숙도 | 적용 — 배럴 공개 경계, 기능은 바인딩만 봄 | M3 / M3(의존성 검사는 영역 밖) | E1 | 충족 — 기능이 전송 정책을 설정할 수 없음(`feature-http-binding.ts:78-108`). 경계 검사는 다른 영역 |
| 3 | 변경 용이성 | 적용 — 오퍼레이션 추가·필터 추가 경로 | M2 / M2 | E1 | 부분 충족 — 오퍼레이션 추가는 계약+바인딩으로 예측 가능. 422 필드 전달은 공개 타입 확장 필요(03-04) |
| 4 | 인지 부하 | 적용 | — / — | E1 | 부분 충족 — `execute()` 약 600줄, V2·V3·RPC 세 재시도 어휘(03-06) |
| 5 | 위험 가시성 | 적용 — 29.4 문장을 채울 수 있는가 | M2 / M2 | E1 | 부분 충족 — 마감·재시도·상한은 계약 `frontend` 블록에 보임. 결과 불명 뒤 무엇이 일어나는지는 호출부에서 안 보이고 선언과 다름(03-01) |
| 6 | 실패 성숙도 | 적용 — 중점 | M3 / M3(조회), M1(결과 불명 쓰기) | E2 | 부분 충족 — timeout·재시도 대상·중첩 재시도·Retry-After는 충족. 결과 불명 쓰기 복구 미충족(03-01, 03-02) |
| 7 | 운영 성숙도 | 적용 — 라벨 cardinality, 수집 실패 격리 | M4 / M4(라벨 문법), M0(배치 크기) | E2·E3 | 부분 충족 — 라벨은 닫힘. keepalive 손실(03-05), 전송 0회 집계(03-07). diagnostics는 기본 sink 없이 메모리 100건(VD-07 결정대로) |
| 8 | 디버깅 가능성 | 적용 — 요청 식별자·원인 보존·민감정보 | M2 / M0(V3 식별자) | E1·E2 | 미충족 — 민감정보 제외와 오류 종류 보존은 충족. 문의 식별자 연결 끊김(03-03) |
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | 부분 충족 — V2 legacy 유지 이유는 문서화됨. runbook이 오래됨(03-08) |
| 10 | 테스트 성숙도 | 적용 — 영역 테스트 검출력 | M3 / M3 | E2 | 부분 충족 — 480건 통과, 결함 주입 7건 중 4건 검출·1건 중복 방어·1건 단위만 검출·1건 생존. 결과 불명 재전송 키, 422 전달, 배치 크기, correlation 테스트 없음 |
| 11 | 데이터 성숙도 | 부분 적용 — cursor 일관성만 | M3 / M3 | E2 | 충족 — snapshot 변경·cursor 반복·상한 검출(`cursor-pagination-runtime.ts:98-141`). 저장소 데이터는 다른 영역 |
| 12 | 동시성 성숙도 | 적용 — 늦은 응답·로그아웃 중 응답·중복 클릭 | M3 / M3 | E2 | 부분 충족 — 세대 fence·필터별 key·같은 탭 중복 클릭 차단 충족. 결과 불명 뒤 재전송이 같은 작업으로 식별되지 않음(03-01). 여러 탭 미검증 |
| 13 | 확장성 | 다른 영역 — 기능 수 증가는 extreme-scale 리뷰 | — | — | 적용 제외 |
| 14 | 성능 성숙도 | 적용 — 본문·구조·동시성 상한 | M3 / M3 | E2 | 충족 — 상한 전부 계약값. 텔레메트리 배치 크기만 예외(03-05) |
| 15 | 보안 성숙도 | 적용 — 토큰 보관·갱신·폐기, 로그아웃 후 캐시 | M3 / M3 | E2 | 충족 — 자격증명 헤더 경계, profile 소유 credentials, no-store, 세대별 QueryClient. 토큰은 외부 owner 소유로 문서화. 세션 만료 안내는 03-02 |
| 16 | 의존성 성숙도 | 다른 영역 | — | — | 적용 제외 |
| 17 | API / Contract 성숙도 | 적용 — 오류 envelope·런타임 스키마 | M3 / M3 | E2 | 부분 충족 — 성공·문제 본문 모두 런타임 검증. 선언된 recovery descriptor 미사용(03-01), 401/403/429 분류 불가(03-02), 422 필드 전달 불가(03-04) |
| 18 | 배포 성숙도 | 다른 영역 — release·SW | — | — | 적용 제외 |
| 19 | 설정 성숙도 | 적용 — `REQUEST_TIMEOUT_MS`, `MAX_RETRY_ATTEMPTS` | M3 / M3 | E2 | 부분 충족 — V3는 상한으로만 적용(`runtime-adapters.ts:462-470`, 테스트 있음). V2와 의미 다름(03-06) |
| 20 | 개발자 경험 | 다른 영역 | — | — | 적용 제외 |
| 21 | Guardrail 성숙도 | 적용 — 계약 설치 검증 | M3 / M3 | E2 | 부분 충족 — KEYED에 recovery descriptor가 없으면 설치 거부. 그러나 descriptor 내용은 어떤 실행에도 쓰이지 않아 가드가 형식만 지킴(03-01) |
| 22 | 추상화 성숙도 | 적용 — FeatureHttpBinding | — / M2 | E1 | 부분 충족 — 전송·재시도를 잘 숨김. 문제 매핑 타입이 너무 좁음(03-04) |
| 23 | 일관성 | 적용 | — / M1 | E1 | 부분 충족 — KEYED 의미 불일치(03-06) |
| 24 | 네이밍 / 의미 | 적용 | — / M1 | E1 | 부분 충족 — `IDEMPOTENCY_REPLAY`, `reconcileUnknownEffect`가 이름만큼의 동작(재전송·조회)을 하지 않음(03-01) |
| 25 | 조직 확장성 | 구조적 준비만 — 사용자 1인 | — / M2 | E1 | 충족(구조) — 기능은 계약+매퍼만 기여, 전송 정책은 공통 |
| 26 | Ownership | 적용 — 외부 auth owner 책임 | M1 / M1 | E0·E1 | 부분 충족 — owner 계약 문서 있음(`starter-experience.md:52-68`). `notifyUnauthenticated` 뒤 owner가 할 일과 요청 재실행 없음은 설계서에만 있음. runbook 오래됨(03-08) |
| 27 | 삭제 가능성 | 부분 적용 — V2·RPC·텔레메트리는 선택 | — / 미확인 | E1 | 미검증 — V2는 기본 조합에서 호출처가 없음. 제거 실험은 하지 않음 |
| 28 | 회복 가능성 | 적용 — 결과 불명 쓰기의 조정 | M2 / M1 | E1 | 미충족 — 조정 수단이 사용자 추측뿐이고 재전송이 새 키(03-01) |
## 6. 미검증 목록
- **백엔드 멱등 계약:** 같은 키·다른 입력 거절, 키 보관 기간, 진행 중 같은 키의 409 여부. 03-01의 실제 피해 범위를 정한다. 백엔드 계약 문서나 통합 환경이 필요하다.
- **외부 auth owner 동작:** `notifyUnauthenticated` 뒤 갱신·상태 알림 순서, `readSubject` 구현 여부. 실제 owner 구현이나 계약 테스트가 필요하다.
- **여러 탭:** 한 탭 로그아웃이 다른 탭의 세대를 바꾸는지, 두 탭에서 같은 생성을 보낼 때 키가 다른 문제. 외부 owner와 cross-context 영역(02)과 함께 봐야 한다.
- **게이트웨이 리다이렉트형 세션 만료:** 쿠키 profile(`SAME_ORIGIN_COOKIE`)에서 게이트웨이가 302로 로그인 페이지를 돌려주면 `redirect:"error"` 때문에 네트워크 실패로 분류되고 SAFE 조회는 재시도된다. 기본 profile은 bearer라 해당 없지만, 쿠키 profile을 쓰는 다운스트림에서 "재로그인" 안내가 나오는지 확인이 필요하다.
- **Browser RPC 실제 provider:** 스트림 정리·재시도는 단위 테스트로만 확인했다. 생성된 Connect/gRPC-Web 클라이언트와의 통합이 필요하다.
- **실제 브라우저에서 앱 전체 흐름:** 로그아웃 중 응답 도착, 세션 만료 저장, 결과 불명 화면을 E2E로 확인하지 않았다(E2E 영역 담당).
@@ -0,0 +1,281 @@
# 04 realtime 어댑터 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/adapters/realtime/` 16개 파일 9,577줄(SSE·WebSocket·polling·reconnect·stream coordinator·codec). 이 영역을 검증하는 `tests/unit/realtime/` 16개 파일 9,283줄. 계약(`src/contracts/realtime-streams.ts`, `realtime-events.ts`)과 설계 문서는 판정에 필요한 부분만 참조했다.
> 영역 판정(35.8): **조건부 사용 가능** — codec·stream coordinator·SSE 파서·polling·handoff는 building block으로 쓸 수 있다. reconnect coordinator를 단일 재연결 소유자로 두는 실시간 연결의 운영 도입은 04-01을 고치기 전에는 보류한다. 이 runtime은 production에 조합되지 않은 상태(`AVAILABLE_NOT_COMPOSED`)다.
## 1. 결론
- 신뢰할 수 없는 입력 검증, 모든 큐·버퍼·빈도의 상한, 순서·중복·gap 처리, 늦은 콜백 fence는 단단하다. 직전 리뷰 6.4의 1~11번은 현재 코드에서 고쳐진 것을 확인했다. 예외는 6.4-7이다. 재시도 예산 초기화가 일부 경로에만 들어갔다.
- **막아야 할 것 (04-01, High):** 오래 열린 연결은 첫 끊김 뒤 재연결하지 않는다. 실험에서 10분 정상 연결 뒤 1초 offline이 생기면 run이 `OFFLINE retryable:true`로 끝났고 재시도는 0회였다. 이벤트 없이 heartbeat만 오가던 WS가 6분 뒤 서버 재시작(1012)을 받아도 같았다. 원인은 elapsed 예산이 run 시작 시각에 고정된 것이다. 이 예산을 초기화하는 경로가 offline·throw 경로에는 없다.
- **고칠 것 (04-02, 04-03, Medium):** SSE 429/503의 Retry-After는 실패 결과에 실리지 않는다. 저장소의 SSE↔reconnect 배선처럼 결과를 그대로 넘기면, 서버가 30초 기다리라고 해도 0.5초·1초 뒤 재시도한다. 등록되지 않은 이벤트 타입이 오면 연결은 `MALFORMED_EVENT`로 끝난다. 그런데 stream coordinator의 freshness는 `CURRENT`로 남는다. 설계 13.1 위반이다. 오래 열린 탭에 "구버전 클라이언트"라는 신호도 가지 않는다.
- **테스트:** 209건이 통과했다. 변이 8건 중 6건을 잡았다. SSE idle timeout(heartbeat 감시)에는 테스트가 없다(04-06). 04-01~04-03의 시나리오도 테스트가 없다.
- **미검증:** 실제 SSE/WS 서버와 실제 브라우저는 확인하지 못했다. 청크 크기, hidden 탭 타이머, bfcache가 여기 해당한다. 부하 상태의 재연결 분포와 realtime 제거 게이트(`test:realtime-removal`)도 미검증이다.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `src/adapters/realtime/` 16개 파일 전체를 읽었다. 연결 지점도 필요한 만큼 읽었다: `src/contracts/realtime-streams.ts`(레지스트리·상한), `src/application/ports/realtime/event-authority.ts`(observation 타입), `src/application/policies/bounded-polling.ts`(상한), `scripts/lib/realtime-boundaries.ts` |
| 설계 문서 | `docs/architecture/realtime-events-web-push-and-bounded-polling.md` 0·4·5·6·7·12·13·14·16·19·20절, `decisions/VD-28-…md` 재연결 부분, `optional-adapter-recipes.md` Realtime 절. 주장으로만 읽었다 |
| 실행한 테스트 | `node scripts/run-vitest.ts run tests/unit/realtime/`: 14 files, **209 passed** |
| 스크래치 실험 | `scratchpad/04/`의 `exp-blip.ts`, `exp-reconnect.ts`, `exp-ws-quiet.ts`, `exp-429.ts`, `exp-unknown.ts`, `bench-parser.ts`. Node 24 type stripping으로 `src`를 직접 import하고 가짜 clock·fetch·socket을 썼다 |
| 변이 실험 | 분리 worktree에서 8건을 넣고 해당 테스트 파일만 돌렸다. **6건 검출.** M1 예산 초기화 제거, M2 jitter 제거, M3 effect 뒤 scope fence 제거, M4 1013→RESTART, M5 gap 검사 제거, M6 WS inbound 큐 상한 제거. **2건 생존.** M7 SSE `IDLE_TIMEOUT`을 retryable:false로 바꾼 것(→ 04-06). M8 accept 시점 scope 검사 제거(processEvent가 다시 검사하므로 의미 있는 공백 아님). worktree는 지웠다 |
| 가드레일 | worktree에서 `check-realtime-boundaries.ts`(artifact는 scratchpad): PASS. `check-realtime-boundary-fixtures.ts`: PASS(forbidden 규칙 3건 거절) |
| 확인하지 못한 범위 | `test:realtime-removal`. fixture 복사본에서 타입체크·lint·`test:all`·build를 모두 돌리는 스크립트라, 13개 에이전트가 동시에 도는 중에는 생략했다. 실제 스트리밍 서버와 브라우저도 확인하지 못했다(설계 20절의 해당 항목도 미체크). `check:architecture`·`check:types`는 오케스트레이터가 돌린다. `src/adapters/web-push`는 이 영역 밖이다 |
### 직전 리뷰 6.4 재확인 (현재 코드 기준)
| 직전 ID | 현재 상태 | 근거 |
|---|---|---|
| 6.4-1 DRAINING 중 recovery | 고쳐짐 | `stream-coordinator.ts:695-700` |
| 6.4-2 hint 없는 retryable 실패도 재연결 | 고쳐짐 | `reconnect-coordinator.ts:1523-1534`, 통합 테스트 `realtime-reconnect-coordinator.test.ts:1566-1691` |
| 6.4-3 barrier NONE recovery 종료 | 고쳐짐 | `event-consumer.ts:181-188` |
| 6.4-4 SSE 파서 성능 | 고쳐짐 | 250KB chunk 중앙값 2.4~3.4ms(Node 24, `bench-parser.ts`). 브라우저는 미측정 |
| 6.4-5 chunk당 item 상한 | 고쳐짐 | `sse/fetch-sse-connection.ts:418-431` drain. 바이트 상한은 남음 → 04-05 |
| 6.4-6 dedupe | 고쳐짐 | `stream-coordinator.ts:603-613`, `:1070-1082`, `event-codec.ts:369-387` |
| 6.4-7 재시도 예산 초기화 | **일부만** | 분류 경로 `reconnect-coordinator.ts:905-916`, `:935-945`에만 적용됨 → 04-01 |
| 6.4-8 복사본 통합 | 고쳐짐 | `result.ts:97-135`, `:238-294` 한 벌. polling도 같은 헬퍼 사용 |
| 6.4-9 `endAttempt`, `_recovery` | 고쳐짐 | `reconnect-coordinator.ts:596-607`. `_recovery`는 남아 있지 않음. `run()`은 여전히 약 665줄(`:306-971`) |
| 6.4-10 probe 버퍼 상한 | 고쳐짐 | `live-poll-handoff-coordinator.ts:258-289` |
| 6.4-11 사소 항목 | 고쳐짐 | poll throw → OFFLINE retryable(`polling/bounded-poll-coordinator.ts:288-293`, `:354-359`) 등 |
### 32절 시나리오를 realtime 구독 관점에서 따라간 결과
**화면 이동·언마운트**
```text
unmount → 조합 코드가 signal.abort() 또는 close() 호출
→ reconnect: stop → phase abort → session.close → finally에서 listener 해제 (reconnect-coordinator.ts:361-368, :954-970)
→ WS: terminate → listener 4종 해제, heartbeat·unsubscribe 타이머 abort, 큐 비움 (websocket/websocket-connection.ts:1326-1390)
→ SSE: controller abort + reader cancel(2초 상한) (sse/fetch-sse-connection.ts:455-466, :591-602)
→ poll: stop(ABORTED) → 대기 abort, visibility/online 구독 해제 (polling/bounded-poll-coordinator.ts:160-186, :490-500)
→ stream coordinator.close(): fence + 남은 작업 drain(5초) (stream-coordinator.ts:1003-1025)
```
각 조각은 스스로 정리된다. 늦게 끝나는 작업은 `DRAINING`으로 추적한 뒤 닫는다.
남는 것은 두 가지다.
- 논리 구독 refcount가 런타임에 없다. refcount는 "마지막 consumer가 사라지면 unsubscribe"하는 장치다. 이 부분은 조합 코드 몫이다(04-04).
- `close()`는 terminal이다. React StrictMode의 mount→cleanup→mount에서는 마운트마다 새 인스턴스를 만들어야 한다.
**로그아웃 중 응답 도착**
```text
scope.isCurrent() = false
→ 이벤트 도착: accept/processEvent에서 fence → SCOPE_FENCED drop, effect 0 (stream-coordinator.ts:302-305, :400-403)
→ 진행 중 effect: isCurrent 컨텍스트로 commit 거부, 끝난 뒤 재확인 (:504-511, :570-573) — 변이 M3 검출
→ 진행 중 snapshot recovery: 완료 뒤 scope 확인 → fence (:763-766)
→ poll 응답: attempt 뒤 isCurrent 확인, onValue에 isCurrent 전달 (polling/bounded-poll-coordinator.ts:315-328, :408-413)
→ 연결 자체: 다음 경계(이벤트 또는 close)까지 열린 채 유지 (EXP2) → 04-04
```
이전 사용자의 응답이 다음 세션 상태에 들어가지 않는 것은 확인했다. 연결을 닫는 일은 조합 코드가 `close()`를 불러야 일어난다.
## 3. 확인된 강점
1. **신뢰할 수 없는 프레임을 정해진 순서로 처리한다.** 순서는 바이트 상한 → JSON 중복 키 검사 → `JSON.parse` → 정확한 키 집합 → registry의 stream/type 조회 → payload 스키마 → mapper → freeze다. 근거는 `event-codec.ts:101-201`이다. WS 제어 프레임도 같은 방식이다(`websocket/websocket-protocol.ts:172-200`). 테스트는 `event-codec.test.ts`, `websocket-protocol.test.ts`다.
2. **자원 상한이 모든 곳에 있고, 호출자가 올릴 수 없다.** 이벤트는 64KB, 큐는 256건/4MB, dedupe는 2,048건/4MB/10분이다(`src/contracts/realtime-streams.ts:29-38`). WS 한도는 서버가 광고해도 줄이기만 한다(`websocket/websocket-connection.ts:198-214`, `:1620-1653`, `:1655-1693`). SSE 파서는 `sse/sse-parser.ts:7-14`, 재연결은 `reconnect-policy.ts:3-10`, polling은 `bounded-polling.ts:1-5`에 상한이 있다. 장시간 연결에서 메모리가 무한히 늘어나는 경로는 찾지 못했다.
3. **순서·중복·gap·epoch를 처리한다.** 같은 ID에 다른 내용이 오면 conflict로 복구한다. sequence가 건너뛰면 gap으로 snapshot 복구한다. 과거 sequence는 drop한다. 근거는 `stream-coordinator.ts:419-477`이다. cursor는 effect 성공 뒤에만 전진한다(`:588-595`). WS 재구독 때는 `nextExpectedSequence`와 cursor를 대조한다(`websocket/websocket-connection.ts:821-858`). 변이 M5가 검출됐다.
4. **늦은 콜백 fence가 있다.** scope와 generation을 accept·effect 전후·recovery 전후·poll 전후에 확인한다(32절 추적 참조). effect에는 `isCurrent`를 넘겨 commit 직전 확인을 강제한다. 변이 M3이 검출됐다.
5. **재연결 폭주를 억제한다.** full jitter를 쓴다. server not-before hint는 낮춰 잘라 내지 않고 넘으면 종료한다(`reconnect-policy.ts:73-114`). 시도 10회·5분·최대 60초가 상한이다. 힌트 없는 WS `OVERLOADED`(1013)는 종료한다(`websocket/websocket-connection.ts:1814-1819`). 예산 초기화에는 "유효 신호 + 안정 유지" 두 조건이 모두 필요하다(`reconnect-policy.ts:137-149`). 변이 M1·M2·M4가 검출됐다.
6. **인증과 엔드포인트를 좁게 둔다.** 엔드포인트는 고정 same-origin HTTPS/WSS다. URL에 query·credential이 없다(`sse/fetch-sse-connection.ts:471-491`, `websocket/websocket-connection.ts:1584-1614`). 401/403은 재시도 없이 종료하므로 인증 재시도 폭주가 없다(`sse/fetch-sse-connection.ts:545-550`). native `WebSocket`/`EventSource`는 이 폴더 밖에서 금지되고, 가드레일이 PASS했다.
## 4. 발견 사항 (36.3)
### 04-01 오래 열린 연결은 첫 끊김(offline 깜빡임, 조용한 WS의 서버 재시작) 뒤 재연결하지 않고 끝난다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 12, 18, 28, 10, 5 |
| 근거 | 원인은 두 가지다. ① 재시도 elapsed 예산의 시작점 `budgetStartedAt`이 run 시작 시각이다(`reconnect-coordinator.ts:347`). 이 값을 초기화하는 곳은 서버 close를 분류하는 두 경로(`:905-916`, `:935-945`)뿐이다. offline으로 끊긴 경로(`:824-862`)와 `waitClosed`가 throw한 경로(`:863-870`)는 초기화 없이 `offlineRetry`/`providerRetry`만 만든다. 그러면 다음 루프의 `canRetry`가 남은 예산을 0으로 본다. online을 기다리지도 않고 `retry.terminalResult`를 반환한다(`:482-495`). offline 대기 시간도 같은 예산에서 빠진다(`:496-513`). ② 초기화 조건인 `markValidHeartbeatOrEvent`(`:620-622`)를 WS에서는 이벤트가 올 때만 부를 수 있다. HEARTBEAT_ACK는 연결 안에서 소비되고(`websocket/websocket-connection.ts:360-376`) 관측 종류에도 없다(`:70-79`). 실험 조건: base 1s, max elapsed 5분, stable 30s. 결과는 셋이다. (a) 10분 정상 연결 뒤 1초 offline → `{kind:"OFFLINE",retryable:true}`로 종료, 재시도 0회(`exp-blip.ts`). 같은 조건에서 서버 close를 받은 경우는 재연결했다. (b) 시작 직후 6분 offline → online 복귀 시 시도 0회로 종료(`exp-reconnect.ts`). (c) 이벤트 없이 heartbeat ACK만 정상인 WS가 6분 뒤 1012를 받음 → `PROVIDER_UNAVAILABLE retryable:true`로 종료, 소켓 1개(`exp-ws-quiet.ts`) |
| 발생 조건 | 연결이 `maxElapsedMs`(상한 5분)보다 오래 유지된 뒤 끊길 때다. 네트워크가 잠깐 끊기는 경우(Wi-Fi 전환, 노트북 절전 복귀)와, 이벤트가 드문 WS 구독에서 서버가 재시작하는 경우다. 실사용 세션 대부분이 해당한다 |
| 영향 | realtime이 조용히 멈추고 화면은 오래된 데이터를 보여 준다. 결과가 `retryable:true`라 조합 코드가 다시 run할 수는 있다. 하지만 예산 소진(멈춰야 함)과 이 경우(재연결해야 함)의 결과 모양이 같아 구분할 수 없다. 다시 run하는 바깥 루프를 만들면 설계가 금지한 두 번째 재시도 루프가 된다. reference runtime이라 이 recipe를 채택하는 다운스트림에 그대로 복제된다 |
| 심각도·우선순위 | High · P1. 설계 5.4가 지원한다고 적은 장애(offline→online, 서버 재시작)에서 핵심 기능이 멈춘다. production에 조합되기 전이라 P0는 아니다. realtime 도입 전에 풀어야 할 차단 항목이다 |
| 통제·증거 | M2(분류 경로에만 구현) · E2(스크래치 실험) |
| 확실성과 남은 가정 | 코드 경로와 실험으로 확인했다. 조합 코드가 WS `CONNECTED` 관측 시점에 markValid를 부르면 (c)는 피할 수 있다. 그런 안내는 코드와 문서에 없다 |
| 최소 개선 방향 | (1) 세션이 열린 뒤 끝나는 모든 경로(offline·throw 포함)에서 `isReconnectAttemptResetEligible`를 적용한다. 한 헬퍼로 모으면 된다. (2) elapsed 예산은 연속 실패가 시작된 시각부터 잰다. offline 대기 중에는 멈춘다. online 복귀 시 `budgetStartedAt = now`로 두고 시도 횟수 상한은 유지한다. (3) WS에 heartbeat ACK 관측을 추가한다. 예: `observe({kind:"HEARTBEAT_ACK"})` |
| 비용·부작용 | 수십 줄이다. `maxAttempts`는 그대로라 무한 재시도는 생기지 않는다 |
| 완료 기준 | (a)(b)(c) 모두 재연결 시도가 1회 이상 일어난다. 예산을 실제로 소진했을 때만 terminal이 된다 |
| 검증 방법 | `realtime-reconnect-coordinator.test.ts`에 (a)(b)(c)를 ManualClock으로 추가한다. 현재 offline 테스트(`:400-435`)는 시작 시 짧은 offline만 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.4-7(Q-6.4-7)의 수정이 분류 경로에만 들어감. 이번에 새로 찾은 경로 |
### 04-02 SSE 429/503의 Retry-After가 실패 결과에 실리지 않아, 기본 배선에서는 서버가 요구한 시각보다 먼저 재연결한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 5, 22, 23, 10 |
| 근거 | `sse/fetch-sse-connection.ts:554-575`는 Retry-After가 유효하면 `onRetryHint` 콜백(`:73`)으로만 알린다. 반환하는 실패에는 `retryable:true`만 남는다. reconnect coordinator는 hint를 attempt 결과의 `serverNotBeforeMs`로만 받는다(`reconnect-coordinator.ts:44-51`, `:725-731`). 저장소의 유일한 SSE↔reconnect 배선(`realtime-reconnect-coordinator.test.ts:1643-1690`)도 `read` 결과를 그대로 넘긴다. 실험(`exp-429.ts`, 429 + `Retry-After: 30` 두 번): 이 배선에서는 재연결 대기가 **500ms, 1000ms**였다. `onRetryHint`로 받아 결과에 넣으면 30000ms, 30000ms였다. polling은 같은 정보를 실패 값 안에 싣는다(`polling/bounded-poll-coordinator.ts:28-30`) |
| 발생 조건 | 서버나 게이트웨이가 과부하·점검·rate limit 때문에 SSE 연결에 429/503 + Retry-After를 줄 때 |
| 영향 | 모든 탭이 서버가 정한 시각보다 먼저 재연결한다. 첫 시도는 [0, base) 안에 몰린다. 시도 상한(10회·5분)이 있어 무한 폭주는 아니다. 하지만 과부하를 풀려는 서버 신호를 무시해 회복을 늦춘다. 설계 5.3의 "server not-before보다 먼저 재시도하지 않는다"를 기본 배선이 어긴다 |
| 심각도·우선순위 | Medium · P2. 증폭 폭이 시도 상한으로 제한된다. 04-01과 같은 경로를 고칠 때 같이 고치면 싸다 |
| 통제·증거 | M1(설계 문서만) · E2(스크래치 실험) |
| 확실성과 남은 가정 | 콜백을 직접 이어 붙이는 조합 코드는 영향이 없다. 그런 배선 예시는 저장소 어디에도 없다 |
| 최소 개선 방향 | SSE 실패 결과에 `retryAfterMs`를 싣는다. SSE 모듈에서 reconnect 결과로 옮기는 작은 bridge 함수를 export한다. EOF의 `retryHintMs`(`:405-411`)와 같은 통로로 합친다 |
| 비용·부작용 | 공개 타입에 선택 필드를 추가한다. 기존 소비자와 호환된다 |
| 완료 기준 | 429/503 + Retry-After가 bridge를 거치면 재연결 대기가 hint 이상이다. hint가 상한을 넘으면 지금처럼 종료한다 |
| 검증 방법 | 통합 테스트 `:1643` 옆에 429 + Retry-After 케이스를 추가하고 `clock.sleepCalls`로 대기를 확인한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 04-03 등록되지 않은 이벤트 타입이 오면 연결은 MALFORMED_EVENT로 끝나고, stream freshness는 CURRENT로 남는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(설계 13.1 계약 위반). 오래 열린 탭에 대해서는 구조적 위험 |
| 관련 관점 | 17, 18, 8, 10 |
| 근거 | codec은 registry에 없는 `eventType`을 `MALFORMED_EVENT`로 거절한다(`event-codec.ts:145-151`). 스키마 오류와 같은 코드다. consumer는 이 실패를 stream coordinator에 알리지 않고 그대로 반환한다(`event-consumer.ts:85-88`). SSE는 읽기를 끝낸다(`sse/fetch-sse-connection.ts:350-352`). WS는 PROTOCOL_MISMATCH로 닫는다(`websocket/websocket-connection.ts:1038-1039`, `:1574-1578`). 둘 다 retryable:false다. 실험(`exp-unknown.ts`): 이벤트 1·2를 적용한 뒤 새 타입의 이벤트 3을 보냈다. SSE는 `MALFORMED_EVENT retryable:false`로 끝났고, coordinator `inspect()`는 `freshness:"CURRENT"`였다. 설계 13.1(`realtime-events-web-push-and-bounded-polling.md:1829`, `:1850-1851`)은 MALFORMED_EVENT에서 freshness를 `UNKNOWN`으로 두라고 적는다. unknown type을 버린 뒤 CURRENT를 유지하지 말라고도 적는다. 테스트는 현재 동작을 고정한다(`event-codec.test.ts:70-77`) |
| 발생 조건 | 백엔드가 기존 stream에 이벤트 타입을 추가해 배포했는데 이전 프론트 번들을 쓰는 탭이 열려 있을 때. 보통 "추가만 한 호환 변경"으로 취급하는 배포다 |
| 영향 | 오래 열린 탭의 realtime이 재시도 없이 멈춘다. freshness 축만 보는 화면은 CURRENT를 표시한다. 실패 코드가 데이터 손상과 같다. 그래서 조합 코드는 "새로고침하면 해결되는 구버전"과 "서버 버그"를 구분하지 못한다. 설계 5.5가 요구하는 N/N-1 또는 reload 정책을 걸 신호도 없다 |
| 심각도·우선순위 | Medium · P2. 연결 상태 축을 함께 쓰는 조합(설계 5.1)이라면 화면이 STALE로 보일 수 있어 피해가 줄어든다. 샘플 패턴으로 복제되는 범위다 |
| 통제·증거 | fail-closed는 M2. freshness 계약은 구현이 없다(M0) · E2 |
| 확실성과 남은 가정 | 코드와 실험으로 확인했다. 조합 코드가 transport 종료를 freshness에 반영할지는, 조합 코드가 없어 미확인이다 |
| 최소 개선 방향 | (1) 등록되지 않은 이벤트 타입을 별도 사유로 구분한다. 관측 reason이나 failure kind를 추가하는 방식이다. (2) decode 실패를 해당 stream의 freshness `UNKNOWN`으로 반영하는 경로를 둔다. (3) "추가된 이벤트 타입" 호환 규칙을 설계에 한 줄로 고정한다. 예: reload 유도, 또는 non-state-bearing이면 무시 |
| 비용·부작용 | failure vocabulary를 추가하면 ports 계약이 바뀐다 |
| 완료 기준 | 새 타입 이벤트를 받은 뒤 `inspect().freshness`가 CURRENT가 아니다. 조합 코드가 받은 실패만으로 "구버전 클라이언트"를 판별할 수 있다 |
| 검증 방법 | `event-consumer.test.ts`의 SSE+consumer+coordinator 통합 묶음에 등록되지 않은 타입 케이스를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 04-04 hidden 탭 닫기·로그아웃 시 닫기·kill switch를 강제하는 코드가 없고, `isCurrent`는 루프 경계에서만 확인한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 12, 15, 5, 14, 20 |
| 근거 | registry는 `hiddenPolicy`·`killSwitchId`·`fallback`을 필수 필드로 검증한다(`src/contracts/realtime-streams.ts:85`, `:357`). 그런데 `src/` 어디에서도 읽지 않는다(grep). reconnect coordinator가 받는 환경 신호는 online뿐이다(`reconnect-coordinator.ts:103-106`). SSE 연결에는 visibility 입력이 없다. `isCurrent`는 루프 경계에서만 호출된다(`:349-355`). 실험(`exp-reconnect.ts` EXP2): 열린 세션에서 `isCurrent`를 false로 바꾸고 10분을 보냈다. run은 RUNNING 그대로였고 `session.close`는 0회였다. `close()`를 불러야 닫혔다. 설계 5.5의 `maxConnectionAge`(`…md:851-854`)는 registry에 필드가 없다. polling만 visibility를 직접 듣는다(`polling/bounded-poll-coordinator.ts:172-186`) |
| 발생 조건 | 다운스트림이 설계 5.4~5.6에 적힌 "기본 동작"을 런타임이 해 준다고 믿고 조합할 때 |
| 영향 | hidden 탭도 연결을 유지해 탭 수만큼 연결이 생긴다. HTTP/1.1이면 fetch-SSE 6개로 같은 origin의 다른 요청이 막힐 수 있다. 설계 6.4가 HTTP/2를 hosting 증거로 요구하는 이유다. 로그아웃 뒤에도 조용한 stream의 연결은 서버가 끊거나 다음 이벤트가 올 때까지 남는다. 이벤트 적용은 fence로 막히므로 화면 데이터가 섞이지는 않는다(변이 M3 검출) |
| 심각도·우선순위 | Low · P3. `optional-adapter-recipes.md:141-144`가 visibility·logout 처리를 채택자의 필수 검증으로 적어 두었다. 다만 필수 registry 필드가 런타임 강제처럼 읽힌다 |
| 통제·증거 | M1 · E2 |
| 확실성과 남은 가정 | 조합 코드가 없어 실제 피해는 조합 방식에 달렸다 |
| 최소 개선 방향 | 세 곳에 적는다. registry 필드 주석과 설계 5.4~5.6에는 "reference runtime은 강제하지 않는다, 조합 코드 책임"을 적는다. `isCurrent` 타입 주석에는 "경계에서만 확인한다, 로그아웃 시 `close()`가 필요하다"를 적는다. 필요하면 reconnect 환경에 scope·visibility 구독을 추가한다 |
| 비용·부작용 | 문서만 고치면 몇 줄이다 |
| 완료 기준 | 채택자가 코드 옆 주석만 보고 닫기 책임이 자기에게 있다는 것을 안다 |
| 검증 방법 | 문서 리뷰. 구독을 추가한다면 "scope 변경 → session.close" 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 04-05 SSE reader가 256KB를 넘는 chunk를 한 번에 주면, 이벤트 크기와 상관없이 EVENT_TOO_LARGE로 끝난다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 14, 6 |
| 근거 | 파서는 chunk가 `maxChunkBytes`(256KB, `sse/sse-parser.ts:11`)를 넘으면 실패한다(`:99`). 연결은 reader chunk를 자르지 않고 그대로 넣는다(`sse/fetch-sse-connection.ts:418-431`). 결과는 retryable:false다. 파서에는 이미 한 입력을 나눠 처리하는 `drain()`(`sse-parser.ts:54-59`, `:106`)이 있다 |
| 발생 조건 | 브라우저가 쌓인 바이트를 큰 chunk로 넘길 때다. 메인 스레드가 오래 막힌 뒤나 재연결 직후 replay가 몰릴 때 생길 수 있다. chunk 크기는 서버의 이벤트 크기가 아니라 브라우저와 네트워크가 정한다. 실제 크기는 측정하지 못했다 |
| 영향 | 정상 크기의 이벤트만 받는데도 realtime이 멈춘다 |
| 심각도·우선순위 | Low · P3. 발생 빈도를 모른다. 수정은 몇 줄이다 |
| 통제·증거 | M0(chunk 분할 없음) · E1 |
| 확실성과 남은 가정 | 브라우저별 fetch body chunk 상한은 미확인 |
| 최소 개선 방향 | `fetch-sse-connection.ts`에서 chunk를 `maxChunkBytes` 단위로 `subarray`해 push/drain한다 |
| 비용·부작용 | 없음 |
| 완료 기준 | 1MB 단일 chunk에 정상 이벤트가 여러 개 들어 있어도 전부 전달된다 |
| 검증 방법 | `fetch-sse-connection.test.ts`에 1MB 단일 chunk 케이스를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.4-5 관련. item 상한은 고쳐졌고 바이트 상한 문제가 남음 |
### 04-06 SSE idle timeout(heartbeat 감시)에 테스트가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(테스트 공백) |
| 관련 관점 | 10, 6 |
| 근거 | `sse/fetch-sse-connection.ts:386-390`의 `IDLE_TIMEOUT` 경로를 검사하는 테스트가 없다. `tests/unit/realtime/`에서 `IDLE_TIMEOUT`을 찾으면 reconnect 테스트의 가짜 결과 한 곳만 나온다. 변이 M7(retryable을 false로 바꿈)은 `fetch-sse-connection.test.ts` 24건을 모두 통과했다. 같은 실험에서 M1~M6은 모두 검출됐다 |
| 발생 조건 | idle 타이머, comment 처리, retryable 값을 바꾸는 변경이 들어올 때 |
| 영향 | SSE에서 반쯤 끊긴 연결(NAT 만료, 절전 복귀)을 감지하는 유일한 장치다. 여기가 회귀하면 SSE가 조용히 멈추거나 재연결하지 않는다 |
| 심각도·우선순위 | Low · P2. 현재 코드는 맞다(E1). 회귀를 막는 장치가 없다는 문제다 |
| 통제·증거 | M2 · E2(변이 실험) |
| 확실성과 남은 가정 | 확인됨 |
| 최소 개선 방향 | ManualClock으로 테스트 2건을 추가한다. 하나는 idle 경과 → `IDLE_TIMEOUT retryable:true`와 reader cancel 확인이다. 다른 하나는 comment가 타이머를 연장하는지 확인이다 |
| 비용·부작용 | 없음 |
| 완료 기준 | M7 변이가 실패한다 |
| 검증 방법 | 변이 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 04-07 재연결·폴링·SSE 연결에 관측 지점이 없어 설계 14.1의 connect/poll 진단 이벤트를 낼 곳이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 7, 8 |
| 근거 | stream coordinator(`stream-coordinator.ts:74`, `:1115`)와 WS(`websocket/websocket-connection.ts:1481`)에는 닫힌 어휘의 `observe`가 있다. reconnect coordinator(`reconnect-coordinator.ts:121-143`), polling(`polling/bounded-poll-coordinator.ts:86-102`), SSE(`sse/fetch-sse-connection.ts:83-94`)에는 없다. 설계 14.1·14.2(`…md:1873-1930`)는 `realtime_connect_attempted`, 재연결 시도·대기·소진 비율, `bounded_poll_*`를 요구한다. 예산 소진과 04-01 종료는 결과 모양도 같다 |
| 발생 조건 | 운영에서 재연결 폭주나 소진을 보려 할 때 |
| 영향 | 클라이언트 쪽에서 재연결 시도·대기·종료 이유를 셀 수 없다. attempt를 감싸면 시도 수는 셀 수 있다. 대기 시간과 "소진인지 terminal인지"는 알 수 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0(해당 지점) · E1 |
| 확실성과 남은 가정 | 확인됨 |
| 최소 개선 방향 | reconnect·poll coordinator에 `observe?` 의존성을 추가한다. 낼 값은 attempt 시작·종료(closed kind), 대기 bucket, 종료 이유(EXHAUSTED/TERMINAL/ABORTED)다 |
| 비용·부작용 | sink 실패가 제어 흐름에 영향을 주지 않게 try/catch한다. stream coordinator와 같은 방식이다 |
| 완료 기준 | 14.1의 connect·poll 이벤트를 조합 코드가 추가 래핑 없이 만들 수 있다 |
| 검증 방법 | 관측 호출 순서를 확인하는 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 04-08 VD-28과 설계 5.3이 현재 재연결 규칙과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서) |
| 관련 관점 | 9, 5, 24 |
| 근거 | 설계 5.3(`realtime-events-web-push-and-bounded-polling.md:779-782`)과 VD-28(`decisions/VD-28-…md:265-266`)은 "rate/provider 실패는 server hint가 있을 때만 재시도하고, 없으면 terminal"이라고 적는다. 코드는 R-4.2 이후 retryable이면 hint 없이도 재시도한다. hint가 필요한지는 transport가 정한다(`reconnect-coordinator.ts:1523-1534`). 이 코드는 같은 설계 문서의 6.3·7.4 표(502/504, RESTART는 bounded 재시도)와는 맞는다. 또 VD-28:258은 attempt 초기화 조건을 "stable-open **또는** valid signal"로 적는다. 코드와 설계 5.3은 "**둘 다**"다(`reconnect-policy.ts:131-149`) |
| 발생 조건 | 채택자가 결정 문서(VD-28)를 기준으로 조합 코드를 짤 때 |
| 영향 | 조합 코드가 hint 없는 502를 terminal로 바꾸거나, 초기화 조건을 느슨하게 다시 구현할 수 있다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1(문서 불일치) · E1 |
| 확실성과 남은 가정 | 확인됨 |
| 최소 개선 방향 | 두 문서의 해당 줄을 코드 기준으로 고친다 |
| 비용·부작용 | 없음 |
| 완료 기준 | 5.3, 6.3, 7.4, VD-28이 같은 규칙을 말한다 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.4-2, 6.4-7 수정 때 문서가 같이 바뀌지 않음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용. 상태 전이(stream OPEN/DRAINING/CLOSED, reconnect IDLE/RUNNING/DRAINING/CLOSED)와 입력 불변식 | M3 / M3 | E2 | 충족. 정확한 키 검증과 terminal·idempotent close |
| 2 | 구조적 성숙도 | 적용. ports/contracts와 kernel(`platform/`)만 import | M3 / M3(boundary 검사) | E2 | 충족. `check:architecture`는 오케스트레이터 몫 |
| 3 | 변경 용이성 | 적용. 이벤트 타입을 추가하는 변경 | M2 / M1 | E2 | 부분 충족. 백엔드가 타입을 추가하면 이전 탭이 멈춤(04-03) |
| 4 | 인지 부하 | 적용. 조합 배선 계약(markValid, classifyClosed, hint) | M2 / M1 | E1 | 부분 충족. `run()` 약 665줄(`reconnect-coordinator.ts:306-971`). 배선 규칙이 코드 곳곳에 흩어져 04-01·04-02가 생김 |
| 5 | 위험 가시성 | 적용 | M2 / M1 | E2 | 부분 충족. hint가 콜백으로만 전달됨(04-02). `isCurrent`는 폴링 방식(04-04) |
| 6 | 실패 성숙도 | 적용(중점) | M3 / M2 | E2 | **미충족.** full jitter·상한·hint 하한은 좋다. 장시간 연결 뒤 재연결이 안 됨(04-01). Retry-After가 유실됨(04-02). WS 프로토콜에는 재시도 hint 필드가 없어 `OVERLOADED`는 항상 종료다. 폭주는 막지만 과부하가 끝나도 클라이언트가 스스로 복귀하지 않는다 |
| 7 | 운영 성숙도 | 적용(중점) | M2 / M1 | E1 | 부분 충족. stream과 WS에만 관측이 있음(04-07) |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1 | 부분 충족. 닫힌 failure 어휘가 있고 raw 사유는 노출하지 않는다. unknown type과 손상 데이터를 구분하지 못함(04-03) |
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | 부분 충족. 직전 리뷰 수정은 반영됐다. 결정 문서가 코드와 어긋남(04-08) |
| 10 | 테스트 성숙도 | 적용 | M3 / M3(일부) | E2 | 부분 충족. 209건 통과, 변이 6/8 검출. SSE idle 감시가 공백(04-06). 04-01~03 시나리오에 테스트 없음 |
| 11 | 데이터 성숙도 | 적용. cursor와 checkpoint 의미 | M3 / M3 | E2 | 충족. cursor는 effect 뒤에 전진하고 메모리에만 있다. 영속 저장은 없다 |
| 12 | 동시성 성숙도 | 적용(중점). 순서·중복·gap·여러 탭 | M3 / M3 | E2 | 부분 충족. 순서·중복·gap·단일 recovery는 충족. 탭별 연결은 설계상 의도지만 hidden 닫기를 강제하는 코드가 없음(04-04). 장시간 연결 뒤 재연결(04-01) |
| 13 | 확장성 | 적용. 구조 상한만 확인 가능(요청량 목표 없음) | 미정 / M2 | E1 | 미검증. 구독 32개, stream별 큐 상한은 있음. 부하는 측정 안 함 |
| 14 | 성능 성숙도 | 적용(중점) | M3 / M3 | E2 | 부분 충족. 메모리 상한이 모두 있고 파서는 250KB에 약 3ms. chunk가 256KB를 넘으면 종료(04-05) |
| 15 | 보안 성숙도 | 적용(중점) | M3 / M3 | E2 | 충족(영역 범위). 고정 same-origin, URL에 credential 없음, 401/403 즉시 종료, 로그아웃 뒤 적용 fence. 잔여: 로그아웃 시 연결 닫기는 조합 코드 책임(04-04) |
| 16 | 의존성 성숙도 | 적용 | M2 / M2 | E1 | 충족. 외부 패키지 없음. native API는 facade로 주입 |
| 17 | API/Contract 성숙도 | 적용(중점) | M3 / M2 | E2 | 부분 충족. envelope 정확 키, protocol literal, 레지스트리 스키마. unknown type 처리가 설계와 다름(04-03) |
| 18 | 배포 성숙도 | 적용(중점). 새 배포 뒤 오래 열린 탭 | M2 / M1 | E2 | 부분 충족. 서버 재시작 재연결은 R-4.2로 해결. 이벤트 타입 추가(04-03)와 조용한 WS(04-01)는 남음. N/N-1 정책 없음 |
| 19 | 설정 성숙도 | 적용 | M3 / M3 | E2 | 충족. 정책은 생성 시 검증하고, 상한은 낮추기만 허용 |
| 20 | 개발자 경험 | 적용 | M2 / M1 | E1 | 부분 충족. 조합 예시가 테스트 안에만 있다. 채택자가 배선을 직접 추론해야 함(04-02, 04-04) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E2 | 충족. realtime-boundaries 검사와 fixture PASS. native API와 미선택 composition을 차단 |
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | 부분 충족. session·attempt 추상화는 transport를 잘 숨긴다. hint 통로가 transport마다 다름(04-02) |
| 23 | 일관성 | 적용 | M2 / M2 | E1 | 부분 충족. abort·snapshot 헬퍼는 한 벌로 합쳐짐. retry hint는 polling이 in-band, SSE가 콜백 |
| 24 | 네이밍/의미 | 적용 | M2 / M2 | E1 | 부분 충족. `markValidHeartbeatOrEvent`에 넘길 WS heartbeat 신호가 없음(04-01). unknown type을 `MALFORMED_EVENT`로 부름(04-03) |
| 25 | 조직 확장성 | 적용 제외. 작성자 1인, 구조적 준비만 평가 | — | E1 | 적용 제외. registry에 `owner` 필드가 필수로 있음 |
| 26 | Ownership | 적용 제외. 제품 조합(RT-05)이 선택되지 않음 | — | E0 | 적용 제외. recipe `owner: project-owner-required` |
| 27 | 삭제 가능성 | 적용 | M3 / 미확인 | E0 | 미검증. `test:realtime-removal` 게이트는 있으나 이번에 돌리지 않음 |
| 28 | 회복 가능성 | 적용. snapshot 복구와 재연결 | M3 / M2 | E2 | 부분 충족. gap·cursor 만료 → snapshot 복구는 충족. 끊김 뒤 스스로 복구하지 못하는 경로가 있음(04-01) |
## 6. 미검증 목록
| 항목 | 판단하지 못한 이유 | 확인하려면 |
|---|---|---|
| 실제 브라우저의 fetch body chunk 크기(04-05), hidden 탭 타이머 throttling, bfcache 복귀, freeze | 브라우저 실행 없음 | Playwright에서 로컬 SSE 서버로 대량 replay·hidden·bfcache 시나리오 실행 |
| 실제 SSE/WS 서버와의 연결, 프록시 idle 종료, HTTP/1.1 연결 수 한계 | 로컬 스트리밍 서버 없음(설계 20절 미체크) | 로컬 서버와 nginx/ALB 설정으로 E3 실험 |
| 여러 클라이언트 재연결 분포(서버 재시작 직후 폭주 크기) | 부하 실험 없음. jitter 공식은 단위 테스트와 코드로만 확인 | N개 클라이언트 시뮬레이션으로 초당 재연결 수 측정 |
| realtime 제거 게이트(`test:realtime-removal`) | 전체 타입체크·lint·test·build를 fixture에서 돌려 비용이 커서 생략 | CI 또는 단독 실행 |
| 조합 코드가 transport 종료를 freshness에 반영하는지(04-03), 로그아웃 시 `close()`를 부르는지(04-04) | production 조합과 예시가 없음 | RT-05 조합 코드가 생기면 재검토 |
| SSE 파서 성능의 브라우저 수치 | Node 24 벤치만 실행 | 실제 브라우저 performance 측정 |
@@ -0,0 +1,383 @@
# 브라우저 저장소와 adapter kernel 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/` — 약 14.9k줄. 이 영역을 검증하는 테스트(`tests/unit/indexeddb-*.test.ts`, `opfs-*.test.ts`, `abortable-operation.test.ts`, `storage-*.test.ts`, `browser-storage-policy.test.ts`, `tests/helpers/memory-indexeddb.ts`, `tests/browser-capabilities/indexeddb-runtime.spec.ts`·`opfs-runtime.spec.ts`)와 `docs/operations/*recovery*.md` 중 이 영역 부분.
> 영역 판정(35.8): **조건부 사용 가능** — adapter kernel과 Web Storage 어댑터는 지정 범위에서 사용 가능. IndexedDB 런타임은 "사용자 데이터 삭제 보장"을 요구하지 않는 dataset에 한해 사용 가능(05-03, 05-05 전제). OPFS 런타임은 05-01·05-02를 고치기 전에는 제품에 조합하지 않는다.
전제: IndexedDB·OPFS 런타임은 `AVAILABLE_NOT_COMPOSED`다. repo의 bootstrap은 이 두 런타임을 조합하지 않는다(`src/bootstrap/runtime-adapters.ts`는 Web Storage와 kernel만 import). 따라서 아래 결함은 현재 배포 앱에서 발생하지 않고, **다운스트림이 이 reference runtime을 조합할 때** 복제된다. 심각도는 그 조합을 기준으로 매겼다.
## 1. 결론
- **adapter kernel은 지정 범위에서 쓸 수 있다.** IndexedDB open/transaction의 "한 번만 결론 내기", 늦게 도착한 연결 닫기, 결론 뒤 도착한 upgrade 중단이 한 곳에 있고 단위 테스트와 실제 브라우저 2탭 테스트가 있다. kernel 예외 규칙도 지켜진다. 위반 import 2건을 일부러 넣어 보니 `check:architecture`가 둘 다 잡았다.
- **OPFS 런타임은 조합 전에 막아야 할 결함이 2건 있다.**
- 05-01: 다른 탭이나 같은 탭에서 `reconcile()`이 돌면 진행 중인 put의 파일을 지운다. 그런데 put은 성공으로 보고되고, 덮어쓰기라면 이전 버전까지 사라진다.
- 05-02: put의 첫 receipt 쓰기가 quota 초과나 크래시로 실패하면 빈 `receipt.json`이 남는다. 그 뒤로 authority 전체의 reconcile과 GC가 영구히 멈춘다.
- 둘 다 재현 스크립트로 확인했다.
- **"손상된 행 하나가 정리 작업 전체를 멈추는" 패턴이 여러 곳에 남아 있다.** 직전 리뷰 6.5-4는 IndexedDB 파티션 purge의 행 단위 검증만 고쳤다. 다음 경로는 그대로다.
- open 단계의 governance 행 손상(05-03)
- 만료 sweep과 receipt prune(05-05)
- OPFS reconcile 루프(05-02)
- **사용자 데이터 삭제 보장이 부분적이다.**
- IndexedDB: LOGOUT/ACCOUNT_DELETION purge는 open이 성공해야만 돌고, dataset 전체를 지우는 경로가 port에 없다(05-03).
- OPFS: purge 뒤에도 chunk 바이트가 디스크에 남는다(05-04).
- **신·구 버전 탭 공존.** 설계 문서의 `future-schema`/`INCOMPATIBLE` 상태는 코드에 없다. 이전 버전 탭은 `MIGRATION_FAILED`/`READ_ONLY`를 받지만 실제로는 읽기도 못 한다(05-06).
- **미검증:** 실제 브라우저에서의 다중 탭 OPFS 경합, 실제 quota 초과, 2 GiB 객체 검증 시간은 확인하지 못했다. 게다가 단위 테스트 대역이 바로 이 동작을 숨긴다(05-08).
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`. 미커밋은 `CLAUDE.md`와 가이드 문서뿐 |
| 목적·실행 구성 | 템플릿 reference runtime의 저장소·kernel 성숙도. 브라우저 SPA, 여러 탭 동시 실행 지원, SSR 없음 |
| 읽은 코드 | kernel 전 파일(`indexeddb-connection.ts`, `indexeddb-transaction.ts`, `abortable-operation.ts`, `browser-lifecycle.ts`, `retry-after.ts`, `bounded-capacity.ts`, 배럴), IndexedDB 런타임 전 파일(runtime, maintenance, governance, records, migrations, failure, types), Web Storage 어댑터·코덱·`src/contracts/storage-keys.ts`, `browser-file-storage/`(storage-manager, result), 관련 port(`src/application/ports/browser-file-storage/*`), `.dependency-cruiser.json`, `scripts/test-browser-file-storage-runtime-removal.ts`와 `scripts/lib/removal-fixture.ts`, `config/ci/gates.json`의 FE-GATE-008/020 |
| OPFS 하위 범위 | 보조 에이전트가 OPFS 7개 파일과 테스트를 읽고 재현했다. High 2건(05-01, 05-02)과 05-04는 이 리뷰어가 재현 스크립트를 다시 실행하고 해당 코드 줄을 직접 읽어 확인했다. 그 밖의 OPFS 항목은 보조 에이전트가 읽은 결과에 코드 확인을 일부 더한 것이다 |
| 문서 | `docs/operations/browser-file-storage-recovery.md`, `docs/operations/client-cache-and-storage-recovery.md`, `docs/architecture/browser-file-and-origin-storage.md` §6·§7·§11, VD-11, VD-15 |
| 실행한 테스트 | `node scripts/run-vitest.ts run` 대상 8파일(indexeddb-connection/transaction/runtime/maintenance, abortable-operation, storage-manager-adapter, browser-storage-policy, storage-registry) → **167/167 통과**. 보조 에이전트가 실행한 OPFS 3파일(opfs-worker-runtime 48, opfs-byte-store 22, indexeddb-opfs-journal 13) → **83/83 통과** |
| 재현 실험 | scratchpad `05/`에서 `node --experimental-transform-types`로 실행. repo 소스를 import만 하고 repo에는 쓰지 않았다.<br>① `idb-experiments.ts`: 결과가 E1~E4로 05-03, 05-06, 05-05의 근거다.<br>② `fake-fidelity.ts`: 메모리 IndexedDB와 실제 IndexedDB의 차이 5가지(05-08).<br>③ `opfs/reconcile-vs-live-put.ts`, `quota-receipt.ts`, `logout-remnant.ts`: 05-01, 05-02, 05-04 |
| 가드레일 실험 | `git worktree`로 분리한 사본에서 adapter 간 금지 import 2건을 넣고 `scripts/check-architecture.ts`를 실행했다. 두 건 모두 `adapters-do-not-know-other-concrete-adapters` 위반으로 검출됐다. worktree는 `git worktree remove --force`로 지웠다 |
| 확인하지 못한 범위 | ① Playwright `test:browser-capabilities`: 3엔진 브라우저 설치와 dev 서버가 필요하고 CI FE-GATE-008이 담당하므로 실행하지 않았다. 스펙은 읽었다.<br>② `test:browser-file-storage-removal`: repo 사본에서 test:all과 build를 전부 다시 돌리는 작업이라 브리프 범위 밖이다. 스크립트만 읽었다.<br>③ 실제 Web Locks, 실제 OPFS quota, 파일 핸들 무효화 |
| 직전 리뷰 비교 | 2026-09-24 리뷰 6.5절 1~10을 현재 코드에서 다시 확인했다. 결과는 아래 표와 같다 |
직전 리뷰 6.5 재확인:
| ID | 현재 상태 | 근거 |
|---|---|---|
| 6.5-1 OPFS GC 커서 | 해결. 한계는 코드에 표시돼 있다 | `opfs-byte-store-adapter.ts:1097-1110` digest 커서 페이징. 호출마다 가장 작은 digest부터 다시 시작한다는 한계가 `ponytail:` 주석으로 적혀 있다 |
| 6.5-2 dedup 재사용 청크 보호 | 해결 | worker `opfs-worker-runtime.ts:1240-1256`이 재사용 청크의 mtime을 갱신한다. 다만 청크 전체를 다시 쓰므로 임시 quota를 쓰고, 이 쓰기가 `QUOTA_EXCEEDED`로 실패할 수 있다 |
| 6.5-3 lock 대기와 RPC 타임아웃 | 해결 | lock 대기 상한이 별도 값이다(`opfs-policy.ts:58`, 10분). 넘으면 `BLOCKED`. 멈춘 put이 lock을 쥐는 문제는 05-07에 따로 적었다 |
| 6.5-4 파티션 purge가 손상 행에 막힘 | **부분 해결** | 행 단위는 고쳐졌다(`indexeddb-runtime.ts:2229-2451`, 테스트 `indexeddb-runtime.test.ts:1246`). open 단계 손상과 만료 sweep은 그대로다 → 05-03, 05-05 |
| 6.5-5 prepared-object 검증기 | **부분 해결** | `opfs-prepared-object.ts`로 합쳐졌고 저장된 객체는 자기 chunk 크기로 검증한다. `stableJson` 2벌, objectId 정규식 하드코딩이 남아 있다 → 05-10 |
| 6.5-6 openObject 이중 읽기 | 해결 | 보조 에이전트 확인(client `:343-355`, worker `:717`, `:773-778`) |
| 6.5-7 IndexedDB 저장 행 검증기 중복 | 해결 | runtime·maintenance·governance가 `indexeddb-records.ts`를 import한다. binding 검증의 수제 트랜잭션은 남아 있다 → 05-12 |
| 6.5-8 삭제 후 revision 재시작 | 문서화 | `indexeddb-port.ts` `IndexedDbWriteReceipt` 주석(D-13), `opfs-ports.ts:29-35` |
| 6.5-9 보상 실패 시 원래 코드 유지 | 코드는 해결, runbook은 미갱신 | adapter `:917-947`. `browser-file-storage-recovery.md:17-21`은 예전 코드를 적고 있다 → 05-09 |
| 6.5-10 kernel 계약 구멍 2개 | 해결 | `indexeddb-transaction.ts:269-280`, `indexeddb-connection.ts:337-341`. 테스트는 `indexeddb-connection.test.ts:472-530` |
## 3. 확인된 강점
1. **IndexedDB 상태 기계가 kernel 한 곳에 있다.** open, versionchange, blocked, 트랜잭션 결론을 한 곳에서 처리한다.
- 결론은 한 번만 난다. 늦게 온 연결은 닫는다(`src/adapters/platform/indexeddb-connection.ts:273-277`, `:420-425`).
- open이 이미 결론 난 뒤 시작된 upgrade는 중단한다(`:337-341`).
- versionchange가 오면 연결을 바로 닫고 캐시 핸들을 버린다(`:473-486`).
- 성공 뒤에 온 실패가 이긴다(`indexeddb-transaction.ts:269-280`).
- 실제 브라우저 2탭 versionchange·blocked 테스트가 있다(`tests/browser-capabilities/indexeddb-runtime.spec.ts:920`, `:972`). 이 테스트는 CI FE-GATE-008에서 Chromium·Firefox·WebKit으로 돈다(`config/ci/gates.json:1836-1845`).
2. **IndexedDB CAS의 저장 규칙이 한 트랜잭션 안에서 지켜진다.** 한 readwrite 트랜잭션이 다음을 함께 처리한다.
- record, retention sidecar, dataset budget, idempotency receipt 갱신
- revision CAS와 같은 키 재실행 판정(`indexeddb-runtime.ts:1488-1731`)
- commit이 실패하면 전부 되돌린다(테스트 `indexeddb-runtime.test.ts:346`). 여러 탭의 동시 쓰기는 IndexedDB가 트랜잭션을 순서대로 실행하므로 막힌다.
3. **스키마·데이터 migration 절차가 안전한 순서를 지킨다.**
- DDL은 추가만 허용한다(`indexeddb-migrations.ts`).
- codec migration은 변환을 트랜잭션 밖에서 한다.
- 쓸 때 revision과 codec version을 다시 확인하고, checkpoint를 CAS로 갱신한다(`indexeddb-maintenance.ts:746-985`).
- 이전 버전 writer가 다 빠졌다는 확인 없이는 시작하지 않는다(`:1006-1027`).
4. **사용자별 저장소가 이름으로 분리된다.** DB 이름은 opaque token 3개에서만 만든다(`indexeddb-governance.ts:67-80`). 저장된 scope·policy binding을 upgrade, open, maintenance 때마다 확인한다(`:163-322`). 관측 이벤트에는 key, 값, 계정이 들어가지 않는다(`indexeddb-types.ts` `IndexedDbObservation`).
5. **Web Storage는 신·구 버전 탭이 서로의 값을 지우지 않는다.**
- 물리 키에 `schemaVersion`이 들어간다(`src/contracts/storage-keys.ts:165-171`). 그래서 스키마를 올리면 다른 키를 쓰게 된다.
- 코덱은 accessor, 이상한 prototype, 크기 초과를 저장 전에 거절한다(`browser-storage-codec.ts:126-231`).
- 제거 대상은 해당 물리 키 하나뿐이다(`browser-storage-adapter.ts:84-101`).
6. **kernel 예외 범위가 지켜지고, 위반하면 자동으로 걸린다.**
- `src/adapters/**`의 그룹 간 import 대상은 전부 `platform/`, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts` 중 하나다(전수 확인).
- 위반 2건을 넣은 실험에서 `check:architecture`가 둘 다 검출했다.
- 런타임 제거 드릴이 CI FE-GATE-020에서 돈다(`config/ci/gates.json:2072-2080`).
## 4. 발견 사항 (36.3)
### 05-01 OPFS reconcile이 진행 중인 put의 파일을 지우고, put은 성공으로 보고된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 12, 1, 6, 11, 28 |
| 근거 | ① reconcile은 미완료 journal 행을 모두 가져오고, 행 주인이 아직 살아 있는지 보지 않는다(`indexeddb-opfs-journal.ts:688-728`, `opfs-byte-store-adapter.ts:566`).<br>② `PREPARING` 행이면 `cleanupTransaction`을 부른 뒤, 행에 적힌 주인의 `fencingToken`으로 rollback한다(`opfs-byte-store-adapter.ts:957-976`). 주인의 토큰을 그대로 쓰므로 fence가 주인을 막지 못한다.<br>③ worker cleanup은 mutation lock을 기다린다. lock은 FINISH_PUT이 끝나면 풀린다(`opfs-worker-runtime.ts:543-546`). 그 직후 cleanup이 receipt에 적힌 generation과 manifest를 지운다(`:890-918`).<br>④ journal rollback은 `FILES_READY` 행도 받아들인다(`indexeddb-opfs-journal.ts:641-647`).<br>⑤ 재현 결과(`scratchpad/05/opfs/reconcile-vs-live-put.ts`, 실제 adapter·worker·journal에 메모리 FS와 FIFO 배타 lock을 붙임): 첫 put은 `tab A put: ok gen 1` → `tab B reconcile: CONFLICT` → `open: INTEGRITY_FAILED`. 덮어쓰기도 `ok gen 2` 뒤 `INTEGRITY_FAILED`였고, gen 1도 사라졌다 |
| 발생 조건 | 탭 B(또는 같은 탭)의 `maintenance.reconcile()`이 탭 A의 put이 진행되는 동안 실행된다. 앱 시작 때 reconcile을 돌리는 흔한 조합에서 두 번째 탭을 열기만 해도 생긴다. runbook도 운영자에게 reconcile 실행을 안내한다(`browser-file-storage-recovery.md:25`) |
| 영향 | 성공으로 보고된 쓰기가 사라진다. 덮어쓰기라면 이전 버전도 사라진다. 설계 문서의 "committed row는 partial file을 가리키지 않는다"(§7.2)가 깨진다 |
| 심각도·우선순위 | High · P1. 지원 범위인 여러 탭 실행에서 사용자 데이터가 조용히 사라진다. repo에서는 조합되지 않았지만 OPFS를 조합하는 순간 모든 다운스트림에 복제되므로, 조합 전에 막아야 한다 |
| 통제·증거 | M1(설계 문서의 약속만 있음) · E2(메모리 FS 재현). 실제 브라우저는 미검증 |
| 확실성과 남은 가정 | 경쟁 순서는 코드로 확인했다. 실제 Web Locks가 FIFO라는 가정은 재현 스크립트와 같다. 실제 브라우저에서의 타이밍은 미검증이다 |
| 최소 개선 방향 | reconcile이 살아 있는 put의 행을 건드리지 못하게 한다. 방법은 ① 트랜잭션별 Web Lock을 begin부터 complete까지 잡고, reconcile은 `ifAvailable`로 잠기지 않은 행만 처리한다. ② 또는 물리 삭제 전에 journal에서 fencing token을 CAS로 넘겨받는다(소유권 이전). 비교 대안인 "시작 후 N분 지난 행만" 방식은 시계에 의존하므로 보조 수단으로만 쓴다 |
| 비용·부작용 | 트랜잭션별 lock 이름 규칙이 추가된다. 탭이 비정상 종료되면 lock이 자동으로 풀리므로 복구 경로는 유지된다 |
| 완료 기준 | 두 런타임이 같은 root와 journal을 공유하는 상태에서 put과 reconcile을 겹쳐 실행해도 ① put이 성공이면 `open`이 성공하고 ② reconcile은 해당 행을 건너뛴다 |
| 검증 방법 | 재현 스크립트를 단위 테스트로 옮긴다(실제 journal + 배타 lock 대역). 실제 브라우저 2탭 스펙을 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음(6.5-2의 GC 경합과는 다른 경로) |
### 05-02 첫 receipt 쓰기가 실패하면 빈 `receipt.json`이 남아 authority 전체의 reconcile과 GC가 영구히 멈춘다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 6, 28, 11, 14 |
| 근거 | ① `writeJsonAtomic`은 `getFileHandle({create:true})`로 빈 파일을 먼저 만든 뒤 쓴다(`opfs-worker-runtime.ts:1292-1303`).<br>② `beginPut`에서 첫 `writeReceipt`가 실패하면 lease만 풀고 빈 receipt는 남긴다(`:398-417`).<br>③ 보상 cleanup이 그 파일을 파싱하다 `CORRUPT_DATA`를 던진다(`:1306-1315`). 코드는 "읽을 수 없는 staging은 남긴다"는 방침에 따라 파일을 지우지 않는다(`:893-903`).<br>④ reconcile 루프는 첫 실패에서 바로 반환하므로 GC 단계까지 가지 못한다(`opfs-byte-store-adapter.ts:600-613`).<br>⑤ 재현 결과(`quota-receipt.ts`): put `QUOTA_EXCEEDED/RECONCILE` → reconcile을 반복해도 매번 `CORRUPT_DATA` → 같은 id로 다시 put하면 `CONFLICT/NONE` → 다른 id의 put은 성공하지만 reconcile은 계속 `CORRUPT_DATA` |
| 발생 조건 | origin이 quota에 닿은 상태에서 put을 시작할 때(첫 쓰기가 가장 먼저 실패한다), 또는 파일 생성과 쓰기 사이에 탭이 크래시할 때 |
| 영향 | ① 해당 objectId가 영구히 막힌다. ② GC가 돌지 않아 quota가 회수되지 않는다. 문제를 일으킨 quota 부족이 스스로 풀리지 않는다. ③ `listIncomplete`에는 scope 필터가 없어 같은 authority의 모든 partition에서 reconcile이 멈춘다. ④ runbook은 journal 행 수동 삭제를 금지하므로(`browser-file-storage-recovery.md:28`) 승인된 탈출 경로가 없다 |
| 심각도·우선순위 | High · P1. 복구 경로가 없는 정지이고, 복구가 가장 필요한 상황(quota 부족)에서 생긴다. OPFS 조합 전 차단 항목이다 |
| 통제·증거 | M0(이 경로를 처리하는 코드가 없음) · E2(메모리 FS 재현) |
| 확실성과 남은 가정 | 실제 OPFS에서 `getFileHandle({create:true})`가 빈 파일을 바로 만들고, 쓰기에 실패하면 swap 파일만 버린다는 가정을 두었다. 이는 표준 동작이다. 실제 브라우저에서 quota를 재현하지는 않았다 |
| 최소 개선 방향 | ① 0바이트 receipt는 "receipt 없음"으로 처리한다. ② reconcile 루프는 실패한 행을 건너뛰고 세고 계속 진행한 뒤 GC까지 간다. 05-05와 같은 방식이다 |
| 비용·부작용 | 작다. 건너뛴 행은 관측 이벤트로 보고해야 조용히 묻히지 않는다 |
| 완료 기준 | 첫 쓰기에서 quota 실패를 주입한 뒤 ① reconcile이 그 행을 정리하거나 건너뛰고 ② GC까지 실행되고 ③ 같은 id의 재시도가 성공한다 |
| 검증 방법 | worker 단위 테스트에 "빈 receipt 파일" 픽스처를 추가하고, adapter 테스트에 "행 하나 실패 + 나머지 정상"을 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 05-03 IndexedDB LOGOUT/ACCOUNT_DELETION purge는 open이 성공해야만 돌고, dataset을 지우는 경로가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 11, 15, 28, 27 |
| 근거 | ① `enforceLifecycleBatch`는 `runTransaction`을 거치고, `runTransaction`은 캐시된 연결(`connection.current()`)이 없으면 바로 `UNAVAILABLE`을 반환한다(`indexeddb-runtime.ts:823-836`, `:2453-2510`).<br>② open의 admission이 governance binding과 budget 행을 검증한다. budget 행 모양이 틀리거나 `usedBytes > hardBudgetBytes`이면 `CORRUPT`로 보고 `POLICY_REJECTED`로 open을 거절한다(`indexeddb-governance.ts:278-289`, `indexeddb-runtime.ts:696-728`, `:599-609`).<br>③ port에는 dataset 삭제(`deleteDatabase`) 연산이 없다(`indexeddb-port.ts` `IndexedDbRepositoryPort`). kernel에 `deleteIndexedDbDatabase`가 있지만 이 런타임은 쓰지 않는다.<br>④ 재현 결과(E1): budget 행을 손상시킨 뒤 새 런타임의 open → `POLICY_REJECTED`, `ACCOUNT_DELETION` → `UNAVAILABLE/REOPEN`, 개인 record가 그대로 남았다 |
| 발생 조건 | governance 행(binding 또는 budget)이 손상됐을 때. 다음 경우도 같은 결과가 된다(일시적): 정책 값이 바뀐 새 release, 이전 버전 탭(05-06), blocked upgrade |
| 영향 | 계정 삭제나 로그아웃 뒤에도 그 기기에 개인 데이터가 남는다. 행 손상은 R-5.4로 고쳤지만 같은 종류의 손상이 한 단계 앞(open)에서 여전히 purge를 막는다 |
| 심각도·우선순위 | Medium · P2. 손상이 있어야 생기고 피해는 기기 한 대로 한정된다. 다만 계정 삭제 계약이 걸린 경로이고 다운스트림에 복제된다. PERSONAL/CONFIDENTIAL dataset을 조합하기 전에 고친다 |
| 통제·증거 | M2(행 단위만 구현) · E2(메모리 IndexedDB 재현) |
| 확실성과 남은 가정 | 경로는 코드와 재현으로 확인했다. 실제 기기에서 governance 행이 손상되는 빈도는 모른다 |
| 최소 개선 방향 | LOGOUT/ACCOUNT_DELETION에 한해, open(admission)이 `POLICY_REJECTED`/`CORRUPT`로 실패하면 authority 승인을 받은 뒤 `deleteIndexedDbDatabase`로 dataset DB 전체를 지우는 경로를 둔다. runbook의 "DB 전체 삭제는 data owner 승인 action" 원칙은 `authorizeLifecycle` proof로 충족한다. 같은 연산이 capability 제거 시 기기 데이터 정리(관점 27)에도 쓰인다 |
| 비용·부작용 | port에 메서드가 하나 는다(추가만 하는 변경). blocked 상태의 삭제는 결과를 알 수 없으므로(kernel `BLOCKED_DEADLINE`) 결과 계약을 정해야 한다 |
| 완료 기준 | budget/binding 행이 손상된 DB에서 ACCOUNT_DELETION이 dataset을 완전히 지우고 `COMPLETE`를 반환한다 |
| 검증 방법 | E1 시나리오를 단위 테스트로 만든다. 메모리 대역은 `deleteDatabase`가 없으므로 대역에 추가해야 한다. 실제 브라우저 스펙에도 넣는다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.5-4 부분 해결 |
### 05-04 OPFS LOGOUT/ACCOUNT_DELETION purge 뒤에도 파일 바이트가 디스크에 남는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 11, 15, 24, 27 |
| 근거 | ① purge의 remove는 객체 디렉터리만 지운다(`opfs-byte-store-adapter.ts:500-505`, `opfs-worker-runtime.ts:799-810`).<br>② chunk는 GC만 지우고, GC는 쓴 지 24시간 지난 청크만 지운다(`opfs-byte-store-adapter.ts:1088-1091`, `opfs-policy.ts:61`).<br>③ 재현 결과(`logout-remnant.ts`): purge가 `removedObjects 1, releasedBytes 5`를 보고한 직후에 reconcile을 돌려도 `chunks/sha256/…bin => SECRT`가 남아 있었다 |
| 발생 조건 | 모든 LOGOUT/ACCOUNT_DELETION purge. 로그아웃한 사용자의 scope로는 다시 런타임을 열지 않을 수 있으므로 GC가 영영 돌지 않을 수 있다 |
| 영향 | 공용 기기에서 로그아웃하거나 계정을 삭제한 사용자의 파일 내용이 남는다. `removedObjects`/`releasedBytes`라는 보고가 실제 삭제 범위를 과장한다. journal의 scope binding 행도 남는다 |
| 심각도·우선순위 | Medium · P2. 개인정보 잔존이지만 같은 origin 접근이 있어야 읽을 수 있다. 개인 파일을 다루는 조합 전에 고친다 |
| 통제·증거 | M1 · E2 |
| 확실성과 남은 가정 | 청크 경로가 partition별이라 partition 디렉터리를 통째로 지워도 다른 사용자 데이터에 영향이 없다는 점은 보조 에이전트가 경로 구성(`scopeRootPath`)으로 확인했다 |
| 최소 개선 방향 | purge가 끝나면 mutation lock 안에서 `authorities/<a>/<ns>/<p>` partition 디렉터리를 통째로 지운다. 또는 해당 purge에 한해 grace 없이 GC를 돌린다 |
| 비용·부작용 | 작다. 같은 partition의 진행 중 put과 경합하므로 lock 안에서 해야 한다 |
| 완료 기준 | purge `COMPLETE` 직후 해당 partition 경로에 파일이 0개 |
| 검증 방법 | `logout-remnant.ts`를 테스트로 만든다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 05-05 만료 정리(RETENTION_SWEEP, receipt prune)가 손상 행 하나에 영구히 멈추고, receipt가 쌓여 결국 모든 쓰기가 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 6, 11, 28, 8 |
| 근거 | ① RETENTION_SWEEP은 sidecar가 손상됐거나 budget이 삭제 바이트를 감당하지 못하면 배치 전체를 `CORRUPT_DATA`로 중단한다(`indexeddb-runtime.ts:2132-2148`, `:2179-2185`). 다음 호출도 인덱스의 같은 첫 행부터 다시 시작한다.<br>② `pruneExpiredReceipts`도 손상 receipt 하나나 `receiptCount < 1`이면 중단한다(`indexeddb-maintenance.ts:1185-1193`, `:1210-1216`).<br>③ CAS는 `receiptCount > maxIdempotencyReceipts`이면 `LIMIT_EXCEEDED`를 반환한다(`indexeddb-runtime.ts:1584-1607`).<br>④ 재현 결과: E3 손상 sidecar 1개 → sweep 3회 모두 `CORRUPT_DATA`, 만료된 정상 행 a·b·c가 그대로 남음. E4 손상 receipt 1개 → prune `MIGRATION_FAILED/INDEXEDDB_MIGRATE`, 이후 CAS 한 번 성공 뒤 `LIMIT_EXCEEDED` |
| 발생 조건 | 만료 인덱스 범위 안에 손상 행이 하나 있을 때. budget 값이 어긋났을 때도 같다 |
| 영향 | ① TTL 정책이 끝난 데이터가 기기에 계속 남는다. 읽기와 query는 만료 행을 숨기므로 화면에서는 보이지 않는다. ② receipt가 정리되지 않아 상한에 닿으면 그 dataset의 모든 쓰기가 영구히 `LIMIT_EXCEEDED`가 된다. ③ receipt 손상이 `MIGRATION_FAILED`로 보고돼 운영자를 migration 절차로 잘못 보낸다 |
| 심각도·우선순위 | Medium · P2. 손상이 있어야 생기지만 한번 생기면 스스로 풀리지 않고, 쓰기 기능이 결국 멈춘다 |
| 통제·증거 | M2 · E2 |
| 확실성과 남은 가정 | 손상 행에서 멈추는 것 자체는 의도된 fail-closed로 보인다(`indexeddb-runtime.test.ts:1038`이 고정). 문제는 그 뒤의 정상 행까지 막는 범위다. runbook의 "손상된 user-authored 행 자동 삭제 0" 원칙과 충돌하지 않게 고칠 수 있다 |
| 최소 개선 방향 | 손상 행은 지우지 않고 건너뛴다(개수를 세고 `CORRUPT_DATA` 관측으로 보고한다). 커서는 다음 행으로 진행한다. R-5.4가 파티션 purge에서 쓴 방식과 같다. prune의 실패 코드는 `CORRUPT_DATA`로 바로잡는다 |
| 비용·부작용 | budget 값이 조금 어긋나도 진행하게 되므로, 어긋난 값은 파티션 purge의 0 리셋처럼 다른 경로에서 바로잡아야 한다 |
| 완료 기준 | 손상 행 1개와 만료된 정상 행 N개가 있을 때 sweep·prune이 정상 행 N개를 지우고 손상 1건을 보고한다 |
| 검증 방법 | E3·E4 시나리오를 단위 테스트로 만든다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.5-4와 같은 계열. 이번에 새로 확인 |
### 05-06 이전 버전 탭이 새 스키마(future schema)를 만나면 `MIGRATION_FAILED/READ_ONLY`를 받지만, 실제로는 읽기도 못 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서 계약과 코드 불일치, 재현) |
| 관련 관점 | 11, 18, 5, 17, 28 |
| 근거 | ① runtime은 항상 자기 `schemaVersion`으로 open한다(`indexeddb-runtime.ts:649-653`). DB가 더 높은 버전이면 `VersionError`가 나고, 이것이 `MIGRATION_FAILED`, recovery `READ_ONLY`로 바뀐다(`indexeddb-failure.ts:36-44`).<br>② 상태 타입에 future-schema 상태가 없다(`indexeddb-port.ts:23-49`).<br>③ 읽기도 캐시된 연결이 필요하므로 `UNAVAILABLE/REOPEN`이 된다(`indexeddb-runtime.ts:835-836`).<br>④ 재현 결과(E2): v2 탭이 upgrade한 뒤 v1 런타임에서 open → `MIGRATION_FAILED/INDEXEDDB_OPEN/READ_ONLY`, 상태 `CLOSED/NOT_OPENED`, read → `UNAVAILABLE/REOPEN`.<br>⑤ 문서는 다르게 약속한다: `browser-file-and-origin-storage.md:563-580`(`future-schema -> read-only|online-only`), VD-15 `:713`(`INCOMPATIBLE`), `browser-file-storage-recovery.md:173`, `:190`.<br>⑥ OPFS journal도 v1만 알고 다른 버전은 모두 거절한다(`indexeddb-opfs-journal.ts:207-212`). 동작은 같다 |
| 발생 조건 | 롤링 배포 중에 새 탭이 스키마를 올리고 옛 탭이 열려 있을 때. rollback bundle이 future schema를 만날 때 |
| 영향 | ① 데이터 손상은 없다. 파괴적 쓰기 없이 fail-closed로 끝난다. ② 하지만 "새로고침이 필요하다"는 상황이 "migration 실패"로 보고돼 runbook §5(migration/corruption 사고)로 잘못 안내된다. ③ `READ_ONLY` 안내는 따를 수 없다 |
| 심각도·우선순위 | Medium · P2. 안전성은 유지되지만 흔한 공존 상황의 진단과 UX를 잘못 이끈다. 다운스트림이 이 코드를 보고 화면 분기를 만든다 |
| 통제·증거 | M1(문서만) · E2 |
| 확실성과 남은 가정 | 메모리 대역의 `VersionError` 경로는 실제 IndexedDB 동작과 같다. 실제 브라우저 스펙에는 이 경우가 없다 |
| 최소 개선 방향 | open에서 `VersionError`(또는 `oldVersion > schemaVersion`)를 별도로 분류해, 예를 들어 `code: "UNSUPPORTED"` 또는 새 코드, `recovery: "ONLINE_ONLY"`, 상태 `INCOMPATIBLE`로 드러낸다. 문서를 코드에 맞추는 선택도 가능하다. 그 경우 "N-1은 online-only로만 동작"이라고 적고 `READ_ONLY` 안내를 없앤다 |
| 비용·부작용 | 코드를 추가하면 port 계약을 바꾸는 변경이 된다(추가만). 문서만 고치면 비용이 거의 없다 |
| 완료 기준 | E2 시나리오에서 이전 버전 탭이 문서에 적힌 상태와 recovery를 받는다 |
| 검증 방법 | 단위 테스트 1개와 실제 브라우저 2탭 스펙(v2 upgrade 뒤 v1 재open) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 05-07 source가 멈춘 put 하나가 origin 전역 OPFS mutation lock을 무기한 쥔다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 12, 14, 22, 5 |
| 근거 | ① lock은 BEGIN_PUT에서 잡고(`opfs-worker-runtime.ts:368`) FINISH/FAIL/ABORT에서만 푼다.<br>② page 쪽 `rechunk`는 source 스트림을 기다리는 시간에 상한이 없다(`opfs-worker-client.ts:276-281`).<br>③ lock 이름은 origin 전체가 공유한다(`opfs-policy.ts:53`). 다른 쪽 대기 상한은 10분이다(`:58`).<br>④ reconcile 예산(5초)은 lock 대기를 세지 않는다. 기한 확인은 항목 사이에서만 한다(adapter `:604`, `:1120`)(보조 에이전트) |
| 발생 조건 | put의 source가 멈추고(네트워크 스트림 정지 등) 호출자가 signal을 넘기지 않았을 때 |
| 영향 | 모든 탭의 put, delete, finalize, GC가 10분 뒤 `BLOCKED`로 실패한다. 5초로 잡은 reconcile이 10분 걸릴 수 있다. 이 전역 직렬화는 port 계약에 드러나 있지 않다 |
| 심각도·우선순위 | Medium · P2. 탭을 닫으면 풀리므로 영구적이지 않다. D-3 결정으로 lock 범위를 좁히지 않기로 했으므로 남은 수단은 시간 상한뿐이다 |
| 통제·증거 | M1 · E1(기존 테스트 `stalledSource`가 lock 유지를 보여 준다고 보조 에이전트가 보고) |
| 확실성과 남은 가정 | 실제 브라우저에서 확인하지 않았다 |
| 최소 개선 방향 | worker의 active put에 idle timeout을 둔다(마지막 APPEND 이후 N초가 지나면 fail하고 lock을 푼다). port 주석에 "OPFS 쓰기는 origin 전체에서 한 번에 하나"를 적는다 |
| 비용·부작용 | 느린 source가 정상적으로 오래 걸리는 경우와 구분할 값이 필요하다 |
| 완료 기준 | source를 멈춘 put이 정해진 시간 안에 실패하고, 다른 탭의 put이 곧바로 진행된다 |
| 검증 방법 | 배타 lock 대역을 쓰는 worker 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.5-3의 남은 부분(타임아웃 분리는 해결, 무기한 점유는 남음) |
### 05-08 테스트 대역이 여러 탭·트랜잭션 수명·quota 동작을 숨겨, 05-01·05-02 같은 결함을 잡지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (재현으로 차이 확인) |
| 관련 관점 | 10, 12 |
| 근거 | `tests/helpers/memory-indexeddb.ts`와 실제 IndexedDB의 차이를 실험으로 확인했다(`fake-fidelity.ts`).<br>(a) 겹친 readwrite 트랜잭션 2개가 각자 스냅샷을 복제하고 store를 통째로 덮어쓴다(`:320-322`, `:486-490`). 카운터가 2가 아니라 1이 된다. 실제로는 순서대로 실행된다.<br>(b) macrotask 뒤에 낸 요청이 `TransactionInactiveError` 없이 받아들여지고 commit된다. 실제로는 예외가 난다.<br>(c) 배열 keyPath 인덱스를 primary key로 정렬한다(`:611-614`). 키 비교도 `String`/JSON으로 한다(`:118-147`).<br>(d) DB 이름을 무시한다(`:744-745`). 그래서 user-B DB가 user-A 행을 본다. 테스트가 이를 우회하려고 이름별 라우팅 factory를 따로 만들었다(`indexeddb-runtime.test.ts:1268-1272`).<br>(e) 더 높은 버전으로 open해도 기존 연결에 versionchange가 오지 않는다(수동 `triggerVersionChange`만 있음).<br>(f) upgrade 트랜잭션을 동기로 끝내므로, upgrade 안에서 비동기로 난 abort(binding 불일치)가 되돌려지지 않는다(`:939-964`).<br>OPFS 쪽(보조 에이전트): byte-store 테스트의 가짜 journal은 fence와 phase를 무시한다(`opfs-byte-store.test.ts:126-245`). 대부분의 worker 테스트는 배타성이 없는 `immediateLeases`를 쓴다. 메모리 FS에는 quota가 없다. 공유 root에서 두 런타임을 돌리는 테스트가 없다 |
| 발생 조건 | 이 대역으로 동시성, upgrade, 인덱스 정렬, quota를 검증하려 할 때 |
| 영향 | ① 이 영역의 High 결함 2건이 통과하는 테스트 옆에 숨어 있었다. ② 대역은 `tests/helpers/`에 있어 다운스트림이 그대로 복사해 쓰는데, 헤더 주석(`:723-727`)은 "transaction-level commit/rollback과 upgrade blocking을 모델링한다"고만 말하고 위 차이는 밝히지 않는다. 실제 브라우저 스펙(CI FE-GATE-008)이 일부를 보완하지만 2탭 CAS 경합, upgrade 중 binding abort, 복합 인덱스, OPFS 다중 탭은 다루지 않는다 |
| 심각도·우선순위 | Medium · P2. 테스트가 주는 확신이 과장된다. 제품 피해는 간접적이다 |
| 통제·증거 | M2 · E2(실험) |
| 확실성과 남은 가정 | 차이 (a)~(e)는 실험으로, (f)는 코드로 확인했다 |
| 최소 개선 방향 | ① 대역 헤더에 모델링하지 않는 의미를 적는다(가장 싸다). ② 가능하면 대역이 DB 이름 분리, 트랜잭션 직렬화, 비활성 요청 예외를 흉내 내게 한다. ③ OPFS는 배타 lock 대역과 공유 root 2런타임 테스트 1개를 추가한다. 이 테스트가 05-01을 잡는다. 실제 브라우저 2탭 OPFS 스펙 추가도 검토한다 |
| 비용·부작용 | 대역을 고치면 기존 테스트 일부가 드러나는 결함 때문에 실패할 수 있다(의도된 결과) |
| 완료 기준 | 위 (a)·(b)·(d) 실험이 대역에서 실제 IndexedDB와 같은 결과를 내거나, 헤더에 명시된 비지원 항목이 된다. 05-01·05-02 회귀 테스트가 존재한다 |
| 검증 방법 | `fake-fidelity.ts`를 대역 자체의 테스트로 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.5-3 "immediateLeases가 경합을 보지 않음"과 같은 계열. 미해결 |
### 05-09 OPFS recovery runbook이 현재 코드와 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서 불일치) |
| 관련 관점 | 28, 9, 17 |
| 근거 | ① `browser-file-storage-recovery.md:17-21`은 보상 실패를 `OBJECT_RECONCILE`/`CONFLICT`(recovery `RETRY`)로 보고한다고 적었다. 코드는 put 자신의 코드를 유지하고 `OBJECT_WRITE`, recovery `RECONCILE`을 쓴다(`opfs-byte-store-adapter.ts:933-946`, Q-6.5-9에서 바뀜).<br>② `:26`의 `EFFECT_UNKNOWN`은 worker가 보내지 않는다. client 파서도 거절하므로(`opfs-worker-client.ts:652-658`) adapter 분기 `:936`, `:964`는 실행되지 않는다.<br>③ `:374-375`는 `PREPARING`은 resume, `FILES_READY` 검증 실패는 quarantine이라고 적었다. 코드는 둘 다 삭제만 한다(`opfs-byte-store-adapter.ts:957-1012`) |
| 발생 조건 | 운영자가 runbook대로 신호를 찾거나 복구를 기대할 때 |
| 영향 | 운영자가 나오지 않는 코드를 찾고, 존재하지 않는 quarantine/resume을 기대한다. 삭제되는 데이터는 commit 전 staging뿐이라 데이터 피해는 제한적이다 |
| 심각도·우선순위 | Low · P2. 문서 불일치지만 복구 절차 문서라서, 도입 전에 맞춘다 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 코드와 문서 줄을 대조했다 |
| 최소 개선 방향 | runbook의 STO-01 절과 §7 recovery를 현재 코드에 맞춘다. `EFFECT_UNKNOWN`은 port에서 없애거나 worker가 실제로 보내게 한다 |
| 비용·부작용 | 작다 |
| 완료 기준 | runbook의 코드·phase별 동작이 adapter와 일치하고, 죽은 분기가 없다 |
| 검증 방법 | `verify:documentation` 범위에 이 표를 넣을 수 있는지 검토. 최소한 수동 대조 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.5-9 후속(문서 미갱신) |
### 05-10 prepared-object 검증 통합이 덜 끝났다: objectId 정규식 하드코딩, `stableJson` 2벌
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (조건부) |
| 관련 관점 | 9, 19, 23 |
| 근거 | ① 정책의 `isObjectIdAllowed`는 바꿀 수 있다(`opfs-policy.ts:29`, `:65`). 그런데 `isPreparedObject`는 `/^[A-Za-z0-9_-]{8,128}$/`을 하드코딩했다(`opfs-prepared-object.ts:8`, `:55-56`). 정책을 넓히면 BEGIN_PUT은 통과하고 FINISH_PUT은 `CORRUPT_DATA`로 실패한다.<br>② `stableJson`이 두 벌이고 NaN 처리가 다르다(`opfs-worker-runtime.ts:1723-1734`는 throw, `indexeddb-opfs-journal.ts:1611-1619`는 `"null"`).<br>③ `sameScope`, SHA-256·generation id 정규식도 여러 곳에 중복돼 있다(보조 에이전트) |
| 발생 조건 | 다운스트림이 objectId 규칙을 넓힐 때(예: 더 긴 id). NaN은 정책 검증 때문에 현재 도달하지 않는다 |
| 영향 | 설정 하나를 바꾸면 모든 put이 마지막 단계에서 실패하고 journal 행이 남는다 |
| 심각도·우선순위 | Low · P3. 기본 설정에서는 생기지 않는다 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | 코드로 확인했다. 실행 재현은 하지 않았다 |
| 최소 개선 방향 | `isPreparedObject`가 objectId 문법을 policy에서 받거나, policy의 허용 범위를 prepared-object 문법 안으로 제한(검증)한다. `stableJson`은 한 벌만 남긴다 |
| 비용·부작용 | 작다 |
| 완료 기준 | 넓힌 objectId 정책으로 put이 끝까지 성공하거나, 정책 생성 시점에 거절된다 |
| 검증 방법 | 정책 확장 단위 테스트 1개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.5-5 부분 해결 |
### 05-11 IndexedDB 예외 매핑 표가 두 벌이고, OPFS가 IndexedDB 폴더에 묶여 "각자 독립 제거 가능" 주장이 사실과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (주석 주장 불일치) + 개선 제안 |
| 관련 관점 | 9, 27, 2, 23 |
| 근거 | ① IndexedDB 예외 매핑 표가 두 벌이다: `storage/indexeddb/indexeddb-failure.ts:22-72`(runtime, maintenance, OPFS journal이 사용)와 `browser-file-storage/result.ts:43-90`(checkpoint store 등이 사용). 결과가 다르다. `QuotaExceededError`의 retryable 값, `NotFoundError`, `TransactionInactiveError`, `ConstraintError` recovery가 서로 다르다. runtime 주석(`indexeddb-runtime.ts:553-557`)은 "통합은 별도 변경"이라고만 적었고 제거 조건과 담당이 없다.<br>② OPFS journal이 `../indexeddb/indexeddb-failure.ts`를 import한다(`indexeddb-opfs-journal.ts:34`). 같은 `storage` 그룹이라 규칙상 허용된다.<br>③ `.dependency-cruiser.json:207` 주석은 "storage/indexeddb와 storage/opfs가 각자 독립적으로 제거 가능"하다고 하고, `storage/index.ts:5-7`은 제거 스크립트가 "그 두 폴더만 삭제"한다고 한다. 실제 스크립트는 10개 경로를 한꺼번에 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:23-34`). IndexedDB만 제거하는 경우는 검증되지 않고, 그렇게 하면 OPFS 빌드가 깨진다 |
| 발생 조건 | 다운스트림이 IndexedDB 런타임만 제거하거나, 두 매핑 표 중 하나만 고칠 때 |
| 영향 | 부분 제거가 실패한다. 같은 브라우저 예외에 대해 IndexedDB를 쓰는 두 어댑터가 다른 재시도 판단을 내린다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | import와 스크립트 경로 목록으로 확인했다 |
| 최소 개선 방향 | `mapIndexedDbException`을 kernel 예외 파일인 `browser-file-storage/result.ts`로 옮기고 `mapBrowserDataException`과 차이를 정리한다. 두 주석은 실제 드릴 범위("browser-file-storage 번들 전체를 함께 제거")에 맞게 고친다. 새 파일 단위 예외는 필요 없다 |
| 비용·부작용 | 매핑을 합치면 checkpoint store 등의 실패 코드가 바뀔 수 있어 테스트 갱신이 필요하다 |
| 완료 기준 | `storage/opfs/`에서 `storage/indexeddb/`로 가는 import가 0개. 주석이 드릴 범위와 일치 |
| 검증 방법 | import 그래프 확인. 원하면 IndexedDB만 제거하는 드릴 변형 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 05-12 binding 검증이 kernel 밖에서 트랜잭션 상태 기계를 손으로 다시 구현한다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 9, 22 |
| 근거 | `verifyIndexedDbDatasetBinding`이 `oncomplete`/`onabort`/`onerror`와 caller abort를 직접 연결한다(`indexeddb-governance.ts:223-322`). `src/adapters`에서 kernel 밖에 `oncomplete`를 쓰는 곳은 여기 하나뿐이다. kernel의 CP-4 처리(abort가 throw하면 abort 주장을 철회, `indexeddb-transaction.ts:218-230`)가 이 복사본에는 없다 |
| 발생 조건 | kernel 트랜잭션 의미를 바꿀 때 이 복사본이 따라가지 않는다 |
| 영향 | 지금은 읽기 전용 검증이라 잘못된 결론의 피해가 작다. 다섯 번째 복사본이 다시 갈라질 여지가 있다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | grep과 코드로 확인했다 |
| 최소 개선 방향 | `runIndexedDbTransaction` + `onIndexedDbRequest`로 바꾼다 |
| 비용·부작용 | 작다. 동작을 고정하는 테스트가 있다(`indexeddb-runtime.test.ts:842`) |
| 완료 기준 | `src/adapters`에서 kernel 밖 `oncomplete` 사용 0곳 |
| 검증 방법 | 기존 binding 테스트 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.5-7 후속 |
### 05-13 IndexedDB 연결의 versionchange 핸들러가 비동기 admission이 끝난 뒤에야 설치된다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 12, 22 |
| 근거 | ① `onsuccess` 뒤 `admit`이 비동기로 binding 검증 트랜잭션을 돈다(`indexeddb-connection.ts:420-445`, `indexeddb-runtime.ts:696-728`).<br>② `onversionchange`는 open이 결론 난 뒤 `adopt`에서만 설치된다(`indexeddb-connection.ts:491-505`, `:473-486`). 그 사이 다른 탭이 upgrade를 요청하면 이 연결은 닫히지 않고, 상대는 blocked 기한(기본 10초)까지 기다리다 `BLOCKED`로 실패한다.<br>③ maintenance는 admit 안에서 먼저 핸들러를 설치한다(`indexeddb-maintenance.ts:429`). runtime만 이 창이 열려 있다 |
| 발생 조건 | 탭 A의 open admission(트랜잭션 1개, 수 ms)과 탭 B의 upgrade 요청이 겹칠 때 |
| 영향 | 탭 B의 upgrade가 한 번 실패한다. 재시도하면 이번에는 핸들러가 있어 풀린다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | 코드 순서로 판단했다. 재현하지 않았다 |
| 최소 개선 방향 | kernel `openIndexedDbDatabase`가 `onsuccess` 직후, admission 전에 임시 versionchange 핸들러(닫고 `CLOSED`로 결론)를 설치한다 |
| 비용·부작용 | 작다 |
| 완료 기준 | admission 중 versionchange가 와도 연결이 닫히고 open이 실패로 끝난다 |
| 검증 방법 | 대역에서 admission 중 `triggerVersionChange` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 05-14 OPFS GC의 유예 기간을 "참조가 끊긴 시각"이 아니라 "쓴 시각"으로 센다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (보조 에이전트 보고, 코드 일부 확인) |
| 관련 관점 | 12, 11 |
| 근거 | GC 후보는 mtime이 24시간 지난 청크다(`opfs-byte-store-adapter.ts:1088-1091`). 청크 읽기는 lock 없이 한다(worker `:767`, 보조 에이전트). 세대 N+1이 commit되면 N의 오래된 청크는 곧바로 삭제 대상이 된다 |
| 발생 조건 | 세대 N을 스트림으로 읽는 도중 N+1 commit과 reconcile GC가 끼어들 때 |
| 영향 | 읽기 스트림이 중간에 `NOT_FOUND`로 끊긴다. 재시도하면 새 세대를 읽으므로 데이터 손실은 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 재현하지 않았다 |
| 최소 개선 방향 | 참조가 끊길 때 청크 mtime을 갱신하거나, 읽기 중인 세대를 GC가 알 수 있게 한다. 또는 port 주석에 "읽기 중 교체되면 NOT_FOUND 가능"을 적는다 |
| 비용·부작용 | 작다 |
| 완료 기준 | 선택한 방향에 맞는 테스트 또는 계약 주석 |
| 검증 방법 | worker 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용. 저장 규칙(CAS, revision, 재실행 판정, budget) | 목표 M2 / 확인 M2 | E2(167+83 통과), E2 재현 | 부분 충족 — 05-01(성공한 put 뒤 파일 삭제) |
| 2 | 구조적 성숙도 | 적용. kernel 예외 범위 | 목표 M3 / 확인 M3 | E3(worktree에 위반 2건 주입 → `check:architecture` 검출) | 충족 — 잔여: 같은 그룹 안 런타임 간 결합은 규칙이 보지 않는다(05-11). 참고: `depcruise` 자체는 TS 7에서 0 modules를 검사하고, 실제 판정은 스크립트 자체 그래프가 한다(다른 영역 — 가드레일) |
| 3 | 변경 용이성 | 적용. 정책·설정 변경 | M1 | E1 | 부분 충족 — dataset 정책 값(budget, TTL)을 바꾸면 binding 불일치로 기존 DB가 잠기고, 이행 경로는 문서상 "forward fix"뿐이다. objectId 정책 확장이 깨진다(05-10) |
| 4 | 인지 부하 | 적용 | — | E1 | 부분 충족 — kernel 덕분에 상태 기계는 한 곳에 있다. `indexeddb-runtime.ts`(2539줄)의 CAS는 여전히 콜백이 10단 넘게 중첩된다(`:1498-1729`) |
| 5 | 위험 가시성 | 적용 | M1 | E1 | 부분 충족 — D-13과 실패 분류는 port에 드러나 있다. origin 전역 OPFS 직렬화(05-07)와 future schema 의미(05-06)는 드러나 있지 않다 |
| 6 | 실패 성숙도 | 적용 | M2 | E2 | 부분 충족 — 손상 한 건이 정리 작업 전체를 멈추는 패턴(05-02, 05-05). quota는 `QUOTA_EXCEEDED`로 매핑되고 rollback된다(E2) |
| 7 | 운영 성숙도 | 적용(연결점만) | M1 | E1 | 부분 충족 — `observe` 연결점과 safe bucket 이벤트가 있다. 조합이 없어 실제 알림 경로는 없다(0.1 전제상 비대상) |
| 8 | 디버깅 가능성 | 적용 | M2 | E2 | 부분 충족 — 실패 코드가 닫혀 있고 원문을 노출하지 않는다. `MIGRATION_FAILED`가 receipt 손상(05-05)과 future schema(05-06)에 잘못 쓰인다 |
| 9 | 유지보수 성숙도 | 적용. 4벌 → kernel 통합 뒤 남은 중복 | M2 | E1 | 부분 충족 — 예외 매핑 2벌(05-11), 수제 트랜잭션 1곳(05-12), OPFS `stableJson` 등(05-10) |
| 10 | 테스트 성숙도 | 적용 | M3 | E2(250개 통과), CI FE-GATE-008 3엔진 | 부분 충족 — 대역이 동시성, upgrade, quota 의미를 숨기고 High 2건을 못 잡았다(05-08) |
| 11 | 데이터 성숙도 | 적용(핵심) | M2 | E2 | 부분 충족 — 추가만 하는 DDL, 경계가 있는 codec migration, 사용자별 DB 분리는 좋다. 삭제 보장(05-03, 05-04, 05-05)과 future schema(05-06)가 남았다 |
| 12 | 동시성 성숙도 | 적용(핵심, 여러 탭) | M2 | E2 재현, 실제 브라우저 2탭 IDB 스펙 | **미충족** — 05-01(High, 재현). 그 밖에 05-07, 05-13, 05-14 |
| 13 | 확장성 | 부분 적용. 데이터량 | M2(배치 500행/30초, query 스캔 5000행 상한) | E1 | 미검증 — 규모 목표가 없고 측정하지 않았다 |
| 14 | 성능 성숙도 | 부분 적용 | M2 | E1 | 미검증 — 2 GiB verify가 60초 RPC 안에 끝나는지, dedup이 청크를 다시 쓰는 비용 |
| 15 | 보안 성숙도 | 적용. 사용자 데이터 분리·잔존 | M2 | E2 | 부분 충족 — opaque 이름, 관측 이벤트에서 민감정보 제거, lifecycle proof는 좋다. 로그아웃 뒤 잔존(05-03, 05-04) |
| 16 | 의존성 성숙도 | 적용 제외 — 이 영역은 외부 패키지 없이 브라우저 API만 쓴다 | — | — | 적용 제외 |
| 17 | API / Contract | 적용. port 계약 | M2 | E1 | 부분 충족 — 닫힌 실패 분류, D-13 명시. `EFFECT_UNKNOWN`은 선언만 있고 쓰이지 않는다(05-09). future schema 코드(05-06) |
| 18 | 배포 성숙도 | 적용. 신·구 탭 공존 | M2 | E2 | 부분 충족 — Web Storage 키에 버전이 들어가고 IDB versionchange를 처리한다. N-1이 future schema를 만나면 잘못 분류된다(05-06). OPFS lock 이름·root가 설정값이라 release마다 다르면 탭끼리 배제가 깨진다(보조 에이전트, 검사 없음) |
| 19 | 설정 성숙도 | 적용 | M2(생성 시 assert) | E1 | 부분 충족 — 정책 검증은 강하다. objectId 정책과 검증기가 서로 맞지 않는다(05-10) |
| 20 | 개발자 경험 | 다른 영역 — 문서·온보딩 | — | — | 적용 제외(이 영역) |
| 21 | Guardrail 성숙도 | 적용. kernel 규칙, 제거 드릴, 번들 inventory | M3 | E3(위반 주입 실험), CI 게이트 정의 확인 | 충족 — 제거 드릴 자체는 실행하지 않았다(미검증 목록) |
| 22 | 추상화 성숙도 | 적용. kernel이 숨기는 것과 드러내는 것 | M2 | E1 | 부분 충족 — kernel은 메커니즘만 갖고 정책·실패 코드는 호출자에 남긴다(`indexeddb-connection.ts:19-24`). 좋은 경계다. 숨기지 말아야 할 것이 숨어 있다: OPFS 전역 lock(05-07), admission 중 versionchange 공백(05-13) |
| 23 | 일관성 | 적용 | M1 | E1 | 부분 충족 — 같은 예외가 두 어댑터에서 다른 답을 낸다(05-11) |
| 24 | 네이밍 / 의미 | 적용 | M1 | E2 | 부분 충족 — OPFS purge의 `removedObjects`/`releasedBytes`가 실제 삭제 범위를 과장한다(05-04) |
| 25 | 조직 확장성 | 적용(구조적 준비만) | — | E0 | 미검증 — dataset별 opaque scope와 kernel 공유 구조는 준비돼 있다. 팀이 하나라 실제 검증은 불가 |
| 26 | Ownership | 적용(템플릿 칸만) | M1 | E0 | 미검증 — runbook이 owner·연락처 칸을 비워 두고 설치 branch가 채우게 한다 |
| 27 | 삭제 가능성 | 적용 | M3(코드 제거 드릴 FE-GATE-020) | E1(스크립트 읽음, 미실행) | 부분 충족 — 번들 전체 제거는 검증된다. IndexedDB만 제거하는 경우는 불가(05-11). 기기에 남은 데이터를 정리하는 API가 없다(05-03). OPFS는 purge 뒤에도 바이트가 남는다(05-04) |
| 28 | 회복 가능성 | 적용(핵심) | M1 | E2 | **미충족** — 05-02는 승인된 복구 경로가 없다. runbook과 코드가 다르다(05-09, 05-06). dataset 삭제 경로가 없다(05-03) |
적용 항목 26개 기준: 충족 2(2, 21), 부분 충족 18, 미충족 2(12, 28), 미검증 4(13, 14, 25, 26). 적용 제외 2(16, 20).
## 6. 미검증 목록
| 항목 | 이유 | 확인에 필요한 것 |
|---|---|---|
| 05-01·05-02가 실제 브라우저에서 나는지 | 재현은 메모리 FS와 FIFO lock 대역으로 했다 | Playwright 2탭 OPFS 스펙(공유 root, 실제 Web Locks). quota는 `navigator.storage` 제한 환경이나 대용량 채우기로 재현 |
| 실제 IndexedDB의 2탭 CAS 경합, upgrade 중 binding 불일치 abort | 메모리 대역이 이 의미를 모델링하지 않고(05-08), 실제 브라우저 스펙에도 없다 | `indexeddb-runtime.spec.ts`에 케이스 추가 |
| `test:browser-capabilities` 현재 결과 | 3엔진 브라우저와 dev 서버가 필요하고 CI FE-GATE-008이 담당 | 오케스트레이터나 CI의 최신 JUnit |
| `test:browser-file-storage-removal` 현재 결과 | repo 사본에서 test:all과 build를 전부 다시 도는 작업이라 브리프 범위 밖 | CI FE-GATE-020 증거 |
| 2 GiB 객체 verify가 60초 RPC 안에 끝나는지 | 성능 측정 환경 없음 | 저사양 기기 측정 |
| dedup이 청크를 다시 쓸 때 다른 탭의 열린 File이 `NotReadableError`를 내는지, swap 파일이 quota에 잡히는지 | 브라우저별 동작 | 실제 브라우저 실험 |
| STO-01 이전(v1) 쓰기만 하는 옛 탭과의 공존 | 재현 환경 없음 | 두 release를 띄운 2탭 실험 |
| OPFS 판정 중 05-07·05-10·05-14의 세부 | 보조 에이전트가 읽은 결과이고 이 리뷰어가 재현하지 않았다 | 해당 단위 테스트 추가 시 확인 |
@@ -0,0 +1,299 @@
# Service Worker / Web Push 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/adapters/service-worker/` (7파일, 약 2.4k줄), `src/adapters/web-push/` (12파일, 약 3.7k줄), `vite.service-worker.config.ts`, `tsconfig.service-worker.json`, 이 영역의 테스트(`tests/unit/service-worker-*`, `tests/unit/web-push-*` 9파일 약 5.0k줄, `tests/e2e/service-worker-update.spec.ts`, `tests/helpers/fake-push-control-repository.ts`)
> 영역 판정(35.8): **조건부 사용 가능** — Service Worker 정적 자산(`PWA_STATIC_ASSETS`)에 한한다. **Web Push는 해당 용도의 사용 보류**(06-01, 06-02).
## 1. 결론
- 기본 구성에서는 Service Worker(이하 SW)가 꺼져 있다(`src/features/installed-runtime-capabilities.ts:40`, `null`). Web Push는 빌드 단계에서 거부된다(`scripts/lib/service-worker-build-input.ts:58-62`). 그래서 아래 결함은 SW를 켜거나 Web Push를 조립한 다운스트림에서만 나타난다.
- SW 정적 자산 경로는 튼튼하다. 설치할 때 sha256·바이트 수·타입을 검증하고, 전부 성공해야만 쓴다. 해시 이름 GET만 가로채고, 이전 릴리스 캐시 1개를 남긴다. 32절 "새 배포 후 기존 탭" 시나리오는 활성화 전후 모두 옛 청크를 캐시나 네트워크에서 받는다(2.1절). 직전 리뷰 6.6-1~12는 코드와 테스트에 반영돼 있음을 현재 코드에서 다시 확인했다.
- Web Push에는 실제 브라우저에서 드러나는 결함이 2개 있다. **06-01**: 알림 클릭 핸들러가 실제 `Notification` 객체를 거부해서 모든 클릭이 무시된다. Chromium·Firefox·WebKit에서 `data`가 own property가 아님을 확인했고, 단위 재현 테스트도 실패했다. **06-02**: 두 탭에서 enable과 reconcile이 겹치면 한 탭은 `PUSH_READY`를 보고하는데, 탭들이 공유하는 native 구독과 서버 연결은 지워진다. 두 가지 실행 순서 모두 단위 테스트로 재현했다.
- 잘못 배포된 SW를 끄는 경로(28)는 페이지가 부팅해야만 동작한다. 운영 문서는 코드에 없는 "network-only kill switch"를 안내한다(06-03). 런타임 kill switch 분기를 무력화해도 관련 테스트 82개가 모두 통과한다(06-04).
- SW를 켜도 관측(observe)·차단기(blockers)·업데이트 알림이 조립되지 않는다. 그래서 설치 실패와 활성화 결과가 어디에도 보이지 않는다(06-05).
- 미검증: 여러 탭(얼어 있는 탭, 앱이 아닌 창)이 있을 때 실제 브라우저에서의 활성화, 롤백 릴리스 재설치, `service-worker.js`가 404를 줄 때 엔진별 등록 유지 여부. e2e 스펙은 이번에 실행하지 않았다.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`, 미커밋은 `CLAUDE.md`·가이드 문서뿐 |
| 목적과 실행 구성 | 템플릿. SW는 opt-in(`null` 기본), Web Push는 `NOT_SELECTED`·빌드 거부. 여러 탭은 지원 범위 |
| 읽은 코드 | 범위 전체 파일 전부. 연결 확인용: `src/contracts/service-worker.ts`, `src/contracts/web-push.ts`, `src/contracts/runtime-capabilities.ts:90-135`, `src/bootstrap/{register-service-worker,optional-runtime-host,create-runtime-composition}.ts`, `src/bootstrap/runtime-application.tsx`, `src/application/ports/out/web-push-control.ts`, `scripts/build-frontend.ts`, `scripts/generate-service-worker-assets.ts`, `scripts/generate-runtime-config.ts`, `scripts/lib/{service-worker-build-input,hosting-probe}.ts` |
| 읽은 문서(주장) | `docs/operations/release-cache-rollback.md`, `docs/operations/browser-file-storage-recovery.md` §8, `docs/operations/adapter-remediation-ledger.md`(SW/WP 행), `docs/architecture/realtime-events-web-push-and-bounded-polling.md` §5.5·§8, 설계 문서 §17.2~17.4·§24.10, `docs/architecture/optional-adapter-recipes.md` |
| 실행한 테스트 | `node scripts/run-vitest.ts run` + SW·web-push 단위 10파일 → **10 files, 126 tests passed** |
| 실험 1 (브라우저 속성) | Playwright로 Chromium·Firefox·WebKit에서 `Notification.prototype.data`가 getter인지, 인스턴스에 own `data`가 있는지 확인 → 세 엔진 모두 getter이고 `Object.hasOwn(n,"data") === false`, own key 0개 (06-01) |
| 실험 2 (분리 worktree, 삭제 완료) | ① WebIDL 형태 알림으로 click 재현 → 실패. own property 검사를 `"data" in` 으로 바꾸면 `close`/`waitUntil` 호출 확인 (06-01). ② 두 탭 push 경합 두 가지 순서 → 둘 다 실패 (06-02). ③ `disabledCleanup` 분기 무력화 변이 → 관련 5파일 82개 테스트 통과 (06-04). 재현 파일: 스크래치패드 `06/zz-review06-probe.test.ts` |
| 실험 3 | `classifyFetch`를 node로 실행해 API·다운로드 URL 분류 확인 (06-08) |
| 확인하지 못한 범위 | e2e `service-worker-update.spec.ts`(지시서상 vitest만 허용), 실제 푸시 서비스·VAPID 흐름, 여러 탭·롤백 브라우저 실험, `scripts/test-realtime-runtime-removal.ts` |
| 직전 리뷰 비교 | 6.6-1~6.6-12 반영 확인. 6.6-2 시나리오 중 "얼린 백그라운드 탭" 부분은 남음(06-07). 6.6-7 수정 분기가 새 경합 원인이 됨(06-02 순서 2) |
### 2.1 32절 "새 배포 후 기존 탭 사용" 추적
전제: SW `ACTIVE` + `PWA_STATIC_ASSETS`, 릴리스 N → N+1. 호스팅은 N+1의 `/assets/`만 서빙한다고 가정한다(e2e도 같은 가정).
```text
탭 A(빌드 N, 워커 N 제어) ── 배포 N+1 ──▶ 서버: index.html · service-worker.js · assets = N+1
├─ 탭 A의 N 청크 요청 → 워커 N: N manifest에 있음 → 현재 캐시 hit (lifecycle.ts:295-315)
├─ 브라우저 update 검사(내비게이션, 6시간 update()) → 워커 N+1 설치(자산 검증·캐시) → waiting
│ (page-controller.ts:157-161, 351-363)
├─ 새 탭 B(빌드 N+1) → N+1 청크: N manifest에 없음 + 해시 이름
│ → PREVIOUS_RELEASE_FALLBACK → N-1 캐시 miss → 네트워크 (static-assets.ts:53-56, entry.ts:106-109)
├─ [템플릿 그대로] 아무도 requestActivation()을 부르지 않음
│ → 모든 탭이 닫힐 때까지 워커 N 유지 → 옛 탭도 계속 동작 (안전)
└─ [다운스트림이 활성화 UI를 붙인 경우] requestActivation → 모든 창 drain → skipWaiting
→ 워커 N+1이 탭 A 제어 → 탭 A의 N 청크: marker로 찾은 N 캐시 hit (lifecycle.ts:226-246)
→ ACTIVATED_RELOAD_REQUIRED 전 탭 통지 → 템플릿에는 구독자 없음 (page-controller.ts:293-299)
→ 다음 배포 N+2 활성화 때 N 캐시 삭제(이전 캐시 1개만 보존)
→ 탭 A가 아직 N이면 네트워크 → 404 → presentation 청크 복구(영역 08 범위)
롤백 N+1 → N: service-worker.js = N → 같은 digest 캐시에 재설치(기존 캐시 안 지움, static-assets.ts:159)
→ waiting → 위와 같은 활성화 조건
```
정리하면 옛 청크는 현재 워커 캐시 → (활성화 뒤) 이전 릴리스 캐시 → 네트워크 순서로 찾는다. 이 경로가 끊기는 곳은 두 군데다. 첫째, 활성화가 두 번 이상 지나간 탭이다. 둘째, 첫 방문이라 SW 제어를 받지 않는 탭이다(`RELOAD_TO_ENABLE`, `page-controller.ts:206-211`). 두 경우 모두 청크 오류 복구(다른 영역)가 받는다. 이 영역에 남는 문제는 두 가지다. 탭 하나 때문에 활성화가 거절되는 것(06-07)과, 활성화·reload UI가 조립되지 않은 것(06-05)이다.
## 3. 확인된 강점
1. **설치 무결성과 사용자 데이터 차단.** 자산 수·크기 상한을 둔다(`service-worker-static-assets.ts:111-139`). 상태·타입·바이트 수·sha256을 모두 검증한다(`:291-325`). 전부 성공해야 캐시를 쓰고, 설치 기한과 늦게 끝난 작업의 정리도 있다(`:146-200`). 자산은 `credentials: "omit"`으로 받는다(`:272-277`). 그래서 인증된 응답이 SW 캐시에 들어갈 경로가 없다.
2. **가로채기 범위가 좁고 동기적으로 정해진다.** fetch 리스너는 `PWA_STATIC_ASSETS`일 때만 등록된다(`service-worker-entry.ts:94-111`). navigation, config, release manifest는 가로채지 않는다. 그래서 새 배포 뒤 HTML은 항상 새것이다. 등록은 `updateViaCache: "none"`을 쓴다(`service-worker-page-controller.ts:157-161`). `onFetch`의 저장소 예외는 모두 네트워크 폴백으로 끝난다(`service-worker-lifecycle.ts:296-307`).
3. **활성화는 핸드셰이크로만 일어난다.** install에서 `skipWaiting()`을 부르지 않고, `clients.claim()`도 없다(`service-worker-entry.ts:82-90`). nonce와 source 객체 동일성으로 응답을 짝짓는다(`service-worker-page-controller.ts:410-448`). `skipWaiting()` 실패는 거절로 처리한다(`service-worker-lifecycle.ts:357-362`). 다른 빌드 탭의 drain은 page와 worker를 함께 돌리는 seam 테스트로 확인된다(`tests/unit/service-worker-runtime.test.ts:1436`).
4. **남의 캐시와 등록을 지우지 않는다.** 캐시 이름은 정확히 일치해야 소유로 본다(`src/contracts/service-worker.ts:123-128`). 활성화 때 현재 캐시와 이전 1개를 남기고 오래된 것부터 지운다(`service-worker-lifecycle.ts:150-197`). 등록 소유권도 scope와 script가 정확히 일치해야 인정한다(`service-worker-removal.ts:33-63`). 제거는 `ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null` 단계로 진행하고 테스트도 있다(`tests/unit/service-worker-runtime.test.ts:348-460`).
5. **push payload를 신뢰하지 않는다.** 제목·본문·URL을 payload에서 받지 않고, 레지스트리에 고정된 문구만 쓴다(`inbound/push-event-adapter.ts:125-164`). payload는 exact key, 중복 JSON 멤버 거부, 3 KiB 상한, 만료·시계 차이를 검사한다(`push-codec.ts:45-125`). 클릭 경로는 레지스트리 path를 쓰고, same-origin이면서 계정 정보·해시가 없는 URL만 연다(`inbound/notification-click-adapter.ts:176-183`, `:382-394`, `notification-registry.ts:106-122`).
6. **로그아웃 해지 순서와 권한 상태를 구분한다.** 로그아웃은 fence를 먼저 회전해 REVOKED로 만들고, 그다음 backend revoke, native unsubscribe, 알림 정리 순서로 진행한다(`push-subscription-adapter.ts:391-466`). 6.6-7도 반영됐다. REVOKED나 UNASSOCIATED 상태에서 서버가 ABSENT를 돌려주면 등록하지 않고 해지한다(`:346-369`, 테스트 `web-push-subscription-adapter.test.ts:838-944`). 권한 결과는 `PUSH_DENIED` / `PUSH_PERMISSION_REQUIRED` / `PERMISSION_DISMISSED` / `PUSH_UNSUPPORTED` / `REGISTRATION_NOT_ACTIVE`로 나눠 보고한다(`:164-230`, `:527-543`).
## 4. 발견 사항
### 06-01 알림 클릭 핸들러가 실제 브라우저의 `Notification`을 거부해 모든 클릭이 무시됨
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 1, 10, 15, 22 |
| 근거 | `src/adapters/web-push/service-worker-runtime.ts:268-281`의 `notificationClickEventFacade`가 `Object.hasOwn(value.notification, "data")`(`:276`)를 요구한다. WebIDL 속성은 인스턴스가 아니라 `Notification.prototype`의 getter다. Playwright로 Chromium·Firefox·WebKit에서 확인했다. 세 엔진 모두 `Notification.prototype`에 `data` getter가 있고, `Object.hasOwn(new Notification(...), "data") === false`, 인스턴스 own key는 0개다. 분리 worktree에서 prototype getter로 `data`를 노출하는 알림으로 `notificationclick`을 보냈더니 `close()`와 `waitUntil()`이 한 번도 불리지 않았다(테스트 실패). 검사를 `"data" in notification`으로 바꾸자 둘 다 호출됐다. 기존 테스트는 모두 own `data`를 가진 plain object를 쓴다(`tests/unit/web-push-worker-runtime.test.ts:282, 338, 383, 444, 707, 795, 821, 860, 908`). |
| 발생 조건 | WEB_PUSH를 조립한 워커에서 사용자가 알림을 클릭한다. 모든 엔진에서 일어난다. |
| 영향 | 클릭이 아무 동작도 하지 않는다. 알림이 닫히지 않고, 앱 창이 열리거나 포커스되지 않는다. Q-6.6-11의 "앱 루트 열기" fallback과 클릭 URL 검증도 실행되지 않는다. `web_push_click_dispatched` 관측 이벤트도 남지 않아 운영에서 발견하기 어렵다. |
| 심각도·우선순위 | Medium · P1. 현재 빌드는 WEB_PUSH를 거부하므로(`scripts/lib/service-worker-build-input.ts:58-62`) 기본 구성에는 영향이 없다. 하지만 조립하는 순간 클릭 기능이 100% 실패하고 테스트는 통과한다. 그래서 Web Push 채택 전에 반드시 고쳐야 한다. |
| 통제·증거 | M2(검사는 구현됐지만 조건이 틀림) · E2(단위 재현) + E3(3개 엔진 속성 확인) |
| 확실성과 남은 가정 | `NotificationEvent.notification`이 `Notification` 인스턴스라는 것은 스펙상 사실이다. 실제 푸시 수신부터 클릭까지의 end-to-end는 실행하지 않았다(푸시 서버 없음). |
| 최소 개선 방향 | own property 검사를 `"data" in value.notification`으로 바꾼다. 같은 파일의 `pushEventFacade`, `windowClientFacade`는 이미 prototype을 거쳐 접근하므로 문제없다. |
| 비용·부작용 | 한 줄 변경이다. `data`가 맞지 않는 객체는 여전히 `decodeNotificationClickData`에서 거부된다. |
| 완료 기준 | 테스트 fake가 실제 WebIDL 형태(prototype accessor)를 따르고, 그 fake로 클릭 테스트가 통과한다. |
| 검증 방법 | 단위 테스트는 class 기반 fake로 만든다. 브라우저 테스트는 SW 안에서 `registration.showNotification()` 뒤 `getNotifications()`로 얻은 실제 `Notification`을 click facade에 넣는 방식으로 짠다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음. 6.6-11 수정은 이 검사 뒤에 있어 실제 브라우저에서는 도달하지 않는다. |
### 06-02 두 탭에서 enable/reconcile이 겹치면 공유 native 구독과 서버 연결이 지워지고 한 탭은 `PUSH_READY`를 보고함
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 12, 6, 10, 15 |
| 근거 | native 구독은 SW 등록당 하나라서 모든 탭이 공유한다. fence 레코드도 origin에 하나다(revision CAS). 그런데 코드는 CAS 패배와 "UNASSOCIATED인데 native가 있음"을 둘 다 자기가 남긴 잔여물로 보고 정리한다. **순서 1**: 탭 1이 enable 중이고 서버는 이미 탭 1의 등록을 commit했다. 두 탭 모두 rev 1로 prepare한다. 탭 2가 reconcile에서 ACTIVE commit을 받아 먼저 activate한다(rev 1→2). 탭 1의 activate는 `STALE_REVISION`이 되고, `activateCommit`의 보상(`push-subscription-adapter.ts:734-735`, `compensate` `:741-759`)이 서버 연결을 revoke하고 공유 native를 `unsubscribe()`한다. 재현 결과는 `enabled: PUSH_UNAVAILABLE(LOCAL_FENCE_UNSAFE)`, `reconciled: PUSH_READY`, fence `ACTIVE association_01`, `unsubscribe` 1회, 서버 연결 없음이다. **순서 2**: 탭 1의 register가 진행 중이라 서버는 아직 ABSENT다. 탭 2의 reconcile이 fence UNASSOCIATED + native 있음 + ABSENT를 보고 R-6.7 분기(`:346-369`)에서 native를 해지한다. 그 뒤 탭 1의 register가 끝나 ACTIVE로 commit된다. 재현 결과는 `reconciled: BACKEND_ASSOCIATION_MISSING`, `enabled: PUSH_READY`, `unsubscribe` 1회다. 두 순서 모두 fake repository(`tests/helpers/fake-push-control-repository.ts`)와 공유 fake native로 분리 worktree에서 재현했다. 기존 테스트에 탭 간 경합 사례는 없다. |
| 발생 조건 | 같은 브라우저 프로필의 두 탭 이상에서, 한 탭이 enable하는 동안 다른 탭이 부팅하며 reconcile한다. 또는 세션 복원으로 여러 탭이 동시에 부팅하면서 fence 전이가 필요한 경우(크래시 뒤 복구)다. 여러 탭은 지원 범위다(0.1). |
| 영향 | 사용자는 "켜짐"을 보지만 푸시가 오지 않는다. 다음 inspect나 reconcile에서야 `NATIVE_SUBSCRIPTION_MISSING`으로 드러나고, 다시 켜려면 사용자가 enable을 다시 해야 한다. 데이터 노출 경로는 없다. |
| 심각도·우선순위 | Medium · P2. 보안 피해는 없고 기능이 조용히 꺼진다. 특정 순서가 필요하고, 다음 조회에서 드러나 재활성화로 복구된다. |
| 통제·증거 | M2(CAS는 있지만 보상 범위가 과함) · E2(fake 단위 재현, 실제 브라우저 탭 경합은 미재현) |
| 확실성과 남은 가정 | 실행 순서는 테스트에서 게이트로 고정했다. 실제 발생 빈도는 네트워크 지연에 달려 있어 측정하지 않았다. |
| 최소 개선 방향 | 가장 작은 수단은 브라우저 기본 기능인 Web Locks다. `navigator.locks.request("web-push-control", …)`로 enable·reconcile·revoke를 origin 단위로 직렬화하면 두 순서가 모두 사라진다. 대안으로, 보상 전에 fence를 다시 읽어 같은 association이 ACTIVE로 commit돼 있으면 성공으로 수렴하게 할 수 있다. 또 native `unsubscribe`는 이 호출이 새로 만든 구독(`created`)일 때만 하도록 제한한다. |
| 비용·부작용 | Web Locks를 지원하지 않는 환경(구형 Safari)에서의 fallback 정책을 정해야 한다. 직렬화로 부팅 reconcile이 조금 늦어질 수 있다. |
| 완료 기준 | 두 탭 fake(같은 repository, 같은 native)로 두 순서를 모두 돌렸을 때, `PUSH_READY`를 보고한 탭이 있으면 native 구독과 서버 연결이 살아 있다. |
| 검증 방법 | 위 재현 테스트 2개를 repo 테스트로 옮긴다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음. 순서 2는 6.6-7 수정 분기가 원인이다. |
### 06-03 잘못된 SW를 끄는 경로가 페이지 부팅에 의존하고, 운영 문서는 코드에 없는 kill switch를 안내함
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서와 코드 불일치) + 구조적 위험(워커 쪽 차단 경로 없음) |
| 관련 관점 | 28, 18, 9, 5, 26 |
| 근거 | 코드에 있는 끄는 경로는 둘이고, 둘 다 페이지 코드다. ① 런타임 설정 `CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` → `serviceWorkerDisabledCleanup`(`src/contracts/runtime-capabilities.ts:124-133`) → unregister(`service-worker-page-controller.ts:117-126`). ② `REMOVE_REGISTRATION` 릴리스(`:135-143`). 둘 다 config·release manifest·contract set 검증과 첫 React effect가 끝난 뒤에 실행된다(`src/bootstrap/optional-runtime-host.ts:97-98`, `src/bootstrap/runtime-application.tsx:21-23`). 워커 쪽 출구는 없다. install에서 `skipWaiting()`을 부르지 않고(`service-worker-entry.ts:82-85`), 워커는 런타임 설정을 읽지 않는다(`:35-80`이 전부 빌드 상수). `REMOVE_REGISTRATION`·`PURGE`·`null` 모드는 `service-worker.js`를 아예 만들지 않는다(`scripts/build-frontend.ts:58-67`). 그래서 브라우저 update 검사가 받을 대체 워커가 없다. 문서 불일치는 세 곳이다. `docs/operations/browser-file-storage-recovery.md:406`은 "waiting/client-drain controller는 아직 없다"고 적었지만 실제로는 `service-worker-page-controller.ts:365-478`에 있다. `:454-455`는 "fetch interception을 network-only kill switch로 전환", "new worker activation 중지"를 조치로 안내하지만 그런 스위치는 코드에 없다. `docs/operations/release-cache-rollback.md`에는 SW 롤백 단계가 없다(롤백 워커가 waiting에 머무는 조건, 실제로 쓸 수 있는 `SERVICE_WORKER: DISABLED`, 설계 문서 `…closed-deep-design.md:3411`의 `service-worker.js` `no-cache` 요구). `verify:hosting-headers`는 worker 파일이 있는지만 본다(`scripts/lib/hosting-probe.ts:10-27`). |
| 발생 조건 | SW `ACTIVE`로 운영하던 중 워커 결함 때문에 페이지가 부팅하지 못하는 경우(예: 다운스트림이 fetch·push 핸들러를 고친 경우). 또는 장애 대응 중 운영자가 문서를 따라 kill switch를 찾는 경우. |
| 영향 | 페이지가 부팅하는 한 `SERVICE_WORKER: DISABLED`로 재빌드 없이 unregister할 수 있다. 이 부분은 잘 돼 있다. 하지만 부팅을 막는 워커는 사용자가 모든 탭을 닫을 때까지 남는다. `REMOVE_REGISTRATION` 릴리스는 교체 워커를 만들지 않으므로 이 경우를 해결하지 못한다. 장애 중 운영자는 없는 스위치를 찾느라 시간을 쓴다. |
| 심각도·우선순위 | Medium · P2. 템플릿 워커의 fetch 경로는 방어적이다(`onFetch` 예외를 모두 null로 바꾸고 네트워크로 넘김, `service-worker-lifecycle.ts:296-307`). 템플릿 그대로일 때 부팅을 막는 경로는 찾지 못했다. 피해는 다운스트림이 워커를 고친 경우와 장애 대응 시간에 한정된다. |
| 통제·증거 | 페이지 쪽 M2 / 워커 쪽 M0 · E1 |
| 확실성과 남은 가정 | `service-worker.js`가 404일 때 엔진이 기존 등록을 유지하는지는 확인하지 않았다(스펙상 update 실패, 등록 유지로 읽힘). |
| 최소 개선 방향 | ① `browser-file-storage-recovery.md` §8을 코드에 맞게 고친다. 없는 스위치를 지우고, `CAPABILITY_OVERRIDES.SERVICE_WORKER=DISABLED`의 절차와 효과(다음 부팅 때 unregister, 캐시는 유지)를 적는다. ② 부팅을 막는 워커용 비상 경로를 하나 정한다. 예: install에서 `skipWaiting()`, activate에서 소유 캐시 삭제와 `registration.unregister()`를 하는 "자기 해제 워커"를 같은 URL에 산출하는 빌드 모드를 만들고, `REMOVE_REGISTRATION`도 이 워커를 내보내게 한다. ③ `release-cache-rollback.md`에 SW 선택 시의 롤백 단계를 추가한다. |
| 비용·부작용 | 문서 수정은 작다. 자기 해제 워커는 빌드 모드 1개와 e2e 1개가 필요하다. |
| 완료 기준 | 운영 문서의 모든 조치가 실제 코드 경로를 가리킨다. 부팅 불가 워커 시나리오를 e2e로 한 번 복구해 본다. |
| 검증 방법 | 두 빌드 e2e 헬퍼(`tests/e2e/support/service-worker-builds.ts`)로 "fetch가 실패하는 워커 A → 자기 해제 워커 B" 복구를 확인한다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 06-04 런타임 kill switch(`SERVICE_WORKER: DISABLED` → unregister) 분기가 어떤 테스트로도 검증되지 않음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(검출력 공백) |
| 관련 관점 | 10, 28, 21 |
| 근거 | `service-worker-page-controller.ts:117-126`. 분리 worktree에서 이 분기 첫 줄에 `return DISABLED`를 넣어 unregister를 막았다. 그 상태로 `service-worker-runtime`, `optional-runtime-host`, `runtime-adapters`, `runtime-capability-snapshot`, `service-worker-web-push-remediation` 5파일 82개 테스트를 돌렸더니 모두 통과했다. 테스트는 `disabledCleanup: false`만 쓴다(`tests/unit/service-worker-runtime.test.ts:95`, `:1423`, `tests/unit/optional-runtime-host.test.ts:14`). `REMOVE_REGISTRATION` 모드는 테스트가 있다(`service-worker-runtime.test.ts:380-460`). |
| 발생 조건 | 이 분기나 `resolveRuntimeCapabilities`의 `serviceWorkerDisabledCleanup` 계산이 회귀하는 경우. |
| 영향 | 설정만으로 SW를 끄는 유일한 경로가 깨져도 CI가 모른다. 장애 때 설정을 바꿔도 등록이 남는다. |
| 심각도·우선순위 | Medium · P2. 복구 수단의 회귀를 검출하지 못한다. 기본 구성(SW off)에는 영향이 없다. |
| 통제·증거 | 구현 M2 / 검출 M0 · E2(변이 실험) |
| 확실성과 남은 가정 | 변이 1개로 확인했다. e2e에도 이 경로는 없다. |
| 최소 개선 방향 | controller 단위 테스트 1개를 추가한다. `disabledCleanup: true`일 때 `register` 0회, `getRegistration` 1회, 소유 등록이면 `unregister` 1회이고 결과는 `DISABLED`여야 한다. 소유가 아니면 `unregister` 0회이고 `INCOMPATIBLE`이어야 한다. `resolveRuntimeCapabilities`가 `serviceWorkerDisabledCleanup: true`를 계산하는지도 한 줄로 단언한다. |
| 비용·부작용 | 테스트 30줄 안팎이다. |
| 완료 기준 | 위 변이를 넣으면 테스트가 실패한다. |
| 검증 방법 | 같은 변이를 다시 적용해 실패하는지 본다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 06-05 SW를 켜도 관측·차단기·업데이트 알림이 조립되지 않아 설치 실패와 활성화 결과가 보이지 않음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 7, 8, 18, 20, 19 |
| 근거 | `src/bootstrap/create-runtime-composition.ts:43-54`는 `observe`와 `blockers`를 넘기지 않는다. `optional-runtime-host.ts:148`의 `health()`는 repo 어디에서도 읽지 않는다. `onUpdateWaiting`·`onReloadRequired`·`requestActivation`을 쓰는 앱 코드가 없고, presentation에서 host에 접근할 방법도 없다. e2e 헬퍼는 이를 우회하려고 임시 복사본의 소스를 고친다(`tests/e2e/support/service-worker-builds.ts:31-35`, `:61-81`). 업데이트 설치가 실패하면 관측 이벤트도 남지 않는다(`watchForUpdates`는 installed만 알림, `service-worker-page-controller.ts:328-349`). SW를 켜는 방법은 `installed-runtime-capabilities.ts:28-29`의 한 줄("two-pass build")뿐이다. `docs/architecture/optional-adapter-recipes.md:94`는 "update/rollback UX가 없으면 설치하지 말 것"이라고 적었지만, 무엇을 붙여야 하는지(관측, blockers, 활성화 UI, reload 처리)는 없다. |
| 발생 조건 | 다운스트림이 SW 선택을 `ACTIVE`로 바꾼다. |
| 영향 | 첫 설치 실패(`INSTALL_FAILED`, 예: CDN이 content-type을 다르게 보냄)와 업데이트 설치 실패가 텔레메트리와 UI 어디에도 남지 않는다. blockers가 없어서, 다운스트림이 활성화 UI만 붙이면 편집 중인 탭도 drain에 동의한다. 기능 자체는 안전하게 실패한다. 활성화 요청이 없으면 모든 탭이 닫힐 때 교체된다. |
| 심각도·우선순위 | Medium · P2. 35.2의 "주요 진단 정보 부족"에 해당한다. 기본 구성에는 영향이 없다. |
| 통제·증거 | M1(계약에 hook이 있음) · E1 |
| 확실성과 남은 가정 | UI를 템플릿이 제공할지는 소유자 결정이다. 관측 연결의 부재는 코드로 확인했다. |
| 최소 개선 방향 | composition에서 `observe`를 텔레메트리 포트에 연결하고, `health()`를 기존 runtime capability snapshot에 싣는다. recipe 문서에 SW 켜기 체크리스트(관측, blockers, 활성화 UI, reload 처리)를 둔다. UI 자체는 다운스트림 몫으로 남겨도 된다. |
| 비용·부작용 | 연결 코드 수십 줄이다. 이벤트 이름과 수집 정책을 정해야 한다. |
| 완료 기준 | `ACTIVE`로 켠 구성에서 설치 실패가 텔레메트리 이벤트 1건으로 남는 테스트가 있다. |
| 검증 방법 | `createOptionalRuntimeHost` 단위 테스트에서 fake host의 설치 실패를 주입한다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.6-3의 hook 추가는 반영됨. 앱 쪽 조립은 이번에 새로 제기한다. |
### 06-06 로그아웃 없이 계정이 바뀌면 새 계정이 push fence를 넘길 방법이 없음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 15, 17, 11 |
| 근거 | fence `prepare`는 저장된 authority와 다르면 `STALE_AUTHORITY`로 실패한다(`push-association-fence-store.ts:205-214`). `enable`과 `reconcile`은 이 실패를 그대로 반환한다(`push-subscription-adapter.ts:232-237`, `:298-303`). fence를 넘기는 유일한 API인 `revoke`는 저장된 authority와 정확히 같은 `previousAuthority`를 요구한다(`:402-410`). 그런데 포트(`src/application/ports/out/web-push-control.ts:7-30`)에는 저장된 authority를 읽는 방법이 없다. 설계 문서(`realtime-events-web-push-and-bounded-polling.md:1292-1316`)는 정상 로그아웃 순서만 정의한다. 테스트도 정상 rotate만 다룬다. |
| 발생 조건 | Web Push를 조립한 구성에서, 세션 만료·쿠키 삭제·로그아웃 중 크래시 등으로 revoke 없이 계정이 A에서 B로 바뀐다. |
| 영향 | B의 enable과 reconcile이 계속 `STALE_AUTHORITY`로 실패하고, inspect는 `SESSION_AUTHORITY_CHANGED`를 반환한다. fence는 A의 ACTIVE로 남아서 워커가 A 연결의 push를 계속 표시한다. 이를 막는 것은 서버의 send-time 인가와 짧은 TTL뿐이다(설계 `:1300-1316`). 알림 문구는 계정 중립이고 클릭 뒤 조회는 B 세션으로 재인가되므로, 데이터 노출 경로는 찾지 못했다. |
| 심각도·우선순위 | Medium · P2. 막다른 상태가 되고 이전 계정의 알림이 계속 표시된다. 기능 조립이 전제다. |
| 통제·증거 | M1(정상 경로만 명시) · E1 |
| 확실성과 남은 가정 | 다운스트림 세션 소유자가 이전 authority를 따로 보관한다면 우회할 수 있다. 하지만 그 책임이 포트에도 문서에도 적혀 있지 않다. |
| 최소 개선 방향 | 포트에 저장된 authority와 무관하게 fence를 회전해 REVOKED로 만들고 captured association을 revoke하는 명시적 연산을 추가한다(예: `revokeForeign({ nextAuthority })`). 서버 TTL과 send-time 인가를 채택 완료 기준으로 문서에 둔다. |
| 비용·부작용 | 포트에 연산 1개가 추가된다(추가만, 파괴적 변경 없음). |
| 완료 기준 | A의 ACTIVE fence가 남은 상태에서 B가 한 번의 호출로 fence REVOKED, 연결 revoke, 새 opt-in 가능 상태가 되는 테스트가 있다. |
| 검증 방법 | `web-push-subscription-adapter.test.ts`에 A→B 비정상 전환 사례를 추가한다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 06-07 응답하지 않는 창 하나가 활성화를 막고, 그 시간 초과가 "dirty 탭"으로 보고됨
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(실패 분류) + 구조적 위험(활성화 가용성) |
| 관련 관점 | 12, 6, 24, 18 |
| 근거 | 워커는 `includeUncontrolled: true`로 scope 안의 모든 창을 drain 대상으로 잡는다(`service-worker-lifecycle.ts:341-348`). 응답은 page controller의 message listener만 보낸다(`service-worker-page-controller.ts:267-291`). 응답하지 않는 창은 네 종류다. 앱이 아닌 문서(예: `/config.json`을 연 탭), `start()`가 register를 기다리는 중인 탭(`registration`이 null이라 source 검사 실패, `:277-279`, `:310-320`), stop된 탭, 브라우저가 얼린 백그라운드 탭이다. 워커의 30초 시간 초과(`lifecycle.ts:403-407`)와 `skipWaiting()` 실패(`:357-362`)는 모두 `ACTIVATE_REJECTED`로 통지된다(`:350`, `:360`). 요청 탭은 이를 `BLOCKED_DIRTY_CLIENT`로 바꾼다(`page-controller.ts:441-452`). 페이지 자신의 `CLIENT_DRAIN_TIMEOUT`(`:457-460`)은 워커가 35초 동안 아무 답도 없을 때만 나오므로, 워커가 살아 있으면 도달하지 않는다. |
| 발생 조건 | 다운스트림이 활성화 UI를 붙였고, 위 네 종류의 창 중 하나라도 열려 있다. |
| 영향 | 사용자는 "저장하지 않은 변경이 있는 탭"이라는 잘못된 이유를 보고, 그런 탭을 찾지 못한다. 교체는 모든 탭이 닫힐 때로 미뤄진다(안전한 쪽으로 실패). |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | 얼린 탭의 메시지 보류는 브라우저 동작이다. 실제 브라우저 재현은 하지 않았다. |
| 최소 개선 방향 | 워커가 거절 이유(명시 거절 / 시간 초과 / commit 실패)를 구분해 보내고, 페이지는 이를 `CLIENT_DRAIN_TIMEOUT`·`FAILED`로 매핑한다. 워커 교체의 영향을 받지 않는 제어 밖 창을 drain 대상에서 뺄지 검토한다. |
| 비용·부작용 | 프로토콜 메시지에 필드나 kind가 1개 추가된다(V1 호환 확인 필요, SW-10과 연결). |
| 완료 기준 | 응답 없는 창 1개가 있는 seam 테스트에서 결과가 `CLIENT_DRAIN_TIMEOUT`이다. |
| 검증 방법 | `tests/unit/service-worker-runtime.test.ts`의 `activationSeam`에 listener 없는 client를 추가한다. |
| 담당·기한·상태 | 미정 · 미정 · 일부 미해결 |
| 직전 리뷰 | 6.6-2 시나리오 중 "얼린 백그라운드 탭" 부분이 미해결이다(R-6.2는 빌드 필터만 고침). 6.6-10b의 여유분 추가로 페이지 시간 초과가 사실상 도달 불가가 됐다. |
### 06-08 해시 파일명 판별이 same-origin API·다운로드 GET까지 가로챔
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(주석과 동작 불일치) |
| 관련 관점 | 5, 14, 24 |
| 근거 | `HASHED_STATIC_ASSET_NAME = /-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/`(`src/contracts/service-worker.ts:110`)을 same-origin 경로 전체에 적용한다(`service-worker-static-assets.ts:54-56`, `:60-70`). node로 `classifyFetch`를 실행했더니 `/api/v1/user-profiles.json`, `/api/reports/monthly-summary2026.csv`, `/media/onboarding-video-final.mp4`, `/downloads/release-notes-20260925.pdf`가 모두 `PREVIOUS_RELEASE_FALLBACK`으로 분류됐다. 반면 주석은 "API calls … left to the browser untouched"라고 적었다(`service-worker-entry.ts:102-105`, `service-worker-lifecycle.ts:263-268`). |
| 발생 조건 | SW `ACTIVE` + same-origin API/BFF 또는 다운로드 경로에 `-영숫자8자 이상.확장자` 형태 이름이 있다. |
| 영향 | 이런 GET마다 워커 기동, `caches.keys()`, 이전 캐시 marker 읽기(`lifecycle.ts:232-235`, `:200-219`)를 거친 뒤 `fetch(request)`로 다시 보낸다. 이전 캐시에는 검증된 자산만 있어서 잘못된 응답이 나갈 경로는 없다. 지연이 늘고, "SW는 API를 건드리지 않는다"는 가정이 깨진다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E2(node 실행) |
| 확실성과 남은 가정 | 지연 크기는 측정하지 않았다. |
| 최소 개선 방향 | fallback을 빌드 자산 디렉터리(`/assets/`) 아래로 한정한다. 또는 이전 캐시에 실제로 있는 URL만 가로챈다. |
| 비용·부작용 | 조건 1개 추가다. base path 배포를 고려해야 한다. |
| 완료 기준 | 위 URL 4개가 `NETWORK_PASSTHROUGH`로 분류되는 단위 테스트가 있다. |
| 검증 방법 | `classifyFetch` 표 테스트를 추가한다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | Q-6.6-6b 결정("해시 파일명")의 구현 범위 문제. 새 항목이다. |
### 06-09 거절된 알림 클릭의 fallback이 router base path를 무시하고 origin 루트를 엶
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 15, 3 |
| 근거 | `inbound/notification-click-adapter.ts:269`가 `${origin}/`을 연다. SW scope와 앱은 `routerBasePath`에 있다(`service-worker-page-controller.ts:54-57`, `service-worker-removal.ts:65-76`). 설계 문서도 `<origin>/`로 적었다. |
| 발생 조건 | base path 배포(예: `/app/`)에서 만료되거나 fence가 맞지 않는 클릭이 들어온다. 06-01이 고쳐진 뒤에만 도달한다. |
| 영향 | 앱 밖 페이지(다른 앱이나 404)가 열린다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | 정적 확인이다. |
| 최소 개선 방향 | click adapter에 앱 루트 URL을 주입한다(워커에서는 `registration.scope`를 쓸 수 있다). |
| 비용·부작용 | 의존성 1개 추가 |
| 완료 기준 | base path가 `/app/`일 때 거절된 클릭이 `/app/`을 여는 테스트가 있다. |
| 검증 방법 | `web-push-worker-runtime.test.ts` "a rejected click opens the app root"에 사례를 추가한다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.6-11 수정의 부수 문제 |
### 06-10 SW 빌드가 배포 프로필이 아니라 로컬 `public/config.json`에서 release manifest URL을 읽음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(설정 출처 불일치) |
| 관련 관점 | 19, 9 |
| 근거 | `vite.service-worker.config.ts:51-53`이 `public/config.json`을 읽는다. 반면 배포용 설정은 `scripts/build-frontend.ts:55-56` → `scripts/generate-runtime-config.ts:26`이 만드는 `dist/config.json`이다. 지금은 4개 프로필의 `RELEASE_MANIFEST_URL`이 같고(`config/runtime/*.json`) 덮어쓰기 대상도 아니라서(`generate-runtime-config.ts:32-35`) 결과가 같다. 또 `build-frontend.ts:25-28` 주석은 "Service Worker hashes the emitted config.json"이라고 적었지만, generator는 `config.json`을 제외한다(`scripts/generate-service-worker-assets.ts:33-39`). |
| 발생 조건 | 어떤 프로필이 다른 `RELEASE_MANIFEST_URL`을 쓰기 시작한다. |
| 영향 | 워커의 NETWORK_ONLY 판정 대상이 어긋난다. 다만 해시 이름이 아니면 어차피 가로채지 않아 실제 차이는 작다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E1 |
| 확실성과 남은 가정 | 현재 영향은 없다. |
| 최소 개선 방향 | `dist/config.json`을 읽거나, `resolveServiceWorkerBuildInput`에서 두 값이 일치하는지 검사한다. 주석도 고친다. |
| 비용·부작용 | 수 줄 |
| 완료 기준 | 프로필과 `public/config.json`의 값이 다르면 빌드가 실패하거나 프로필 값을 쓴다. |
| 검증 방법 | `tests/unit/service-worker-build-input.test.ts`에 사례를 추가한다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1·E2 | 부분 충족: 메시지·payload·manifest 검증은 exact. 클릭 facade가 실제 이벤트를 거부함(06-01) |
| 2 | 구조적 성숙도 | 적용: worker/page realm 분리 | M3 / M3 | E1 | 충족: `tsconfig.service-worker.json`이 page realm 파일을 제외하고, entry는 web-push를 import하지 않음(`service-worker-entry.ts:144-158`). 전체 의존성 게이트는 영역 01 |
| 3 | 변경 용이성 | 적용: WEB_PUSH 조립 | M1 / M1 | E1 | 부분 충족: 조립 절차가 entry 주석에만 있고 build-input이 거부함. base path 누락(06-09) |
| 4 | 인지 부하 | 적용 | 해당 없음 | E1 | 부분 충족: 계약 주석은 충실. 활성화 규약이 page·worker 두 파일(630·724줄)에 나뉘고 subscription adapter가 1115줄 |
| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | 부분 충족: 결과 타입은 명확. "API는 건드리지 않음"(06-08), 없는 kill switch 문서(06-03) |
| 6 | 실패 성숙도 | 적용: 구독 실패·권한 거부 구분 | M2 / M2 | E1·E2 | 부분 충족: 권한 거부·dismiss·미지원·등록 비활성을 구분하고, 설치 실패 코드는 11종. 활성화 시간 초과가 dirty로 보고됨(06-07). register 재시도마다 새 멱등 키를 씀(`push-subscription-adapter.ts:680`), 서버 upsert가 전제 |
| 7 | 운영 성숙도 | 적용 | M2 / M1 | E1 | 미충족: observe·health 미연결(06-05) |
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1 | 부분 충족: 관측 hook과 reason 코드는 풍부하지만 조립되지 않음(06-05) |
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | 부분 충족: 운영 문서가 현재 코드와 다름(06-03). `void SERVICE_WORKER_BOUNDS.retainedPreviousCaches`(`service-worker-lifecycle.ts:167`)는 여전히 아무 일도 하지 않음. 빌드 주석 불일치(06-10) |
| 10 | 테스트 성숙도 | 적용 | M3 / M3(부분) | E2(126 pass) | 부분 충족: 경계·경합 단위 테스트가 많음. fake가 WebIDL 형태와 달라 06-01을 못 잡음, kill switch 변이 생존(06-04), 탭 간 push 경합 없음(06-02), e2e는 단일 탭 업데이트·fallback만 다룸 |
| 11 | 데이터 성숙도 | 적용: SW 캐시 사용자 범위·삭제 | M2 / M2 | E1 | 충족: 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담고, 현재+이전 1개를 보존하며, PURGE는 소유 캐시만 지움. push fence에는 계정 ID와 endpoint가 없음(`contracts/web-push.ts:45-57`). 로그아웃 뒤 OS 알림 잔존은 문서화됨 |
| 12 | 동시성 성숙도 | 적용: 여러 탭·SW 메시지 | M2 / M2 | E2 | 미충족: push 탭 간 경합(06-02). SW 활성화는 single-flight·nonce·source 검증으로 양호, 응답 없는 창 문제 있음(06-07) |
| 13 | 확장성 | 적용: 자산 수 증가 | M2 / M2 | E1 | 부분 충족: 256개·5 MiB 상한을 넘으면 빌드에서 거부(`generate-service-worker-assets.ts:60-86`). 기능 증가 시 도달 시점은 미측정 |
| 14 | 성능 성숙도 | 적용 | M2 / M2 | E1·E2 | 부분 충족: fetch 리스너는 조건부로 등록되고 해시 GET만 가로챔. 과대 가로채기(06-08), miss마다 marker를 읽음 |
| 15 | 보안 성숙도 | 적용: payload 신뢰, 구독-사용자 연결, 해지, 클릭 URL | M2 / M2 | E1·E2 | 부분 충족: payload, 클릭 URL, 로그아웃 순서, R-6.7은 양호. 비정상 계정 전환 시 막다른 상태(06-06) |
| 16 | 의존성 성숙도 | 적용 제외: 이 영역에 런타임 외부 패키지가 없음(빌드 도구는 영역 외) | 해당 없음 | 해당 없음 | 적용 제외 |
| 17 | API / Contract | 적용: SW 메시지 V1, push 포트 | M2 / M2 | E1 | 부분 충족: exact key와 버전 불일치 시 fail-closed. V2 이행은 SW-10으로 미룸(`adapter-remediation-ledger.md:151`). push 포트에 저장 authority 조회가 없음(06-06) |
| 18 | 배포 성숙도 | 적용: 32절 추적(2.1절) | M2 / M2 | E1(e2e 미실행) | 부분 충족: 옛 청크는 현재 캐시→이전 캐시→네트워크 순서로 찾음. 활성화·reload UI 미조립(06-05), 응답 없는 창(06-07) |
| 19 | 설정 성숙도 | 적용: SW 관련 설정 검증 | M3 / M3 | E2 | 부분 충족: build-input이 모르는 handler·중복·WEB_PUSH·stale identity를 빌드에서 거부(`service-worker-build-input.ts:36-80`). 설정 출처 불일치(06-10), `service-worker.js` Cache-Control 미검사(06-03) |
| 20 | 개발자 경험 | 적용: SW 켜기 | M1 / M1 | E1 | 부분 충족: `ACTIVE`로 바꾸는 한 줄 외에 조립 안내가 없음(06-05) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E1·E2 | 부분 충족: build-input 거부, hosting-probe의 worker 파일 검사, tsconfig realm 분리는 동작. kill switch 회귀는 검출하지 못함(06-04) |
| 22 | 추상화 성숙도 | 적용: structural facade | M2 / M2 | E1·E2 | 부분 충족: facade 덕분에 테스트할 수 있지만, 실제 WebIDL과의 차이를 가림(06-01) |
| 23 | 일관성 | 적용 | 해당 없음 | E1 | 부분 충족: `validateActiveFence` 두 벌(`push-event-adapter.ts:196-214`, `notification-click-adapter.ts:343-367`), abort race helper 두 벌(`service-worker-static-assets.ts:365-380`, `notification-click-adapter.ts:66-81`). 현재 동작 차이는 없음 |
| 24 | 네이밍 / 의미 | 적용 | 해당 없음 | E1 | 부분 충족: `CLIENT_DRAINED`는 "지금 차단기가 없음"만 뜻하고 입장을 닫지 않음. `BLOCKED_DIRTY_CLIENT`에 시간 초과가 섞임(06-07) |
| 25 | 조직 확장성 | 적용 제외: 0.1 전제(1인 관리), 구조적 준비는 다른 영역 | 해당 없음 | 해당 없음 | 적용 제외 |
| 26 | Ownership | 적용: SW 장애 대응 | M1 / M1 | E0 | 미검증: quarantine owner(`frontend-platform`) 표기는 있으나 SW 장애 대응 절차가 코드와 맞지 않음(06-03) |
| 27 | 삭제 가능성 | 적용 | M3 / M3 | E1·E2 | 부분 충족: 단계적 제거 모드를 구현하고 테스트함. web-push는 entry import가 없어 파일 삭제로 제거 가능하다고 주장함. 삭제 스크립트는 미실행 |
| 28 | 회복 가능성 | 적용: kill switch·unregister·롤백 | 페이지 M2 / 워커 M0 | E1·E2 | 미충족: 워커 쪽 비상 경로 없음, 문서 불일치(06-03), 런타임 kill switch 검증 없음(06-04) |
## 6. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| e2e `tests/e2e/service-worker-update.spec.ts` | 지시서상 vitest만 실행 가능. 두 빌드 업데이트와 이전 캐시 fallback의 브라우저 증거를 이번에 새로 얻지 않음 | 오케스트레이터 게이트나 CI에서 Playwright 실행 |
| 여러 탭 활성화(다른 빌드, 얼린 탭, 앱이 아닌 창) | 실제 브라우저 필요(06-07) | e2e 헬퍼로 두 번째 page를 열고, 하나는 `/config.json`에 둔 채 `requestActivation()` |
| 롤백 N+1 → N 재설치와 활성화, `REMOVE_REGISTRATION` 뒤 404 update 시 등록 유지 | 여러 릴리스 호스팅 필요(06-03) | e2e 서버에서 dist-b → dist-a 순서로 서빙하고, worker 파일 없는 dist도 서빙 |
| Web Push end-to-end(실제 푸시 서비스, VAPID, 클릭) | 푸시 서버 없음. 06-01은 속성 확인과 단위 재현, 06-02는 fake 단위 재현까지만 함 | 로컬 web-push 서버와 Chromium으로 push → 클릭 |
| web-push 삭제 가능성 | `scripts/test-realtime-runtime-removal.ts` 미실행 | 스크립트를 읽고 격리 환경에서 실행 |
| `check:types`(service-worker 프로젝트), `check:architecture` | 전체 게이트는 오케스트레이터 담당 | 게이트 결과 참조 |
| 자산 상한(256개·5 MiB) 도달 시점 | 기능 수 증가 실험 없음 | extreme-scale fixture 빌드에서 `service worker assets:` 출력 확인 |
@@ -0,0 +1,292 @@
# contracts (공유 어휘·외부 계약) 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/contracts/` 40파일 약 8.7k줄, `schemas/`, `config/contracts/` 4파일, `config/compatibility/fixtures.json`, `docs/contracts/compatibility.md`, 이 영역을 검증하는 테스트(`tests/unit` 계약·매퍼·경계 관련, `tests/runtime-schema`, `tests/contract`, `tests/fixtures/typecheck`의 계약 관련 negative fixture)
> 영역 판정(35.8): **조건부 사용 가능** — 외부 입력 검증과 레지스트리 조립은 그대로 써도 된다. 다만 (1) 오류 종류의 화면 문구 연결, (2) "필드 추가는 안전"이라는 호환성 규칙과 FE-GATE-014, (3) 참조 기능의 V2/V3 이중 선언은 다운스트림이 믿고 복제하면 안 된다. 사용 조건은 1절 참조.
## 1. 결론
- **외부 입력 경계는 막혀 있다.** 런타임 설정·릴리스 매니페스트·realtime envelope·HTTP 응답은 zod 또는 exact decode로 검증하고, 실패하면 fail-closed(모르면 거부)로 끝난다. 직전 리뷰 6.7-1~6.7-12는 모두 반영됐다. 그중 6건(6.7-1·2·3·4·5·10)은 코드를 되돌리는 변이 실험에서 테스트가 실패하는 것까지 확인했다.
- **고쳐야 할 것 1 — 오류 문구가 비어 있다 (07-01).** `ERROR_REGISTRY` 38종 중 22종은 문구 카탈로그에 키가 없다. 조회 실패 화면에 "요청한 문구를 표시할 수 없습니다."가 나온다. 해당 종류는 `SCHEMA_MISMATCH`, `CONFLICT`, `VALIDATION_REJECTED` 등이다. 이 연결을 검사하는 테스트·타입·거버넌스가 없다.
- **고쳐야 할 것 2 — 호환성 규칙이 실제 파서 동작과 다르다 (07-02).** 문서와 분류기는 선택 필드 추가를 "additive(안전)"로 본다. 그런데 설정 V2, HTTP V2 envelope, realtime envelope는 모르는 키를 거부한다. 타입·enum·nullable 변경은 분류기가 `"none"`으로 답한다. CI의 `config-compatibility` 게이트(FE-GATE-014)는 손으로 쓴 fixture 8개로 분류기 자체만 검사하고, 실제 스키마는 보지 않는다.
- **고쳐야 할 것 3 — 같은 HTTP 오퍼레이션이 두 벌이다 (07-03).** 참조 기능은 오퍼레이션 3개를 V2 행과 V3 descriptor로 각각 선언한다. 계약 거버넌스(FE-REG-API)는 실행되지 않는 V2 벌만 감시한다. V3의 path·응답 상한을 바꿔도 `check-registries`는 PASS다.
- **나머지는 Low다.** 연결되지 않은 레지스트리 필드(07-04), 위반 3개 중 1개만 고정하는 negative fixture(07-05), `invokeValidator`의 "절대 throw하지 않음" 약속의 구멍(07-06), 폐기 표시 부재(07-07).
- **미검증:** 실제 브라우저에서 구버전 탭과 신버전 서버·설정이 공존하는 시나리오는 실행하지 않았다. 파서 단위 실행으로만 확인했다. browser-rpc의 미등록 gRPC 코드가 command의 효과 확실성(effect certainty)에 주는 영향은 영역 03 범위다.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template` `main` `4626b73`. 워킹트리는 리뷰 문서만 미커밋이다 |
| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA와 정적 호스팅, 여러 탭 동시 실행을 지원한다. SSR은 없다 |
| 읽은 코드 | `src/contracts/` 전부. 핵심 파일(`errors.ts`, `external-contract-runtime.ts`, `compatibility.ts`, `schema-registry.ts`, `boundary-mapper.ts`, `api-operations.ts`, `rest-profiles.ts`, `release-artifacts.ts`, `contract-set.ts`, `release-tokens.ts`, `realtime-events.ts`, `realtime-streams.ts`, `telemetry.ts`, `diagnostics.ts`, `mutation-intent.ts`, `env.ts`, `exact-snapshot.ts`, `read-only-registry.ts`, `storage-keys.ts`, `offline-command.ts`)는 줄 단위로 읽었다. 나머지는 export 목록과 경계 처리만 읽었다. 추적을 위해 영역 밖 소비자도 일부 읽었다: `adapters/http/client.ts`, `adapters/http/schema-registry.ts`, `adapters/http/feature-http-binding.ts`, `adapters/realtime/event-codec.ts`, `adapters/browser-rpc/browser-rpc-runtime.ts`, `presentation/i18n/*`, `presentation/components/async-surface.tsx`, 참조 기능 계약, `scripts/check-registries.ts`, `scripts/lib/registry-compatibility.ts`, `scripts/check-compatibility.ts`, `scripts/lib/ci-step-result.ts`, `config/ci/gates.json` |
| 실행한 테스트 | `node scripts/run-vitest.ts run` 로 계약 관련 20파일 실행 → **244/244 통과**. 여기에 `tests/runtime-schema` 전체가 포함된다. `tests/contract`와 참조 기능 계약 테스트 7파일 → **33/33 통과**. negative fixture 8개(`failure-kind`, `result-narrowing`, `http-operation-id`, `http-wire-mapper`, `diagnostics-port`, `reference-operation`, `http-route-id`, `http-operation-input`)를 `tsc -p`로 실행했고, 모두 의도한 줄에서 의도한 오류 코드가 났다 |
| 실험 | scratchpad의 분리 worktree(`git worktree add --detach`)에서 변이 16건을 넣고 관련 테스트를 돌렸다(아래 표). 실험 후 worktree는 제거했다. repo 원본에서는 노드 스크립트로 파서·분류기·문구 해석을 직접 호출했다 |
| 확인하지 못한 범위 | 전체 게이트(`check:types`, `check:architecture`, `test:unit` 전체)는 오케스트레이터 몫이라 실행하지 않았다. `browser-rpc.ts`(947줄) 내부 검증식, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `runtime-capabilities.ts`, `product-features.ts`는 줄 단위로 읽지 않았다. 실제 브라우저·서버 공존 실험은 하지 않았다 |
| 직전 리뷰와 비교 | 6.7-1~12를 현재 코드에서 다시 확인했다. 6.7-8(검증기 프로토콜·`MappingResult` 두 모양)은 소유자 결정 D-15에 따라 별칭으로 남아 있고, 이 리뷰에서 결함으로 다시 세지 않았다(관점 23에만 기록) |
### 2.1 변이 실험 결과 (관점 10·21)
"변이 실험"은 규칙 하나를 일부러 망가뜨린 뒤 테스트가 실패하는지 보는 방법이다. 실패하면 테스트가 그 규칙을 지키고 있다는 뜻이다(killed). 통과하면 그 규칙은 테스트가 지키지 않는다는 뜻이다(survived).
| ID | 망가뜨린 규칙 | 결과 |
|---|---|---|
| M1 | `createFailure`: `effect: MAYBE_APPLIED`면 `retryable=false` (`errors.ts:292-296`) | **survived** (19파일 279건 통과). 07-04 참조 |
| M1b | `withFailureEffect`: MAYBE_APPLIED면 `retryable=false` | killed (4건 실패) |
| M3 | 멱등 키 문법을 수정 전으로 되돌림 (6.7-1) | killed |
| M4 | 매니페스트 URL의 origin·pathname 재확인 제거 (6.7-3) | killed (4건) |
| M6 | exact decode의 non-enumerable 거부 제거 | killed (3건) |
| M7 | 검증 이슈 상한 50 → 5000 | killed |
| M8 | `FEATURE_OVERRIDES` 키 금지어 면제 제거 (6.7-2) | killed |
| M9 | REST V2 COMMAND+GET 거부 제거 (6.7-4) | killed (4건) |
| M10 | `isVersionCompatible`의 minor 비교 제거(항상 호환) | **survived** (10파일 77건 통과). 런타임 minor가 더 낮은 경우를 검사하는 테스트가 없다 |
| M11 | 텔레메트리 `operation_id`를 대문자 전용 문법으로 되돌림 (6.7-5) | killed (3건) |
| M12 | realtime 타임스탬프의 달력 검사 제거 | killed (2건) |
| M13 | V3 조립의 "retryBudget>0 + NEVER" 모순 거부 제거 | survived. 실행기가 `http-retry-lifecycle.ts:25`에서 NEVER를 다시 막으므로 실제 영향은 작다 |
| M14 | contract-set 패키지별 digest 비교 제거 | survived. 뒤이은 집합 digest 비교가 같은 불일치를 잡으므로 동작이 같다(equivalent mutation) |
| M16 | `kindForStatus` 409 → CONFLICT 제거 | killed (2건) |
| M18 | 스키마 레지스트리 이슈 상한 투영 제거 | killed |
| M19 | 배포 승인에서 `.internal` 호스트 거부 제거 (6.7-10) | killed |
결과: 16건 중 12건 killed. survived 4건 중 의미가 있는 것은 M1과 M10이다. M13은 실행기에 이중 방어가 있고, M14는 동작이 같은 변이다.
### 2.2 직접 호출로 확인한 동작
```text
config as-is PASS
config + NEW_OPTIONAL_KEY REJECT unrecognized_keys
config CONFIG_SCHEMA_VERSION "2.1" REJECT invalid_union
config CAPABILITY_OVERRIDES { NEW_CAP } REJECT unrecognized_keys
isVersionCompatible("2.0", "2.1") true
classify(선택 필드 추가) additive
classify(id: string → number) none
classify(enum [A,B] → [A]) none
classify(string → string|null) none
HTTP V2 envelope + links success=false
HTTP V2 failure envelope + error.target success=false
resolveMessage(ko, error.schema_mismatch) 요청한 문구를 표시할 수 없습니다.
invokeValidator(issues: 5) TypeError 발생
invokeValidator(success: "no") VALID
```
### 2.3 변경 시나리오 추적: 오류 코드 하나 추가 (관점 3)
**A. 서버가 새 오류 코드를 보낸다 (프론트 코드는 그대로).** 예: 403 응답에 `error.code: "QUOTA_EXHAUSTED"`.
```text
서버 응답
→ HTTP V2: envelope 검증(strict) → kind = kindForStatus(403) = FORBIDDEN, code는 정규식을 통과하면 보존
(client.ts:995-1016). envelope의 error 객체에 모르는 필드가 하나라도 있으면
envelope 검증 실패 → code = "HTTP_FAILURE"로 대체
→ HTTP V3: 401/403/429는 PROBLEM 매핑 전에 고정 분류(feature-http-binding.ts:341-356) → 서버 code 버림
그 밖의 상태는 기능의 mapProblem 결과, 없으면 kindForStatus + code "CONTRACT_PROBLEM"
→ browser-rpc: transport 오류 코드 어휘가 닫혀 있음(browser-rpc.ts:76-93). 등록되지 않은 코드는
프로토콜 위반 → API_CONTRACT_MISMATCH("API 계약 버전이 현재 화면과 일치하지 않습니다")
→ 화면: kind 단위 문구만 있음. code는 표시하지 않음
→ 관측: telemetry·diagnostics에는 error_kind만 남음. 서버 code는 남지 않음(telemetry.ts:4-21)
```
구버전 소비자는 새 코드를 "견딘다". 기존 kind로 안전하게 떨어진다. 대신 의미가 뭉개지고, 관측으로도 새 코드가 늘었는지 알 수 없다. RPC만 예외다. VD-27 설계표에 있는 `UNKNOWN`, `OUT_OF_RANGE`도 어휘에 없어서 계약 위반으로 분류된다.
**B. 그 코드를 별도 문구·행동으로 보여 준다 (새 FailureKind 추가).**
| # | 파일 | 바꾸는 정책 | 빠뜨리면 검출? |
|---|---|---|---|
| 1 | `src/contracts/errors.ts` ERROR_REGISTRY 행 | 기본 재시도 여부, action, severity, telemetryEvent (4개. 뒤 2개는 소비자 없음, 07-04) | kind 오타는 타입이 잡음 |
| 2 | `src/presentation/i18n/catalog.ts` ko-KR·en-US | 화면 문구 2개 | **검출 안 됨** — 대체 문구가 나감 (07-01) |
| 3 | 매핑 1곳: V3는 기능의 `mapProblem`, V2는 hook이 없어 `src/adapters/http/client.ts`, RPC는 `browser-rpc-runtime.ts:1543` | 서버 code → kind 매핑 | 검출 안 됨 |
| 4 | `tests/unit/error-classification.test.ts:14` | 고정 개수 38 | 테스트 실패로 드러남 |
| - | 레지스트리 거버넌스 | 행 추가 = additive, 증거 불필요 | 해당 없음 |
| - | 텔레메트리 | `error_kind` 정규식이 새 값 자동 허용 | 해당 없음 |
합계: 코드 3~4파일, 정책 4~5개, 함께 배포할 단위 1개. `FailureKind`를 망라하는 `Record`가 없어서 컴파일러가 빠진 곳을 알려 주지 않는다. 기능 전용 오류라도 플랫폼 공용 `ERROR_REGISTRY`와 공용 카탈로그를 고쳐야 한다. 그래서 기능 팀 사이의 공동 변경 지점이 된다(관점 25).
## 3. 확인된 강점
1. **설정·매니페스트를 엄격하게 거부한다.** 모르는 키는 `.strict()`가 막는다. HTTPS, 자격 증명 없는 URL, demo 인증은 local에서만 허용하는 규칙, 같은 origin 경로 조건을 한 곳에서 강제한다(`src/contracts/release-artifacts.ts:91-171`). 비밀처럼 보이는 설정 이름은 거부한다(`src/contracts/env.ts:73-110`). M4·M8 변이를 테스트가 잡았다.
2. **조립 시점 입력은 한 번만 읽고 스냅샷한다.** exact decode가 `exact-snapshot.ts:74-123` 하나로 모였다. accessor, non-enumerable, 커스텀 prototype, symbol 키를 거부한다. `external-contract-runtime.ts:579-626`, `rest-profiles.ts:118-204`, `realtime-streams.ts:540`, `browser-rpc.ts:388-414`가 이 구현을 쓴다. M6 변이를 테스트가 잡았다.
3. **결과를 모르는 쓰기를 재시도 대상에서 뺀다.** `MAYBE_APPLIED`면 `retryable=false`, `action=contact-support`가 된다(`errors.ts:282-341`). `withFailureEffect` 쪽은 테스트가 고정한다(M1b killed).
4. **모르는 값을 안전하게 처리하는 곳이 여러 군데 있다.**
- 응답 DTO는 모르는 필드를 버린다(`.strip()`, `features/reference-feature/contracts/reference-schemas.ts:29-48`).
- 모르는 검증 코드는 일반 문구로 바뀐다(`presentation/forms/form-contracts.ts:42-50`).
- 저장소에 모르는 값이 있으면 거부한다. 저장소 키에는 버전이 붙어 있다(`storage-keys.ts:128-201`).
- 모르는 기능 ID의 override는 무시한다(`release-artifacts.ts:65-80`).
- 모르는 오프라인 상태에서는 어떤 전이도 허용하지 않는다(`offline-command.ts:100-107`).
5. **레지스트리의 깨지는 변경에는 증거를 요구한다.** `scripts/lib/registry-compatibility.ts:303-336`이 breaking 변경마다 versionBump, migration, compatibilityWindow, rollback, owner가 비어 있지 않은지 검사한다. 실제 증거 파일은 `config/contracts/registry-change-evidence.json`이다.
6. **realtime 시퀀스·시각을 엄격하게 검사한다.** 시퀀스는 BigInt로 uint64 상한을 확인한다. 타임스탬프는 윤년·말일까지 확인한다(`realtime-events.ts:120-184`). M12 변이를 테스트가 잡았다. 직접 호출에서도 `2026-02-29`가 거부됐다.
## 4. 발견 사항 (36.3)
### 07-01 오류 종류 22개에 화면 문구가 없어 "요청한 문구를 표시할 수 없습니다"가 표시된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 8, 17, 20, 21, 23 |
| 근거 | `src/contracts/errors.ts:52`가 키를 `error.${kind.toLowerCase()}`로 만든다. 카탈로그(`src/presentation/i18n/catalog.ts:130-145` ko, `:288-303` en)에는 그중 16개만 있다. 직접 호출 결과 22종의 키가 ko·en 모두에 없다: REQUEST_ABORTED, CONTENT_TYPE_MISMATCH, MALFORMED_JSON, RESPONSE_BODY_LIMIT, ENVELOPE_MISMATCH, SCHEMA_MISMATCH, MAPPING_CONTRACT_VIOLATION, RESULT_LIMIT_EXCEEDED, SCOPE_GENERATION_CHANGED, IDENTITY_INTERN_LIMIT_EXCEEDED, DUPLICATE_IN_FLIGHT, PAGINATION_CONTRACT_VIOLATION, CONFLICT, VALIDATION_REJECTED, UNKNOWN_CLIENT_FAILURE, BOOT_CONFIG_FAILURE, RELEASE_MANIFEST_FAILURE, DEPLOY_MISMATCH, STORAGE_UNAVAILABLE, STORAGE_QUOTA_EXCEEDED, TELEMETRY_FAILURE, QUERY_CACHE_FAILURE. `resolveMessage`는 없는 키를 `common.unavailable`로 대체한다(`presentation/i18n/message-contract.ts:75-79`). 데이터 없이 실패한 조회는 `terminal-error`가 되어(`application/view-models/async-state.ts:90-94`) 이 문구를 그대로 제목으로 보여 준다(`presentation/components/async-surface.tsx:83`). 막는 장치도 없다. `ErrorDefinition.userMessageKey`는 `string`이다(`errors.ts:35`). `errorMessage(messageKey: string)`도 타입 키를 요구하지 않는다(`components/error-copy.ts:3`). `check-i18n`은 로케일끼리 키가 같은지만 본다(`scripts/check-i18n.ts:32-52`). FE-REG-ERROR의 `references`는 비어 있다(`config/contracts/registry-governance.json:339` 항목) |
| 발생 조건 | 조회가 데이터 없이 실패하고 kind가 위 22종 중 하나일 때. 예: 서버 DTO 변경으로 `SCHEMA_MISMATCH`, 409 `CONFLICT`, 422 `VALIDATION_REJECTED`, 그 밖의 4xx `UNKNOWN_CLIENT_FAILURE` |
| 영향 | 사용자는 "요청한 문구를 표시할 수 없습니다" + "지원 정보 확인" 버튼을 본다. 무엇이 잘못됐는지 알 수 없고, 문구 자체가 번역 누락처럼 보인다. 새 kind를 추가하는 다운스트림도 같은 방식으로 문구를 빠뜨리고, 아무 검사도 실패하지 않는다 |
| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 하지만 흔한 실패(계약 불일치·충돌·검증 거부)의 사용자 안내가 틀리고, 샘플과 기본값으로 복제된다 |
| 통제·증거 | M0(연결 검사 부재 확인) · E2(직접 호출 실행) |
| 확실성과 남은 가정 | 누락 22종은 확인했다. 부팅 계열(BOOT_CONFIG_FAILURE 등)이 별도 부트 화면을 쓰는지는 확인하지 않았다. 그래도 조회 경로의 누락만으로 결함은 성립한다 |
| 최소 개선 방향 | (1) 누락 22개 키를 ko·en에 추가한다. 비슷한 종류는 같은 문구를 써도 된다. (2) `tests/unit`에 테스트 하나를 둔다: 모든 `ERROR_REGISTRY` 행의 `userMessageKey`가 `KO_MESSAGES`와 `EN_MESSAGES`에 있는지. 테스트는 계층 규칙과 무관하게 양쪽을 import할 수 있다 |
| 비용·부작용 | 문구 22쌍과 테스트 1개. 동작 변경은 없다 |
| 완료 기준 | 38종 모두 전용 문구로 해석된다. 키 하나를 지우면 테스트가 실패한다 |
| 검증 방법 | 새 테스트 실행. 카탈로그에서 키 하나를 지운 변이로 테스트 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 07-02 호환성 규칙·분류기·FE-GATE-014가 "필드 추가는 안전"이라 하지만 실제 reader 여러 곳이 모르는 필드를 거부한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 24, 21, 10, 18, 19 |
| 근거 | **규칙:** `docs/contracts/compatibility.md:6`은 "additive changes preserve current required fields"라고만 적는다. 이 규칙은 reader가 모르는 필드를 거부하는 경계를 구분하지 않는다. **분류기:** `classifyObjectSchemaChange`(`src/contracts/compatibility.ts:236-254`)는 속성 존재 여부와 required만 본다. 타입 변경(string→number), enum 축소, nullable 변경은 모두 `"none"`이다(2.2 실행 결과). **게이트:** FE-GATE-014는 이름이 `config-compatibility`다(`config/ci/gates.json:1989`). 그런데 실행하는 `scripts/check-compatibility.ts:24-34`는 `config/compatibility/fixtures.json`에 손으로 쓴 before/after 8쌍을 분류기에 넣어 보는 자가 검사다. 실제 설정·API 스키마의 이전/현재 버전은 읽지 않는다. **실제 reader:** ① 런타임 설정 V2는 `.strict()`이고 `CONFIG_SCHEMA_VERSION`이 `z.literal("2.0")`이다(`release-artifacts.ts:163-171`). 선택 키 하나를 추가하거나 버전을 "2.1"로 올리면 거부된다. `isVersionCompatible("2.0","2.1")`은 true라고 답하지만, 이 minor 호환 규칙은 설정 V2에서는 도달하지 않는다. ② `CAPABILITY_OVERRIDES`는 모르는 capability를 거부한다(`release-artifacts.ts:50-63`). 반면 `FEATURE_OVERRIDES`는 "공유 설정 문서가 여러 빌드를 덮을 수 있게" 모르는 ID를 무시한다(`:65-80`). ③ HTTP V2 성공·실패 envelope은 `.strict()`다(`adapters/http/schema-registry.ts:12-34`). `links`나 `error.target`만 추가해도 검증에 실패한다. ④ realtime envelope은 exact-key로 검사하고, 모르는 eventType을 MALFORMED_EVENT로 처리한다(`adapters/realtime/event-codec.ts:126,149`). 그러면 연결을 닫고 복구를 시작한다. ⑤ RPC transport 오류 코드는 닫힌 어휘이고, 모르는 코드는 계약 위반이 된다(2.3). ③④는 설계 문서의 `REJECT_UNKNOWN`(control envelope) 방침과 일치한다. 문제는 호환성 규칙·분류기·게이트가 이 방침을 반영하지 않는다는 점이다 |
| 발생 조건 | 다운스트림이 문서와 게이트를 믿고 다음 변경을 "additive"로 배포할 때: 설정에 선택 키나 capability 추가(여러 빌드가 공유 설정을 쓰는 경우), 서버 envelope에 필드 추가, 새 realtime eventType을 서버가 먼저 배포. 여러 탭과 롤백은 지원 범위이므로 구버전 reader가 실제로 남아 있다 |
| 영향 | 설정: 구 빌드가 부팅에 실패한다(`BOOT_CONFIG_FAILURE`). envelope: 구 탭의 V2 호출이 모두 `ENVELOPE_MISMATCH`가 된다. realtime: 구 탭의 스트림이 이벤트마다 닫히고 복구를 반복한다. 타입·enum 변경은 게이트가 "none"이라 리뷰에서도 놓친다. 모두 fail-closed라 데이터 손상은 없다 |
| 심각도·우선순위 | Medium · P2 — 게이트 이름과 분류 결과가 실제보다 강한 보장을 약속해서, 배포 순서 판단을 틀리게 만든다. 템플릿의 호환성 문서와 게이트는 그대로 복제된다 |
| 통제·증거 | M1(문서 규칙만 있음. 게이트는 분류기 자가 검사) · E2(파서·분류기 직접 실행) |
| 확실성과 남은 가정 | 파서 동작은 실행으로 확인했다. 실제 브라우저에서 구 탭과 신 서버가 공존하는 실험은 하지 않았다. 설정 공유 운영은 코드 주석(`release-artifacts.ts:71-73`)이 지원한다고 적은 시나리오다 |
| 최소 개선 방향 | (1) `docs/contracts/compatibility.md`에 경계별 표를 넣는다. `REJECT_UNKNOWN` 경계(설정, V2 envelope, realtime envelope, RPC 오류 어휘)에서는 필드 추가도 breaking이고, reader를 먼저 배포해야 한다. (2) 분류기는 모르는 변경(타입·enum·nullable)을 `"none"` 대신 `"breaking"`으로 답한다(fail-closed). 아니면 이름을 `classifyRequiredPropertyChange`로 줄인다. (3) FE-GATE-014는 실제 스키마(예: 빌드가 만드는 `dist/runtime-config.schema.json`)를 커밋된 기준본과 비교한다. 그게 과하면 게이트 이름을 `compatibility-classifier-selftest`로 바꾼다. (4) `CAPABILITY_OVERRIDES`의 모르는 키 처리를 `FEATURE_OVERRIDES`와 맞추거나, 다른 이유를 적는다. (5) `compatibility.test.ts`에 "런타임 minor가 더 낮으면 비호환" 케이스를 추가한다(M10 survived) |
| 비용·부작용 | (1)(4)(5)는 작다. (2)는 분류기 결과가 보수적으로 바뀌므로 fixture를 갱신해야 한다. (3)은 기준본 파일과 갱신 절차가 하나 더 생긴다 |
| 완료 기준 | 문서가 경계별 규칙을 적고 있다. 타입 변경 fixture가 `breaking`으로 분류된다. 게이트가 실제 스키마를 읽거나 이름이 실제 동작과 맞다 |
| 검증 방법 | 분류기에 타입·enum 변경 fixture 추가. 설정 스키마에 선택 키를 추가한 변이로 게이트 결과 확인. M10 재실행 시 killed |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 07-03 참조 기능이 같은 HTTP 오퍼레이션을 V2·V3 두 벌로 선언하고, 거버넌스는 실행되지 않는 V2 벌만 본다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (갈라진 중복 복사본) |
| 관련 관점 | 3, 9, 17, 20, 21, 22, 23 |
| 근거 | V2 행: `src/features/reference-feature/contracts/reference-feature-contract.ts:155-238`(`defineRestOperation` 3개). V3 descriptor: `reference-feature-contract-contribution.ts:103-140` 등 3개. method, path, 성공 상태, 응답 상한, 재생 정책, auth profile을 양쪽에 따로 적는다. 실행되는 것은 V3다(`adapters/http/index.ts:37-45`가 "V2 legacy, 레지스트리를 비워서 출하"라고 적는다. gateway도 V3를 쓴다). V2 벌이 쓰이는 곳은 세 군데다. FE-REG-API 거버넌스(`registry-governance.json:143`, exportName `API_OPERATIONS`), 스키마·매퍼·프로필 바인딩 검사(`features/installed-feature-contracts.ts:40-44,77`), realtime snapshot 바인딩(`realtime-streams.ts:451-470`은 V2 QUERY 행을 요구한다). V3 조립(`features/installed-contract-contributions.ts:15`)과 V2 행이 일치하는지 비교하는 코드·테스트는 없다(`reference-contract.test.ts:112-132`는 V2 키 목록만 본다). **실험:** worktree에서 V3의 `pathTemplate`을 `/api/v9/items/{resourceId}`로, `responseByteLimit`을 32 KiB → 8 MiB로 바꿨다. `node scripts/check-registries.ts`는 `11 registries PASS`였다. 실패한 것은 참조 기능용 시나리오 카탈로그 통합 테스트 하나뿐이었다(`tests/integration/http-scenario-catalog.test.ts`, 동작 기반) |
| 발생 조건 | 다운스트림이 참조 기능을 복제해 오퍼레이션을 추가·변경할 때. 특히 V3만 고치고 V2를 두는 경우 |
| 영향 | 거버넌스가 "breaking 변경에는 증거 필요"를 강제하는 대상이 실제로 실행되지 않는 복사본이다. 실행되는 계약의 path·상한·재시도 변경은 증거 없이 통과한다. 반대로 V2만 바꾸면 증거를 요구받지만 동작은 바뀌지 않는다. 다운스트림 기능은 오퍼레이션마다 두 형식을 배워야 하고, 참조 기능 같은 시나리오 카탈로그가 없으면 불일치를 잡을 장치가 없다 |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 하지만 공유 계약 변경 관리가 착시가 되고, 기능마다 변경 누락이 반복될 구조다. 소유자 결정("갈라진 중복 복사본은 문제")에 해당한다 |
| 통제·증거 | M0(두 벌 일치 검사 부재) · E2(worktree 변이 실험) |
| 확실성과 남은 가정 | 참조 기능 기준으로 확인했다. V2 클라이언트를 실제로 주입해 쓰는 다운스트림이 있는지는 알 수 없다 |
| 최소 개선 방향 | 둘 중 하나를 고른다. (a) V2 행을 V3 descriptor에서 생성해 한 벌로 만든다(method/path/상태/상한/auth 복사). (b) 당장은 테스트 하나를 추가한다. 같은 operationId의 V2 행과 V3 descriptor에서 method, path, 성공 상태, 응답 상한, auth profile, 재생 정책이 일치하는지 본다. 장기적으로는 FE-REG-API가 조립된 V3 레지스트리를 감시하게 옮긴다 |
| 비용·부작용 | (b)는 테스트 1개. (a)와 거버넌스 이전은 기준본(baseline) 재승인과 change evidence가 필요하다 |
| 완료 기준 | V3 path나 상한을 바꾸면 거버넌스 또는 일치 테스트가 실패한다 |
| 검증 방법 | 위 실험을 다시 실행해 `check-registries` 또는 일치 테스트가 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 (6.7-8의 "두 모양"과 같은 계열이지만 대상이 다르다) |
### 07-04 ERROR_REGISTRY의 severity·redaction·telemetryEvent와 AppFailure.retryable은 읽는 곳이 없는데 정책처럼 관리된다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 (이름·필드가 실제 보장을 과장) |
| 관련 관점 | 22, 24, 7, 10 |
| 근거 | `errors.ts:31-39`의 7개 필드 중 `severity`, `redaction`, `telemetryEvent`를 읽는 코드는 `src`에 없다(grep 결과 0건). 실제 텔레메트리는 `bootstrap/runtime-adapters.ts:256`과 `adapters/http/client.ts:246`이 `"api.request.failed"`를 직접 적어 보낸다. 그런데도 FE-REG-ERROR는 `telemetryEvent`를 breakingField로 둔다(`registry-governance.json` FE-REG-ERROR `breakingFields`). 과거에 이 필드를 바꿀 때 rollback 계획까지 적은 증거가 남아 있다(`registry-change-evidence.json:101`). `redaction` 목록도 실제로는 쓰이지 않는다. 실제 필드 제거는 `createFailure`의 허용 목록 복사가 한다. `AppFailure.retryable`도 presentation·application·query-cache에서 읽는 곳이 없다(grep 0건). 그래서 `createFailure(…, {effect:"MAYBE_APPLIED"})`의 `retryable=false` 규칙을 망가뜨려도 테스트가 통과한다(M1 survived) |
| 발생 조건 | 다운스트림이 새 kind에 `telemetryEvent: "payment.failed"` 같은 값을 적거나 `redaction`에 필드를 추가하고, 그대로 동작한다고 믿을 때. 또는 `failure.retryable`로 자동 재시도를 만들 때 |
| 영향 | 기대한 이벤트가 나가지 않는다. 비식별 처리도 바뀌지 않는다. 거버넌스는 효과 없는 필드 변경에 증거를 요구한다. `retryable`을 쓰기 시작하면, 테스트되지 않은 규칙에 기대게 된다 |
| 심각도·우선순위 | Low · P3 — 지금은 동작 결함이 없다. 오해로 생길 비용만 있다 |
| 통제·증거 | M0(연결 부재) · E1(grep) + E2(M1 변이) |
| 확실성과 남은 가정 | 영역 밖(`src/platform/telemetry`)은 필드 이름만 grep했다. 같은 이름의 `severity`는 텔레메트리 이벤트의 필드이지 ERROR_REGISTRY 필드가 아니다 |
| 최소 개선 방향 | 연결하거나 지운다. 연결하지 않을 필드는 행에서 빼고 governance의 `breakingFields`에서도 뺀다. `retryable`을 공개 계약으로 남긴다면 `createFailure`의 effect 규칙 테스트 1개를 추가한다 |
| 비용·부작용 | 필드 제거는 레지스트리 스냅샷 변경이라 change evidence가 필요하다 |
| 완료 기준 | ERROR_REGISTRY의 모든 필드에 읽는 곳이 있거나 필드가 없다. M1이 killed가 된다 |
| 검증 방법 | grep으로 소비자 확인, M1 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 07-05 diagnostics negative fixture는 위반 3개 중 1개만 고정해서 나머지 2개가 풀려도 게이트가 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (가드레일 검출력) |
| 관련 관점 | 21, 10 |
| 근거 | `tests/fixtures/typecheck/invalid-diagnostics-port.ts:7-11`에 위반이 3개 있다. 잘못된 `level`, 잘못된 `eventId`, 잘못된 텔레메트리 이벤트 이름이다. 게이트는 종료 코드 1과 출력 안의 문자열 `"UNKNOWN_DIAGNOSTIC_EVENT"`만 확인한다(`config/ci/gates.json` `check-types-fixture-diagnostics`, `scripts/lib/ci-step-result.ts:66-72`). **실험:** worktree에서 `TelemetryPort.emit`의 인자를 `string`으로 넓혔다(`application/ports/telemetry-port.ts`). tsc는 여전히 exit 1이었고, 판정 함수 `classifyGateStepResult`는 `EXPECTED_FAILURE`를 돌려줬다. 텔레메트리 이벤트 이름 계약이 풀린 것을 검출하지 못한다. `level` 쪽도 같은 구조다. 다른 fixture들은 TS 오류 코드만 고정한다(예: `"error TS2322:"`). 지금은 fixture마다 위반이 하나라 문제없다 |
| 발생 조건 | 텔레메트리 포트나 진단 level 타입이 넓어지는 변경 |
| 영향 | 미등록 텔레메트리 이벤트 이름이 컴파일을 통과한다. 런타임 투영(`telemetry.ts:153-158`)에서 조용히 버려진다 |
| 심각도·우선순위 | Low · P3 — 런타임 투영이 한 번 더 막는다. 검출 수단이 약해진 것뿐이다 |
| 통제·증거 | M3(부분: 3개 중 1개) · E2(변이 실험) |
| 확실성과 남은 가정 | 확인됨 |
| 최소 개선 방향 | TypeScript의 기본 기능인 `// @ts-expect-error`를 위반마다 붙이고, fixture가 오류 없이 컴파일되는 것을 게이트 조건으로 삼는다. 위반이 풀리면 TS2578("쓰이지 않은 @ts-expect-error")로 실패한다. 위반 하나마다 별도로 검출되고, 기대 진단 문자열 관리가 필요 없다. 최소한 이 fixture는 3개로 나눈다 |
| 비용·부작용 | fixture 수정과 gates.json의 expect 변경 |
| 완료 기준 | 3개 위반 각각을 풀었을 때 게이트가 실패한다 |
| 검증 방법 | 위 실험을 세 위반에 각각 반복 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 07-06 `invokeValidator`의 "native throw로 새지 않는다" 약속에 구멍이 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 1, 24, 6 |
| 근거 | 주석(`external-contract-runtime.ts:61-65`)은 검증기 호출이 native throw로 새지 않는다고 약속한다. 그런데 try 밖에서 `[...(result.issues ?? [])]`를 펼친다(`:89`). 직접 호출 결과 `{success:false, issues:5}`와 `{success:false, issues:{}}`는 TypeError를 던졌다. `result.success`는 truthy 여부만 보므로(`:84`) `{success:"no"}`가 VALID가 된다. 호출처는 V3 실행기의 입력·출력·problem 검증 3곳이다(`adapters/http/http-execution-v3.ts:646,1318,1541`) |
| 발생 조건 | 기능이나 외부 패키지가 zod 래퍼가 아닌 직접 만든 검증기를 넣고, 그 검증기가 형식에 맞지 않는 결과를 돌려줄 때. 참조 구현(`zodValidator`)은 항상 배열을 돌려준다 |
| 영향 | 약속된 `VALIDATOR_RUNTIME_FAILURE` 대신 예외가 실행기 밖으로 나가거나, 검증되지 않은 `data`가 VALID로 통과한다 |
| 심각도·우선순위 | Low · P3 — 검증기는 빌드에 포함되는 코드라 원격 입력으로는 도달하지 않는다 |
| 통제·증거 | M2(try/catch는 있으나 불완전) · E2(직접 호출) |
| 확실성과 남은 가정 | 예외가 실행기의 바깥 catch에서 어떤 결과가 되는지는 영역 03에서 확인할 일이다 |
| 최소 개선 방향 | `result.success === true`, `Array.isArray(result.issues)` 검사를 넣고, 아니면 `THROWN`을 돌려준다. 해당 테스트 2건 추가 |
| 비용·부작용 | 몇 줄 |
| 완료 기준 | 위 세 입력이 모두 `THROWN`이 된다 |
| 검증 방법 | 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 07-07 호환 별칭·V1 reader에 폐기 표시와 제거 조건이 코드에 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 17, 9, 26, 27 |
| 근거 | `src/contracts`에 `@deprecated`가 0건이다. 호환 별칭은 주석으로만 표시된다: `ApiFailure`(`errors.ts:264-269`, 8파일 사용), `boundary-mapper.ts:17-18`의 `MappingResult`(7파일 사용), `read-only-registry.ts:64-65` 재수출. V1 설정·매니페스트 reader(`release-artifacts.ts:154-161,191-198`)의 보존 기간은 change evidence에 "one release"라고만 적혀 있다(`registry-change-evidence.json`의 `FE-REG-ENV:API_CONTRACT_VERSION` 항목, 2026-09-24 도입). 코드에는 제거 조건·담당·확인 방법이 없다 |
| 발생 조건 | 시간이 지나 제거 시점을 판단할 때, 또는 새 코드가 별칭을 계속 import할 때 |
| 영향 | 신규 코드가 옛 이름을 계속 쓴다. 보존 기간이 지났는지 알 방법이 없어서 호환 코드가 영구화된다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1(evidence JSON 문장) · E1 |
| 확실성과 남은 가정 | "one release"는 도입된 지 하루라 아직 지나지 않았다 |
| 최소 개선 방향 | 별칭과 V1 reader에 `/** @deprecated <대체> — <제거 조건/릴리스> */`를 단다. 이미 쓰는 typescript-eslint에 `no-deprecated` 규칙이 있는지 확인해 새 import를 막는다 |
| 비용·부작용 | 주석 몇 줄. 규칙을 켜면 기존 사용처 경고가 생긴다 |
| 완료 기준 | 별칭마다 대체와 제거 조건이 적혀 있다 |
| 검증 방법 | grep, lint |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.7-8과 관련 (D-15로 별칭 유지는 결정됨. 폐기 표시는 결정 범위 밖) |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 — 외부 JSON 런타임 검증 | 목표 M4 · 확인 M3 | E2(runtime-schema·계약 테스트 통과, M4/M8 killed) | 부분 충족 — 설정·매니페스트·envelope·realtime은 파서를 거친다. `invokeValidator` 구멍(07-06). `AppFailure`는 브랜드 없는 타입이라 리터럴로 만들 수 있다(지금 `src`에 그런 우회는 없음) |
| 2 | 구조적 성숙도 | 적용 | M3 | E1(`.dependency-cruiser.json`의 contracts→application/features/presentation/bootstrap/adapters 금지 규칙, `src/contracts`의 상향 import 0건) | 충족 — 전체 `check:architecture` 실행은 오케스트레이터 몫 |
| 3 | 변경 용이성 | 적용 | M1 | E1(2.3 추적) | 부분 충족 — 오류 코드 추가는 3~4파일, 정책 4~5개. 문구 누락은 검출되지 않는다(07-01). HTTP 오퍼레이션 두 벌(07-03) |
| 4 | 인지 부하 | 적용 | M1 | E1 | 부분 충족 — HTTP 계약 2세대(V2/V3), 매핑 결과 2모양, 검증기 프로토콜 2개, 거버넌스 JSON 4개. 주석마다 §·VD-·Q-·R- 참조가 많아 추적 비용이 크다 |
| 5 | 위험 가시성 | 적용 | M2 | E1 | 충족 — `HTTP_EXECUTION_CEILINGS`, `REALTIME_HARD_LIMITS`, `BROWSER_RPC_HARD_LIMITS` 등 상한이 계약에 드러난다. 효과 확실성(`FailureEffectCertainty`)도 타입으로 드러난다 |
| 6 | 실패 성숙도 | 적용 | M3 | E2(M1b killed, M1 survived) | 부분 충족 — MAYBE_APPLIED 처리는 있다. `createFailure` 경로는 테스트가 없다(07-04). 새 오류 코드는 kind 단위로 안전하게 떨어진다 |
| 7 | 운영 성숙도 | 부분 적용 — 관측 어휘 | M1 | E1 | 부분 충족 — telemetry에는 `error_kind`만 남고 서버 code는 남지 않는다. `telemetryEvent` 필드는 효과가 없다(07-04). 관측 파이프라인은 다른 영역 |
| 8 | 디버깅 가능성 | 부분 적용 | M2 | E1 | 부분 충족 — `AppFailure`는 requestId·traceId·code를 보존한다. 관측으로 나가는 것은 kind뿐이다. 수집 경로는 다른 영역(03·09) |
| 9 | 유지보수 성숙도 | 적용 | M1 | E1 | 부분 충족 — 별칭 폐기 표시가 없다(07-07). 두 벌 선언(07-03) |
| 10 | 테스트 성숙도 | 적용 | M3 | E2(244+33 통과, 변이 16건 중 12 killed) | 부분 충족 — 직전 리뷰 수정분은 테스트가 잡는다. M1·M10 survived. 구버전 소비자/신버전 제공자 조합 테스트는 없다 |
| 11 | 데이터 성숙도 | 부분 적용 — 저장소 키 계약 | M4 | E1 | 충족(이 영역 범위) — 키 버전화와 `migration: "discard"`만 허용하고, 모르는 값은 거부한다(`storage-keys.ts`). 저장 구현은 영역 05 |
| 12 | 동시성 성숙도 | 적용 제외 — contracts는 순수 함수. 조립 시점 재읽기 방지(스냅샷 1회 읽기)는 관점 1에 기록 | - | - | 적용 제외 |
| 13 | 확장성 | 부분 적용 | M2 | E1 | 부분 충족 — 레지스트리 상한(예: RPC 오퍼레이션 512, realtime 스트림 128)이 있다. 기능 전용 오류도 중앙 `ERROR_REGISTRY`로 모인다. 규모 실험은 다른 영역 |
| 14 | 성능 성숙도 | 적용 제외 — 계약 코드는 상한이 정해진 작업만 한다. 측정 대상 아님 | - | - | 적용 제외 |
| 15 | 보안 성숙도 | 적용 — 설정 비밀 이름, 배포 승인, 자격 증명 헤더 | M3 | E2(M8·M19 killed) | 충족 — 6.7-2·6.7-10 수정 확인. 텔레메트리는 속성 허용 목록으로 제한한다 |
| 16 | 의존성 성숙도 | 부분 적용 | M1 | E1 | 부분 충족 — contracts가 zod에 직접 의존한다(`release-artifacts.ts`, `contract-set.ts`). 판단은 다른 영역 |
| 17 | API / Contract 성숙도 | 적용 — 중점 | 목표 M3 · 확인 M1~M2 | E2 | 부분 충족 — 누락·빈 값·모르는 값을 안전하게 처리하는 곳이 많다(강점 4). 호환성 규칙·게이트가 strict 경계를 반영하지 않는다(07-02). 폐기 절차가 코드에 없다(07-07). 구·신 버전 공존 검증이 없다 |
| 18 | 배포 성숙도 | 다른 영역 — release. 이 영역 관련분만 기록 | M1 | E2 | 부분 충족 — 설정 V2가 엄격해서 빌드 간 설정 공유 시 additive 변경에도 부팅이 막힌다(07-02) |
| 19 | 설정 성숙도 | 부분 적용 | M3 | E2 | 부분 충족 — 스키마, 불변식, 금지 이름을 검증한다. `CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`의 모르는 키 처리가 다르다(07-02) |
| 20 | 개발자 경험 | 부분 적용 | M1 | E1 | 부분 충족 — 오퍼레이션 하나에 두 형식을 써야 한다(07-03). 문구 누락은 조용히 대체 문구로 나간다(07-01) |
| 21 | Guardrail 성숙도 | 적용 — negative fixture | M3 | E2(fixture 8개 실행, 변이 실험) | 부분 충족 — fixture는 의도한 위반을 잡는다. diagnostics fixture는 3개 중 1개만 고정한다(07-05). 문구 연결(07-01), V2/V3 일치(07-03)를 잡는 장치가 없다. FE-GATE-014는 자가 검사다(07-02) |
| 22 | 추상화 성숙도 | 적용 — 레지스트리·거버넌스 | M2 | E1·E2 | 부분 충족 — exact-snapshot으로 모은 것은 효과가 확인된다(M6 killed). 레지스트리 거버넌스는 효과 없는 필드(07-04)와 실행되지 않는 복사본(07-03)도 감시한다. module augmentation은 contracts 밖(영역 09) |
| 23 | 일관성 | 적용 | M2 | E1 | 부분 충족 — `AppFailure.code` 문법이 경로마다 다르다(V2 `^[A-Z0-9_]{1,64}$`, V3 problem code는 120자 자유 문자열, RPC는 `RPC_*`). 진단 `outcome` 값은 소문자·대문자 어휘가 섞여 있다(`diagnostics.ts:94-97`). `MappingResult` 두 모양은 D-15로 유지된다. `validBoundedString`은 "공백만 아님 + 바이트 상한"만 본다 |
| 24 | 네이밍 / 의미 성숙도 | 적용 — 중점 | M1 | E2 | 미충족 — 이름이 보장을 과장한다. `config-compatibility` 게이트와 `classifyObjectSchemaChange`(07-02), "never escapes as a native throw"(07-06), `telemetryEvent`·`redaction`(07-04). `safeValidationIssues`의 "safe"는 크기 제한이지 문자 정제가 아니다(코드 80자, 경로 120자 자유 문자열) |
| 25 | 조직 확장성 | 구조적 준비만 평가(작성자 1인) | M1 | E1 | 미검증 — 기능 전용 오류도 중앙 레지스트리와 공용 카탈로그를 고쳐야 한다(2.3). 레지스트리마다 owner 문자열은 있다 |
| 26 | Ownership 성숙도 | 부분 적용 | M1 | E1 | 부분 충족 — governance·evidence에 owner가 있다. 호환 코드 제거 담당은 없다(07-07) |
| 27 | 삭제 가능성 | 다른 영역 — 기능 제거 | - | E1 | 다른 영역 — 참조 기능 제거 시 V2·V3 두 곳을 지워야 한다는 점만 기록(07-03) |
| 28 | 회복 가능성 | 적용 제외 — contracts는 복구 절차를 소유하지 않음 | - | - | 적용 제외 |
## 6. 미검증 목록
- **구 탭 + 신 서버·설정 공존.** strict reader가 실제 배포 순서에서 부팅 실패나 재연결 반복으로 이어지는지는 파서 단위로만 확인했다. 확인하려면 Playwright에서 구 번들이 열린 탭에 envelope 필드와 설정 키가 추가된 응답을 주는 시나리오가 필요하다.
- **browser-rpc 미등록 오류 코드와 command 효과.** 코드가 프로토콜 위반으로 분류될 때 command의 `effect`(MAYBE_APPLIED 여부)가 어떻게 되는지 확인하지 않았다. 영역 03에서 transport 오류 경로 테스트로 확인해야 한다.
- **부팅 오류 화면의 문구.** `BOOT_CONFIG_FAILURE` 등 부팅 계열이 `TerminalErrorSurface` 대신 별도 부트 화면 문구를 쓰는지 확인하지 않았다(07-01의 부팅 계열 영향 범위).
- **줄 단위로 읽지 않은 파일.** `browser-rpc.ts` 내부 검증식, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `runtime-capabilities.ts`, `product-features.ts`.
- **전체 게이트.** `check:types`, `check:architecture`, `test:unit` 전체, `verify:compatibility`를 이 리뷰에서 직접 실행하지 않았다(오케스트레이터 몫).
@@ -0,0 +1,364 @@
# presentation 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/presentation/` 72파일(TS/TSX 약 8.1k줄, CSS 약 1.6k줄). 시나리오 추적용으로 샘플 화면 `src/features/reference-feature/presentation/`(8파일, 약 580줄)도 읽었다. 문서 `docs/accessibility/manual-checklist.md`, `docs/styling/*`, `docs/architecture/routing-pages-and-patterns.md`, 테스트 `tests/component/`, `tests/features/reference-feature/reference-page.test.tsx`, `tests/e2e/`(화면 관련), `tests/visual/`, `tests/storybook/`
> 영역 판정(35.8): **조건부 사용 가능**
## 1. 결론
- **조회 화면 패턴은 그대로 써도 된다.** 목록·상세는 loading·success·empty·error·idle을 구분한다. 조회 실패는 종류에 따라 "로그인"(현재 URL로 복귀), "안전한 화면으로 이동", "다시 시도" 버튼을 따로 준다. 이전 세션의 응답과 과거 필터의 응답이 현재 화면을 덮지 않는다. 테스트도 이 동작을 막고 있다.
- **폼 저장 실패 처리는 고쳐야 한다(08-01).** 모든 폼이 쓰는 `useAppForm`이 세션 만료(401)·권한 없음(403)·요청 과다(429)를 전부 "입력 내용을 확인해 주세요 / 잠시 후 다시 시도해 주세요" 하나로 보여 준다. 로그인 버튼도 없다. 같은 실패가 목록 조회에서는 "로그인" 버튼으로 나온다.
- **결과 불명 저장(08-03)은 판단 근거 없이 사용자에게 "적용됨/안 됨"을 고르게 한다.** "안 됨"을 고른 뒤 같은 값으로 다시 저장하면 새 멱등 키로 나간다. 정본 설계 문서는 같은 키를 쓰라고 한다.
- **오류 종류 38개 중 22개에 사용자 문구가 없다(08-02).** 이때 오류 제목으로 "요청한 문구를 표시할 수 없습니다."가 뜬다. 샘플 화면 문구는 언어 전환 대상이 아니다(08-04). 두 문제 모두 `check:i18n`이 잡지 못한다.
- **접근성은 자동 스캔 증거만 있다. 그마저 범위가 좁다.** axe는 보호 라우트 4개에서 실제 화면이 아니라 로그인 안내 화면을 검사한다(08-05). 사람이 한 수동 검토는 0/10건이다. 그래서 merge 게이트 FE-GATE-009의 수동 검토 단계가 현재 상태로는 통과할 수 없다(08-06).
- 직전 리뷰 6.8의 1~9, 11~13은 코드에서 고쳐진 것을 다시 확인했다. 6.8-10(상태 화면 통합)만 일부가 남았다(08-11).
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상·커밋 | `main` / `4626b73`. 미커밋 파일(`CLAUDE.md`, 가이드)은 판정 기준으로만 읽었다 |
| 목적·실행 구성 | 템플릿 SPA. SSR 없음. 판정 전제는 공통 지시서 2절을 따랐다 |
| 읽은 코드 | `src/presentation/` 전 파일(routes, boundaries, layouts, providers, adapters/query, forms, templates, design-system, i18n, pages, examples). 샘플 화면 전체. 연결 확인용으로 `src/contracts/errors.ts`, `src/application/view-models/async-state.ts`, `src/adapters/platform/browser-mutation-intent-factory.ts`, `src/bootstrap/runtime-application.tsx`, `eslint.config.ts`, `scripts/check-i18n.ts`, `config/ci/gates.json`의 FE-GATE-009 |
| 실행한 테스트(원본 트리) | `node scripts/run-vitest.ts run` 대상 14파일: router, async-surface, form-foundation, route-status-surfaces, locale-platform, app-shell, chunk-recovery-boundary → 59/59 통과. reference-page, application-query-scope-fence, application-mutation-scope-fence, context-route-gateway, pagination, tooltip, page-templates → 32/32 통과 |
| 실험(분리 worktree, 종료 후 제거) | ① probe 테스트 2파일: 폼 실패 kind별 화면, 로케일 전환 뒤 오류 문구, registry↔catalog 누락, 목록 실패 시 status, 결과 불명 뒤 재제출 멱등 키 → 결과는 각 발견 항목에 적었다. ② 결함 주입: `ChunkRecoveryBoundary`의 `key` 제거 → chunk-recovery 테스트 실패(검출됨). `isInitialLoading`을 `query.isPending`으로 되돌림 → application-query-bridge 테스트 실패(검출됨). `TextField`의 `aria-describedby` 제거 → component 테스트 1건 실패(검출됨). feature 화면에 `dangerouslySetInnerHTML` 추가 → ESLint FE-OC-019가 검출함. `check:i18n`은 통과함(검사 범위 밖). ③ `check:i18n` → PASS(145 keys). 이때 한국어 literal이 있는 화면 파일 9개가 그대로 있었다. ④ `verify-a11y-manual.ts` → 실패("evidence is incomplete") |
| 확인하지 못한 범위 | Playwright E2E·visual·storybook 실행(브라우저와 포트를 다른 에이전트와 공유), 실제 스크린리더, 번들 크기 재측정(`dist/`는 9/24 빌드이고 새 빌드는 공유 경로에 쓴다), HTTP 상태→FailureKind 분류(영역 03) |
| 직전 리뷰 비교 | 6.8-1~9, 11~13: 코드에서 수정 확인. 대부분 회귀 테스트도 있다(예: `router.test.tsx:109`, `:141`, `chunk-recovery-boundary.test.tsx:144`, `app-shell.test.tsx:81`, `context-route-gateway.test.tsx:72`). 6.8-10은 일부 미해결 → 08-11 |
### 2.1 32절 시나리오 추적
| 시나리오 | 따라간 경로 | 결과 |
|---|---|---|
| 목록 최초 진입 | URL → `ContextRouteGateway` → `ProtectedRoute` → Suspense(`RouteLoadingSurface`) → `ReferenceResourcePage` → `useApplicationQuery` → `AsyncSurface` | 상태 구분됨(`async-state.ts:90-102`, `reference-page.test.tsx:163`). 실패 중에도 결과 수 status가 "결과 확인 중"으로 남는다(08-09). 문구가 없는 오류 종류가 22개다(08-02) |
| 상세 URL 직접 접속 | 생성 파일 `src/.generated/product-context-index.ts` → `context-routes.ts` → lazy 상세 페이지. `DetailPage key={resourceId}` | 동작함(컴포넌트 테스트). ID가 `new`/`status`면 충돌한다(08-13). SPA fallback은 배포 영역 |
| 빠른 필터 변경 | URL search → zod codec → `bindQuery`가 필터마다 다른 key token 부여 → abort signal 전달 | 과거 응답이 최신 화면을 덮지 않는다(key 분리). 샘플에 필터 UI가 없어 URL을 직접 바꿔야 재현된다 |
| 화면 이동·언마운트 | queryFn이 signal을 쓰므로 관찰자가 0이면 TanStack이 취소한다. gateway의 `active` 플래그, Popover·Menu·Toast 리스너 정리 | 작업·리스너가 쌓이지 않는다(정적 확인). 뒤로 가기 스크롤 복원은 없다(08-08) |
| 로그아웃 중 응답 도착 | 실행 전후 `scope.isCurrent()` 확인(`application-query.ts:101-121`), `QueryClientProvider key={generation}` | 이전 세션 응답을 버린다(scope-fence 테스트 통과) |
| 저장 버튼 중복 클릭 | 버튼 disabled, `submitForm`의 `pendingRef`(`use-app-form.ts:257-271`), `REJECT_WHILE_ACTIVE`(`application-query.ts:458-469`), 멱등 키 | 화면 쪽 중복 방지 충족. 결과 불명 뒤 재제출은 새 키를 쓴다(08-03) |
| 낙관적 갱신 실패 | `optimistic-layer-runtime.ts` layer rollback, 서버 갱신 시 base 재계산(`:50-62`) | 구현과 테스트가 있다(`application-mutation-optimistic-cache.test.tsx`). 샘플 화면은 이 패턴을 쓰지 않는다 |
| 세션 만료 | 조회: `AUTH_REQUIRED` → "로그인" → `beginSignIn(returnTo)`. 저장: 08-01. subject가 바뀌면 scope fence가 앱 트리를 다시 마운트한다 | 조회는 충족. 저장은 미충족. 작성 중인 폼 값은 확인 없이 사라진다(데이터 폐기 정책으로 보이지만 문서에서 확인하지 못함) |
| 다국어 전환 | `PreferenceProviders`가 fence 밖에 있다(`runtime-application.tsx:32-56`). `lang/dir` 동기화. 로케일이 바뀌면 제목만 갱신한다 | 셸과 공통 상태 문구는 전환된다. 샘플 화면 문구(08-04)와 표시 중인 폼 오류(08-10)는 전환되지 않는다 |
| 키보드·보조기술 | 라우트 이동 시 main → h1 포커스(`app-router.tsx:166-180`, `page-header.tsx:16-27`). Dialog 포커스 복귀(`core.tsx:363-412`). ErrorSummary와 첫 오류 필드 포커스. `aria-describedby`/`aria-invalid`(`core.tsx:154-241`) | 구현·테스트 있음. 결함 주입도 검출된다. 실제 스크린리더 확인은 0건(08-06). axe 범위가 좁다(08-05) |
### 2.2 대표 과제(관점 4): "목록 화면이 어느 API를 호출하고 실패하면 어떤 화면을 보여 주는가"
작성자 설명 없이 코드만으로 끝까지 찾을 수 있었다. 막힌 곳은 네 군데다.
```text
URL /examples/reference-resources
→ route 정의: reference-feature-contract.ts:78 (grep으로 바로 찾음)
→ 페이지 컴포넌트: installed-feature-runtimes.tsx의 ROUTE_RUNTIME에는 feature 항목이 비어 있음 ({}) ← 막힘 1
실제 경로: src/.generated/product-context-index.ts(생성 파일, git에 없음) → context-routes.ts → reference-feature-runtime.ts → lazy page ← 막힘 2
→ 호출: use-reference-feature.ts:121 → input.listResources → reference-feature-api.ts → reference-http-gateway.ts
operationId LIST_REFERENCE_RESOURCES → contract path /api/reference-resources (contract.ts:158)
→ 실패: AppFailure.kind → ERROR_REGISTRY 행(action) → 문구 키는 `error.${kind.toLowerCase()}` 문자열 규칙(errors.ts:52) ← 막힘 3
→ catalog에 없으면 조용히 대체 문구
→ AsyncSurface → TerminalErrorSurface. 버튼은 registry action과 페이지가 넘긴 onAction이 둘 다 있어야 보임
(use-reference-failure-action.ts가 reauth/navigate/contact-support만 처리, retry는 onRetry) ← 막힘 4
```
- 막힘 1·2: feature 화면은 boot용 descriptor(`reference-feature-runtime-descriptor.ts:17-21`, 빈 runtime)와 실행용 runtime이 나뉘어 있다. 연결 고리가 생성 파일이라 clean checkout에서는 파일 검색으로 찾을 수 없다. `app-router.tsx`도 platform 경로(`ROUTE_RUNTIME`)와 context 경로(`runtimeOverride`) 두 갈래를 모두 알아야 읽힌다.
- 막힘 3: 실패 종류와 화면 문구가 타입으로 연결되지 않는다. 그래서 문구 누락(08-02)을 코드 탐색으로는 알아채기 어렵다.
- 막힘 4: 버튼이 안 보일 때 원인이 registry 쪽인지 페이지 쪽인지 두 파일을 함께 봐야 한다.
- 어느 HTTP 상태가 어느 kind가 되는지는 `feature-http-binding.ts:345`와 `http-execution-v3.ts:1158` 두 곳에 있다(영역 03).
## 3. 확인된 강점
1. **비동기 상태 모델이 화면 오류를 줄인다.** `AsyncState`는 base 상태와 overlay가 서로 배타적이다(`async-state.ts:19-61`, `:83-125`). `AsyncSurface`가 상태별 화면을 고정한다(`async-surface.tsx:104-176`). 조회 실패는 action에 따라 로그인(현재 URL·hash로 복귀)·이동·재시도로 갈린다(`use-reference-failure-action.ts:14-50`). 권한 없음·인증 실패·로그인 시작 실패는 `reference-page.test.tsx:211-293`이 막는다. 비활성 쿼리는 로딩이 아니라 idle이다(`application-query.ts:182`, 결함 주입으로 검출 확인).
2. **세션 경계와 응답 경쟁을 화면 쪽에서 막는다.** 요청 전후 scope 확인(`application-query.ts:101-121`), generation마다 다른 QueryClient, fence 밖의 로케일·테마, router dispose(`app-router.tsx:545-551`)가 있다. 과거 세션·과거 필터의 응답이 현재 화면에 들어가지 않는다.
3. **중복 제출과 결과 불명의 자동 재전송을 막는다.** 제출 하나를 검증부터 결과까지 묶는다(`use-app-form.ts:257-271`). effect가 없는 실패는 `MAYBE_APPLIED`로 본다(`application-query.ts:720-731`). 결과 불명이면 재제출을 막는다(`reference-resource-form-page.tsx:44-47`, `form-foundation.test.tsx:162`).
4. **접근성 기본 동작이 구현돼 있고, 테스트가 회귀를 잡는다.** 라우트 포커스, native `<dialog>`와 세대 번호로 하는 포커스 복귀, 필드 오류 연결, ErrorSummary가 있다. `aria-describedby` 제거 주입이 실제로 실패로 잡혔다.
5. **XSS 경로가 막혀 있다.** `dangerouslySetInnerHTML`은 모든 소스에서 ESLint로 금지된다(`eslint.config.ts:394-409`). feature 화면에 넣어 보자 검출됐다. React 19.2는 `javascript:` URL을 차단한다. 백엔드 메시지 렌더링은 `check:i18n`이 검사한다. CSP는 `script-src 'self'`다(`config/hosting/security-headers.json:4`).
6. **화면은 경로별로 lazy 로딩된다.** platform 화면(`route-runtime.tsx:25-47`), feature 화면(`reference-feature-runtime.ts:8-25`), context 라우트 모듈(생성 index의 동적 import)이 모두 분리돼 있다. 청크 실패 복구는 라우트별로 초기화된다(`app-router.tsx:338-339`, `:440-449`).
## 4. 발견 사항 (36.3)
### 08-01 폼 저장 실패가 세션 만료·권한 없음·요청 과다까지 "입력 확인 / 잠시 후 다시 시도" 하나로 합쳐짐
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 5, 10, 23 |
| 근거 | `src/presentation/forms/use-app-form.ts:212-239`: `VALIDATION_REJECTED`, `MAYBE_APPLIED`, `APPLIED_CONFIRMED`, `CONFLICT` 외 모든 실패가 `form.unavailable`이 된다. `form-contracts.ts:16-22`의 `FormResultState`에는 재로그인·권한 없음 상태가 없다. 이 문구는 `ErrorSummary`에 들어가고 제목은 항상 "입력 내용을 확인해 주세요."다(`form-components.tsx:55`). probe: reference 폼에 `AUTH_REQUIRED`(401, NOT_APPLIED)를 돌려주자 alert="입력 내용을 확인해 주세요.저장하지 못했습니다. 잠시 후 다시 시도해 주세요."였고 로그인 버튼이 없었다(셸은 "로그아웃"을 표시). `FORBIDDEN`, `RATE_LIMITED`, `DUPLICATE_IN_FLIGHT`도 결과가 같았다 |
| 발생 조건 | 저장 요청이 401/403/429 등으로 거절될 때. 특히 토큰이 만료된 뒤 저장할 때 |
| 영향 | 사용자는 입력을 고치거나 재시도하지만 결과가 바뀌지 않는다. 403인데 "잠시 후 다시 시도"로 안내한다. 같은 실패가 목록 조회에서는 "로그인" 버튼으로 나와 화면 응답이 서로 다르다. 입력값은 남으므로 데이터 손실은 없다 |
| 심각도·우선순위 | Medium · P1 — 피해는 잘못된 안내로 끝난다. 하지만 `useAppForm`은 다운스트림 폼 전부가 쓰는 기본 훅이라 복제 범위가 가장 넓고, 고치는 비용은 작다 |
| 통제·증거 | M0(폼 경로에 구분 수단 없음) · E2(probe 테스트) |
| 확실성과 남은 가정 | 폼 쪽 동작은 확인했다. HTTP 어댑터가 401 저장 실패를 NOT_APPLIED로 분류한다는 전제는 영역 03에서 확인해야 한다 |
| 최소 개선 방향 | `FormResultState`에 `reauth-required`·`forbidden`·`retry-later`를 추가하고 `failure.action` 기준으로 분기한다. 이 결과들은 ErrorSummary가 아니라 폼 상태 영역에 보여 준다. ErrorSummary 제목은 입력 오류일 때만 쓴다. reauth면 `beginSignIn(returnTo)` 버튼을 준다. 대안으로 폼 feedback 슬롯에서 `TerminalErrorSurface`를 재사용할 수 있다 |
| 비용·부작용 | 폼 결과 상태가 늘어 샘플과 문서를 고쳐야 한다. 로그인 후 scope fence 재마운트로 폼 값이 사라지므로, 로그인 버튼 앞에 그 사실을 알려야 한다 |
| 완료 기준 | 401·403·429 저장 실패에서 서로 다른 문구와 행동(로그인/이동/재시도)이 나온다. "입력 내용을 확인해 주세요" 제목은 나오지 않는다 |
| 검증 방법 | `form-foundation.test.tsx`와 `reference-page.test.tsx`에 kind별 `it.each` 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-02 오류 종류 38개 중 22개에 문구가 없어 "요청한 문구를 표시할 수 없습니다."가 오류 제목으로 나옴
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 3, 21, 23, 24 |
| 근거 | 문구 키는 문자열 규칙으로 만든다: `src/contracts/errors.ts:52` `error.${kind.toLowerCase()}`. catalog에는 `error.*` 키가 16개뿐이다(`src/presentation/i18n/catalog.ts:130-145`). 없는 키는 `message-contract.ts:75-79`에서 `common.unavailable`로 바뀐다. probe로 누락 22개를 확인했다: CONFLICT, SCHEMA_MISMATCH, MALFORMED_JSON, CONTENT_TYPE_MISMATCH, ENVELOPE_MISMATCH, RESPONSE_BODY_LIMIT, MAPPING_CONTRACT_VIOLATION, RESULT_LIMIT_EXCEEDED, PAGINATION_CONTRACT_VIOLATION, QUERY_CACHE_FAILURE, UNKNOWN_CLIENT_FAILURE, SCOPE_GENERATION_CHANGED, IDENTITY_INTERN_LIMIT_EXCEEDED, DUPLICATE_IN_FLIGHT, VALIDATION_REJECTED 등. 목록 조회에 `SCHEMA_MISMATCH`를 주자 alert="요청한 문구를 표시할 수 없습니다. / 지원 정보 확인"이 나왔다. `check:i18n`(`scripts/check-i18n.ts:32-53`)은 locale 간 키가 같은지만 보고, registry와 catalog가 이어지는지는 보지 않는다(실행 결과 PASS) |
| 발생 조건 | 서버 응답 형식 불일치, 조회 중 409, 결과 상한 초과, 클라이언트 매핑 실패 등 |
| 영향 | 사용자는 "문구 누락" 안내를 오류 설명으로 읽는다. 문의할 때 무엇이 실패했는지 말할 수 없다. 새 FailureKind를 추가해도 어떤 검사도 실패하지 않아 같은 누락이 반복된다 |
| 심각도·우선순위 | Medium · P2 — 화면이 멈추지 않고 행동 버튼도 나온다. 다만 22개 종류에 걸쳐 있고 검출 수단이 없다 |
| 통제·증거 | M1(VD-06 결정 8에 원칙만 있음) · E2(probe) |
| 확실성과 남은 가정 | 누락은 확인했다. 일부 kind(TELEMETRY_FAILURE 등)는 화면에 오지 않을 수 있다. 어떤 kind가 화면에 오는지 정하는 일도 수정 범위에 들어간다 |
| 최소 개선 방향 | 화면에 올 수 있는 kind에 ko/en 문구를 추가한다. 테스트로 "`ERROR_REGISTRY`의 모든 `userMessageKey`가 catalog에 있거나 명시적 제외 목록에 있음"을 검사한다. 타입 제약으로 강제하는 방법도 있다 |
| 비용·부작용 | 문구 최대 22개 × 2 locale, 테스트 1개 |
| 완료 기준 | 누락 키가 0개이거나 제외 목록과 정확히 같다. 새 kind를 추가하면 테스트가 실패한다 |
| 검증 방법 | 단위 테스트 + 문구 하나를 지우는 결함 주입 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-03 결과 불명 저장을 확인 수단 없이 사용자가 판정하게 하고, "안 됨" 뒤 재제출은 새 멱등 키로 나감
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(정본 설계와 불일치) |
| 관련 관점 | 6, 12, 5, 17 |
| 근거 | 결과 불명 화면은 "변경됨으로 확인 / 변경되지 않음으로 확인" 두 버튼뿐이다(`async-surface.tsx:156-170`). 샘플 폼은 이 화면을 그대로 쓰고, 목록·상세 확인 링크가 없다(`reference-resource-form-page.tsx:129-141`). 제출할 때마다 intent를 새로 만든다(`application-query.ts:508-515`). 브라우저 factory는 create할 때마다 새 UUID 멱등 키를 준다(`src/adapters/platform/browser-mutation-intent-factory.ts:36-40`). probe: `MAYBE_APPLIED` → "변경되지 않음으로 확인" → 같은 값 재제출에서 키가 `key-1`, `key-2`로 달랐다. 정본 설계는 `docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md:1707-1708`("같은 submit의 retry/reconcile에는 동일 intent/key, form value가 변경되면 새 intent")과 `:1721-1723`(inspect로 no effect를 확인한 뒤에만 사용자 재시도 허용)이다 |
| 발생 조건 | 저장 요청을 보낸 뒤 타임아웃·연결 끊김(`MAYBE_APPLIED`) → 사용자가 "변경되지 않음" 선택 → 같은 값으로 다시 저장 |
| 영향 | 첫 요청이 실제로 적용됐다면 서버는 두 요청을 다른 작업으로 보고 중복 생성한다. 사용자는 판단할 근거가 없다. 샘플은 create라 항목이 중복된다. 다운스트림이 주문·결제 폼에 복제하면 피해가 커진다 |
| 심각도·우선순위 | Medium · P2 — 사용자가 명시적으로 "안 됨"을 골라야 발생하고 자동 재전송은 막혀 있다. 하지만 기본 샘플의 결과 불명 처리가 근거 없는 선택으로 끝난다 |
| 통제·증거 | 자동 재전송 차단 M2 / 재제출 키 동일성 M0 · E2(probe) |
| 확실성과 남은 가정 | 클라이언트 동작은 확인했다. 서버가 멱등 키로 중복을 막는다는 계약은 repo 밖이다 |
| 최소 개선 방향 | ① 결과 불명 화면에 확인 행동을 넣는다: 목록·상세 재조회 링크, 또는 feature에 inspect operation이 있으면 조회. ② NOT_APPLIED 확인 뒤 같은 canonical input으로 재제출하면 이전 intent/key를 재사용하고, 값이 바뀌면 새 key를 만든다. admission에 이미 intent가 있다(`application-query.ts:514`) |
| 비용·부작용 | intent 보관 수명을 정해야 한다. inspect 계약은 feature마다 다르다 |
| 완료 기준 | 같은 값 재제출에 같은 멱등 키가 나간다. 결과 불명 화면에서 적용 여부를 확인할 경로가 있다 |
| 검증 방법 | `reference-page.test.tsx`에 키 비교 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-04 샘플 화면 문구가 catalog 없이 코드에 박혀 있어 언어 전환이 적용되지 않음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23, 21, 20 |
| 근거 | `reference-resource-page.tsx:18-40`("새 항목 만들기", "새로고침", "총 N개 항목", "결과 확인 중"), `reference-resource-form-page.tsx:24-27`, `:64-70`, `:106-126`, `:143-145`, `reference-resource-detail-page.tsx:24-58`, `reference-resource-status-page.tsx:9-22`. feature catalog는 라우트 제목만 넣고, ko-KR 값도 영어다(`reference-message-catalog.ts:2-11`). 그래서 한국어 모드에서 제목은 영어, 본문은 한국어다. `check:i18n`은 공통 디렉터리 7개만 검사한다(`scripts/check-i18n.ts:55-63`). 한국어 literal이 있는 화면 파일 9개(feature 4, pages 1, examples 4)가 있어도 PASS였다. VD-06(`:69`)은 검사 범위를 "common UI"로 선언한다 |
| 발생 조건 | en-US로 바꾼 뒤 reference 화면에 들어갈 때 |
| 영향 | 버튼·결과 수·저장 완료 문구가 한국어로 남는다. 샘플을 복사하면 기능 화면마다 literal이 퍼지고, 나중에 번역할 때 전부 다시 찾아야 한다. feature가 자기 문구를 catalog에 넣는 방법(`installed-feature-messages.ts`)이 있는데 샘플이 그 방법을 보여 주지 않는다 |
| 심각도·우선순위 | Medium · P2 — 기능이 고장 나지는 않는다. 다만 복제되는 샘플이 반복 변경 비용을 만든다 |
| 통제·증거 | 공통 UI M3 / feature 화면 M1 · E2(`check:i18n` 실행, grep) |
| 확실성과 남은 가정 | 확인. 샘플 문구를 번역하지 않기로 한 결정이 있는지는 찾지 못했다 |
| 최소 개선 방향 | 샘플 문구를 `reference-message-catalog.ts`로 옮기고 message key로 렌더한다. `check:i18n` 범위에 `src/features/*/presentation`과 `src/presentation/pages`를 넣는다(examples는 명시적으로 제외해도 된다) |
| 비용·부작용 | 문구 약 30개, 검사 범위 확장 |
| 완료 기준 | en-US에서 reference 화면에 한국어 literal이 없다. `check:i18n`이 feature 화면 literal을 검출한다 |
| 검증 방법 | `check:i18n:fixture`에 feature 화면 사례를 추가하고, e2e i18n에 reference 화면 1개를 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-05 axe 스캔이 보호 라우트 4개에서 실제 화면 대신 로그인 안내 화면만 검사함
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(검증 공백) |
| 관련 관점 | 10, 21 |
| 근거 | `tests/e2e/accessibility.spec.ts:5-22`는 라우트마다 `page.goto` 직후 axe를 돌린다. demo 세션의 기본값은 unauthenticated다(`tests/e2e/reference-route.spec.ts:22-24`에서 "세션이 필요합니다."를 확인). 그래서 REFERENCE_RESOURCE_LIST/DETAIL/FORM/STATUS는 같은 `ProtectedRoute` StatusPage를 네 번 검사한다. 로딩·오류·빈 상태, ErrorSummary가 뜬 폼, 결과 불명 화면도 검사하지 않는다(열린 다이얼로그 1건만 `:47-58`). visual 5건에도 reference 화면이 없다(`tests/visual/platform.visual.spec.ts`) |
| 발생 조건 | 항상 |
| 영향 | 목록·폼 화면의 접근성 회귀가 axe 게이트를 통과한다. "10개 라우트 통과"라는 결과가 실제 검사 범위보다 넓게 읽힌다 |
| 심각도·우선순위 | Medium · P2 |
| 통제·증거 | 공개 화면 M3 / 보호 화면 M0 · E1(테스트 코드 정독. Playwright는 실행하지 않음) |
| 확실성과 남은 가정 | 테스트 코드와 demo 기본 세션으로 확인했다 |
| 최소 개선 방향 | 보호 라우트는 "로그인 시작"을 누른 뒤 검사한다. `page.route`로 목록 성공·빈 결과·오류를 각각 응답해 상태별로 검사한다. 폼 제출 오류 상태도 검사한다 |
| 비용·부작용 | E2E 실행 시간이 늘어난다(3엔진) |
| 완료 기준 | 보호 라우트를 검사하기 전에 heading이 라우트 제목인지 assert한다. 상태별 검사가 있다 |
| 검증 방법 | heading assert로 검사 대상을 고정한 뒤 a11y spec 실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-06 수동 접근성 검토 기록 10건이 모두 pending이라 merge 게이트 FE-GATE-009가 통과할 수 없음
| 필드 | 내용 |
|---|---|
| 성격 | 미검증 |
| 관련 관점 | 10, 21, 26 |
| 근거 | `artifacts/tests/a11y-manual/*.md` 10개가 모두 `Status: pending-manual-review`다. worktree에서 `node scripts/verify-a11y-manual.ts`를 돌리자 "Manual accessibility evidence is incomplete"로 실패했다. `config/ci/gates.json`에서 FE-GATE-009는 `review-a11y-manual`(expect pass)을 포함하고, merge 단계 게이트다. `docs/accessibility/manual-checklist.md`는 axe 통과가 WCAG 준수가 아니라고 스스로 적는다 |
| 발생 조건 | 모든 PR의 merge 게이트 |
| 영향 | 키보드·스크린리더·포커스 복귀를 사람이 확인한 증거가 0건이다. CI에서 FE-GATE-009가 항상 실패하거나, 그 실패를 무시하는 운영이 굳어진다. 둘 중 어느 쪽인지는 확인하지 못했다 |
| 심각도·우선순위 | Medium · P2 — 문서는 한계를 정직하게 적었지만, 게이트 설계와 현재 상태가 서로 맞지 않는다 |
| 통제·증거 | M1 · E2(스크립트 실행) |
| 확실성과 남은 가정 | 스크립트 실패는 확인했다. CI가 이 게이트를 실제로 돌려 실패했는지는 CI 로그가 없어 확인하지 못했다(CI 영역) |
| 최소 개선 방향 | 릴리스 후보 하나로 10개 라우트 수동 검토를 한 번 수행한다. 또는 `review:a11y-manual`을 release 단계로 옮기고, merge 단계에는 기록 형식 검사만 둔다 |
| 비용·부작용 | 사람이 약 10개 화면을 검토해야 한다 |
| 완료 기준 | 서명된 기록 10건이 있거나, 게이트 단계를 조정하고 문서에 반영했다 |
| 검증 방법 | `pnpm review:a11y-manual` 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-07 실패 화면이 문의 식별자를 보여 주지 않고, 라우트 렌더 실패 화면에는 다음 행동이 없음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 24, 28 |
| 근거 | `app-router.tsx:92-108` `RouteFailureSurface`: StatusPage에 `supportReference`도 action도 없다. 그런데 문구는 "문제가 계속되면 운영 지원 참조 정보를 확인하세요"다(`catalog.ts:77-78`). 청크 실패 화면(`chunk-recovery-boundary.tsx:115-121`)도 "지원 참조 정보를 확인해 주세요"(`catalog.ts:99-100`)라고 하지만 reason은 `data-` 속성에만 있다. 문서 `routing-pages-and-patterns.md:280`은 "안전한 support surface와 trace/build ID를 표시한다"고 한다. `TerminalErrorSurface`(`async-surface.tsx:60-89`)는 `AppFailure.requestId/traceId`를 쓰지 않는다. 샘플의 contact-support 행동은 고정 문자열 `REFERENCE-STATUS-DEMO` 페이지로 이동한다(`use-reference-failure-action.ts:33-35`, `reference-resource-status-page.tsx:22`). `reportRenderFailure`는 void라 화면에 돌려줄 ID가 없다(`application-api.ts:62`). 부트 실패 화면만 build·release·지원 참조를 보여 준다(`boot-error-shell.tsx`) |
| 발생 조건 | 라우트 렌더 오류, 청크 복구 실패, contact-support 성격의 조회 실패 |
| 영향 | 사용자가 문의할 때 줄 식별자가 없다. 운영자는 신고를 서버 requestId·빌드와 연결할 수 없다. 렌더 실패 화면은 URL이 바뀌기 전까지 풀리지 않는데 재시도 버튼이 없다(registry의 RENDER_FAILURE action은 reload-once다) |
| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 "주요 진단 정보 부족"에 해당 |
| 통제·증거 | 문서 M1 / 구현 M0 · E1 |
| 확실성과 남은 가정 | 확인. 진단 이벤트에 상관관계 ID를 만드는 쪽은 영역 09·텔레메트리 소관이다 |
| 최소 개선 방향 | `RouteFailureSurface`와 `ChunkRecoverySurface`에 buildId와 짧은 incident ID를 `supportReference`로 표시하고, 같은 값을 진단 이벤트에 기록한다. `TerminalErrorSurface`는 requestId가 있으면 표시한다. contact-support로 이동할 때 식별자를 넘긴다. 렌더 실패 화면에 "한 번 새로고침" 버튼을 둔다 |
| 비용·부작용 | 진단 포트가 ID를 반환하도록 바뀐다(application 포트 변경) |
| 완료 기준 | 세 화면에 지원 참조 문자열이 보이고, 같은 값이 진단 이벤트에 있다 |
| 검증 방법 | render-boundary, chunk-recovery, async-surface 컴포넌트 테스트에 assert 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-08 뒤로 가기에서 스크롤을 복원하지 않고 해시 대상도 무시함(문서 계약과 다름)
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 24, 10 |
| 근거 | `app-router.tsx:166-180`은 pathname/search가 바뀔 때마다 `window.scrollTo(0,0)`을 하고, 이동 종류(POP)를 보지 않는다. src 전체에 `ScrollRestoration`·`history.scrollRestoration`이 없다. `PageHeader`도 h1에 `focus()`(preventScroll 없음)를 한다. 문서는 `routing-pages-and-patterns.md:82`(Data Mode를 고른 이유에 scroll restoration 포함), `:292`(back/forward는 저장한 scroll 복원), `:294`(hash target 처리)다. jsdom에서는 scroll을 건너뛰고(`app-router.tsx:170`) 관련 테스트도 없다 |
| 발생 조건 | 긴 목록 → 상세 → 뒤로 가기. `/page#section` 링크 |
| 영향 | 목록에서 보던 위치를 잃는다. 해시 링크가 맨 위로 간다. 데이터 영향은 없다 |
| 심각도·우선순위 | Low · P2 — 편의 문제다. 다만 문서가 약속한 동작이고 모든 목록 화면에 복제된다 |
| 통제·증거 | M1(문서만) · E1 |
| 확실성과 남은 가정 | 코드에서 확인했다. 브라우저 자동 복원이 effect보다 먼저 일어나도 effect가 다시 맨 위로 보낸다 |
| 최소 개선 방향 | AppShell에 `<ScrollRestoration />`을 두고, `RouteLifecycle`의 scrollTo는 PUSH/REPLACE일 때만 실행한다. 해시가 있으면 대상으로 이동하고 포커스한다 |
| 비용·부작용 | h1 포커스와 스크롤 복원의 순서를 맞춰야 한다(`focus({preventScroll:true})`) |
| 완료 기준 | 브라우저에서 list → detail → back 시 이전 scrollY가 복원된다 |
| 검증 방법 | Playwright e2e 1건(jsdom에서는 불가) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-09 목록 조회가 실패해도 결과 수 영역(role=status)이 "결과 확인 중"으로 남음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 1, 23 |
| 근거 | `reference-resource-page.tsx:38-40` `query.data ? ... : "결과 확인 중"`. `CollectionPage`는 이 값을 `role="status"`로 렌더한다(`page-templates.tsx:119-123`). probe: `SERVER_FAILURE`일 때 alert="요청을 완료하지 못했습니다. 다시 시도"와 status="결과 확인 중"이 함께 나왔다. idle 상태에서도 같다 |
| 발생 조건 | 목록 조회 실패 또는 비활성 |
| 영향 | 화면과 보조기술에 "확인 중"과 "실패"가 동시에 전달된다. 샘플이 `state.base`가 아니라 `data` 유무로 상태를 판단하는 패턴을 퍼뜨린다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E2(probe) |
| 확실성과 남은 가정 | 확인 |
| 최소 개선 방향 | 결과 수는 `query.state.base`가 success/empty일 때만 보여 준다 |
| 비용·부작용 | 한 줄 수정 |
| 완료 기준 | 실패·로딩·idle에서 결과 수 status가 없다 |
| 검증 방법 | `reference-page.test.tsx`에 실패 시 status 텍스트 assert |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-10 언어를 바꿔도 이미 표시된 폼 오류 문구는 이전 언어로 남음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23 |
| 근거 | `use-app-form.ts:185-197`, `:214-222`, `:231-237`이 번역을 끝낸 문자열을 state에 저장한다. probe: 검증 오류 뒤 en-US로 바꾸자 "Review the entered information. Name: 입력값이 너무 짧습니다."가 나왔다 |
| 발생 조건 | 오류가 표시된 상태에서 언어 전환 |
| 영향 | 제목은 영어, 필드 오류는 한국어로 섞인다. 다시 제출해야 갱신된다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E2(probe) |
| 확실성과 남은 가정 | 확인 |
| 최소 개선 방향 | 오류를 message key(또는 issue code)로 저장하고 렌더할 때 번역한다 |
| 비용·부작용 | `FieldErrors` 타입이 바뀌어 `ErrorSummary`·`TextField` 호출부를 함께 고쳐야 한다 |
| 완료 기준 | 언어 전환 즉시 표시 중인 오류 문구가 바뀐다 |
| 검증 방법 | `locale-platform.test.tsx`에 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-11 같은 인증 필요·권한 없음·없음 상태를 그리는 화면이 세 벌 있음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 23, 9, 22 |
| 근거 | 세 벌은 다음과 같다. ① 라우트 수준 StatusPage(`app-router.tsx:213-272`, `route.auth.*` 문구). ② 조회 실패 `TerminalErrorSurface`(`async-surface.tsx:60-89`, `error.*`). ③ 디자인 시스템 `AuthRequiredSurface`/`ForbiddenSurface`/`NotFoundSurface`/`AccessSurface`(`state-surfaces.tsx`, `common-patterns.tsx:126-139`, `access.*`). 같은 403이 샘플에서는 "이 작업을 수행할 권한이 없습니다.", 갤러리와 visual snapshot에서는 "403 · 권한 없음 / 접근할 수 없습니다."로 나온다. `state-surfaces-light.png`는 실제 흐름에서 쓰지 않는 쪽을 고정하고 있다. Q-6.8-10은 라우트 수준만 StatusPage로 통합했다 |
| 발생 조건 | 다운스트림이 권한·인증 화면을 만들 때 |
| 영향 | 어느 것을 쓸지 매번 골라야 한다. 문구·디자인을 바꾸려면 세 곳을 고쳐야 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E1 |
| 확실성과 남은 가정 | 확인 |
| 최소 개선 방향 | `AsyncSurface`의 AUTH_REQUIRED/FORBIDDEN/NOT_FOUND 분기를 `AccessSurface`로 렌더한다. 또는 `state-surfaces`를 공개 barrel에서 빼고 한 가지만 권장한다 |
| 비용·부작용 | visual baseline 갱신 |
| 완료 기준 | 같은 실패 종류가 조회·갤러리에서 같은 컴포넌트와 문구로 나온다 |
| 검증 방법 | async-surface 테스트, visual 갱신 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.8-10 일부 미해결 |
### 08-12 Pagination 페이지 링크가 Ctrl/Cmd/Shift 클릭까지 막아 새 탭 열기가 안 됨
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 24 |
| 근거 | `navigation.tsx:268-273`은 onClick에서 조건 없이 `preventDefault()`를 한다. 주석은 "href is for open-in-new-tab"이다. React Router `Link`는 사용자 onClick 뒤 `defaultPrevented`면 자체 처리도 건너뛴다(react-router 7.18.1 `handleClick`). 가운데 버튼(auxclick)은 열린다 |
| 발생 조건 | 수정키를 누른 채 페이지 번호 클릭 |
| 영향 | 새 탭 대신 현재 탭에서 페이지가 바뀐다. 주석과 동작이 다르다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E1 |
| 확실성과 남은 가정 | 확인 |
| 최소 개선 방향 | `button !== 0`이거나 수정키가 눌렸으면 return한 뒤 `preventDefault` |
| 비용·부작용 | 없음 |
| 완료 기준 | Ctrl 클릭에서 `onChange`가 호출되지 않는다 |
| 검증 방법 | `pagination.test.tsx`에 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 08-13 상세 경로 `:resourceId`가 정적 경로 `new`·`status`와 겹쳐 그 ID의 항목을 열 수 없음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 17, 1 |
| 근거 | `reference-feature-contract.ts:91`, `:104`, `:117`. ID 스키마는 1~120자 임의 문자열이다(`reference-schemas.ts:24-27`). React Router는 정적 세그먼트를 우선한다. 목록 링크는 `reference-resource-page.tsx:51`에 있다 |
| 발생 조건 | 서버 ID가 `new` 또는 `status`인 항목 |
| 영향 | 목록에서 누르면 생성 폼이나 상태 화면이 열린다. UUID 형태의 ID면 일어나지 않는다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E1 |
| 확실성과 남은 가정 | 라우팅 규칙으로 확인했다. 실제 서버 ID 형식은 repo 밖이다 |
| 최소 개선 방향 | 상세 경로를 `/…/items/:resourceId`처럼 분리하거나, ID 스키마에서 예약어를 거부한다 |
| 비용·부작용 | URL 변경 |
| 완료 기준 | ID `new`인 항목의 링크가 상세 화면을 연다 |
| 검증 방법 | 라우터 컴포넌트 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 — 화면 상태 모델 | 목표 M4 / 확인 M4(`AsyncState` 타입으로 불가능한 조합 차단) | E2 | 부분 충족 — 샘플이 `data` 유무로 상태를 판단(08-09), 경로 충돌(08-13) |
| 2 | 구조적 성숙도 | 적용 — presentation 경계 | 목표 M3 / 확인 M3(ESLint로 adapters·bootstrap·ports/out import 금지, tanstack은 `adapters/query`만 허용, templates는 application 금지) | E1 | 충족 — 영역 안에서 위반 없음 |
| 3 | 변경 용이성 | 적용 — 오류 종류·라우트 추가 | 목표 M3 / 확인 M1 | E2 | 부분 충족 — 오류 종류를 추가해도 문구 누락이 검출되지 않음(08-02) |
| 4 | 인지 부하 | 적용 — 대표 과제 수행(2.2) | — | E1 | 부분 충족 — 생성 파일 경유, descriptor와 runtime 분리, 문자열 규칙 키, 버튼 표시 조건 두 곳 |
| 5 | 위험 가시성 | 적용 — 실패·결과 불명 표시 | 목표 M2 / 확인 M2 | E2 | 부분 충족 — 결과 불명은 드러나지만 확인 경로가 없음(08-03) |
| 6 | 실패 성숙도 | 적용 — 32.2 실패 구분 | 목표 M2 / 조회 M2, 폼 M0 | E2 | 부분 충족 — 폼 실패 합침(08-01), 문구 누락(08-02), 결과 불명(08-03) |
| 7 | 운영 성숙도 | 다른 영역 — 텔레메트리(09). presentation은 route·render 이벤트만 보낸다 | — | — | 적용 제외 |
| 8 | 디버깅 가능성 | 적용 — 화면의 문의 식별자 | 목표 M2 / 확인 M0(부트 화면 제외) | E1 | 미충족 — 08-07 |
| 9 | 유지보수 성숙도 | 적용 | — | E1 | 부분 충족 — 상태 화면 세 벌(08-11), 문서와 구현 불일치(08-07, 08-08) |
| 10 | 테스트 성숙도 | 적용 — 컴포넌트·E2E·visual 검출력 | 목표 M3 / 확인 M3(주입 4건 모두 검출) | E2 | 부분 충족 — 폼 인증·권한 실패, 스크롤, 보호 화면 axe(08-05), 샘플 i18n, visual에 샘플 화면 없음 |
| 11 | 데이터 성숙도 | 적용 제외 — presentation은 저장을 소유하지 않는다. 폼 값은 URL·storage에 남기지 않는다(`form-foundation.test.tsx:140`) | — | E2 | 적용 제외 |
| 12 | 동시성 성숙도 | 적용 — 응답 순서·중복 제출·세션 전환 | 목표 M3 / 확인 M3 | E2 | 부분 충족 — 결과 불명 뒤 새 멱등 키(08-03). 여러 탭은 영역 02 |
| 13 | 확장성 | 다른 영역 — 기능 수 증가(extreme-scale 문서, 영역 09) | — | — | 적용 제외 |
| 14 | 성능 성숙도 | 적용 — 경로별 lazy | 목표 M3 / 확인 M2(정적) | E1 | 부분 충족 — lazy 분리는 확인. 번들 수치는 미검증(`check:bundle` 미실행) |
| 15 | 보안 성숙도 | 적용 — XSS·외부 URL·클라이언트 가드 | 목표 M3 / 확인 M3(ESLint FE-OC-019 주입 검출, React 19 `javascript:` 차단, CSP) | E2 | 충족 — 클라이언트 가드가 UX용이라는 선언과 서버 403 표시 테스트도 있다 |
| 16 | 의존성 성숙도 | 다른 영역 | — | — | 적용 제외 |
| 17 | API / Contract 성숙도 | 적용 — route codec·URL 계약 | 목표 M3 / 확인 M3(zod parse 뒤에만 사용, canonical redirect, loop guard) | E2 | 부분 충족 — 08-13, 정본과 다른 intent/key 수명(08-03) |
| 18 | 배포 성숙도 | 일부 적용 — 청크 실패 복구 | 목표 M3 / 확인 M3 | E2 | 충족(화면 쪽) — 6.8-1/2/7 수정과 테스트 확인. 릴리스 전환은 다른 영역 |
| 19 | 설정 성숙도 | 일부 적용 — `routerBasePath` | 목표 M2 / 확인 M2(router `Link` 사용) | E2 | 충족 — `design-system-links.test.tsx` |
| 20 | 개발자 경험 | 적용 — 샘플·템플릿 사용성 | — | E1 | 부분 충족 — 샘플이 i18n·실패 분기 방법을 보여 주지 않음(08-01, 08-04) |
| 21 | Guardrail 성숙도 | 적용 | 목표 M3 / 확인 M3(레이어·HTML) / M1(i18n 범위, 문구 누락, 수동 a11y) | E2 | 부분 충족 — 08-02, 08-04, 08-05, 08-06 |
| 22 | 추상화 성숙도 | 적용 — AsyncSurface·templates·useApplicationMutation | — | E1 | 충족 — 템플릿이 데이터를 가져오지 않고 슬롯만 가진다. `application-query.ts` 875줄의 bound/legacy 겸용은 학습 비용이 크다(관찰만 기록) |
| 23 | 일관성 | 적용 | — | E2 | 부분 충족 — 08-04, 08-10, 08-11. 같은 실패의 조회·폼 응답이 다름(08-01) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | — | E1 | 부분 충족 — 문구·문서가 약속한 동작을 구현하지 않음(08-07, 08-08, 08-12) |
| 25 | 조직 확장성 | 구조적 준비만 평가 — feature별 catalog·route 기여 지점은 있다 | — | E1 | 적용 제외(1인 관리 전제) |
| 26 | Ownership 성숙도 | 일부 — 수동 a11y 검토 책임자 없음 | — | E2 | 미검증 — 08-06 |
| 27 | 삭제 가능성 | 다른 영역 — reference feature 제거(영역 09) | — | — | 적용 제외 |
| 28 | 회복 가능성 | 적용 — 화면 오류 복구 | 목표 M2 / 확인 M2 | E2 | 부분 충족 — 청크 실패는 reload 버튼 있음. 렌더 실패는 URL 변경 전까지 행동이 없음(08-07) |
## 6. 미검증 목록
- **실제 스크린리더 발표.** 새로 마운트되는 `aria-live` 영역(LoadingSurface, EmptySurface)이 발표되는지, 라우트 이동 발표가 중복되는지, TextArea 글자 수 `<output>`이 입력마다 발표되는지 확인하지 않았다. → NVDA/VoiceOver 수동 검토(08-06과 함께)
- **Playwright E2E·visual·storybook.** 브라우저와 포트를 공유하는 환경이라 실행하지 않았다. 08-05, 08-08은 코드 정독 근거다. → `test:e2e`, `test:a11y`, `test:visual` 실행
- **번들 크기.** 경로별 lazy 분리는 정적으로 확인했다. `dist/`는 9/24 빌드이고, 새 빌드는 공유 경로에 쓰기 때문에 재측정하지 않았다. → `check:bundle`
- **HTTP 상태 → FailureKind·effect 분류.** 08-01과 08-03은 어댑터가 401/403을 NOT_APPLIED로, 타임아웃을 MAYBE_APPLIED로 분류한다는 전제 위에 있다. → 영역 03
- **세션 만료 시 폼 초안 폐기.** scope fence 재마운트로 작성 중 값이 확인 없이 사라진다. 의도된 데이터 폐기 정책인지 문서에서 찾지 못했다
- **FE-GATE-009의 실제 CI 결과.** 로그가 없다. → CI 영역
- **상세 URL 직접 접속의 정적 호스팅 fallback.** → 배포 영역
@@ -0,0 +1,313 @@
# 애플리케이션 코어·기능·조립 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `src/application/`(3.5k줄), `src/features/`(2.8k줄), `src/bootstrap/`(2.1k줄), `src/platform/`(2.6k줄), `src/apps/`, `src/contexts/`(각 0.05k줄). 약 10.9k줄. 생성기 `scripts/generate-product-feature-index.ts`, 제거 검증 `scripts/test-sample-removal.ts`, 이 영역을 검증하는 `tests/features/`, `tests/platform/`, `tests/unit/`의 application·bootstrap 관련 테스트, `tests/runtime-schema/runtime-config.test.ts`
> 영역 판정(35.8): **조건부 사용 가능** — 기능 1개(reference-feature를 교체하는 방식) 범위에서 사용 가능. 기능을 2개 이상 설치하는 용도는 09-01 해결 전 사용 보류. `VITE_PRODUCT_FEATURES`로 기능을 빼는 배포는 09-02 해결 전 사용 보류.
## 1. 결론
- **기능을 하나 더 설치하면 중앙 조립 파일 3곳이 타입 검사에서 깨진다(09-01, High).** 격리 worktree에서 local-draft 기능에 `feature-module.ts`만 추가하자 `installed-feature-adapters.ts`, `installed-feature-runtimes.tsx`, `installed-feature-contracts.ts`에서 tsc 오류 8건이 났다. "기능을 추가해도 이 composer는 바뀌지 않는다"는 주석(`src/features/installed-feature-adapters.ts:17-18`)은 기능이 1개일 때만 맞다. TS 규모 게이트는 실제 composer를 거치지 않는 합성 fixture로 측정한다.
- **부트 실패 경로가 원인을 잃는다.** 모듈 평가 단계의 throw(예: `VITE_PRODUCT_FEATURES` 오타)는 `boot()`의 try 밖에서 나서 정적 셸이 "불러오는 중"으로 멈춘다(09-03). 설정·매니페스트 외 오류는 `BOOT_CONFIG_FAILURE`로 잘못 표시되고 오류 객체는 콘솔·수집기 어디에도 남지 않는다(09-04).
- **`VITE_PRODUCT_FEATURES`는 소비자마다 다르게 적용된다(09-02).** 브라우저 번들은 이 값을 적용하지만 Node 빌드 스크립트(계약 세트 생성)와 라우터의 context 인덱스는 무시한다. 오타는 빌드를 통과하고 브라우저에서만 터진다.
- **IndexedDB 기능 경로는 조립까지 이어지지 않는다(09-05, 09-06).** 부트스트랩은 `http`·`telemetry`만 제공해서 IndexedDB를 쓰는 기능을 설치하면 부트가 `TypeError`로 실패한다. local-draft 샘플은 도메인 규칙(`createLocalDraft`)을 어느 쓰기 경로에서도 호출하지 않는다.
- **잘 막혀 있는 것:** 직전 리뷰 6.9-1~6.9-12는 현재 코드에서 모두 고쳐진 것을 확인했다. `AUTH_MODE=demo`는 스키마·프로필 생성·release admission 세 단계에서 staging/production 진입이 막힌다. 설정 문서는 strict 스키마로 오타 최상위 키를 거부하고, 부트 JSON은 크기·시간·타입 상한 안에서 읽는다.
- **미검증:** `test:sample-removal` 전체 실행, 부트 실패 경로의 실제 브라우저 동작, `check:architecture` 위반 주입(이 환경에서 pnpm 의존성 검사가 막혀 실행하지 못함).
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`, 2026-09-25 |
| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA, 정적 호스팅, SSR 없음. 여러 탭 지원 |
| 읽은 코드 | 범위 내 파일 전부. 부트 경로(`main.tsx` → `create-runtime-composition.ts` → `composition-root.ts` → `runtime-adapters.ts`), 설정·매니페스트 로더, 기능 설치 표면(`installed-*`), 두 샘플 기능 전체, `platform/release`·`platform/telemetry`·`platform/execution`. 연결 확인용으로 `src/contracts/{release-artifacts,product-features,deployment-admission,contract-set}.ts`, `src/presentation/routes/app-router.tsx`(context 라우팅 부분), `src/adapters/diagnostics/bounded-diagnostics.ts`, `src/adapters/http/http-execution-v3.ts`(intent 검증 부분) |
| 읽은 설정·스크립트 | `.dependency-cruiser.json`, `config/runtime/*.json`, `public/config.json`, `config/contracts/registry-governance.json`, `config/testing/risk-coverage.json`·`test-evidence.json`, `config/ci/gates.json`(스크립트 목록), `package.json` scripts, `scripts/{generate-product-feature-index,test-sample-removal,generate-runtime-config,check-release-admission,build-frontend,generate-contract-set}.ts`, `scripts/scale/collect-tsc-diagnostics.ts` |
| 실행한 테스트 | `node scripts/run-vitest.ts run tests/features tests/platform tests/runtime-schema/runtime-config.test.ts` + `tests/unit/`의 14개 파일(runtime-adapters, chunk-recovery(-runtime), application-boundary, product-features, installed-feature-messages, optional-runtime-host, read-bounded-boot-json, product-index-entrypoints, runtime-capability-snapshot, color-scheme, compatibility, release-coherence) → **62 files / 397 tests 통과** |
| 실험 1 (격리 worktree) | `src/features/local-draft-feature/`에 `feature-module.ts`·`context-routes.ts` 추가 → 생성기 실행 → `tsc -p tsconfig.app.json`: **3개 파일 8건 오류**. 같은 상태에서 `tests/unit/runtime-adapters.test.ts`: **15건 중 12건 실패**, 모두 `TypeError: Cannot read properties of undefined (reading 'get')`. 실험 후 worktree 삭제 |
| 실험 2 | `VITE_PRODUCT_FEATURES=none node -e "import('./src/features/installed-product-manifest.ts')…"` → Node에서는 `["reference-feature"]`, 계약 기여 1건 그대로 |
| 실험 3 | `VITE_PRODUCT_FEATURES=reference-featrue node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts` → 모듈 import 시점에 `installed-product-manifest.ts:43`에서 throw, 테스트 0건 실행 |
| 실험 4 | `tests/features/` 최상위 3개 파일 단독 실행 → 4건 통과. 이 파일들을 실행하는 package script·CI 게이트는 없음 |
| 확인하지 못한 것 | `test:sample-removal`(복제본에서 typecheck·전체 테스트·coverage·build를 돌리는 무거운 스크립트라 읽기로 대신함). `check:architecture` 위반 주입(worktree에서 `pnpm`의 의존성 상태 검사가 install을 시도하다 중단됨. 공유 `node_modules/.pnpm-workspace-state-v1.json`이 다른 에이전트의 `/tmp/security-followup-producer-*` 경로로 반복 갱신되는 중이었다). 부트 실패 경로의 실제 브라우저 동작(정적 추적과 vitest import 실험으로 대신함) |
| 직전 리뷰와 비교 | 6.9-1(reload 무한 반복), 6.9-5(킬스위치), 6.9-6(featureId 중복), 6.9-7(listener), 6.9-8(boot shell), 6.9-9(reload guard 통합), 6.9-10(safe error), 6.9-12(구조 정리)는 현재 코드를 읽어 고쳐진 것을 확인했다. 6.9-2·6.9-3·6.9-11(텔레메트리)은 수정 코드를 읽었고 해당 테스트가 통과했다. 6.9-8은 고쳐졌지만 모듈 평가 단계 실패가 남는다(09-03) |
## 3. 확인된 강점
1. **개발용 인증이 공개 환경에 못 들어간다.** 세 단계가 따로 막는다. 브라우저 스키마는 `APP_ENV`가 local/development가 아니면 `AUTH_MODE: demo`를 거부한다(`src/contracts/release-artifacts.ts:103-109`). 프로필 생성은 `APP_ENV`와 빌드 대상이 다르면 멈춘다(`scripts/generate-runtime-config.ts:47-51`). release admission(FE-GATE-027)은 staging/production에 demo·placeholder ID·비 HTTPS를 거부한다(`src/contracts/deployment-admission.ts:69-107`). 외부 인증 owner가 없으면 세션이 fail-closed다(`src/bootstrap/runtime-adapters.ts:304-309`).
2. **설정 문서 검증이 엄격하다.** 최상위 키 오타는 `.strict()`로 거부된다(`src/contracts/release-artifacts.ts:160-171`, 테스트 `tests/runtime-schema/runtime-config.test.ts:75`). 선택 기능 설정은 필요할 때만 요구한다(`TELEMETRY_ENDPOINT`는 `TELEMETRY_ENABLED`일 때만, `release-artifacts.ts:96-102`). 부트 JSON은 5초·64KB/1MB·`redirect: "error"`·fatal UTF-8 안에서 읽는다(`src/bootstrap/read-bounded-boot-json.ts:17-28`, `:85-131`).
3. **부트스트랩은 기능의 공개 표면만 조합한다(32.4).** `src/bootstrap/`의 기능 import는 `features/installed-*` 6개 파일뿐이다. 기능끼리 import는 `.dependency-cruiser.json`의 `features-do-not-import-other-features`가 막는다. 킬스위치로 끈 기능은 입력 자체가 만들어지지 않는다(`src/features/installed-feature-adapters.ts:26-37`, 테스트 `tests/unit/runtime-adapters.test.ts:284`).
4. **reload 반복이 구조적으로 막혀 있다.** boot mismatch와 chunk 실패가 같은 guard를 쓰고, 키와 무관하게 TTL 안 두 번째 reload를 거부하며, 마커가 실제로 저장된 경우에만 reload를 허용한다(`src/platform/release/release-mismatch-recovery.ts:114-165`). 마커는 탭별 sessionStorage다(`src/contracts/storage-keys.ts:61-69`).
5. **reference-feature의 쓰기 경로가 경계에서 검증된다.** create 명령은 HTTP 계약의 `inputValidator`(zod, trim·1..120자)를 통과해야 나가고(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:158-161`), KEYED 명령은 intent가 없으면 전송 전에 거부된다(`src/adapters/http/http-execution-v3.ts:375-378`). 재시도 예산 0과 결과 불명 처리가 계약에 적혀 있다(`reference-feature-contract-contribution.ts:37-47`, `:190-203`).
## 4. 발견 사항 (36.3)
### 09-01 기능을 2개 이상 설치하면 중앙 조립 파일이 타입 검사에 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 13, 20, 21, 22, 25, 10 |
| 근거 | 중앙 조립 파일이 설치 모듈 배열의 **유니언 원소**에 `flatMap`을 호출한다: `src/features/installed-feature-adapters.ts:8-10`, `src/features/installed-feature-runtimes.tsx:6-8`. 라우트 레지스트리는 `typeof PLATFORM_ROUTE_REGISTRY & InstalledFeatureContract["routes"]`로 캐스트한다(`src/features/installed-feature-contracts.ts:21-27`). 기능이 1개면 유니언이 아니라서 통과한다. **실험 1**: local-draft에 `feature-module.ts`만 추가하자 tsc 오류 8건(`installed-feature-adapters.ts:9,13,33`, `installed-feature-runtimes.tsx:7,14,24`, `installed-feature-contracts.ts:97,113`). TS 규모 게이트는 `installed-*`를 거치지 않는 합성 모듈을 컴파일한다(`scripts/scale/collect-tsc-diagnostics.ts:70-104`). `tests/contract/reusable-capability/feature-adapter-composition.test.ts`는 2개 기여를 런타임 함수로만 합친다 |
| 발생 조건 | 다운스트림이 기능을 하나 더 추가하거나, reference-feature를 남긴 채 첫 제품 기능을 추가 |
| 영향 | `check:types:app`(CI 필수 게이트)이 실패해서 머지할 수 없다. 해결하려면 중앙 composer의 제네릭 타입을 고쳐야 한다. 설계가 없애려던 "중앙 파일 수정"이 모든 다운스트림에서 첫 기능 추가 때 생긴다. `vite build`는 타입 검사를 안 하므로 런타임 동작 자체는 별개다 |
| 심각도·우선순위 | High · P1 — 템플릿의 주 사용 경로(기능 추가)가 필수 게이트에서 막힌다. 샘플을 복사한 모든 다운스트림에 복제된다. 선언된 규모 목표(context당 200 기능, app당 20 context)와 정면으로 어긋난다 |
| 통제·증거 | 목표 M3(다기능 typecheck fixture) / 확인 M0 · E3(격리 worktree 컴파일 실험) |
| 확실성과 남은 가정 | 오류 8건은 직접 재현했다. 두 번째 기능의 모양을 reference와 똑같이 맞추면 일부 오류가 줄 수는 있지만, featureId 리터럴이 다르면 `flatMap` 추론 실패는 남는다(오류 메시지가 첫 유니언 원소로 `U`를 고정함을 보여 준다) |
| 최소 개선 방향 | `flatMap` 대신 원소 타입을 넓힌 명시 루프(`const contributions: ContributionShape[] = []`)로 모으고, 라우트 레지스트리는 유니언의 교집합이 아니라 `UnionToIntersection` 또는 `Record<string, RouteDefinition>`으로 넓힌다. 기능 2개(모양이 다른) 설치 상태를 컴파일하는 typecheck fixture를 FE-GATE-003에 추가한다 |
| 비용·부작용 | 좁은 리터럴 타입 일부를 잃을 수 있다(`ROUTE_REGISTRY` 키 자동완성 등). fixture 1개와 CI 스크립트 1줄 추가 |
| 완료 기준 | reference-feature + 모양이 다른 두 번째 기능(예: local-draft)을 설치한 상태에서 `check:types:app` 통과 |
| 검증 방법 | 새 typecheck fixture가 CI에서 실행되고, composer를 원래대로 되돌리면 그 fixture가 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-02 `VITE_PRODUCT_FEATURES`가 번들·빌드 스크립트·라우터에서 다르게 적용된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(오타 경로·Node 무시) + 구조적 위험(계약 세트 불일치) |
| 관련 관점 | 19, 17, 18, 21, 24, 6 |
| 근거 | 선택값을 `import.meta.env`에서 모듈 평가 시점에 읽는다(`src/features/installed-product-manifest.ts:22-46`). Node에는 `import.meta.env`가 없어서 무시된다. **실험 2**: `VITE_PRODUCT_FEATURES=none`에서도 Node는 `["reference-feature"]`. 계약 세트 생성(`scripts/generate-contract-set.ts:10`)은 Node에서 전체 집합으로 매니페스트를 만들고, 브라우저는 좁힌 집합으로 검증한다(`src/bootstrap/load-release-manifest.ts:296-301`, `src/contracts/contract-set.ts:89-93`). 라우터는 선택을 거치지 않은 생성 context 인덱스를 쓴다(`src/apps/template-app.ts:10-14` → `src/presentation/routes/app-router.tsx:505`). "모든 registry가 선택을 따른다" 테스트는 `src/features/installed-*`만 검사한다(`tests/unit/product-features.test.ts:175-209`). **실험 3**: 오타는 import 시점 throw. 주석도 서로 다르다: `src/contracts/env.ts:59-61`은 "번들에 안 들어간다", `src/contracts/product-features.ts:10-13`은 "번들을 줄이지 않는다" |
| 발생 조건 | 배포 빌드에서 `VITE_PRODUCT_FEATURES`를 설정 |
| 영향 | (a) 오타 → 빌드·Node 검증은 통과하고 모든 사용자의 브라우저에서 부트가 멈춘다(09-03 경로). (b) 제외한 기능에 외부 계약 패키지가 있으면 매니페스트에는 들어가고 브라우저 기대값에는 없어서 매 부트가 `CONTRACT_SET_PACKAGE_UNEXPECTED`로 실패한다. (c) 제외한 기능의 URL은 context 라우트로 매칭된 뒤 `getRoute`에서 "Unregistered route" 오류 화면으로 간다(`app-router.tsx:308`, 정적 추적) |
| 심각도·우선순위 | Medium · P2 — 지금 저장소에서는 옵션을 안 쓰고 reference-feature가 TEMPLATE_FIXTURE라 (b)가 발동하지 않는다. 이 옵션을 쓰는 배포에는 P1 |
| 통제·증거 | 목표 M3 / 확인 M1(주석·단위 테스트만) · E2(실험 2·3) |
| 확실성과 남은 가정 | (a)·Node 무시는 재현했다. (b)는 코드 경로로 확정했지만 외부 패키지를 가진 기능이 없어 실행하지 못했다. (c)는 정적 추적만 했다 |
| 최소 개선 방향 | 선택을 빌드 입력 하나로 만든다. 생성기(`generate-product-feature-index.ts`)가 `VITE_PRODUCT_FEATURES`를 읽어 선택된 기능만 생성 인덱스에 넣으면, 번들·Node 스크립트·context 인덱스가 같은 집합을 보고 오타는 생성 단계에서 실패한다. 대안: Node 스크립트가 `process.env`로 같은 선택을 적용하고 build 첫 단계에서 값을 검증 |
| 비용·부작용 | 생성기 변경과 생성기 테스트 추가. 선택을 바꾸면 재생성이 필요해진다(이미 모든 진입점이 생성기를 먼저 돈다) |
| 완료 기준 | 잘못된 값은 `pnpm build` 첫 단계에서 실패한다. `VITE_PRODUCT_FEATURES=none` 빌드의 `contractSet`·생성 context 인덱스·번들에 제외 기능이 없다 |
| 검증 방법 | 생성기 단위 테스트 + 선택값을 준 빌드에서 매니페스트·dist 문자열 검사 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-03 모듈 평가 단계에서 실패하면 부트 셸이 "불러오는 중"으로 멈춘다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 8, 7 |
| 근거 | try/catch는 `boot()` 함수 안만 감싼다(`src/bootstrap/main.tsx:24-52`). 정적 import 그래프에서 모듈 최상위 코드가 throw하면 `main.tsx` 본문이 실행되지 않는다. 최상위 throw 지점: `installed-product-manifest.ts:43`(선택값), `installed-feature-messages.ts:39-41`(메시지 키 중복), `installed-feature-contracts.ts:21-82`(라우트·operation·schema 조합 검증), `installed-feature-runtimes.tsx:10-28`, `installed-contract-contributions.ts:15`. 정적 셸에는 타임아웃·`error` 핸들러가 없다(`index.html:10-22`). 실험 3으로 import 시점 throw를 확인했다 |
| 발생 조건 | 잘못된 `VITE_PRODUCT_FEATURES`, 기능 간 메시지 키·라우트 ID 중복, 조합 검증 실패가 있는 빌드가 배포됨 |
| 영향 | 모든 사용자가 `aria-busy` 로딩 표시만 무기한 본다. `BootErrorShell`·부트 진단 기록·release mismatch 자동 복구가 모두 건너뛰어진다. 원인은 브라우저 콘솔의 uncaught 오류뿐이다 |
| 심각도·우선순위 | Medium · P2 — 결정적 빌드 결함이라 배포 전 브라우저 스모크로 잡힐 수 있다. 다만 production 전용 빌드 변수(09-02)는 CI e2e 빌드와 다를 수 있다 |
| 통제·증거 | 목표 M2 / 확인 M0 · E2(import 실험) + E1(정적 추적) |
| 확실성과 남은 가정 | ES 모듈 평가 순서상 확정이다. 실제 브라우저 화면은 실행하지 않았다 |
| 최소 개선 방향 | `main.tsx`가 앱 그래프를 `await import("./create-runtime-composition.ts")`로 불러와 모듈 평가 실패도 같은 catch로 받게 한다. 또는 `index.html`에 작은 인라인 `error`/타임아웃 처리를 둔다 |
| 비용·부작용 | 동적 import 한 번이 추가된다(첫 로드에 청크 하나). 인라인 스크립트는 CSP 해시 관리가 필요하다 |
| 완료 기준 | 모듈 최상위 throw를 넣은 빌드에서 `BootErrorShell`이 뜬다 |
| 검증 방법 | 잘못된 `VITE_PRODUCT_FEATURES`로 빌드한 fixture를 Playwright로 열어 오류 화면 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.9-8 후속 — 정적 셸은 추가됐으나 모듈 평가 실패 경로가 남음 |
### 09-04 설정·매니페스트 외 부트 오류가 `BOOT_CONFIG_FAILURE`로 표시되고 원인이 버려진다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 6, 7, 24 |
| 근거 | 알 수 없는 오류는 `safe = { supportReference: "boot:unknown" }`만 넘긴다(`src/bootstrap/main.tsx:38-41`). `BootErrorShell`의 기본값이 `kind="BOOT_CONFIG_FAILURE"`, `code="BOOT_FAILED"`라서 설정 문제로 표시된다(`src/presentation/boundaries/boot-error-shell.tsx:12-19`). 오류 객체는 콘솔에 찍지 않고, `recordBootFailure`는 모듈 메모리에만 저장한다(`src/adapters/diagnostics/bounded-diagnostics.ts:80-106`, `getLastBootEvidence`를 부르는 src 코드 없음). 스키마 실패 시 어느 키가 틀렸는지(issue path)도 버린다(`src/bootstrap/load-runtime-config.ts:117-131`). **실험 1**에서 기능 조립 실패가 `TypeError`로 나는 것을 확인했다. 이 오류는 브라우저에서 이 경로로 간다 |
| 발생 조건 | 조립 단계 버그(09-05 같은 capability 누락, 기능 입력 생성 throw), 설정 파일 수기 편집 오류 |
| 영향 | 개발자·운영자가 "설정 실패"로 오진한다. 스택·메시지가 없어서 브레이크포인트 없이는 원인을 찾을 수 없다. 부트 실패율은 어떤 수집기에도 도달하지 않는다(설정 전이라 endpoint가 없음) |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없고 진단 비용이 모든 다운스트림에 반복된다 |
| 통제·증거 | 목표 M2 / 확인 M1 · E1 |
| 확실성과 남은 가정 | 코드 경로로 확정. 브라우저 확장 오류 리포터가 따로 있으면 일부 보완될 수 있다 |
| 최소 개선 방향 | 알 수 없는 오류에는 `kind: "BOOT_UNEXPECTED_FAILURE"`와 build ID를 넣는다. 개발 빌드에서는 `console.error(error)`를 남긴다. 스키마 실패의 issue path 목록(키 이름만, 값 제외)을 safe 필드에 싣는다 |
| 비용·부작용 | 키 이름 노출은 값이 아니므로 비밀 노출 위험이 낮다. i18n 문구 1~2개 추가 |
| 완료 기준 | 조립 단계 `TypeError`가 `BOOT_UNEXPECTED_FAILURE`로 표시되고, 개발 콘솔에 원 오류가 남는다. 오타 키 설정은 틀린 키 이름을 보여 준다 |
| 검증 방법 | `createRuntimeComposition`에 throw를 주입하는 컴포넌트 테스트, 잘못된 config.json으로 Playwright 부트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음(6.9-10은 값 누출 방향이었고 고쳐짐) |
### 09-05 IndexedDB capability가 부트스트랩에 없고, `needs`가 런타임에서 검사되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 2, 3, 5, 22, 20, 30.5 |
| 근거 | 부트스트랩이 기능에 주는 capability는 `http`, `telemetry` 둘뿐이다(`src/bootstrap/runtime-adapters.ts:560-566`). 타입은 `indexedDb`를 선언한다(`src/features/feature-adapter-contribution.ts:46-51`). 조합 함수는 기여의 `needs`를 실제 context와 대조하지 않는다(`feature-adapter-contribution.ts:161-190`). **실험 1**: local-draft 설치 시 `runtime-adapters.test.ts` 12/15 실패, `TypeError: Cannot read properties of undefined (reading 'get')`(`create-local-draft-feature-input.ts:29`). IndexedDB 저장소 조립(codec·migration·storage policy·scope token)의 유일한 예시는 브라우저 테스트 안에 있다(`tests/browser-capabilities/local-draft-composition.spec.ts:44-150`). 문서는 이 경로를 "두 번째 실행 가능한 contribution 모양"으로 소개한다(`docs/architecture/frontend-application-foundation.md:125-138`) |
| 발생 조건 | 다운스트림이 local-draft를 본떠 IndexedDB 기능을 설치 |
| 영향 | 부트가 실패하고 09-04 때문에 "설정 실패"로 보인다. 타입 검사는 09-01 때문에 `unknown`으로 무너져 누락을 잡지 못한다. 다운스트림은 production 조립 코드를 테스트 파일에서 옮겨 와 중앙 `runtime-adapters.ts`를 고쳐야 한다 |
| 심각도·우선순위 | Medium · P2 — 문서화된 선택 경로가 부트 실패로 끝나지만, 기본 구성(reference만 설치)에는 영향이 없다 |
| 통제·증거 | 목표 M3(타입) + M2(런타임 검사) / 확인 M1 · E3(실험 1) |
| 확실성과 남은 가정 | 재현했다. 09-01이 고쳐지면 타입 검사가 누락을 잡을 가능성이 높지만 확인하지 않았다 |
| 최소 개선 방향 | `composeFeatureAdapterInputs`가 `needs`의 각 capability가 context에 있는지 확인하고, 없으면 `feature <id> needs indexedDb, which the host did not provide`로 throw한다. IndexedDB provider 조립을 opt-in recipe(`recipes/`)나 `runtime-adapters.ts`의 주석 처리된 슬롯으로 제공한다 |
| 비용·부작용 | 런타임 검사 몇 줄. recipe는 codec·migration 결정을 다운스트림에 남겨야 한다 |
| 완료 기준 | capability를 안 준 채 local-draft를 설치하면 기능 ID와 빠진 capability 이름이 담긴 오류가 난다. 문서의 조립 예시가 src 또는 recipes에 있다 |
| 검증 방법 | `feature-adapter-composition.test.ts`에 capability 누락 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-06 local-draft 샘플의 도메인 규칙이 쓰기 경로에서 적용되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 1, 10, 24, 30.5 |
| 근거 | 규칙(trim, 빈 ID·제목 금지, 제목 160자·본문 100,000자 상한)은 `createLocalDraft`에 있다(`src/features/local-draft-feature/domain/local-draft.ts:7-21`). 이 함수는 src·tests 어디서도 호출되지 않는다. `saveDraft`는 `LocalDraft` 모양의 객체를 그대로 저장소에 넘긴다(`application/local-draft-api.ts:61-64` → `adapters/local-draft-indexeddb-store.ts:54-61`). `LocalDraft`는 브랜드 없는 plain 타입이라 리터럴 객체로 만들 수 있다(`local-draft.ts:1-5`) |
| 발생 조건 | 호출자가 `createLocalDraft`를 거치지 않고 `{ draftId, title, body }`를 만들어 저장 |
| 영향 | 빈 제목, 공백 ID, 상한 초과 본문이 IndexedDB에 저장된다. 이 샘플을 IndexedDB 기능 패턴으로 복사한 다운스트림은 "도메인 규칙이 있다"고 믿지만 실제로는 UI 검증에만 의존한다(1절 위험 신호) |
| 심각도·우선순위 | Medium · P2 — 로컬 데이터 한정이지만 샘플로 복제되는 패턴이다 |
| 통제·증거 | 목표 M2 / 확인 M0(규칙 코드는 있으나 적용 경로 없음) · E1 |
| 확실성과 남은 가정 | 코드 경로로 확정. 저장소 codec이 검증할 수는 있으나 codec은 src에 없다(테스트 codec은 타입만 확인) |
| 최소 개선 방향 | `saveDraft`에서 `createLocalDraft(command.draft)`를 호출하고 실패를 `VALIDATION_REJECTED` Result로 돌려준다. 또는 `LocalDraft`를 브랜드 타입으로 만들어 팩터리만 만들 수 있게 한다 |
| 비용·부작용 | 몇 줄. throw를 Result로 바꾸는 매핑 필요 |
| 완료 기준 | 빈 제목·상한 초과 draft 저장이 저장소 호출 없이 거부된다 |
| 검증 방법 | local-draft API 단위 테스트(경계값: 160/161자, 공백 ID) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-07 기능 추가·제거가 중앙 정책 파일 여러 곳을 요구하고, 제거 검증은 샘플 전용·일부 게이트만 돈다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 3, 27, 4, 20, 25, 21 |
| 근거 | **제거**(`scripts/test-sample-removal.ts`가 하는 일): 디렉터리 4개(`src/features/reference-feature`, `tests/features/reference-feature`, `src/contexts/reference-context`, `tests/mocks`) + 개별 테스트 4개 + typecheck fixture 16개 삭제(`:41-67`), 생성 인덱스 재생성(`:131`), runtime 프로필 4개(`:138-161`), `risk-coverage.json`의 목록 4개·baseline 숫자(`:163-188`), `test-evidence.json`(`:190-216`), `registry-governance.json`(`:218-252`), `package.json` 스크립트 12개(`:254-275`), CI 계약·workflow 재생성(`:276-285`). 즉 중앙 정책 파일 8종 이상. 이후 실행하는 게이트는 typecheck·architecture·registry 구조(`--no-baseline`)·test:all·coverage·evidence source·check:ci·home smoke·build뿐이다(`:302-335`). `lint`, baseline 포함 `check:registries`, `check:i18n`, e2e는 돌지 않는다. residue 검사는 `src`·`tests`만 본다(`:287-300`). **추가**: API operation·schema가 있는 새 기능은 `registry-governance.json`의 FE-REG-API·FE-REG-SCHEMA `consumerDirectories`에 디렉터리를 넣어야 `check:registries`가 통과한다(`scripts/check-registries.ts:548-583`, 현재 reference 디렉터리만 등록). 생성기는 `feature-module.ts`가 없는 기능 디렉터리를 경고 없이 건너뛴다(`scripts/generate-product-feature-index.ts:249-256`, local-draft가 실제로 이렇게 빠져 있다). 새 기능 recipe 문서는 이 파일들을 언급하지 않는다(`docs/architecture/frontend-ports-adapters-and-boundaries.md:1040-1120`). reference README의 설치 지점 이름도 실제와 다르다(`src/features/reference-feature/README.md:48`은 `REFERENCE_FEATURE_RUNTIME_CONTRIBUTION`, 실제 모듈은 `REFERENCE_FEATURE_RUNTIME_DESCRIPTOR`) |
| 발생 조건 | 다운스트림이 기능을 추가하거나 reference가 아닌 기능을 제거 |
| 영향 | 기능마다 공유 JSON 파일을 함께 수정해서 여러 팀이면 충돌이 반복된다. reference가 아닌 기능 제거는 스크립트가 없어 수동 절차를 재구성해야 한다. 파일 이름 오타는 기능이 조용히 빠지는 것으로 끝난다 |
| 심각도·우선순위 | Medium · P2 — 변경 비용이 기능마다 반복된다. 안전 문제는 아니다 |
| 통제·증거 | 목표 M3(추가·제거 절차 문서 + 일반화된 검증) / 확인 샘플 제거 M3(스크립트), 일반 기능 M1 · E1(`test:sample-removal` 미실행) |
| 확실성과 남은 가정 | 목록은 스크립트·설정을 읽어 확정. registry baseline 승인이 추가에도 필요한지는 확인하지 않았다 |
| 최소 개선 방향 | (1) 생성기가 `src/features/*/`에 `feature-module.ts`가 없으면 명시적 opt-out 표시(예: `NOT_INSTALLED.md`)가 없는 한 실패. (2) `consumerDirectories`를 기능 디렉터리 glob(`src/features/*/adapters`)으로 바꿔 기능별 등록을 없앤다. (3) recipe 문서에 "추가 시 바꾸는 파일" 표를 둔다. (4) 제거 스크립트가 기능 ID를 인자로 받게 한다 |
| 비용·부작용 | glob은 검출 범위를 넓혀 오탐이 늘 수 있다. 제거 스크립트 일반화는 중간 규모 작업 |
| 완료 기준 | 새 기능 추가 시 기능 디렉터리 밖에서 바꾸는 파일이 생성 인덱스(자동)와 선택적 runtime 프로필뿐이다. 이름 오타가 생성 단계에서 실패한다 |
| 검증 방법 | 두 번째 샘플 기능을 추가하는 fixture에서 `check:registries`·`check:types`·생성기가 추가 수정 없이 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-08 local-draft가 삭제 후 재생성 시 revision 재사용(ABA)을 막지 않아 다른 탭의 오래된 저장이 새 초안을 덮는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 12, 11, 1 |
| 근거 | 포트 계약이 경고한다: `remove`는 tombstone 없이 지우고 다음 생성은 revision 1부터 시작하므로, 삭제 전 revision N을 쥔 작성자가 재생성된 레코드를 덮을 수 있다. 호출자가 소유한 값과 짝지으라고 권한다(`src/application/ports/browser-file-storage/indexeddb-port.ts:72-80`). local-draft는 `expectedRevision`만 쓴다(`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts:55-61`, `application/local-draft-api.ts:10-20`) |
| 발생 조건 | 같은 `draftId`를 재사용하는 설계(예: 화면당 고정 ID). 탭 A가 revision 1을 쥔 상태에서 탭 B가 삭제 후 같은 ID로 새로 저장하고, 탭 A가 저장 |
| 영향 | 탭 B의 새 초안이 탭 A의 오래된 내용으로 조용히 덮인다. 일반 경쟁(둘 다 revision 1에서 저장)은 CAS가 `CONFLICT`로 막는다 |
| 심각도·우선순위 | Low · P2 — 조건이 좁고 로컬 초안 한 건이지만, 샘플이 포트 경고를 따르지 않는 모습으로 복제된다 |
| 통제·증거 | 목표 M2 / 확인 M1(포트 문서) · E1 |
| 확실성과 남은 가정 | 포트 문서와 코드로 확정. draftId를 초안마다 새로 만들면 발생하지 않는다. 실제 IndexedDB로 재현하지 않았다 |
| 최소 개선 방향 | `LocalDraft`에 생성 시 만든 `createdAt` 또는 무작위 `generation` 값을 넣고 저장 시 함께 비교하거나, 샘플 주석에 "draftId는 초안마다 새로 만든다"는 전제를 적는다 |
| 비용·부작용 | 필드 1개 추가와 비교 로직. 주석만 두면 비용 없음 |
| 완료 기준 | 삭제·재생성 후 오래된 revision 저장이 `CONFLICT`가 된다(또는 전제가 샘플에 명시됨) |
| 검증 방법 | fake repository로 삭제→재생성→오래된 저장 순서 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-09 `FEATURE_OVERRIDES` 키 오타가 진단 없이 무시되어 킬스위치가 조용히 작동하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 19, 7, 8 |
| 근거 | 설치되지 않은 ID는 의도적으로 "inert"다(`src/contracts/release-artifacts.ts:65-80`). `resolveProductFeatures`는 모르는 키를 무시하고(`src/contracts/product-features.ts:110-129`) 부트스트랩도 경고를 남기지 않는다(`src/bootstrap/runtime-adapters.ts:437-444`). 설정 변경은 새 부트부터 적용된다(`src/bootstrap/load-runtime-config.ts:152-153`) |
| 발생 조건 | 장애 중 운영자가 `"reference-featrue": "DISABLED"`처럼 오타로 기능을 끔 |
| 영향 | 기능이 계속 ACTIVE다. 운영자는 platform overview 화면을 봐야만 알 수 있다 |
| 심각도·우선순위 | Low · P2 — "여러 빌드가 한 문서를 공유한다"는 명시된 이유가 있어 검출 범위는 선언돼 있다. 다만 긴급 조치 도구의 조용한 실패다 |
| 통제·증거 | 목표 M2 / 확인 M1 · E1 |
| 확실성과 남은 가정 | 코드로 확정 |
| 최소 개선 방향 | 부트 시 이 빌드가 모르는 override 키마다 `feature.override.unknown` 진단을 1회 기록한다. release admission이 대상 빌드의 compiled ID와 대조해 경고한다 |
| 비용·부작용 | 진단 이벤트 1종. 공유 문서 운영과 충돌하지 않는다 |
| 완료 기준 | 오타 키가 진단·admission 기록에 나타난다 |
| 검증 방법 | runtime-adapters 단위 테스트에 모르는 키 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-10 부트 실패 화면에 다시 시도 동작이 없고 설정·매니페스트는 한 번만 요청한다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 6, 28, 32.2 |
| 근거 | `BootErrorShell`은 제목·코드·지원 참조만 보여 주고 행동이 없다(`src/presentation/boundaries/boot-error-shell.tsx:20-53`, 문구 `src/presentation/i18n/catalog.ts:146-152`). 부트 JSON 읽기는 1회 시도다(`src/bootstrap/read-bounded-boot-json.ts:82-96`). 자동 reload는 release mismatch만 대상이다(`src/bootstrap/boot-release-recovery.ts:18-26`) |
| 발생 조건 | 일시적 네트워크 오류로 `CONFIG_FETCH_FAILED`·`CONFIG_TIMEOUT` |
| 영향 | 사용자는 `BOOT_CONFIG_FAILURE / CONFIG_TIMEOUT` 코드만 보고 새로고침하라는 안내를 받지 못한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M2 / 확인 M1 · E1 |
| 확실성과 남은 가정 | 코드로 확정. UX 결정일 수 있다 |
| 최소 개선 방향 | 네트워크 계열 코드일 때 "다시 시도" 버튼(`location.reload()`)과 안내 문구를 둔다. 자동 재시도는 두지 않는다(reload 반복 방지 규칙 유지) |
| 비용·부작용 | 문구 2개·버튼 1개 |
| 완료 기준 | FETCH/TIMEOUT 실패 화면에 다시 시도 버튼이 있다 |
| 검증 방법 | `render-boundary.test.tsx`에 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-11 `tests/features/` 최상위 테스트 3개가 어떤 스크립트·CI 게이트에서도 실행되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21 |
| 근거 | `test:reference-feature`는 `tests/features/reference-feature`만(`package.json:79`), `test:coverage`도 같은 하위 폴더만 포함한다(`package.json:81`). `tests/features/feature-installation-surface.test.ts`, `feature-module.test.ts`, `product-features-scale.test.ts`는 어느 스크립트에도 없다(`config/ci/gates.json` 스크립트 목록 확인). 단독 실행 시 4건 통과(실험 4). `defineFeatureModule`의 id 불일치 throw(`src/features/feature-module.ts:75-79`)를 검사하는 테스트는 없다. 참고로 `tests/architecture/`도 `test:platform`·`check:topology`·`check:observability`에서만 돌고 이 셋은 CI 게이트에 없다(다른 영역 확인 필요) |
| 발생 조건 | 해당 테스트가 지키는 규칙(중앙 파일에 reference 전용 import 금지 등)을 어기는 변경 |
| 영향 | 회귀가 CI에서 검출되지 않는다 |
| 심각도·우선순위 | Low · P3 — 같은 규칙 일부를 `tests/unit/product-features.test.ts`가 CI에서 다룬다 |
| 통제·증거 | 목표 M3 / 확인 M1 · E2(단독 실행) |
| 확실성과 남은 가정 | 스크립트·게이트 목록으로 확정 |
| 최소 개선 방향 | `test:reference-feature`·`test:coverage`의 경로를 `tests/features`로 넓히거나 세 파일을 `tests/unit`으로 옮긴다. id 불일치 케이스를 추가한다 |
| 비용·부작용 | 스크립트 1~2줄. `test-sample-removal.ts:271-272`의 경로 치환도 함께 수정 |
| 완료 기준 | 세 파일이 CI 게이트에서 실행된다 |
| 검증 방법 | CI 로그 또는 junit 결과에서 파일 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 09-12 local-draft의 테스트 fixture 복사본이 src와 갈라졌고, 경계 테스트는 복사본을 검사한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 10, 23 |
| 근거 | `tests/contract/consumer-experience/fixtures/local-draft-feature.ts`는 저장소 실패를 `BrowserDataResult`로 그대로 돌려주고, src 버전은 `AppFailure`로 변환한다(`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts:19-43`). "기능 코드에 native IndexedDB가 없다" 테스트는 fixture 파일을 읽는다(`tests/contract/consumer-experience/indexeddb-local-draft.test.ts:136-160`). 문서의 측정값(LOC 97, import 1)도 fixture 기준이다(`docs/architecture/capability-consumer-experience.md:60-100`) |
| 발생 조건 | src local-draft가 바뀌거나 금지 API를 쓰게 됨 |
| 영향 | 문서·테스트가 말하는 대상과 실제 샘플이 다르다. 소유자 전제상 "갈라진 중복 복사본" |
| 심각도·우선순위 | Low · P3 — native IDB 전역 사용은 ESLint 경계 검사가 따로 막는다(`scripts/check-browser-file-storage-boundaries.ts`) |
| 통제·증거 | 목표 M3 / 확인 M1 · E1 |
| 확실성과 남은 가정 | 파일 비교로 확정 |
| 최소 개선 방향 | fixture를 지우고 테스트가 src의 local-draft를 import·검사하게 한다 |
| 비용·부작용 | 테스트 기대값이 `AppFailure` 기준으로 바뀐다 |
| 완료 기준 | local-draft 구현이 한 벌이다 |
| 검증 방법 | `grep`으로 중복 정의 0건, 테스트 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 — 두 샘플의 생성·변경 경로 | M2 / reference M3(계약 검증기+KEYED 거부), local-draft M0 | E1, E2 | 부분 충족 — local-draft 도메인 규칙 미적용(09-06). reference는 조회 모델이라 상태 전이가 없음 |
| 2 | 구조적 성숙도 | 적용 | M3 / M2 — bootstrap이 `installed-*`만 import하는 것은 지켜지나 이를 강제하는 규칙은 없음 | E1 | 부분 충족 — 32.4 준수. bootstrap→기능 내부 import 금지 규칙 부재, capability 공급이 계약과 불일치(09-05) |
| 3 | 변경 용이성 | 적용 — 기능 추가·제거 추적 | M3 / M0(2개째 기능 추가 시 게이트 실패) | E3 | 미충족 — 09-01, 09-07 |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | 부분 충족 — 생성기 파일명 규약, 모듈 augmentation 2종, `consumerDirectories` 등 숨은 전제(09-07). README 이름 불일치 |
| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | 부분 충족 — HTTP 계약에 deadline·재시도·트래픽이 드러남. `needs` 선언은 있으나 런타임 확인 없음(09-05) |
| 6 | 실패 성숙도 | 적용 — 부트 실패 | M2 / M1 | E1, E2 | 부분 충족 — reload 반복 차단은 좋음. 모듈 평가 실패 무한 로딩(09-03), 재시도 동작 없음(09-10) |
| 7 | 운영 성숙도 | 부분 적용 — SLO는 템플릿 범위 밖 | M1 / M1 | E1 | 부분 충족 — 부트 실패가 수집기에 도달하지 않음(09-04). 킬스위치 오타 무진단(09-09) |
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1 | 미충족 — 알 수 없는 부트 오류 원인 폐기·오분류(09-04) |
| 9 | 유지보수 성숙도 | 적용 | M2 / M2 | E1 | 부분 충족 — 직전 리뷰의 중복(reload guard, 텔레메트리 전송)은 합쳐짐. local-draft fixture 복사본(09-12), 주석 불일치(`env.ts:59-61`) |
| 10 | 테스트 성숙도 | 적용 — 이 영역 테스트 검출력 | M3 / M2 | E2(62 files/397 tests 통과) | 부분 충족 — 킬스위치·reload·demo 거부는 테스트가 분기를 직접 고정. 다기능 typecheck 없음(09-01), 고아 테스트(09-11), 부트 실패 e2e 없음, staging+demo 거부 케이스 없음 |
| 11 | 데이터 성숙도 | 부분 적용 — 로컬 IndexedDB 샘플만 | M2 / M1 | E1 | 부분 충족 — local-draft ABA(09-08). 보관·로그아웃 정책은 src 샘플에 없고 테스트에만 있음 |
| 12 | 동시성 성숙도 | 적용 — 여러 탭 | M2 / M2 | E1 | 부분 충족 — reload 마커는 탭별 sessionStorage, CAS로 일반 경쟁 차단. 삭제 후 재생성 ABA(09-08) |
| 13 | 확장성 | 적용 — 기능 수 증가 축 | M3 / M0 | E3 | 미충족 — 실제 composer는 기능 2개에서 타입 실패. TS 규모 게이트가 합성 fixture로 실제 조립을 우회(09-01). 부트 비용은 기능당 계약·스키마·메시지 eager, 페이지 lazy(측정 안 함) |
| 14 | 성능 성숙도 | 다른 영역 — 번들·성능 | — | 미확인 | 미검증 — 부트는 설정(≤5s)→매니페스트(≤5s) 순차. 실제 시간 측정 안 함 |
| 15 | 보안 성숙도 | 적용 — demo 인증, route policy | M3 / M3 | E1, E2 | 부분 충족 — demo는 세 단계에서 공개 환경 차단. route policy는 UX용이고 서버 인가가 기준이라는 전제와 일치(자격 증명 부착은 fail-closed). 배포 경로가 admission을 건너뛰면 막을 수단 없음(배포 영역) |
| 16 | 의존성 성숙도 | 다른 영역 | — | — | 적용 제외 — 이 영역 고유 의존성 없음 |
| 17 | API / Contract 성숙도 | 적용 — 설정·매니페스트·기능 계약 | M3 / M2 | E1, E2 | 부분 충족 — 계약 세트 기대값이 Node와 브라우저에서 다름(09-02) |
| 18 | 배포 성숙도 | 부분 적용 | M3 / M2 | E1 | 부분 충족 — rolling mismatch 1회 reload. 빌드 선택값 불일치(09-02) |
| 19 | 설정 성숙도 | 적용 — `public/config.json` | M3 / M3(최상위 키), M1(override 키) | E2 | 부분 충족 — strict 스키마·조합 검증·선택 기능 비요구는 좋음. override 오타 무진단(09-09), 스키마 실패 위치 미표시(09-04), 빌드 변수 검증 시점(09-02) |
| 20 | 개발자 경험 | 적용 — 기능 추가 | M2 / M1 | E3 | 미충족 — 첫 추가 기능에서 타입 게이트 실패, 조립 오류가 설정 실패로 보임(09-01, 09-04, 09-05) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M2 | E1 | 부분 충족 — 기능 간 import·계층 규칙은 강제. 생성기의 조용한 skip, 다기능 typecheck 부재, 고아 테스트(09-07, 09-01, 09-11) |
| 22 | 추상화 성숙도 | 적용 — `FeatureModule` 제네릭·contribution | M2 / M1 | E3 | 미충족 — 6개 타입 파라미터와 유니언 추론에 기대는 조립이 2개째 기능에서 무너짐(09-01) |
| 23 | 일관성 | 적용 | M2 / M2 | E1 | 부분 충족 — reference는 mapper에서 도메인 팩터리를 쓰고 local-draft는 안 씀. 주석·README 불일치 |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M1 | E1 | 부분 충족 — `LocalDraft`가 검증된 값처럼 보임(09-06). `INSTALLED_*`·`EXPECTED_CONTRACT_SET_PACKAGES`가 실행 환경마다 다른 값(09-02). 알 수 없는 오류가 `BOOT_CONFIG_FAILURE`(09-04) |
| 25 | 조직 확장성 | 구조적 준비만 평가(전제) | M2 / M1 | E1 | 부분 충족 — 기능마다 공유 JSON 수정 필요(09-07) |
| 26 | Ownership 성숙도 | 다른 영역 | — | — | 적용 제외 — 기능 owner 필드는 있음(`reference-mapper.ts:114`), 운영 책임은 문서 영역 |
| 27 | 삭제 가능성 | 적용 — sample removal | M3 / M3(reference 한정), M1(일반 기능) | E1(스크립트 읽기, 미실행) | 부분 충족 — 제거 스크립트가 중앙 파일 8종을 정리하고 residue를 검사. 일반 기능용 절차 없음, 일부 게이트만 실행(09-07) |
| 28 | 회복 가능성 | 부분 적용 — 부트·청크 복구 | M2 / M2 | E1, E2 | 부분 충족 — reload-once와 fail-closed 마커. 부트 실패 후 사용자 복구 동작 없음(09-10) |
## 6. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| `test:sample-removal` 전체 통과 여부 | 복제본에서 typecheck·test:all·coverage·build를 돌려 오래 걸리고, 공유 워킹트리에 `.tmp/`를 만든다 | 격리 환경에서 `corepack pnpm test:sample-removal` 실행, junit `artifacts/tests/sample-removal.xml` 확인 |
| bootstrap → 기능 내부 import를 넣었을 때 `check:architecture` 결과 | worktree에서 pnpm 의존성 검사가 install을 시도하다 중단됨(공유 `node_modules` 상태 파일이 다른 에이전트 경로로 바뀌어 있음). 규칙 파일상 막는 규칙은 없음 | 정상 pnpm 환경에서 위반 import 1줄 주입 후 `check:architecture` |
| 모듈 평가 실패·알 수 없는 부트 오류의 실제 브라우저 화면(09-03, 09-04) | 브라우저 실행 안 함 | 잘못된 `VITE_PRODUCT_FEATURES`로 빌드 후 Playwright로 열기 |
| 제외 기능 URL의 화면(09-02 (c)) | 정적 추적만 함 | `VITE_PRODUCT_FEATURES=none` 빌드에서 `/examples/reference-resources` 접속 |
| 외부 계약 패키지를 가진 기능 + 선택값 조합의 `CONTRACT_SET_PACKAGE_UNEXPECTED`(09-02 (b)) | 저장소에 외부 패키지를 가진 기능이 없음 | EXTERNAL_PACKAGE 기여를 가진 fixture 기능 2개로 빌드·부트 |
| 부트 시간과 기능 수에 따른 부트 비용 | 성능 측정 범위 밖 | 기능 N개 fixture로 부트 시간·번들 측정(성능 영역) |
| 두 탭 local-draft ABA의 실제 IndexedDB 재현(09-08) | 포트 문서와 코드로 판단 | 브라우저 두 컨텍스트로 삭제→재생성→오래된 저장 |
@@ -0,0 +1,234 @@
# 테스트 체계: 빠른 계층(Node/jsdom) 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `tests/unit/`(140파일, 60,361줄 — 표본), `tests/component/`(5,812줄), `tests/integration/`(4,481줄), `tests/contract/`(716줄), `tests/runtime-schema/`(629줄), `tests/features/`(1,956줄), `tests/platform/`(2,786줄), `tests/recipes/`(963줄), `tests/helpers/`·`tests/mocks/`·`tests/support/`·`tests/fixtures/`(약 3,300줄), `tests/setup.ts`, `vitest.config.ts`, `scripts/run-vitest.ts`, `config/testing/*.json`, `scripts/check-test-evidence.ts`, `scripts/check-risk-coverage.ts`와 `scripts/lib/risk-coverage.ts`, `docs/testing/*` — 합계 약 81k줄
> 영역 판정(35.8): **조건부 사용 가능** — 조건: 10-01을 고치기 전에는 깨끗한 체크아웃(새 clone, CI 러너)에서 `test:unit`·`test:all`이 통과하지 않는다. IndexedDB 테스트 대역의 한계(05-08)를 알고 쓴다.
## 1. 결론
- **빠른 테스트의 검출력은 표본 규칙에서 높다.** 고위험 규칙 8개를 일부러 바꿔 보는 실험(변이 실험)에서 7개를 테스트가 잡았다. 직전 리뷰 수정(6.3-1 `..` 경로, 6.7-1 멱등 키, Q-6.9-9 reload guard, Q-6.3-11 401 복구)의 회귀 테스트도 모두 동작했다. 순서를 섞어 3회 돌렸을 때 순서 의존 실패는 없었다.
- **깨끗한 체크아웃에서 `test:unit`이 실패한다(10-01, High).** `tests/unit/removal-fixture.test.ts:125`가 gitignore된 `artifacts/release/*` 같은 로컬 생성물이 있어야 통과한다. 작업 트리에는 그 파일이 있어서 통과하고, 새 worktree에서는 매번 실패한다. FE-GATE-005 CI job은 이 파일을 만들지 않는다.
- **샘플 기능 테스트 하나가 부하에서 흔들린다(10-02).** `reference-page.test.tsx:138`의 첫 `findByRole`은 기본 1초 안에 lazy route를 불러와야 하는데, 혼자 돌려도 804ms가 걸린다. 66~81개 파일을 함께 돌린 실행 중 6회 실패했다. 실패 메시지는 "heading을 못 찾음"이라 시간 초과라는 원인을 가린다.
- **V3 HTTP 실행기의 재시도 의미 연결은 테스트가 없다(10-03).** 실행기가 계약의 `retrySemantics`를 무시하도록 바꿔도 관련 75개 파일이 모두 통과했다. 규칙은 순수 함수 단위 테스트에만 고정돼 있고, fixture의 KEYED 명령은 항상 `retryBudget: 0`이다.
- **커버리지 게이트는 17개 모듈의 현재값 ratchet(되돌아가지 못하게 현재 수치로 고정한 하한)과 전체 평균이다(10-04).** 문서의 위험별 목표(HTTP adapter 90% 이상 등)와 "19개 모듈·80개 threshold" 주장과 다르다. live V3 재시도 모듈은 빠지고 legacy V2 모듈이 들어가 있다.
- 미검증: main 트리 전체 `test:unit`·`test:coverage` 결과와 실제 커버리지 수치는 오케스트레이터 실행에 맡겼다. CI가 이 repo에서 돌지 않아(12-01) CI 러너 조건의 실행 시간·flaky는 보지 못했다.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`, 미커밋 `CLAUDE.md`·가이드 문서만 있음 |
| 목적·실행 구성 | 템플릿. 빠른 계층은 Vitest 4.1.10, 기본 Node 환경, component 테스트는 파일별 `@vitest-environment jsdom`(31/31) |
| 읽은 설정·도구 | `vitest.config.ts` 전체, `scripts/run-vitest.ts` 전체, `tests/setup.ts`, `config/testing/risk-coverage.json`·`test-evidence.json`, `scripts/check-test-evidence.ts` 전체, `scripts/check-risk-coverage.ts`와 `scripts/lib/risk-coverage.ts`의 평가부(`:315-331`, `:708-901`), `package.json` 테스트 스크립트, `config/ci/gates.json`의 게이트→명령 대응, `.gitea/workflows/quality-gates.yml` merge job |
| 읽은 테스트 자산 | `tests/helpers/memory-indexeddb.ts` 전체, `create-test-application.ts`, `runtime-capabilities-stub.ts`, `tests/mocks/server.ts`·`scenarios/catalog.ts` 앞부분, `tests/support/runtime/determinism.ts`, 표본 테스트 약 20개(http-execution-v3, service-worker-runtime, reference-page, app-shell, removal-fixture, risk-coverage, v8-coverage-counter-semantics, indexeddb-local-draft, http-scenario-catalog 등) |
| 전 범위 grep | fake timer·전역 stub 복원, skip 변형, retry 설정, mock 호출 순서 단언, snapshot, 실제 시간 대기, 자식 프로세스 사용, MSW 사용처 |
| main 트리 실행 | `node scripts/run-vitest.ts run tests/component` → 31파일 182개 통과, 7.0s · `run tests/integration` → 12파일 151개 통과, 11.9s · 프로세스를 띄우는 unit 7파일 → 476개 통과, 4.2s |
| worktree 실험 | `git worktree add --detach <scratchpad>/10/wt HEAD` + `node_modules` 심볼릭 링크(= 새 clone과 같은 상태). ① 생성 전 `vitest run tests/component/router.test.tsx` → import 해석 실패 ② `vitest list` → 292파일 수집 ③ 순서 섞기: 비-unit 94파일 × seed 2개 전부 통과(15.5s/18.1s), unit 140파일 seed 7 → 139 통과·1 실패(10.2s) ④ `removal-fixture.test.ts` 단독 → 같은 실패 ⑤ 변이 8건을 `vitest related <파일> --run`(Playwright·system spec 제외)으로 실행 ⑥ `reference-page.test.tsx` 단독 3회·스위트 4회·묶음 실행 약 10회 ⑦ IndexedDB 대역 탐침 5건 ⑧ `check-test-evidence.ts --source-root`로 skip 검사 탐침. 끝난 뒤 worktree 제거 |
| 확인하지 못한 범위 | main 트리 전체 `test:unit`·`test:coverage`(오케스트레이터 몫), 실제 커버리지 수치, CI 러너 조건, unit 140개 중 표본 밖 파일의 모듈별 검출력(01~09 영역) |
| 이전 리뷰와 비교 | 직전 리뷰는 `src/`만 봤다. 5.2(연결 지점 테스트 부재)는 realtime에서 개선됨을 확인했다(`realtime-reconnect-coordinator.test.ts:32-39`가 실제 WS/SSE 연결을 씀). HTTP V3 재시도 연결에는 남아 있다(10-03) |
변이 실험 결과(원본은 실험 후 복원):
| ID | 바꾼 곳 | 결과 | 잡은 테스트 |
|---|---|---|---|
| M1 | `src/adapters/http/http-retry-lifecycle.ts:26-27` KEYED도 dispatch 뒤 재시도 허용 | 잡힘 | `tests/unit/http-retry-lifecycle.test.ts` 1개 |
| M1b | `src/adapters/http/http-execution-v3.ts:940` `canRetryTransport(contract.retrySemantics, …)` → `canRetryTransport("SAFE", …)` | **통과(미검출)** | 없음(75파일 547개 통과) |
| M2 | `src/adapters/http/retry-policy.ts:62` idempotency `none`도 재시도 | 잡힘 | unit `retry-policy` 2개, integration(MSW) `http-client` 6개 |
| M3 | `src/platform/release/release-mismatch-recovery.ts` reload guard를 키별로 되돌림(Q-6.9-9 이전) | 잡힘 | platform 2개, `tests/release` 1개, unit `chunk-recovery` 1개 |
| M4 | `src/adapters/http/http-contract-bridge.ts:204` `..` 검사 제거(6.3-1 되돌림) | 잡힘 | `http-contract-bridge.test.ts` "rejects the dot segment \"..\"" |
| M5 | `src/contracts/mutation-intent.ts` 멱등 키에 공백 허용 | 잡힘 | `legacy-and-optional-network-remediation.test.ts` 1개 |
| M6 | `src/adapters/http/client.ts:344` `recoveryUsed = true` 제거 | 잡힘 | integration(MSW) `auth-recovery` "stops after a second 401" |
| M7 | `http-execution-v3.ts:784` `Idempotency-Key` 헤더 제거 | 잡힘 | unit `http-execution-v3`, features `reference-runtime-composition`, scale `network-flap` |
## 3. 확인된 강점
1. **회귀 테스트가 실제 규칙을 고정한다.** 위 표에서 변이 8건 중 7건이 잡혔다. 실패한 테스트 이름이 깨진 규칙을 그대로 말한다(예: "rejects the dot segment \"..\" instead of letting URL resolution move the target"). 가짜 fetch도 실제 `Response` 객체를 돌려준다(`tests/unit/http-execution-v3.test.ts:164`, `:187`).
2. **테스트 사이에 상태가 새지 않는다.** `vitest.config.ts:13-15`가 `restoreMocks`·`clearMocks`·`mockReset`을 켠다. `tests/setup.ts:5-7`이 RTL `cleanup`을 돈다. fake timer를 쓰는 7개 파일은 모두 `useRealTimers`로 되돌린다. `stubGlobal`을 쓰는 2개 파일은 `unstubAllGlobals`로 되돌린다. 순서를 섞은 3회 실행에서 순서 의존 실패는 없었다.
3. **flaky를 재시도로 숨기지 않는다.** `vitest.config.ts`에 `retry`가 없다(기본 0). CI는 `CI: "true"`를 준다(`.gitea/workflows/quality-gates.yml:27`). 그래서 Vitest가 `.only`를 거부한다(`allowOnly` 기본값이 CI에서 false).
4. **HTTP 실패 시나리오가 "선언 = 실행 = 관측"으로 묶여 있다.** `tests/integration/http-scenario-catalog.test.ts:388-389`가 시나리오마다 실제 실행 결과를 기대값과 비교하고 실패 메시지에 `executionId`를 넣는다. `scripts/check-test-evidence.ts:230-270`이 선언 ID와 실행 ID의 누락·추가·digest·관측값 불일치를 거부한다. MSW 서버는 처리되지 않은 요청을 실패로 만든다(`tests/mocks/server.ts:8`).
5. **빠르다.** 22코어·부하 평균 5~14에서 unit 140파일 10.2s, component 31파일 7.0s, integration 12파일 11.9s, 나머지 94파일 15~18s였다.
6. **mock 호출 순서를 베낀 테스트가 드물다.** `toHaveBeenNthCalledWith` 2건, `mock.calls` 전체 비교 9건이 전부다. 모두 전달된 값·열린 창·읽은 페이지 같은 관찰 가능한 결과를 본다(예: `tests/unit/cursor-pagination-runtime.test.ts:85`). snapshot 단언은 1건이다. Given/When/Then 표기를 세는 검사는 없다(관점 23).
## 4. 발견 사항 (36.3)
다른 영역과 겹치는 항목은 새 ID를 만들지 않고 아래 증거만 보탠다.
- **05-08 보강(IndexedDB 대역):** 탐침으로 두 가지를 더 확인했다. 숫자 키 `1`과 문자열 키 `"1"`이 한 행으로 합쳐진다(`tests/helpers/memory-indexeddb.ts:118-126`, `String(key)`). `delete(IDBKeyRange)`는 오류 없이 아무것도 지우지 않는다(`:550`, `get`도 `:520`). 겹친 readwrite 트랜잭션의 쓰기 유실, macrotask 뒤 요청 수용, 배열 keyPath 인덱스 오정렬은 05-08과 같은 결과였다. 도움말 주석(`:724`)은 모델링하지 않는 의미를 적지 않는다.
- **11-08 보강(skip 검사):** `scripts/check-test-evidence.ts:288`의 정규식은 `.skip(`·`.fixme(`만 본다. `it.skipIf(true)`, `it.todo`, 테스트 안의 `ctx.skip()`은 quarantine 주석 없이 통과했다(탐침 exit 0). 현재 `it.skipIf(isReducedCiContractRun())`가 3곳에 있다(`tests/unit/task3-selective-integration.test.ts:182`, `:196`, `tests/unit/supply-chain.test.ts:543`). 모두 removal-fixture 모드 전용이라 지금은 정당하다.
- **12-04·09-11 보강(어느 명령에도 속하지 않는 테스트):** 12-04 목록 밖으로 `tests/scale/browser-soak.contract.test.ts`는 `check:scale:*` 프로필에도 없다(`scripts/scale/run-scale-profile.ts:32-110`). `tests/scripts/verify-extreme-scale.test.ts`는 어떤 스크립트에도 없다.
### 10-01 깨끗한 체크아웃에서 `test:unit`이 실패한다 — 테스트가 gitignore된 로컬 생성물에 의존
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 20, 21, 30.8 |
| 근거 | `tests/unit/removal-fixture.test.ts:113-125`는 `RELEASE_CANDIDATE_EVIDENCE_PATHS` 중 현재 작업 디렉터리에 실제로 있는 `artifacts/…` 파일을 세고 `expect(preserved).toBeGreaterThan(0)`를 요구한다. 이 파일들(`artifacts/release/*.json`, `artifacts/security/*.json`, `artifacts/performance/bundle.json` 등)은 `.gitignore:11`(`artifacts/**/*.json`)로 추적되지 않는다. 새 worktree에서 이 파일 단독 실행 → `AssertionError: expected 0 to be greater than 0`(5 통과·1 실패). unit 전체(shuffle) → 139/140 통과, 이 파일만 실패. main 트리는 누가 릴리스 체인을 돌려 둔 파일이 있어서 통과한다. CI merge job FE-GATE-005(`.gitea/workflows/quality-gates.yml:47`, `:55-71`)는 checkout → install → `ci:gate`만 하고 산출물을 받지 않는다. FE-GATE-005 명령은 `test:unit`·`test:contract`·`test:coverage`다 |
| 발생 조건 | 릴리스 체인(`build:release-candidate` 등)을 한 번도 돌리지 않은 체크아웃. 새 clone, CI 러너, 다운스트림 복사본이 모두 해당한다 |
| 영향 | `test:unit`, `test:all`(README가 안내하는 기본 개발 루프), `test:coverage`가 실패한다. FE-GATE-005가 켜진 러너에서는 매번 빨간불이다. 새 사용자는 첫 실행에서 실패를 보고, 팀은 빨간불을 무시하는 습관을 배운다 |
| 심각도·우선순위 | High · P1 — 30.8절 "깨끗한 환경의 설치·실행·기본 테스트"와 merge 게이트를 깨뜨린다. 복사한 모든 프로젝트에 그대로 간다. 사용자·데이터 피해는 없어서 Critical이 아니다(14-01과 같은 기준) |
| 통제·증거 | M0(생성물 의존을 막는 장치 없음) · E2(깨끗한 worktree 실행) |
| 확실성과 남은 가정 | 실패 재현은 확실하다. 이 repo는 CI가 돌지 않아(12-01) 실제 CI 실패 기록은 없다 |
| 최소 개선 방향 | 테스트 대상이 "복사 시 보존"이므로 `process.cwd()` 대신 임시 폴더에 가짜 증거 파일을 만들고 `copyReleaseEvidenceTree(tempRoot, target)`로 검사한다. 또는 `tests/setup.ts`나 lint로 빠른 계층이 `artifacts/`·`dist/`를 읽지 못하게 한다 |
| 비용·부작용 | 테스트 수정 몇 줄. 보존 검사 의미는 유지된다 |
| 완료 기준 | 깨끗한 worktree(`git worktree add` + install)에서 `test:unit`이 통과한다. 빠른 계층 테스트가 추적되지 않는 파일을 읽지 않는다 |
| 검증 방법 | 새 worktree에서 `node scripts/run-vitest.ts run tests/unit` 실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.0(깨끗한 체크아웃 게이트 실패)과 같은 종류. 6.0의 생성 파일 문제는 `scripts/run-vitest.ts:51-60`로 고쳐졌고, 이 건은 새로 확인됨 |
### 10-02 샘플 기능 페이지 테스트가 부하에서 흔들리고, 실패 메시지가 시간 초과를 가린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(조건부 재현) |
| 관련 관점 | 10, 8, 14, 30.5 |
| 근거 | `tests/features/reference-feature/reference-page.test.tsx:137-138`이 첫 렌더 직후 `findByRole("heading", …)`를 기본 제한 시간(1,000ms, Testing Library 기본값)으로 기다린다. 이 테스트는 파일의 첫 테스트라 lazy route 청크를 불러오는 비용을 혼자 낸다. 단독 실행에서 804ms가 걸렸다(여유 약 20%). 관련 테스트 묶음(66~81파일 병렬, 부하 평균 5~14) 약 10회 실행 중 6회 `TestingLibraryElementError: Unable to find role="heading"`으로 실패했다. 단독 3/3, 자기 스위트(`tests/features/reference-feature`) 4/4는 통과했다. 저장소 어디에도 `asyncUtilTimeout` 설정이 없다 |
| 발생 조건 | CPU가 바쁠 때. 여러 디렉터리를 함께 돌리는 `test:coverage`(V8 계측 + `--maxWorkers=4`), `vitest related`, 느린 CI 러너 |
| 영향 | merge 게이트가 코드 변경과 무관하게 가끔 실패한다. 메시지가 "화면에 제목이 없다"라서 UI 결함처럼 보인다. 이 파일은 복제용 샘플이라 같은 패턴이 다운스트림 기능 테스트로 퍼진다 |
| 심각도·우선순위 | Medium · P2 — 제품 피해는 없지만 게이트 신뢰와 조사 비용을 반복해서 깎는다 |
| 통제·증거 | M0 · E2(반복 실행, 조건 기록) |
| 확실성과 남은 가정 | 원인(첫 lazy import가 1초 기본값에 가까움)은 측정으로 확인했다. CI 조건에서의 실패율은 미확인이다 |
| 최소 개선 방향 | 첫 대기에 route 준비 신호를 기다리거나(`await screen.findByRole(…, {}, { timeout: 5_000 })`), `tests/setup.ts`에서 `configure({ asyncUtilTimeout })`를 테스트 타임아웃과 맞춘다. lazy 모듈을 `beforeAll`에서 미리 import하는 방법도 있다 |
| 비용·부작용 | 한두 줄. 전역 timeout을 늘리면 진짜 멈춤을 늦게 발견하므로 첫 렌더 대기에만 적용하는 편이 낫다 |
| 완료 기준 | 부하 조건(예: 비-unit 디렉터리 전체 + unit 동시 실행) 20회에서 실패 0 |
| 검증 방법 | `vitest related src/adapters/http/http-retry-lifecycle.ts --run`을 반복 실행하고 실패 수를 센다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 10-03 V3 HTTP 실행기가 계약의 재시도 의미를 쓰는지 검증하는 테스트가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(검출 공백) |
| 관련 관점 | 10, 6, 17, 21 |
| 근거 | 변이 M1b: `src/adapters/http/http-execution-v3.ts:940`에서 `contract.retrySemantics` 대신 `"SAFE"`를 넘겨도 관련 75파일 547개 테스트가 통과했다. 같은 규칙의 순수 함수(`http-retry-lifecycle.ts:21-30`)를 바꾼 M1은 unit 1개만 잡았다. 테스트 fixture의 KEYED 명령은 `retryBudget: 0`이다(`tests/helpers/external-contract-fixture.ts:173`, `:194`). 샘플 계약도 0이다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:195`). 그래서 "KEYED + 예산 > 0 + dispatch 뒤 전송 실패" 경로는 어떤 테스트에서도 실행되지 않는다. 계약 검증은 NEVER + 예산 > 0만 막는다(`src/contracts/external-contract-runtime.ts:489-494`). 테스트 전략 문서는 이 위험을 P0로 두고 "unit policy + MSW integration"으로 막는다고 쓴다(`docs/testing/frontend-platform-testing-strategy.md` 3절 표) |
| 발생 조건 | 실행기 리팩터링에서 재시도 판단 인자가 바뀌거나 빠질 때. 다운스트림이 KEYED 명령에 `retryBudget` 1~2를 줄 때 |
| 영향 | dispatch된 KEYED 명령이 자동 재전송돼도 빠른 테스트가 모른다. 같은 멱등 키로 가므로 서버가 키를 지원하면 피해는 제한되지만, 문서가 약속한 "dispatch 뒤에는 재전송 대신 조정" 계약이 조용히 깨진다 |
| 심각도·우선순위 | Medium · P2 — 전략 문서 스스로 P0로 분류한 규칙인데 연결 계층 검증이 없다. 실제 피해는 서버 멱등 처리 여부에 달려 있다 |
| 통제·증거 | M3(순수 함수 단위) / 실행기 연결은 M0 · E2(변이 실험) |
| 확실성과 남은 가정 | 미검출은 확인했다. 모듈 세부 규칙 차이는 03-06이 다룬다 |
| 최소 개선 방향 | `http-execution-v3.test.ts`에 KEYED·`retryBudget: 2` 계약으로 "dispatch 전 실패는 재시도, dispatch 뒤 실패는 fetch 1회 + `MAYBE_APPLIED`" 두 테스트를 추가한다 |
| 비용·부작용 | 테스트 2개. 기존 fixture 재사용 |
| 완료 기준 | M1b 변이를 넣으면 새 테스트가 실패한다 |
| 검증 방법 | M1b를 다시 적용하고 `vitest related src/adapters/http/http-execution-v3.ts --run` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 5.2(연결 지점 테스트 부재)의 패턴이 HTTP V3 재시도 연결에 남아 있음 |
### 10-04 커버리지 게이트가 문서의 위험별 목표가 아니라 17개 모듈의 현재값 하한이고, live 재시도 모듈이 빠져 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 10, 21, 9 |
| 근거 | `scripts/lib/risk-coverage.ts:804-871`이 막는 것: 전체 평균(lines 75·statements 73·functions 80·branches 68, `config/testing/risk-coverage.json:5-10`), `criticalModules` 17개의 모듈별 하한, 커버리지 표에서 빠진 모듈, 카운터가 0인 모듈. 모듈별 하한은 현재값 근처다(branches: `service-worker-lifecycle.ts` 43, `http-execution-v3.ts` 52, `read-bounded-boot-json.ts` 57, `browser-storage-adapter.ts` 60). 전략 문서는 "retry/error/auth/chunk policy — 모든 결정 분기", "HTTP/storage/telemetry adapter — 90% 이상"을 목표로 적고(`docs/testing/frontend-platform-testing-strategy.md:957-958`), "19개 high-risk module에 80개 scoped threshold"라고 쓴다(`:158`). 실제는 17개·모듈별 68개(+전체 4개). 목록에는 legacy V2 `retry-policy.ts`가 있고, live V3 재시도 규칙 `http-retry-lifecycle.ts`(10-03), `http-contract-bridge.ts`(6.3-1), realtime `reconnect-coordinator.ts`, `indexeddb-runtime.ts`, `push-subscription-adapter.ts`(직전 리뷰 상위 결함 모듈)는 없다 |
| 발생 조건 | 목록 밖 고위험 모듈의 테스트가 줄거나 분기가 늘 때. 전체 평균만 유지되면 통과한다 |
| 영향 | 문서를 믿은 다운스트림이 고위험 모듈이 90% 이상으로 막혀 있다고 오해한다. 커버리지는 보조 신호라 직접 피해는 작다 |
| 심각도·우선순위 | Low · P3 — 1차 방어는 테스트 자체이고 10-03처럼 개별로 보완할 수 있다 |
| 통제·증거 | M3(17개 모듈) / 문서 목표는 M1 · E1(정적 확인, 실제 커버리지 수치 미확인) |
| 확실성과 남은 가정 | 정책 파일과 평가 코드는 확인했다. 현재 커버리지 실제값은 `test:coverage`를 돌리지 않아 모른다 |
| 최소 개선 방향 | 문서 2.3·14.2절을 "현재값 ratchet + 올릴 목표"로 고쳐 쓴다. `highRiskPaths`에 live 경로(`http-retry-lifecycle.ts`, `http-contract-bridge.ts`)와 직전 리뷰 결함 모듈을 넣고 현재값으로 하한을 둔다 |
| 비용·부작용 | JSON 몇 줄. 목록이 늘면 ratchet 갱신 부담이 조금 는다 |
| 완료 기준 | 문서 수치가 정책 파일과 같다. live 재시도·경로 규칙 모듈이 목록에 있다 |
| 검증 방법 | `check:coverage:fixture`와 `test:coverage` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 10-05 테스트 파일 하나를 돌리는 방법이 문서에 없고, 문서에 적힌 명령은 새 체크아웃에서 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 19 |
| 근거 | 동작하는 방법(`node scripts/run-vitest.ts run <file>`)은 어디에도 적혀 있지 않다(14 영역 2.1절 표와 같은 관찰). 운영 ledger는 `corepack pnpm exec vitest run <file>`을 쓴다(`docs/operations/adapter-remediation-ledger.md:75-97`). 이 명령은 생성기를 거치지 않는다. 새 worktree에서 `vitest run tests/component/router.test.tsx` → `Failed to resolve import "../.generated/product-feature-index.ts"`. `pnpm test:unit -- <file>`은 줄어들지 않는다. 스크립트가 이미 `tests/unit`을 넘기므로 `vitest list tests/unit tests/unit/retry-policy.test.ts` → 140파일. `vitest.config.ts`에 `include`가 없어 인자 없는 `vitest run`은 Playwright spec 25개와 host 전제 system 테스트 3개까지 모은다(`vitest list` → 292파일) |
| 발생 조건 | 새 clone 직후 파일 하나를 돌릴 때, 경로 없이 `vitest`를 돌릴 때 |
| 영향 | 첫 실행에서 모듈 해석 오류를 보고 원인(생성기)을 스스로 찾아야 한다. Node 버전 검사도 건너뛴다 |
| 심각도·우선순위 | Low · P3 — 한 번 `pnpm dev`나 다른 스크립트를 돌리면 사라진다 |
| 통제·증거 | M0 · E2 |
| 확실성과 남은 가정 | 재현했다 |
| 최소 개선 방향 | `docs/testing/taxonomy.md`에 "파일 하나: `node scripts/run-vitest.ts run <file>`" 한 줄을 넣는다. `vitest.config.ts`에 `include: ["tests/**/*.test.{ts,tsx}"]`와 `tests/system/**` 제외를 둔다 |
| 비용·부작용 | 몇 줄. `tests/system`은 `test:system`이 경로로 지정하므로 영향 없음을 확인해야 한다 |
| 완료 기준 | 새 clone에서 문서의 한 줄 명령으로 파일 하나가 돈다. 인자 없는 `vitest list`에 `.spec.ts`가 없다 |
| 검증 방법 | 새 worktree에서 문서 명령 실행, `vitest list --filesOnly` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 10-06 fake timer 복원이 일부 테스트 본문 끝에만 있어, 단언이 실패하면 같은 파일의 다음 테스트로 새어 실패가 연쇄된다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 10, 8, 23 |
| 근거 | `finally`나 `afterEach` 없이 본문 끝에서 `vi.useRealTimers()`를 부르는 곳이 5곳이다: `tests/unit/service-worker-runtime.test.ts:854-886`, `:890-921`, `tests/unit/system-clock.test.ts:7-16`, `tests/unit/http-execution-v3.test.ts:633-655`, `tests/component/design-system-platform.test.tsx:262-288`. 같은 파일의 다른 테스트는 `try/finally`를 쓴다(`service-worker-runtime.test.ts:1013-1058`). 전역 복원은 없다(`tests/setup.ts:5-7`) |
| 발생 조건 | 위 테스트 중 하나의 중간 단언이 실패할 때 |
| 영향 | 뒤 테스트들이 fake timer 아래에서 멈추거나 timeout으로 실패해, 실제 실패 하나가 여러 개처럼 보인다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2(대부분 파일) · E1 |
| 확실성과 남은 가정 | 정적 확인. 연쇄 실패를 실제로 만들어 보지는 않았다 |
| 최소 개선 방향 | `tests/setup.ts`의 `afterEach`에 `vi.useRealTimers()` 한 줄을 추가한다 |
| 비용·부작용 | 한 줄 |
| 완료 기준 | 전역 `afterEach`에서 실제 타이머로 돌아간다 |
| 검증 방법 | 위 테스트 하나에 실패 단언을 넣고 같은 파일의 다음 테스트가 통과하는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 10-07 테스트 문서가 현재 구성과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서) |
| 관련 관점 | 9, 20, 24 |
| 근거 | ① 전략 문서는 "clock/random/scheduler/storage helper와 … 비결정적 우회를 차단한다"고 쓴다(`docs/testing/frontend-platform-testing-strategy.md:145-146`). `tests/support/runtime/determinism.ts`를 import하는 파일은 0개다. 그 안의 `createControlledScheduler().clearTimeout`은 아무것도 취소하지 않는 `vi.fn()`이다(`:33`). ② 공통 scenario ID 표(`:713-735`)의 `auth-recover-once`·`auth-persistent-401`·`server-terminal-500`은 catalog에 없다. catalog에는 `unauthenticated-401`·`response-too-large`·`server-terminal-503`이 있다(`tests/mocks/scenarios/catalog.ts:17-37`). ③ taxonomy는 `test:all` 구성을 runtime-schema~recipe로 설명한다(`docs/testing/taxonomy.md:19-22`). 실제로는 `test:platform`과 `check:release-coherence`도 돈다(`package.json:83`). ④ taxonomy는 자식 프로세스를 띄우는 테스트를 `tests/integration`에 두라고 한다(`docs/testing/taxonomy.md:65-70`). 실제 `tests/unit`에는 Node·Vitest·CI 러너를 띄우는 파일이 7개 있다(예: `tests/unit/risk-coverage.test.ts:28-33`이 30초 예산을 따로 둔다). 측정상 7파일 4.2s라 속도 피해는 작다 |
| 발생 조건 | 문서를 보고 helper를 찾거나 시나리오를 추가할 때 |
| 영향 | 없는 보호를 있다고 믿는다. 새 기능 작성자가 없는 scenario ID로 계획을 세운다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 정적 확인 |
| 최소 개선 방향 | 쓰지 않는 `determinism.ts`는 지우거나 문서 문장을 고친다. scenario 표를 catalog에서 복사한다. taxonomy의 `test:all` 설명과 분류 규칙을 현재 상태로 맞춘다 |
| 비용·부작용 | 문서 수정 |
| 완료 기준 | 위 네 문장이 코드와 같다 |
| 검증 방법 | 문서 대조 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 다른 영역 — 모듈 규칙은 01~09 | — | — | 적용 제외 |
| 2 | 구조적 성숙도 | 다른 영역 — 경계 검사는 12 | — | — | 적용 제외 |
| 3 | 변경 용이성 | 적용 — 테스트 추가·변경 비용 | M2 / M2 | E1 | 충족 — `create-test-application.ts`가 운영 `createApplication`을 재사용하고, 시나리오 증거는 owner별 contribution이다(`config/testing/test-evidence.json`) |
| 4 | 인지 부하 | 적용 — 테스트 탐색 | M2 / M2 | E1 | 부분 충족 — 실패 테스트 이름이 규칙을 말한다. unit 60k줄에 제품·도구 테스트가 섞여 있다(도구 대상 27파일 8.8k줄) |
| 5 | 위험 가시성 | 적용 — 테스트 대역의 한계 표시 | M1 / M1 | E2 | 부분 충족 — IndexedDB 대역이 모델링하지 않는 의미를 적지 않는다(05-08) |
| 6 | 실패 성숙도 | 적용 — 실패 경로 테스트 | M3 / M3 | E2 | 부분 충족 — 19개 HTTP 실패 시나리오 × 3 operation 실행 증거. V3 재시도 연결 공백(10-03) |
| 7 | 운영 성숙도 | 적용 제외 — 테스트 계층 밖 | — | — | 적용 제외 |
| 8 | 디버깅 가능성 | 적용 — 실패 메시지 | M2 / M2 | E2 | 부분 충족 — `it.each` 191건, `executionId` 메시지. 부하 flaky 메시지가 원인을 가림(10-02), fake timer 연쇄 실패 가능(10-06) |
| 9 | 유지보수 성숙도 | 적용 — 테스트 문서·자산 | M1 / M1 | E1 | 부분 충족 — 문서 불일치(10-07), 커버리지 문서 수치(10-04) |
| 10 | 테스트 성숙도 | 적용 — 이 영역의 중심 | M3 / M3 | E2 | 부분 충족 — 변이 7/8 검출, 순서 의존 없음, 재시도로 숨김 없음. 깨끗한 체크아웃 실패(10-01), flaky(10-02), 연결 공백(10-03) |
| 11 | 데이터 성숙도 | 적용(테스트 대역 범위만) | M2 / M1 | E2 | 부분 충족 — IndexedDB 대역의 키·범위 삭제 의미가 다름(05-08 보강) |
| 12 | 동시성 성숙도 | 적용 — 테스트 간 격리·대역의 동시성 | M3 / M3 | E2 | 부분 충족 — 순서 섞기 3회 통과. 대역은 겹친 트랜잭션에서 쓰기를 잃는다(05-08) |
| 13 | 확장성 | 다른 영역 — 11 | — | — | 적용 제외 |
| 14 | 성능 성숙도 | 적용 — 테스트 실행 시간 | M2 / M2 | E2 | 충족(개발 장비 기준) — unit 10s·component 7s·integration 12s. CI 러너 시간은 미검증. merge CI는 `test:unit` 뒤 `test:coverage`가 같은 테스트를 다시 돈다 |
| 15 | 보안 성숙도 | 다른 영역 | — | — | 적용 제외 |
| 16 | 의존성 성숙도 | 다른 영역 — 13 | — | — | 적용 제외 |
| 17 | API / Contract 성숙도 | 부분 적용 — 계약 테스트 계층 | M3 / M3 | E2 | 부분 충족 — runtime-schema·contract 테스트와 scenario 증거 있음. 실행기 연결 공백(10-03) |
| 18 | 배포 성숙도 | 다른 영역 — 11·13 | — | — | 적용 제외 |
| 19 | 설정 성숙도 | 적용 — 테스트 러너 설정 | M2 / M2 | E2 | 부분 충족 — `run-vitest.ts`가 Node 버전·NODE_ENV·생성기를 고정한다. `include` 없음(10-05) |
| 20 | 개발자 경험 | 적용 — 테스트 실행 경로 | M2 / M1 | E2 | 미충족 — 새 clone에서 `test:unit` 실패(10-01), 파일 하나 실행 방법 미문서(10-05) |
| 21 | Guardrail 성숙도 | 적용 — 테스트 증거·커버리지 게이트 | M3 / M2 | E2 | 부분 충족 — scenario receipt 검사는 강함. skip 검사 우회(11-08 보강), 커버리지 범위(10-04), 명령에 속하지 않는 테스트(12-04) |
| 22 | 추상화 성숙도 | 적용 — 테스트 대역·검사 도구 | M2 / M2 | E1 | 부분 충족 — IndexedDB 대역이 차이를 숨김(05-08). risk-coverage 도구 약 1.5k줄은 비용 대비 효과 검토 대상(12-10) |
| 23 | 일관성 | 적용 — 테스트 작성 방식 | M2 / M2 | E1 | 부분 충족 — GWT 표기를 품질로 세지 않음. fake timer 복원 방식이 파일마다 다름(10-06) |
| 24 | 네이밍 / 의미 성숙도 | 적용 — 테스트 계층 이름 | M1 / M1 | E1 | 부분 충족 — `tests/unit`에 프로세스를 띄우는 테스트가 있음(10-07 ④) |
| 25 | 조직 확장성 | 적용 제외 — 작성자 1인, 구조적 준비만 | — | — | 적용 제외 |
| 26 | Ownership 성숙도 | 부분 적용 — quarantine·커버리지 owner | M2 / M1 | E2 | 부분 충족 — 커버리지 모듈에 owner가 있음. quarantine 만료를 검사하지 않음(11-08) |
| 27 | 삭제 가능성 | 다른 영역 — 14 | — | — | 적용 제외 |
| 28 | 회복 가능성 | 적용 제외 — 테스트 계층 밖 | — | — | 적용 제외 |
## 6. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| main 트리 전체 `test:unit`·`test:coverage` 결과, 실제 커버리지 수치 | 공유 작업 트리에서 전체 게이트 실행 금지 | 오케스트레이터 실행 결과. 단, main 트리 `test:unit` 통과는 로컬 `artifacts/` 때문일 수 있다(10-01) |
| CI 러너에서의 시간·flaky(특히 10-02) | 이 repo에서 CI가 돌지 않음(12-01) | CI를 켜고 `test:coverage`를 20회 반복 |
| unit 140파일 중 표본 밖 파일의 검출력 | 범위 분담(모듈별은 01~09) | 영역별 변이 실험 |
| jsdom 에뮬레이션(`tests/component/app-shell.test.tsx:17-57`의 modal dialog)과 실제 브라우저 차이 | 브라우저 테스트는 11 영역 | 11 영역의 E2E·capability 결과 대조 |
| MSW scenario 19개의 개별 구현이 실제 서버 의미와 맞는지 | 카탈로그 앞부분만 읽음 | `tests/mocks/scenarios/catalog.ts` 전체와 백엔드 계약 대조 |
@@ -0,0 +1,251 @@
# 테스트 체계(브라우저·릴리스·규모·시스템) 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `tests/e2e/`(976줄), `tests/browser-capabilities/`(3,903줄), `tests/visual/`(54줄 + 기준 이미지 5장), `tests/storybook/`(24줄), `tests/release/`(608줄), `tests/scale/`(2,099줄), `tests/system/`(2,747줄, 훑어봄), `tests/architecture/`(431줄), `tests/scripts/`(232줄), `playwright*.config.ts` 5개(184줄), `config/scale/`, `config/performance/`, 문서 5개(`docs/testing/taxonomy.md`, `docs/operations/performance-evidence.md`, `docs/reviews/2026-09-23-extreme-scale-*.md`, `docs/reviews/2026-09-23-release-coherence-baseline.md`). 판정을 위해 함께 읽은 스크립트: `scripts/drill-runbook.ts`, `scripts/test-performance.ts`, `scripts/scale/*`(일부), `scripts/verify-extreme-scale.ts`, `scripts/verify-browser-capability-evidence.ts`, `scripts/check-test-evidence.ts`(일부), `config/ci/gates.json`(명령·게이트), `.gitea/workflows/quality-gates.yml`.
> 영역 판정(35.8): **조건부 사용 가능** — 브라우저 capability 테스트, Service Worker 두 빌드 업데이트 테스트, 부트 정합성 테스트는 참고 구현으로 복제해도 된다. 런북 drill(11-01)을 복구 증거로, 라우트 a11y·visual 대기 방식(11-02)을 검사 패턴으로, 규모 기준선(11-03)을 CI 게이트로, lab 성능 1회 측정(11-07)을 릴리스 판정으로 그대로 쓰는 것은 보류한다.
## 1. 결론
- **운영 승격 게이트의 런북 drill 5개는 복구를 하지 않는다.** 단언 일부가 상수 `true`다. 격리 worktree에서 `dist/assets/*.js`를 전부 지워 앱이 부팅할 수 없게 만들어도 5개 모두 PASS였다(11-01). `PROD_PROMOTION_READY`가 이 PASS에 의존한다.
- **라우트별 axe 검사가 lazy route의 로딩 화면을 검사할 때가 있다.** 같은 빌드에 넣은 a11y 위반을 한 번은 24/24 잡고, 다음엔 Chromium에서 0/3, 1/5만 잡았다. 상태 화면 visual 기준 이미지는 아예 로딩 화면이다(11-02).
- **규모 증거는 생성기 지역성·알고리즘 복잡도·요청 증폭 상한을 보여 준다.** 이름만 다른 stub 기능으로 만든 증거라서, 선언된 앱당 상한(컨텍스트 20 × 기능 200)의 실제 타입 검사·빌드 비용은 측정되지 않았다(11-04). 규모 회귀 게이트는 기준선을 만든 CPU 한 종류에서만 통과할 수 있고, "CI execution tiers"라는 설명과 달리 어느 CI job에도 없다(11-03).
- **flaky를 재시도로 숨기지는 않는다.** Playwright 설정 5개 모두 `retries`가 없고(기본 0), 공용 fixture가 콘솔 오류·페이지 오류·요청 실패를 실패로 만든다. 다만 `test.only` 차단은 capability 설정에만 있다(11-08).
- **핵심 흐름 E2E는 "보호 화면이 열린다"까지만 본다.** 목록 응답을 스키마 위반으로 바꿔도 E2E가 통과했다. 저장 성공·실패 후 재시도 브라우저 테스트가 없다(11-06). lab 성능 게이트는 1회 측정이고 상호작용 지표에 Playwright 왕복 시간이 들어간다(11-07).
- **미검증:** CI 러너에서의 실제 결과, e2e·capability 전체 실행, browser soak, `test:system`.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, 영역 11(테스트 체계: 브라우저·릴리스·규모·시스템) |
| 커밋·상태·시점 | `main` / `4626b73`, 2026-09-25. 코드 변경 실험은 모두 `scratchpad/11/wt` 분리 worktree에서 했고, 끝난 뒤 `git worktree remove --force`로 지웠다 |
| 실행 환경 | Node v24.14.0, pnpm 11.17.0, Playwright 1.62.0(chromium-1234, firefox-1538, webkit-2336), Intel Core Ultra 7 155H(22 스레드). 실행 중 loadavg 17~28(다른 영역 에이전트 동시 실행) |
| 읽은 코드·설정 | 머리말 범위 전체. `tests/system/`은 테스트 이름과 대표 3파일 앞부분만 읽었다(CI 러너·공급망 영역 12·13과 겹침) |
| 실행한 테스트·실험 | 아래 표 |
| 확인하지 못한 범위 | e2e 전체·a11y 전체·browser-capabilities 전체·storybook spec, `test:system`(systemd·bwrap·cgroup v2 필요), `check:scale:nightly` browser soak, `service-worker-update.spec.ts`(두 번 빌드), CI 실행 이력(권한 없음) |
| 이전 리뷰와 비교 | 직전 리뷰(2026-09-24)는 `tests/` 대부분을 범위 밖으로 뒀다. 관련 항목 6.9-1(부트 reload 반복)·6.6-1(실제 브라우저 SW 업데이트 테스트 요구)은 현재 코드에서 다시 확인했다 |
실행 목록(모두 분리 worktree, 원본 `node_modules` 심볼릭 링크. pnpm의 deps 검사가 설치를 시도하므로 `pnpm_config_verify_deps_before_run=false`로 끄고 `node`/`npx`로 직접 실행):
| 명령·실험 | 결과 |
|---|---|
| `node scripts/run-vitest.ts run tests/release tests/architecture tests/scripts` | 11파일 58개 통과 |
| `node scripts/run-vitest.ts run tests/scale` | 14파일 83개 통과 |
| `node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts` | 빌드 성공(local profile, SW 없음) |
| `playwright test --config playwright.visual.config.ts`(포트만 4391로, 서버는 `vite preview`) | 5/5 통과 |
| `playwright test tests/e2e/reference-route.spec.ts` 3엔진 | 3/3 통과 |
| 변이: reference-route 목 응답을 503으로 | spec 단언은 통과, strict fixture의 콘솔 오류 검사로만 실패 |
| 변이: reference-route 목 응답을 스키마 위반 200으로 | **통과**. 화면은 오류 문구 표시 |
| 프로브: 라우트별로 spec과 같은 순서(goto → `main` 표시 → axe) | `/`, `/examples/ui`, `/examples/states`, `/examples/platform`에서 axe 검사 노드 74~79개, h1 0개. h1을 기다리면 106/374/182/351개 |
| 변이: `state-gallery-page.tsx`에 alt 없는 `img`와 이름 없는 `button` 추가 후 `accessibility.spec.ts` 반복 | 1차 3엔진×8회 24/24 검출 → 2차 Chromium 0/3 → 3차 Chromium 1/5, Firefox 5/5, WebKit 5/5 |
| `node scripts/drill-runbook.ts FE-RB-001..005` | 5개 PASS |
| 같은 명령, `dist/assets/*.js` 전부 삭제 후 | **5개 PASS**. FE-RB-002 record의 복구 단언 4개 모두 `passed: true` |
| `node scripts/scale/check-scale-baseline.ts` | exit 1, `INCOMPLETE`(compiler 16축·absolute 28·growth 8 통과, CPU가 달라 timing 0) |
| `node scripts/test-performance.ts` 6회(포트만 4394, `--strictPort`) | 6회 모두 FAIL. interaction 326~1103ms, LCP 1820~2740ms, CLS 0~0.0043 |
## 3. 확인된 강점
- **flaky가 재시도로 숨지 않는다.** `playwright*.config.ts` 5개 모두 `retries`가 없다(기본 0). 공용 fixture가 console error/warning, `pageerror`, `requestfailed`를 모아 테스트 끝에 실패시킨다(`tests/support/browser/strict-browser-test.ts:15-43`). 11-06 변이에서 503을 잡은 것도 이 fixture다.
- **브라우저 capability 테스트는 3엔진에서 같은 케이스가 실제로 돌았는지 확인한다.** 증거 검사가 junit의 failures·errors·skipped가 0인지, 엔진별 케이스 집합이 Chromium과 같은지 본다(`scripts/verify-browser-capability-evidence.ts:11`, `:53`). 여러 탭 동작도 실제 브라우저 두 페이지로 확인한다(`tests/browser-capabilities/cross-context-invalidation.spec.ts:160`, `:223`, `tests/browser-capabilities/indexeddb-runtime.spec.ts:920`, `:972`).
- **신·구 빌드 공존을 실제 브라우저에서 확인한다(SW 구성).** 운영 빌드 A·B를 만들어 A에서 B로 업데이트한 뒤, 서버에서 지운 A의 route 청크를 이전 캐시가 응답하는지 본다(`tests/e2e/service-worker-update.spec.ts:207-247`). 직전 리뷰 6.6-1이 요구한 형태다. Firefox 제외는 owner·만료일이 있는 quarantine으로 표시돼 있다(`:148`).
- **부트 정합성 테스트는 실제 loader와 복구 정책을 쓴다.** `loadRuntimeConfig`, `loadReleaseManifest`, `releaseMismatchKey`, `createReleaseMismatchRecovery`를 그대로 호출한다(`tests/release/release-fixture.ts:4-8`, `:184-223`). 직전 리뷰 **6.9-1(번갈아 바뀌는 mismatch 키로 reload 반복)은 해결됐다.** 두 종류의 mismatch가 번갈아 와도 reload는 1회다(`tests/release/mixed-replica.test.ts:105-117`, `tests/release/release-matrix.test.ts:236-250`).
- **규모 증거가 "통과"를 과장하지 않게 만든 장치가 있다.** 건너뛴 단계가 있으면 tier가 `incomplete`로 끝난다(`scripts/scale/run-scale-profile.ts:157`, `:185`). CPU가 다르면 timing을 비교하지 않고 통과로 치지 않는다(`scripts/scale/scale-baseline.ts:202`, `:357`). 기준선에 CPU·Node·TypeScript 버전·승인자가 있다(`config/scale/benchmark-baseline.json:3-10`). 요청 증폭 테스트는 실제 V3 executor로 1만 interaction을 돌린다(`tests/scale/traffic/synthetic-traffic.ts:41-92`). soak은 heap 표본 전에 GC를 강제한다(`scripts/scale/browser-soak.ts:456`).
- **아키텍처 테스트에 음성 fixture가 있다.** request-fanout 금지 fixture 3개 거부(`tests/architecture/request-fanout.test.ts:37-44`), 다른 앱 기능이 섞인 번들 거부(`tests/architecture/app-build-input.test.ts:56` 이후), vendor SDK 규칙의 정규식 의미 확인(`tests/architecture/observability-boundaries.test.ts:166-185`).
## 4. 발견 사항 (36.3)
### 11-01 런북 drill이 복구를 하지 않고, 일부 단언이 상수 `true`라서 앱이 깨진 빌드에서도 PASS한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 28, 7, 10, 21, 24 |
| 근거 | `scripts/drill-runbook.ts`: FE-RB-001 `:118-120` `injectedMountFailure = true`라서 `negativeFixtureFailedAsExpected`가 항상 true. "product root mount" 근거는 runtime schema parse 성공(`:126`). FE-RB-002 "entry and lazy assets reachable"·"critical route smoke"는 `dist/index.html`·`dist/.vite/manifest.json` 파일 존재 확인(`:162-166`, `:173`, `:180`). FE-RB-003 `triggerAsserted: true`(`:199`), "failure rate at baseline" `true`(`:202`). FE-RB-004 "product flow unaffected" `true`(`:241`). FE-RB-005 `triggerAsserted: true`(`:271`), "critical smoke" `true`(`:276`). FE-RB-005 명세는 "이전 불변 tuple 선택 → 호환성 확인 → 원자적 전환 → smoke"인데(`config/runbooks/runbooks.json` FE-RB-005 `containment`), drill은 현재 `dist`의 tuple 정합성과 고정된 음성 tuple 하나만 본다. `providerVerificationRequired: true`는 record에만 남고 읽는 곳이 없다. `PROD_PROMOTION_READY`는 FE-GATE-016·021~025의 PASS만 본다(`scripts/lib/promotion-readiness.ts:27-34`, `:50-51`). FE-GATE-016과 FE-GATE-025는 같은 `drill:runbook -- FE-RB-005`를 실행한다(`config/ci/gates.json` `drill-runbook`). 문서는 "positive fixture 통과와 의도적 negative fixture 거부가 있어야 검증된 통제"라고 적는다(`docs/testing/taxonomy.md:80-82`). **실행:** 분리 worktree에서 빌드 후 5개 PASS. `dist/assets/*.js`를 전부 지운 뒤에도 5개 PASS, FE-RB-002 record의 복구 단언 4개 모두 `passed: true` |
| 발생 조건 | `workflow_dispatch` stage `production`/`field`에서 production gate job 실행(`.gitea/workflows/quality-gates.yml:370-384`) |
| 영향 | 운영 승격 단계가 복구 능력을 확인하지 않고 통과한다. 다운스트림은 "drill PASS"를 복구 연습 증거로 받아들인다. 같은 drill이 두 게이트 ID로 두 번 세어진다 |
| 심각도·우선순위 | Medium · P1 — 사용자 데이터 피해는 없다. 하지만 운영 승격 게이트가 거짓 PASS를 내는 구조가 템플릿 기본값으로 복제된다. "운영 승격 준비"를 주장하기 전에 고쳐야 한다 |
| 통제·증거 | 목표 M3 / 확인 M1(런북 문서만 유효) · E3(worktree 실험) |
| 확실성과 남은 가정 | 정적 확인과 실행이 일치한다. provider(호스팅)는 repo 밖이라 실제 전환 리허설을 템플릿이 전부 할 수 없다는 점은 인정한다. 문제는 할 수 없는 부분을 PASS로 적는 것이다. 영역 13(릴리스 스크립트)과 겹칠 수 있다 |
| 최소 개선 방향 | (1) 상수 `true` 단언을 없앤다. 로컬에서 확인할 수 없는 단언은 `UNVERIFIED`로 적고, 하나라도 있으면 gate 결과를 `UNVERIFIED`로 낸다(`GateResult`에 이미 `UNVERIFIED`가 있다, `promotion-readiness.ts:39`). (2) 로컬에서 가능한 부분은 실제로 한다: 두 release 디렉터리와 active pointer를 로컬 정적 서버로 흉내 내고, 전환 후 Playwright smoke(부트 1회·route 1개)를 돌린다. (3) FE-GATE-016/025 중복을 정리한다. 대안: drill 이름을 "사전 조건 검사"로 바꾸고 승격 공식에서 뺀다 |
| 비용·부작용 | 로컬 smoke 추가 시 브라우저 설치가 production gate job에 필요하다. `UNVERIFIED`로 바꾸면 현재 `PROD_PROMOTION_READY`가 false가 된다(의도된 결과) |
| 완료 기준 | JS 자산이 없는 `dist`에서 FE-RB-002·FE-RB-005가 실패한다. provider 없이 실행하면 PASS가 아니라 UNVERIFIED가 나온다. 코드에 상수 `true` 복구 단언이 없다 |
| 검증 방법 | 위 실험(자산 삭제 후 drill 실행)을 다시 한다. drill 단위 테스트에 "깨진 dist → 실패" 케이스를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 11-02 라우트별 axe 검사와 상태 화면 visual 검사가 lazy route의 로딩 화면을 검사한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 9 (가이드 32.3 접근성) |
| 근거 | `tests/e2e/accessibility.spec.ts:12-16`은 goto → `main` 표시 확인 → axe 순서다. `main`은 앱 셸이 먼저 그리고, route 청크가 오기 전에는 로딩 화면("화면을 준비하고 있습니다.")이 들어 있다. **프로브:** 같은 순서로 실행하면 `/`, `/examples/ui`, `/examples/states`, `/examples/platform` 모두 axe 검사 노드 74~79개, 검사한 h1 0개. h1을 기다린 뒤에는 106/374/182/351개. **변이:** 상태 화면에 alt 없는 `img`와 이름 없는 `button`을 넣고 같은 빌드로 spec을 반복했다. 1차 24/24 검출, 2차 Chromium 0/3, 3차 Chromium 1/5·Firefox 5/5·WebKit 5/5. 보호 라우트 4개(`/examples/reference-resources*`)는 로그인하지 않아 "세션이 필요합니다" 화면만 검사한다. **visual:** `tests/visual/platform.visual.spec.ts:35-43`은 기다리지 않고 `main`을 찍는다. 기준 이미지 `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/state-surfaces-light-chromium-visual-linux.png`(1040×1028)가 로딩 화면 자체다. 실행 결과 5/5 통과 |
| 발생 조건 | 라우트 청크가 axe 실행 전에 도착하지 않을 때. 러너 부하·엔진에 따라 달라진다 |
| 영향 | a11y 게이트(FE-GATE-009)가 페이지 본문 위반을 실행마다 다르게 잡는다. 거짓 통과가 나거나, 관계없는 PR에서 갑자기 실패한다. reference feature 목록·상세·폼은 자동 axe 대상이 아니다. visual의 상태 화면 계약은 비어 있다. 다운스트림은 이 패턴을 자기 라우트에 그대로 복제한다 |
| 심각도·우선순위 | Medium · P2 — 보안·데이터 피해는 없다. 접근성 회귀 검출이 우연에 맡겨지고 샘플로 복제된다 |
| 통제·증거 | 목표 M3 / 확인 M2(검사는 있으나 대상이 불안정) · E3 |
| 확실성과 남은 가정 | 변이 검출률이 실행마다 바뀐 것을 직접 확인했다. CI 러너에서의 검출률은 미확인 |
| 최소 개선 방향 | axe·스크린샷 전에 `await expect(page.getByRole("heading", { level: 1 })).toBeVisible()`처럼 route 본문이 그려졌음을 확인한다. 보호 라우트는 데모 로그인 뒤 검사하는 케이스를 추가한다. 상태 화면 기준 이미지를 다시 만든다 |
| 비용·부작용 | 한 줄 대기 추가. 기준 이미지 1장 재생성 |
| 완료 기준 | 같은 변이를 넣으면 3엔진에서 10/10 검출한다. 상태 화면 기준 이미지에 제목과 상태 표면이 보인다 |
| 검증 방법 | 위 변이 실험을 `--repeat-each=10`으로 반복한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 11-03 규모 회귀 게이트는 기준선을 만든 CPU에서만 통과할 수 있고, "CI tier"라는 설명과 달리 어느 CI job에도 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 13, 14, 21, 24 |
| 근거 | `scripts/scale/run-scale-profile.ts:6-13`은 pr/main/nightly/release를 "CI execution tiers"라고 설명한다. workflow에는 schedule 트리거가 없고(`.gitea/workflows/quality-gates.yml:4-21`), `config/ci/gates.json` 명령 목록에 `check:scale:*`·`check:scale:baseline`·`verify:extreme-scale`이 없다. 기준선 비교는 CPU 모델이 다르면 timing을 비교하지 않고 `incomplete`로 끝나며 exit 1이다(`scripts/scale/scale-baseline.ts:202`, `:357`). 기준선 CPU는 `i5-10400F`(`config/scale/benchmark-baseline.json:7`). **실행:** 이 호스트(Core Ultra 7 155H)에서 `check-scale-baseline.ts` → exit 1 `INCOMPLETE`(CPU와 무관한 compiler 16축·absolute 28·growth 8은 모두 통과). 그래서 `baseline-regression` 단계를 포함한 main·nightly·release tier(`run-scale-profile.ts:58-76`, `:78`, `:96`)는 다른 기계와 CI 러너에서 항상 실패한다. 수락 문서의 "24/24 PASS"는 컨테이너 1회 실행 기록이다(`docs/reviews/2026-09-23-extreme-scale-acceptance.md:27-37`) |
| 발생 조건 | 조합 경로의 복잡도 회귀, 요청·telemetry 증폭 회귀 등 규모 속성을 깨는 변경 |
| 영향 | 규모 속성 회귀를 자동으로 잡는 경로가 없다. 다운스트림은 기준선을 자기 기계에서 재승인하기 전에는 이 게이트를 쓸 수 없다 |
| 심각도·우선순위 | Medium · P2 — 규모가 이 템플릿의 선언된 목표 축인데, 그 회귀 검출이 수동 1회 기록에 머문다 |
| 통제·증거 | 목표 M3 / 확인 M1(스크립트와 기록만) · E3 |
| 확실성과 남은 가정 | 일반적인 "CI에 연결되지 않은 테스트" 문제는 12-04와 같은 원인이다. 여기서는 규모 게이트 고유의 기계 결합 문제만 적는다. **12-04 보정:** `tests/architecture`와 `tests/release`는 FE-GATE-020의 제거 fixture 안에서 `test:all`(→ `test:platform`, `check:release-coherence`)로 간접 실행된다(`scripts/test-sample-removal.ts:321`, `scripts/test-realtime-runtime-removal.ts:122`, `scripts/test-optional-recipe-removal.ts:68`, `scripts/test-browser-file-storage-runtime-removal.ts:139`). 전혀 실행되지 않는 것은 `tests/scale/`, `tests/scripts/`, scale tier 스크립트다 |
| 최소 개선 방향 | (1) CPU와 무관한 축(compiler count, growth shape, 요청 증폭 비율)만으로 된 tier를 PR 게이트에 넣는다. 이 축들은 지금도 다른 CPU에서 통과한다. (2) timing 비교는 기준선과 같은 러너 라벨에서만 도는 별도 job으로 나누고, 기준선 재승인을 러너 기준으로 한다. (3) `run-scale-profile.ts` 설명의 "CI" 표현을 실제와 맞춘다 |
| 비용·부작용 | PR 게이트 시간 증가(PR tier는 이 호스트에서 수 초~수십 초 규모). timing job에는 고정 러너가 필요하다 |
| 완료 기준 | PR에서 CPU 무관 scale tier가 실행되고 증거가 남는다. 다른 CPU에서도 exit 0이며 timing은 advisory로 기록된다 |
| 검증 방법 | 기준선과 다른 CPU에서 PR tier를 실행해 exit 0을 확인한다. 조합 workload에 이차 누적을 일부러 넣으면 PR tier가 실패하는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 (관련: 12-04) |
### 11-04 규모 증거는 이름만 다른 stub 기능으로 만든 것이라, 선언된 앱당 상한(20 × 200)의 실제 비용은 측정되지 않았다
| 필드 | 내용 |
|---|---|
| 성격 | 미검증 |
| 관련 관점 | 13, 14 (가이드 13절 "과장 방지", 30.6) |
| 근거 | 디스크 fixture 기능은 파일 3개에 `PAGE = "<id>-page"` 문자열뿐이다(`tests/scale/filesystem-topology.ts:24-37`). App A는 100개(`:15`). tsc fixture는 React·zod·플랫폼 계약을 import하지 않는 독립 모듈이다(`scripts/scale/collect-tsc-diagnostics.ts:74-97`). 기준선에서 실제 앱(기능 1개) instantiations는 699,730, toy 기능 400개는 33,998이다(`config/scale/benchmark-baseline.json:100-125`). S3/S4(10만·100만)는 개수만 저장하는 in-memory 모델(`tests/scale/synthetic-topology.ts:43-49`)과 분할 산술(`tests/architecture/topology-cardinality.test.ts:72-99`)이다. 선언된 상한: `CONTEXT_MAX_FEATURES = 200`(`src/contexts/reference-context/context-module.ts:9`), `APP_MAX_CONTEXTS = 20`(`src/apps/template-app/app-module.ts:6`) → 앱당 4,000 |
| 발생 조건 | 다운스트림이 한 앱에 실제 기능을 수백 개 이상 넣을 때 |
| 영향 | **증명하는 것:** 생성기가 선택한 앱의 선언만 읽는다(지역성). 조합·조회 알고리즘이 선형이다. 요청 증폭에 상한이 있다. **증명하지 않는 것:** 실제 기능 모양으로 한 앱의 기능이 늘 때 타입 검사·빌드·번들·테스트 시간, route 수, 메모리. 상한 값이 "검증된 수용 범위"로 읽힐 수 있다. 실제 비용의 중심(기능 1개 앱이 이미 70만 instantiation)은 측정 밖이다 |
| 심각도·우선순위 | Medium · P2 — 이 repo의 규모 목표가 기능 수 축이다. 측정한 축과 조건이 문서에 분리돼 있지 않다 |
| 통제·증거 | 목표 M3 / 확인 M1(상한 선언과 상한 초과 거부만 M3) · E2 |
| 확실성과 남은 가정 | 수락 문서는 "전역 증가에도 한 앱은 변하지 않는다"를 주장하며, 그 주장 자체는 증거와 맞다. 앱 내부 증가 비용은 주장하지 않았지만 상한 값의 근거도 적혀 있지 않다 |
| 최소 개선 방향 | reference feature를 복제한 실제 모양의 기능(이름·ID만 바꾼 것) 25/100/400개로 앱 1개를 만들어 `tsc --extendedDiagnostics`, `vite build` 시간, 초기·lazy 청크 크기를 측정하고 기준선에 넣는다. 수락 문서에 "검증한 증가 축 / 조건 / 검증하지 않은 축" 표를 둔다 |
| 비용·부작용 | fixture 생성기 1개와 측정 시간(수 분). 기준선 재승인 |
| 완료 기준 | 실제 모양 기능의 로컬 증가 측정이 기준선에 있고, 상한 값의 근거 범위가 문서에 적혀 있다 |
| 검증 방법 | 측정을 두 번 돌려 증가 곡선과 분산을 기록한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 11-05 release 테스트의 "구 자산 도달성"은 테스트 fixture 자신을 검사하고, 기본 구성의 구 탭 청크 복구는 실제 브라우저에서 확인되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 18, 10, 24 |
| 근거 | `tests/release/old-asset-reachability.test.ts:1-3`은 `release-fixture.ts`만 import한다. 테스트 4개 모두 테스트 코드인 `createReleaseFixture().fetch`(`tests/release/release-fixture.ts:87-160`)의 동작을 확인한다. 제품 코드나 배포 스크립트는 호출하지 않고, 읽는 설정은 `config/hosting/cache-policy.json`뿐이다. 수락 문서 17행은 "old-asset reachability를 검증한다"고 적는다(`docs/reviews/2026-09-23-extreme-scale-acceptance.md:23`). 기본 구성은 `serviceWorker: null`이다. 이때 구 탭 → 청크 404 → `ChunkRecoveryBoundary` → 1회 reload 흐름은 실제 브라우저에서 오류 문구 분류만 확인하고(`tests/browser-capabilities/chunk-load-error.spec.ts:7-29`), 나머지는 jsdom 컴포넌트 테스트다. 실제 두 빌드 공존 테스트는 SW ACTIVE 구성에만 있다(`tests/e2e/service-worker-update.spec.ts:207-247`). 자산 보존은 repo 밖 provider 책임이다(`docs/operations/release-cache-rollback.md:3-7`) |
| 발생 조건 | 기본 구성으로 배포한 뒤, 이전 빌드를 연 탭이 lazy route로 이동할 때 |
| 영향 | 문서 주장보다 증거가 좁다. 가이드 32절의 "새 배포 후 기존 탭" 시나리오가 기본 구성에서 실제 브라우저로 끝까지 돈 적이 없다. 청크 오류 문구나 reload 동작이 브라우저마다 달라도 jsdom 테스트는 통과한다 |
| 심각도·우선순위 | Low · P2 — 부트 정합성(fail-closed)은 실제 loader로 확인된다. 남은 것은 기본 구성의 복구 흐름과 문서 표현이다 |
| 통제·증거 | 목표 M3 / 확인 M2(부트 정합성 M3, 구 탭 복구 M2) · E2 |
| 확실성과 남은 가정 | 컴포넌트 테스트(`tests/component/chunk-recovery-boundary.test.tsx`)는 이 영역 밖이라 내용 확인은 이름·일부 줄만 했다 |
| 최소 개선 방향 | old-asset 테스트를 "fixture 계약"으로 이름을 낮추거나 지운다. SW 없이 빌드 A·B를 번갈아 제공하는 Playwright 테스트를 1개 추가한다(`tests/e2e/support/service-worker-builds.ts` 재사용): A 탭에서 B 배포 후 A 전용 청크가 404이면 1회 reload 뒤 B로 부팅하고, 두 번째 실패에서는 reload하지 않는다 |
| 비용·부작용 | 두 번 빌드하는 테스트 1개(SW 테스트와 빌드 공유 가능) |
| 완료 기준 | 기본 구성의 구 탭 복구가 3엔진 실제 브라우저에서 한 번 이상 끝까지 확인된다. 문서 17행이 실제 증거 범위와 맞다 |
| 검증 방법 | 새 spec에서 reload 가드를 일부러 끄면 실패하는지 확인한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 11-06 핵심 사용자 흐름 E2E가 "보호 화면이 열린다"까지만 확인한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 6 (가이드 30.5 샘플 대표성) |
| 근거 | `tests/e2e/reference-route.spec.ts:21-31`은 제목과 "인증됨"만 확인하고, 목 데이터 "Browser reference"가 화면에 나오는지 보지 않는다. **변이:** 목 응답을 스키마 위반 200(`[{ wrong: true }]`)으로 바꿔도 통과했고 화면은 오류 문구를 보였다. 503으로 바꾸면 spec 단언이 아니라 공용 fixture의 콘솔 오류 검사(`tests/support/browser/strict-browser-test.ts:41`)로만 실패했다. `tests/e2e/reference-form.spec.ts:12-50`은 검증 실패·취소 확인·320px만 본다. 저장 성공, 실패 후 재시도, 로그아웃, 세션 만료 브라우저 테스트는 없다. 같은 흐름의 로직은 jsdom 컴포넌트 테스트에 있다(`tests/features/reference-feature/reference-page.test.tsx:163-446`) |
| 발생 조건 | 운영 빌드에서만 생기는 연결 오류(매퍼, base URL, codec 번들링 등)로 목록·저장이 항상 오류가 되는 변경 |
| 영향 | 그런 변경이 E2E를 통과한다. 템플릿의 샘플 E2E가 약한 단언 패턴을 가르친다 |
| 심각도·우선순위 | Low · P2 — 흐름 로직은 컴포넌트 테스트가 다루고, HTTP 오류는 공용 fixture가 잡는다. 남는 것은 운영 빌드 전용 결함의 검출이다 |
| 통제·증거 | 목표 M3 / 확인 M2 · E3 |
| 확실성과 남은 가정 | 변이 결과는 직접 확인했다 |
| 최소 개선 방향 | reference-route에 `getByText("Browser reference")` 단언을 추가한다. 저장 성공(POST 목 → 목록 또는 상세로 이동)과 실패 → 재시도 E2E를 1개씩 추가한다 |
| 비용·부작용 | spec 2개, 3엔진에서 수 초 |
| 완료 기준 | 위 두 변이(스키마 위반 200, 503)에서 spec 단언이 실패한다. 저장 성공과 재시도가 브라우저에서 한 번씩 돈다 |
| 검증 방법 | 같은 변이 실험을 다시 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 11-07 lab 성능 게이트가 1회 측정이고, 상호작용 지표에 Playwright 왕복 시간이 들어가며, 측정 대상 서버를 확인하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 14, 10, 24 |
| 근거 | `scripts/test-performance.ts:55-101`은 브라우저를 한 번 실행해 한 번 잰다. 반복·중앙값이 없다. `namedInteractionMs`는 Node의 `performance.now()`로 잰 `click()` + `heading.waitFor()` 시간이다(`:92-101`). CDP 왕복과 lazy 청크 다운로드(200KB/s)가 포함된다. 이 값을 INP와 같은 200ms 예산과 비교한다(`config/performance/budgets.json:10`). 기록에는 브라우저 버전·Node·플랫폼·네트워크·CPU 감속 배율·캐시 상태가 있지만 CPU 모델·코어 수·호스트 부하가 없다(`:108-124`). 4배 감속의 기준 기계를 알 수 없다. 서버는 `pnpm preview --port 4173`이고 `--strictPort`가 없다(`:27-32`). 4173이 이미 쓰이면 vite는 다른 포트로 뜨고, 스크립트는 4173에 떠 있는 다른 서버를 잰다. 빌드 식별값은 응답이 아니라 로컬 `dist/release-manifest.json`에서 읽는다(`:48-50`). **실행**(포트만 바꿈, loadavg 17~28/22스레드): 6회 모두 FAIL. interaction 326~1103ms, LCP 1820~2740ms. 같은 빌드에서 interaction이 3.4배 흔들렸다 |
| 발생 조건 | 러너 부하 변동, 공유 러너, 포트 충돌 |
| 영향 | 릴리스 게이트(FE-GATE-026) 판정이 러너 상태에 따라 뒤집힌다. 사람이 다시 돌려 통과시키면 숨은 재시도가 된다. 지표 이름("interaction")과 실제 측정 내용이 다르다 |
| 심각도·우선순위 | Medium · P2 — 릴리스 판정 게이트다. 사용자 피해는 없지만 판정 신뢰도가 낮다 |
| 통제·증거 | 목표 M3 / 확인 M2 · E3(부하 높은 호스트) |
| 확실성과 남은 가정 | 이 호스트는 다른 에이전트가 동시에 돌던 중이라 실제보다 느렸을 수 있다. 조용한 CI 러너에서 통과하는지는 미확인이다. 분산이 크다는 점과 기록 항목 누락은 부하와 무관하다 |
| 최소 개선 방향 | 5~9회 반복해 중앙값과 분산을 기록한다. 상호작용은 페이지 안 `PerformanceObserver`의 event entry(INP 근사)나 페이지 내부 시계로 잰다. CPU 모델·코어 수·loadavg를 기록한다. `--strictPort`를 쓰고 응답 HTML의 build-id를 확인한다 |
| 비용·부작용 | 게이트 시간이 수십 초 늘어난다 |
| 완료 기준 | 같은 빌드를 10회 돌려 판정이 뒤집히지 않거나, 뒤집힐 때 분산이 증거에 남는다. 다른 서버가 4173에 있으면 실패한다 |
| 검증 방법 | 반복 측정 결과의 분산 비교. 4173에 다른 서버를 띄운 상태에서 실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 11-08 Playwright에 `test.only` 차단과 quarantine 만료 검사가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 21, 10, 26 |
| 근거 | `forbidOnly: true`는 `playwright.capabilities.config.ts:5`에만 있다. `playwright.config.ts`, `playwright.visual.config.ts`, `playwright.storybook.config.ts`에는 없다(Playwright 기본값 false). ESLint에 focused test 규칙이 없다. skip 검사는 파일 안에 quarantine 주석 형식이 하나라도 있는지만 본다(`scripts/check-test-evidence.ts:288-294`). `expires` 날짜가 지났는지 확인하지 않고, 주석 하나가 같은 파일의 모든 skip을 허용한다 |
| 발생 조건 | `test.only`가 섞인 커밋, 만료된 quarantine |
| 영향 | e2e·a11y·visual 게이트가 테스트 하나만 돌고 통과한다. 만료된 quarantine이 계속 통과한다 |
| 심각도·우선순위 | Low · P3 — 실수 한 번이 필요하고, 리뷰로도 잡을 수 있다 |
| 통제·증거 | 목표 M3 / 확인 M2(capability만 M3) · E1 |
| 확실성과 남은 가정 | 정적 확인. 실행하지 않았다 |
| 최소 개선 방향 | 모든 Playwright 설정에 `forbidOnly: true`. quarantine `expires`를 오늘 날짜와 비교하고, skip 호출마다 바로 위 줄 quarantine을 요구한다 |
| 비용·부작용 | 설정 3줄, 검사 수 줄 |
| 완료 기준 | `test.only`를 넣으면 e2e가 실패한다. 지난 날짜 quarantine이 실패한다 |
| 검증 방법 | 음성 fixture(`tests/fixtures/test-evidence/forbidden`)에 두 경우를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 다른 영역 — src 담당 영역 | — | — | 적용 제외 |
| 2 | 구조적 성숙도 | 다른 영역 — 12 | — | — | 적용 제외 |
| 3 | 변경 용이성 | 적용 — 테스트가 기능 추가·삭제를 따라가는가 | M2 / M2 | E1: 기대값을 설치된 레지스트리에서 읽음(`tests/e2e/platform-overview.spec.ts:5-9`, `accessibility.spec.ts:5-8`) | 충족 |
| 4 | 인지 부하 | 적용 — "어느 테스트가 어디서 도는가" | M1 / M1 | E1: `docs/testing/taxonomy.md`가 위치 규칙 제공 | 부분 충족 — `tests/architecture`·`tests/release`는 제거 fixture 안에서만 CI 실행, scale tier는 CI 없음(11-03, 12-04) |
| 5 | 위험 가시성 | 다른 영역 — src 담당 영역 | — | — | 적용 제외 |
| 6 | 실패 성숙도 | 적용 — 실패 주입 테스트 | M3 / M3(단위), M2(브라우저) | E2: scale traffic이 실제 executor로 전면·반복 장애 증폭 상한 확인 | 부분 충족 — 브라우저 수준 실패 복귀 없음(11-06) |
| 7 | 운영 성숙도 | 적용 — production drill 게이트 | M3 / M1 | E3 | 미충족 — 11-01 |
| 8 | 디버깅 가능성 | 적용 — 테스트 실패 진단 | M2 / M2 | E1: trace·screenshot `retain-on-failure`, junit, 게이트 로그 | 부분 충족 — 공용 fixture가 `pageerror`를 이름만 기록(`strict-browser-test.ts:27`)해 메시지가 빠진다 |
| 9 | 유지보수 성숙도 | 적용 — 기준 이미지·기준선 관리 | M2 / M2 | E1: 기준선 재승인에 owner·reason 요구 | 부분 충족 — visual 기준 이미지 1장이 로딩 화면(11-02) |
| 10 | 테스트 성숙도 | 적용(중점) | M3 / M2 | E3 | 부분 충족 — retry 0과 strict fixture는 좋다. 11-02, 11-05, 11-06, 11-08. `tests/scale/composition-scale.test.ts:47-48`의 재측정 1회는 의도가 주석에 있다 |
| 11 | 데이터 성숙도 | 적용 제외 — 이 영역에 데이터 이관·보관 경로 없음(IndexedDB capability 테스트 자체는 02 영역 대상) | — | — | 적용 제외 |
| 12 | 동시성 성숙도 | 적용 — 여러 탭 | M3 / M3(어댑터) | E1(이번에 실행 안 함) | 충족(어댑터 범위) — 실제 두 페이지로 BroadcastChannel·storage event·IDB versionchange 확인. 앱 전체 여러 탭 E2E는 없음 |
| 13 | 확장성 | 적용(중점) | M3 / M1 | E3 | 부분 충족 — 지역성·선형성·증폭 상한은 증거 있음. 앱 내부 증가는 미측정(11-04), 회귀 게이트는 기계 결합·CI 없음(11-03) |
| 14 | 성능 성숙도 | 적용(중점) | M3 / M2 | E3 | 부분 충족 — scale 기준선은 조건 기록 양호. lab 게이트는 1회 측정·조건 누락(11-07). field는 입력이 없으면 설계상 `FAIL_UNVERIFIED`(`performance-evidence.md:13-22`) |
| 15 | 보안 성숙도 | 다른 영역 — 12·13 (`tests/system`은 CI 러너·공급망 검증) | — | — | 적용 제외 |
| 16 | 의존성 성숙도 | 적용 — 브라우저 엔진 고정 | M2 / M2 | E2: Playwright 1.62.0 고정, CI가 3엔진 설치(`quality-gates.yml:67-69`) | 충족 |
| 17 | API / Contract | 다른 영역 — 03 | — | — | 적용 제외 |
| 18 | 배포 성숙도 | 적용(중점) — 신·구 버전 공존 | M3 / M2 | E2 | 부분 충족 — 부트 정합성은 실제 loader(M3), SW 구성 공존은 실제 브라우저. 기본 구성 구 탭 복구·자산 보존은 fixture·jsdom 수준(11-05) |
| 19 | 설정 성숙도 | 적용 — 테스트 서버 설정 | M2 / M2 | E1 | 부분 충족 — 포트 고정, `reuseExistingServer: false`, lab 성능은 `--strictPort` 없음(11-07) |
| 20 | 개발자 경험 | 적용 — 테스트 하나 실행 | M2 / M2 | E3 | 부분 충족 — spec 하나도 매번 전체 빌드(`playwright.config.ts:17-18`). 비TTY에서 `corepack pnpm build`가 deps 검사로 install을 시도하다 중단됨(관찰). `verify-extreme-scale.ts:204`만 이를 끈다(14 영역과 겹침) |
| 21 | Guardrail 성숙도 | 적용(중점) | M3 / M2 | E3 | 부분 충족 — 아키텍처 음성 fixture·capability 증거 검사는 실제 위반을 잡는다. 11-02, 11-08, 12-04 |
| 22 | 추상화 성숙도 | 적용 제외 — 테스트 헬퍼가 얇고 판정할 추상화 없음 | — | — | 적용 제외 |
| 23 | 일관성 | 적용 — 공용 fixture 사용 | M2 / M2 | E1: 한 곳(`chunk-load-error.spec.ts`)만 기본 `test`를 쓰며 오류를 일부러 내는 이유가 주석에 있음 | 충족 |
| 24 | 네이밍 / 의미 | 적용 — 게이트·지표 이름 | M1 / M1 | E1 | 미충족 — "drill"(11-01), INP 예산과 비교되는 "interaction"(11-07), "CI execution tiers"(11-03), "old-asset reachability"(11-05) |
| 25 | 조직 확장성 | 다른 영역 — 14 (1인 관리, 구조적 준비만) | — | — | 적용 제외 |
| 26 | Ownership | 적용 — quarantine·기준선 책임 | M2 / M2 | E1: quarantine에 owner·expires, 기준선에 승인자 | 부분 충족 — 만료일 미검사(11-08) |
| 27 | 삭제 가능성 | 다른 영역 — 14 (제거 fixture) | — | — | 적용 제외 |
| 28 | 회복 가능성 | 적용(중점) — runbook drill | M3 / M1 | E3 | 미충족 — drill이 복구를 하지 않고 상수 `true` 단언으로 PASS(11-01) |
## 6. 미검증 목록
- **CI 러너에서의 실제 결과.** 게이트 실행 이력을 볼 권한이 없다. 11-02의 검출률과 11-07의 통과 여부는 CI 러너에서 다시 재야 한다. 필요한 것: 같은 커밋에서 FE-GATE-008/009/026 반복 실행 기록.
- **e2e·a11y·browser-capabilities·storybook 전체 실행.** spec 1개(reference-route)와 a11y 1개 케이스, visual만 실행했다. 필요한 것: 조용한 호스트에서 `test:e2e`, `test:a11y`, `test:browser-capabilities`, `test:storybook` 1회씩.
- **`service-worker-update.spec.ts`.** 빌드를 두 번 해야 해서 실행하지 않았다. 강점 3은 코드 읽기(E1) 기준이다.
- **browser soak(`check:scale:nightly`).** 120초 Chromium 1개 탭 조건이다. 더 긴 세션, Firefox·WebKit, 실제 API 성공 경로 soak은 없다. 필요한 것: 30분 이상 soak 1회와 heap 곡선.
- **`test:system`.** systemd·bubblewrap·cgroup v2 호스트가 필요하다. 이번 호스트에서 전제 확인을 하지 않았다.
- **lab 성능의 조용한 환경 값.** 이번 6회 측정은 부하가 높은 호스트에서 했다. 필요한 것: 부하 없는 기계에서 10회 반복.
- **field Web Vitals.** 개인정보 승인·표본 기준이 정해지지 않아 설계상 `FAIL_UNVERIFIED`다. 결함이 아니라 미정 상태다.
- **`tests/component/chunk-recovery-boundary.test.tsx`의 내용.** 11-05 판단에 필요한 부분만 이름 수준으로 확인했다(다른 영역 범위).
@@ -0,0 +1,325 @@
# 가드레일·CI 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `scripts/check-*.ts`(29개, 5.5k줄), `scripts/check-architecture.ts`(1.1k), `scripts/run-ci-gate.ts`, `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts`, `scripts/lib/`의 CI·검사 관련 파일, `.gitea/workflows/quality-gates.yml`(460), `config/ci/gates.json`(2.9k), `config/architecture/`, `config/testing/`, `config/schemas/`, `.dependency-cruiser.json`, `eslint.config.ts`(868), `tsconfig*.json`, `package.json` 검사 스크립트. `scripts/` 전체 규모(141파일·31.7k줄)는 비용 평가에만 사용했다. 빌드·릴리스·공급망 스크립트 자체는 영역 13.
> 영역 판정(35.8): **조건부 사용 가능** — 로컬 `check:architecture`는 직접 import 위반을 실제로 막는다. 다만 이 repo의 CI는 호스트에서 꺼져 있어 머지를 막지 않고, 생성된 workflow는 release-admission 게이트를 실행하지 않는다. 릴리스 파이프라인 용도로는 12-02를 고치기 전까지 사용 보류.
## 1. 결론
- **머지를 막는 장치가 없다.** Gitea 저장소 설정이 `has_actions: false`다. `main` HEAD와 PR #2의 커밋에 CI 상태가 하나도 없고, PR #2는 그대로 머지됐다. 27개 게이트는 작성자가 로컬에서 돌릴 때만 동작한다(12-01).
- **생성된 workflow가 FE-GATE-027(release-admission)을 실행하지 않는다.** 생성기가 matrix가 아닌 job에서 첫 게이트만 실행한다. 그래서 `APP_PROFILE`이 비어 로컬·demo 인증으로 빌드된 후보도 promotion까지 간다(12-02).
- **직접 import 위반은 막힌다.** worktree에서 위반 17건을 넣어 보았다. presentation→adapter 직접 import, type-only, 동적 `import()`, 다른 adapter 내부·배럴, 커널을 거친 우회, 배럴 건너뛰기가 모두 `check:architecture`에서 실패했다. 뚫린 것은 네 경로다. 경계 밖 모듈을 거친 재수출, `import.meta.glob`, 2단계 `index.ts`, cross-context-invalidation 예외다(12-03, 12-06, 12-07).
- **CI에 연결되지 않은 검사가 많다.** 테스트 14파일(architecture·release·scripts·features 최상위)과 `check:adapter-inventory` 등 검사 스크립트 10여 개는 어떤 게이트도 실행하지 않는다. 지금은 통과하지만 깨져도 알 수 없다(12-04).
- **유지 비용이 크다.** workflow YAML 460줄을 만들고 검증하는 데 6.4k줄을 쓴다. 그런데도 12-02 버그가 계약 검사 1.2k줄과 스냅샷 테스트를 그대로 통과했다. dependency-cruiser는 매번 실행되지만 0개 모듈을 검사한다(12-05, 12-10).
- 미검증: 호스트의 branch protection 설정(API가 401을 반환), 실제 Gitea runner에서 workflow가 도는지, CI 소요 시간.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상·커밋 | `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 가이드 문서뿐 |
| 읽은 코드·설정 | 위 범위 전체. `check-architecture.ts`, `run-ci-gate.ts`, `check-ci-contract.ts`, `ci-step-result.ts`, `promotion-readiness.ts`, `generate-ci-workflow.ts` 해당부, `ci-gates.ts` 소유권 검사부, `check-design-system.ts`, `check-i18n.ts`, `realtime-boundaries.ts` 정규식부, `check-adapter-inventory.ts` 앞부분. 문서는 `docs/architecture/layers.md`, `VD-01`, `VD-05`, `docs/operations/ci-quality-gates.md` 관련 절, README 검증·CI 절 |
| 실험 | worktree(`scratchpad/12/wt`, 끝나고 삭제)에서 위반 probe 20파일을 넣었다. 그 뒤 `check-architecture.ts`(pnpm exec 대체 shim 사용), 파일별 `eslint`, `check-design-system.ts`를 실행했다. 결과는 12-03 표에 있다 |
| 실행한 명령 | 기준선 `check-architecture.ts` → PASS(373 모듈, 1159 간선, 그래프 회귀 검사 16개, 금지 fixture 9개 거부) · `depcruise --info`와 리포트 → 검사 모듈 0개 · `tsc -p tsconfig.web-worker.json --listFilesOnly` → 0파일 · `tsc -p tests/fixtures/typecheck/tsconfig.image-cdn-resolve-signal.json` → 기대대로 TS2741 · `node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts tests/unit/ci-step-result.test.ts` → 414/414 통과 · CI 밖 테스트 `tests/architecture tests/release tests/scripts tests/features/{feature-installation-surface,feature-module,product-features-scale}.test.ts` → 14파일 62개 통과 · Gitea 공개 API 읽기(`/repos/…`, `/commits/<sha>/status`, `/pulls/2`) |
| 확인 못 한 것 | branch protection·Actions 실행 이력(토큰 필요, 401). 전체 게이트(오케스트레이터 담당). `tests/scale`(무거움). CI 소요 시간 |
| 참고 | worktree에서 `corepack pnpm check:architecture`를 실행하면 pnpm 11의 의존성 점검이 `pnpm install`을 시도한다. purge 확인 단계에서 중단됐고 원본 `node_modules`는 바뀌지 않았다. 그래서 이후에는 pnpm 없이 실행했다 |
| 직전 리뷰 | 6.0(깨끗한 체크아웃에서 게이트 실패)은 모든 스크립트에 생성 단계를 붙여 고쳐졌다. 재발은 없다. 다만 그 결함이 main에 머지된 원인(CI 미실행)은 12-01로 남아 있다. 6.7-12(contracts→presentation/bootstrap 규칙)는 `.dependency-cruiser.json`에 추가된 것을 확인했다 |
## 3. 확인된 강점
- **import 그래프가 실패 쪽으로 닫혀 있다.** 다음 경우는 모두 게이트 실패다. 해석 안 되는 import, 파싱 실패, 문자열이 아닌 `import()`·`require()`, 로컬 JS 확장자 specifier, 지원하지 않는 규칙 모양(`reachable` 등). 근거: `scripts/check-architecture.ts:462-510`, `:799-815`. 회귀 fixture 16개가 매 실행마다 검출력을 다시 확인한다(`:821` 이후). 실험에서 직접 위반 13건을 모두 잡았다.
- **음성 fixture는 "정해진 방식으로 실패"해야 통과한다.** 종료 코드와 진단 ID가 둘 다 맞아야 한다(`scripts/lib/ci-step-result.ts:37-80`). 검사기가 다른 이유로 죽으면 통과로 치지 않는다. 타입 fixture 22개, i18n·diagnostics·design-system·registry fixture가 이 방식이다.
- **workflow와 설정이 어긋나면 잡는다.** `check:ci`가 FE-GATE-010 안에서 workflow를 다시 생성해 비교한다. action은 전체 SHA로 고정한다(`scripts/contracts/ci-gates.ts` action 검사). 설치는 `--frozen-lockfile --ignore-scripts`이고, `permissions: contents: read`, `persist-credentials: false`다.
- **TypeScript `paths`를 경계로 쓰지 않는다([S4]).** 어느 tsconfig에도 `paths`가 없고 Vite alias도 없다. alias를 새로 넣으면 그래프가 unresolved로 실패한다. 경로 설정이 조용히 경계를 우회할 수 없다.
- **도구 선택 이유가 기록돼 있다.** TS 7 + ESLint 10 때문에 typescript-eslint와 jsx-a11y를 쓸 수 없다. `VD-01`에 그 이유와 교체 조건이 있다. 버전은 전부 exact pin이고 `.nvmrc`·`packageManager`도 고정돼 있다. `src`·`scripts`에 `eslint-disable`·`@ts-ignore`가 없다.
## 4. 발견 사항 (36.3)
### 12-01 이 repo에서 CI가 실행되지 않아 게이트가 머지를 막지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10, 26, 9 |
| 근거 | Gitea API `GET /repos/donghyeon.kang/clean-architecture-frontend-template` → `has_actions: false`, `default_branch: main`. `4626b73`(main HEAD), `38020da`·`d7fc464`(PR #2 커밋)의 `/status`가 모두 `total_count: 0`. PR #2는 `merged: true`. 문서는 required check 설정을 repo 밖 책임으로 두고(`docs/operations/ci-quality-gates.md:379-381`), 전환 전에 staging smoke가 필요하다고 한다(`:201-203`). README는 "No gate is downgraded to a warning"라고 쓴다(`README.md:176`). 추가로 push 트리거가 `develop`뿐이다(`.gitea/workflows/quality-gates.yml:5-6`). 실제 통합 브랜치는 `main`이고 `origin/develop`은 9/20에 멈춰 있다 |
| 발생 조건 | 모든 PR·push. Actions를 켜도 `main`에 직접 push하거나 머지한 결과는 트리거되지 않는다 |
| 영향 | 게이트가 깨진 상태로 main에 들어갈 수 있다. 다운스트림은 그 main을 복사한다. 실제 전례가 있다. 직전 리뷰 6.0(깨끗한 체크아웃에서 architecture·types·unit·component 전부 실패)이 main에 머지돼 있었다 |
| 심각도·우선순위 | High · P1 — 템플릿의 핵심 주장(27개 게이트가 머지를 막음)이 원본에서 실현되지 않는다. 깨진 기본값이 복제된 전례가 있다 |
| 통제·증거 | 목표 M4(required check) / 확인 M1(문서만) · E3(호스트 공개 API 관찰) |
| 확실성과 남은 가정 | Actions 비활성과 상태 0개는 직접 확인했다. branch protection은 401이라 보지 못했다. 과거에 Actions가 켜져 있었는지는 모른다 |
| 최소 개선 방향 | (1) 저장소 Actions와 runner를 켜고 merge 게이트 13개를 required check로 지정한다. (2) push 트리거에 `main`을 추가한다(`gates.json` → 재생성). 호스트 설정이 당장 어렵다면 README에 "이 repo는 CI를 실행하지 않는다, 머지 전 로컬 명령은 X"를 명시하는 것이 최소선이다 |
| 비용·부작용 | runner 1대. merge 게이트 13개가 각자 설치하므로 PR당 시간 비용이 생긴다(미측정) |
| 완료 기준 | 게이트 하나를 일부러 깨뜨린 PR이 머지 불가로 표시되고, `main` push에도 상태가 붙는다 |
| 검증 방법 | 실패 PR 1건과 통과 PR 1건의 상태 API 결과를 남긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 6.0의 재발 방지 조건. 6.0 증상 자체는 해결됨 |
### 12-02 생성된 workflow가 FE-GATE-027(release-admission)을 실행하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 18, 15, 17 |
| 근거 | `config/ci/gates.json:2365-2368`: `immutable_build`는 `["FE-GATE-015","FE-GATE-027"]`를 가진다. `scripts/generate-ci-workflow.ts:200`는 matrix가 아닌 job에서 `job.gateIds[0]`만 실행한다. 결과 workflow `.gitea/workflows/quality-gates.yml:143-144`는 `ci:gate -- FE-GATE-015`만 실행하고, 파일 어디에도 `FE-GATE-027`이 없다. 계약 검사는 "소유"만 보고 "실행"은 보지 않는다(`scripts/contracts/ci-gates.ts:851-853`, `:856-875`). 스냅샷 테스트가 이 결과를 고정한다(`tests/unit/ci-workflow-generation.test.ts`, 414개 통과). `promotion-readiness.ts:23-25`는 027 없이는 RELEASE_READY가 아니라고 하지만, 이 공식은 계약 자기검사에만 쓰인다 |
| 발생 조건 | 태그나 `workflow_dispatch`로 release 이상을 실행할 때. `APP_PROFILE` 변수가 비면 `scripts/generate-runtime-config.ts:72`가 `local` 프로필(AUTH_MODE demo, loopback API)로 빌드한다 |
| 영향 | 로컬·demo 인증 후보가 promotion job까지 통과해 "검증된" 산출물로 올라간다. 이 게이트가 막으려던 경우(`scripts/check-release-admission.ts:13-24`)가 그대로 열려 있다 |
| 심각도·우선순위 | High · P1 — 릴리스 용도의 차단 항목이다. merge 게이트에는 영향이 없다. 지금은 12-01 때문에 CI 자체가 돌지 않아 실제 노출은 없다 |
| 통제·증거 | 목표 M3 / 확인 M1(계약에 명시, 실행 없음) · E2(생성 테스트 통과로 현재 출력 확인) + E1 |
| 확실성과 남은 가정 | 정적으로 확정했다. 실제 promotion 이후의 배포 단계는 repo 밖이다 |
| 최소 개선 방향 | 생성기가 non-matrix job의 `gateIds` 전부를 순서대로 실행하게 한다. 또는 `immutable_build`에 027 전용 step을 추가한다. 계약 검사에 "모든 gate id가 생성된 workflow의 run step에 나타난다"를 넣는다 |
| 비용·부작용 | 스냅샷 1개 갱신. 027은 `RELEASE_TARGET` 미선언 시 실패하므로 release 변수 설정이 필요하다 |
| 완료 기준 | workflow에 `ci:gate -- FE-GATE-027` 실행이 있고, 계약 검사가 그 줄을 지운 변형을 거부한다 |
| 검증 방법 | 생성 테스트에 "gate id 누락" 음성 변형을 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-03 경계 규칙은 직접 간선만 본다 — 경계 밖 모듈을 거친 재수출이 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 2, 10 |
| 근거 | 아래 실험 표. `findArchitectureViolations`(`scripts/check-architecture.ts:707`)는 간선 하나씩만 규칙에 맞춘다. 전이 도달(`reachable`)은 지원하지 않는다(`:799-815`). presentation이 `src/features/<x>/*.ts`(하위 폴더 밖 파일), `src/contexts/**`, `src/apps/**`를 import하는 것을 막는 규칙이 없다. 그 모듈들이 `src/adapters`를 재수출하는 것을 막는 규칙도 없다. 현재 코드에서도 presentation 55개 모듈 중 45개가 adapter에 전이로 닿는다. 경로 예시: `presentation/i18n/catalog.ts → features/installed-feature-messages.ts → .generated/product-feature-index.ts → reference-feature/feature-module.ts → reference-feature/adapters/… → adapters/http/index.ts`. 이 경로는 `.dependency-cruiser.json:190`의 동결 예외를 통과한다 |
| 발생 조건 | lint가 presentation의 직접 import를 막을 때 개발자가 feature 루트·context·app 파일에 `export * from ".../adapters/…"`를 추가하는 경우 |
| 영향 | "presentation은 concrete adapter를 모른다"는 규칙이 CI 통과 상태로 깨진다. adapter 코드가 presentation 테스트와 번들에 딸려 들어간다. 템플릿 규칙이므로 다운스트림도 같은 구멍을 갖는다 |
| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해로 바로 이어지지는 않는다. 경계 위반이 조용히 쌓이는 경로다 |
| 통제·증거 | 목표 M3 / 확인 M3(직접 간선만) · E3(worktree 실험) |
| 확실성과 남은 가정 | 우회 통과는 실행으로 확인했다. 현재의 전이 도달이 의도된 것인지는 동결 예외의 해소 계획(assembly를 bootstrap으로 옮김)에 달려 있다 |
| 최소 개선 방향 | 규칙 두 개를 추가한다. (a) `src/features/*/`의 하위 폴더 밖 파일·`src/contexts`·`src/apps`에서 `src/adapters`로 가는 간선을 금지한다(feature 조립 파일은 명시 목록으로). (b) presentation → `src/apps`·`src/contexts` 금지(현재 `app-router.tsx`는 목록 예외). 전이 검사를 넣고 싶다면 기존 그래프로 presentation→adapters 도달 여부만 계산하는 규칙 1개로 충분하다 |
| 비용·부작용 | 규칙 2개 + fixture 2개. 동결 예외와 겹치는 파일을 목록에 올려야 한다 |
| 완료 기준 | 아래 P4a·P4b probe가 `check:architecture`에서 실패한다 |
| 검증 방법 | `tests/fixtures/architecture/dependency-graph/cross-boundary`에 재수출 fixture를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음(직전 리뷰는 직접 import만 확인) |
실험 결과(21절 우회 경로). 각 probe는 새 파일 하나 또는 둘이다.
| probe | 내용 | `check:architecture` | ESLint |
|---|---|---|---|
| P1 | `presentation/pages` → `adapters/http/index.ts` | 실패(3개 규칙) | 실패 |
| P1b | 같은 경로 `import type` | 실패 | 실패 |
| P1c | 동적 `import("../../adapters/telemetry/index.ts")` | 실패 | **통과** |
| P1d | `import.meta.glob("../../adapters/telemetry/*.ts")` | **통과** | **통과** |
| P1e | feature presentation → `adapters/telemetry` | 실패 | **통과**(lint는 http·storage·auth만 금지) |
| P2 / P2b | `adapters/http` → `realtime/event-codec.ts` / `realtime/index.ts`(상대 경로) | 실패 | 통과 |
| P2c | `adapters/platform`(커널) → `http/index.ts` | 실패 | 통과 |
| P3 / P3c | bootstrap·feature adapter → adapter 내부 파일(배럴 건너뜀) | 실패 | 통과 |
| P3b | `adapters/http/internals/index.ts` 신설 후 bootstrap에서 import | **통과** | 통과 |
| P4a | feature 루트 파일이 `adapters/telemetry` 재수출 → presentation이 import | **통과** | **통과** |
| P4b | `contexts/reference-context`가 재수출 → presentation이 import | **통과** | **통과** |
| P4c | `presentation/adapters/query`가 `query-cache` 재수출 | 실패 | 통과 |
| P5 | `adapters/http`·`web-push` → `cross-context-invalidation/index.ts` | **통과** | 통과 |
| P6 / P6b | `presentation/pages` / feature presentation → `design-system/primitives/core.tsx` (`check-design-system`) | **통과** / 실패 | — |
### 12-04 CI에 연결되지 않은 테스트와 검사가 있고, 그런 누락을 찾는 장치가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 10, 21, 26 |
| 근거 | `gates.json`의 91개 명령(합성 스크립트 포함)에서 닿지 않는 것들이 있다. 테스트 디렉터리: `tests/architecture`(6), `tests/release`(3), `tests/scripts`(2), `tests/features/*.test.ts` 최상위(3), `tests/scale`(14). `test:coverage`는 `tests/platform`까지만 포함한다(`package.json` `test:coverage`). 스크립트: `check:adapter-inventory`, `check:remediation-ledger`, `check:release-coherence`, `check:topology`, `check:traffic`, `check:observability`, `check:request-fanout`, `check:app-build-input`, `check:types:fixture:image-resolve-signal`(음성 fixture) 등. 이 중 일부는 CI 밖 `verify:extreme-scale`만 실행한다(`scripts/verify-extreme-scale.ts:28-45`). `validatePackageScriptGraph`는 `check:ci`의 스크립트 그래프만 본다(`scripts/check-ci-contract.ts:58`). `CLAUDE.md:23`은 `check:adapter-inventory`를 게이트로 나열한다 |
| 발생 조건 | 이 테스트나 검사가 깨지는 변경. 예: 배포 호환 테스트 `tests/release/old-asset-reachability.test.ts`, 경계 테스트 `tests/architecture/observability-boundaries.test.ts`, INVENTORY 불일치 |
| 영향 | 로컬에서 따로 돌리지 않으면 아무도 모른다. 지금은 14파일 62개가 모두 통과한다(실행 확인). 잃는 것은 앞으로의 검출력이다 |
| 심각도·우선순위 | Medium · P2 |
| 통제·증거 | 목표 M3 / 확인 M1 · E2(현재 통과) + E1(CI 미연결) |
| 확실성과 남은 가정 | `tests/scale` 일부는 비용 때문에 의도적으로 뺐을 수 있다. 그 의도는 어디에도 적혀 있지 않다 |
| 최소 개선 방향 | (1) `tests/architecture`, `tests/release`, `tests/scripts`, `tests/features/*.test.ts`를 기존 게이트 명령(`test:unit` 또는 `test:coverage` 경로 목록)에 추가하고, `check:adapter-inventory`와 image fixture를 FE-GATE-010·003에 추가한다. (2) `check-ci-contract`에 "`tests/` 아래 테스트 파일은 어떤 게이트 명령의 경로에 속하거나 명시된 제외 목록(이유 포함)에 있어야 한다"는 검사를 추가한다 |
| 비용·부작용 | 게이트 시간 소폭 증가. 제외 목록 관리 |
| 완료 기준 | CI 밖 테스트·검사 목록이 비어 있거나, 남은 항목마다 이유가 적혀 있다 |
| 검증 방법 | 새 테스트 디렉터리를 임시로 만들면 계약 검사가 실패한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-05 dependency-cruiser가 0개 모듈을 검사하고 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 16, 21, 24 |
| 근거 | `depcruise --info` 결과, TypeScript 트랜스파일러는 `>=2 <7`만 지원하고(설치 7.0.2) babel은 `<8`만 지원한다(설치 8). `check:architecture`가 남기는 `artifacts/quality/dependency-report.json`의 `summary.totalCruised: 0`, `modules: []`. 코드는 이 사실을 주석으로 인정한다(`scripts/check-architecture.ts:114-115`). 그런데 모듈 수가 0이어도 실패하지 않는다. 문서는 여전히 dependency-cruiser가 검사한다고 쓴다(`docs/architecture/decisions/VD-01-typescript-lint-tooling.md` 검증 절 "ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다", `docs/architecture/typescript-state-and-data-flow.md:55`, `docs/architecture/frontend-platform-capability-review.md:68`) |
| 발생 조건 | 항상 |
| 영향 | 실제 규칙 적용은 자체 그래프가 한다. 그래서 지금 규칙이 빠지지는 않는다. 다만 리포트와 문서가 "표준 도구가 검사했다"는 잘못된 증거를 만든다. 자체 그래프를 걷어내거나 고장 나도 dependency-cruiser가 받쳐 줄 거라고 오해하기 쉽다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E2(실행 확인) |
| 확실성과 남은 가정 | 확정 |
| 최소 개선 방향 | 둘 중 하나. dependency-cruiser 실행을 빼고 설정 파일 이름을 규칙 파일로 바꾼다(예: `config/architecture/import-rules.json`). 아니면 `totalCruised === 0`이면 실패하게 하고 TS 7 지원 전까지는 실행을 끈다. 문서 3곳을 고친다 |
| 비용·부작용 | 파일 이름을 바꾸면 문서 참조를 갱신해야 한다 |
| 완료 기준 | 리포트나 문서에 "dependency-cruiser가 검사"라는 주장이 없거나, 실제로 모듈 수가 0보다 크다 |
| 검증 방법 | `dependency-report.json` 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-06 `import.meta.glob`은 import로 인식되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 2 |
| 근거 | `visitSyntaxNode`(`scripts/check-architecture.ts:462-510`)는 import/export 선언, `import()`, `require()`, TS import type만 수집한다. probe P1d가 그래프와 ESLint를 모두 통과했다. `tsconfig.app.json`에 `vite/client` 타입이 있어 타입 검사도 통과한다 |
| 발생 조건 | presentation 등에서 `import.meta.glob("../../adapters/…")`를 쓰는 경우. 현재 `src`에는 사용처가 없다 |
| 영향 | 이 경로로 adapter 모듈을 번들에 끌어와도 어떤 검사도 모른다 |
| 심각도·우선순위 | Low · P3 — 실수로 쓰기보다 의도적으로 우회할 때 쓰는 형태다 |
| 통제·증거 | M0(이 경로에 대해) · E3 |
| 확실성과 남은 가정 | 확정 |
| 최소 개선 방향 | `import.meta.glob` 호출을 발견하면 parse failure로 거부한다(현재 비문자열 `import()`를 다루는 방식과 같다). 쓸 곳이 생기면 그때 패턴을 간선으로 확장한다 |
| 비용·부작용 | 10줄 내외와 fixture 1개 |
| 완료 기준 | P1d가 실패한다 |
| 검증 방법 | `dependency-graph/unresolved` fixture에 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-07 경계 예외가 적힌 이유보다 넓고, 담당·재검토 시점이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 26, 5 |
| 근거 | (1) 배럴 규칙이 모든 adapter 그룹의 2단계 `index.ts`를 공개 배럴로 인정한다(`.dependency-cruiser.json:215`). 적힌 이유는 `storage/indexeddb`·`storage/opfs` 두 곳뿐이다(`docs/architecture/layers.md:64-69`). probe P3b(`http/internals/index.ts`)가 통과했다. (2) `cross-context-invalidation/index.ts` 예외는 모든 adapter에 적용된다(`.dependency-cruiser.json:202`). 그런데 `layers.md:39-44`와 규칙 주석은 "query-cache의 두 타입만, 동결됨, 새 간선은 게이트 실패"라고 쓴다. probe P5(http·web-push → cci)가 통과했다. 소유자 결정상 이것은 kernel 예외이므로 문서 쪽이 틀렸다. (3) `presentation/adapters/query`는 주석 없이 `presentation-does-not-know-adapters`에서 통째로 빠진다(`.dependency-cruiser.json:27`). (4) `pnpm-workspace.yaml:4-8`의 `minimumReleaseAgeExclude`(eslint·playwright)에 이유·만료 조건이 없다. 네 예외 모두 담당자와 재검토 시점이 없다 |
| 발생 조건 | 누군가 새 서브배럴이나 cci 간선을 추가할 때 |
| 영향 | 문서를 믿는 사람은 막힐 거라고 생각하지만 실제로는 통과한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E3 |
| 확실성과 남은 가정 | (1)은 모든 그룹에 서브배럴을 열어 두려는 의도일 수도 있다. 그렇다면 문서만 고치면 된다 |
| 최소 개선 방향 | (1) 도착 정규식을 `^src/adapters/storage/(indexeddb|opfs)/index\.ts$`로 좁힌다. (2) 새 파일 단위 예외는 제안하지 않는다. `layers.md`와 규칙 주석을 "모든 adapter가 쓸 수 있는 kernel 예외"로 고친다. (3)·(4)에는 한 줄 이유를 단다. 예외마다 `comment`에 담당과 재검토 조건을 적는 관례를 둔다 |
| 비용·부작용 | 정규식 1줄, 문서 몇 줄 |
| 완료 기준 | P3b가 실패하거나 문서가 "모든 그룹 허용"으로 맞춰진다. `layers.md`에 "동결" 주장이 남지 않는다 |
| 검증 방법 | barrel fixture에 서브배럴 거부 케이스를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-08 design-system 검사기가 presentation 내부의 deep import를 보지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 23 |
| 근거 | `VD-05`: "제품 코드는 `presentation/design-system/index`만 import한다". 검사는 specifier 문자열에 `presentation/design-system/`이 들어 있을 때만 잡는다(`scripts/check-design-system.ts:110-115`). presentation 안의 `../design-system/primitives/core.tsx`는 이 문자열이 없어 통과한다(P6). 현재 `src/presentation/templates/page-templates.tsx:8-9`와 `src/presentation/components/ui/*.ts` 6개 파일이 이 형태로 import하고, 게이트는 PASS다. fixture는 `../../../../src/presentation/design-system/…` 모양 하나뿐이다 |
| 발생 조건 | presentation 파일에서 design-system 내부를 상대 경로로 import할 때 |
| 영향 | 공개 API를 거치지 않은 사용이 늘어나도 검사는 통과를 보고한다. `components/ui`가 의도된 facade라면 그 사실이 규칙에 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2(일부 경로) · E3 |
| 확실성과 남은 가정 | `components/ui`·`templates`가 허용 대상인지는 문서에 없다 |
| 최소 개선 방향 | 이 규칙을 정규식 검사기에서 빼고 import 그래프 규칙 1개로 옮긴다. 경로 해석이 끝난 상태에서 `^src/presentation/design-system/(?!index\.ts$)`로 가는 간선을 금지하고, 허용 facade는 `pathNot`에 명시한다 |
| 비용·부작용 | 정규식 5줄을 지우고 규칙 1개를 추가한다 |
| 완료 기준 | P6이 실패하거나 허용 facade 목록이 규칙에 명시된다 |
| 검증 방법 | 그래프 fixture 1개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-09 레이어 규칙 사본이 세 개이고 하나는 아무도 읽지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23, 9, 4 |
| 근거 | `config/architecture/layers.json`은 어떤 스크립트나 테스트도 읽지 않는다(`grep` 결과는 설계 문서 2곳뿐). 내용도 낡았다. contracts·features·platform·apps·contexts가 없고, adapters가 `src/adapters` 전체를 import할 수 있다고 적혀 있다. 이는 실제 규칙(`adapters-do-not-know-other-concrete-adapters`)과 반대다. ESLint `layerPatterns`(`eslint.config.ts:9-34`, `:751-761`)와 `.dependency-cruiser.json`도 범위가 다르다. 예: feature presentation에 대해 lint는 http·storage·auth만 금지하고, 그래프는 `src/adapters` 전체를 금지한다 |
| 발생 조건 | 규칙을 바꿀 때 어느 파일이 기준인지 헷갈린다 |
| 영향 | 소유자가 문제로 보는 "갈라진 중복 복사본"이다. 지금 CI에서 강제되는 것은 그래프 쪽이므로 규칙이 빠지지는 않는다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 확정 |
| 최소 개선 방향 | `layers.json`을 지운다(또는 그래프 규칙에서 생성한다). ESLint `no-restricted-imports`는 "편집기에서 빨리 보여 주는 보조"라고 주석을 달고, 기준은 `.dependency-cruiser.json` 하나로 둔다 |
| 비용·부작용 | 파일 1개 삭제, 문서 2곳 링크 수정 |
| 완료 기준 | 레이어 규칙의 기준 파일이 하나다 |
| 검증 방법 | `grep -r layers.json` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-10 가드레일·CI 코드의 유지 비용이 검출력에 비해 크다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 21, 9, 4, 22, 3, 30.6 |
| 근거 | `scripts/`는 141파일·31.7k줄이고, `check-*` 29개가 5.5k줄이다. workflow 460줄을 만들고 검증하는 데 `gates.json` 2,895 + `ci-gates.ts` 1,229 + `generate-ci-workflow.ts` 498 + `package-script-graph.ts` 994(셸 토크나이저) + `ci-artifact-validator.ts` 742 = 약 6.4k줄을 쓴다. 이 층을 거쳤는데도 12-02(게이트 누락)가 통과했고, 414개 테스트가 누락된 출력을 스냅샷으로 고정했다. 정규식 검사기는 그래프가 이미 강제하는 규칙을 한 번 더 구현한다. `check-design-system.ts:102`(lucide)는 `.dependency-cruiser.json:44` `icon-vendor-is-facade-only`와 겹치고, `scripts/lib/realtime-boundaries.ts:21`(realtime import)은 `presentation-does-not-fetch-directly`와 겹친다. 정규식 쪽이 더 약하다(12-08). 반대로 자체 import 그래프(약 0.9k줄)는 TS 7에서 dependency-cruiser가 동작하지 않아(`VD-01`) 필요한 비용이고, fixture로 자기검증까지 한다 |
| 발생 조건 | 게이트를 하나 추가하거나 바꿀 때: `package.json` + `gates.json` 명령·게이트·아티팩트·스키마 + 재생성 + 스냅샷 갱신 |
| 영향 | 작성자 1인 체제에서 다운스트림 팀이 이 메타 시스템을 떠안는다(30.6). 복잡도가 검출력을 보장하지 않는다는 사례가 이미 있다(12-02) |
| 심각도·우선순위 | Medium · P2 |
| 통제·증거 | 해당 없음 · E1(규모 측정) + E2(12-02 누락이 테스트를 통과) |
| 확실성과 남은 가정 | 비용은 줄 수로 잰 대리 지표다. 실제 변경 시간은 측정하지 않았다 |
| 최소 개선 방향 | 새 시스템을 만들지 말고 줄인다. (1) import 관련 정규식 규칙(icon vendor, realtime import, design-system deep import)을 그래프 규칙으로 옮기고 정규식을 지운다. (2) workflow 계약 검사의 핵심 불변식을 "모든 게이트 id가 run step에 있다" 하나로 먼저 세운다. (3) `package-script-graph.ts`의 셸 파싱이 막는 위험(install lifecycle)이 `--ignore-scripts`와 `allowBuilds`로 이미 막혀 있는지 확인하고, 그렇다면 축소한다 |
| 비용·부작용 | 삭제 위주. 검사 범위가 줄지 않았는지 기존 음성 fixture로 확인해야 한다 |
| 완료 기준 | 같은 규칙을 두 도구가 따로 구현하는 곳이 없다. CI 메타 층에 "실행 누락" 음성 fixture가 있다 |
| 검증 방법 | 기존 음성 fixture 전체 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-11 검사 실패 메시지에 이유와 해결 방향이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 20, 8 |
| 근거 | ESLint `no-restricted-imports` 패턴에 `message`가 없다(`eslint.config.ts:36-38`). 출력은 "`'../../adapters/http/index.ts' import is restricted from being used by a pattern`"뿐이다. 그래프는 "`Architecture violation [rule]: a -> b`"로 파일 쌍과 규칙 이름만 출력하고 줄 번호가 없다(`scripts/check-architecture.ts:204`). 규칙 대부분에 `comment`(이유)가 이미 있지만 출력하지 않는다 |
| 발생 조건 | 위반이 났을 때 |
| 영향 | 왜 막혔고 어디로 가야 하는지(배럴, port, bootstrap)를 `.dependency-cruiser.json`을 열어 찾아야 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | — · E3(probe 출력) |
| 확실성과 남은 가정 | 확정 |
| 최소 개선 방향 | 위반 출력에 규칙 `comment` 첫 문장과 specifier를 붙인다. ESLint 패턴을 `{ group, message }` 형태로 바꾼다 |
| 비용·부작용 | 수십 줄 |
| 완료 기준 | probe P1 출력만 보고 수정 위치를 알 수 있다 |
| 검증 방법 | 금지 fixture 출력 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 12-12 unused 변수·import를 아무 도구도 잡지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 16, 9, 21 |
| 근거 | `VD-01` 결정 3은 "unused 진단은 `tsc`가 소유한다"며 TS 파일의 `no-unused-vars`를 끈다(`eslint.config.ts:465`, `:484`, `:507`). 그런데 `tsconfig.base.json`에 `noUnusedLocals`·`noUnusedParameters`가 없다 |
| 발생 조건 | 쓰지 않는 import·변수가 생길 때 |
| 영향 | 죽은 import가 남는다. 경계 그래프는 import가 쓰이는지 여부와 상관없이 간선으로 보므로 경계 판정에는 영향이 없다. 가독성과 삭제 용이성(27)이 약해진다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0(결정과 구현 불일치) · E1 |
| 확실성과 남은 가정 | 옵션을 켰을 때 기존 코드에서 몇 건이 나오는지는 세지 않았다 |
| 최소 개선 방향 | `tsconfig.base.json`에 `noUnusedLocals: true`(필요하면 `noUnusedParameters`도)를 켜고, 나온 건을 정리한다 |
| 비용·부작용 | 한 번 정리하는 비용 |
| 완료 기준 | 결정 문서와 설정이 일치한다 |
| 검증 방법 | `check:types` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 다른 영역 — 도메인 규칙 영역 | — | — | 적용 제외 |
| 2 | 구조적 성숙도 | 적용 — import 경계 강제 | M3 / M3(직접 간선) | E3 probe 20개 | 부분 충족 — 재수출·glob 우회(12-03, 12-06). `paths` 오용 없음 |
| 3 | 변경 용이성 | 적용 — 게이트 추가 비용 | M2 / M2 | E1 | 부분 충족 — 게이트 하나에 4곳 수정(12-10) |
| 4 | 인지 부하 | 적용 — 검사 코드 규모 | — | E1 | 부분 충족 — 31.7k줄, 규칙 사본 3개(12-09, 12-10) |
| 5 | 위험 가시성 | 부분 — 예외 범위 표시 | M1 / M1 | E3 | 부분 충족 — 예외가 문서보다 넓음(12-07) |
| 6 | 실패 성숙도 | 다른 영역 — 런타임 실패 처리 | — | — | 적용 제외 |
| 7 | 운영 성숙도 | 다른 영역 — 13(릴리스·운영) | — | — | 적용 제외 |
| 8 | 디버깅 가능성 | 적용 — 게이트 로그 | M2 / M2 | E3 | 부분 충족 — 로그는 artifact로 남지만 위반 메시지에 줄·이유가 없음(12-11) |
| 9 | 유지보수 성숙도 | 적용 | — | E1·E2 | 부분 충족 — 메타 CI 비용, 문서와 도구 불일치(12-05, 12-10) |
| 10 | 테스트 성숙도 | 적용 — 검사기 자기검증·CI 연결 | M3 / M2 | E2 | 부분 충족 — 음성 fixture는 강함. CI 밖 테스트 14파일(12-04) |
| 11 | 데이터 성숙도 | 적용 제외 — 이 영역에 데이터 없음 | — | — | 적용 제외 |
| 12 | 동시성 성숙도 | 적용 제외 | — | — | 적용 제외 |
| 13 | 확장성 | 다른 영역 — extreme-scale 문서·영역 | — | — | 적용 제외 |
| 14 | 성능 성숙도 | 부분 — CI 시간 비용 | — | 미확인 | 미검증 — CI 소요 시간 미측정 |
| 15 | 보안 성숙도 | 부분 — CI 권한·릴리스 입장 | M3 / M2 | E1 | 부분 충족 — `contents: read`, SHA 고정. release-admission 미실행(12-02) |
| 16 | 의존성 성숙도 | 적용 — lint·타입 도구 | M2 / M2 | E2 | 부분 충족 — exact pin·frozen lockfile·ADR 있음. depcruise 무동작(12-05), unused 진단 공백(12-12), 예외 이유 없음(12-07) |
| 17 | API / Contract | 부분 — gates.json 계약 | M3 / M2 | E2 | 부분 충족 — 소유와 실행을 구분하지 않음(12-02) |
| 18 | 배포 성숙도 | 다른 영역 — 13. 단 12-02가 영향 | — | E1 | 적용 제외(12-02 참조) |
| 19 | 설정 성숙도 | 다른 영역 — 13·19 | — | — | 적용 제외 |
| 20 | 개발자 경험 | 적용 — 실패 메시지 | M2 / M1 | E3 | 부분 충족 — 12-11 |
| 21 | Guardrail 성숙도 | 핵심 | M4(required) / M1(머지), M3(로컬 import) | E3 | 미충족 — 머지 차단 없음(12-01), 게이트 누락(12-02). 로컬 import 검사는 강함 |
| 22 | 추상화 성숙도 | 적용 — CI 메타 층 | — | E2 | 부분 충족 — 12-10 |
| 23 | 일관성 | 적용 — 규칙 사본 | M2 / M1 | E1 | 부분 충족 — 12-09, 12-08 |
| 24 | 네이밍 / 의미 | 부분 — `.dependency-cruiser.json`이 실제 강제 도구를 가림 | — | E2 | 부분 충족 — 12-05 |
| 25 | 조직 확장성 | 구조적 준비만 평가(1인 관리) | — | E1 | 미검증 — `gates.json` 단일 2.9k줄 파일이 충돌 지점이 될 수 있음 |
| 26 | Ownership | 적용 — 예외·게이트 담당 | M1 / M1 | E1 | 부분 충족 — risk-coverage에는 owner가 있음. 경계 예외에는 담당·재검토가 없음(12-07) |
| 27 | 삭제 가능성 | 다른 영역 — FE-GATE-020 removability | — | — | 적용 제외 |
| 28 | 회복 가능성 | 적용 제외 | — | — | 적용 제외 |
## 6. 미검증 목록
- **branch protection·required check 설정.** Gitea API가 401을 반환했다. 확인하려면 저장소 관리자 토큰으로 `/branch_protections`를 조회한다.
- **생성된 workflow가 실제 Gitea runner에서 도는지.** Actions가 꺼져 있어 실행 이력이 없다. patched artifact action, `gitea.run_attempt`, `RUNNER_IMAGE_DIGEST` 등이 대상이다. 문서(`ci-quality-gates.md:201`)가 요구하는 staging smoke 1회가 필요하다.
- **CI 소요 시간과 비용.** merge 게이트 13개가 각자 설치하고 빌드한다. 1회 실행 기록이 있어야 판단할 수 있다.
- **`tests/scale` 14파일의 현재 상태.** 무거워서 실행하지 않았다.
- **전체 게이트.** `lint`, `check:types`, `test:*`는 오케스트레이터가 실행한다. 이 문서는 `check-architecture.ts` 단독 실행과 대상 테스트 파일 실행 결과만 사용했다.
- **12-12에서 `noUnusedLocals`를 켰을 때 기존 코드의 위반 수.**
@@ -0,0 +1,399 @@
# 빌드·릴리스·배포·설정·공급망·보안 설정 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: 빌드·릴리스·공급망·보안·호스팅 스크립트(`scripts/build-frontend.ts`, `scripts/generate-*`, `scripts/verify-*`, `scripts/security-scan.ts`, `scripts/check-{browser-security,bundle,release-admission,compatibility}.ts`, `scripts/drill-runbook.ts`, 승격·provider 관련 `scripts/lib/*` — 약 8.8k줄), `vite.config.ts`, `config/{release,hosting,runtime,security,compatibility,runbooks}/`(약 7.5k줄, 대부분 `dependency-baseline.json`), `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.npmrc`, `.nvmrc`, `public/`, `.env.example`, `index.html`, 문서 `docs/security/*`, `docs/operations/*`, `docs/runbooks/*`, `docs/architecture/static-delivery.md`(약 3.1k줄). 릴리스 흐름을 따라가기 위해 `.gitea/workflows/quality-gates.yml`과 `config/ci/gates.json`의 해당 job도 읽었다.
> 영역 판정(35.8): **조건부 사용 가능** — 빌드, 런타임 설정 스키마, 로컬 릴리스 증거 생성은 그대로 써도 된다. 이 repo의 CI를 운영 승격·롤백 판단에 그대로 믿고 쓰는 것은 13-01, 13-03, 13-04, 13-05를 고치거나 사용 프로젝트가 보완하기 전까지 보류한다.
## 1. 결론
- **운영 환경 승인 게이트(FE-GATE-027)가 등록만 되어 있고 실행되지 않는다(13-01).** CI 생성기가 비-matrix job에서 첫 번째 gate만 실행한다. 원장은 이 항목(OPS-02)을 `FIXED`로 적고 있다. 그래서 repo 변수 `APP_PROFILE` 하나가 잘못되면 다른 환경용 설정을 담은 산출물이 그대로 "승격"된다.
- **검증한 산출물과 배포 산출물의 연결은 immutable_build → provider → promotion 구간에서만 강하다.** 운영 단계 runbook·롤백 drill은 새 checkout에서 local 프로필로 다시 빌드한 결과를 보고, 일부 판정은 상수 `true`다. build 없이 돌려도 롤백 drill이 PASS한다(13-03). 이전 release를 재검증하는 도구는 provider 증거 유효기간 2시간 때문에 오래된 release를 거절한다(13-04). hosting 헤더 게이트는 배포 전에 돌고, `HOSTING_BASE_URL`이 없으면 자기 선언 사본과 비교해 PASS한다(13-05).
- **배포 즉시 장애로 이어지는 결함 1건:** `dist/config.json`, `dist/release-manifest.json`이 mode `0600`으로 만들어지고 release tar에 그대로 들어간다. 웹 서버가 파일 소유자와 다른 사용자로 돌면 부트가 403으로 실패한다(13-02).
- **번들 비밀값 경로 1건:** `import.meta.env` 전체 객체 참조 때문에 코드가 쓰지 않는 `VITE_*` 빌드 환경변수까지 공개 번들에 들어간다. `sk_live_…` 형태 값을 넣어 빌드해도 secret scan은 PASS였다(13-06).
- 런타임 설정은 빌드와 브라우저가 같은 zod 스키마를 쓰고, demo 인증·비 HTTPS endpoint를 staging/production에서 거부한다. lockfile 무결성, CI 설치 스크립트 차단, action SHA 고정도 실제로 걸려 있다. 이 부분은 강점이다.
- 미검증: 실제 호스팅 provider(헤더, 포인터 전환, 이전 자산 보존), Gitea에서의 workflow 전체 실행, 외부 vulnerability·provenance provider, 운영 CSP 아래 브라우저 동작.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, 영역 13 |
| 커밋·상태 | `main` / `4626b73`. 미커밋은 `CLAUDE.md`, 가이드 문서뿐 |
| 지원 구성 | 정적 호스팅 SPA. 불변 release + active pointer(문서상). Service Worker·realtime·web worker는 기본 `null`/`NOT_SELECTED`(`src/features/installed-runtime-capabilities.ts:35-41`) |
| 규모·운영 목표 | 없음(전제). provider 복구 목표는 `TBD`(`docs/runbooks/FE-RB-005.md`) |
| 읽은 코드·설정 | 범위 표의 스크립트 전체, `src/contracts/{deployment-admission,release-artifacts,env,telemetry}.ts`, `src/bootstrap/runtime-config-schema.ts`, CI workflow·`config/ci/gates.json`의 job/gate/command 정의, `scripts/generate-ci-workflow.ts` 렌더링 부분 |
| 읽은 문서(주장) | `docs/security/supply-chain.md`, `browser-boundary.md`, `docs/operations/{release-cache-rollback,ci-quality-gates,performance-evidence}.md`, `docs/runbooks/FE-RB-00{1..5}.md`, `docs/architecture/static-delivery.md`, README 설정·릴리스 절 |
| 실행한 테스트 | worktree에서 `node scripts/run-vitest.ts run tests/unit/{deployment-admission,hosting-probe,runbook-contract,promotion-readiness,build-environment}.test.ts tests/release tests/platform/release tests/runtime-schema/runtime-config.test.ts` → **12 files, 120 tests 통과** |
| 실험(모두 `scratchpad/13/wt` 분리 worktree) | ① build 없이 `drill-runbook.ts FE-RB-001..005` → 001·003·004·005 PASS, 002만 FAIL ② `APP_PROFILE` 없이 build → `APP_ENV=local, AUTH_MODE=demo, API=http://localhost:8080/` ③ `APP_PROFILE=production` build 후 `RELEASE_TARGET=production/staging/local/""`로 admission → production만 ADMITTED ④ dist와 CI와 같은 tar 옵션으로 만든 archive의 권한 목록 ⑤ `generate-supply-chain.ts` → LOCAL PASS(561개), `promotion=FAIL_UNVERIFIED` ⑥ `check-bundle.ts` → 초기 JS 196,623 / 204,800 gzip bytes ⑦ 참조하지 않는 `VITE_*` 변수·가짜 토큰을 넣고 build + `security-scan.ts` ⑧ `VITE_ROUTER_BASE_PATH=/app/` build ⑨ strict 설정 스키마에 키 추가 ⑩ scratch 폴더에서 pnpm 11의 `.npmrc` `engine-strict` 적용 여부 |
| 확인 못 한 것 | 실제 호스팅·CDN(provider 미선정), Gitea workflow 실행, `test:system`·외부 provider(bwrap/systemd 필요), e2e·lab performance(Playwright), SW `ACTIVE` 2-pass build, 여러 runner 사이 재현성 |
| 이전 리뷰와 비교 | 직전 리뷰(`2026-09-24-src-full-review.md`)는 `src/`만 봤고 이 영역은 범위 밖이었다(`:825-826`). 관련 항목만 아래 2.1에 적는다 |
### 2.1 직전 리뷰 관련 항목 재확인
| 직전 ID | 현재 상태 | 근거 |
|---|---|---|
| 6.0 깨끗한 체크아웃에서 생성 파일 없음 | 해결 | `package.json:12-13`, `:18` 등 `dev`·`build`·`check:*`가 `generate-product-feature-index.ts`를 먼저 실행. worktree 새 체크아웃에서 build 성공 |
| 6.9-1, 6.9-9 reload 가드 | 이 영역 밖(다른 영역) | `src/platform/release/release-mismatch-recovery.ts:7-12`에 세션·TTL 기반 단일 guard가 보임. 상세 판정은 해당 영역에 맡긴다 |
## 3. 확인된 강점
1. **런타임 설정 스키마가 한 벌이다.** 빌드 단계(`scripts/generate-runtime-config.ts`)와 브라우저(`src/bootstrap/runtime-config-schema.ts:19`)가 같은 `runtimeConfigV2ArtifactSchema`(`src/contracts/release-artifacts.ts:163-171`)를 쓴다. `.strict()`라 모르는 키(비밀값 이름 포함)는 거부된다. staging/production에서 demo 인증(`:103-108`)과 비 HTTPS endpoint(`:13-20`)를 거부한다. 배포 시 덮어쓸 수 있는 값은 `API_BASE_URL`, `TELEMETRY_ENDPOINT` 두 개로 제한된다(`scripts/generate-runtime-config.ts:32-35`). 실험 ③에서 production 산출물을 staging·local로 승인하려 하면 거부됐다.
2. **immutable 후보의 식별값 연결이 촘촘하다.** immutable_build가 dist와 증거를 결정적 tar(`.gitea/workflows/quality-gates.yml:149`)로 묶고, archive SHA-256을 job output으로 넘긴다. provider job과 promotion은 그 digest, run id, nonce, 서명 키 fingerprint를 다시 확인한다(`scripts/lib/promotion-stager.ts:83-205`). CI의 `VITE_COMMIT_SHA`는 checkout HEAD와 같아야 한다(`scripts/lib/build-environment.ts:64-85`, `scripts/run-ci-gate.ts:67-99`).
3. **설치 경계가 실제로 막혀 있다.** 모든 job이 `pnpm install --frozen-lockfile --ignore-scripts`(`quality-gates.yml:63-66` 외)를 쓴다. lockfile 561행 모두 sha512 integrity가 있고 tarball/git 의존성은 없다. action은 전부 40자 commit SHA로 고정, `permissions: contents: read`, `persist-credentials: false`(`quality-gates.yml:23-24`, `:57-59`). 빌드 스크립트 허용은 `esbuild`, `msw` 두 개뿐이다(`pnpm-workspace.yaml:1-3`).
4. **캐시 정책이 선언되고 모델로 검증된다.** HTML `no-cache`, config·manifest `no-store`, 해시 자산 `immutable`(`config/hosting/cache-policy.json`), 공개 source map 금지(`vite.config.ts:32`, `scripts/check-browser-security.ts:35-45`). 새 release 활성화 뒤에도 이전 해시 자산이 남아야 한다는 규칙을 in-memory 호스팅 모델로 테스트한다(`tests/release/old-asset-reachability.test.ts:6-43`). SW 선택이 없으면 dist에 SW가 없어야 한다는 검사도 있다(`scripts/verify-hosting-headers.ts:188-193`).
5. **release 일관성 검사가 넓다.** `scripts/verify-release.ts:115-191`이 release manifest ↔ runtime config ↔ Vite manifest hash ↔ route chunk 파일 존재 ↔ build manifest를 모두 대조한다. 같은 체크아웃 2회 빌드 digest 비교(`scripts/verify-reproducible-build.ts:42-56`)도 있다.
6. **admission 규칙 자체는 잘 설계되어 있다.** placeholder build id, loopback·사설·CGNAT·IPv6 ULA 호스트, telemetry endpoint 누락을 모두 거부한다(`src/contracts/deployment-admission.ts:64-191`, 테스트 `tests/unit/deployment-admission.test.ts`). 문제는 이 규칙이 CI에서 실행되지 않는다는 점이다(13-01).
## 4. 발견 사항 (36.3)
### 13-01 운영 환경 승인 게이트(FE-GATE-027)가 CI에서 실행되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 18, 19, 21, 26 (+30.1) |
| 근거 | `config/ci/gates.json:2357-2368` immutable_build의 gateIds는 `FE-GATE-015`, `FE-GATE-027` 두 개다. 그러나 `scripts/generate-ci-workflow.ts:200`은 비-matrix job에서 `job.gateIds[0]`만 렌더링한다. 결과 workflow(`.gitea/workflows/quality-gates.yml:143-144`)는 `ci:gate -- FE-GATE-015`만 실행한다. 다른 job에도 027은 없다. `scripts/run-ci-gate.ts`는 호출당 gate 하나만 돈다. 승인 기록 `artifacts/release/deployment-admission.json`은 후보 archive 멤버(`quality-gates.yml:149-196`)에도, promotion 검증에도 없다. `scripts/lib/promotion-readiness.ts:18-26`의 RELEASE_READY 공식에는 027이 있지만 이 함수는 `check-ci-contract.ts`의 자기 검사에서만 쓰인다. 원장 `docs/operations/adapter-remediation-ledger.md:482`는 OPS-02를 `FIXED`로 적는다. 실험 ②: `APP_PROFILE` 없이 `build` → `dist/config.json`이 `APP_ENV=local, AUTH_MODE=demo, API_BASE_URL=http://localhost:8080/`(기본값 `scripts/generate-runtime-config.ts:72`) |
| 발생 조건 | tag push나 release dispatch 때 repo 변수 `vars.APP_PROFILE`(`quality-gates.yml:130`)이 의도한 대상과 다를 때. 변수가 환경별이 아니라 repo 단위 하나라서 staging 릴리스 뒤 값을 되돌리지 않으면 바로 발생한다. 빈 값이면 빌드가 실패하므로 막힌다 |
| 영향 | 다른 환경의 API·telemetry endpoint나 인증 모드를 담은 산출물이 "승격" 상태가 된다. staging endpoint는 조용히 동작할 수도 있다(운영 사용자 요청이 staging 백엔드로 감). local 프로필이면 demo 인증 + localhost API로 전면 장애. 서버 인가 경계는 영향 없음 |
| 심각도·우선순위 | Medium · P1 — 운영자 설정 실수 한 번이면 발생하고, 막으려고 만든 게이트가 원장에 해결로 적혀 있어 아무도 다시 보지 않는다. CI를 복사한 모든 사용 프로젝트에 같은 빈칸이 복제된다 |
| 통제·증거 | 규칙 M2(구현·단위 테스트) / CI 강제 M0 · E1(생성기·workflow 정적 확인) + E3(로컬 build·admission 실험) |
| 확실성과 남은 가정 | 생성기 코드와 생성된 workflow를 직접 확인했다. Gitea에서 실행하지는 않았다 |
| 최소 개선 방향 | 생성기가 비-matrix job의 gateIds를 모두 순서대로 실행하게 한다(또는 FE-GATE-015 명령 목록 끝에 `check-release-admission`을 넣는다). 승인 기록을 archive 멤버와 promotion 재검증에 포함한다. `APP_PROFILE`과 `RELEASE_TARGET`이 다르면 실패시킨다. `docs/operations/ci-quality-gates.md:293-305` 변수 목록에 두 변수를 추가한다 |
| 비용·부작용 | 작다. archive 멤버를 늘리면 archive 스키마·verifier 목록도 바뀐다 |
| 완료 기준 | `APP_PROFILE=staging`, `RELEASE_TARGET=production`인 release 실행에서 immutable_build가 실패한다. 생성된 workflow에 027 실행이 보인다 |
| 검증 방법 | `check:ci`에 "job이 소유한 gate는 workflow에서 실행된다" 검사와 negative fixture 추가. worktree에서 `APP_PROFILE=staging` build 후 `RELEASE_TARGET=production node scripts/check-release-admission.ts`가 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음(범위 밖) |
### 13-02 공개 dist 파일 3개가 mode 0600으로 만들어져 웹 서버가 읽지 못할 수 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 18, 28 (+30.1) |
| 근거 | `scripts/lib/validated-json-artifact.ts:86-92`가 임시 파일을 `0o600`으로 열고 rename한다. `scripts/generate-build-manifest.ts:124-137`이 이 writer로 `dist/config.json`, `dist/release-manifest.json`, `dist/runtime-config.schema.json`을 쓴다. 실험 ④: 다른 dist 파일은 `-rw-rw-r--`, 이 세 파일만 `-rw-------`. CI와 같은 옵션(`tar … --owner=0 --group=0`, `quality-gates.yml:149`)으로 묶으면 `-rw------- 0/0 dist/config.json`으로 권한이 보존된다 |
| 발생 조건 | dist나 promoted archive를 파일 소유자와 다른 OS 사용자로 도는 웹 서버에 올릴 때. 예: Docker `COPY dist /usr/share/nginx/html`(nginx worker 사용자), root로 풀고 Apache·nginx로 서빙. 객체 스토리지 업로드처럼 파일 권한을 무시하는 호스팅은 영향 없음 |
| 영향 | `/config.json`, `/release-manifest.json`이 403 → 모든 부트가 `BOOT_CONFIG_FAILURE`(FE-RB-001). 검증을 모두 통과한 바로 그 산출물이 실패한다 |
| 심각도·우선순위 | Medium · P2 — 첫 배포에서 바로 드러나고 수정이 쉽다. 호스팅이 정해지지 않아 영향받는 사용 프로젝트 비율은 알 수 없다 |
| 통제·증거 | M0(공개 파일 권한 규칙 없음) · E3(로컬 build·tar 실험) |
| 확실성과 남은 가정 | 권한은 직접 확인했다. 실제 nginx 컨테이너에서 403을 재현하지는 않았다 |
| 최소 개선 방향 | dist 공개 파일은 일반 writer(0644)로 쓰거나 build 마지막에 권한을 맞춘다. `artifacts/` 증거 파일만 0600을 유지한다 |
| 비용·부작용 | 한 줄 수준. private 증거 규칙과 섞이지 않게 writer를 나눈다 |
| 완료 기준 | build 후 `find dist -type f ! -perm -o=r` 결과가 비어 있다 |
| 검증 방법 | `verify-release.ts`에 권한 검사 추가, 또는 build 테스트에서 위 명령 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-03 운영 단계 runbook·롤백 게이트가 이름과 다른 것을 검사한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 28, 10, 18, 21, 24 |
| 근거 | production_gate(`quality-gates.yml:369-397`)는 새 checkout, frozen install, `ci:gate`만 한다. 후보·승격 archive를 받지 않고 `APP_PROFILE`도 없어 local 프로필로 다시 빌드한다. FE-GATE-016과 FE-GATE-025는 같은 명령(`build` + `drill:runbook -- FE-RB-005`)이다(`config/ci/gates.json` gates). `scripts/drill-runbook.ts:66-71`은 `dist/`가 없으면 `public/`의 placeholder를 읽는다. 상수 판정: `:199` `triggerAsserted: true`, `:202` "failure rate at baseline" `true`, `:241` "product flow unaffected" `true`, `:271` rollback `triggerAsserted: true`, `:276` "critical smoke" `true`. `:118-130`은 `injectedMountFailure = true` 상수라 negative fixture가 항상 통과하고, "product root mount"와 "no repeated boot error"는 같은 스키마 파싱 결과 하나다. 실험 ①: build 없이 FE-RB-005가 PASS, 기록은 `releaseId: "local-release"`, "critical smoke" `passed: true` |
| 발생 조건 | 항상. production dispatch마다 이 게이트가 돈다 |
| 영향 | `PROD_PROMOTION_READY`가 "승격한 release를 되돌릴 수 있다"가 아니라 "몇 개 함수가 기대값을 돌려준다"를 뜻한다. PASS 기록이 운영 준비 증거로 남아 사용 프로젝트가 롤백 훈련을 했다고 믿게 된다 |
| 심각도·우선순위 | Medium · P2 — 실제 롤백을 막지는 않는다. stdout에 "provider verification still required"가 찍혀 완전히 숨기지는 않는다. 그래도 증거 기록은 PASS다 |
| 통제·증거 | M1(runbook 문서) · E3(build 없는 drill 실행) |
| 확실성과 남은 가정 | 직접 실행해 확인했다 |
| 최소 개선 방향 | 상수 `true`를 없애고 측정하지 못한 항목은 `UNVERIFIED`로 기록한다. `providerVerificationRequired`가 참이면 전체 결과를 `PASS`가 아닌 별도 상태로 둔다. `public/` fallback을 없앤다. drill이 승격 archive와 이전 release archive 경로를 입력으로 받게 한다. 016/025 중복을 정리한다. 이름을 "runbook 논리 검사"처럼 실제 범위에 맞춘다 |
| 비용·부작용 | 중간. 증거 스키마와 promotion 공식이 바뀐다 |
| 완료 기준 | dist 없이 FE-RB-005가 실패한다. 기록에 상수 판정이 없다. production_gate가 승격 archive를 내려받아 검사한다 |
| 검증 방법 | drill 단위 테스트에 "build 없음 → FAIL", "provider 미검증 → PASS 아님" 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-04 이전 release를 재검증할 수단이 없어 문서의 롤백 절차를 그대로 실행할 수 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 28, 18, 16 |
| 근거 | provider 증거 유효기간 상한이 2시간이다(`scripts/lib/provider-evidence.ts:12`). 재검증 때 `expires <= now`면 만료로 실패한다(`:485`). `scripts/verify-exact-promotion-bundle.ts:58-73`은 `nowEpochMs`를 넘기지 않아 현재 시각으로 검사한다. 문서는 모든 하위 소비자가 archive와 서명 증거를 다시 검증해야 한다고 한다(`docs/security/supply-chain.md:257-260`). 롤백 runbook은 이전 불변 release의 tuple을 검증하라고 하고(`docs/runbooks/FE-RB-005.md`), 옛 커밋 재빌드는 금지한다(`docs/operations/release-cache-rollback.md:9-13`). drill의 롤백 검증 함수는 경로를 코드 옵션으로만 받고 CLI 인자가 없다(`scripts/drill-runbook.ts:292-318`, `:320-331`) |
| 발생 조건 | 승격 후 2시간이 지난 release를 배포하거나 그 release로 롤백할 때(다음 날 배포, 지난주 release로 롤백 등) |
| 영향 | 문서가 요구하는 "배포 전 재검증"을 repo 도구로 통과할 수 없다. 사고 중에는 검증을 건너뛰거나 롤백이 늦어진다. 신선도 검사는 새 승격에는 맞지만 보관된 release의 재확인에는 맞지 않는다 |
| 심각도·우선순위 | Medium · P2 — 롤백 자체는 provider에서 포인터를 바꾸면 되지만, 문서가 정한 안전 확인이 불가능하다 |
| 통제·증거 | M0(보관 release 재검증 경로 없음) · E1 |
| 확실성과 남은 가정 | 코드로 확인했다. 실제 서명된 bundle로 실행하지는 않았다(provider 키 없음) |
| 최소 개선 방향 | `verify:promotion`에 보관 모드를 둔다. 서명·digest·멤버 검사는 유지하고, 신선도는 "승격 시점 기록(`promotion-verification.json`의 `verifiedAt`)이 당시 유효 창 안이었는가"로 바꾼다. drill에 archive 경로 인자를 추가한다. 문서에 롤백 시 실행할 명령을 적는다 |
| 비용·부작용 | 중간. 보관 모드가 재사용 공격 방어를 약하게 만들지 않게, 새 승격에는 쓰지 못하도록 분리해야 한다 |
| 완료 기준 | 3시간 전에 승격된 fixture bundle이 보관 모드에서 PASS, 변조 bundle은 FAIL |
| 검증 방법 | `nowEpochMs`를 주입한 단위 테스트 2개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-05 hosting 헤더 게이트가 배포 전에 돌고, 배포·전환·자산 보존 단계는 repo에 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 18, 15, 21, 28 |
| 근거 | `HOSTING_BASE_URL`이 없으면 `scripts/verify-hosting-headers.ts:133-139`가 선언을 그 사본인 `config/hosting/response-headers.fixture.json`과 비교하고 exit 0으로 끝난다(`:205`는 `providerVerificationRequired`만 표시). `mode: "live"`를 요구하는 소비자가 없다(grep). 그런데 문서는 운영 승격에 live가 필요하다고 한다(`docs/operations/release-cache-rollback.md:29-33`). FE-GATE-019는 release_gate(`quality-gates.yml:80-118`)에서 immutable_build·promotion보다 먼저 돌고, workflow에는 배포 job이 없다. 그래서 live 모드는 이전 배포를 새 로컬 빌드의 첫 `.js` 이름(`verify-hosting-headers.ts:76-85`)으로 찌른다. 확인 경로는 `/`, `/config.json`, `/release-manifest.json`, JS 1개뿐이다. deep link, 없는 자산의 404, CSS는 보지 않는다. `docs/architecture/static-delivery.md:15-33`은 CI가 업로드·도달성 확인·포인터 전환·smoke를 한다고 그리지만 workflow에는 없다. 이전 해시 자산 보존 기간(rolling window)은 테스트 모델에만 있고(`tests/release/release-fixture.ts:91`, `:132`) 운영 문서에 최소 기간이 없다 |
| 발생 조건 | `HOSTING_BASE_URL`을 설정하지 않았거나, 설정했더라도 새 release가 아직 배포되지 않은 모든 release 실행 |
| 영향 | CSP·HSTS·cache-control 오설정이나 SPA fallback이 없는 호스팅이 게이트를 통과한다. live 모드는 새 release를 보지 못하고, 첫 JS 이름이 바뀌면 404로 실패한다. 사용 프로젝트는 배포·smoke가 이 repo에 있다고 오해할 수 있다. 이전 자산 삭제 시점이 provider 구현마다 달라진다(오래 열린 탭은 reload-once 복구에 의존) |
| 심각도·우선순위 | Medium · P2 — 게이트가 거짓 PASS를 내지만, 실제 배포 경로가 repo 밖이라 피해는 사용 프로젝트 구현에 달려 있다 |
| 통제·증거 | 헤더 선언 M1, fixture 비교 M3(자기 사본), 배포 후 확인 M0 · E1 |
| 확실성과 남은 가정 | workflow 순서와 코드로 확인했다. live 모드는 대상 호스트가 없어 실행하지 않았다 |
| 최소 개선 방향 | fixture 모드 결과를 PASS가 아닌 `UNVERIFIED`로 바꾸고 promotion이 live를 요구하게 한다. 헤더 검사를 배포 후 단계(별도 post-deploy job 또는 문서화된 provider 단계)로 옮기고 승격 release의 자산 이름으로 확인한다. deep link, 없는 자산(404이며 `text/html`이 아님), CSS를 추가한다. 문서에 "업로드·포인터 전환·전환 후 smoke는 사용 프로젝트 provider adapter 책임"과 이전 자산 최소 보존 기간을 적는다 |
| 비용·부작용 | 중간. post-deploy 단계는 호스팅 선택 뒤에만 완성된다 |
| 완료 기준 | `HOSTING_BASE_URL` 없이 FE-GATE-019가 PASS하지 않는다. live 확인이 승격 release의 해시 자산을 요청한다 |
| 검증 방법 | 로컬 정적 서버에 헤더를 일부러 빼고 live 모드 실행 → 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-06 쓰지 않는 `VITE_*` 빌드 변수까지 공개 번들에 들어가고, secret scan은 이를 잡지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 15, 16, 14 |
| 근거 | `src/contracts/env.ts:123`(기본 인자 `import.meta.env`)과 `src/features/installed-product-manifest.ts:24-28`(`import.meta`를 캐스팅해 `.env` 전체 접근)이 env 객체 전체를 참조한다. Vite는 이 경우 모든 `VITE_*` 값을 객체 리터럴로 넣는다. 실험 ⑦: `VITE_PROBE_UNREFERENCED=probe-value-13`으로 build → `index-*.js`, `design-system-*.js`에 문자열이 있다. `VITE_PAYMENT_KEY=sk_live_…`, `VITE_SENTRY_AUTH_TOKEN=sntrys_…`로 build → 둘 다 번들에 있고 `node scripts/security-scan.ts` → "PASS (1355 files)". 탐지 규칙은 4개(PEM RSA/EC/PKCS8, `AKIA…`, `gh?_…`, `client_secret|password|private_key` 대입)뿐이다(`scripts/lib/secret-scan.ts:20-31`). 부작용: build id가 `design-system` chunk(66 KB gzip)에 들어가 release마다 이 chunk 해시가 바뀐다 |
| 발생 조건 | 빌드 환경(CI 변수, 개발자 셸, `.env.local`)에 `VITE_` 접두어 비밀값이 있을 때. 코드에서 참조하지 않아도 들어간다 |
| 영향 | 비밀값이 공개된다. 게이트는 PASS를 낸다 |
| 심각도·우선순위 | Medium · P2 — 전제는 `VITE_`에 비밀을 넣는 실수다(`.env.example:1-4`가 경고한다). 다만 참조하지 않은 값까지 싣는 범위는 이 템플릿 코드가 넓혔고, 탐지도 안 된다 |
| 통제·증거 | M1(문서 경고), 탐지 M3(4개 형식만) · E3 |
| 확실성과 남은 가정 | 직접 build해 확인했다 |
| 최소 개선 방향 | `import.meta.env.VITE_BUILD_ID`처럼 키마다 직접 참조한다(Vite가 개별로 치환). 전체 객체 참조를 lint로 금지한다. build 스크립트에서 허용 목록 밖 `VITE_*` 변수가 있으면 실패시킨다. 탐지 규칙은 표준 규칙 세트 사용을 검토한다 |
| 비용·부작용 | 작다. 규칙을 넓히면 오탐 allowlist 관리가 늘어난다 |
| 완료 기준 | 실험 ⑦을 반복했을 때 probe 문자열이 dist에 없다. design-system chunk 해시가 build id에 따라 바뀌지 않는다 |
| 검증 방법 | build 테스트: 임의 `VITE_*` 변수를 넣고 dist grep |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-07 하위 경로 배포에서 config·manifest URL이 base를 따르지 않아 부트가 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 18, 23 |
| 근거 | `vite.config.ts:7-15`는 "하위 경로 배포가 일관되거나 build에서 실패한다"고 적는다. 하지만 runtime config URL 기본값은 `/config.json`(`src/contracts/env.ts:46`, `:128`)이고, 프로필의 `RELEASE_MANIFEST_URL`은 `/release-manifest.json`이다(`config/runtime/*.json`). 배포 시 덮어쓸 수 있는 값은 API·telemetry뿐이다(`scripts/generate-runtime-config.ts:32-35`). 실험 ⑧: `VITE_ROUTER_BASE_PATH=/app/` build 성공 → `index.html`은 `/app/assets/…`, 번들의 config URL은 `/config.json`, `dist/config.json`의 manifest URL은 `/release-manifest.json`. hosting 확인 경로도 루트 고정(`scripts/verify-hosting-headers.ts:80-85`) |
| 발생 조건 | `/app/`처럼 하위 경로에 배포하고 `VITE_RUNTIME_CONFIG_URL`과 프로필 파일을 따로 고치지 않았을 때 |
| 영향 | build와 게이트는 통과하고, 부트에서 config 404로 전면 실패 |
| 심각도·우선순위 | Low · P2 — 하위 경로 배포에만 해당하고 첫 배포에서 바로 드러나며 우회가 있다. 그러나 `.env.example:20-22`가 지원 기능으로 안내한다 |
| 통제·증거 | M1 · E3 |
| 확실성과 남은 가정 | 산출물을 직접 확인했다. 브라우저 부트는 실행하지 않았다 |
| 최소 개선 방향 | 두 URL 기본값을 base에서 만든다(`${base}config.json`). 또는 base가 `/`가 아닌데 두 값이 base로 시작하지 않으면 build를 실패시킨다 |
| 비용·부작용 | 작다 |
| 완료 기준 | `/app/` build에서 두 URL이 `/app/`로 시작하거나 build가 실패한다 |
| 검증 방법 | runtime-config 생성 테스트에 base 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-08 선언된 CSP가 브라우저에서 한 번도 적용되지 않고, opt-in 기능을 막는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 15, 10 (+30.2) |
| 근거 | CSP는 `config/hosting/security-headers.json:4`에 선언만 있다. e2e는 `vite preview`로 돌고(`playwright.config.ts:16-20`) 헤더를 붙이지 않는다. CSP를 붙이는 테스트는 없다(grep). 문서는 빌드 산출물이 CSP와 호환된다고 한다(`docs/security/browser-boundary.md:7-10`). `connect-src 'self' https:`는 다른 origin의 `wss:`를 허용하지 않는다(CSP3 scheme 비교 규칙: `https:`는 `https`만 맞음). realtime은 `wss://<origin>`을 만든다(`src/adapters/realtime/websocket/websocket-connection.ts:1609`). `img-src 'self' data:`에는 preview lease가 쓰는 `blob:`이 없다(`src/adapters/browser-files/object-url-lease.ts:111`, `:286`). 기본 구성은 이 기능들이 꺼져 있어 영향이 없다(`src/features/installed-runtime-capabilities.ts:35-41`). 기본 `index.html` 산출물에는 inline script·style이 없다(실험 산출물 확인) |
| 발생 조건 | 사용 프로젝트가 realtime(다른 origin), 파일 preview, 이미지 CDN recipe를 켜고 이 CSP를 그대로 배포할 때 |
| 영향 | 로컬·e2e에서는 되고 운영 CSP에서만 막힌다. 반대로 `connect-src https:`는 XSS가 나면 임의 HTTPS로 데이터를 보낼 수 있게 둔다 |
| 심각도·우선순위 | Low · P2 — 기본 구성은 문제없다. 기능을 켤 때 반드시 부딪히는 함정이다 |
| 통제·증거 | M1 · E1(`wss` 판정은 명세 기준, 브라우저 실행 미확인) |
| 확실성과 남은 가정 | 브라우저에서 CSP 위반을 재현하지 않았다 |
| 최소 개선 방향 | e2e 한 벌을 `security-headers.json` 헤더를 붙이는 정적 서버로 돌리고 `securitypolicyviolation` 0건을 확인한다. recipe 문서에 필요한 CSP 추가분을 적는다. `connect-src`를 runtime config의 API·telemetry origin으로 좁히는 방안을 검토한다 |
| 비용·부작용 | 중간. 헤더를 붙이는 정적 서버가 필요하다(`scripts/serve-static.ts` 확장 가능) |
| 완료 기준 | 운영 CSP 아래 smoke가 통과하고 위반 이벤트가 0건 |
| 검증 방법 | Playwright에서 위반 이벤트 수집 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-09 `.npmrc`의 `engine-strict`, `save-exact`가 pnpm 11에서 무시된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 16, 19, 20 |
| 근거 | `.npmrc:1-2`. `corepack pnpm config list`에 두 값이 없다. 실험 ⑩: scratch 폴더에서 `engines.node: "<1.0.0"` + `.npmrc engine-strict=true` → install 성공. 같은 조건에 `pnpm-workspace.yaml`의 `engineStrict: true` → 엔진 오류로 실패 |
| 발생 조건 | 개발자가 로컬에서 install하거나 의존성을 추가할 때 |
| 영향 | `engines.node >=24.11 <25`가 설치 때 강제되지 않는다. 새 의존성이 `^` 범위로 저장된다. CI는 `.nvmrc`와 frozen lockfile로 막혀 영향이 작다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 설정이 있다고 믿지만 실제 M0 · E3 |
| 확실성과 남은 가정 | pnpm 11.17.0에서 확인했다 |
| 최소 개선 방향 | `pnpm-workspace.yaml`에 `engineStrict: true`, `saveExact: true`로 옮기고 `.npmrc`에서 지운다 |
| 비용·부작용 | 없음 |
| 완료 기준 | 지원 범위 밖 Node로 install이 실패한다 |
| 검증 방법 | 실험 ⑩ 반복 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-10 config 호환성 게이트는 분류기 자기 검사이고, strict reader에서 "additive" 변경이 깨진다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 19, 24 |
| 근거 | FE-GATE-014(`verify:compatibility`)는 `config/compatibility/fixtures.json`의 예제 스키마만 분류한다(`scripts/check-compatibility.ts:23-34`). 이전 release의 실제 스키마와 비교하지 않는다. 예제는 선택 키 추가를 "additive"(호환)로 본다. 그런데 실제 reader는 `.strict()`다(`src/contracts/release-artifacts.ts:50-57`, `:163-171`). 실험 ⑨: production 프로필에 키 하나를 더하면 `unrecognized_keys`로 거부된다. 호스팅 모델에서 `/config.json`은 활성 release의 것이 나간다(`tests/release/old-asset-reachability.test.ts:28-34`) |
| 발생 조건 | 이전 빌드가 새 config를 읽을 때. 예: SW `ACTIVE`에서 캐시된 app shell, 부트 중 포인터 전환 |
| 영향 | "호환"으로 분류된 설정 변경이 이전 빌드의 부트를 실패시킨다. 게이트 이름과 실제 검사가 다르다 |
| 심각도·우선순위 | Low · P3 — 기본 구성(SW 없음)에서는 노출이 작다 |
| 통제·증거 | M1 · E3 |
| 확실성과 남은 가정 | 이전 빌드가 새 config를 읽는 경로를 브라우저에서 재현하지 않았다 |
| 최소 개선 방향 | 게이트가 이전 release의 `runtime-config.schema.json`과 현재 스키마를 비교하게 한다. strict reader 기준으로 "키 추가 = 이전 reader에 breaking"으로 분류하거나, reader가 top-level 미지 키를 무시하는 정책을 명시한다 |
| 비용·부작용 | 중간. 이전 release 스키마를 보관해야 한다 |
| 완료 기준 | 키 추가 변경이 게이트에서 breaking으로 표시된다 |
| 검증 방법 | fixture에 strict reader 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-11 API 실패 telemetry에 release·build 식별값이 없어 배포와 이상을 연결하기 어렵다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 7, 8, 18 |
| 근거 | `api.request.failed`의 필수·선택 속성에 `build_id`, `release_id`가 없다(`src/contracts/telemetry.ts:72-77`). `build_id`는 부트 실패·렌더 실패에만 있고 `release_id`는 어느 이벤트에도 필수가 아니다. collector body는 `{ events }`뿐이라 공통 envelope도 없다(`src/adapters/telemetry/telemetry-collector.ts:91`) |
| 발생 조건 | 배포 중 신·구 탭이 공존할 때 API 실패율을 release별로 나누려 할 때 |
| 영향 | FE-RB-003/005의 "새 release 때문인가" 판단에 필요한 연결이 없다 |
| 심각도·우선순위 | Low · P3 — 관측 영역과 겹칠 수 있다 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 서버 쪽에서 요청 헤더로 release를 붙이는지는 확인하지 않았다 |
| 최소 개선 방향 | 모든 이벤트 공통 envelope에 `build_id`, `release_id`를 넣는다 |
| 비용·부작용 | 작다. 값 종류는 release 수만큼만 늘어난다 |
| 완료 기준 | 전송 body의 모든 이벤트에 두 값이 있다 |
| 검증 방법 | telemetry projection 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-12 SBOM·provenance가 증명하는 범위가 문서에 정리되어 있지 않다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 16, 24 |
| 근거 | SBOM은 `pnpm list --depth Infinity` 설치 그래프다(`scripts/generate-supply-chain.ts:88-92`). 실험 ⑤: 561개 중 development 551, production 10. 번들에 실제로 들어간 패키지는 module inventory가 `node_modules` 경로를 `external:<파일명>`으로 바꿔 패키지 이름·버전이 남지 않는다(`scripts/lib/vite-module-inventory.ts`, 실험에서 패키지 0개 식별). local provenance는 빌드한 같은 프로세스가 만든 서명 없는 문서다(`builder.id: "local:…"`, `invocationId: "LOCAL_UNSIGNED"`, `generate-supply-chain.ts:252-280`). 그런데 `predicateType`은 SLSA provenance v1이다. 외부 provenance provider는 빌드 뒤 다른 job에서 오프라인으로 후보 digest에 서명한다(`docs/security/supply-chain.md:216-223`) |
| 발생 조건 | 사용 프로젝트나 감사자가 SBOM·provenance를 근거로 판단할 때 |
| 영향 | 아래 표의 "증명하지 못하는 것"을 증명된 것으로 오해할 수 있다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E3 |
| 확실성과 남은 가정 | 외부 provider 출력은 보지 못했다 |
| 최소 개선 방향 | 문서에 아래 표를 넣는다. module inventory에 패키지 이름·버전을 남겨 "배포물에 든 패키지" 목록을 만든다. local 문서에 "서명 없음, 자기 보고"를 표시한다 |
| 비용·부작용 | 작다 |
| 완료 기준 | 배포물에 든 패키지@버전 목록이 산출물로 나온다 |
| 검증 방법 | 목록과 SBOM production 항목 대조 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
|---|---|---|
| SBOM | lockfile에 고정된 설치 그래프와 각 패키지의 sha512 integrity, license | 배포물에 실제로 들어간 부분 집합, 취약점 없음 |
| local provenance | dist digest ↔ lockfile ↔ source set ↔ SBOM digest가 서로 맞음 | 빌드 과정이 변조되지 않았음(서명·격리 없음), 빌드한 주체 |
| 외부 provenance 서명 | 지정 키 보유자가 이 run·source revision·후보 digest를 보고 서명함 | 빌드 job 자체의 격리, provider가 성실히 검사했음(`supply-chain.md:244-248`도 이렇게 적음) |
| 외부 vulnerability 서명 | provider가 이 lockfile·dist에 대해 결과를 주장함 | 오프라인 DB의 최신성, 누락 없음 |
### 13-13 공급망·승격 체계의 도입 비용이 크고 실제 환경에서 한 번도 돈 적이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 미검증 |
| 관련 관점 | 16, 4, 9 (+30.6) |
| 근거 | 공급망·승격·provider 관련 스크립트가 약 8.9k줄이다. 승격까지 가려면 bwrap·prlimit·systemd-run, systemd user manager 254 이상, cgroup v2 위임(`docs/security/supply-chain.md:113-128`), 오프라인 데이터로 Ed25519 서명 보고서를 내는 provider 두 개(`:210-215`)가 필요하다. repo 안의 vulnerability 결과는 `UNCONFIGURED`/`FAIL_UNVERIFIED` placeholder다(`scripts/lib/local-policy-evidence.ts:42-53`). 문서는 staging Gitea에서 end-to-end smoke를 먼저 통과해야 required check로 쓸 수 있다고 한다(`docs/operations/ci-quality-gates.md:201-203`, `supply-chain.md:110-111`). 그 실행 기록은 없다. provider 없이 승격을 끄는 선택지는 문서에 없다. provider 신뢰 키 교체 절차도 없다 |
| 발생 조건 | 사용 프로젝트가 Gitea 외 CI나 일반 runner에서 이 파이프라인을 쓰려 할 때 |
| 영향 | 승격 단계까지 쓰려면 사용 프로젝트가 큰 인프라를 먼저 갖춰야 한다. 못 갖추면 승격이 항상 실패하고, 결국 파이프라인을 우회하게 된다 |
| 심각도·우선순위 | Low · P3 — 문서가 한계를 정직하게 적고 fail-closed로 동작한다 |
| 통제·증거 | M2 · E2(단위·fixture) / 실제 환경 미확인 |
| 확실성과 남은 가정 | `test:system`과 provider 실행은 하지 않았다 |
| 최소 개선 방향 | "provider 없는 구성"(local 증거까지만, 승격은 수동 승인)을 지원 구성으로 문서화한다. 신뢰 키 교체·폐기 절차를 적는다. staging smoke 결과를 기록한다 |
| 비용·부작용 | 문서 작업이 주다 |
| 완료 기준 | 최소 구성과 전체 구성이 각각 무엇을 보장하는지 문서에 있다 |
| 검증 방법 | 문서 검토, staging smoke 기록 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-14 초기 JS 예산의 96%를 템플릿 기본 화면이 쓰고, lab 측정은 1회다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 14 |
| 근거 | 실험 ⑥: 초기 JS 196,623 / 204,800 gzip bytes(`config/performance/budgets.json`). 초기 파일 9개 중 `index` 93.5 KB, `design-system` 65.6 KB, `preload-helper` 28.5 KB. CSS 8.5 KB는 합계에 없다(`scripts/check-bundle.ts:34-37`은 JS만 센다). 측정 조건(Node·pnpm·runner)은 기록된다(`scripts/generate-supply-chain.ts:309-321`). lab 측정(`scripts/test-performance.ts:57-100`)은 local 프로필 build를 `vite preview`로 띄워 1회 측정하고, 상호작용 시간은 Node의 `performance.now()`로 Playwright 클릭부터 heading 대기까지 잰다(Playwright 왕복 포함) |
| 발생 조건 | 사용 프로젝트가 첫 기능을 추가할 때 |
| 영향 | 약 8 KB 여유라 첫 기능 추가에서 예산이 깨질 가능성이 높다. 사용 프로젝트가 이유 없이 예산을 올리게 된다. lab 1회 측정은 흔들린다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M3 · E3(번들), lab은 미실행 |
| 확실성과 남은 가정 | gzip 수준은 Node 기본값이다. 호스팅 압축(brotli 등)과 다를 수 있다 |
| 최소 개선 방향 | 템플릿 기준선과 여유를 문서에 적는다. CSS 포함 여부를 명시한다. lab은 여러 번 측정해 중앙값을 쓴다 |
| 비용·부작용 | 작다. CI 시간이 조금 는다 |
| 완료 기준 | 예산 문서에 기준선·여유·측정 조건이 있다 |
| 검증 방법 | 문서 검토 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 13-15 런타임 설정의 정본 위치·배포 변수 설명이 문서와 다르고 사본이 두 벌이다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 20, 9, 23 |
| 근거 | README는 런타임 설정이 `public/config.json`에 있다고 한다(`README.md:24`). 실제로 build는 이 파일을 `config/runtime/<profile>.json`으로 덮어쓴다(`scripts/build-frontend.ts:24-28`). `APP_PROFILE`, `RUNTIME_API_BASE_URL`, `RUNTIME_TELEMETRY_ENDPOINT`, `RELEASE_TARGET`은 README·docs 어디에도 없다(grep). `public/config.json`과 `config/runtime/local.json`은 같은 내용의 사본인데 동기화 검사가 없다. `ENV_REGISTRY`는 `VITE_BUILD_ID`를 필수로 적지만(`src/contracts/env.ts:43`) 코드는 `local-build`로 대체한다(`:125`). `build-frontend.ts:24-28` 주석은 SW가 config.json을 해시한다고 하지만 SW 자산 목록은 이를 뺀다(`scripts/generate-service-worker-assets.ts:36`) |
| 발생 조건 | 사용 프로젝트가 README를 보고 운영 설정을 `public/config.json`에 넣을 때 |
| 영향 | 수정이 build에서 조용히 사라진다. 배포 변수를 코드에서 찾아야 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 정적 확인 |
| 최소 개선 방향 | README 설정 절을 프로필·배포 변수·우선순위(프로필 < `RUNTIME_*` 덮어쓰기 < build identity) 기준으로 고친다. `public/config.json`을 local 프로필에서 생성하거나 동기화 검사를 둔다 |
| 비용·부작용 | 작다 |
| 완료 기준 | 문서만 보고 production 산출물을 만들 수 있다 |
| 검증 방법 | `verify:documentation`에 변수 목록 대조 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 다른 영역 — `src/` 규칙은 각 영역 | — | — | 적용 제외 |
| 2 | 구조적 성숙도 | 다른 영역 — 아키텍처 영역 | — | — | 적용 제외 |
| 3 | 변경 용이성 | 적용 — 새 프로필·환경 추가 경로 | M2 목표 / 프로필·`DEPLOYMENT_TARGETS`·`public` 사본·CI 변수를 함께 바꿔야 함 | E1 | 부분 충족 — 13-15 |
| 4 | 인지 부하 | 적용 — 릴리스 파이프라인 이해 비용 | 27 gate, 공급망 문서 한 문단이 수십 개 규칙 | E1 | 부분 충족 — 13-13 |
| 5 | 위험 가시성 | 적용 — gate 결과가 실제 확인 범위를 드러내는가 | drill·hosting이 "provider verification required"를 출력하지만 기록은 PASS | E3 | 부분 충족 — 13-03, 13-05 |
| 6 | 실패 성숙도 | 적용(좁게) — build 단계 실패 처리 | 각 단계 비정상 종료 시 즉시 중단(`build-frontend.ts:34-43`), 증거 쓰기 원자적 rename | E1 | 충족(이 범위) |
| 7 | 운영 성숙도 | 적용 — 배포 버전과 이상 연결 | 부트·렌더 실패에 build_id, API 실패에는 없음 | E1 | 부분 충족 — 13-11 |
| 8 | 디버깅 가능성 | 적용 — 운영 오류를 빌드와 소스로 연결 | commit·build id는 manifest에 있음. 공개 source map 금지는 맞지만 비공개 source map 보관 경로가 없어 압축된 stack trace를 풀 수단이 없다 | E1 | 부분 충족 |
| 9 | 유지보수 성숙도 | 적용 — 설정·문서 드리프트 | 죽은 `.npmrc` 설정, 낡은 README, 사본 두 벌 | E3 | 부분 충족 — 13-09, 13-15 |
| 10 | 테스트 성숙도 | 적용 — 릴리스 규칙의 검증 | admission·coherence·캐시 모델 단위 테스트는 좋음(E2). CSP·운영 헤더 브라우저 검증 없음, drill은 상수 판정 | E2·E3 | 부분 충족 — 13-03, 13-08 |
| 11 | 데이터 성숙도 | 다른 영역 — 브라우저 저장소 | — | — | 적용 제외 |
| 12 | 동시성 성숙도 | 다른 영역 — 탭·저장소 | — | — | 적용 제외 |
| 13 | 확장성 | 다른 영역 — extreme-scale 문서·영역 | — | — | 적용 제외 |
| 14 | 성능 성숙도 | 적용 — 번들 예산 측정 조건 | 예산 M3, 조건 기록 있음, 여유 4%, lab 1회 | E3 | 부분 충족 — 13-14 |
| 15 | 보안 성숙도 | 적용 — CSP·헤더·번들 비밀값 | 헤더 선언 M1, 설정 키 금지·strict M4, 번들 비밀값 탐지 좁음. 참고: `dist/.vite/manifest.json`도 공개 배포물에 포함됨(소스 경로 노출, 영향 작음) | E3 | 부분 충족 — 13-06, 13-08 |
| 16 | 의존성 성숙도 | 적용 — 잠금·설치 스크립트·SBOM·provenance | frozen lockfile + `--ignore-scripts` CI에서 M4, sha512 전부, vulnerability 검사는 외부 미구성, `.npmrc` 무시, build에서 `npx` 사용(`build-frontend.ts:53`, 설치 전에는 registry 조회 가능) | E3 | 부분 충족 — 13-09, 13-12, 13-13 |
| 17 | API / Contract 성숙도 | 적용(좁게) — 설정·manifest 스키마 | 버전 판별 스키마, V1 reader 유지. 호환 게이트는 예제만 | E3 | 부분 충족 — 13-10 |
| 18 | 배포 성숙도 | 적용 — 검증물=배포물, HTML·자산 전환, 롤백 | 후보 archive 연결 강함(E2). admission 미실행, hosting 배포 전 실행, 파일 권한, drill이 다른 빌드 확인, 자산 보존 기간 없음 | E3 | 미충족 — 13-01~13-05 |
| 19 | 설정 성숙도 | 적용 — 스키마·우선순위·기본값·검증 위치 | 스키마 단일·strict·환경별 규칙 M4. 기본 프로필 local, 하위 경로 URL, 우선순위 미문서화 | E3 | 부분 충족 — 13-01, 13-07, 13-15 |
| 20 | 개발자 경험 | 적용 — build·배포 시작 경로 | `pnpm build` 5초 내 성공(실험). 운영 build 방법이 문서에 없음 | E3 | 부분 충족 — 13-15 |
| 21 | Guardrail 성숙도 | 적용 — gate가 실제로 실행·검출하는가 | negative fixture 다수. gate 소유 검사가 실행 여부를 보지 않음 | E3 | 부분 충족 — 13-01, 13-05 |
| 22 | 추상화 성숙도 | 다른 영역 | — | — | 적용 제외 |
| 23 | 일관성 | 적용 — 도구·경로 규칙 | `npx`와 `corepack pnpm` 혼용, dist/config.json writer 두 개, 경로 규칙 불일치 | E1 | 부분 충족 — 13-07 |
| 24 | 네이밍 / 의미 성숙도 | 적용 — gate 이름이 보장 범위와 맞는가 | "rollback-drill", "critical smoke", "config-compatibility"가 실제보다 넓게 들림 | E3 | 부분 충족 — 13-03, 13-10 |
| 25 | 조직 확장성 | 적용 제외 — 1인 관리(전제) | 구조적 준비만: gate 레지스트리·owner 필드 있음 | E1 | 적용 제외 |
| 26 | Ownership 성숙도 | 적용 — 승인·예외 책임 | 취약점 예외는 다른 reviewer 필수. dependency baseline 승인은 환경변수로 자기 기재(`update-dependency-baseline.ts:6-13`). runbook escalation 역할은 있으나 실제 담당 없음 | E1 | 부분 충족 |
| 27 | 삭제 가능성 | 다른 영역 — FE-GATE-020 제거 테스트. 이 영역: 공급망 체계를 끄는 경로가 문서에 없음 | M0 | E1 | 부분 충족 — 13-13 |
| 28 | 회복 가능성 | 적용 — 롤백 절차 실행 가능성 | 절차 문서 M1, 이전 release 재검증 불가, drill은 상수 판정, 복구 목표 TBD | E3 | 미충족 — 13-03, 13-04 |
### 5.1 33절 시나리오 적용
| 시나리오 | 적용 | 판정 |
|---|---|---|
| 새 환경 생성 | 부분 — CI 변수 목록 | `APP_PROFILE`·`RELEASE_TARGET` 누락(13-01). 호스팅은 provider 미정 |
| 인스턴스·노드 중단, 공통 의존성 장애, readiness·liveness, 자원 압박 | 적용 제외 — 정적 호스팅, 서버 프로세스 없음 | — |
| 백업·복구 | 적용 — 이전 release 보관과 복원 | 승격 artifact 보관 기간은 조직 결정으로 비움(`gates.json` retention `UNSUPPORTED_PENDING_ORGANIZATION_POLICY`). 이전 release 재검증 불가(13-04). 미충족 |
| 비밀값·인증서 교체 | 부분 — 프론트에는 런타임 비밀이 없음(설계상). provider 신뢰 키만 해당 | 키 교체·폐기 절차 없음(13-13). 미충족 |
| 공급망·배포 권한 | 적용 | 후보 digest·서명 연결 강함. 배포 단계와 그 권한은 repo 밖. 부분 충족 |
| 구성 차이 누적 | 적용 — 헤더·캐시 선언과 실제 | 배포 뒤 확인 없음(13-05). 미충족 |
| 기반 제거·이전 | 적용 제외 — 호스팅 자원이 repo에 없음 | — |
## 6. 미검증 목록
| 항목 | 필요한 것 |
|---|---|
| 실제 호스팅에서 헤더·SPA fallback·포인터 전환·이전 자산 보존 | provider 선정 후 live `verify:hosting-headers`와 deep link·404 확인 |
| Gitea에서 workflow 전체 실행(특히 immutable_build, provider, promotion) | staging Gitea와 runner, repo 변수 |
| 외부 vulnerability·provenance provider와 `test:system` | bwrap·systemd 254+·cgroup v2 위임 runner, 서명 키 |
| 운영 CSP 아래 브라우저 동작, `wss:` 차단 여부 | 헤더를 붙이는 정적 서버 + Playwright |
| production 프로필 산출물의 브라우저 부트 | 외부 인증·API 대역(e2e는 local/demo만 확인) |
| mode 0600 파일의 실제 403 | nginx 컨테이너에서 dist 서빙 |
| SW `ACTIVE` 2-pass build와 config 호환 | capability 선택 변경 후 build·e2e |
| 여러 runner 사이 빌드 재현성 | 서로 다른 runner 이미지에서 digest 비교 |
| lab performance(FE-GATE-026) | Playwright Chromium 실행 |
| pnpm 11의 최소 공개 경과 기간 기본값 | pnpm 문서 확인(`minimumReleaseAgeExclude`가 이를 전제함) |
@@ -0,0 +1,266 @@
# 템플릿 제품성·문서·개발자 경험 성숙도 리뷰
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 범위: `README.md`(181줄), `docs/`(추적 파일 118개, 약 61,800줄 — 표본 대조), `recipes/`(3,681줄), `schemas/`(5개), `.storybook/`(2개), `SPEC.md`·`tasks/`(826줄), 제거 스크립트 4개(823줄)와 `scripts/lib/removal-fixture.ts`, 기능 설치 생성기 `scripts/generate-product-feature-index.ts`, CI 계약 `scripts/contracts/ci-gates.ts`(해당 부분)
> 영역 판정(35.8): **조건부 사용 가능** — 샘플을 유지한 채 시작하는 용도에 한정. "샘플을 지우고 자기 기능으로 시작"하는 용도는 14-01·14-02를 고치기 전까지 **사용 보류**.
## 1. 결론
- **샘플 제거 게이트가 현재 main에서 실패한다(14-01, High).** `corepack pnpm test:sample-removal`(merge 단계 FE-GATE-020)을 실행한 결과 13개 검사 중 typecheck, unit-integration, coverage, home-smoke, fixture-id-residue 5개가 실패했다. 원인은 2026-09-24 수정 라운드(R-7.5, R-8.5, R-8.7, R-9.3, Q-6.8-10, Q-6.9-12)에서 추가된 플랫폼 테스트 6개가 샘플 기능을 직접 참조하는 것이다. README의 "샘플을 지워도 typecheck·test·build가 유지된다"는 주장은 지금 거짓이다. 이 템플릿을 복사한 프로젝트는 첫 PR부터 merge 게이트가 빨간 상태로 시작한다.
- **실제 프로젝트에서 샘플이나 선택 기능을 지우면 `check:ci`가 실패한다(14-02, Medium).** CI 계약이 "게이트 27개·명령 91개·참조 103개·산출물 109개"와 게이트 모양의 SHA-256 해시로 고정돼 있다. 제거 스크립트는 fixture 전용 완화 모드(`CI_CONTRACT_MODE=removal-fixture`)에서만 통과한다. 다운스트림이 이 기준선을 바꾸는 절차는 어디에도 문서화돼 있지 않다.
- **새 기능 추가 안내가 현재 설치 방식과 다르다(14-03, Medium).** 문서는 중앙 catalog 파일에 등록하라고 안내한다. 실제로는 `feature-module.ts`·`context-routes.ts`·context 선언을 두면 생성기가 기능을 찾아낸다. 이 규칙은 생성기 주석과 리뷰 폴더 안의 계획 문서에만 있다.
- **템플릿 버전 식별과 패치 전파 경로가 없다(14-04, Medium).** 태그, CHANGELOG, "원본 패치를 받는 방법" 문서가 없다. 최근 보안 수정(R-3.4, R-7.4, R-9.3)이 다운스트림에 전달될 경로도 없다.
- 문서는 이유·한계를 잘 설명하는 편이다. 다만 규모가 크고(약 62K줄), 현재 계약·목표 설계·작업 이력이 한 트리에 섞여 있으며, 최상위 지원 범위 표가 없다(14-05, 14-06). 수치·목록 drift도 여러 곳에 있다(14-07).
- 미검증: 깨끗한 환경에서 설치부터 실행까지, 나머지 제거 게이트 3개, 작성자 외 사용자의 기능 추가.
## 2. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` `4626b73`, 워킹트리 깨끗함(미추적 `CLAUDE.md`, 가이드 1개) |
| 목적·실행 구성 | 복사해서 시작점으로 쓰는 프론트엔드 템플릿. SPA + 정적 호스팅. SSR 없음 |
| 읽은 것 | README 전체, `docs/architecture`의 입구 문서(`starter-experience.md`, `overview.md`, `frontend-application-foundation.md`, `optional-adapter-recipes.md`, `capability-consumer-experience.md`, `browser-data-capability-completion-ledger.md` 앞부분, `frontend-platform-implementation-roadmap.md` 1~4절), `docs/testing/taxonomy.md`, `docs/operations/ci-quality-gates.md` 앞부분, `docs/contracts/compatibility.md`, `docs/styling/design-system-platform.md` 1·10절, `src/features/reference-feature/README.md`, 제거 스크립트 4개, `scripts/lib/removal-fixture.ts`, `scripts/lib/fixture-node-modules.ts`, 생성기, `scripts/contracts/ci-gates.ts` 430~620행, `scripts/verify-documentation-readiness.ts`, `scripts/update-registry-baseline.ts`, `config/recipes/frontend-capability-recipes.json`, `config/ci/gates.json`(구조), `.env.example`, `public/config.json`, `config/runtime/*.json` |
| 실행한 것 | ① `corepack pnpm test:sample-removal` — **실패(exit 1)**, 1분 49초. 스크립트를 먼저 읽고 `.tmp/reference-feature-removal-*`(gitignore, 종료 시 삭제)와 `artifacts/tests/sample-removal.xml`에만 쓰는 것을 확인한 뒤 실행했다. 실행 후 `git status`는 변화 없음. 로그: scratchpad `14/sample-removal.log`. ② CI 계약 파서 실험 — `config/ci/gates.json`을 메모리에서 바꿔 `parseCiGateContract`에 넣음(파일 쓰기 없음, scratchpad `14/ci-canonical-probe2.ts`). ③ README에 나오는 `pnpm <script>` 22개가 `package.json`에 있는지 대조 — 전부 있음. ④ Gitea API 읽기(`GET .../commits/38020da/status`) |
| 확인하지 못한 것 | 깨끗한 환경의 `install --frozen-lockfile` → `dev` 실행(공유 워킹트리·node_modules를 바꿀 수 있어 생략). `test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal`(34.8절 — 샘플 제거 실패로 FE-GATE-020 판정이 이미 나옴. 앞의 두 개는 고정 경로 `.tmp/<이름>`을 써서 병렬 에이전트와 충돌할 수 있음). 5,957줄짜리 "정본" 설계 문서 등 대형 설계 문서는 표본만 대조 |
| 직전 리뷰와 비교 | `2026-09-24-src-full-review.md`는 `src/`만 봤다. 이 영역의 문서·스크립트는 그 범위 밖이었다. 6.0(깨끗한 체크아웃 게이트)은 `package.json`의 `dev`/`build`/`check:*` 앞에 생성기가 붙어 있어 고쳐진 것으로 보인다(정적 확인만) |
### 2.1 20절 확인 과제를 문서만으로 따라가기
| 과제 | 문서 경로 | 결과 |
|---|---|---|
| 1. 런타임·패키지 관리자 확인 | README "Start locally" → `.nvmrc` 24.14.0, Corepack, `package.json` engines(`>=24.11 <25`, pnpm 11), `.npmrc` `engine-strict=true` | 가능 |
| 2. 설치·샘플 실행 | `corepack pnpm install --frozen-lockfile`, `corepack pnpm dev`. `dev`가 생성기를 먼저 실행한다 | 문서상 가능. 실행은 미검증 |
| 3. 테스트 하나 실행, 의도적 입력 오류 확인 | `docs/testing/taxonomy.md`는 "focused test"를 말하지만 파일 하나를 돌리는 명령(`node scripts/run-vitest.ts run <file>`)은 적혀 있지 않다. 잘못된 설정이면 "mount 전에 멈춘다"(`starter-experience.md:22`)는 설명만 있고 사용자가 보게 될 화면·메시지는 없다 | 부분 |
| 4. 작은 기능을 권장 구조로 추가 | `starter-experience.md:78-83` → `installed-feature-contracts.ts`를 열면 생성 파일(`src/.generated`, 미추적)에서 온 값을 합칠 뿐이다 → 생성기 소스 주석(`scripts/generate-product-feature-index.ts:95-107`)에서야 `feature-module.ts`/`context-module.ts` 규칙을 찾는다 → 주석이 가리키는 "Spec §5"는 `docs/reviews/…/extreme-scale-frontend-plan-bundle/…` 안에 있다 | **막힘** (14-03) |
| 5. 기본 샘플 제거 | `reference-feature/README.md`는 검증 명령(`test:sample-removal`)만 알려 준다. 실제로 지우는 순서는 스크립트 코드에만 있다. 그 검증도 지금 실패하고(14-01), 스크립트가 하는 설정 편집을 실제 repo에서 따라 하면 `check:ci`가 실패한다(14-02) | **막힘** |
| 6. 연결 실패·포트 충돌·필수 설정 누락 해결 | 문제 해결 문서가 없다. 포트 충돌은 Vite가 알아서 다른 포트를 쓴다. API(`localhost:8080`)가 없으면 샘플 화면이 오류 상태를 보여 주는 정도다 | 부분 |
관점 4(인지 부하) 대표 과제 — "route 하나를 가진 기능을 추가한다":
| 관찰 | 기록 |
|---|---|
| 시작점 | README → `docs/architecture/starter-experience.md` "Extending the starter" |
| 필수 지식 | FeatureModule 7필드(`src/features/feature-module.ts:44-60`), contract 9필드(route·route runtime·API operation·invalidation 3종·topic version·schema·runtime schema·mapper), context 선언 4개 리터럴, `context-routes.ts`의 `FEATURE_CONTEXT_ROUTES`, `ApplicationFeatureInputs` module augmentation, adapter contribution의 `needs`, runtime descriptor, ko-KR/en-US 메시지 카탈로그 |
| 뜻밖의 이동 | 문서가 가리킨 `installed-feature-contracts.ts` → `installed-product-manifest.ts` → 미추적 `src/.generated/` → 생성기 → 리뷰 폴더 안의 spec |
| 숨은 전제 | 생성기는 선언을 정규식으로 읽으므로 `export const FEATURE_MODULE_ID = "..."`처럼 **문자열 리터럴**이어야 한다(`generate-product-feature-index.ts:217-226`). `feature-module.ts`가 없는 기능 폴더는 **오류 없이 설치되지 않는다**(`:254-255`의 `catch { continue; }`. `local-draft-feature`가 일부러 이렇게 빠져 있다). route는 context의 `CONTEXT_ROUTE_PATH` 아래에 있어야 한다 |
| 오류 설명 | 생성기의 오류 메시지는 구체적이다("must export a literal FEATURE_MODULE_ID", 예산 초과 등). 조용히 빠지는 경우만 예외다 |
## 3. 확인된 강점
1. **제거 가능성을 merge 게이트로 둔 설계.** FE-GATE-020(removability)이 merge 단계에 있다(`config/ci/gates.json` stages.merge). 샘플 제거 스크립트는 공통 테스트가 남아 있는지(`scripts/test-sample-removal.ts:35-40`), `src`·`tests`·`dist`에 샘플 ID 잔여물이 없는지, route가 없어졌는지까지 검사한다. 그래서 이번 회귀(14-01)도 실행 한 번으로 드러났다. fixture는 `mkdtemp`와 `finally` 정리를 쓰고, `node_modules`를 항목별 심볼릭 링크로 연결해 pnpm이 원본 의존성을 지우는 사고를 막는다(`scripts/lib/fixture-node-modules.ts:4-17`).
2. **위험한 기본값이 운영 구성에 들어가지 못한다.** `AUTH_MODE=demo`는 설정 파싱 단계에서 `APP_ENV`가 local/development가 아니면 거부된다(`src/contracts/release-artifacts.ts:95-106`). 배포 승인 단계도 staging/production에 external 인증을 요구한다(`src/contracts/deployment-admission.ts:77-80`). 기본 `pnpm dev`는 외부 서비스 없이 셸을 띄운다(`public/config.json` — demo 인증, 텔레메트리 꺼짐).
3. **선택 기능의 도입 조건이 기계가 읽는 카탈로그로 있다.** 12개 recipe마다 도입 조건·금지 조건·fallback·제거 순서·gzip 예산·owner가 `config/recipes/frontend-capability-recipes.json`에 있고, 스키마(`schemas/config/frontend-capability-recipes.schema.json`)와 gate로 검사된다. 문서 표(`docs/architecture/optional-adapter-recipes.md` 3절)는 "카탈로그가 정본"이라고 우선순위를 밝힌다. `browser-data-capability-completion-ledger.md:27-40`은 COMPOSED와 AVAILABLE_NOT_COMPOSED를 구분해 "구현됨"과 "조립됨"이 섞이지 않게 한다.
4. **문서가 한계와 변경 조건을 적는다.** `capability-consumer-experience.md`의 "What this does and does not prove"는 증명한 것과 증명하지 않은 것을 나눈다. `frontend-application-foundation.md`는 공통화 조건("another feature repeats the same policy"), 파일 분리 기준, 플랫폼 계약이 맞지 않을 때 feature 전용 adapter로 빠지는 길(30.7)을 적는다. `frontend-platform-implementation-roadmap.md` 2절은 템플릿 밖 책임(IdP, 호스팅, RUM, 번역 승인 등)을 명시한다.
5. **생성 파일과 수정 파일의 구분이 표시되고 검사된다.** `.gitea/workflows/quality-gates.yml:1`("GENERATED FILE — edit config/ci/gates.json"), `src/.generated/*` 헤더("Do not edit by hand"), `check:ci-workflow`·`check:artifact-schemas`·`check:feature-index` drift 검사가 있다.
6. **README 명령과 실제 스크립트가 일치한다.** README에 나오는 22개 스크립트 이름이 모두 `package.json`에 있고, "27-gate"도 `scripts/contracts/ci-gates.ts:477`과 맞는다. 수동 접근성 검토 대상 route 목록은 `verify:documentation`이 route registry에서 뽑아 README와 대조한다.
## 4. 발견 사항 (36.3)
### 14-01 샘플 제거 게이트(FE-GATE-020)가 main에서 실패한다 — 플랫폼 테스트 6개가 샘플을 직접 참조
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 27, 10, 21, 20, 2, 30.5, 30.8 |
| 근거 | `corepack pnpm test:sample-removal` 실행 결과 exit 1: "Reference feature removal failed: typecheck, unit-integration, coverage, home-smoke, fixture-id-residue". 타입 오류: `tests/component/context-route-gateway.test.tsx:18`(`../../src/features/reference-feature/context-routes.ts` 없음), `tests/unit/installed-feature-messages.test.ts:7`(`reference-message-catalog.ts` 없음). 실패 테스트: `installed-feature-messages.test.ts`(카탈로그가 `[]`), `tests/component/route-status-surfaces.test.tsx:66`, `tests/component/router.test.tsx:142-160`의 3개 surface(`/examples/reference-resources`를 platform router 테스트에 씀 — 이 파일이 "home-smoke" 검사 대상이라 home smoke도 실패). 잔여물 검사 추가 실패: `tests/platform/telemetry/redact-telemetry.test.ts:41-43`, `tests/unit/observability-cardinality.test.ts:90`. `git blame` 결과 6개 모두 2026-09-24 수정 커밋(4e0745c R-9.3, 810849e R-7.5, 5e7cee1 R-8.5, 7022a1e R-8.7, 38db97a Q-6.8-10, 1e93d30 Q-6.9-12)에서 들어왔다 |
| 발생 조건 | (a) 템플릿 CI의 merge 단계 실행 (b) 다운스트림이 샘플 폴더를 실제로 지움 |
| 영향 | README `:66-71`("generic starter routes continue to typecheck, test, and build after that feature is removed")와 `starter-experience.md:88-90` 6단계가 지금은 틀렸다. 복사한 프로젝트는 첫 PR부터 MERGE_READY가 실패한다. 샘플을 지우면 typecheck와 테스트 6개가 깨지고, 사용자는 이 테스트들이 플랫폼 테스트인지 샘플 테스트인지 스스로 가려내야 한다 |
| 심각도·우선순위 | High · P1 — 템플릿의 핵심 주장(제거 가능한 샘플)과 merge 게이트가 현재 커밋에서 깨져 있다. 템플릿을 복사한 모든 프로젝트에 그대로 복제된다. 데이터·보안 피해는 없어서 Critical이나 P0는 아니다 |
| 통제·증거 | 목표 M3(게이트로 검출). 확인: 검출 장치는 있으나 수정 과정에서 돌지 않았다. `SPEC.md:18`과 `tasks/todo.md:9`의 공통 게이트 목록에 FE-GATE-020·`test:all`·`check:ci`가 없다. PR #2의 head `38020da`는 Gitea commit status가 0건이다(`GET /api/v1/repos/.../commits/38020da/status` → `total_count: 0`). CI 실행 증거 없이 merge된 것으로 보인다 · E3(실행) |
| 확실성과 남은 가정 | 실패 원인은 정적 import와 로그로 확정했다. Gitea Actions가 이 repo에서 꺼져 있는지 아니면 실패를 무시했는지는 확인하지 못했다 |
| 최소 개선 방향 | 플랫폼 테스트가 샘플 대신 테스트 전용 가짜 기능(`tests/fixtures/…`의 feature module)이나 platform route를 쓰게 바꾼다. 샘플에 대한 단언이 꼭 필요하면 `tests/features/reference-feature/`로 옮긴다(제거 스크립트가 함께 지운다). 수정 라운드의 공통 게이트 목록에 `test:sample-removal`을 넣는다 |
| 비용·부작용 | 테스트 6개 수정. 테스트용 feature fixture를 하나 만들면 다른 플랫폼 테스트도 같은 fixture를 재사용할 수 있다 |
| 완료 기준 | main에서 `test:sample-removal`이 PASS하고 JUnit 13개 testcase가 모두 성공이다. PR에 FE-GATE-020 상태가 기록된다 |
| 검증 방법 | `corepack pnpm test:sample-removal`. Gitea branch protection에 required check 설정 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 직전 리뷰 수정(R-7.5, R-8.5, R-8.7, R-9.3, Q-6.8-10, Q-6.9-12)에서 생긴 회귀 |
### 14-02 CI 계약이 템플릿 자신의 모양(개수·해시)에 고정돼 있어, 실제 제거·추가를 하면 `check:ci`가 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.3, 30.7, 27, 20, 21, 3, 25 |
| 근거 | canonical 모드는 게이트 27개, 명령 정의 91개·참조 103개, 산출물 109개, stage 5개를 정확히 요구한다(`scripts/contracts/ci-gates.ts:477-490`). 게이트 모양 SHA-256도 상수로 고정돼 있다(`:445`, `:553-556`). job 9개 순서(`:868`), `FE-GATE-001..027` 순서(`:788`)도 고정이다. 제거 스크립트는 `CI_CONTRACT_MODE=removal-fixture`와 `--reduced-removal-fixture`로 이 검사를 끄고서 통과한다(`scripts/lib/removal-fixture.ts:162-172`, `:330-334`). 실험(메모리에서만 변경): `test-reference-feature` 명령 1개와 그 산출물을 뺀 계약 → canonical "command authority baseline must contain exactly 91 definitions and 103 references; received 90 … artifact … exactly 109; received 108", removal-fixture 모드 → PASS. 명령 1개 추가 → canonical FAIL, removal-fixture PASS. 같은 구조의 두 번째 기준선: 샘플 제거는 registry 관점에서 breaking 변경이라 `check:registries`가 `config/contracts/registry-change-evidence.json` 항목(versionBump, migration, compatibilityWindow, rollback, owner)을 요구한다(`scripts/lib/registry-compatibility.ts:300-330`). 기준선을 새로 찍는 `scripts/update-registry-baseline.ts`는 package script가 아니고 README·docs(리뷰·이력 폴더 제외)에 언급이 없다. 샘플 제거 스크립트는 `check:registries:structure`(`--no-baseline`)로 이 검사도 피한다(`test-sample-removal.ts:320`) |
| 발생 조건 | 다운스트림이 샘플·recipe·realtime 등을 실제로 지우거나, 자기 CI 명령·게이트·산출물을 하나라도 추가·삭제할 때 |
| 영향 | FE-GATE-020이 증명하는 것은 "완화 모드에서의 제거"다. 다운스트림이 실제로 쓸 수 있는 제거 경로는 증명되지 않는다. 다운스트림은 `scripts/contracts/ci-gates.ts`의 가드 상수와 해시를 직접 고쳐야 한다. 문서(`docs/operations/ci-quality-gates.md:5-7`)는 "registry를 고치고 `generate:ci-workflow`를 돌려 커밋하라"고만 한다. 템플릿이 소유하는 기준선과 프로젝트가 소유할 기준선이 구분돼 있지 않다 |
| 심각도·우선순위 | Medium · P1 — 실패는 조용하지 않고 우회 방법(상수 수정)도 있어 피해는 제한적이다. 하지만 "복사해서 내 프로젝트로 시작"이라는 기본 용도에서 첫 구조 변경마다 걸리는 차단 항목이다 |
| 통제·증거 | 가드 자체는 M4에 가깝다. 다운스트림 변경 절차는 M0(부재 확인) · E2(파서 실행 실험) |
| 확실성과 남은 가정 | 개수·해시 검사는 코드로 확정했다. 작성자가 이 고정을 "다운스트림도 상수를 고친다"는 의도로 뒀을 수 있다. 그렇다면 결함은 절차 부재로 좁혀진다 |
| 최소 개선 방향 | ① "새 프로젝트 시작 시 초기화할 기준선" 목록을 문서로 둔다(CI 권한 수치·해시, registry baseline·approval, coverage `repositoryBaseline`, runtime profile의 `FEATURE_OVERRIDES`). ② CI 권한 수치·해시를 코드 상수 대신 `config/ci/` 아래 승인 파일(owner·reason 포함)로 옮기고, `update:registry-baseline`처럼 갱신 스크립트를 package script로 제공한다. ③ 제거 스크립트는 완화 모드 대신 이 갱신 절차를 거쳐 canonical `check:ci`를 통과하게 한다 |
| 비용·부작용 | ②는 가드가 약해질 수 있다. 승인 파일에 owner·reason을 요구하고 diff를 리뷰 대상으로 두면 된다 |
| 완료 기준 | 샘플을 지운 fixture가 `CI_CONTRACT_MODE` 없이 canonical `check:ci`와 `check:registries`를 통과한다. 그 절차가 문서에 있다 |
| 검증 방법 | 제거 스크립트에서 `CI_CONTRACT_MODE`·`--reduced-removal-fixture`·`--no-baseline`을 빼고 실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 14-03 새 기능 추가 안내가 현재 설치 방식(생성기 + feature/context 선언)과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 4, 9, 3, 25, 30.5, 30.6 |
| 근거 | `docs/architecture/starter-experience.md:78-83`: "install it through `src/features/installed-feature-contracts.ts`", runtime·adapter도 각 중앙 파일을 통해 넣으라고 한다. 실제로는 `installed-feature-contracts.ts`가 `installed-product-manifest.ts` → `src/.generated/product-feature-index.ts`(생성기 출력, 미추적)를 합칠 뿐이다. 기능은 `src/features/<f>/feature-module.ts`(`FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE`), `context-routes.ts`(`FEATURE_CONTEXT_ROUTES`), `src/contexts/<c>/context-module.ts`(4개 리터럴)로 발견된다(`scripts/generate-product-feature-index.ts:95-107`, `:270-301`). 이 규칙이 적힌 곳은 생성기 주석과 `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` §3.2·§5뿐이다. 코드 주석은 경로 없이 "Spec §5.2"만 적는다(`src/contexts/reference-context/context-module.ts:2`, `src/apps/template-app/app-module.ts:2`). `frontend-application-foundation.md:98-103`도 생성기를 언급하지 않는다. 같은 문서의 route 표(`starter-experience.md:29-36`)는 등록된 10개 중 6개만 적는다(`EXAMPLES_PLATFORM`, `REFERENCE_RESOURCE_DETAIL/FORM/STATUS` 누락) |
| 발생 조건 | 작성자 도움 없이 첫 기능을 추가할 때(20절 과제 4) |
| 영향 | 문서를 따르면 중앙 catalog를 손으로 고치게 된다. 이 방식은 문서가 금지하는 "중앙 catalog에 기능별 조립"이고, 생성기의 context 예산 검사도 거치지 않는다. 폴더만 만들고 `feature-module.ts`를 빠뜨리면 오류 없이 설치되지 않는다(`generate-product-feature-index.ts:254-255`). 가장 많이 복제되는 작업의 입구가 잘못돼 있다 |
| 심각도·우선순위 | Medium · P2 — 탐색 비용과 잘못된 등록 위험. 데이터·보안 피해는 없다 |
| 통제·증거 | M1이 틀린 상태(문서는 있으나 코드와 다름) · E1 |
| 확실성과 남은 가정 | 중앙 파일에 손으로 contract를 넣었을 때 어떤 gate가 잡는지는 실험하지 않았다 |
| 최소 개선 방향 | `starter-experience.md` "Extending the starter"를 현재 절차로 바꾼다: 기능 폴더 구조, 선언 파일 3개와 필수 export, context route 루트, `generate:feature-index`, 확인 명령. spec §3.2·§5는 `docs/architecture/`로 옮기고 코드 주석이 그 경로를 가리키게 한다. route 표는 지우거나 `verify:documentation` 대상에 넣는다. 선언 파일이 없는 기능 폴더는 경고하거나, 제외를 명시적으로 표시하게 한다 |
| 비용·부작용 | 문서 1~2개 수정. 생성기 경고는 `local-draft-feature` 같은 의도된 예외를 표시할 방법이 필요하다 |
| 완료 기준 | 문서만 보고 빈 기능 하나를 추가해 route가 뜨고 `check:architecture`·`check:types`가 통과한다 |
| 검증 방법 | 작성자 외 사람(또는 문서만 준 에이전트)에게 과제 4를 수행시키고 막힌 지점을 기록한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 14-04 템플릿 버전 식별과 다운스트림 패치 전파 경로가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 30.4, 26, 16, 9 |
| 근거 | `package.json` `version: 0.1.0`, git tag 0개(`git tag` 결과 없음). 생성 workflow는 `tags: ["v*"]`에 반응하도록 돼 있다(`.gitea/workflows/quality-gates.yml:7`). CHANGELOG·릴리스 노트·"원본 변경 반영 방법" 문서가 없다(`upstream`/`downstream`/`changelog`로 README·docs 검색 — 리뷰·이력 폴더 제외 — 관련 결과 없음). 복사한 프로젝트가 어느 커밋에서 출발했는지 남기는 표식도 없다. 템플릿 결함과 사용 프로젝트 결함을 누가 분류하고 패치를 누가 적용하는지(26)도 적혀 있지 않다. 템플릿 밖 책임 목록은 있으나(`frontend-platform-implementation-roadmap.md` 2절) 로드맵 안에 묻혀 있다 |
| 발생 조건 | 템플릿에서 보안·계약 수정이 나올 때. 예: 이번 라운드의 R-3.4(자격증명 헤더 검증), R-7.4(COMMAND 메서드 제한, CSRF), R-9.3(텔레메트리 리댁션) |
| 영향 | 이미 복사한 프로젝트는 수정이 나왔다는 사실도, 어떤 파일을 가져가야 하는지도 알 수 없다. 템플릿의 가치(한 번 고치면 여러 프로젝트가 혜택)가 복사 시점에 끊긴다 |
| 심각도·우선순위 | Medium · P2 — 다운스트림 수는 미확인이다. 보안 수정이 전파되지 않는 경로가 복사본 수만큼 복제된다 |
| 통제·증거 | M0(부재 확인) · E1 |
| 확실성과 남은 가정 | 작성자가 repo 밖에서 다운스트림을 관리하는지는 모른다 |
| 최소 개선 방향 | ① 의미 있는 수정 묶음마다 태그(`vX.Y.Z`)와 짧은 CHANGELOG(보안·계약 변경은 별도 표시, 영향 파일 경로 포함)를 남긴다. ② README에 "복사 후 출발 커밋을 기록하는 위치"와 "원본 패치를 cherry-pick·diff로 가져오는 방법"을 둔다. ③ 템플릿 결함 신고·분류 책임 한 줄 |
| 비용·부작용 | 릴리스마다 몇 분. 템플릿 소유자가 1인이라 가벼운 형식이 맞다 |
| 완료 기준 | 태그 1개 이상, CHANGELOG, README의 업데이트 절 |
| 검증 방법 | 30.4절 검증 — 사용자 수정이 들어간 복사본에 작은 보안 패치를 한 번 반영해 충돌·테스트·되돌림을 기록한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 14-05 문서 규모가 크고 현재 계약·목표 설계·작업 이력이 한 트리에 섞여 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 9, 4, 20, 30.6 |
| 근거 | 추적 중인 `docs/`가 118개 파일, 약 61,800줄이다. `docs/architecture`만 약 34,000줄이고, 가장 큰 문서는 5,957줄이다(`2026-07-30-frontend-runtime-capability-…-closed-deep-design.md`). 로드맵(1,277줄)은 스스로 "non-authoritative"라며 그 5,957줄 문서를 정본으로 지정한다(`frontend-platform-implementation-roadmap.md:3-8`). README는 링크한 16개 문서가 "target designs and review findings"라고 밝힌다(`README.md:95-99`). 작업 이력(`docs/superpowers/` 27개, 약 11,000줄)과 리뷰(`docs/reviews/`)가 약 22,200줄이다. 그 리뷰 폴더 안의 계획 번들이 현재 topology의 유일한 명세다(14-03). 루트의 `SPEC.md`·`tasks/`는 이번 수정 라운드의 작업 추적이다. 문서 색인(현재/목표/이력 구분)은 없다. 언어도 섞여 있다(README·입구 문서는 영어, `reference-feature/README.md`·recipe·ledger·스타일 문서는 한국어) |
| 발생 조건 | 새 사용자가 "지금 무엇이 동작하고 무엇이 계획인가"를 찾을 때. 템플릿을 복사할 때 |
| 영향 | 읽는 사람이 어떤 문장이 현재 계약인지 판단하려면 여러 문서의 우선순위 규칙을 알아야 한다. 복사한 프로젝트가 템플릿 작업 이력 약 2만 줄과 `SPEC.md`·`tasks/`를 함께 받는다. 무엇을 지워도 되는지 목록이 없다 |
| 심각도·우선순위 | Medium · P2 — 탐색 비용이 반복해서 든다. 계약 위반은 아니다 |
| 통제·증거 | M1(일부 문서에 우선순위 선언) · E1 |
| 확실성과 남은 가정 | 대형 설계 문서는 표본만 대조했다. 전체 drift 비율은 모른다 |
| 최소 개선 방향 | `docs/README.md` 색인 하나: ① 현재 계약(입구 5~6개), ② 목표 설계, ③ 작업 이력·리뷰(다운스트림이 지워도 되는 폴더라고 표시). `SPEC.md`·`tasks/`는 `docs/` 아래 이력 폴더로 옮긴다. 현재 계약 문서에 쓰인 규칙이 설계 문서에 있으면 짧게 옮기고 링크한다 |
| 비용·부작용 | 파일 이동 시 `review-ledger.json` 등 경로 참조를 함께 고쳐야 한다 |
| 완료 기준 | 색인이 있고, 복사 후 지울 폴더 목록이 README에 있다 |
| 검증 방법 | 20절 과제 1~6을 색인만 보고 다시 따라간다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 14-06 최상위 지원 범위 표(기본/선택/실험/비지원)가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 30.2, 20, 23 |
| 근거 | 선택 기능은 recipe 카탈로그와 ledger에서 잘 구분된다(강점 3). 하지만 README에는 SSR 비지원(`client-cache-and-storage.md:32`, `:123`의 `NOT_SELECTED`), 지원 브라우저(테스트는 chromium·firefox·webkit, browserslist 없음), 인증 모드, 호스팅 형태를 한 번에 보여 주는 표가 없다. "실험" 범주도 없다. 상태 어휘가 문서마다 다르다: recipe `RECIPE_AVAILABLE`, ledger `COMPOSED/AVAILABLE_NOT_COMPOSED/DESIGNED_NOT_IMPLEMENTED/NOT_SELECTED/PLATFORM_LIMITED`, catalog `defaultStatus: NOT_INSTALLED`, recipe 문서 10단계의 `INSTALLED` |
| 발생 조건 | 도입 여부를 판단할 때 |
| 영향 | 비지원 항목을 README에서 볼 수 없다. 여러 문서를 읽어야 확인할 수 있다 |
| 심각도·우선순위 | Low · P3 — 정보는 존재하고, 0.1 전제대로 기본과 opt-in 구분은 문서에 있다 |
| 통제·증거 | M1(분산) · E1 |
| 확실성과 남은 가정 | 없음 |
| 최소 개선 방향 | README에 4행 표 하나(기본 지원 / 선택 지원 = recipe / 실험 / 비지원 = SSR·앱 관리 background transfer 등)와 상태 어휘 대응표 |
| 비용·부작용 | 표 유지 비용. 가능하면 catalog에서 생성한다 |
| 완료 기준 | README 표 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 14-07 문서의 수치·목록이 코드와 어긋나 있고, DOCUMENTATION_READY 게이트는 이를 검사하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 24, 21, 19 |
| 근거 | 표본 대조 결과: ① `docs/operations/ci-quality-gates.md:3` "all 26 gates" ↔ 코드 27개(`scripts/contracts/ci-gates.ts:477`, README `:169`). ② `docs/architecture/capability-consumer-experience.md:22-26` LOC 91/109/65/41, 합계 306 ↔ 현재 137/137/82/50, 합계 406. ③ `starter-experience.md:29-36` route 6개 ↔ 등록 10개(14-03). ④ `.env.example:9`는 runtime profile 설명을 `docs/architecture/layers.md`에서 보라고 하지만 그 문서에는 `config/runtime`·`config.json` 언급이 없다. README `:24`는 설정 위치를 `public/config.json`이라고만 한다(배포 값은 `config/runtime/<profile>.json`). `verify:documentation`은 diagram 리뷰 ledger와 `review-evidence.md`가 서로 같은 문자열을 담는지, README·`manual-checklist.md`에 route ID가 있는지만 본다(`scripts/verify-documentation-readiness.ts:17-20`, `:44-95`). 대조 대상 diagram 파일은 repo 밖에 있다(`review-ledger.json` note) |
| 발생 조건 | 코드 변경 뒤 문서가 따라오지 않을 때 |
| 영향 | 게이트 이름(DOCUMENTATION_READY)이 보장 범위보다 크게 읽힌다. 수치가 틀린 문서는 문서 전체의 신뢰를 떨어뜨린다 |
| 심각도·우선순위 | Low · P3 — 제한된 문서 불일치 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 표본 대조다. 다른 drift가 더 있을 수 있다 |
| 최소 개선 방향 | ①~④를 고친다. 손으로 쓴 수치(게이트 수, LOC)는 문서에서 빼거나 생성 값을 인용한다. 게이트 설명에 "route ID와 diagram ledger만 검사"라고 범위를 적는다 |
| 비용·부작용 | 작음 |
| 완료 기준 | 네 곳 수정, 게이트 범위 문구 |
| 검증 방법 | `grep`으로 수치 대조, `verify:documentation` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 14-08 제거 스크립트의 실패 보고가 원인을 가린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 27, 10 |
| 근거 | `scripts/test-sample-removal.ts:367`은 실패 수와 관계없이 `failures="1"`을 쓴다(이번 실행: 5개 실패인데 1). `:371`은 실패한 모든 testcase의 메시지에 잔여물 파일 목록을 넣는다. 그래서 JUnit만 보면 typecheck 실패 원인도 "잔여물 파일 목록"으로 보인다. 실제 타입 오류는 콘솔 로그에만 있다. `scripts/test-optional-recipe-removal.ts`는 고정 경로 `.tmp/optional-recipe-removal`을 쓰고 `try/finally`가 없어서 예외가 나면 fixture가 남는다. 두 번 동시에 실행하면 서로 덮어쓴다(`test-realtime-runtime-removal.ts:19`도 고정 경로) |
| 발생 조건 | 제거 게이트 실패 시 CI 산출물(JUnit)로 원인을 볼 때, 병렬 실행 시 |
| 영향 | 실패 원인을 좁히려면 긴 로그(이번 실행 3,696줄)를 다시 읽어야 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E3(실행 결과 XML 확인) |
| 확실성과 남은 가정 | 없음 |
| 최소 개선 방향 | `failures`에 실제 실패 수를 쓰고, testcase마다 자기 원인(명령 이름과 exit code, 잔여물은 residue 검사에만)을 넣는다. 네 스크립트 모두 `mkdtemp` + `finally`로 맞춘다 |
| 비용·부작용 | 작음 |
| 완료 기준 | 실패 시 XML의 failure 메시지가 검사별로 다르다 |
| 검증 방법 | 일부러 실패시킨 fixture로 XML 확인(`tests/unit/removal-fixture.test.ts`에 추가 가능) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
## 5. 28개 관점 판정 (36.2)
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 다른 영역 — 01~13 | - | - | 적용 제외 |
| 2 | 구조적 성숙도 | 부분 적용 — 플랫폼 테스트가 샘플 기능에 결합된 것만 확인 | M3 / 검출 장치는 있으나 미실행 | E3 | 부분 충족 — 14-01 |
| 3 | 변경 용이성 | 적용 — 기능 추가·제거 경로 | M3 / 제거 경로가 canonical 게이트와 충돌 | E2 | 부분 충족 — 14-02, 14-03 |
| 4 | 인지 부하 | 적용 — 대표 과제 "기능 추가"를 문서만으로 수행 | M1 / 입구 문서가 틀림 | E1 | 부분 충족 — 14-03, 14-05. 숨은 전제: 리터럴 export, 선언 누락 시 조용히 제외 |
| 5 | 위험 가시성 | 다른 영역 | - | - | 적용 제외 |
| 6 | 실패 성숙도 | 다른 영역 | - | - | 적용 제외 |
| 7 | 운영 성숙도 | 다른 영역 — runbook·운영 문서는 운영 영역 | - | - | 적용 제외 |
| 8 | 디버깅 가능성 | 부분 적용 — 제거 게이트의 실패 보고 | M2 | E3 | 부분 충족 — 14-08 |
| 9 | 유지보수 성숙도 | 적용 — 문서가 이유·한계·변경 조건을 설명하는가 | M1 | E1 | 부분 충족 — 입구 문서는 이유·한계를 잘 적음(강점 4). 규모·혼합·drift는 14-05, 14-07 |
| 10 | 테스트 성숙도 | 부분 적용 — 제거 게이트 | M3 / main에서 실패 | E3 | 부분 충족 — 14-01 |
| 11 | 데이터 성숙도 | 다른 영역 | - | - | 적용 제외 |
| 12 | 동시성 성숙도 | 다른 영역 | - | - | 적용 제외 |
| 13 | 확장성 | 다른 영역 — extreme-scale 영역 | - | - | 적용 제외 |
| 14 | 성능 성숙도 | 다른 영역 | - | - | 적용 제외 |
| 15 | 보안 성숙도 | 다른 영역. demo 인증 차단만 강점으로 확인 | M4(설정 파싱) | E1 | 적용 제외(이 영역) |
| 16 | 의존성 성숙도 | 다른 영역. 보안 패치 전파만 여기서 봄 | M0 | E1 | 부분 — 14-04 |
| 17 | API / Contract 성숙도 | 다른 영역. registry 기준선이 제거를 막는 부분만 14-02 | - | E1 | 적용 제외(이 영역) |
| 18 | 배포 성숙도 | 다른 영역 | - | - | 적용 제외 |
| 19 | 설정 성숙도 | 다른 영역. 설정 위치 문서 drift만 14-07 | M1 | E1 | 적용 제외(이 영역) |
| 20 | 개발자 경험 | 적용 — 20절 과제 1~6 | M1~M3 / 과제 4·5 막힘 | E1, E3 | 미충족 — 과제 4·5를 작성자 도움 없이 끝낼 수 없음(14-01~14-03). README 명령 22개는 모두 실재 |
| 21 | Guardrail 성숙도 | 부분 적용 — 제거 게이트, 문서 게이트, CI 계약 가드 | M3 / PR에서 게이트 실행 증거 없음(status 0건) | E3, E1 | 부분 충족 — 14-01, 14-02, 14-07. CI 실행 강제는 CI 영역과 공유 |
| 22 | 추상화 성숙도 | 다른 영역 | - | - | 적용 제외 |
| 23 | 일관성 | 부분 적용 — 문서 언어·상태 어휘 | - | E1 | 부분 충족 — 14-05(언어 혼용), 14-06(상태 어휘 여러 벌) |
| 24 | 네이밍 / 의미 성숙도 | 부분 적용 — 게이트 이름이 보장 범위를 과장 | M1 | E1 | 부분 충족 — 14-07(DOCUMENTATION_READY) |
| 25 | 조직 확장성 | 구조적 준비만 평가(작성자 1인) | M2 | E1 | 부분 충족 — 기능별 contribution·생성기·context 예산은 준비됨. 공유 JSON(`risk-coverage.json`, `test-evidence.json`, `registry-governance.json`, `registry-baseline.json`, `gates.json`, runtime profile)은 여러 팀이 동시에 고치는 지점이 되고, CI 변경마다 코드 상수·해시를 고쳐야 한다(14-02). 실제 조직 확장은 미확인 |
| 26 | Ownership 성숙도 | 적용 — 템플릿 결함과 사용 프로젝트 결함의 책임 구분 | M1(템플릿 밖 책임 목록만) | E1 | 부분 충족 — 14-04 |
| 27 | 삭제 가능성 | 적용 — 제거 스크립트 4개 | M3 / 샘플 제거 실패, 실제 제거 경로 미증명 | E3(샘플), 미검증(나머지 3개) | 미충족 — 14-01, 14-02, 14-08 |
| 28 | 회복 가능성 | 다른 영역 | - | - | 적용 제외 |
### 5.1 30절 템플릿 기준 판정
| 절 | 판정 | 근거 |
|---|---|---|
| 30.1 최소 구성과 안전한 기본값 | 부분 충족 | 외부 의존 없이 `dev`가 뜨는 구성(demo 인증, 텔레메트리 꺼짐). demo는 local/development 밖에서 파싱 단계에서 거부된다(강점 2). 깨끗한 환경 실행은 미검증 |
| 30.2 옵션 조합 | 부분 충족 | recipe 12개의 도입·금지 조건과 fallback이 카탈로그에 있다. 최상위 지원 표, 실험 범주, 조합 제약(예: Web Push = realtime + service-worker + permission 조합, `optional-adapter-recipes.md` 3절 끝)의 검증 범위 표가 없다 — 14-06 |
| 30.3 생성·복사 후 수정 권한 | 부분 충족 | 생성 파일은 표시·drift 검사가 된다(강점 5). 템플릿 소유 기준선(CI 수치·해시, registry baseline, coverage 기준선)과 프로젝트가 고칠 곳이 구분되지 않는다 — 14-02 |
| 30.4 버전과 업데이트 전파 | 미충족 | 태그·CHANGELOG·전파 절차 없음 — 14-04 |
| 30.5 샘플 대표성 | 부분 충족 | reference feature는 목록·상세·폼·상태 화면, 실패 분류, 멱등 생성, typed failure를 보여 준다. 두 번째 모양(IndexedDB local draft)도 있다. 샘플이 플랫폼 테스트에 결합돼 있고(14-01), 샘플을 따라 기능을 추가하는 문서가 틀리다(14-03) |
| 30.6 도입·유지 비용 | 부분 충족 — 비용 높음 | package script 141개, CI 게이트 27개(명령 91개), 문서 약 62K줄. 샘플 기능 21개 파일 1,787줄. 첫 기능에 필요한 개념 약 10개(2.1절 표). 샘플 제거 검증 1분 49초(22코어) |
| 30.7 졸업 가능성 | 부분 충족 | feature 전용 adapter로 빠지는 길, 공통화·분리 기준이 문서화돼 있다(강점 4). CI 계약이 코드 상수·해시로 잠겨 있고 topology 규칙이 리뷰 폴더에만 있어, 구조를 바꿀 때 알아야 할 것이 문서 밖에 있다 — 14-02, 14-03 |
| 30.8 배포 판단 최소 증거 | 부분 충족 | "새 프로젝트 시작": 깨끗한 환경 증거 미확인. "기본 패턴 복제": 작성자 외 사용자 증거 없음. "선택 기능 분리": 샘플 제거 게이트 실패(14-01), 나머지 3개 미검증. "패치 전달": 증거 없음(14-04). "외부 증거가 필요한 게이트는 FAIL_UNVERIFIED 유지"라는 원칙은 README와 로드맵에 명시돼 있다 |
## 6. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 깨끗한 환경에서 `install --frozen-lockfile` → `dev` → 첫 화면 | 공유 워킹트리·`node_modules`를 건드릴 수 있어 생략 | 별도 컨테이너나 새 clone에서 README 명령만 실행 |
| `test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal` | 34.8절(샘플 결과로 FE-GATE-020 판정이 이미 나옴). 앞의 두 개는 고정 `.tmp` 경로라 병렬 에이전트와 충돌 가능 | 단독 환경에서 세 명령 실행 |
| PR에서 CI가 실제로 도는지 | PR #2 head의 commit status가 0건이라는 것만 확인. Actions 설정·runner·branch protection은 권한 밖 | Gitea 저장소 설정(Actions 활성화, required checks) 확인 |
| 중앙 catalog에 손으로 contract를 넣었을 때 어떤 gate가 잡는지 | 코드 변경 실험이 필요 | worktree에서 실험 |
| 작성자 외 사용자의 기능 추가 | 사람·기록 없음 | 14-03 수정 뒤 과제 4를 다른 사람에게 맡겨 기록 |
| 대형 설계 문서(5,957줄 정본 등)의 전체 drift | 표본 대조만 수행 | 문서별 핵심 주장 목록을 뽑아 코드와 대조 |
@@ -0,0 +1,93 @@
# 성숙도 리뷰(2026-09-25) 반영 뒤 남긴 판단과 후속 작업
2026-09-28 기준, `main` `f753669`(태그 `v0.2.0`)에 남아 있는 것을 적는다. 리뷰 발견은 모두 닫혔다(`README.md` 10·11절). 아래는 "실무 기준이라면 이렇게 두지 않았겠지만, 이번 라운드에서는 이렇게 두었다"고 판단한 것들이다. 다음 리뷰 라운드는 이 문서에서 출발한다.
우선순위는 P1(다음 작업 전에 처리), P2(다음 라운드), P3(기회가 될 때)이다.
## 1. 기준을 고치는 대신 한도를 올리거나 목록에 넣은 것
| 우선 | 항목 | 현재 상태 | 왜 이렇게 두었나 | 다음 행동 |
|---|---|---|---|---|
| P1 | 초기 JS 예산 | `check:bundle` 203,481 / 204,800 gzip bytes. 여유 약 1.3KB | 11-04 측정에서 실제 모양 기능 하나가 초기 JS를 약 2.9KB 늘린다(`config/scale/feature-shape-growth.json`). 이번 라운드는 측정과 기록까지만 했다 | 기능을 하나 더 넣으면 게이트가 실패한다. 초기 청크에 들어가는 기능 코드를 route 청크로 옮기거나, 예산 근거를 다시 정한다 |
| P2 | 레시피 번들 예산 인상 | realtime 40,000 → 40,900(`2c5e268`), file-transfer 55,600 → 55,700(`4b0e44a`). offline-indexeddb 36,891 / 36,900(여유 9바이트) | 기존 규칙(측정값을 100바이트 단위로 올림)을 따랐다. 코드를 줄이지 않고 한도를 맞췄다 | 레시피마다 늘어난 원인을 보고 줄일 수 있는지 본다. offline-indexeddb는 다음 수정에서 바로 넘는다 |
| P2 | `check:remediation-ledger` | 실패한다. 게이트 제외 목록(`config/ci/ungated-scripts.json`)에 이유와 함께 있다 | 리뷰 전(`4626b73`)부터 실패했다. 2026-09-18 리팩터링 뒤 테스트 마커(TR-02~TR-04, X-AUDIT-01·02)가 빠졌고, 원장(`docs/operations/adapter-remediation-ledger.md`)의 file-transfer 예산 문구가 옛 값이다 | 원장을 현재 코드에 맞추거나, 역사 기록으로 보고 검사를 없앤다. 맞춘 뒤에는 게이트에 연결한다 |
제외 목록의 나머지 16개(`check:scale:*`, `verify:extreme-scale`, `test:all` 등)는 로컬 단축 명령이거나 CI가 나눠서 돌리는 묶음이라 빠진 검사가 아니다.
## 2. 프로젝트 원칙과 어긋나게 들어간 것
| 우선 | 항목 | 내용 | 다음 행동 |
|---|---|---|---|
| P2 | `readSubject` 필수화(`c6300e9`) | 계획의 원칙은 "공개 포트는 추가만 한다"인데, 이 변경은 `ExternalSessionOwner.readSubject()`와 `SessionGateway.getSubject()`를 필수로 바꾼다. "전부 main에 합친다"는 지시로 병합했고, CHANGELOG 0.2.0에 [계약]으로 표시했다 | 복사한 프로젝트를 위한 이행 절차(없는 owner는 `integration-failed`로 닫힘)를 README 업데이트 절에 한 줄 더 적는다. 앞으로 같은 종류의 변경은 선택 필드 → 경고 → 필수의 단계를 둘지 정한다 |
## 3. 원인을 고치지 않고 환경 탓으로 넘긴 테스트
| 우선 | 테스트 | 관찰 | 다음 행동 |
|---|---|---|---|
| P1 | `tests/integration/provider-guardian-transaction.test.ts` | 부하가 높을 때 시간 초과. 검증 중 20번에 2번 실패 | 시간 의존 대기를 없애거나 fake timer로 바꾼다 |
| P1 | `tests/component/runtime-application.test.tsx` | 부하 평균 약 18~22에서 heading이 `aria-busy` 상태로 남아 실패. 단독 재실행은 통과 | 첫 대기 조건을 10-02와 같은 방식으로 고친다 |
| P2 | `http-execution-v3-live-authority` 테스트 | 검증 중 한 번 실패 | 재현 조건을 찾는다 |
| P2 | 10-02 후속 | reference-page 첫 대기는 고쳤지만, 무거운 부하에서 같은 파일의 다른 테스트가 한 번 실패했고 메시지가 여전히 "element not found"다 | 같은 파일의 나머지 대기도 같은 방식으로 바꾼다 |
| P3 | `tests/system/ci-runner/ci-artifact-contract.test.ts` | 단독으로도 10초 시간 초과가 난 적이 있다(레인 C 보고). 공통 게이트 밖이다 | 시간 한도나 fixture 크기를 조정한다 |
CI를 켜면(U-1) 이 테스트들이 무작위로 머지를 막는다. CI를 켜기 전에 P1 두 건을 처리한다.
## 4. 완료 기준은 만족하지만 실무 기준으로 빈틈이 있는 것
검증 단계(`README.md` 11절)에서 "충족, 단 기준 밖 빈틈"으로 적은 것들이다.
### 범위를 좁혀 닫은 것
| 우선 | ID | 빈틈 | 위치 |
|---|---|---|---|
| P2 | 06-05 | SW 업데이트 설치 실패, `observe`, `health()`는 연결하지 않았다. 레시피 문서에 "없다"고 적었다 | `src/adapters/service-worker/service-worker-page-controller.ts` `watchForUpdates`, `docs/architecture/optional-adapter-recipes.md` |
| P2 | 13-03 | 운영 단계는 승격 archive의 SHA만 대조한다. 서명 재검증(`verify:promotion --archived`)은 promotion job에서만 돈다. 실제 Gitea runner에서 돈 적이 없다(U-1) | `config/ci/gates.json` production_gate |
| P3 | 05-10 | 임의로 넓힌 id 정책은 생성 시점에 막지 못하고, BEGIN_PUT에서 `INVALID_INPUT`으로 거절한다 | `src/adapters/storage/opfs/opfs-policy.ts` `isWritableObjectId` |
| P3 | 01-06 | 하한은 skew를 반영하지 않는다(사용자 결정). 서버 수명 ≥ 최소 잔여 수명 + skew 조건을 문서로 둔다. 서버 시각 추정이나 상대 수명(`ttlMs`) 계약이 생기면 다시 본다 | `docs/architecture/presigned-transfer-and-image-cdn.md` 172행 부근 |
| P3 | 09-08 | 코드로 막지 않고 주석으로 닫았다(리뷰가 허용한 대안) | `src/features/local-draft-feature/domain/local-draft.ts` (`8784354`) |
| P3 | 12-12 | `noUnusedLocals`만 켰다. `noUnusedParameters`는 켜지 않았다 | `tsconfig.base.json` |
| P3 | 14-07 | 틀린 수치를 지우고 검사 범위를 적었다. `verify:documentation`이 검사하는 범위는 그대로 좁다 | `docs/operations/ci-quality-gates.md` |
| P3 | 07-07 | 리뷰가 선택으로 제안한 `no-deprecated` lint를 켜지 않았다 | `eslint.config.ts` |
| P3 | 09-07 | 기능 제거 검증이 lint, `check:i18n`, e2e를 건너뛴다 | `scripts/test-sample-removal.ts` |
### 테스트가 약한 것
| 우선 | ID | 빈틈 |
|---|---|---|
| P2 | 07-03 | V2 행이 하나도 없어도 V2/V3 일치 테스트가 통과한다. V3에만 있는 operation도 보지 않는다 |
| P3 | 01-11 | probe 재사용 테스트가 공개 이미지만 쓴다. capability가 필요한 비공개 이미지 경로는 테스트가 없다 |
| P3 | 05-03 | 손상된 budget 행만 테스트한다. 손상된 binding 행은 테스트하지 않는다 |
| P3 | 06-10 | Vite SW 설정이 `dist/config.json`을 읽도록 바뀐 부분에 단위 테스트가 없다(입력 해석 함수만 테스트) |
| P3 | 08-04 | en-US 브라우저 검사가 목록·폼 화면만 본다. 상세·상태 화면은 보지 않는다 |
| P3 | 08-07 | 요청 ID가 화면에 뜨는지만 보고, 같은 ID의 진단 이벤트는 확인하지 않는다 |
### 나중에 조용히 깨질 수 있는 것
| 우선 | ID | 빈틈 | 위치 |
|---|---|---|---|
| P2 | 06-08 | 이전 릴리스 fallback이 Vite 기본 폴더명 `assets/`를 하드코딩한다. `build.assetsDir`를 바꾸면 fallback이 조용히 꺼진다 | `src/adapters/service-worker/service-worker-static-assets.ts:66` `BUILD_ASSET_DIRECTORY` |
| P3 | 01-09 | 바이트 한도 검사는 조립 코드가 transport에 `maxPartCount`를 넘길 때만 동작한다 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` |
| P3 | 01-03 | 업로드 PUT에 idle 제한이 없다. 멈춘 5 MiB part는 크기 기반 마감(약 110초)에서야 끝난다. 리뷰가 허용한 선택지다 | `src/adapters/browser-transfer/resumable-upload/` |
| P3 | 03-03 | 서버가 correlation 헤더를 되돌려 주지 않으면 실패의 `requestId`가 비어 있다 | `src/adapters/http/client.ts` (requestId 해석), `src/adapters/http/http-execution-v3.ts` |
| P3 | 02-09 | 문서의 줄 번호 참조(`server-state-scope-runtime.ts:148`)가 이미 `:154`로 밀렸다. 이 문서는 `verify:documentation` 대상이 아니다 | `docs/architecture/client-cache-and-storage.md` |
## 5. 테스트 쪽 우회
| 우선 | 항목 | 내용 | 다음 행동 |
|---|---|---|---|
| P2 | `tests/browser-capabilities/resumable-upload.spec.ts:7` | `PAGE_ORIGIN`에 포트 4174가 박혀 있다. 설정 파일의 포트를 바꾸면 CORS로 실패한다. 이번 검증은 파일을 잠시 고쳐 돌린 뒤 되돌렸다 | Playwright `baseURL`에서 origin을 읽는다 |
| P3 | `tests/e2e/service-worker-update.spec.ts` | 빌드 B가 route chunk를 하나 바꾸도록 not-found 페이지에 export를 덧붙인다(`0289e0b`). 앱 동작은 정상이고, 09-02 뒤로 build ID가 route chunk에 들어가지 않아 생긴 조치다 | 두 빌드를 만드는 도우미에 "route chunk를 바꾸는 변경"을 공식 옵션으로 둔다 |
| P3 | fixture의 pnpm 설치 검사(F-4, F-12) | fixture가 pnpm을 부를 때 `pnpm_config_verify_deps_before_run=false`로 설치 검사를 끈다(`scripts/lib/fixture-node-modules.ts:41`). fixture가 공유 `node_modules`를 링크로 쓰는 구조는 그대로다 | fixture 전용 설치나 읽기 전용 링크를 검토한다 |
| P3 | 00-03의 이미 남은 임시 폴더 | 테스트는 이제 자기 임시 폴더를 지운다. 수정 전에 쌓인 약 2,400개(`repository-inventory-*`, `sw-assets-*` 등)는 `/tmp`에 남아 있다 | 호스트에서 한 번 지운다 |
## 6. 사용자 몫(변동 없음)
`SPEC.md` "범위 밖"과 `tasks/todo.md` 끝에 있다. U-1(Gitea Actions·runner·required check), U-2(수동 접근성 검토 10건), U-3(태그 `v0.2.0` push), U-4(작성자 외 기능 추가 기록, staging 공급망 smoke), U-5(백엔드 멱등 키 계약 확인), F-11(SBOM의 `scheduler@0.27.0` 분류와 의존성 기준선 재승인).
## 7. 권하는 처리 순서
1. 초기 JS 예산(1절 P1). 다음 기능 추가가 여기서 막힌다.
2. 부하 flaky 테스트 두 건(3절 P1). CI를 켜기(U-1) 전에 처리한다.
3. `check:remediation-ledger` 정리와 게이트 연결(1절).
4. 하드코딩 두 건: `resumable-upload.spec.ts`의 포트, 06-08의 `assets/`(4·5절 P2).
5. 나머지 P2, 그다음 P3.
@@ -0,0 +1,407 @@
# 템플릿 성숙도 리뷰 — 전체 종합 (2026-09-25)
> 검토일: 2026-09-25 · 기준: `main` / `4626b73` (워킹트리 깨끗함)
>
> 기준 문서: [`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`](../TEMPLATE-MATURITY-REVIEW-GUIDE.md)
>
> 범위: repo 전체를 14개 영역으로 나눠 영역별 리뷰 에이전트가 병렬로 읽었다. 이 문서는 그 결과를 오케스트레이터가 모은 것이다.
>
> 이 리뷰에서 코드는 수정하지 않았다.
## 1. 사용 결정 (36.5-1)
전체 판정: **조건부 사용 가능.** 샘플 기능 하나를 유지하거나 교체하며 조회 화면 위주로 시작하는 용도에 한한다. 아래 용도는 표의 항목을 고치기 전까지 보류한다.
| 용도 | 결정 | 막는 항목 |
|---|---|---|
| 샘플(reference-feature)을 두고 기능 1개로 시작, 조회 화면 위주 | 조건부 사용 가능 | 10-01(새 clone에서 `test:unit` 1건 실패) |
| 샘플을 지우고 자기 기능으로 시작 | 사용 보류 | 14-01, 14-02 |
| 기능을 2개 이상 설치 | 사용 보류 | 09-01, 09-05 |
| 쓰기(command) 샘플을 "결과 불명 처리" 예제로 복제 | 사용 보류 | 03-01, 03-02, 08-01 |
| opt-in realtime 연결을 운영에 조립 | 사용 보류 | 04-01 |
| opt-in OPFS 저장소를 제품에 조립 | 사용 보류 | 05-01, 05-02 |
| opt-in Web Push | 사용 보류 | 06-01, 06-02 |
| 이 repo의 CI를 머지·승격 차단 장치로 믿기 | 사용 보류 | 12-01, 12-02, 11-01 |
opt-in 런타임(realtime, OPFS, Web Push, browser-transfer)은 기본 구성에 조립돼 있지 않다(`AVAILABLE_NOT_COMPOSED`, SW는 기본 `null`). 그래서 이 런타임들의 결함은 **기능을 켜는 다운스트림에서만** 나타난다.
## 2. 차단 항목 (P1)
같은 결함이 두 영역에서 나온 것은 하나로 합쳤다. 심각도는 가이드 35.2절 기준이다.
**실제 사용자·데이터 피해로 이어지는 것**
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [03-01](03-adapters-http-state.md) (= 08-03) | High | 결과 불명(`MAYBE_APPLIED`) 쓰기에서 계약이 선언한 "같은 멱등 키로 재전송"(`IDEMPOTENCY_REPLAY`)을 실행하는 코드가 없다. 화면은 사용자에게 "적용됨/안 됨"을 추측하게 하고, "안 됨" 뒤 재제출은 새 키(`randomUUID()`)로 나간다. 서버가 실제로 적용했다면 중복 생성이 된다. | 코드 확인 |
| [04-01](04-adapters-realtime.md) | High | 오래 열린 realtime 연결이 첫 끊김 뒤 재연결하지 않고 끝난다. 재연결 예산 시작 시각이 run 시작에 고정되고, offline·예외 경로에서는 초기화되지 않는다. | 재현 |
| [05-01](05-adapters-storage-kernel.md) | High | OPFS reconcile이 진행 중인 put의 파일을 지운다. put은 성공으로 보고되고, 덮어쓰기면 이전 버전도 사라진다. | 재현(Node, fake OPFS) |
| [05-02](05-adapters-storage-kernel.md) | High | 첫 receipt 쓰기가 quota로 실패하면 빈 `receipt.json`이 남고, 그 authority의 reconcile·GC가 영구히 멈춘다. | 재현(Node, fake OPFS) |
| [06-01](06-adapters-service-worker-push.md) | Medium | 알림 클릭 핸들러가 `Object.hasOwn(notification, "data")`를 요구한다. 실제 브라우저의 `data`는 prototype getter라서 모든 클릭이 무시된다. | 에이전트가 3엔진에서 확인 |
| [08-01](08-presentation.md) + [03-02](03-adapters-http-state.md) | Medium | 쓰기의 401·403·429가 결과 불명으로 고정되고(03-02), 폼은 이를 "입력 확인 / 잠시 후 다시 시도" 하나로 보여 준다(08-01). 세션 만료 중 저장하면 재로그인 버튼이 없다. | 에이전트 재현 |
**템플릿 사용을 막는 것 (개발 시점에 드러남)**
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [09-01](09-app-core.md) | High | 기능을 하나 더 설치하면 중앙 조립 파일 3곳에서 tsc 오류 8건. `InstalledFeatureContract["routes"]`가 여러 기능이면 합집합이 되어 교집합 타입과 맞지 않는다. | 코드 확인 |
| [14-01](14-template-product-docs.md) | High | 샘플 제거 게이트(FE-GATE-020, merge 단계)가 main에서 실패한다. 2026-09-24 수정 라운드에서 들어온 테스트 6개가 샘플을 직접 참조한다. | `test:sample-removal` 재실행 → exit 1 |
| [14-02](14-template-product-docs.md) | Medium | CI 계약이 게이트 수·명령 수·해시로 템플릿 자신의 모양에 고정돼 있다. 기능을 실제로 추가·제거하면 `check:ci`가 실패한다. | 에이전트 실험 |
| [10-01](10-tests-fast-layers.md) | Medium | `tests/unit/removal-fixture.test.ts`는 gitignore된 `artifacts/release/*`가 있어야 통과한다. 새 clone과 CI 러너에서는 실패한다. | 코드 확인(증거 경로 15개 모두 gitignore 확장자) |
**검증 장치가 동작하지 않는 것**
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [12-01](12-guardrails-ci.md) | High | Gitea 저장소의 Actions가 꺼져 있다(`has_actions: false`). main HEAD의 커밋 상태는 0건이다. workflow의 push 트리거는 `develop`뿐인데 기본 브랜치는 `main`이다. 14-01 같은 회귀가 main에 들어온 경로가 여기다. | Gitea API 확인 |
| [12-02](12-guardrails-ci.md) (= 13-01) | High | 생성기가 matrix가 아닌 job에서 `gateIds[0]`만 실행한다(`scripts/generate-ci-workflow.ts:200`). `immutable_build`의 두 번째 게이트 FE-GATE-027(release-admission)이 workflow에 없다. `APP_PROFILE`이 비면 local/demo 인증 빌드가 승격 단계까지 간다. | 코드·workflow 확인 |
| [11-01](11-tests-browser-release-scale.md) (= 13-03) | Medium | 런북 drill 5개가 실제 복구를 하지 않고 일부 단언이 상수 `true`다. `dist/assets/*.js`를 전부 지워도 PASS한다. 이 결과로 `PROD_PROMOTION_READY`가 통과된다. | 에이전트 실험 |
## 3. 확인된 강점 (36.5-2)
- **레이어 경계가 실패 쪽으로 닫혀 있다.** 해석 안 되는 import, 파싱 실패, 지원하지 않는 규칙 모양은 모두 실패로 처리된다. worktree에 넣은 직접 import 위반 13건을 `check:architecture`가 모두 잡았다(12). 남은 우회는 전이 재수출과 `import.meta.glob`이다(12-03, 12-06).
- **신뢰할 수 없는 입력은 상한 → 정확한 키 → 스키마 순서로 검증한다.** 설정·매니페스트·realtime 이벤트·Cache Storage 응답 모두 같은 방식이다(04, 07, 02).
- **인증 세대 fence가 동작한다.** 로그아웃 뒤 늦게 온 HTTP 응답, realtime 이벤트, poll 응답이 현재 세션 상태를 바꾸지 않는다. 세대마다 QueryClient를 새로 만든다(03, 04, 08).
- **`AUTH_MODE=demo`는 브라우저 스키마, 프로필 생성, release admission 세 단계에서 staging/production 진입이 막힌다(09, 13).** 다만 세 번째 단계는 CI에서 실행되지 않는다(12-02).
- **재시도는 한 계층에만 있다.** 전체 마감 하나와 재시도 권한 하나가 대기를 관리한다. `Retry-After`는 상한과 jitter를 붙여 따른다(03, 01).
- **테스트가 flaky를 숨기지 않는다.** Vitest와 Playwright 설정 5개 모두 retry가 0이다. 순서를 섞어 3회 돌려도 순서 의존 실패가 없었다(10, 11).
- **직전 리뷰(2026-09-24)의 수정은 대부분 현재 코드에서 확인됐다.** 6.1·6.3·6.7·6.9는 전부, 6.2는 12개 중 10개, 6.4는 11개 중 10개가 해결됐다. 남은 부분은 02-07, 04-01, 05-03, 05-07, 05-10, 06-07, 08-11에 이어서 적었다.
## 4. 반복되는 원인
발견 137건은 다섯 가지 원인으로 모인다. 고칠 때 개별 항목보다 원인 단위로 보는 편이 싸다.
1. **선언한 동작을 코드가 하지 않는다.** 계약·문서·게이트 정의가 약속한 것이 실행 경로에 없다.
예: `IDEMPOTENCY_REPLAY`(03-01), `hiddenPolicy`·`killSwitchId`(04-04), FE-GATE-027(12-02), drill(11-01), SW kill switch 문서(06-03), 호스팅 헤더 자기 비교(13-05).
문서가 반대로 틀린 경우도 있다. 이미 구현된 것을 "미구현"으로 적었다(02-09, 03-08, 05-09).
2. **게이트는 있는데 돌지 않는다.** CI 비활성(12-01), 어떤 게이트도 실행하지 않는 테스트·스크립트(12-04), 빨간 샘플 제거 게이트(14-01), 새 clone에서만 드러나는 실패(10-01).
3. **테스트 대역과 테스트 설계가 실제 위험을 가린다.**
메모리 IndexedDB가 트랜잭션 순서와 blocked 동작을 숨긴다(05-08). KEYED fixture는 항상 `retryBudget: 0`이다(10-03).
변이를 넣어도 통과한 테스트: 01-04, 02-02, 02-08, 04-06, 06-04, 07-04, 07-05. axe가 실제 화면이 아니라 로딩·로그인 화면을 검사한다(08-05, 11-02).
4. **"기능 수 증가" 축이 실제로는 기능 1개 기준이다.**
2개째 설치 실패(09-01), `needs` 미검사(09-05), 중앙 정책 파일 8종 동시 수정(09-07), 해시 고정 CI 계약(14-02).
규모 증거는 stub 기능으로 만들었다(11-04). 생성기가 `feature-module.ts` 없는 폴더를 조용히 건너뛴다(14-03).
5. **실패 분류가 화면과 진단까지 이어지지 않는다.**
401·403·429가 결과 불명으로 고정된다(03-02, 08-01). 오류 종류 38개 중 22개에 문구가 없다(07-01).
`x-correlation-id`를 읽고 버린다(03-03). 부트 오류가 모두 `BOOT_CONFIG_FAILURE`가 된다(09-04). 실패 화면이 없는 식별자를 안내한다(08-07).
## 5. 미검증 (36.5-5)
| 범위 | 이유 | 확인 방법 |
|---|---|---|
| 실제 CI 러너에서의 workflow 실행, branch protection | Actions 비활성(12-01), 보호 설정 API는 401 | Actions를 켜고 main에 PR 하나를 올려 전 게이트 결과를 본다 |
| 05-01·05-02의 실제 브라우저 재현 | Node + fake OPFS·Web Locks로 재현함 | Playwright 2탭 spec으로 실제 OPFS·Web Locks·quota에서 재현 |
| 03-01의 실제 피해 범위 | 백엔드 멱등 키 보관·충돌 처리 계약이 repo 밖 | 백엔드 템플릿의 멱등 키 계약과 대조 |
| 깨끗한 환경의 install → dev → 첫 화면 | 에이전트가 같은 워킹트리를 공유해 실행하지 않음 | 새 clone에서 README 명령만으로 수행 |
| E2E·a11y·visual·storybook·capability 전체, `test:system`, `test:coverage` 전체 | 시간·호스트 조건 | CI 러너에서 전체 실행 |
| 제거 게이트 3개(optional-recipe, browser-file-storage, realtime) | `.tmp` 경로 충돌 우려로 병렬 실행 안 함 | 순차 실행 |
| 성능 측정(11-07), 규모 기준선(11-03) | 부하가 높은 호스트(loadavg 17~28)에서만 실행됨 | 조용한 고정 러너에서 5회 이상 반복 |
| 작성자 외 사용자의 기능 추가, 다운스트림 소비자 현황 | 기록 없음 | 25·26 관점은 구조적 준비만 평가함 |
## 6. 개선 순서 (36.5-6)
| 순서 | 대상 | 이유 | 최소 변경 | 완료 기준 |
|---|---|---|---|---|
| 1 | 12-01, 12-02 | 다른 모든 게이트가 머지를 막게 하는 전제다. 비용이 가장 작다. | Actions 활성화, push 트리거에 `main` 추가, 생성기가 `gateIds` 전부를 실행 | main PR에서 27개 게이트가 모두 실행되고, 하나를 일부러 깨면 머지가 막힌다 |
| 2 | 10-01, 14-01 | 새 clone과 샘플 제거라는 템플릿의 첫 두 경로를 복구한다. | 테스트가 로컬 생성물 대신 fixture를 쓴다. 샘플 참조 테스트 6개를 fixture로 옮긴다. | 새 worktree에서 `test:unit` 통과, `test:sample-removal` 통과 |
| 3 | 03-01, 03-02, 08-01 | 복제되는 쓰기 샘플이 중복 생성을 가르친다. | 결과 불명 시 같은 intent·키로 재전송하는 경로. 401·403·429는 분류기를 거친다. | 응답 유실 fake에서 재시도가 같은 키로 나간다. 세션 만료 저장이 재로그인을 안내한다. |
| 4 | 09-01, 09-05, 14-02, 14-03 | 기능 수 증가 축을 실제로 여는 작업이다. | 조립 타입을 교집합으로 계산. `needs`를 부트에서 검사. CI 계약의 개수·해시 고정을 풀거나 갱신 명령 제공. | local-draft를 두 번째 기능으로 설치해 `check:types`·`test:all`·`check:ci`가 통과한다 |
| 5 | 04-01, 05-01, 05-02, 06-01, 06-02 | opt-in 런타임을 조립하기 전에 고친다. | 각 영역 문서의 최소 개선 방향 | 각 문서의 완료 기준 |
| 6 | 11-01, 13-02, 13-04, 13-05 | 승격·롤백 판단의 증거를 실제 동작과 맞춘다. | drill이 승격 산출물로 복구를 수행 | 자산을 지운 빌드에서 drill이 FAIL한다 |
| 7 | 문서 불일치(02-09, 03-08, 05-09, 06-03, 14-07 등) | 운영 문서가 틀리면 복구 때 잘못된 행동을 한다. | 해당 절만 코드에 맞춘다 | 문서의 각 주장에 코드 위치가 붙는다 |
## 7. 재검토 조건 (36.5-7)
- CI를 켠 뒤 첫 전체 실행 결과가 나왔을 때
- 두 번째 기능을 설치하거나 샘플을 제거하는 다운스트림이 생겼을 때
- realtime, OPFS, Web Push, browser-transfer 중 하나를 기본 구성에 조립할 때
- TypeScript·pnpm·Vite 주 버전을 올릴 때. dependency-cruiser는 이미 TS 7에서 0개 모듈을 검사한다(12-05).
- 인증 방식(`AUTH_MODE`)이나 배포 방식(하위 경로 배포, 13-07)이 바뀔 때
---
## 8. 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `4626b73`, 미커밋 변경 없음(이 리뷰의 산출물 제외) |
| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + SW. SSR 없음 |
| 필수 요구·규모·운영 목표 | 기능 수 증가 축만 목표가 있다(`2026-09-23-extreme-scale-*`). 요청량·SLO 목표 없음 → 연결점만 평가 |
| 읽은 범위 | `src/` 전체, `tests/` 전체(unit은 표본), `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, `schemas/`, 루트 설정 |
| 수행한 테스트·실험 | 8.1절 게이트 12개. 각 영역에서 대상 테스트 실행, 분리 worktree에서 변이·결함 주입, scratchpad 재현 스크립트 |
| 확인하지 못한 범위 | 5절 |
| 이전 리뷰와 비교 | `2026-09-24-src-full-review.md`의 각 항목을 현재 코드에서 다시 확인했다. 이전 실행 결과는 증거로 쓰지 않았다. |
### 8.1 게이트 실행 결과 (오케스트레이터, `4626b73`)
| 게이트 | 결과 |
|---|---|
| `check:architecture` | 통과 |
| `check:types` (app, node, test, recipes, web-worker, service-worker) | 통과 |
| `lint` | 통과 |
| `test:unit` | 통과 — 140파일, 2077개 |
| `test:component` | 통과 — 31파일, 182개 |
| `test:integration` | 통과 — 12파일, 151개 |
| `test:contract` | 통과 — 3파일, 14개 |
| `test:runtime-schema` | 통과 — 3파일, 55개 |
| `verify:documentation` | `PASS_SCOPED` |
| `check:adapter-inventory` | 통과 |
| `check:ci` | 통과 |
| `test:sample-removal` | **실패** — typecheck, unit-integration, coverage, home-smoke, fixture-id-residue (14-01) |
주의: `test:unit` 통과는 이 워킹트리에 남은 `artifacts/release/*` 덕분이다. 새 clone에서는 1건이 실패한다(10-01).
### 8.2 오케스트레이터 재확인 (High 전부)
| ID | 방법 | 결과 |
|---|---|---|
| 03-01 | `browser-mutation-intent-factory.ts:37-40`(매번 `randomUUID()`), `application-query.ts:651-680`(사용자 선택만으로 정리), `IDEMPOTENCY_REPLAY` 사용처 grep | 확인 — 선언만 있고 실행 경로 없음 |
| 04-01 | `reconnect-coordinator.ts:347`, `:914-915`, `:943-944` 읽기 + 에이전트 실험 `exp-blip.ts` 재실행 | 확인 — offline 깜빡임 뒤 `attempts=1`로 종료 |
| 05-01, 05-02 | 에이전트 재현 스크립트 재실행 | 확인 — put 성공 뒤 `INTEGRITY_FAILED`, quota 뒤 reconcile 계속 `CORRUPT_DATA` |
| 09-01 | `installed-feature-contracts.ts:21-27` 타입 계산 읽기 | 확인 — 기능이 여럿이면 합집합 타입이 된다(에이전트 worktree 실험: tsc 8건) |
| 12-01 | Gitea API `GET /repos/...` → `has_actions: false`, `default_branch: main`. `commits/4626b73/status` → `total_count: 0` | 확인 |
| 12-02 | `generate-ci-workflow.ts:200`, `gates.json`의 `immutable_build.gateIds = [FE-GATE-015, FE-GATE-027]`, workflow에서 `FE-GATE-027` 0회 | 확인 |
| 14-01 | `corepack pnpm test:sample-removal` 재실행 | 확인 — exit 1, 94초 |
| 10-01 | `RELEASE_CANDIDATE_EVIDENCE_PATHS`의 `artifacts/` 경로 15개가 모두 gitignore 확장자 | 확인. 심각도는 High → Medium으로 조정(피해가 개발·CI 비용에 한정되고 수정이 작음) |
### 8.3 오케스트레이터 발견
#### 00-01 테스트 fixture가 공유 `node_modules`의 pnpm 상태 파일을 덮어쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 12, 20 |
| 근거 | `scripts/lib/fixture-node-modules.ts:19-30`는 `node_modules` 최상위 항목을 하나씩 심볼릭 링크한다. 파일 `.pnpm-workspace-state-v1.json`도 링크된다. `tests/integration/security-followup-archive.test.ts:24`, `:55`가 fixture 안에서 `corepack pnpm build:release-candidate`를 실행하면, pnpm이 이 링크를 통해 원본 상태 파일의 `projects`를 `/tmp/security-followup-producer-*`로 바꾼다. 리뷰 중 실제로 관찰했다. 다음 `corepack pnpm <script>`는 의존성 검증·설치 단계를 먼저 돈다("Done in 923ms"). |
| 발생 조건 | 통합 테스트를 돌린 뒤 같은 repo에서 pnpm 명령을 실행할 때. 테스트와 pnpm 명령이 동시에 돌 때 |
| 영향 | 매번 불필요한 설치 검증이 돈다. 동시 실행 중이면 공유 `node_modules`를 건드리는 설치가 겹칠 수 있다. 링커 주석이 막으려 한 사고(공유 의존성 삭제)와 같은 종류의 경로가 파일 하나에 남아 있다. |
| 심각도·우선순위 | Low · P2 — 지금까지 관찰된 효과는 자동 복구되는 재검증뿐이다 |
| 통제·증거 | M2(디렉터리는 막음, 파일은 안 막음) · E2 |
| 최소 개선 방향 | 최상위의 점(`.`)으로 시작하는 pnpm 상태 파일은 링크하지 않고 복사하거나 건너뛴다 |
| 완료 기준 | 통합 테스트 실행 전후로 원본 상태 파일의 `projects`가 바뀌지 않는다 |
| 검증 방법 | 테스트 전후 파일 해시 비교 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 8.4 영역 분할 (다음 리뷰에서 재사용)
| 번호 | 영역 | 경로 | 문서 |
|---|---|---|---|
| 01 | browser-transfer | `src/adapters/browser-transfer/` | [01](01-adapters-browser-transfer.md) |
| 02 | browser-files / cache / cross-context | `src/adapters/browser-files/`, `cache-storage/`, `cross-context-invalidation/` | [02](02-adapters-browser-files-cache.md) |
| 03 | HTTP·서버 상태·인증·진단 | `src/adapters/http/`, `browser-rpc/`, `query-cache/`, `auth/`, `diagnostics/`, `telemetry/` | [03](03-adapters-http-state.md) |
| 04 | realtime | `src/adapters/realtime/` | [04](04-adapters-realtime.md) |
| 05 | 저장소·adapter kernel | `src/adapters/storage/`, `platform/`, `browser-file-storage/` | [05](05-adapters-storage-kernel.md) |
| 06 | Service Worker / Web Push | `src/adapters/service-worker/`, `web-push/`, SW 빌드 설정 | [06](06-adapters-service-worker-push.md) |
| 07 | contracts | `src/contracts/`, `schemas/`, `config/contracts/` | [07](07-contracts.md) |
| 08 | presentation | `src/presentation/` | [08](08-presentation.md) |
| 09 | 애플리케이션 코어·기능·조립 | `src/application/`, `features/`, `bootstrap/`, `platform/`, `apps/`, `contexts/` | [09](09-app-core.md) |
| 10 | 테스트 — 빠른 계층 | `tests/unit`, `component`, `integration`, `contract`, `runtime-schema`, `features`, `platform`, `recipes`, `helpers`, `mocks` | [10](10-tests-fast-layers.md) |
| 11 | 테스트 — 브라우저·릴리스·규모 | `tests/e2e`, `browser-capabilities`, `visual`, `storybook`, `release`, `scale`, `system`, `architecture`, `scripts` | [11](11-tests-browser-release-scale.md) |
| 12 | 가드레일·CI | 검사 스크립트, `.gitea/`, `config/ci`, `config/architecture`, lint·tsconfig·depcruise 설정 | [12](12-guardrails-ci.md) |
| 13 | 빌드·릴리스·설정·공급망 | 빌드·릴리스·보안 스크립트, `vite.config.ts`, `config/release·hosting·runtime·security`, `package.json`, lockfile | [13](13-build-release-supply-chain.md) |
| 14 | 템플릿 제품성·문서·DX | `README.md`, `docs/`, `recipes/`, 제거 스크립트 | [14](14-template-product-docs.md) |
영역 에이전트에게 준 공통 지시(전제, 작업 규칙, 판정 규칙, 문서 형식)는 이 폴더의 각 문서 머리말과 루트 `CLAUDE.md`에 반영돼 있다.
## 9. 28개 관점 판정 (36.2)
영역별 판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
종합 판정은 영역 판정을 평균하지 않는다. 한 영역이라도 미충족이면 그 이유를 적는다(35.7절).
| 번호 | 관점 | 영역 01~14 | 종합 판정 | 근거와 잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | O P O O P P P P P - - - - - | 부분 충족 | 입력 경계 불변식은 강하다. put이 성공으로 보고되며 데이터를 잃는다(05-01). 도메인 규칙 함수를 아무도 호출하지 않는다(09-06). |
| 2 | 구조적 성숙도 | O O O O O O O O P - - P - P | 부분 충족 | 직접 위반은 M3~M4로 막힌다. 전이 재수출과 `import.meta.glob` 우회가 남아 있다(12-03, 12-06). |
| 3 | 변경 용이성 | P O P P P P P P X O O P P P | 미충족 | 기능 추가 시 조립 타입 실패(09-01), 중앙 정책 파일 8종(09-07), 해시 고정 CI 계약(14-02). 오류 종류를 추가해도 문구 누락을 잡지 못한다(07-01). |
| 4 | 인지 부하 | P × 14 | 부분 충족 | docs 약 61.8k줄에 색인이 없다(14-05). workflow 460줄을 6.4k줄로 생성·검증한다(12-10). 레이어 규칙 사본이 3벌이다(12-09). |
| 5 | 위험 가시성 | P P P P P P O P P P - P P - | 부분 충족 | recovery 값으로 호출자가 할 일을 정할 수 없다(01-05). SW가 API GET을 가로챈다(06-08). |
| 6 | 실패 성숙도 | P P P X P P P P P P P - O - | 부분 충족 | 결과 불명 쓰기(03-01), 재연결 중단(04-01), GC 영구 정지(05-02). 재시도 계층은 하나로 정리돼 있다. |
| 7 | 운영 성숙도 | P P P P P X P - P - X - P - | 부분 충족 | SW를 켜도 관측이 조립되지 않는다(06-05). drill이 복구를 하지 않는다(11-01). SLO는 템플릿 범위 밖이다. |
| 8 | 디버깅 가능성 | P P X P P P P X X P P P P P | 미충족 | V3가 correlation id를 버리고 `requestId`가 항상 비어 있다(03-03). 부트 오류를 삼킨다(09-04). 화면이 없는 식별자를 안내한다(08-07). |
| 9 | 유지보수 성숙도 | P × 14 | 부분 충족 | 코드와 어긋난 운영 문서가 여럿이다(02-09, 03-08, 05-09, 06-03, 14-07). 중복 사본(05-11, 08-11, 09-12). deprecated 표시가 없다(07-07). |
| 10 | 테스트 성숙도 | P × 14 | 부분 충족 | 고위험 변이 대부분을 잡고 retry 0이다. 새 clone 실패(10-01), 테스트 대역 한계(05-08), 변이 생존(10-03 외), 게이트 밖 테스트(12-04)가 남아 있다. |
| 11 | 데이터 성숙도 | P P O O P O O - P P - - - - | 부분 충족 | purge 불가·바이트 잔존(05-03, 05-04). 구버전 탭이 읽기도 못 한다(05-06). revision 재시작(09-08). |
| 12 | 동시성 성숙도 | O P P P X X - P P P O - - - | 미충족 (opt-in 런타임) | 기본 구성의 세대 fence는 충족한다. OPFS put·reconcile 경쟁(05-01)과 두 탭 push 구독 경쟁(06-02)이 남아 있다. |
| 13 | 확장성 | P O - ? ? P P - X - P - - - | 미충족 (기능 수 축) | 기능 2개부터 실패한다(09-01). 규모 증거는 stub 기능으로 만들었다(11-04). 기준선은 CPU가 같아야 통과한다(11-03). |
| 14 | 성능 성숙도 | P P O P ? P - P ? O P ? P - | 부분 충족 | 초기 JS가 예산의 96%다(13-14). lab 측정은 1회뿐이다(11-07). keepalive 한도(03-05). |
| 15 | 보안 성숙도 | O P O O P P O O P - - P P - | 부분 충족 | 자격증명 헤더 경계, XSS, demo 차단은 충족한다. 쓰지 않는 `VITE_*` 변수까지 번들에 들어간다(13-06). CSP를 브라우저에서 확인한 적이 없다(13-08). 계정 전환 시 push fence(06-06). |
| 16 | 의존성 성숙도 | O - - O - - P - - - O P P > | 부분 충족 | lockfile 무결성과 frozen install은 충족한다. depcruise가 0개 모듈을 검사한다(12-05). `.npmrc` 설정이 무시된다(13-09). |
| 17 | API / Contract | P × 12, - × 2 | 부분 충족 | 호환성 분류기가 strict reader와 어긋난다(07-02). V2/V3 이중 선언(07-03). 모르는 이벤트 타입(04-03). 422 필드 오류(03-04). |
| 18 | 배포 성숙도 | P P - P P P P O P - P - X - | 미충족 (릴리스 파이프라인) | SW 두 빌드 공존과 청크 복구는 충족한다. 산출물 권한 0600(13-02), provider 증거 2시간(13-04), 호스팅 헤더 자기 비교(13-05), FE-GATE-027 누락(12-02). |
| 19 | 설정 성숙도 | P O P O P P P O P P P - P - | 부분 충족 | strict 스키마는 충족한다. `VITE_PRODUCT_FEATURES` 불일치(09-02), override 오타 무시(09-09), 하위 경로 배포(13-07). |
| 20 | 개발자 경험 | P - - P - P P P X X P P P X | 미충족 | 새 clone 실패(10-01), 샘플 제거 실패(14-01). 기능 추가 안내가 실제 생성기 규칙과 다르다(14-03). 파일 하나를 실행하는 방법이 없다(10-05). |
| 21 | Guardrail 성숙도 | P ? P O O P P P P P P X P P | 미충족 | 로컬 검사는 M3다. 그러나 CI가 돌지 않아(12-01) 머지 시점의 강제력이 없다. FE-GATE-027 누락(12-02), 게이트 밖 테스트(12-04). |
| 22 | 추상화 성숙도 | P P P P P P P O X P - P - - | 부분 충족 | kernel은 결론을 한 곳에서 낸다. 기능 조립이 `needs`를 검사하지 않는다(09-05). 레지스트리 필드 일부를 아무도 읽지 않는다(07-04). |
| 23 | 일관성 | P P P P P P P P P P O P P P | 부분 충족 | 재시도 의미가 3벌이다(03-06). 상태 화면이 3벌이다(08-11). 샘플 문구가 하드코딩돼 있다(08-04). |
| 24 | 네이밍 / 의미 | P P P P P P X P P P X P P P | 부분 충족 | `inspect()`가 항상 `verified:true`를 보고한다(02-05). "native throw 없음" 약속과 실제 동작이 다르다(07-06). "CI tiers"는 CI에 없다(11-03). |
| 25 | 조직 확장성 | - - O - ? - ? - P - - ? - P | 부분 충족 (구조만) | 팀이 하나라 실제 검증은 미확인이다. 중앙 정책 파일 8종이 공동 수정 지점이다(09-07). |
| 26 | Ownership | P - P - ? ? P ? - P P P P P | 부분 충족 | 예외에 담당자·재검토 시점이 없다(12-07). 템플릿 버전과 CHANGELOG가 없다(14-04). |
| 27 | 삭제 가능성 | ? ? ? ? P P > - P - - - P X | 미충족 | 샘플 제거 게이트가 빨간 상태다(14-01). CI 계약이 제거를 막는다(14-02). "독립 제거 가능" 주석은 사실과 다르다(05-11). |
| 28 | 회복 가능성 | P P X P X X - P P - X - X - | 미충족 | GC 영구 정지(05-02), purge 불가(05-03), SW 끄는 경로가 페이지 부팅에 의존한다(06-03). drill이 복구를 하지 않는다(11-01). 이전 release 재검증 불가(13-04). |
집계(적용 28개 기준): 충족 0 · 부분 충족 19 · 미충족 9(3, 8, 12, 13, 18, 20, 21, 27, 28) · 미검증 0 · 적용 제외 0.
미충족 9개 중 12, 13, 18은 판정 칸에 적은 범위(opt-in 런타임, 기능 수 축, 릴리스 파이프라인)에서만 미충족이다.
## 10. 발견 색인
영역 문서의 발견 142건이다. 같은 결함 4쌍과 포함 관계 1건을 합치면 137건이고, 8.3절 오케스트레이터 발견 1건을 더해 **138건**이다.
중복을 뺀 심각도 분포: Critical 0 · High 8 · Medium 57 · Low 73(00-01 포함).
심각도 조정은 두 건이다. 13-01은 12-02와 합치면서 High로 올렸고, 10-01은 Medium으로 내렸다. 각 항목의 상세(근거·발생 조건·영향·완료 기준·검증 방법)는 링크한 영역 문서에 있다.
| ID | 심각도 | 우선 | 성격 | 관점 | 제목 | 비고 |
|---|---|---|---|---|---|---|
| [03-01](03-adapters-http-state.md) | High | P1 | 확인된 결함 | 6, 12, 17, 24, 28, 5 | 결과 불명인 KEYED 쓰기: 선언된 "같은 키 재전송" 복구가 없고, 사용자 추측 뒤 새 멱등 키로 다시 보낸다 | 08-03과 합침 · 해결 · dfb1b9e · 백엔드 멱등 키 계약은 U-5 |
| [04-01](04-adapters-realtime.md) | High | P1 | 확인된 결함 | 6, 12, 18, 28, 10, 5 | 오래 열린 연결은 첫 끊김(offline 깜빡임, 조용한 WS의 서버 재시작) 뒤 재연결하지 않고 끝난다 | 해결 · bcad7b0 |
| [05-01](05-adapters-storage-kernel.md) | High | P1 | 확인된 결함 | 12, 1, 6, 11, 28 | OPFS reconcile이 진행 중인 put의 파일을 지우고, put은 성공으로 보고된다 | 해결 · 8fc816e |
| [05-02](05-adapters-storage-kernel.md) | High | P1 | 확인된 결함 | 6, 28, 11, 14 | 첫 receipt 쓰기가 실패하면 빈 `receipt.json`이 남아 authority 전체의 reconcile과 GC가 영구히 멈춘다 | 해결 · 47cf040 |
| [09-01](09-app-core.md) | High | P1 | 확인된 결함 | 3, 13, 20, 21, 22, 25, 10 | 기능을 2개 이상 설치하면 중앙 조립 파일이 타입 검사에 실패한다 | 해결 · 30cf71b, bcf8752, 2a1591a |
| [12-01](12-guardrails-ci.md) | High | P1 | 확인된 결함 | 21, 10, 26, 9 | 이 repo에서 CI가 실행되지 않아 게이트가 머지를 막지 않는다 | 해결(repo 쪽) · b8cc5d4 · Actions·runner·required check는 U-1 |
| [12-02](12-guardrails-ci.md) | High | P1 | 확인된 결함 | 21, 18, 15, 17 | 생성된 workflow가 FE-GATE-027(release-admission)을 실행하지 않는다 | 13-01과 합침 · 해결 · 239b22a |
| [13-01](13-build-release-supply-chain.md) | High | P1 | 확인된 결함 | 18, 19, 21, 26 (+30.1) | 운영 환경 승인 게이트(FE-GATE-027)가 CI에서 실행되지 않는다 | = 12-02 (같은 결함, High로 통일) · 해결 · 239b22a |
| [14-01](14-template-product-docs.md) | High | P1 | 확인된 결함 | 27, 10, 21, 20, 2, 30.5, 30.8 | 샘플 제거 게이트(FE-GATE-020)가 main에서 실패한다 — 플랫폼 테스트 6개가 샘플을 직접 참조 | 원인 연결: 12-01 · 해결 · 991da88 · PR 상태 기록은 U-1 |
| [06-01](06-adapters-service-worker-push.md) | Medium | P1 | 확인된 결함 | 1, 10, 15, 22 | 알림 클릭 핸들러가 실제 브라우저의 `Notification`을 거부해 모든 클릭이 무시됨 | 해결 · 8522cb5 |
| [08-01](08-presentation.md) | Medium | P1 | 확인된 결함 | 6, 5, 10, 23 | 폼 저장 실패가 세션 만료·권한 없음·요청 과다까지 "입력 확인 / 잠시 후 다시 시도" 하나로 합쳐짐 | 03-02와 함께 수정 · 해결 · 9894a70, 67117cc |
| [10-01](10-tests-fast-layers.md) | Medium | P1 | 확인된 결함 | 10, 20, 21, 30.8 | 깨끗한 체크아웃에서 `test:unit`이 실패한다 — 테스트가 gitignore된 로컬 생성물에 의존 | 오케스트레이터 조정: High → Medium (피해가 개발·CI 비용에 한정, 수정 비용 작음) · 해결 · 23336f2 |
| [11-01](11-tests-browser-release-scale.md) | Medium | P1 | 확인된 결함 | 28, 7, 10, 21, 24 | 런북 drill이 복구를 하지 않고, 일부 단언이 상수 `true`라서 앱이 깨진 빌드에서도 PASS한다 | 13-03과 합침 · 해결 · 7f889a6 |
| [14-02](14-template-product-docs.md) | Medium | P1 | 확인된 결함 | 30.3, 30.7, 27, 20, 21, 3, 25 | CI 계약이 템플릿 자신의 모양(개수·해시)에 고정돼 있어, 실제 제거·추가를 하면 `check:ci`가 실패한다 | 해결 · 0114b1e, ad0e83c |
| [01-01](01-adapters-browser-transfer.md) | Medium | P2 | 확인된 결함 | 6, 5, 17, 24 | object store PUT의 401/403과 실행기의 만료 판정이 capability 재발급 없이 `upload()` 전체 실패로 끝난다 | 해결 · 648fe4e |
| [01-02](01-adapters-browser-transfer.md) | Medium | P2 | 구조적 위험 | 6, 5, 17, 28, 11 | 완료됐거나 완료 여부를 모르는 업로드가 일반 실패로 보고되고, resourceId를 되찾는 길이 "같은 파일로 `upload()` 재실행"뿐이다 | 해결 · 7b2cefb |
| [01-03](01-adapters-browser-transfer.md) | Medium | P2 | 구조적 위험 | 6, 14, 19 | 전송 시간 제한이 바이트 수나 진행과 무관한 고정 값이다 | 해결 · 5a6665a |
| [01-04](01-adapters-browser-transfer.md) | Medium | P2 | 확인된 결함 | 10, 6, 21 | 결과 불명 재시도의 핵심 규칙(같은 idempotency key 재사용)을 어떤 테스트도 고정하지 않는다 | 해결 · 5cc1d00 |
| [01-05](01-adapters-browser-transfer.md) | Medium | P2 | 구조적 위험 | 5, 17, 24, 8 | 실패의 `recovery` 값이 호출자가 할 수 있는 행동과 1:1로 이어지지 않는다 | 해결 · 426b6b8 |
| [02-01](02-adapters-browser-files-cache.md) | Medium | P2 | 확인된 결함 | 6, 12, 14, 23, 5 | preview를 만든 직후 abort하면 object URL lease가 반환되고 다시 회수되지 않는다 | 해결 · c9be8d6 |
| [03-02](03-adapters-http-state.md) | Medium | P2 | 확인된 결함 | 6, 15, 17, 5 | 명령의 401/403/429가 패키지 분류기를 거치지 않고 `MAYBE_APPLIED`로 고정돼, 세션 만료 저장이 "지원 문의"로 끝난다 | 08-01과 함께 수정 · 해결 · 2afee67, 9894a70 |
| [03-03](03-adapters-http-state.md) | Medium | P2 | 확인된 결함 | 8, 7 | 권장 경로(V3)에서 문의 식별자 → 서버 기록 연결이 끊겼다 | 해결 · c5da3cf, 20b6878, e7f376a, f0a6495 |
| [03-04](03-adapters-http-state.md) | Medium | P2 | 확인된 결함 | 17, 3, 22 | V3로는 서버 422 필드 오류가 폼까지 가지 못한다 | 해결 · 479acd5 |
| [04-02](04-adapters-realtime.md) | Medium | P2 | 확인된 결함 | 6, 5, 22, 23, 10 | SSE 429/503의 Retry-After가 실패 결과에 실리지 않아, 기본 배선에서는 서버가 요구한 시각보다 먼저 재연결한다 | 해결 · 02d3fdf |
| [04-03](04-adapters-realtime.md) | Medium | P2 | 확인된 결함 | 17, 18, 8, 10 | 등록되지 않은 이벤트 타입이 오면 연결은 MALFORMED_EVENT로 끝나고, stream freshness는 CURRENT로 남는다 | 해결 · 7e37660 |
| [05-03](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 11, 15, 28, 27 | IndexedDB LOGOUT/ACCOUNT_DELETION purge는 open이 성공해야만 돌고, dataset을 지우는 경로가 없다 | 해결 · 3e37fbf |
| [05-04](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 11, 15, 24, 27 | OPFS LOGOUT/ACCOUNT_DELETION purge 뒤에도 파일 바이트가 디스크에 남는다 | 해결 · 6ab564f |
| [05-05](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 6, 11, 28, 8 | 만료 정리(RETENTION_SWEEP, receipt prune)가 손상 행 하나에 영구히 멈추고, receipt가 쌓여 결국 모든 쓰기가 실패한다 | 해결 · b87ab5e |
| [05-06](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 11, 18, 5, 17, 28 | 이전 버전 탭이 새 스키마(future schema)를 만나면 `MIGRATION_FAILED/READ_ONLY`를 받지만, 실제로는 읽기도 못 한다 | 해결 · 7f45afa |
| [05-07](05-adapters-storage-kernel.md) | Medium | P2 | 구조적 위험 | 6, 12, 14, 22, 5 | source가 멈춘 put 하나가 origin 전역 OPFS mutation lock을 무기한 쥔다 | 해결 · 2b24f6d |
| [05-08](05-adapters-storage-kernel.md) | Medium | P2 | 구조적 위험 | 10, 12 | 테스트 대역이 여러 탭·트랜잭션 수명·quota 동작을 숨겨, 05-01·05-02 같은 결함을 잡지 못한다 | 해결 · 9cae587 |
| [06-02](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 12, 6, 10, 15 | 두 탭에서 enable/reconcile이 겹치면 공유 native 구독과 서버 연결이 지워지고 한 탭은 `PUSH_READY`를 보고함 | 해결 · e6c683e |
| [06-03](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 28, 18, 9, 5, 26 | 잘못된 SW를 끄는 경로가 페이지 부팅에 의존하고, 운영 문서는 코드에 없는 kill switch를 안내함 | 해결 · 9f2305a |
| [06-04](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 10, 28, 21 | 런타임 kill switch(`SERVICE_WORKER: DISABLED` → unregister) 분기가 어떤 테스트로도 검증되지 않음 | 해결 · cebfa67 |
| [06-05](06-adapters-service-worker-push.md) | Medium | P2 | 구조적 위험 | 7, 8, 18, 20, 19 | SW를 켜도 관측·차단기·업데이트 알림이 조립되지 않아 설치 실패와 활성화 결과가 보이지 않음 | 해결 · cd47516, 5168550 |
| [06-06](06-adapters-service-worker-push.md) | Medium | P2 | 구조적 위험 | 15, 17, 11 | 로그아웃 없이 계정이 바뀌면 새 계정이 push fence를 넘길 방법이 없음 | 해결 · 996a959 |
| [07-01](07-contracts.md) | Medium | P2 | 확인된 결함 | 3, 8, 17, 20, 21, 23 | 오류 종류 22개에 화면 문구가 없어 "요청한 문구를 표시할 수 없습니다"가 표시된다 | 08-02와 합침 · 해결 · bb70820, 2b2cabb |
| [07-02](07-contracts.md) | Medium | P2 | 구조적 위험 | 17, 24, 21, 10, 18, 19 | 호환성 규칙·분류기·FE-GATE-014가 "필드 추가는 안전"이라 하지만 실제 reader 여러 곳이 모르는 필드를 거부한다 | 해결 · 17d617a, 340acc5 |
| [07-03](07-contracts.md) | Medium | P2 | 구조적 위험 | 3, 9, 17, 20, 21, 22, 23 | 참조 기능이 같은 HTTP 오퍼레이션을 V2·V3 두 벌로 선언하고, 거버넌스는 실행되지 않는 V2 벌만 본다 | 해결 · c936063 |
| [08-02](08-presentation.md) | Medium | P2 | 확인된 결함 | 6, 3, 21, 23, 24 | 오류 종류 38개 중 22개에 문구가 없어 "요청한 문구를 표시할 수 없습니다."가 오류 제목으로 나옴 | = 07-01 (같은 결함) · 해결 · bb70820 |
| [08-03](08-presentation.md) | Medium | P2 | 확인된 결함 | 6, 12, 5, 17 | 결과 불명 저장을 확인 수단 없이 사용자가 판정하게 하고, "안 됨" 뒤 재제출은 새 멱등 키로 나감 | = 03-01 (같은 결함) · 해결 · dfb1b9e |
| [08-04](08-presentation.md) | Medium | P2 | 확인된 결함 | 23, 21, 20 | 샘플 화면 문구가 catalog 없이 코드에 박혀 있어 언어 전환이 적용되지 않음 | 해결 · 411619c, 9960a61, 8613832 |
| [08-05](08-presentation.md) | Medium | P2 | 확인된 결함 | 10, 21 | axe 스캔이 보호 라우트 4개에서 실제 화면 대신 로그인 안내 화면만 검사함 | 11-02와 같은 테스트 파일 · 해결 · f17572a, 02b90b2, 6b58951 |
| [08-06](08-presentation.md) | Medium | P2 | 미검증 | 10, 21, 26 | 수동 접근성 검토 기록 10건이 모두 pending이라 merge 게이트 FE-GATE-009가 통과할 수 없음 | 해결 · 7298275 · 서명 검토는 U-2 |
| [08-07](08-presentation.md) | Medium | P2 | 확인된 결함 | 8, 24, 28 | 실패 화면이 문의 식별자를 보여 주지 않고, 라우트 렌더 실패 화면에는 다음 행동이 없음 | 해결 · b7fc7e5 |
| [09-02](09-app-core.md) | Medium | P2 | 확인된 결함 | 19, 17, 18, 21, 24, 6 | `VITE_PRODUCT_FEATURES`가 번들·빌드 스크립트·라우터에서 다르게 적용된다 | 해결 · a8111f7, 2a1591a |
| [09-03](09-app-core.md) | Medium | P2 | 확인된 결함 | 6, 8, 7 | 모듈 평가 단계에서 실패하면 부트 셸이 "불러오는 중"으로 멈춘다 | 해결 · 9c8a5f4, eb5264c |
| [09-04](09-app-core.md) | Medium | P2 | 확인된 결함 | 8, 6, 7, 24 | 설정·매니페스트 외 부트 오류가 `BOOT_CONFIG_FAILURE`로 표시되고 원인이 버려진다 | 해결 · aca9490, 69e40f1 |
| [09-05](09-app-core.md) | Medium | P2 | 확인된 결함 | 2, 3, 5, 22, 20, 30.5 | IndexedDB capability가 부트스트랩에 없고, `needs`가 런타임에서 검사되지 않는다 | 해결 · bc7c46b |
| [09-06](09-app-core.md) | Medium | P2 | 확인된 결함 | 1, 10, 24, 30.5 | local-draft 샘플의 도메인 규칙이 쓰기 경로에서 적용되지 않는다 | 해결 · 790f62e |
| [09-07](09-app-core.md) | Medium | P2 | 구조적 위험 | 3, 27, 4, 20, 25, 21 | 기능 추가·제거가 중앙 정책 파일 여러 곳을 요구하고, 제거 검증은 샘플 전용·일부 게이트만 돈다 | 해결 · ad0e83c, 606c191 |
| [10-02](10-tests-fast-layers.md) | Medium | P2 | 확인된 결함 | 10, 8, 14, 30.5 | 샘플 기능 페이지 테스트가 부하에서 흔들리고, 실패 메시지가 시간 초과를 가린다 | 해결 · e8b1163, 4805e56 |
| [10-03](10-tests-fast-layers.md) | Medium | P2 | 확인된 결함 | 10, 6, 17, 21 | V3 HTTP 실행기가 계약의 재시도 의미를 쓰는지 검증하는 테스트가 없다 | 해결 · e62b020 |
| [11-02](11-tests-browser-release-scale.md) | Medium | P2 | 확인된 결함 | 10, 21, 9 (가이드 32.3 접근성) | 라우트별 axe 검사와 상태 화면 visual 검사가 lazy route의 로딩 화면을 검사한다 | 08-05와 같은 테스트 파일 · 해결 · f17572a, 02b90b2 |
| [11-03](11-tests-browser-release-scale.md) | Medium | P2 | 확인된 결함 | 13, 14, 21, 24 | 규모 회귀 게이트는 기준선을 만든 CPU에서만 통과할 수 있고, "CI tier"라는 설명과 달리 어느 CI job에도 없다 | 해결 · 45ee231, 840de45 |
| [11-04](11-tests-browser-release-scale.md) | Medium | P2 | 미검증 | 13, 14 (가이드 13절 "과장 방지", 30.6) | 규모 증거는 이름만 다른 stub 기능으로 만든 것이라, 선언된 앱당 상한(20 × 200)의 실제 비용은 측정되지 않았다 | 해결 · a96fd24, 9cb46eb, 70f4ff8 |
| [11-07](11-tests-browser-release-scale.md) | Medium | P2 | 구조적 위험 | 14, 10, 24 | lab 성능 게이트가 1회 측정이고, 상호작용 지표에 Playwright 왕복 시간이 들어가며, 측정 대상 서버를 확인하지 않는다 | 해결 · 8e5c51e |
| [12-03](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 21, 2, 10 | 경계 규칙은 직접 간선만 본다 — 경계 밖 모듈을 거친 재수출이 통과한다 | 해결 · f8b6a36 |
| [12-04](12-guardrails-ci.md) | Medium | P2 | 구조적 위험 | 10, 21, 26 | CI에 연결되지 않은 테스트와 검사가 있고, 그런 누락을 찾는 장치가 없다 | 해결 · 840de45, 15a946f |
| [12-10](12-guardrails-ci.md) | Medium | P2 | 구조적 위험 | 21, 9, 4, 22, 3, 30.6 | 가드레일·CI 코드의 유지 비용이 검출력에 비해 크다 | 해결 · 7f2a160, 239b22a |
| [13-02](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 18, 28 (+30.1) | 공개 dist 파일 3개가 mode 0600으로 만들어져 웹 서버가 읽지 못할 수 있다 | 해결 · 1a1cfe6 |
| [13-03](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 28, 10, 18, 21, 24 | 운영 단계 runbook·롤백 게이트가 이름과 다른 것을 검사한다 | = 11-01 (같은 결함) · 해결 · 7f889a6, fa3de53 · 실제 CI 실행 확인은 U-1 |
| [13-04](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 28, 18, 16 | 이전 release를 재검증할 수단이 없어 문서의 롤백 절차를 그대로 실행할 수 없다 | 해결 · 839205c |
| [13-05](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 18, 15, 21, 28 | hosting 헤더 게이트가 배포 전에 돌고, 배포·전환·자산 보존 단계는 repo에 없다 | 해결 · a263d8c |
| [13-06](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 15, 16, 14 | 쓰지 않는 `VITE_*` 빌드 변수까지 공개 번들에 들어가고, secret scan은 이를 잡지 못한다 | 해결 · 2ec59ad |
| [14-03](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 20, 4, 9, 3, 25, 30.5, 30.6 | 새 기능 추가 안내가 현재 설치 방식(생성기 + feature/context 선언)과 다르다 | 09-07과 겹침 · 해결(repo 쪽) · ad0e83c, 606c191 · 작성자 외 기능 추가 기록은 U-4 |
| [14-04](14-template-product-docs.md) | Medium | P2 | 구조적 위험 | 30.4, 26, 16, 9 | 템플릿 버전 식별과 다운스트림 패치 전파 경로가 없다 | 해결 · 1cb09e4, 736e855, 91de7cf, 66bc083 |
| [14-05](14-template-product-docs.md) | Medium | P2 | 구조적 위험 | 9, 4, 20, 30.6 | 문서 규모가 크고 현재 계약·목표 설계·작업 이력이 한 트리에 섞여 있다 | 해결 · 6ddb08e, 70f4ff8 |
| [03-05](03-adapters-http-state.md) | Medium | P3 | 구조적 위험 | 7, 14 | 텔레메트리 배치 크기가 브라우저 keepalive 한도(64KiB)와 맞지 않는다 | 해결 · e14c613 |
| [01-06](01-adapters-browser-transfer.md) | Low | P2 | 구조적 위험 | 6, 17, 19, 23 | 서버가 준 만료 시각을 기기 시계로 여유 없이 비교한다 | 결정 종료 · c0b7ff1 (상한만 skew 반영, 하한은 서버 수명 조건으로 문서화. 사용자 결정 2026-09-28) |
| [02-02](02-adapters-browser-files-cache.md) | Low | P2 | 구조적 위험 | 10, 11, 15 | Cache Storage의 익명 요청 규칙을 테스트가 고정하지 않는다 | 해결 · 9a56741 |
| [04-06](04-adapters-realtime.md) | Low | P2 | 확인된 결함 | 10, 6 | SSE idle timeout(heartbeat 감시)에 테스트가 없다 | 해결 · 905189e |
| [05-09](05-adapters-storage-kernel.md) | Low | P2 | 확인된 결함 | 28, 9, 17 | OPFS recovery runbook이 현재 코드와 다르다 | 해결 · 4d8cead |
| [08-08](08-presentation.md) | Low | P2 | 확인된 결함 | 24, 10 | 뒤로 가기에서 스크롤을 복원하지 않고 해시 대상도 무시함(문서 계약과 다름) | 해결 · dbe6b76 |
| [09-08](09-app-core.md) | Low | P2 | 구조적 위험 | 12, 11, 1 | local-draft가 삭제 후 재생성 시 revision 재사용(ABA)을 막지 않아 다른 탭의 오래된 저장이 새 초안을 덮는다 | 해결 · 8784354 |
| [09-09](09-app-core.md) | Low | P2 | 개선 제안 | 19, 7, 8 | `FEATURE_OVERRIDES` 키 오타가 진단 없이 무시되어 킬스위치가 조용히 작동하지 않는다 | 해결 · b685b61 |
| [11-05](11-tests-browser-release-scale.md) | Low | P2 | 구조적 위험 | 18, 10, 24 | release 테스트의 "구 자산 도달성"은 테스트 fixture 자신을 검사하고, 기본 구성의 구 탭 청크 복구는 실제 브라우저에서 확인되지 않는다 | 해결 · 34c9788 |
| [11-06](11-tests-browser-release-scale.md) | Low | P2 | 확인된 결함 | 10, 6 (가이드 30.5 샘플 대표성) | 핵심 사용자 흐름 E2E가 "보호 화면이 열린다"까지만 확인한다 | 해결 · 48b8495, 9cb46eb |
| [13-07](13-build-release-supply-chain.md) | Low | P2 | 확인된 결함 | 19, 18, 23 | 하위 경로 배포에서 config·manifest URL이 base를 따르지 않아 부트가 실패한다 | 해결 · e215c84 |
| [13-08](13-build-release-supply-chain.md) | Low | P2 | 구조적 위험 | 15, 10 (+30.2) | 선언된 CSP가 브라우저에서 한 번도 적용되지 않고, opt-in 기능을 막는다 | 해결 · 8a0e5f5, b25c599, 9dc95ca |
| [01-07](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 12, 14, 22 | 발급됐지만 쓰지 못한 upload capability를 vault에서 회수하지 않는다 | 해결 · b52ca8d, 0f35c98 |
| [01-08](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 18, 3, 11 | 재개할 때 저장된 session을 현재 정책으로 다시 검사해, 정책을 낮춘 배포 뒤 기존 업로드가 막힌다 | 해결 · 8f65eab |
| [01-09](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 19, 13, 14 | part 수 상한과 control-plane 요청·응답 바이트 상한을 서로 검사하지 않는다 | 해결 · 1eee2ac |
| [01-10](01-adapters-browser-transfer.md) | Low | P3 | 확인된 결함 | 7, 8 | `UPLOAD_PART` 관측이 두 계층에서 같은 이름으로 기록되고, 문서가 말한 retry·part bucket은 없다 | 해결 · b3981f9 |
| [01-11](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 14, 5 | 이미지 `resolve()`가 `PRIMARY_REQUIRED` preset이면 호출마다 원본 후보 전체를 내려받아 decode하며, 동시 실행 상한과 결과 재사용이 없다 | 해결 · dde0d2b |
| [02-03](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 11, 15, 5 | browser-file runtime이 인증 scope와 연결되지 않고, 연결 방법도 문서에 없다 | 해결 · c8e4794 |
| [02-04](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 6, 14, 22 | object URL 한도를 preview와 download가 공유하고, 30초 대기 중 초과하면 재시도 불가로 보고한다 | 해결 · 0b41cb3 |
| [02-05](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 24, 5, 8 | `inspect()`가 marker만 읽고 candidate를 `verified: true`로 보고한다 | 해결 · 55c0bf5 |
| [02-06](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 8, 6 | 다운로드 취소와 browser handoff 성공이 관측 기록에서 똑같이 보인다 | 해결 · d76653b |
| [02-07](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 14 | 캐시 조회 한 번의 비용이 여전히 크다 | 해결 · 2cbf500 |
| [02-08](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 10, 15, 12 | 보안·자원 규칙 5개가 다른 조건에 가려 테스트에서 검출되지 않는다 | 해결 · 98977df |
| [02-09](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 9, 17 | cross-tab 무효화 설계 문서가 현재 구현보다 뒤처져 있다 | 해결 · 4358ced |
| [03-06](03-adapters-http-state.md) | Low | P3 | 개선 제안 | 23, 6, 19, 4 | "KEYED" 재시도 규칙과 `REQUEST_TIMEOUT_MS`의 의미가 전송마다 다르다 | 해결 · 84effd0 |
| [03-07](03-adapters-http-state.md) | Low | P3 | 확인된 결함 | 7 | 요청 전에 거절된 미인증(전송 0회)이 `api.request.failed`로 집계된다 | 해결 · f329cc8 |
| [03-08](03-adapters-http-state.md) | Low | P3 | 확인된 결함 | 9, 26, 7 | HTTP 복구 runbook이 현재 코드보다 오래됐다 | 해결 · 0e54e83 |
| [04-04](04-adapters-realtime.md) | Low | P3 | 구조적 위험 | 12, 15, 5, 14, 20 | hidden 탭 닫기·로그아웃 시 닫기·kill switch를 강제하는 코드가 없고, `isCurrent`는 루프 경계에서만 확인한다 | 해결 · 1fe9bfd, 01baaba |
| [04-05](04-adapters-realtime.md) | Low | P3 | 구조적 위험 | 14, 6 | SSE reader가 256KB를 넘는 chunk를 한 번에 주면, 이벤트 크기와 상관없이 EVENT_TOO_LARGE로 끝난다 | 해결 · 2138896 |
| [04-07](04-adapters-realtime.md) | Low | P3 | 개선 제안 | 7, 8 | 재연결·폴링·SSE 연결에 관측 지점이 없어 설계 14.1의 connect/poll 진단 이벤트를 낼 곳이 없다 | 해결 · 03991aa, 01baaba |
| [04-08](04-adapters-realtime.md) | Low | P3 | 확인된 결함 | 9, 5, 24 | VD-28과 설계 5.3이 현재 재연결 규칙과 다르다 | 해결 · 01baaba |
| [05-10](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 9, 19, 23 | prepared-object 검증 통합이 덜 끝났다: objectId 정규식 하드코딩, `stableJson` 2벌 | 해결 · 3767ed7, 33bf559 |
| [05-11](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 9, 27, 2, 23 | IndexedDB 예외 매핑 표가 두 벌이고, OPFS가 IndexedDB 폴더에 묶여 "각자 독립 제거 가능" 주장이 사실과 다르다 | 해결 · 6cc6526, 3aacbd9 |
| [05-12](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 9, 22 | binding 검증이 kernel 밖에서 트랜잭션 상태 기계를 손으로 다시 구현한다 | 해결 · e505a65 |
| [05-13](05-adapters-storage-kernel.md) | Low | P3 | 구조적 위험 | 12, 22 | IndexedDB 연결의 versionchange 핸들러가 비동기 admission이 끝난 뒤에야 설치된다 | 해결 · 9733ea8 |
| [05-14](05-adapters-storage-kernel.md) | Low | P3 | 구조적 위험 | 12, 11 | OPFS GC의 유예 기간을 "참조가 끊긴 시각"이 아니라 "쓴 시각"으로 센다 | 해결 · e872bfa |
| [06-07](06-adapters-service-worker-push.md) | Low | P3 | 확인된 결함 | 12, 6, 24, 18 | 응답하지 않는 창 하나가 활성화를 막고, 그 시간 초과가 "dirty 탭"으로 보고됨 | 해결 · f2e14af |
| [06-08](06-adapters-service-worker-push.md) | Low | P3 | 확인된 결함 | 5, 14, 24 | 해시 파일명 판별이 same-origin API·다운로드 GET까지 가로챔 | 해결 · 8c17eab |
| [06-09](06-adapters-service-worker-push.md) | Low | P3 | 확인된 결함 | 19, 15, 3 | 거절된 알림 클릭의 fallback이 router base path를 무시하고 origin 루트를 엶 | 해결 · dd7a446 |
| [06-10](06-adapters-service-worker-push.md) | Low | P3 | 구조적 위험 | 19, 9 | SW 빌드가 배포 프로필이 아니라 로컬 `public/config.json`에서 release manifest URL을 읽음 | 해결 · cefb0b2 |
| [07-04](07-contracts.md) | Low | P3 | 개선 제안 | 22, 24, 7, 10 | ERROR_REGISTRY의 severity·redaction·telemetryEvent와 AppFailure.retryable은 읽는 곳이 없는데 정책처럼 관리된다 | 해결 · aff5f43 |
| [07-05](07-contracts.md) | Low | P3 | 확인된 결함 | 21, 10 | diagnostics negative fixture는 위반 3개 중 1개만 고정해서 나머지 2개가 풀려도 게이트가 통과한다 | 해결 · 710436b |
| [07-06](07-contracts.md) | Low | P3 | 확인된 결함 | 1, 24, 6 | `invokeValidator`의 "native throw로 새지 않는다" 약속에 구멍이 있다 | 해결 · 0bcee34 |
| [07-07](07-contracts.md) | Low | P3 | 개선 제안 | 17, 9, 26, 27 | 호환 별칭·V1 reader에 폐기 표시와 제거 조건이 코드에 없다 | 해결 · 9e616d3, 340acc5 |
| [08-09](08-presentation.md) | Low | P3 | 확인된 결함 | 1, 23 | 목록 조회가 실패해도 결과 수 영역(role=status)이 "결과 확인 중"으로 남음 | 해결 · 9d61eac |
| [08-10](08-presentation.md) | Low | P3 | 확인된 결함 | 23 | 언어를 바꿔도 이미 표시된 폼 오류 문구는 이전 언어로 남음 | 해결 · ee9b095 |
| [08-11](08-presentation.md) | Low | P3 | 구조적 위험 | 23, 9, 22 | 같은 인증 필요·권한 없음·없음 상태를 그리는 화면이 세 벌 있음 | 해결 · a5fff8f |
| [08-12](08-presentation.md) | Low | P3 | 확인된 결함 | 24 | Pagination 페이지 링크가 Ctrl/Cmd/Shift 클릭까지 막아 새 탭 열기가 안 됨 | 해결 · cef6744 |
| [08-13](08-presentation.md) | Low | P3 | 확인된 결함 | 17, 1 | 상세 경로 `:resourceId`가 정적 경로 `new`·`status`와 겹쳐 그 ID의 항목을 열 수 없음 | 해결 · d7b81c6, 6b58951 |
| [09-10](09-app-core.md) | Low | P3 | 개선 제안 | 6, 28, 32.2 | 부트 실패 화면에 다시 시도 동작이 없고 설정·매니페스트는 한 번만 요청한다 | 해결 · fc8142b |
| [09-11](09-app-core.md) | Low | P3 | 확인된 결함 | 10, 21 | `tests/features/` 최상위 테스트 3개가 어떤 스크립트·CI 게이트에서도 실행되지 않는다 | 12-04에 포함 · 해결 · 840de45 |
| [09-12](09-app-core.md) | Low | P3 | 확인된 결함 | 9, 10, 23 | local-draft의 테스트 fixture 복사본이 src와 갈라졌고, 경계 테스트는 복사본을 검사한다 | 해결 · 070d4db |
| [10-04](10-tests-fast-layers.md) | Low | P3 | 구조적 위험 | 10, 21, 9 | 커버리지 게이트가 문서의 위험별 목표가 아니라 17개 모듈의 현재값 하한이고, live 재시도 모듈이 빠져 있다 | 해결 · d68e25a, 4805e56 |
| [10-05](10-tests-fast-layers.md) | Low | P3 | 확인된 결함 | 20, 19 | 테스트 파일 하나를 돌리는 방법이 문서에 없고, 문서에 적힌 명령은 새 체크아웃에서 실패한다 | 해결 · 72e7ae1 |
| [10-06](10-tests-fast-layers.md) | Low | P3 | 개선 제안 | 10, 8, 23 | fake timer 복원이 일부 테스트 본문 끝에만 있어, 단언이 실패하면 같은 파일의 다음 테스트로 새어 실패가 연쇄된다 | 해결 · d090054 |
| [10-07](10-tests-fast-layers.md) | Low | P3 | 확인된 결함 | 9, 20, 24 | 테스트 문서가 현재 구성과 다르다 | 해결 · 84f2ab9, 4805e56 |
| [11-08](11-tests-browser-release-scale.md) | Low | P3 | 구조적 위험 | 21, 10, 26 | Playwright에 `test.only` 차단과 quarantine 만료 검사가 없다 | 해결 · 7870c48 |
| [12-05](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 16, 21, 24 | dependency-cruiser가 0개 모듈을 검사하고 통과한다 | 해결 · 39b9fbf |
| [12-06](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 21, 2 | `import.meta.glob`은 import로 인식되지 않는다 | 해결 · 7bbe482 |
| [12-07](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 21, 26, 5 | 경계 예외가 적힌 이유보다 넓고, 담당·재검토 시점이 없다 | 해결 · e070efa, 4add908 |
| [12-08](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 21, 23 | design-system 검사기가 presentation 내부의 deep import를 보지 못한다 | 해결 · 7f2a160 |
| [12-09](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 23, 9, 4 | 레이어 규칙 사본이 세 개이고 하나는 아무도 읽지 않는다 | 해결 · 3e1c421 |
| [12-11](12-guardrails-ci.md) | Low | P3 | 개선 제안 | 20, 8 | 검사 실패 메시지에 이유와 해결 방향이 없다 | 해결 · b0f7944 |
| [12-12](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 16, 9, 21 | unused 변수·import를 아무 도구도 잡지 않는다 | 해결 · 49413af |
| [13-09](13-build-release-supply-chain.md) | Low | P3 | 확인된 결함 | 16, 19, 20 | `.npmrc`의 `engine-strict`, `save-exact`가 pnpm 11에서 무시된다 | 해결 · a5dc851 |
| [13-10](13-build-release-supply-chain.md) | Low | P3 | 구조적 위험 | 17, 19, 24 | config 호환성 게이트는 분류기 자기 검사이고, strict reader에서 "additive" 변경이 깨진다 | 해결 · 17d617a |
| [13-11](13-build-release-supply-chain.md) | Low | P3 | 개선 제안 | 7, 8, 18 | API 실패 telemetry에 release·build 식별값이 없어 배포와 이상을 연결하기 어렵다 | 해결 · 43e47f4 |
| [13-12](13-build-release-supply-chain.md) | Low | P3 | 개선 제안 | 16, 24 | SBOM·provenance가 증명하는 범위가 문서에 정리되어 있지 않다 | 해결 · 331ec84 |
| [13-13](13-build-release-supply-chain.md) | Low | P3 | 미검증 | 16, 4, 9 (+30.6) | 공급망·승격 체계의 도입 비용이 크고 실제 환경에서 한 번도 돈 적이 없다 | 해결 · 987ee1c · staging smoke는 U-4 |
| [13-14](13-build-release-supply-chain.md) | Low | P3 | 개선 제안 | 14 | 초기 JS 예산의 96%를 템플릿 기본 화면이 쓰고, lab 측정은 1회다 | 해결 · a55a158 |
| [13-15](13-build-release-supply-chain.md) | Low | P3 | 확인된 결함 | 19, 20, 9, 23 | 런타임 설정의 정본 위치·배포 변수 설명이 문서와 다르고 사본이 두 벌이다 | 해결 · 2ba880c, 5810461, edf44a2, 063375e |
| [14-06](14-template-product-docs.md) | Low | P3 | 개선 제안 | 30.2, 20, 23 | 최상위 지원 범위 표(기본/선택/실험/비지원)가 없다 | 해결 · 2cb3838 |
| [14-07](14-template-product-docs.md) | Low | P3 | 확인된 결함 | 9, 24, 21, 19 | 문서의 수치·목록이 코드와 어긋나 있고, DOCUMENTATION_READY 게이트는 이를 검사하지 않는다 | 해결 · 81d2b84 |
| [14-08](14-template-product-docs.md) | Low | P3 | 확인된 결함 | 8, 27, 10 | 제거 스크립트의 실패 보고가 원인을 가린다 | 해결 · 96391dc |
## 11. 반영 결과 (2026-09-28)
발견 142건(중복을 합치면 138건)을 브랜치 `fix/maturity-review-2026-09-25`에서 고쳤다. 레인이 끝난 뒤 영역 4개로 나눠 발견마다 완료 기준을 코드·테스트와 다시 대조했다(레인 보고와 커밋 메시지는 근거로 쓰지 않음). 이 대조에서 부분 충족 9건과 회귀 1건이 나와 레인 R·S·T와 `6b58951`로 보완했다.
- 보완한 항목: 01-07(`0f35c98`), 05-10(`33bf559`), 06-05(`5168550`), 08-05·08-13(`6b58951`), 11-04·00-02·14-05(`70f4ff8`, 11-04 테스트가 리뷰 문서를 읽어 제거 검증 3개가 실패하던 회귀), 12-04(`15a946f`), 13-03(`fa3de53`).
- 통합 뒤 Playwright 전체(e2e, browser-capabilities, visual, storybook)를 chromium·firefox에서 돌려 회귀 2건을 더 찾아 고쳤다. 09-02 뒤로 두 빌드의 route chunk가 같아져 SW 업데이트 spec이 준비 단계에서 실패했다(`0289e0b`, `4626b73`부터 bisect). 08-08·08-13의 의도된 화면 변경으로 visual 기준 이미지 2개가 어긋났다(`2dc1b3a`).
- 결정으로 종료: 01-06. 하한까지 skew를 완화하면 시계가 정확한 기기에서도 서버에서 이미 만료된 capability를 받아들인다. 상한만 `maxClockSkewMs`를 반영하고, 하한은 "서버 수명 ≥ 최소 잔여 수명 + skew" 조건을 `docs/architecture/presigned-transfer-and-image-cdn.md`에 둔다.
- 브라우저 검증 범위: e2e 전체와 browser-capabilities를 chromium·firefox·webkit에서 돌렸다(visual·storybook은 설정상 chromium만). 처음에는 호스트에 WebKit 시스템 라이브러리(libevent, libavif)가 없었고, 설치한 뒤(2026-09-28) WebKit에서만 난 실패 1건을 `b1a36ab`로 고쳤다. 구 탭 청크 복구 spec이 WebKit의 import 실패 문구를 허용하지 않았다.
- 로컬에서 확인할 수 없는 것: 13-03의 production 단계 archive 다운로드와 12-01의 CI 실행은 Gitea runner에서 확인해야 한다(U-1).
- 남긴 판단과 후속 작업: 완료 기준은 만족했지만 실무 기준으로 미룬 것(예산 인상, 게이트 제외, 부하 flaky, 기준 밖 빈틈, 테스트 우회)은 [`FOLLOW-UP.md`](FOLLOW-UP.md)에 우선순위와 함께 적었다.
- 사용자 몫: U-1~U-5, F-11(SBOM의 `scheduler@0.27.0` 분류, 의존성 기준선 재승인).
- 리뷰 범위 밖에서 확인한 것: `check:remediation-ledger`는 `4626b73`에서도 실패한다(2026-09-18 리팩터링 뒤 테스트 마커와 예산 문구가 원장과 어긋남). `config/ci/ungated-scripts.json`에 이유를 적어 두었다.
@@ -0,0 +1,337 @@
# 01 browser-transfer 성숙도 리뷰 (2026-09-29)
> 기준: `main` / `af3d8e6` (태그 `v0.2.0` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 체크리스트: `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능**. 기본 production 구성에는 조립돼 있지 않다(`AVAILABLE_NOT_COMPOSED`). 조립하는 다운스트림은 01-01의 recovery 번역을 그대로 믿으면 안 된다.
## 요약
- 지난 라운드 발견 11건(01-01~01-11)의 수정이 현재 코드에 있다. 변형 13종 중 12종을 테스트가 잡았다. 지난번에 살아남던 멱등 키 변형(M1·M6·M7)도 이제 잡힌다.
- **새로 확인한 결함(Medium).** `upload()` 실패의 recovery 번역(`toUploadAction`)은 recovery 어휘만 보고 code·단계는 보지 않는다. 그래서 6개 경로에서 포트 표와 다른 행동을 가리킨다. 파일이 바뀌거나 IndexedDB가 잠깐 실패하면 `retryable:true`인데 `recovery:NONE`이 나온다(01-01).
- **01-02 수정의 빈틈(Low).** complete가 반영된 뒤 로컬 정리 실패를 성공으로 보는 규칙이 `completeUpload`에만 있다. 재호출(재조정) 경로에서는 resourceId를 버린다(01-02).
- **01-03 수정의 연결 문제(Low).** 느린 업링크 설정이 runtime 정책과 presigned 실행기 두 곳에 있다. 문서대로 정책만 낮추면 실행기 deadline이 PUT을 끊는다(01-03).
- **제거 경로(Low).** file-transfer 어댑터만 지우면 게이트 3개가 실패한다. 제품 2곳은 이 영역을 조립하지 않으면서 이번 동기화로 37파일 +4,632/−2,085줄을 받았다(01-04).
- 레시피 번들은 55,623 / 55,700 gzip bytes다. 여유는 77바이트다(FOLLOW-UP 유효).
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 영역·경로 | `src/adapters/browser-transfer/` 27파일 약 12.6k줄(`resumable-upload/` 13, `presigned/` 6, `image-cdn/` 7, 배럴 1), `src/application/ports/browser-transfer/` 약 0.8k줄, file-transfer 레시피(`config/recipes/frontend-capability-recipes.json:155-201`), 단위 테스트 15파일, Playwright spec 3개 |
| 커밋·상태 | `main` `af3d8e6`. 코드는 이 커밋과 같다. 주 워킹트리에서 쓴 파일은 이 문서 하나다 |
| 전제 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. 이 영역은 조립되지 않은 선택 레시피다. 배럴(`src/adapters/browser-transfer/index.ts`)이 공개 경계다 |
| 지난 리뷰 이후 변경 | `4626b73..af3d8e6`에서 src 11파일 +474/−77, 단위 테스트 12파일 +1,782/−44 |
| 읽은 코드 | resumable-upload 13파일 중 runtime·정책·검증·checkpoint store·lock·byte source·part 실행기·control plane·fetch 전송의 실패 경로 전부. presigned는 실행기(PUT·download deadline, vault 반환)·`http-common.ts` 상태표. image-cdn은 01-11 변경(probe 동시 상한·재사용). kernel `platform/abortable-operation.ts` 기본 타이머, `browser-file-storage/result.ts` 예외표 2개 |
| 읽은 문서(주장으로만) | `docs/architecture/presigned-transfer-and-image-cdn.md` 3.2·4.3·4.4·7절, `server-file-capability-infrastructure.md` 15.3, CHANGELOG 0.2.0, 지난 리뷰 `01-*.md`·README 11절·FOLLOW-UP |
| 실행한 명령 | 분리 worktree(`git worktree add --detach .../01/wt af3d8e6`, 메인 `node_modules` 링크)에서: 영역 단위 테스트 15파일 → **15 files / 249 tests 통과**. `check-optional-recipes.ts`(source) → file-transfer 55,623 / 55,700. Playwright `playwright.capabilities.config.ts`의 영역 spec 3개 × chromium·firefox·webkit → **9 통과** |
| worktree 안 pnpm 실행 | 실험 X4의 게이트 5개와 Playwright webServer는 worktree에서 `corepack pnpm`으로 돌렸다(`pnpm_config_verify_deps_before_run=false`). 첫 시도는 pnpm 의존성 검사에서 설치 전에 멈췄다. 이후 오케스트레이터 경고(링크된 `node_modules`를 pnpm이 지울 수 있음)를 받았다. 메인 `node_modules`는 그대로다(`.modules.yaml`·`.pnpm` 수정 시각 16:26, worktree 생성 전). 번들 제거 드릴처럼 fixture에 pnpm을 설치하는 스크립트는 돌리지 않았다 |
| 실험 | X1 `upload()` recovery 경로 6개(①~⑥)와 `abort()` 실패 1개(⑦), X2 재조정 중 삭제 실패, X3 deadline 두 겹(실제 provider·vault·실행기), X4 file-transfer 어댑터만 제거 후 게이트 5개, X5 변형 13종(M1, M6~M17. 번호는 지난 라운드와 맞췄다). 실험 파일은 scratchpad `review-2026-09-29/01/`(`zz-area01-experiments.test.ts`, `mutate.py`, 로그)에 있다. worktree는 끝난 뒤 지웠다 |
| 제품 repo 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`을 `git grep`·`git show`로만 읽었다 |
| 확인하지 못한 범위 | 두 탭 실제 경쟁, 실제 object store·BFF, 느린 실제 네트워크, 번들 단위 제거 드릴(`test:browser-file-storage-removal`), `check:types`·`lint` 전체(오케스트레이터 PASS) |
| 지난 리뷰와 비교 | 지난 결과는 증거로 쓰지 않았다. 01-01~01-11은 현재 코드와 변형 실험으로 다시 확인했다(5절, 변형표) |
**변형 실험 X5** (코드 한 곳을 일부러 틀리게 바꾸고, 영역 테스트 12파일 215개가 실패하는지 본다)
| ID | 바꾼 것 | 결과 |
|---|---|---|
| M1 | 모든 멱등 키에 난수 추가(`upload-byte-source.ts:297-302`) | 2 실패 — 검출 |
| M6 | COMPLETE 키를 시도마다 바꿈(`resumable-upload-runtime.ts:1121`) | 3 실패 — 검출 |
| M7 | CREATE 키를 시도마다 바꿈(`:672`) | 1 실패 — 검출 |
| M8 | PART 키를 시도 번호로 바꿈(`:983`) | 4 실패 — 검출 |
| M9 | ABORT 키를 시도마다 바꿈(`:1219`) | **215 통과 — 검출 못 함** |
| M10 | `REISSUE_CAPABILITY`·`RETRY`도 `NONE`으로 번역(`:1720-1724`) | 3 실패 — 검출 |
| M11 | `toUploadAction` 무력화 | 3 실패 — 검출 |
| M12 | complete 뒤 정리 실패를 다시 실패로(`:1153`) | 1 실패 — 검출 |
| M13 | PUT의 `REISSUE_CAPABILITY` 재시도 제거(`:1060-1062`) | 3 실패 — 검출 |
| M14 | PUT deadline에서 바이트 몫 제거(`:1035-1039`) | 2 실패 — 검출 |
| M15 | abort `ALREADY_COMPLETED`에서 resourceId 조회 생략(`:1260`) | 2 실패 — 검출 |
| M16 | session 상한에서 `maxClockSkewMs` 무시(`upload-response-validation.ts:242`) | 1 실패 — 검출 |
| M17 | `ABORT_PENDING`을 `RECONCILE`로 보고(`resumable-upload-runtime.ts:409-415`) | 1 실패 — 검출 |
## 1. 대표 흐름 (체크리스트 2절)
### 1.1 정상 흐름 — 새 파일 업로드
```text
upload(request) resumable-upload-runtime.ts:169
→ 입력 snapshot·검증 → Web Lock(uploadKey) :179, :205 / upload-mutation-lock.ts:40-56
→ 파일 전체 읽기 + part별 SHA-256 manifest :363-374
→ request binding 해시 → checkpoint 읽기(없음) :375-396
→ createSession(CREATE 키) → checkpoint CAS rev1 :643-710 / indexeddb-checkpoint-store.ts:345-386
→ getStatus로 재조정 :546-641
→ part마다: 발급(PART 키) → 발급값 검증 :970-1014 / upload-response-validation.ts:38-76
→ presigned PUT(vault resolve·claim·consume, presigned-transfer-executor.ts:312-396
credentials omit, redirect error)
→ receipt 검증 → checkpoint CAS :1041-1054, :731-773
→ 재조정 → complete(COMPLETE 키) → 응답 검증 :1082-1148
→ checkpoint 삭제 → { QUARANTINED, resourceId, replayed:false } :1149-1156
```
- 정책: 파일·part 상한(`:355-362`), in-flight 바이트 상한(`runtime-policy.ts:104-107`), 재시도 상한·jitter·`Retry-After` 상한(`:1455-1504`).
- 상태 변화: IndexedDB checkpoint 행 생성 → part마다 revision 증가 → 삭제.
- 외부 I/O: BFF control plane(create·status·issue·complete), object store PUT.
- 실패: 재시도는 runtime 한 계층만 한다. 실패는 `toUploadAction`을 거쳐 5개 recovery로 나간다(`:1714-1726`).
- 결과: 이 경로는 실제 브라우저 3종에서 통과했다(`tests/browser-capabilities/resumable-upload.spec.ts:42`).
### 1.2 피해가 큰 흐름 — complete 응답 유실 (29.2)
```text
complete(COMPLETE 키) ── 서버 반영, 응답 유실(timeout)
→ 같은 키로 maxRetries번 재시도 → 모두 실패 :1110-1125
← { UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME } checkpoint(ACTIVE, 모든 part 수락) 남음
경로 A: 같은 파일로 upload() → 파일 전체 재해시 → getStatus = QUARANTINED
→ checkpoint 삭제 → { QUARANTINED, resourceId, replayed:true } :583-600
(삭제가 실패하면 → { UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE }, resourceId 없음 — 01-02)
경로 B: abort() → ABORT_PENDING 기록 → 서버 abort = ALREADY_COMPLETED
→ getStatus로 resourceId 읽기 → checkpoint 삭제
→ { ALREADY_COMPLETED, resourceId } :1185-1278, :1281-1316
경로 C: complete 성공 + 로컬 삭제 실패 → 성공 반환, 행은 다음 호출이 정리 :1149-1156
```
- 멱등성: CREATE·PART·COMPLETE·ABORT 키는 binding·session·part에서만 만든다(`upload-byte-source.ts:289-326`). 시도·호출이 바뀌어도 같다. 변형 M1·M6·M7·M8이 검출된다.
- 서버 계약: complete 진행 중이면 `429 + Retry-After`, `409` 금지, status는 확정 전까지 `ACTIVE`(`resumable-upload.ts:222-230`). 서버 구현과의 대조는 미검증이다.
- 결과: 경로 A·B·C 모두 테스트가 있다(`tests/unit/resumable-upload-runtime-recovery.test.ts` 01-02 절). 경로 A의 삭제 실패 분기만 테스트와 수정이 없다(실험 X2).
### 1.3 변경·삭제 흐름 — file-transfer 어댑터만 제거 (실험 X4)
```text
제품이 file-transfer를 쓰지 않음
→ 제거 드릴 범위 확인: 번들 전체만 지운다 scripts/test-browser-file-storage-runtime-removal.ts:24-37
→ browser-files가 ports/browser-transfer 타입을 씀 src/adapters/browser-files/download-delivery-adapter.ts:16
→ port 폴더는 남기고 src/adapters/browser-transfer/ + 단위 테스트 15파일만 삭제
→ 게이트 실행
check:architecture PASS
check:browser-file-storage-boundaries PASS
check:types FAIL Playwright spec 2개의 import 5건
check:adapter-inventory FAIL 이름으로 고정된 필수 소비자 4파일(check-adapter-inventory.ts:139-144)
check:optional-recipes FAIL ZodError "must cover every reference runtime"(release-artifacts.ts:1147)
```
- 결과: 레시피 하나만 떼는 경로는 문서에도 드릴에도 없다. 실패 메시지 하나(ZodError)는 원인을 가리키지 않는다(01-04).
- 정책 변경 흐름(정책을 낮춘 빌드가 이전 checkpoint를 이어 감)은 테스트가 있다(`resumable-upload-runtime-recovery.test.ts:951-999`).
## 2. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이 영역에서 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 근거와 잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | O | 목표 M3 / 확인 M3 | E2 | checkpoint는 정확한 key 목록만 받는다(`checkpoint-schema.ts:29-143`). 상태는 `ACTIVE → ABORT_PENDING → 삭제`뿐이고 revision CAS로만 바뀐다(`indexeddb-checkpoint-store.ts:345-417`). 변형 M12·M15·M17을 잡았다 |
| 2 | 구조적 성숙도 | O | M4 | E1, 게이트 | 배럴 4개가 공개 경계다. 다른 adapter import는 kernel(`platform/`, `browser-file-storage/result.ts`)뿐이다. `check:architecture` PASS(오케스트레이터) |
| 3 | 변경 용이성 | O | M3 | E2 | 정책을 낮춘 빌드가 이전 checkpoint를 이어 간다(테스트 `recovery.test.ts:951-999`, 변형 없음). 01-08 해소 |
| 4 | 인지 부하 | P | M1~M2 | E1 | recovery 표가 포트에 생겼다(`resumable-upload.ts:104-121`). 하지만 조립에 factory 6개가 필요하고, 같은 뜻의 값(timeout·min rate·`maxRetryAfterMs`)을 여러 곳에 넣는다. 조립 예는 Playwright spec뿐이다(`resumable-upload.spec.ts:266-390`) |
| **5** | 위험 가시성 | P | 목표 M2 / 확인 M1~M2 | E2 | 29.4 문장을 코드로 채울 수 있다(1.1·1.2). complete 진행 중 계약도 포트에 있다(`resumable-upload.ts:222-230`). 남은 것: 포트 표가 6개 경로에서 틀림(01-01), 느린 링크 설정 문서가 한쪽만 적음(01-03), `abort()` 실패 뜻 없음(01-05) |
| **6** | 실패 성숙도 | P | 목표 M3 / 확인 M3(주요 경로) | E2(X1~X3, X5) | 재시도는 한 계층, 상한·jitter·`Retry-After` 상한이 있다. PUT 403·만료는 새 capability로 다시 보낸다(M13 검출). 결과 불명 complete는 재호출·abort로 조정된다(M12·M15 검출). 남은 것: 01-01, 01-02 |
| 7 | 운영 성숙도 | O | M2(연결점) | E2 | part마다 `UPLOAD_PART` 1건 + 시도 수 bucket(`resumable-upload-runtime.ts:833-839`, 테스트 `recovery.test.ts:1001-1029`). 수집·알림은 다운스트림 몫 |
| 8 | 디버깅 가능성 | P | M2 | E2 | code·operation·recovery가 닫힌 분류다. `ABORT_PENDING`은 operation `UPLOAD_ABORT`로 구분된다. 하지만 `NONE`+`retryable:true`처럼 서로 맞지 않는 조합이 나온다(01-01) |
| 9 | 유지보수 성숙도 | P | M2 | E1 | 갈라진 사본이 남았다. `isAbortSignal`은 두 벌(`checkpoint-schema.ts:195` duck typing, `http-common.ts:209` brand 검사). `MEDIA_TYPE`도 두 벌(`checkpoint-schema.ts:26` 길이 63 제한, `presigned-capability-http-provider.ts:47` 제한 없음). `RECOVERIES` 집합(`resumable-upload-runtime.ts:118-132`)은 공유 union을 손으로 복사했다. 새 값이 union에만 추가되면 provider 실패가 `UNAVAILABLE/RESUME`으로 바뀐다. 지금 도달하는 피해는 없다 |
| 10 | 테스트 성숙도 | P | 목표 M3 / 확인 M3(대부분) | E2(249 통과, 변형 12/13 검출), E3(브라우저 9 통과) | 지난 01-04 해소. 남은 것: ABORT 키 재사용은 고정되지 않았다(M9 생존). 01-05 표 테스트는 7경로만 보고 `retryable`을 단언하지 않는다(01-01). 브라우저 spec은 정상 경로만 본다 |
| 11 | 데이터 성숙도 | P | M2~M4 | E2 | 계정 partition, 저장 key allowlist, partition 삭제의 `PENDING/UNKNOWN` 보고는 그대로다. 버려진 checkpoint 정리(inventory·TTL)는 문서가 미구현으로 선언했다(`presigned-transfer-and-image-cdn.md` 4.4). 재조정 경로에서 resourceId 연결을 잃는다(01-02) |
| **12** | 동시성 성숙도 | O | 목표 M3 / 확인 M3 | E2, E3(브라우저 Web Locks·IndexedDB, 단일 탭) | 같은 uploadKey는 Web Lock으로 직렬화하고 대기는 signal로 끊긴다(`upload-mutation-lock.ts:40-56`). checkpoint는 revision CAS(`indexeddb-checkpoint-store.ts:345-386`). receipt 저장은 한 줄로 직렬화(`resumable-upload-runtime.ts:731-773`). worker 하나가 실패하면 형제를 끊는다(`:781-796`). `abort()`는 lock 전에 로컬·다른 탭 작업을 끊는다(`:255-258`). `dispose()`는 provider의 실제 작업까지 기다린다(`:1413-1424`). 두 탭 실제 경쟁은 미검증 |
| 13 | 확장성 | P | M2 | E1 | part 수와 전송 바이트 상한 검사는 조립 코드가 `maxPartCount`를 넘길 때만 돈다(`fetch-json-transport.ts:157-166`). 유일한 조립 예도 넘기지 않는다(`resumable-upload.spec.ts:329-341`) |
| **14** | 성능 성숙도 | P | 목표 M3 / 확인 M3 | E2(X3), 측정 | PUT deadline이 바이트에 비례한다(`resumable-upload-runtime.ts:1033-1039`, 실행기 `presigned-transfer-executor.ts:340-345`). download는 idle 제한이 따로 있다(`:241`). image probe는 동시 4개 상한과 통과 결과 재사용(`image-cdn-runtime.ts:197-221, 587-676`). 남은 것: part마다 SHA-256을 3번 계산한다(manifest, runtime 검증, 실행기). 재개할 때 파일 전체를 다시 해시한다. 업로드 PUT에는 idle 제한이 없다. 두 deadline의 설정이 따로다(01-03). 레시피 번들 55,623 / 55,700 gzip bytes |
| 15 | 보안 성숙도 | O | M4 | E2 | vault identity, HTTPS, `credentials:"omit"`, `redirect:"error"`, `no-referrer`는 그대로다(`presigned-transfer-executor.ts:385-396`). 쓰지 못한 capability도 `finally`에서 vault에서 뺀다(`:107-120`, 01-07 해소) |
| 16 | 의존성 성숙도 | O | M2 | E1 | 외부 패키지가 없다. WebCrypto와 자체 SHA-256만 쓴다 |
| **17** | API / Contract 성숙도 | P | 목표 M3 / 확인 M1~M3 | E2(X1) | 포트 변경은 추가형이다(`UploadAbortOutcome.resourceId?`, 정책 필드는 `Partial`로 받음 `runtime-dependencies.ts:41`). CHANGELOG 0.2.0에 [계약]으로 적혔다. 하지만 "recovery가 행동 하나를 가리킨다"는 주장은 6개 경로에서 틀리다(01-01). `abort()` 실패에는 표가 없다(01-05). 사라진 session의 발급 응답 코드는 서버 문서에 없다 |
| 18 | 배포 성숙도 | O | M3 | E2 | 정책을 낮춘 새 빌드가 이전 checkpoint를 이어 간다(01-08 해소). 모르는 schema 행은 `abort()`로 지운다 |
| 19 | 설정 성숙도 | P | M2 | E2(X3) | 각 factory는 조립 시점에 값을 검증한다. 하지만 factory 사이의 값은 서로 검사하지 않는다. 느린 링크 설정(01-03), `maxPartCount`(13행), `maxRetryAfterMs`(전송·runtime 두 곳)가 그렇다 |
| 20 | 개발자 경험 | P | M1 | E1 | resumable upload 조립 문서가 없다. 조립 예는 Playwright spec 하나다 |
| 21 | Guardrail 성숙도 | P | M3 | E2(X5), E3(X4) | 영역 규칙은 변형으로 검출된다. 하지만 `check-adapter-inventory.ts:139-144`가 이 영역 파일 이름을 고정해 레시피 단위 제거를 막는다(01-04) |
| 22 | 추상화 성숙도 | O | M3 | E1, 제품 E1 | 앱 쪽 포트는 `upload()`·`abort()` 두 개로 작다. 프로토콜 전용 내용은 control plane 포트에 있다. 번역을 한 곳에 둔 선택은 맞다(3절 D1). 제품 1곳(memento)은 백엔드가 offset-append 방식이라 이 영역 대신 자체 실행기 172줄을 만들었다(`memento-frontend` `src/adapters/http/offset-upload.ts`). 템플릿이 한 프로토콜만 지원한다는 범위를 보여 주는 사례이고 결함은 아니다 |
| 23 | 일관성 | P | M2 | E2(X1, X2) | 같은 BFF 403이 createSession에서는 `NONE`, 발급에서는 `RESUME`이다(01-01). 서버 확정 뒤 로컬 정리 실패의 처리가 complete와 재조정에서 다르다(01-02) |
| 24 | 네이밍 / 의미 성숙도 | P | M2 | E2 | `NONE`이 `retryable:true`와 함께 나온다. 닫힌 runtime이 `RESUME`을 준다(01-01) |
| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인. 제품 2곳의 사용 증거는 22·27행에 적었다 |
| 26 | Ownership 성숙도 | P | M1 | E0~E1 | 서버 문서는 status의 404/410만 정한다(`server-file-capability-infrastructure.md:1663`). 발급 단계에서 사라진 session을 어떤 코드로 알릴지는 주인이 없다(01-01 ③). 백엔드 멱등 키 계약은 U-5로 사용자 몫 |
| 27 | 삭제 가능성 | P | 번들 단위 M3 주장 / 레시피 단위 M0 | E3(X4), 제품 E1 | 레시피는 조립되지 않아 production 번들에서는 이미 빠져 있다. 소스 삭제는 번들 전체 단위로만 검증된다(드릴은 이번에 실행하지 않음). 어댑터만 지우면 게이트 3개가 실패한다(01-04). 제품 2곳 모두 조립하지 않으면서 이 영역을 싣고 있다 |
| **28** | 회복 가능성 | P | 목표 M3 / 확인 M3(주 경로) | E2 | 중단 뒤 재개, 결과 불명 complete의 조정(경로 A·B·C), `ABORT_PENDING`, 읽을 수 없는 행 제거가 모두 테스트된다(M12·M15·M17 검출). 남은 것: 재조정 경로 삭제 실패(01-02). 버려진 checkpoint 자동 정리는 선언된 미구현 |
충족 O 9 · 부분 충족 P 18 · 미충족 X 0 · 미검증 ? 0 · 적용 제외 1.
## 3. 설계 선택 설명 (41절)
### D1. `upload()` 실패를 포트 경계 한 곳(`toUploadAction`)에서 호출자 행동 다섯 개로 번역한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 다운스트림 UI가 실패마다 버튼 하나(다시 / 재조정 / abort 후 다시 / 파일 다시 선택 / 없음)를 고른다. 공유 타입 `BrowserDataRecovery`는 13개 값이다(`src/application/ports/browser-file-storage/shared.ts:69-82`). upload에서 뜻이 있는 것은 5개다 |
| 2. 지킬 성질 | 모든 `upload()` 실패의 recovery가 포트 표의 한 행이다. 그 행동을 하면 상황이 나아지거나, `NONE`이면 정말 할 일이 없다 |
| 3. 현재 보장 | [확인한 사실] 번역은 한 곳이다(`resumable-upload-runtime.ts:1714-1726`). 표 밖의 값은 나가지 않는다(변형 M11 검출). [보장하지 않음] 번역 기준이 recovery 어휘뿐이다. 같은 `REOPEN`이 "파일이 바뀜"(재선택 필요)과 "IndexedDB 일시 오류"(다시 부르면 됨)를 모두 뜻하는데 둘 다 `NONE`이 된다(01-01) |
| 4. 대안 | (a) 한 곳 번역 유지 + code·retryable 기준 추가. (b) 각 출처(store·provider·file)가 포트 어휘를 직접 만든다. (c) 실패에 `action` 필드를 새로 둔다 |
| 5. 비교 | (a) 수십 줄. "`NONE`이면 `retryable:false`" 같은 불변식 하나로 검증된다. (b) 번역이 흩어진다. store·provider·file 표는 다른 포트도 쓰므로 upload 전용 어휘를 넣으면 다른 포트가 틀어진다. (c) 가장 명확하다. 공유 타입 변경이라 다른 포트까지 이행 비용이 든다 |
| 6. 판단 | 번역 위치는 유지가 맞다. [기록된 의도] 주석 `:1708-1713`은 "호출자가 직접 할 수 없는 provider 어휘를 행동으로 바꾼다"고 적는다. [리뷰어 추론] 기준만 고치면 되고 구조는 바꿀 필요가 없다 |
| 7. 재검토 조건 | 공유 recovery 어휘가 바뀔 때. `abort()`에도 표가 필요해질 때(01-05). 포트가 action 필드를 갖게 될 때 |
### D2. 멱등 키를 요청 binding·session·part에서 결정적으로 만든다 — 현 상태 유지
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 응답을 잃은 create·part·complete를 재시도하거나, 다른 탭·다음 호출에서 다시 보내도 서버가 같은 작업으로 알아본다(29.2) |
| 2. 지킬 성질 | 같은 논리 작업은 시도·호출·탭이 달라도 같은 키다. 다른 작업(새 session)은 다른 키다 |
| 3. 현재 보장 | [확인한 사실] `deriveUploadIdempotencyKey`(`upload-byte-source.ts:289-326`)는 label·request binding·sessionId·part 값만 쓴다. 시도 번호·시각·난수가 없다. session을 새로 만들 때는 이전 sessionId를 넣어 새 키를 만든다(`resumable-upload-runtime.ts:650-656`). 변형 M1·M6·M7·M8이 모두 검출된다. [보장하지 않음] 서버의 키 범위·보관 기간(U-5). ABORT 키 재사용은 테스트가 없다(M9 생존. abort는 서버에서 본래 멱등이라 피해는 작다) |
| 4. 대안 | (a) 현상 유지. (b) 호출마다 UUID를 만들어 checkpoint에 저장. (c) 키 없이 서버 상태를 먼저 조회한 뒤 쓰기 |
| 5. 비교 | (b) create 응답을 잃으면 checkpoint를 쓰기 전이라 키도 잃는다. 다음 호출이 새 키로 보낸다 — 가이드 6절의 위험 신호다. (c) 조회와 쓰기 사이에 다른 탭이 끼면 session이 둘 생긴다. (a)는 저장 없이 같은 키를 다시 만든다. 대신 같은 파일·같은 uploadKey로 다시 올리면 새 자원이 아니라 이전 자원이 `replayed:true`로 돌아온다. 포트는 uploadKey를 "caller-stable operation key"로 정해 이 비용을 계약에 둔다(`resumable-upload.ts:76`) |
| 6. 판단 | 현재 조건에서 유지할 근거가 있다. 변경 제안 없음 |
| 7. 재검토 조건 | 서버 키 보관 기간이 upload session 수명보다 짧아질 때. 같은 파일을 같은 key로 의도적으로 다시 올리는 요구가 생길 때 |
### D3. PUT 한 번에 runtime deadline과 실행기 deadline을 둘 다 건다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 느린 링크에서도 part가 끝나고, 멈춘 연결은 끊긴다(01-03). presigned 실행기는 resumable runtime 없이 download에도 쓰인다 |
| 2. 지킬 성질 | 어느 모듈을 단독으로 써도 PUT·download에 한도가 있다. 조립했을 때 설정한 최저 처리량이 실제로 적용된다 |
| 3. 현재 보장 | [확인한 사실] runtime은 `providerAttemptTimeoutMs + bytes/policy.minTransferBytesPerSecond`(`resumable-upload-runtime.ts:1033-1039`), 실행기는 `timeoutMs + bytes/options.minTransferBytesPerSecond`(`presigned-transfer-executor.ts:137-143, 340-345`). 단독 사용 시 한도는 보장된다. [보장하지 않음] 두 값이 따로 설정되고 짧은 쪽이 이긴다. 문서는 정책만 낮추라고 한다(`presigned-transfer-and-image-cdn.md:292-298`). 실험 X3에서 정책만 낮추면 실패했다(01-03) |
| 4. 대안 | (a) 두 겹 유지 + 문서에 두 곳을 적음. (b) runtime이 PUT deadline을 실행기에 넘긴다(port 입력 추가). (c) 실행기 PUT deadline 제거 |
| 5. 비교 | (a) 가장 작다. 실수는 막지 못한다. (b) 한 값이 두 계층을 정한다. `UploadPartExecutor` 입력이 바뀐다. (c) 실행기를 단독으로 쓸 때 한도가 없어진다. 성질 2를 깨므로 후보가 아니다 |
| 6. 판단 | 두 겹 자체는 유지할 근거가 있다(성질 2). 연결이 문서에만 있어야 한다면 (a), 실수를 막으려면 (b)다. 지금은 조립하는 제품이 없으므로 (a)가 비용에 맞다 |
| 7. 재검토 조건 | 제품이 이 레시피를 조립하거나 조립 helper를 만들 때 (b)를 다시 본다. 업로드 PUT에 idle 제한(FOLLOW-UP 01-03)을 넣을 때 함께 본다 |
## 4. 발견 사항 (36.3)
### 01-01 `upload()` 실패의 recovery가 6개 경로에서 포트 표와 다른 행동을 가리킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(공개 계약과 구현 불일치) |
| 관련 관점 | 17, 5, 6, 8, 23, 24 |
| 근거 | 포트는 "recovery가 호출자 행동 하나를 가리킨다"고 적는다(`src/application/ports/browser-transfer/resumable-upload.ts:104-121`). 문서도 같다(`docs/architecture/presigned-transfer-and-image-cdn.md:725-737`). 번역은 `toUploadAction`(`src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts:1714-1726`) 한 곳이 한다. 이 함수는 code와 단계를 보지 않는다. 표 밖의 값이면 `REISSUE_CAPABILITY`·`RETRY`만 `RESUME`으로 바꾸고 나머지는 모두 `NONE`으로 바꾼다. `retryable`은 그대로 둔다. 실험 X1 결과: ① 파일이 바뀜 — browser-files 예외표가 `NotReadableError`를 `NOT_READABLE, retryable:true, REOPEN`으로 만든다(`src/adapters/browser-file-storage/result.ts:75-79`, 파일 vault `src/adapters/browser-files/browser-file-vault.ts:474, 536`). `upload()`는 `{NOT_READABLE, UPLOAD_SESSION, retryable:true, NONE}`을 돌려준다. 다시 불러도 같다. 표대로면 `RESELECT`다. ② IndexedDB 일시 오류 — checkpoint store가 `UnknownError`를 `UNAVAILABLE, retryable:true, REOPEN`으로 만든다(`result.ts:160-164`, `indexeddb-checkpoint-store.ts:127-130`). 결과는 `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE}`이다. 같은 runtime으로 한 번 더 부르면 성공했다. ③ BFF 발급 404 — presigned provider가 `NOT_FOUND/NONE`으로 만들고(`src/adapters/browser-transfer/presigned/http-common.ts:167-170`), control plane이 그대로 넘긴다(`http-control-plane-adapter.ts:202-209`). 결과는 `{NOT_FOUND, UPLOAD_PART, retryable:false, NONE}`이다. 서버가 session을 잊은 조건에서 `upload()`를 다시 부르면 새 session으로 성공했다. ④ BFF 401/403 — 발급 단계에서는 `PERMISSION_DENIED/REISSUE_CAPABILITY`(`http-common.ts:164-166`)라서 `RESUME`이 된다. 같은 403이 createSession에서 오면 `NONE`이다(`fetch-json-transport.ts:560-561`). 표는 권한 거절을 `NONE`으로 적는다. ⑤ 닫힌 runtime — `{UNAVAILABLE, UPLOAD_SESSION, retryable:false, RESUME}`이다(`resumable-upload-runtime.ts:172-176`). 같은 runtime에 다시 부르면 늘 같은 답이다. ⑥ capability 만료가 session보다 늦음 — `POLICY_REJECTED/REISSUE_CAPABILITY`(`upload-response-validation.ts:70-74`)가 `RESUME`이 된다. 서버가 같은 값을 다시 주면 같은 실패다. 01-05 표 테스트(`tests/unit/resumable-upload-runtime-recovery.test.ts:729-890`)는 손으로 고른 7경로만 보고 `retryable`은 단언하지 않는다. 위 6경로에는 테스트가 없다 |
| 발생 조건 | ① 선택한 파일을 업로드 중이나 재개 전에 수정·이동. ② 브라우저 IndexedDB 백엔드 일시 오류. ③ BFF가 만료·정리된 session의 발급 요청에 404로 답함. ④ 세션 만료·권한 회수. ⑤ 로그아웃 teardown 뒤 늦게 도착한 호출. ⑥ 서버가 session보다 긴 capability를 줌 |
| 영향 | 포트 표대로 화면을 만든 다운스트림은 ①②③에서 "할 일 없음"으로 멈춘다. 실제로는 파일 재선택이나 재호출로 풀린다. `retryable`을 먼저 보는 다운스트림은 ①에서 같은 실패를 자기 재시도 한도까지 반복한다. ④⑥에서는 "다시 시도"가 파일 전체 재해시 뒤 같은 거절을 받는다. 데이터 손상과 부작용 중복은 없다 |
| 심각도·우선순위 | Medium · P2 — 지난 01-05와 같은 급이다. CHANGELOG 0.2.0 [계약]이 recovery 정리를 알렸으므로 다운스트림은 이 표를 믿는다. 피해는 막다른 화면과 불필요한 재해시에 그친다 |
| 통제·증거 | 7경로 M3(표 테스트) · 위 6경로 M1(주석은 있으나 구현이 다름) · E2(실험 X1. 단위 harness에서 실제 매핑 함수로 오류를 주입했다. 실제 브라우저 오류 발생은 미재현) |
| 확실성과 남은 가정 | ①②④⑤⑥은 코드와 실험으로 확정했다. ③은 "BFF가 사라진 session의 발급에 404를 준다"는 가정이 필요하다. 서버 문서는 status의 404/410만 정한다(`server-file-capability-infrastructure.md:1663`) |
| 결정의 근거 | 번역을 한 곳에 두는 선택은 유지할 만하다(3절 D1). 결함은 번역 기준이 recovery 어휘뿐이라는 점이다 |
| 이해 비용 | 다운스트림 UI 작성자는 포트 표를 믿으면 틀리고, 믿지 않으면 runtime·provider 상태표·store 예외표 세 곳을 읽어야 한다 |
| 최소 개선 방향 | `toUploadAction`이 code와 `retryable`을 함께 본다. 예: `NOT_READABLE`·`STALE_RESULT` → `RESELECT`. 표 밖이면서 `retryable:true` → `RESUME`. `UPLOAD_PART` 단계의 `NOT_FOUND`·`EXPIRED_RESOURCE` → `RECONCILE`. `PERMISSION_DENIED`와 서버 정책 거절 → 단계와 무관하게 `NONE`. 닫힌 runtime → `NONE`(또는 표에 "새 runtime 필요" 행). 불변식 "`NONE`이면 `retryable:false`"를 번역 끝에서 강제한다 |
| 대안 비교 | 3절 D1. (a) 번역 기준 보강이 가장 작다. (b) 출처마다 포트 어휘 생성은 다른 포트를 틀어지게 한다. (c) action 필드 추가는 공유 타입 변경이라 비용이 크다 |
| 단순화의 보존 조건 | 기존 7경로의 기대값(`recovery.test.ts:843-880`)을 유지한다. PUT 403 재발급(M13)과 complete 결과 보고(M12·M15)를 바꾸지 않는다 |
| 비용·부작용 | 수십 줄. 몇 경로의 recovery 값이 바뀌므로 CHANGELOG [계약] 한 줄이 필요하다 |
| 재검토 조건 | `BrowserDataRecovery`에 값이 추가될 때. 포트가 action 필드를 갖게 될 때 |
| 완료 기준 | 실험 X1의 6경로가 표의 행동과 맞는 recovery를 낸다. 모든 `upload()` 실패에서 `recovery === "NONE"`이면 `retryable === false`다 |
| 검증 방법 | 01-05 표 테스트에 6경로를 추가하고 `retryable`도 단언한다. `toUploadAction`을 지금 규칙으로 되돌리는 변형이 새 테스트를 실패시켜야 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 01-05 수정(`426b6b8`)이 남긴 빈틈. 01-05의 완료 기준("실패 경로마다 행동 하나")은 7경로에서만 확인됐다 |
### 01-02 complete가 반영된 뒤 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 28, 6, 11, 23 |
| 근거 | 01-02 수정은 `completeUpload`에서만 로컬 정리 실패를 무시하고 성공을 돌려준다(`resumable-upload-runtime.ts:1149-1156`). 같은 상황의 다른 경로는 그대로다. complete 응답을 잃은 뒤 `upload()`를 다시 부르면 `reconcileActiveCheckpoint`가 status `QUARANTINED`와 resourceId를 받는다. 그다음 `removeCheckpoint`가 실패하면 그 실패를 돌려준다(`:583-589`). 문서는 "서버가 complete를 반영한 뒤 로컬 삭제가 실패해도 `upload()`는 성공"이라고 적는다(`presigned-transfer-and-image-cdn.md:382-384`). 실험 X2: 첫 호출 `{UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME}`. 둘째 호출(삭제 1회 실패 주입) `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE}`, resourceId 없음. 셋째 호출 `{QUARANTINED, resource_01, replayed:true}`. 둘째 호출의 `NONE`은 01-01의 번역 때문이다 |
| 발생 조건 | complete 응답 유실 뒤 재호출에서 IndexedDB 일시 오류. status 응답 직후 caller abort도 같은 분기를 타지만 이때 `ABORTED`는 맞는 답이다 |
| 영향 | 서버에는 자원이 확정됐는데 화면은 실패를 보인다. 01-01 때문에 "할 일 없음"으로 보인다. 행은 남으므로 다음 `upload()`나 `abort()`가 같은 resourceId를 준다. 다만 파일 전체를 다시 해시한다 |
| 심각도·우선순위 | Low · P3 — 두 실패가 겹쳐야 하고 다음 호출로 복구된다 |
| 통제·증거 | complete 경로 M3(변형 M12 검출) · 재조정 경로 M0 · E2(실험 X2) |
| 확실성과 남은 가정 | 코드와 실험으로 확정했다 |
| 결정의 근거 | 적용 제외 — 01-02에서 정한 규칙("서버 확정 뒤의 로컬 정리 실패는 성공")을 같은 조건의 다른 경로에 적용하는 문제다 |
| 이해 비용 | 적용 제외 — 지역 결함 |
| 최소 개선 방향 | `reconcileActiveCheckpoint`의 `QUARANTINED` 분기에서 삭제 실패를 무시하고 `COMPLETED`를 돌려준다. caller abort는 지금처럼 `ABORTED`로 둬도 된다 |
| 대안 비교 | 적용 제외 — 기대 계약이 이미 문서에 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄. 남은 행은 다음 호출이 정리한다(경로 C와 같음) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 실험 X2의 둘째 호출이 `replayed:true`와 resourceId를 돌려준다 |
| 검증 방법 | `recovery.test.ts`의 01-02 절에 "재조정 중 삭제 실패" 테스트를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 01-02 ②와 같은 성질의 다른 경로 |
### 01-03 느린 업링크 설정이 runtime 정책과 presigned 실행기에 따로 있고, 문서는 한쪽만 바꾸라고 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서와 동작 불일치) |
| 관련 관점 | 19, 5, 14, 20 |
| 근거 | PUT 한 번에 deadline이 두 개 걸린다. runtime은 `providerAttemptTimeoutMs + bytes/policy.minTransferBytesPerSecond`다(`resumable-upload-runtime.ts:1033-1039`). presigned 실행기는 자기 `timeoutMs + bytes/options.minTransferBytesPerSecond`다(`presigned-transfer-executor.ts:137-143, 340-345`, 기본 64KiB/s). 두 값은 다른 factory에 들어가고 서로 검사하지 않는다. 짧은 쪽이 이긴다. 문서는 "이보다 느리면 정책의 `minTransferBytesPerSecond`를 낮춘다"고만 적는다(`presigned-transfer-and-image-cdn.md:292-298`). 실험 X3(실제 provider·vault·실행기, fake timer, PUT 7초): runtime만 낮추면(runtime 9초, 실행기 5초) PUT 3번 뒤 `{UNAVAILABLE, UPLOAD_PART, retryable:true, RESUME}`. 실행기도 낮추면 PUT 1번에 성공했다 |
| 발생 조건 | 다운스트림이 기본 약 0.5Mbit/s보다 느린 업링크를 지원하려고 문서대로 정책만 바꾼다 |
| 영향 | 설정을 바꿨는데 그 사용자는 여전히 업로드하지 못한다. 호출마다 part를 `maxRetries+1`번 보내고 버린다 |
| 심각도·우선순위 | Low · P3 — 기본값에서는 두 값이 같다. 설정을 바꾸는 다운스트림에만 생긴다 |
| 통제·증거 | M1(문서가 한쪽만 적음) · E2(실험 X3) |
| 확실성과 남은 가정 | 실험으로 확인했다. 실제 저속 네트워크는 미검증 |
| 결정의 근거 | 두 겹 deadline은 유지할 근거가 있다(3절 D3). 실행기는 runtime 없이도 쓰이므로 자기 한도가 필요하다 |
| 이해 비용 | 조립하는 사람이 두 factory의 네 값(`timeoutMs`, 실행기 min rate, `providerAttemptTimeoutMs`, 정책 min rate)을 함께 맞춰야 한다는 사실을 코드를 읽어야 안다 |
| 최소 개선 방향 | 문서 3.x에 "실행기의 `timeoutMs`·`minTransferBytesPerSecond`도 같이 낮춘다"를 적는다 |
| 대안 비교 | 3절 D3. (a) 문서만 고침: 몇 줄, 실수는 못 막음. (b) runtime이 PUT deadline을 실행기에 넘김: port 입력 추가. (c) 실행기 deadline 제거: 단독 사용 시 한도가 사라져 후보 아님 |
| 단순화의 보존 조건 | 실행기를 단독으로 쓸 때 PUT·download에 한도가 있어야 한다 |
| 비용·부작용 | (a) 몇 줄. (b) 작음, port 변경이라 [계약] |
| 재검토 조건 | 조립 helper가 생기거나 업로드 PUT에 idle 제한을 넣을 때 (b)를 다시 본다 |
| 완료 기준 | 문서가 두 곳을 모두 적거나, 한 곳만 바꿔도 실험 X3이 성공한다 |
| 검증 방법 | 실험 X3을 `recovery.test.ts`의 01-03 절로 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 01-03 수정(`5a6665a`)이 두 계층에 같은 식을 넣으면서 생긴 연결 문제. 지난 19행 "factory 사이 값을 서로 검사하지 않음"과 같은 계열 |
### 01-04 file-transfer 어댑터만 지우면 게이트 3개가 실패한다 — 가드레일이 이 영역 파일 이름에 고정돼 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 27, 21, 20 (+30.4, 30.7) |
| 근거 | 카탈로그는 file-transfer를 독립 선택 레시피로 둔다(`config/recipes/frontend-capability-recipes.json:155-201`). 제거 드릴은 browser-file-storage 번들 전체를 한꺼번에만 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:24-37`). 이 한계는 주석에 기록돼 있다(`src/adapters/storage/index.ts:1-9`). browser-files는 `ports/browser-transfer/presigned-transfer.ts` 타입을 import하므로(`src/adapters/browser-files/download-delivery-adapter.ts:16`, `download-input-validation.ts:11`) port 폴더는 남겨야 한다. 실험 X4에서 `src/adapters/browser-transfer/`와 단위 테스트 15파일만 지웠다. `check:architecture`·`check:browser-file-storage-boundaries`는 통과했다. `check:types`는 Playwright spec 2개의 import 5건으로 실패했다. `check:adapter-inventory`는 이름으로 박힌 필수 소비자 4파일(`scripts/check-adapter-inventory.ts:139-144`)이 없어 실패했다. `check:optional-recipes`는 원인을 말하지 않는 ZodError "must cover every reference runtime"(`scripts/contracts/release-artifacts.ts:1147`)으로 멈췄다. 제품 증거: 두 제품의 `chore/template-sync-v0.2.0`에는 browser-transfer나 browser-file-storage 번들을 조립하는 코드가 없다(참조는 설치되지 않은 샘플 `local-draft-feature`뿐). 두 제품 모두 이 영역 37파일 +4,632/−2,085줄 변경을 이번 동기화로 받았다 |
| 발생 조건 | 번들의 일부(browser-files 등)는 쓰고 file-transfer는 빼려는 제품. 지금 제품 2곳은 번들 전체를 쓰지 않으므로 번들 드릴로도 지울 수 있다. 그러나 그렇게 하지 않았고 이유는 기록에 없다 |
| 영향 | 레시피 하나를 빼려면 드릴이 확인하지 않는 편집(게이트 스크립트·카탈로그·spec)을 손으로 해야 한다. 한 실패 메시지는 원인을 가리키지 않는다. 사용자·데이터 피해는 없다 |
| 심각도·우선순위 | Low · P3 — 지금 제품 조건에서는 번들 단위 제거로 우회할 수 있다. 가드레일이 템플릿 자신의 모양에 고정된 점은 지난 14-02와 같은 계열이다 |
| 통제·증거 | 번들 단위 제거 M3 주장(드릴은 이번에 미실행) · 레시피 단위 M0 · E3(실험 X4), 제품 repo E1 |
| 확실성과 남은 가정 | 게이트 실패는 실행으로 확인했다. `lint`·`test:unit`·build는 돌리지 않았다. 제품이 이 영역을 남긴 이유는 미확인이다 |
| 결정의 근거 | [기록된 의도] 번들 단위 드릴은 "두 폴더 중 하나만 지우는 경우는 드릴이 검증하지 않는다"고 명시한 선택이다(`storage/index.ts:6-9`). [확인한 사실] 번들 안 모듈이 port 타입을 공유하므로 번들 단위 검증이 가장 싸다. [리뷰어 추론] 드릴 범위는 유지해도 된다. 문제는 게이트가 파일 이름을 고정해 부분 제거에서 설명 없이 깨진다는 점이다 |
| 이해 비용 | 레시피를 빼려는 제품 담당자는 카탈로그, `check-adapter-inventory.ts`의 고정 목록, `optional-recipes.ts`, Playwright spec을 스스로 찾아야 한다. 이 목록은 어디에도 없다 |
| 최소 개선 방향 | (1) `check-adapter-inventory.ts`의 필수 소비자 목록을 존재하는 파일로만 검사한다. (2) `check:optional-recipes`가 사라진 sourceRoot를 "레시피 X의 경로가 없음"으로 보고한다. (3) 레시피 단위 제거 절차를 카탈로그의 `removal`이나 문서에 적는다 |
| 대안 비교 | (a) 현상 유지: 비용 없음, 부분 제거는 손으로. (b) 위 (1)~(3): 게이트 두 곳 + 문서. (c) 드릴에 `--recipe=file-transfer` 모드 추가: 가장 확실하지만 CI 시간이 드릴 한 번만큼 늘어난다. 조립하는 제품이 없으므로 (b)가 비용에 맞다 |
| 단순화의 보존 조건 | 파일이 있을 때 `check-adapter-inventory`는 abort 사본 재발을 계속 막아야 한다. 번들 전체 제거 드릴은 그대로 통과해야 한다 |
| 비용·부작용 | 게이트 스크립트 두 곳, 문서 몇 줄 |
| 재검토 조건 | 제품이 번들의 일부만 조립하기 시작하면 (c)를 다시 비교한다 |
| 완료 기준 | browser-transfer 어댑터만 지운 fixture에서 `check:adapter-inventory`와 `check:optional-recipes`가 원인을 말하는 메시지로 실패하거나 통과한다 |
| 검증 방법 | 실험 X4를 다시 실행한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 27행은 "미검증(드릴 미실행)"이었다. 새로 확인한 사실이다. 12(가드레일)·14(템플릿·제품) 영역과 겹칠 수 있다 |
### 01-05 `abort()` 실패의 recovery에는 호출자 행동 표가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 5, 24 |
| 근거 | 행동 표는 `upload()`에만 있다(`resumable-upload.ts:104-121`). `abort()`는 `toUploadAction`을 거치지 않는다(`resumable-upload-runtime.ts:237-278`). 그래서 store의 `REOPEN`·`READ_ONLY`·`RETRY`와 provider 값이 그대로 나온다. 서버가 모르는 state를 주면 `CORRUPT_DATA/UPLOAD_ABORT/RECONCILE`이다(`:1241-1253`). 표에서 `RECONCILE`은 "`upload()`를 다시 부른다"다. 그런데 그러면 `ABORT_PENDING` 때문에 `RESTART`("먼저 `abort()`")가 온다(실험 X1 ⑦). 표의 `RESTART` 행이 호출자를 `abort()`로 보내므로 `abort()` 실패의 뜻도 정해져야 한다 |
| 발생 조건 | abort 중 IndexedDB 오류, 서버 409·5xx·형식이 틀린 응답 |
| 영향 | 다운스트림이 `abort()` 실패를 각자 해석한다. 형식이 틀린 서버 응답에서는 사람이 `upload()`와 `abort()`를 번갈아 누르는 순환이 생긴다(자동 반복은 아님) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0(abort 행동 표 없음) · E2(실험 X1 ⑦) |
| 확실성과 남은 가정 | 코드와 실험으로 확인했다 |
| 결정의 근거 | 적용 제외 — 이미 정한 upload 표를 abort로 넓히는 문제다 |
| 이해 비용 | abort 실패 처리를 정하려면 runtime·store·전송 상태표를 읽어야 한다 |
| 최소 개선 방향 | 포트 주석에 `abort()` 실패의 행동(`abort()` 다시 / 할 일 없음)을 적고, `abort()`에도 01-01과 같은 번역을 둔다 |
| 대안 비교 | 적용 제외 — 01-01의 번역 기준을 공유한다 |
| 단순화의 보존 조건 | `ABORT_PENDING` 유지, `ALREADY_COMPLETED`의 resourceId 반환(M15)을 바꾸지 않는다 |
| 비용·부작용 | 작음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `abort()` 실패 경로마다 recovery가 포트에 적힌 행동 하나다 |
| 검증 방법 | 01-05 표 테스트와 같은 each 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 01-05는 `upload()`만 다뤘다 |
## 5. FOLLOW-UP 재확인
지난 라운드 발견 01-01~01-11의 해소 여부는 머리말 변형표(M12~M17 등)와 판정표에 적었다. 모두 현재 코드에 수정과 검출 테스트가 있다(01-06은 결정으로 종료). 아래는 `FOLLOW-UP.md`의 이 영역 항목이다.
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| 1절 P2 file-transfer 레시피 번들 예산 55,600 → 55,700, 코드를 줄이지 않음 | **유효** | 측정 55,623 / 55,700 gzip bytes(여유 77바이트, `check-optional-recipes.ts` source 실행). 예산 이력은 52,000 → 54,600 → 55,600 → 55,700으로 라운드마다 측정값 + 약 100바이트로 올렸다(`docs/operations/adapter-remediation-ledger.md:441-450, 459`, 커밋 `6fe4aa9`, `4b0e44a`). 늘어난 원인별 분석은 없다. 다음 수정이 이 영역에 77바이트 넘게 더하면 게이트가 실패한다 |
| 1절 P2 `check:remediation-ledger`의 file-transfer 예산 문구 | **유효** | 원장은 54,600을 적는다(`adapter-remediation-ledger.md:448, 459`). 제품 `tech-log-frontend` 동기화 기록도 `af3d8e6`에서 이 검사가 실패한다고 적는다(`docs/operations/template-sync-2026-09-29.md:473`). 전체 판단은 12영역 몫 |
| 4절 P3 01-06 하한은 skew를 반영하지 않음(사용자 결정) | **유효**(결정 유지) | 조건이 문서에 있다(`presigned-transfer-and-image-cdn.md:167-174`). 상한 쪽 skew는 변형 M16이 검출된다 |
| 4절 P3 01-11 probe 재사용 테스트가 공개 이미지만 씀 | **유효** | `tests/unit/image-cdn-runtime.test.ts:1444-1578`의 3개 테스트가 모두 `acceptPublicImmutable(publicAsset())`을 쓴다. capability가 필요한 비공개 이미지 경로의 재사용·만료 재확인은 테스트가 없다 |
| 4절 P3 01-09 바이트 한도 검사는 transport에 `maxPartCount`를 넘길 때만 동작 | **유효** | `fetch-json-transport.ts:157-166`. 유일한 조립 예도 넘기지 않는다(`resumable-upload.spec.ts:329-341`) |
| 4절 P3 01-03 업로드 PUT에 idle 제한 없음 | **유효** | 문서가 그렇게 적는다(`presigned-transfer-and-image-cdn.md:295-297`). 멈춘 5MiB part는 약 110초 뒤 끊긴다. 01-03(이번)의 두 deadline 문제와 함께 볼 항목이다 |
| 5절 P2 `resumable-upload.spec.ts:7` `PAGE_ORIGIN` 포트 4174 고정 | **유효** | `tests/browser-capabilities/resumable-upload.spec.ts:7`. 설정은 `playwright.capabilities.config.ts:24, 30-31`에서 따로 4174를 쓴다. 이번 브라우저 실행은 기본 포트라 통과했다 |
## 6. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 두 탭이 같은 uploadKey로 동시에 upload/abort | 단위 테스트는 메모리 lock·채널만 쓴다. 브라우저 spec은 탭 하나다 | Playwright page 두 개에서 같은 key로 upload와 abort를 겹친다 |
| 01-01 ①②가 실제 브라우저에서 나는 조건 | 실험은 실제 예외 매핑 함수로 주입했다. 파일 수정·IndexedDB 오류를 브라우저에서 일으키지 않았다 | 브라우저에서 선택한 파일을 바꾼 뒤 `openSource` 스트림으로 upload |
| BFF가 사라진 session의 발급에 주는 응답 코드 | 서버 문서는 status만 정한다 | 서버 계약에 발급 단계 404/410 의미를 추가하고 conformance 테스트 |
| 실제 object store의 PUT 403 조건, 같은 키 재발급 응답, complete 소요 시간 | repo 밖 시스템 | provider conformance 테스트(서버 문서 10.2) |
| 저속 실제 네트워크 | 실험은 fake timer | 네트워크 throttling(0.3Mbit/s)으로 5MiB part 업로드 |
| part 버퍼 실제 메모리(copyFactor 4 추정) | 측정 환경 없음 | 브라우저 메모리 프로파일 |
| 번들 단위 제거 드릴 | `test:browser-file-storage-removal`은 fixture에 pnpm을 돌리는 무거운 스크립트라 동시 작업 중 돌리지 않았다 | 단독 환경에서 실행 |
| 레시피 단위 제거 뒤 `lint`·`test:unit`·build | 실험 X4는 게이트 5개만 돌렸다 | X4 fixture에서 나머지 게이트 실행 |
| 레시피 번들 증가분의 원인별 크기 | 모듈별 측정 도구가 없다 | 번들 metafile로 모듈별 gzip 기여를 뽑는다 |
| logout 때 checkpoint partition 삭제 순서 | 조립 코드가 repo에 없다(`AVAILABLE_NOT_COMPOSED`) | 다운스트림 조립에서 `dispose()` → `deletePartition()` 순서 검증 |
@@ -0,0 +1,392 @@
# 02 — browser-files / cache-storage / cross-context-invalidation 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능** — cross-context-invalidation과 browser-files는 지금 범위에서 쓸 수 있다. cache-storage는 정책 값을 바꾸는 배포 전에 02-01을 고쳐야 한다.
## 0. 머리말
### 0.1 결론
- 지난 라운드의 02 발견 9건은 현재 코드에서 회귀가 없다. 코드·테스트로 고친 7건(02-01·02-02·02-04~02-08)의 규칙 12개에 변이를 넣었고 테스트가 모두 잡았다(6.2절).
- 새로 확인한 가장 큰 문제는 **Cache Storage의 active pointer를 현재 정책으로 검증한다는 점이다(02-01, Medium).**
- `retainedPreviousReleaseCount`를 줄인 배포나 pointer 손상 뒤에는 조회·활성화·정리가 모두 `CORRUPT_DATA`로 멈춘다.
- 어댑터 API로는 되돌릴 방법이 없다. 배포마다 캐시가 하나씩 쌓인다.
- 실제 Chromium·Firefox·WebKit Cache API에서 재현했다.
- cross-context-invalidation의 kernel 예외는 지금 query-cache의 **타입 import 2개**에만 쓰인다. 예외는 barrel 전체(런타임 팩토리 포함)를 모든 adapter에 연다. 타입을 contracts로 옮기면 예외 없이 게이트를 통과한다(02-06, 개선 제안, 소유자 결정 필요).
- 나머지는 Low다. `inspect()`의 비용·취소·판정 불가 표현(02-02), CHANGELOG 0.2.0의 영향 경로 오류(02-03), 설계 문서 줄 번호 drift(02-04, FOLLOW-UP 02-09 유효), handoff 실패 시 lease 반환 규칙의 테스트 공백(02-05).
### 0.2 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, 영역 02 |
| 커밋·작업 상태 | `main` / `af3d8e6`(태그 `v0.2.0` + docs 1). 워킹트리의 미커밋 변경은 리뷰 가이드 문서 2개뿐이고 코드는 `af3d8e6`과 같다 |
| 목적과 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 조립 상태 | cross-context-invalidation은 기본 조립이다(`src/bootstrap/runtime-adapters.ts:359-403`). browser-files는 file-transfer recipe, cache-storage는 service-worker-pwa recipe의 `AVAILABLE_NOT_COMPOSED` 런타임이다(`config/recipes/frontend-capability-recipes.json:121-128`). repo 안에서 두 런타임을 조립하는 코드는 없다 |
| 제품 repo 증거 | `tech-log-frontend`, `memento-frontend`(둘 다 `chore/template-sync-v0.2.0`)는 세 폴더를 `af3d8e6`과 똑같이 들고 있다(`git diff af3d8e6 <branch> -- <3 폴더>` 차이 없음). 둘 다 cross-context만 `src/bootstrap/runtime-adapters.ts`에서 쓰고 browser-files·cache-storage는 조립하지 않는다 |
| 규모·운영 목표 | 합의된 목표 없음. 상한 값(개수·바이트)만 코드에 있다 |
| 읽은 코드 | 세 폴더 전체(18파일, 8,140줄). 포트 `src/application/ports/browser-file-storage/{file,shared,cache-storage-ports}.ts`. kernel `src/adapters/browser-file-storage/result.ts`. 계약 `src/contracts/cache-invalidation.ts`. 소비·조립 `src/adapters/query-cache/tanstack-cache-coordinator.ts`, `src/bootstrap/runtime-adapters.ts:330-420`, `src/bootstrap/server-state-generation-store.ts` |
| 읽은 설정·문서(주장) | `.dependency-cruiser.json:241-251`, `docs/architecture/layers.md:40-60`, `CHANGELOG.md` 0.2.0, `README.md:315-340`, `docs/architecture/browser-file-and-origin-storage.md` 3.5·8.3·9절, `docs/architecture/client-cache-and-storage.md` 앞부분 |
| 실행한 테스트 | 영역 unit 11파일 → **146/146 통과**(`node scripts/run-vitest.ts run tests/unit/{browser-file-*,cross-tab-invalidation,public-response-cache*,tanstack-cache-coordinator,abortable-operation}.test.ts`) |
| 실행한 브라우저 테스트 | 분리 worktree에서 `tests/browser-capabilities/{browser-files,cross-context-invalidation,public-cache-storage}.spec.ts`를 chromium·firefox·webkit으로 실행 → **21/21 통과**. 다른 에이전트와 포트가 겹치지 않게 설정 사본의 포트만 4192로 바꿨다 |
| 실험 | E-1 pointer 호환성(Node, 테스트 대역) · E-2 같은 시나리오를 실제 Cache API 3엔진에서 · E-3 변이 19개 · E-4 kernel 예외 probe 2개 · E-5 browser-file-storage 런타임 제거 드릴. 결과는 해당 절에 적었다. worktree는 끝나고 지웠다 |
| 확인하지 못한 범위 | 실제 제품 화면에서의 사용(소비자 없음). 다른 탭에서 계정이 바뀐 뒤의 무효화 hint 영향(auth 영역 의존). Safari의 blob URL 30초 grace 충분성. 7절에 정리했다 |
| 이전 리뷰와 비교 | `docs/reviews/2026-09-25-maturity-review/02-adapters-browser-files-cache.md`(`4626b73`). 지난 결과는 증거로 쓰지 않았고 현재 코드와 실행으로 다시 확인했다 |
### 0.3 실험 기록
| ID | 방법 | 결과 |
|---|---|---|
| E-1 | worktree에 `tests/unit/zz-review02-pointer.test.ts`를 임시로 두었다. `MemoryCacheStorage` 위에서 retained 3으로 release 3개를 활성화한 뒤, 같은 저장소에 retained 1 정책으로 adapter를 새로 만들었다. pointer JSON을 잘라 넣는 경우도 따로 돌렸다 | 조회·활성화·정리·inspect가 모두 `CORRUPT_DATA`/`REHYDRATE`. stage는 성공해 캐시만 늘어난다. 손상 JSON 경우도 활성화 2회와 정리가 같은 실패 |
| E-2 | 같은 시나리오를 Playwright로 실제 `caches`·`navigator.locks`에서 실행(`tests/browser-capabilities/zz-review02-pointer.spec.ts`, 임시) | chromium·firefox·webkit 모두 `{"lookup":"CORRUPT_DATA","deploys":[{"staged":"ok","activated":"CORRUPT_DATA"} ×2],"cleanup":"CORRUPT_DATA","ownedCaches":6}` |
| E-3 | 규칙 한 줄씩 바꾸고 관련 unit 파일만 실행 | 19개 중 14개 검출, 5개 생존. 표는 6.2절 |
| E-4 | P1: `src/adapters/realtime/`에 cross-context 런타임 팩토리를 import하는 파일 추가. P2: query-cache가 쓰는 3개 멤버 타입을 `src/contracts/cache-invalidation.ts`로 옮기고 kernel 예외에서 `cross-context-invalidation/index.ts`를 뺐다 | P1: `check:architecture` 통과(예외가 런타임까지 연다). P2: `check:architecture` 통과, `tsc -p tsconfig.app.json`·`tsconfig.test.json` 오류 0, 관련 unit 30/30 통과 |
| E-5 | worktree에서 `corepack pnpm test:browser-file-storage-removal`(바깥 pnpm의 설치 점검은 `pnpm_config_verify_deps_before_run=false`로 껐다). worktree의 `node_modules`는 메인 repo로의 심볼릭 링크였다. 이 방식은 pnpm이 링크를 통해 메인 `node_modules`를 설치·삭제할 위험이 있다는 오케스트레이터 경고를 받기 **전에** 실행했다 | 3회 실행, 3회째 PASS. 상세는 2.3절. 세 로그 모두 설치·삭제 시도(`ERR_PNPM`, `Packages:`, `Progress:`)가 없다. 메인 `node_modules/.modules.yaml`·`.pnpm/lock.yaml` 수정 시각은 첫 실행 전(16:26) 그대로다. 다음 리뷰에서는 이 드릴을 worktree에서 pnpm으로 돌리지 않는다 |
`check:architecture`는 worktree에서 pnpm이 설치 점검을 시도하지 않도록 `npm_execpath`에 `pnpm exec`만 대신하는 shim을 넣어 실행했다.
## 1. 확인된 강점
1. **캐시에 사용자 응답이 들어갈 경로를 여러 겹으로 막고, 그 규칙이 테스트로 고정돼 있다.** stage 요청은 `credentials: "omit"`, `mode: "same-origin"`, `redirect: "error"`다(`src/adapters/cache-storage/public-cache-response-validation.ts:223-238`). `private`·`no-store`·`Set-Cookie`·`Vary: Cookie` 응답은 거절한다(`:54-66`, `:187-193`). `credentials`를 `"include"`로 바꾼 변이는 테스트가 잡았다(E-3 M08).
2. **캐시 교체는 검증 뒤에만 성공을 말한다.** 기존 후보는 교체본이 검증되기 전에 지우지 않고(`public-response-cache-adapter.ts:452-498`), abort 뒤에는 자산·marker를 쓰지 않는다(`:416-437`, `:566-569`). 활성화는 후보의 모든 entry를 다시 읽고 SHA-256을 맞춘다(`:672-691`, `:1068-1118`). 실제 3엔진에서 "B stage 실패 중에도 A 유지 → B 활성화 → owned만 정리"가 통과했다.
3. **여러 탭의 중복·역순·누락을 명시적으로 처리한다.** eventId 중복 제거, source별 watermark, 빠진 순번은 `GAP` → 전체 topic 무효화(`browser-cross-context-invalidation.ts:484-514`, `tanstack-cache-coordinator.ts:109-116`). STALE 검사와 `storageArea` 검사를 지운 변이는 테스트가 잡았다(M11, M12). 실제 3엔진에서 BroadcastChannel과 localStorage fallback이 모두 통과했다.
4. **파일 이름·MIME을 신뢰하지 않는다.** 저장 이름은 정책의 `safeExtension`만 붙이고 실행 확장자를 무력화한다(`file-policy.ts:310-371`). preview MIME은 서명 바이트에서 오고, 그 타입으로 Blob을 다시 만든다(`object-url-lease.ts:296-318`).
5. **취소·닫기·권한 거부·자원 소진을 Result에서 구분한다.** 닫은 선택 창·저장 창은 `DISMISSED` 성공이고(`browser-file-picker.ts:283-288`, `download-delivery-adapter.ts:531-569`) 관측에서도 `DISMISSED`로 남는다(`file-observer.ts:28-44`). 같은 턴 abort는 `ABORTED`다(`object-url-lease.ts:292-295`). lease 소진은 `retryable:true`, 단일 Blob 한도 초과는 재시도 불가다(`object-url-lease.ts:53-71`, `:122-139`).
## 2. 대표 흐름
### 2.1 정상 흐름 — 탭 A의 저장이 탭 B의 캐시를 무효화한다
```text
탭 A: 명령 성공 → coordinator.invalidate(topics) tanstack-cache-coordinator.ts:184-205
→ invalidateLocal: 활성 query refetch :62-93
→ crossContext.publish({topic, topicVersion}) browser-cross-context-invalidation.ts:292-365
→ 자기 envelope 검사 → sequence+1 → BroadcastChannel.postMessage
→ postMessage가 던지면 localStorage pulse(setItem → removeItem) :377-439
탭 B: message / storage 이벤트
→ parse: protocol·cacheEpoch(같은 release)·topic 버전·TTL contracts/cache-invalidation.ts:123-205
→ storage 이벤트는 캡처한 localStorage와 같은 객체만 browser-cross-context-invalidation.ts:197-212
→ SELF_ECHO / DUPLICATE / STALE 폐기, 순번이 빠지면 GAP :469-514
→ coordinator.receiveRemote → pendingRemote(GAP이면 전체 topic) tanstack-cache-coordinator.ts:95-118
→ 그 topic의 mutation lease가 없을 때 invalidateQueries :120-157
```
| 단계 | 내용 |
|---|---|
| 입력 | 명령 성공 뒤의 등록 topic과 version |
| 정책 | 등록 topic만, 같은 release(`cacheEpoch`)끼리만, TTL 60초(`browser-cross-context-invalidation.ts:160`) |
| 상태 변화 | 탭 B의 TanStack 캐시가 stale이 되고 활성 query가 다시 읽힌다 |
| 외부 I/O | BroadcastChannel, localStorage `storage` 이벤트 |
| 실패 | 두 전송이 모두 없으면 `DEGRADED_LOCAL_ONLY`이고 `cache.operation.failed` 진단을 남긴다(`runtime-adapters.ts:374-386`). 부팅은 막지 않는다 |
| 결과 | 성공 시 탭 B가 새 값을 읽는다. 실패 시 탭 B는 focus refetch 전까지 오래된 값을 본다. release가 다른 탭끼리는 hint가 오가지 않는다(설계상 선언) |
### 2.2 피해가 큰 흐름 — Cache Storage release 배포와 정책 변경
```text
빌드 manifest → admin.stageRelease public-response-cache-adapter.ts:387-606
→ manifest digest 검증 → Web Lock → 자산 fetch(익명) → 검증 → put → marker
→ admin.activateRelease(id, digest) :608-759
→ 후보 전체 재검증 :672-691
→ 이전 pointer 읽기 ← 여기서 CORRUPT_DATA면 끝 :693-702
→ 새 pointer(current + rollback 목록) put
→ responses.matchActiveExact(url) :217-383
→ keys → pointer 읽기 ← 같은 검증 :246-254
→ admin.cleanupOwned() :761-844
→ pointer 읽기 ← 같은 검증 :783-789
pointer 검증 isActivePointer public-cache-codec.ts:430-469
→ rollback 목록 길이 ≤ 현재 retainedPreviousReleaseCount :455-456
→ releaseRegistryId가 현재 정책에서 허용 :441, :459-464
```
| 단계 | 내용 |
|---|---|
| 입력 | 빌드가 만든 manifest, composition이 준 정책 |
| 정책 | 검증한 후보만 활성화, 보존 집합은 pointer와 `retainedPreviousReleaseCount`로 계산(`browser-file-and-origin-storage.md:966-968`) |
| 상태 변화 | release cache 추가, control cache의 pointer 교체, 오래된 owned cache 삭제 |
| 외부 I/O | fetch, Cache API, Web Locks |
| 실패 | 정책을 바꾼 배포(E-2에서는 retained 3 → 1)나 pointer 손상 뒤에는 조회·활성화·정리·inspect가 모두 `CORRUPT_DATA`/`REHYDRATE`다. REHYDRATE를 따라 다시 stage·activate해도 activate가 같은 pointer에서 멈춘다 |
| 결과 | 오프라인 자산 캐시가 계속 꺼지고, 배포마다 release cache가 하나씩 쌓인다(E-2 `ownedCaches: 6`). 되돌리는 방법은 사용자가 사이트 데이터를 지우는 것뿐이다 → **02-01** |
### 2.3 변경·삭제 흐름
**변경 — cross-context kernel 예외를 없애는 작업(E-4 P2)**
```text
query-cache가 쓰는 타입 3개 멤버(publish·subscribe·close) + delivery 타입
→ src/contracts/cache-invalidation.ts에 13줄 추가
→ tanstack-cache-coordinator.ts:16-19 import 1곳 변경
→ .dependency-cruiser.json:250 pathNot에서 cross-context-invalidation/index.ts 삭제
→ check:architecture PASS · tsc app/test 0 errors · unit 30/30
```
바꾼 곳은 3파일이다. bootstrap이 넘기는 `BrowserCrossContextInvalidation`은 새 타입에 구조적으로 들어맞아 조립 코드는 그대로다. 문서는 `layers.md:47-49`와 규칙 주석 두 곳을 같이 고쳐야 한다 → **02-06**
**삭제 — browser-file-storage 런타임 제거 드릴(E-5)**
`scripts/test-browser-file-storage-runtime-removal.ts`는 browser-files·cache-storage·browser-transfer·storage/indexeddb·opfs와 포트를 fixture에서 지우고 게이트를 다시 돌린다(`:24-37`). cross-context-invalidation은 기본 조립이라 대상이 아니다.
세 번 돌렸다.
| 회차 | 결과 | 실패 내용 |
|---|---|---|
| 1 | test 단계 실패 | component 3개 시간 초과(`boot-unexpected-failure`, `runtime-application`, `router`). 당시 부하 평균 약 36(22코어) |
| 2 | test 단계 실패 | integration `provider-guardian-transaction` 1개 시간 초과. component는 211/211 통과 |
| 3 | **PASS** | `Browser file/storage runtime removal: PASS (7 base checks, 55 runtime-dependent tests removed by import graph)`. 55개에는 리뷰용 임시 테스트 1개가 들어 있다 |
- 타입 검사·lint·`check:architecture`·빌드·optional recipes·CI 계약은 세 번 모두 통과했다.
- 1·2회의 실패 테스트는 제거하지 않은 worktree에서 단독으로 다시 돌려 모두 통과했다. `runtime-application`과 `provider-guardian-transaction`은 FOLLOW-UP 3절의 알려진 부하 flaky다.
- 결론: 런타임 묶음은 지금 지울 수 있다. 다만 이 드릴의 test 단계도 부하 flaky 테스트를 그대로 물려받는다(영역 10·11 몫).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 근거와 잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | P | 목표 M2 / 확인 M2 | E2, E3 | lease 수·바이트 상한, preview의 같은 턴 abort(`object-url-lease.ts:292-295`), 캐시의 "검증 뒤에만 성공"은 코드와 테스트로 지켜진다(M01·M04 검출). 다만 pointer의 유효성을 **저장 당시가 아니라 현재 정책**으로 판단한다(`public-cache-codec.ts:441`, `:455-456`). 정책이 바뀌면 멀쩡한 pointer가 손상으로 분류된다(02-01) |
| 2 | 구조적 성숙도 | P | M3 / M3 | E3(E-4) | adapter 사이 import는 kernel만 쓴다. `check:architecture`가 이를 강제한다. kernel 예외는 쓰임(타입 2개)보다 넓어 런타임 팩토리까지 모든 adapter에 열린다(P1 통과, 02-06) |
| 3 | 변경 용이성 | O | M2 / M2 | E1, E3 | 새 파일 정책은 profile 추가, 새 topic은 registry 추가로 끝난다. 예외 제거 같은 구조 변경도 3파일이었다(E-4 P2) |
| 4 | 인지 부하 | P | — / — | E1 | 본 파일 2개가 1.1k줄대다(`download-delivery-adapter.ts` 1,157, `public-response-cache-adapter.ts` 1,185). 리뷰 ID 주석이 37곳이다. 대부분 이유 문장이 따라와 39.8절의 "ID만 있는 주석"은 아니다 |
| **5** | 위험 가시성 | P | M1~M2 / M1~M2 | E1, E3 | `BROWSER_HANDOFF`/`SAVED`/`DISMISSED`, `integrity: NOT_PROVIDED`, `retryable` 구분은 호출자가 읽을 수 있다. 그러나 pointer 실패의 `recovery: "REHYDRATE"`(`public-response-cache-adapter.ts:1016-1020`)는 존재하지 않는 복구 경로를 안내한다(02-01). `inspect()`는 모든 후보의 모든 바이트를 읽고 해시하는데 포트에 signal이 없고 문서는 cache 수 비례로만 적는다(`cache-storage-ports.ts:84`, `browser-file-and-origin-storage.md:974-977`, 02-02) |
| **6** | 실패 성숙도 | P | M2 / M2 | E2, E3 | 취소·닫기·권한·소진·무결성을 나누고 늦게 온 자원을 kernel race로 보상한다(`download-delivery-adapter.ts:601-609`, `:917-929`). pointer가 한번 읽히지 않으면 활성화·정리가 영구히 멈춘다(02-01, E-2). handoff가 실패했을 때 lease를 반환하는 규칙은 코드에 있지만 테스트가 없다(`:853-854`, M10 생존, 02-05) |
| 7 | 운영 성숙도 | P | M2 / M2 | E1 | cross-context 실패·저하는 bootstrap이 진단으로 연결한다(`runtime-adapters.ts:374-386`). file·cache observer는 recipe 조립 몫이라 repo에서는 연결되지 않는다 |
| 8 | 디버깅 가능성 | P | M2 / M2 | E1 | 관측에 파일명·URL·키가 없다. 저장 창 닫기와 handoff 성공이 이제 구분된다(M06 검출). 다만 pointer 손상과 marker 손상이 같은 `CORRUPT_DATA`·`CACHE_LOOKUP`으로 남아(`public-response-cache-adapter.ts:973-975`, `:1017-1019`) 02-01 상태를 관측만으로는 알아보기 어렵다 |
| 9 | 유지보수 성숙도 | P | M1 / M1 | E1 | 설계 문서의 줄 번호가 다시 밀렸다(FOLLOW-UP 02-09 유효, 02-03 수정에서 넣은 참조 3개도 1줄씩 밀림 → 02-04). CHANGELOG 영향 경로가 실제와 다르다(02-03) |
| 10 | 테스트 성숙도 | P | M3 / M3 | E2(146 통과), E3(브라우저 21 통과, 변이 19) | 지난 수정 규칙 12개는 모두 검출. 생존 5개: inspect의 판정 불가(M05, 02-02), handoff 실패 lease 반환(M10, 02-05), pointer 호환 규칙 2개(M13·M14, 02-01 완료 기준에 포함). M09(preview 단독 dispose)는 runtime 조립에서는 download dispose가 같은 registry를 비워 동등하다 |
| **11** | 데이터 성숙도 | P | M2 / M1 | E3(E-2) | Cache Storage에는 익명 공개 응답만 들어가 로그아웃 purge가 필요 없다(M08 검출). control 데이터(pointer)는 `schemaVersion: 1`만 있고, 정책이 달라진 배포에서 읽는 호환 규칙이 없다. 멈춘 동안 release cache가 계속 쌓여 origin 저장 한도를 쓴다(02-01). 소유 prefix를 바꾸는 배포는 옛 캐시를 정리하지 않는다(문서화된 제한, `browser-file-and-origin-storage.md:1004-1008`) |
| **12** | 동시성 성숙도 | O | M3 / M3 | E2, E3 | 탭 간 중복·역순·누락(M11 검출), 캐시 변경의 Web Lock 직렬화(실제 `navigator.locks`로 3엔진 통과), picker별 pending, 같은 턴 abort(M01 검출). stage 뒤 activate 전 cleanup이 후보를 지우는 창은 문서화된 허용이다(`browser-file-and-origin-storage.md` 8.3절) |
| 13 | 확장성 | O | M2 / M2 | E1 | source 256·dedupe 1,024 LRU(`browser-cross-context-invalidation.ts:160-166`), 정책 profile·entry·바이트 상한. 부하 측정은 없다(목표 없음) |
| 14 | 성능 성숙도 | P | M2 / M2 | E1, E2 | 조회 한 번은 `keys()` 1회·본문 복사 2회다(M07 검출). `inspect()`는 후보 수 × 최대 128 MiB를 읽고 해시하며 중간에 멈출 수 없다(02-02) |
| **15** | 보안 성숙도 | O | M2~M3 / M3 | E2, E3 | 익명 캐시 요청(M08), 파일명 무력화, 서명 기반 MIME, active content 금지, canonical handoff URL, 불투명 참조. 지난 02-08의 규칙별 테스트가 유지된다. wire event에 계정 scope가 없는 것은 설계상 선언(`client-cache-and-storage.md:99-101`)이라 결함으로 세지 않았다(7절 미검증) |
| 16 | 의존성 성숙도 | - | — | E1 | 세 폴더 모두 외부 패키지 import가 없다(`grep 'from "[^.]'` 0건) |
| 17 | API / Contract 성숙도 | P | M2 / M2 | E1 | 포트 타입과 wire 계약은 닫혀 있다. CHANGELOG 0.2.0 [계약] 행의 영향 경로·recipe·표현이 실제 변경과 다르다(02-03). `PublicCacheInspection.verified`에 뜻 설명이 없다(02-02) |
| 18 | 배포 성숙도 | P | M2 / M0(정책 변경 호환) | E3(E-2) | release별 cacheEpoch와 후보 stage/activate/보존은 있다. 정책 값을 바꾼 배포 하나가 이후 모든 배포의 캐시 활성화를 막는다(02-01) |
| 19 | 설정 성숙도 | P | M3 / M3 | E2 | 잘못된 상한·정책은 조립 시 TypeError다. 그러나 `retainedPreviousReleaseCount`(1~5, `public-cache-policy.ts:124-126`)를 줄이는 정상 설정 변경이 런타임을 멈춘다(02-01) |
| 20 | 개발자 경험 | > | — | — | 영역 14 |
| 21 | Guardrail 성숙도 | P | M3 / M3 | E3(E-4) | kernel 예외는 `check:architecture`가 강제한다. 예외 범위는 쓰임보다 넓다(02-06). 설계 문서 줄 번호는 어떤 검사도 보지 않는다(02-04) |
| 22 | 추상화 성숙도 | P | — / — | E1, E3 | 네이티브 API를 조립 시 bind·snapshot하는 facade와 공유 lease registry는 목적이 분명하다(4.2절). concrete transport 전체를 "kernel"로 부르는 것은 kernel의 뜻(공용 primitive)과 다르다(02-06) |
| 23 | 일관성 | P | — / — | E1 | 같은 `QUOTA_EXCEEDED`가 경로에 따라 recovery가 다르다. native 예외는 `READ_ONLY`(`result.ts:80-85`), `failureForCode`는 `ONLINE_ONLY`(`public-cache-codec.ts:592-598`)인데 후자는 쓰이지 않는 분기다. cache 관측과 file 관측의 bucket 어휘가 다르다(지난 라운드와 같음) |
| **24** | 네이밍 / 의미 | P | M2 / M2 | E1, E3 | `inspect().verified`는 이제 "모든 entry가 있고 맞다"를 뜻한다(M04 검출). 다만 읽지 못한 경우(UNKNOWN)도 `false`로 합쳐 "검증 실패"와 "판정 불가"가 같다(M05 생존, 02-02). `REHYDRATE`가 pointer 실패에서는 약속을 지킬 수 없다(02-01). preview가 자기 lease로 한도를 채운 경우에도 `retryable:true`라, 그때의 "재시도"는 다른 lease를 놓은 뒤에만 성공한다 |
| 25 | 조직 확장성 | - | — | — | 1인 관리. 팀 경계 검증 대상 없음 |
| 26 | Ownership | > | — | — | 영역 12. kernel 규칙 주석에 담당(frontend-platform)은 있고 재검토 조건은 없다(02-06에 적음) |
| 27 | 삭제 가능성 | O | M3 / M3 | E3(E-5) | 제거 드릴이 browser-files·cache-storage를 포함한 런타임 묶음을 지우고 게이트를 다시 통과한다(3회째 PASS, 2.3절). cross-context는 topic이 0개면 브라우저 기능을 조회하지 않는다(`browser-cross-context-host.ts:60-62`) |
| **28** | 회복 가능성 | X | 목표 M2 / 확인 M0(cache pointer) | E3(E-2) | cross-context는 GAP·재생성으로, browser-files는 dispose로 회복한다. cache-storage는 pointer가 한번 읽히지 않으면 어댑터 API로 회복할 수 없다(02-01). 범위는 opt-in cache-storage 한정이다 |
집계(적용 24개): O 5(3, 12, 13, 15, 27) · P 18 · X 1(28) · ? 0 · 적용 제외 2(16, 25) · 다른 영역 2(20, 26).
## 4. 설계 선택 설명 (41절)
### 4.1 Cache Storage control pointer를 현재 정책으로 엄격하게 읽는다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 활성 release를 가리키는 값이 손상돼도 검증 안 된 release를 서비스하지 않아야 한다. 동시에 다음 배포가 새 release를 활성화하고 오래된 캐시를 지울 수 있어야 한다 |
| 2. 지킬 성질 | (a) 검증한 후보만 활성화한다. (b) manifest와 다른 바이트를 돌려주지 않는다. (c) 읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다. (d) 나쁜 pointer 하나가 이후 배포를 영구히 막지 않는다 |
| 3. 현재 보장 | (a)·(b)·(c)는 보장한다: 활성화 전 전체 재검증(`public-response-cache-adapter.ts:672-691`), 조회마다 본문 SHA-256(`public-cache-response-validation.ts:87-96`), 보존 집합 계산(`:796-814`). (d)는 보장하지 않는다. `isActivePointer`가 정책에 묶인 조건을 읽기 시점에 검사하고(`public-cache-codec.ts:441`, `:455-464`), 네 연산이 모두 그 결과에서 멈춘다(E-1, E-2) |
| 4. 대안 | (가) 현상 유지 + "사이트 데이터 삭제" 안내. (나) `activateRelease`가 읽을 수 없는 이전 pointer를 "없음"으로 보고 새 pointer로 덮어쓴다(rollback 목록은 비움). (다) 읽을 때는 구조만 검사하고, 정책 조건(목록 길이, 허용 ID)은 쓸 때 적용한다. 쓰기 쪽은 이미 `slice(0, retained)`를 한다(`:703-716`). (라) control을 지우는 admin API를 추가한다 |
| 5. 비교 | (가) 코드 0줄. 운영자가 원인을 알 수 없고 캐시가 쌓인다. (나) 몇 줄. (a)~(c)를 잃지 않는다. 새 후보는 여전히 전체 재검증을 거친다. 잃는 것은 손상된 pointer의 rollback 목록뿐이고, 어차피 읽을 수 없던 값이다. (다) 두 줄 정도. 정책 변경은 해결하지만 JSON 손상은 해결하지 못한다. (라) 포트가 늘고 호출자가 언제 불러야 하는지 알아야 한다 |
| 6. 선택 | 확인한 조건(소비자 없음, SW drain 미구현)에서는 (나)+(다)가 가장 작다. 기존 규칙 (a)~(c)를 그대로 두고 (d)만 되찾는다. 현재 구현의 "fail-closed"는 무결성 쪽으로는 맞지만 진행성(d)을 대가로 치르고 있다 |
| 7. 재검토 조건 | Service Worker가 요청마다 이 조회를 쓰고, 구버전 탭이 drain될 때까지 rollback 캐시를 계속 서비스해야 하면(VD-15 drain 프로토콜) 덮어쓰기 뒤의 cleanup이 그 탭의 캐시를 지울 수 있다. 그때는 (라)나 drain을 아는 보존 규칙을 다시 비교한다 |
구분: 현재 동작은 코드와 E-1·E-2로 확인했다. 작성 의도 기록은 찾지 못했다. 설계 문서는 control JSON의 크기 상한과 schema 검증만 말하고 정책이 바뀐 뒤의 읽기는 다루지 않는다(`browser-file-and-origin-storage.md:968-973`). (나)·(다)의 비용은 리뷰어의 추정이고 구현하지 않았다.
### 4.2 object URL lease registry 하나를 preview와 download가 같이 쓴다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | blob URL은 revoke 전까지 Blob을 메모리에 붙잡는다. 탭 하나가 붙잡는 양에 상한이 필요하다 |
| 2. 지킬 성질 | 활성 URL 수·합계 바이트 ≤ 상한, lease마다 revoke 정확히 한 번, dispose는 전부 revoke |
| 3. 현재 보장 | registry 하나를 두 소비자에 넘긴다(`create-browser-file-runtime.ts:109-120`, `:151-168`). download lease는 handoff 뒤 30초 유지된다(`download-delivery-adapter.ts:149`, `:835-842`). 소진은 `retryable:true`, 단일 Blob 초과는 재시도 불가다(`object-url-lease.ts:53-71`). M02·M03 검출 |
| 4. 대안 | 소비자별 registry 분리, 한 registry 안의 소비자별 몫, grace 단축 |
| 5. 비교 | 분리하면 download 폭주가 preview를 막지 않지만, 같은 메모리 상한을 지키려면 상한을 나눠 설정해야 하고 합계 보호가 두 곳으로 갈라진다. 몫을 나누면 설정이 하나 는다. grace를 줄이면 느린 브라우저에서 handoff가 끊길 수 있다(Safari 미검증) |
| 6. 선택 | 보호할 성질이 "탭 전체 메모리"라서 한 예산이 가장 직접적인 표현이다. 02-04 수정으로 소진이 일시적이라는 신호도 호출자에게 간다. **현 상태 유지가 맞다** |
| 7. 재검토 조건 | 제품이 30초 안에 16개가 넘는 다운로드(일괄 내보내기)를 하거나, 관측에서 `PREVIEW`/`DOWNLOAD`의 `LIMIT_EXCEEDED`가 자주 보이면 몫 분리를 다시 비교한다 |
### 4.3 cross-context transport를 adapter kernel 예외로 공유한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | query-cache coordinator가 탭 간 hint를 보내고 받아야 한다. transport 생성과 수명은 bootstrap이 세대마다 맡는다(`runtime-adapters.ts:359-403`) |
| 2. 지킬 성질 | concrete adapter끼리 구현에 기대지 않는다. transport 인스턴스는 조립 쪽만 만든다 |
| 3. 현재 보장 | query-cache는 `import type`으로 타입 2개만 쓴다(`tanstack-cache-coordinator.ts:16-19`). 규칙은 barrel 전체를 모든 adapter에 연다(`.dependency-cruiser.json:241-251`, `layers.md:47-49`). 다른 adapter가 런타임 팩토리를 import해도 통과한다(E-4 P1) |
| 4. 대안 | (가) 현상 유지(12-07 때 소유자가 kernel 예외로 정함). (나) 3개 멤버 채널 타입과 delivery 타입을 `src/contracts/cache-invalidation.ts`로 옮기고 예외를 지운다. (다) 같은 타입을 `src/application/ports/`에 둔다 |
| 5. 비교 | (가) 비용 0. 예외가 쓰임보다 넓게 남고, 두 번째 adapter가 transport를 직접 만들 수 있다. (나) E-4 P2에서 13줄 추가·import 1곳·정규식 1곳으로 게이트와 타입 검사를 통과했다. 계약 타입 하나가 늘지만 bootstrap에서 TypeScript가 구조 일치를 검사한다. (다) (나)와 같지만 wire 계약과 떨어진다 |
| 6. 선택 | 현재 조건(소비자 1곳, 타입만 사용)에서는 (나)가 더 작고 경계가 좁다. 다만 kernel 분류는 소유자 결정이므로 **제안**으로 남긴다(02-06) |
| 7. 재검토 조건 | 두 번째 adapter(SW, realtime 등)가 런타임 transport 동작을 직접 써야 하면 (가)나 transport의 `platform/` 이동을 다시 비교한다 |
## 5. 발견 사항 (36.3)
### 02-01 Cache Storage pointer를 현재 정책으로 검증해, 정책을 바꾼 배포나 손상 뒤에는 조회·활성화·정리가 영구히 멈춘다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 28, 11, 18, 6, 19, 5, 24, 1 |
| 근거 | `isActivePointer`가 rollback 목록 길이를 **현재** `retainedPreviousReleaseCount`와 비교하고(`src/adapters/cache-storage/public-cache-codec.ts:455-456`), ID와 캐시 이름도 현재 정책으로 검사한다(`:441`, `:459-464`). 실패는 `CORRUPT_DATA`/`REHYDRATE`다(`public-response-cache-adapter.ts:1016-1020`). 조회(`:247-254`), 활성화(`:693-702`), 정리(`:783-789`), inspect(`:855-859`)가 모두 이 결과에서 멈춘다. control cache를 지우는 API는 없다(`cache-storage-ports.ts:59-85`). E-2: 실제 Chromium·Firefox·WebKit Cache API에서 retained 3으로 release 3개를 활성화한 뒤 retained 1 adapter로 바꾸면 조회 `CORRUPT_DATA`, 새 release 2개의 stage는 성공·activate는 `CORRUPT_DATA`, cleanup `CORRUPT_DATA`, owned cache 6개. E-1: pointer JSON이 잘려도 같은 결과 |
| 발생 조건 | (1) `retainedPreviousReleaseCount`를 줄이는 배포. 허용 범위 1~5의 정상 설정 변경이다(`public-cache-policy.ts:124-126`). (2) `isReleaseRegistryIdAllowed`를 좁히는 배포. (3) 디스크·브라우저 오류로 pointer가 손상 |
| 영향 | 그 origin의 오프라인 자산 캐시가 계속 꺼진다. 조회 실패는 네트워크로 떨어지므로 온라인 화면은 동작한다. cleanup이 막혀 배포마다 release cache(최대 128 MiB)가 쌓이고 origin 저장 한도를 IndexedDB·OPFS와 나눠 쓴다. 안내된 복구 `REHYDRATE`(`browser-file-and-origin-storage.md:1026` "quarantine/re-fetch")를 따라도 벗어날 수 없다. 사용자가 사이트 데이터를 지워야 한다 |
| 심각도·우선순위 | Medium · P2 — 사용자 데이터 손실은 없고 opt-in 런타임이다. 하지만 정상 설정 변경 하나로 들어가고, 되돌릴 수 없고, 저장 공간을 계속 쓴다. 제품 repo 2곳이 이 코드를 그대로 들고 있다 |
| 통제·증거 | 무결성 M2 / 진행성 M0 확인 · E3(E-2, 3엔진), E2(E-1). pointer 호환 규칙을 지키는 테스트는 없다(M13·M14 생존) |
| 확실성과 남은 가정 | 경로와 결과는 확정. 실제 제품에서 정책을 바꿀 빈도는 모른다. 저장 한도 도달 시 다른 저장소에 주는 영향은 측정하지 않았다 |
| 결정의 근거 | 4.1절. 무결성 fail-closed는 유지하고 진행성만 되찾는 선택이다 |
| 이해 비용 | 운영자는 관측에서 `CACHE_LOOKUP` `CORRUPT_DATA`만 본다. pointer 손상인지 marker 손상인지 구분하려면 Cache Storage를 직접 열어야 한다 |
| 최소 개선 방향 | (1) `activateRelease`에서 이전 pointer가 `CORRUPT_DATA`면 없음으로 보고 새 pointer로 덮어쓴다. 새 후보 재검증은 그대로 둔다. (2) `isActivePointer`에서 정책 의존 조건(목록 길이)을 빼고 쓰기 쪽 `slice`에 맡긴다 |
| 대안 비교 | 4.1절 (가)~(라) |
| 단순화의 보존 조건 | 검증하지 않은 후보를 활성화하지 않는다. 읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다. 조회는 manifest digest가 맞는 바이트만 돌려준다 |
| 비용·부작용 | 코드 몇 줄과 테스트 2~3개. 덮어쓴 뒤 cleanup이 구버전 탭이 쓰던 캐시를 지울 수 있다. 그 탭의 조회는 `STORAGE_EVICTED`로 네트워크로 떨어진다(안전한 방향) |
| 재검토 조건 | 4.1절 7 |
| 완료 기준 | E-1의 두 시나리오에서 다음 배포의 activate가 성공하고, 그 뒤 cleanup이 성공한다. 손상 pointer 상태에서도 검증 안 된 후보는 활성화되지 않는다 |
| 검증 방법 | E-1을 `tests/unit/public-response-cache-repair.test.ts`에 옮긴다. M13·M14 변이가 실패하는지 확인한다. 가능하면 E-2를 `public-cache-storage.spec.ts`에 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-02 `inspect()`의 비용·취소·판정 불가가 포트 계약에 드러나지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 5, 14, 24, 10 |
| 근거 | 지난 02-05 수정으로 `inspect()`가 owned 후보마다 모든 entry를 읽고 SHA-256을 계산한다(`public-response-cache-adapter.ts:864-891`, `verifyReleaseCandidate` `:1068-1118`). 포트는 signal을 받지 않는다(`cache-storage-ports.ts:84`, 호출부 `:883`에서 `undefined`). 문서는 비용을 "cache count"에 비례한다고만 적는다(`browser-file-and-origin-storage.md:974-977`). 읽기 오류(`UNKNOWN`)도 `verified: false`가 되어(`:888`) 없거나 틀린 후보(`REPAIRABLE`)와 같아진다. `unreadableOwnedCacheCount`는 marker 실패만 센다(`:872-874`). `UNKNOWN`을 `true`로 바꾼 변이가 테스트를 통과한다(M05) |
| 발생 조건 | 운영 도구나 조립 코드가 부팅·주기 작업에서 `inspect()`를 부른다. 또는 일시적인 Cache API 오류 중에 부른다 |
| 영향 | 후보 수 × 최대 128 MiB를 읽고 해시하는 동안 멈출 수 없다. 일시 오류가 난 멀쩡한 후보가 rollback 대상에서 빠진다(보수적 방향) |
| 심각도·우선순위 | Low · P3 — 소비자가 없고, 문서가 부팅 경로 연결을 금지한다. 잘못 판단해도 활성화는 다시 검증한다 |
| 통제·증거 | M1 · E1, E3(M05 생존) |
| 확실성과 남은 가정 | 코드로 확정. 실제 소요 시간은 측정하지 않았다 |
| 결정의 근거 | 적용 제외 — 이름이 약속하는 보장은 이미 맞췄고, 남은 것은 계약 설명과 취소 입력이라 대안 비교가 필요하지 않다 |
| 이해 비용 | 호출자는 구현을 읽어야 비용과 `false`의 뜻을 안다 |
| 최소 개선 방향 | `inspect({ signal })`를 받는다. `verified: boolean`을 `VERIFIED`·`INVALID`·`UNREADABLE` 세 값으로 바꾸거나, 판정 불가를 `unreadableOwnedCacheCount`에 넣는다. 포트 주석과 문서 974행에 "entry 바이트에 비례"를 적는다 |
| 비용·부작용 | 포트 타입 변경([계약]). 소비자는 repo 안에 없다 |
| 완료 기준 | 읽기 오류 후보가 "검증 실패"와 구분되어 보고되고, abort로 중간에 멈출 수 있다 |
| 검증 방법 | entry 읽기에서 던지는 가짜 cache로 `inspect()` 결과를 확인하는 테스트. M05 변이가 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-03 CHANGELOG 0.2.0의 browser-files [계약] 행이 실제 변경 경로·대상과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서 불일치) |
| 관련 관점 | 17, 9 (+30.4 업데이트 전파) |
| 근거 | `CHANGELOG.md:51`의 영향 경로는 `src/adapters/browser-file-storage/`, `src/adapters/cache-storage/`다. 이 행의 커밋이 실제로 바꾼 곳은 `src/adapters/browser-files/{object-url-lease,download-delivery-adapter,file-observer}.ts`, `src/application/ports/browser-file-storage/shared.ts`, cache-storage 3파일이다(`git show --name-only c9be8d6 d76653b 0b41cb3 55c0bf5 2cbf500`). `src/adapters/browser-file-storage/`는 이 행의 어느 커밋도 건드리지 않았다. 공개 포트 `BrowserDataObservation.outcome`에 `DISMISSED`가 추가됐는데(`shared.ts:99-100`) 경로에 없다. "닫은 선택 창은 `DISMISSED`"는 Result 변경처럼 읽히지만 Result는 원래 `DISMISSED`였고 바뀐 것은 관측 값이다. cache-storage는 service-worker-pwa recipe 소속인데(`frontend-capability-recipes.json:121-128`) 행은 "browser-files recipe를 쓰는 프로젝트만 해당"이라 적는다. README는 CHANGELOG가 "영향 경로를 적는다"고 약속한다(`README.md:317-320`) |
| 발생 조건 | 복사한 프로젝트가 README 절차대로 경로를 보고 가져올 수정을 고른다 |
| 영향 | browser-files 수정 3건과 포트 타입 변경을 놓칠 수 있다. 관측 소비자가 `outcome`을 전수 분기하면 새 값에서 실패한다. 이번 두 제품 repo는 전체 병합이라 영향을 받지 않았다(두 동기화 기록 확인) |
| 심각도·우선순위 | Low · P3 — 문서 한 행. 이번 소비자는 영향 없음 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 경로 대조로 확정 |
| 결정의 근거 | 적용 제외 — 기록 오류를 바로잡는 문제라 선택 비교가 필요하지 않다 |
| 이해 비용 | 소비자가 커밋을 하나씩 열어 봐야 실제 경로를 안다 |
| 최소 개선 방향 | 경로를 `src/adapters/browser-files/`, `src/adapters/cache-storage/`, `src/application/ports/browser-file-storage/shared.ts`로 고친다. "관측의 `outcome`에 `DISMISSED` 추가"로 쓰고, cache 부분은 service-worker-pwa recipe에 해당한다고 적는다 |
| 비용·부작용 | 문서 한 행 |
| 완료 기준 | 행의 경로가 행의 커밋이 바꾼 `src/` 경로를 모두 포함하고, 그 밖의 경로를 포함하지 않는다 |
| 검증 방법 | `git show --name-only <행의 커밋>`과 대조. 반복된다면 CHANGELOG 행의 경로와 커밋 변경 경로를 대조하는 검사를 검토한다(영역 14) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-04 이 영역 설계 문서의 줄 번호 참조가 다시 밀렸다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서 불일치) |
| 관련 관점 | 9, 21 |
| 근거 | FOLLOW-UP 02-09의 `client-cache-and-storage.md:94` → `server-state-scope-runtime.ts:148`은 아직 빈 줄을 가리킨다(실제 `activateNextGeneration` 호출은 `:154`). 02-03 수정(`c8e4794`)이 넣은 참조도 이후 커밋으로 1줄씩 밀렸다. `browser-file-and-origin-storage.md:368` `download-delivery-adapter.ts:385-391` → 실제 `:386-393`, `:370` `server-state-scope-runtime.ts:19` → 실제 `:20`, `:371` `runtime-adapters.ts:410-416` → 실제 `:411-417`. `client-cache-and-storage.md:79-81`은 브라우저 증거가 "Chromium/Firefox만"이라 적지만 WebKit도 통과한다(0.2절 21/21, `CHANGELOG.md:77`). 두 문서는 `verify:documentation` 대상이 아니다(`scripts/verify-documentation-readiness.ts:19-20`) |
| 발생 조건 | 참조된 파일 위쪽에 줄이 추가될 때마다 |
| 영향 | 문서를 따라간 사람이 엉뚱한 줄을 본다. 한 줄 차이라 오해는 작다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 대조로 확정 |
| 결정의 근거 | 적용 제외 — 문서 사실 오류 |
| 이해 비용 | 참조마다 주변을 다시 찾아야 한다 |
| 최소 개선 방향 | 줄 번호 대신 심볼 이름(`createBrowserFileRuntime`의 `dispose`, `ScopeResetParticipant`)으로 가리킨다. 줄 번호를 남긴다면 문서를 수정한 커밋을 함께 적는다. WebKit 문장을 고친다 |
| 비용·부작용 | 문서 몇 줄 |
| 완료 기준 | 두 문서의 `path:line` 참조가 현재 코드와 맞거나 심볼 참조로 바뀐다 |
| 검증 방법 | 참조 목록을 현재 코드와 대조 |
| 담당·기한·상태 | 미정 · 미정 · FOLLOW-UP 02-09 이어받음 |
### 02-05 bounded download에서 lease를 만든 뒤 handoff가 실패하면 lease를 돌려주는 규칙을 테스트가 고정하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(테스트 공백) |
| 관련 관점 | 10, 6, 14 |
| 근거 | `boundedObjectUrlHandoff`는 lease를 만든 뒤(`download-delivery-adapter.ts:827`) handoff가 던지거나 abort가 확인되면 catch에서 `lease?.release()`로 돌려준다(`:853-854`). 이 한 줄을 지운 변이가 download·runtime 테스트 28개를 모두 통과했다(M10). `createAnchorDownloadHost`는 `document.body.append`를 부르고(`:65`), 다운스트림은 host를 직접 넘길 수 있다(`:112`) |
| 발생 조건 | 리팩터링으로 그 줄이 빠진 뒤, host가 던진다(`body`가 없는 문서, 사용자 host의 오류) |
| 영향 | 실패마다 lease가 하나씩 남아 16번째부터 preview·download가 `LIMIT_EXCEEDED`가 된다. 지난 02-01과 같은 종류의 누수다 |
| 심각도·우선순위 | Low · P3 — 현재 코드는 맞다 |
| 통제·증거 | M2 · E3(변이 생존) |
| 확실성과 남은 가정 | 도달 경로는 host 예외뿐이다. lease 생성과 abort 검사 사이에는 await가 없다 |
| 결정의 근거 | 적용 제외 — 테스트 한 개를 더하는 문제 |
| 이해 비용 | 없음 |
| 최소 개선 방향 | `handoff`가 던지는 host로 `BOUNDED_OBJECT_URL` 전달을 부르고 `activeLeaseCount`가 0으로 돌아오는지 단언한다 |
| 비용·부작용 | 테스트 1개 |
| 완료 기준 | M10 변이가 실패한다 |
| 검증 방법 | 같은 변이 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-06 cross-context-invalidation kernel 예외가 실제 쓰임(타입 2개)보다 넓다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 2, 21, 22, 5, 26 |
| 근거 | adapter 간 예외는 `cross-context-invalidation/index.ts` 전체를 모든 adapter에 연다(`.dependency-cruiser.json:249-250`). 이 barrel은 런타임 팩토리 두 개도 내보낸다(`src/adapters/cross-context-invalidation/index.ts:1-24`). 지금 이 예외를 쓰는 곳은 query-cache의 `import type` 한 곳뿐이다(`tanstack-cache-coordinator.ts:16-19`, 쓰는 멤버는 `subscribe`·`publish`·`close` `:48`, `:195`, `:280`). E-4 P1: realtime에서 런타임 팩토리를 import해도 게이트가 통과한다. E-4 P2: 타입을 contracts로 옮기고 예외를 지워도 게이트·타입 검사·테스트가 통과한다. 규칙 주석에는 담당은 있고 재검토 조건이 없다(`.dependency-cruiser.json:242`). `layers.md:54-56`은 모든 예외 주석에 재검토 조건을 둔다고 적는다 |
| 발생 조건 | 두 번째 adapter가 transport를 직접 만들 때 |
| 영향 | 조립(bootstrap)이 아닌 곳에서 같은 채널 이름의 transport 인스턴스가 생길 수 있다. 세대 교체 때 닫히지 않는 인스턴스가 생긴다. 지금은 그런 코드가 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M3(규칙 강제) · E3(E-4) |
| 확실성과 남은 가정 | 12-07 때 소유자가 이것을 kernel 예외로 정했다(`docs/reviews/2026-09-25-maturity-review/12-guardrails-ci.md:177`). 그 결정의 근거 기록은 찾지 못했다 |
| 결정의 근거 | 4.3절. 확인한 사실: 타입만 쓴다. 기록된 의도: "Any adapter may import it"(`layers.md:47-49`). 리뷰어 추론: 런타임 공유를 의도했다는 요구는 현재 코드에 없다 |
| 이해 비용 | "kernel"이라는 말이 공용 primitive(`platform/`)와 concrete transport를 함께 가리켜, 새 공용 코드를 어디 둘지 판단이 흐려진다 |
| 최소 개선 방향 | E-4 P2와 같이 채널 타입을 `src/contracts/cache-invalidation.ts`로 옮기고 예외를 지운다. `layers.md:47-49`와 규칙 주석을 고친다. 유지하기로 하면 규칙 주석에 재검토 조건을 적는다 |
| 대안 비교 | 4.3절 (가)~(다) |
| 단순화의 보존 조건 | query-cache가 `subscribe`·`publish`·`close`와 delivery의 `ordering`·`transport`를 그대로 쓴다. bootstrap 조립 코드가 바뀌지 않는다. 세대마다 새 transport가 만들어지고 이전 것이 닫힌다 |
| 비용·부작용 | 3파일 + 문서 2곳. 계약 타입 하나가 는다 |
| 재검토 조건 | 4.3절 7 |
| 완료 기준 | `pathNot`에 `cross-context-invalidation/index.ts`가 없고, E-4 P1 같은 import가 `check:architecture`에서 실패한다. 또는 유지 결정과 재검토 조건이 규칙 주석에 있다 |
| 검증 방법 | `check:architecture`, `check:types`, `tests/unit/{tanstack-cache-coordinator,query-cache,cross-tab-invalidation}.test.ts`, P1 probe |
| 담당·기한·상태 | 결정 필요 · 승인자: 템플릿 소유자(frontend-platform) · 신규 |
## 6. FOLLOW-UP 재확인과 지난 발견 회귀 확인
### 6.1 FOLLOW-UP(2026-09-25 라운드)의 이 영역 항목
| FOLLOW-UP 항목 | 현재 상태 | 근거 |
|---|---|---|
| P3 02-09 — 문서 줄 번호 참조(`server-state-scope-runtime.ts:148`)가 `:154`로 밀림, `verify:documentation` 대상 아님 | **유효** | `client-cache-and-storage.md:94`가 아직 `:148`이다. 같은 종류의 drift가 3곳 더 생겼다 → 02-04 |
FOLLOW-UP의 다른 항목(예산, flaky 테스트, 06-08 `assets/` 등)은 이 영역 코드가 아니다.
### 6.2 지난 02 발견의 회귀 확인(E-3)
닫힌 발견은 회귀가 있을 때만 다시 적는다. 수정한 규칙에 변이를 넣어 현재 테스트가 잡는지 봤다.
| 변이 | 지난 ID | 결과 |
|---|---|---|
| M01 preview가 resolve 뒤 abort를 다시 보지 않음 | 02-01 | 검출 |
| M02 preview 소진을 재시도 불가로 | 02-04 | 검출 |
| M03 download 소진을 일반 한도 초과로 | 02-04 | 검출 |
| M04 `inspect().verified` 항상 `true` | 02-05 | 검출 |
| M05 `inspect()`의 판정 불가를 `true`로 | 02-05 | **생존** → 02-02 |
| M06 저장 창 닫기를 성공 관측으로 | 02-06 | 검출 |
| M07 조회당 `keys()` 2회 | 02-07 | 검출 |
| M08 stage 요청 `credentials: "include"` | 02-02 | 검출 |
| M09 preview 단독 dispose에서 lease 미반환 | — | 생존(runtime 조립에서는 download dispose가 같은 registry를 비워 동등) |
| M10 bounded download catch의 `lease?.release()` 삭제 | — | **생존** → 02-05 |
| M11 cross-tab STALE 검사 삭제 | 02-08(5) 인접 | 검출 |
| M12 `storageArea` 검사 삭제 | — | 검출 |
| M13 pointer 목록 길이 검사 삭제 | — | 생존(규칙을 고정하는 테스트 없음 → 02-01 완료 기준) |
| M14 activate가 이전 pointer 실패를 무시 | — | 생존(같은 이유 → 02-01) |
| M15 browser-managed handoff의 다른 origin 거부 삭제 | 02-08(1) | 검출 |
| M16 vault 누적 보관 바이트 상한 삭제 | 02-08(2) | 검출 |
| M17 preview Blob을 검증된 타입으로 다시 만들지 않음 | 02-08(3) | 검출 |
| M18 native picker의 user activation 검사 삭제 | 02-08(4) | 검출 |
| M19 처음 보는 source의 seq>1을 GAP으로 보지 않음 | 02-08(5) | 검출 |
02-03(dispose 안내)과 02-09(문서)는 문서 수정이다. 02-03 안내 문장은 코드와 맞지만 새로 넣은 줄 번호가 밀렸다(02-04).
## 7. 미검증 목록
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
|---|---|---|
| 다른 탭에서 계정이 바뀐 뒤 이 탭이 받은 무효화 hint가 이전 사용자 세대 캐시에 새 세션 응답을 채우는지 | 탭 간 세션 변경 감지는 auth 영역이고, 조립된 2탭 E2E가 없다(`client-cache-and-storage.md:79-80`도 없음을 인정) | 탭 A 로그아웃·B 로그인 → 탭 B mutation → 탭 A 상태를 보는 2탭 E2E |
| Safari에서 blob URL 30초 grace가 충분한지, runtime dispose 직후 handoff가 살아남는지 | 실제 다운로드 완료는 Playwright가 보지 않는다(이번 실행은 handoff까지) | WebKit 실기에서 큰 Blob 다운로드 후 revoke 시점 비교 |
| Chrome `showSaveFilePicker`가 확정 시 빈 파일을 먼저 만드는지 | 사용자 조작이 필요하다 | Chromium 실기 실험 |
| 02-01 상태에서 쌓인 캐시가 origin 한도에 닿을 때 IndexedDB·OPFS 쓰기에 주는 영향 | 한도까지 채우는 실험을 하지 않았다 | 작은 quota 프로필에서 release를 반복 stage하며 다른 저장소의 `QUOTA_EXCEEDED` 관찰 |
| `inspect()`의 실제 소요 시간(02-02) | 소비자가 없고 측정 목표가 없다 | 후보·entry 크기별 측정 |
| 이 영역의 관측이 실제 제품 telemetry로 이어지는지 | file·cache observer를 조립한 코드가 repo·제품 repo 어디에도 없다 | recipe를 조립한 제품에서 확인 |
@@ -0,0 +1,364 @@
# 03 — HTTP·서버 상태·인증·진단 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 판)
> 경로: `src/adapters/http/`, `src/adapters/browser-rpc/`, `src/adapters/query-cache/`, `src/adapters/auth/`, `src/adapters/diagnostics/`, `src/adapters/telemetry/`, 관련 포트와 테스트
> 깊게 본 관점: 5, 6, 8, 12, 15, 17, 22 · 추가로 읽은 절: 29.2, 29.3
> 영역 판정(35.8): **조건부 사용 가능.** 조회·인증 세대·자격증명 경계·전송 상한은 그대로 복제해도 된다. 결과 불명 쓰기 샘플은 03-01을 고치기 전까지 "처리 중" 409를 돌려주는 백엔드(짝 백엔드 템플릿의 기본값)와 함께 복제하지 않는다. API가 다른 origin이면 배포 전에 preflight를 확인한다(03-02).
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`. 미커밋은 리뷰 가이드 문서 2개뿐이고 코드는 커밋과 같다 |
| 목적과 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 인증 `demo`/`external`. 기본 설정의 API는 다른 origin이다(`config/runtime/production.json:3`) |
| 읽은 코드 | 영역 6개 폴더. 흐름 추적을 위해 `src/bootstrap/runtime-adapters.ts`, `src/presentation/adapters/query/application-query.ts`(mutation), `server-state-generation-provider.tsx`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx`, `src/contracts/{errors,external-contract-runtime,mutation-intent,query-keys}.ts`, `src/platform/telemetry/trace-context.ts`, reference feature(`contracts/`, `presentation/`) |
| 읽은 문서 | `CHANGELOG.md` 0.2.0 [계약] 행, `docs/architecture/backend-api-and-server-state-contract.md` §5·§6·16.1, `docs/operations/api-contract-and-server-state-recovery.md` 1·5.2·6.3절, `docs/architecture/starter-experience.md` 인증 절, `docs/architecture/decisions/VD-07-*.md`, `VD-04-*.md`, `docs/runbooks/FE-RB-003.md`, 지난 라운드 03 문서·README 11절·FOLLOW-UP |
| 다운스트림 증거(읽기만) | `../tech-log-frontend`·`../memento-frontend` 브랜치 `chore/template-sync-v0.2.0`의 동기화 기록, `config/runtime/*.json`, tech-log `bff-session-owner.ts`·계약 분류기. 짝 백엔드 `../clean-architecture-backend-template`·`../tech-log-backend`의 멱등·CORS 코드 |
| 실행한 테스트 | `node scripts/run-vitest.ts run` 영역 대상 34개 경로(unit 17, integration 11, component 5, `tests/features/reference-feature`) → **50 파일 / 569 테스트 통과** |
| flaky 재현 | `http-execution-v3-live-authority.test.ts` 단독 20회 순차(부하 8~11) → 20/20 통과. 12개 동시 × 4회(부하 19~30) → 48회 중 1회 실패. 원인은 03-05 |
| 격리 실험(worktree, 끝나고 삭제) | 변이 7개(아래 표). 결정적 재현 테스트 3개: 마감 창(03-05), 키 없는 재전송(03-03), 504 → 409 처리 중 → 재저장(03-01). 실험 파일은 scratchpad `review-2026-09-29/03/experiments/`에 남겼다 |
| 브라우저 실험 | Playwright 1.62, chromium·firefox·webkit. 다른 origin API가 `Access-Control-Allow-Headers`에서 `x-correlation-id`를 빼면 어떻게 되는지 확인(03-02) |
| 확인하지 못한 범위 | 두 제품의 실제 운영 CORS 값, 실제 백엔드와의 통합, 여러 탭, 앱 전체를 브라우저에 띄운 CORS 거절 화면, Browser RPC 실제 provider, 성능 측정. 7절에 이유를 적었다 |
| 이전 리뷰와 비교 | 지난 03-01~03-08은 닫혔다. 회귀는 찾지 못했다. 지난 결과는 증거로 쓰지 않았고 아래 판정은 이번 실행·읽기 결과다 |
변이 실험(관점 10):
| 변이 | 결과 |
|---|---|
| M1 결과 불명 뒤 같은 입력에도 새 intent 생성(`application-query.ts:537-543`) | 검출 — 4건(`application-mutation-admission`, `reference-page`, `reference-production-vertical`) |
| M2 `x-correlation-id` 요청 헤더 제거(`http-execution-v3.ts:819`) | 검출 — 1건(`http-execution-v3.test.ts` request correlation) |
| M3 바인딩이 서버 반사 id를 `requestId`로 넘기지 않음(`feature-http-binding.ts:309-312`) | 검출 — 5건 |
| M4 `SUBJECT_MISSING` 진단 제거(`server-state-scope-runtime.ts:114`) | 검출 — 3건 |
| M5 subject 없는 인증 상태를 "같은 identity"로 취급(닫힘 → 열림) | 검출 — 4건 |
| M6 UNKNOWN 동안 identity lease를 잡지 않음(`application-query.ts:605-608`) | **생존** — 569건 전부 통과(03-06) |
| M7 재전송 때 이전 UNKNOWN admission을 정리하지 않음(`application-query.ts:523-528`) | 검출 — 4건 |
## 1. 결론
- **조회·세대·자격증명 경계는 여전히 튼튼하다.** 변이 M2~M5·M7이 모두 검출됐고, 영역 테스트 569건이 통과한다.
- **같은 키 재전송(지난 03-01의 수정)이 "처리 중" 응답 하나로 풀린다(03-01, High).** 짝 백엔드 템플릿은 처리 중인 같은 키 요청에 `409 IDEMPOTENT_IN_FLIGHT`를 준다. reference 분류기는 모든 409를 `NOT_APPLIED`로 판정한다. 그러면 화면이 "충돌"로 바뀌고, 다음 저장은 새 키로 나간다. 격리 재현에서 키가 `[K, K, K′]`였다.
- **`x-correlation-id`는 교차 origin 배포의 숨은 전제다(03-02).** 백엔드가 헤더를 허용하지 않으면 V3 요청 전부가 "네트워크 오류"로 끝난다. 쓰기는 모두 "결과 불명"이 된다. 통제는 문서 3곳뿐이고, 두 다운스트림 동기화 기록은 이 항목을 백엔드 작업으로 올리지 않았다.
- **재전송이 키 없는 명령에도 열려 있다(03-03).** 결과 불명 쓰기에는 문의 식별자가 보이지 않는다(03-04).
- **`readSubject` 필수화는 안전하고 소음도 작다.** subject가 없으면 닫힘 방향으로 동작한다(M5 검출). 경고는 fence마다 1건이고 기본 sink가 없어 브라우저 메모리에만 남는다. 이행 절차는 CHANGELOG와 `starter-experience.md`에 있다. README 업데이트 절에는 따로 없다.
- **FOLLOW-UP 3절 live-authority 간헐 실패의 원인을 찾았다(03-05).** 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"로 바뀐다. 테스트가 실제 시간 5ms 마감을 써서 부하에서 이 창에 걸린다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — reference 목록 조회
```text
route search
-> useReferenceFeature / bindQuery(scope) use-reference-feature.ts:116-
-> FeatureHttpBinding -> contractOperations.execute runtime-adapters.ts:534-575
-> V3 execute http-execution-v3.ts:472-1090
정책: 인증 프로필 확인 651-657, scope 확인 660-662, 입력 검증 672-692,
자격증명 716-798, 헤더(+x-correlation-id) 802-826, 재시도 상한 828-832
외부 I/O: fetch 905-965, 상한 있는 본문 읽기 998-1026
실패: SAFE는 전송 실패·재시도 상태에서 최대 min(계약, 설정, 2)회 975-991, 1031-1056
-> observation 1건 590-620 -> diagnostics 1건, 실패면 api.request.failed 1건
runtime-adapters.ts:233-306
-> 세대별 QueryClient 캐시 server-state-generation-provider.tsx:43-45
```
- 상태 변화: 캐시만 바뀐다. TanStack 재시도는 꺼져 있어 재시도는 V3 한 곳이다.
- 결과: 로그아웃·계정 전환 중 도착한 응답은 세대 확인으로 버려진다(`http-execution-v3.ts:849-855`, `server-state-scope-runtime.ts:99-185`).
### 2.2 피해가 큰 흐름 — 결과 불명 쓰기와 같은 키 재전송
```text
폼 저장 use-app-form.ts:299-316
-> mutation.submit application-query.ts:409-674
입력 intern -> identity 428-430
같은 identity의 UNKNOWN admission 찾기 504-508
intent 생성(키 = randomUUID) 또는 재사용 537-543
-> V3 POST, Idempotency-Key http-execution-v3.ts:809-811
-> 504 / 마감 초과 -> MAYBE_APPLIED http-effect-certainty.ts:36-49
-> admission UNKNOWN + identity lease application-query.ts:601-613
-> 화면 "변경 결과를 확인할 수 없습니다"
[변경됨으로 확인] [같은 요청으로 다시 보내기] [목록을 새로 불러와 확인]
reference-resource-form-page.tsx:141-172
-> 재전송 -> 같은 intent -> 같은 키 application-query.ts:736-747
-> 백엔드 멱등 처리(재생) backend-api-and-server-state-contract.md §6
```
실패 가지:
- 재전송에 서버가 "처리 중" 409로 답한다 → `NOT_APPLIED` → 키 결합이 풀린다 → 다음 저장은 새 키(03-01).
- 키 없는 명령 → 키 없이 다시 실행(03-03).
- 세대 fence(로그아웃·계정 전환·subject 없는 owner의 재알림) → UNKNOWN admission 폐기(`application-query.ts:818-831`) → 새 키. 런북 6.3-7에 한계로 적혀 있다.
- CORS preflight 거절 → 모든 쓰기가 `MAYBE_APPLIED`(03-02).
- 어느 가지에서도 화면에 문의 식별자가 없다(03-04).
### 2.3 변경 흐름 — 다운스트림이 v0.2.0을 받는다
```text
외부 owner(__CA_FRONTEND_AUTH_OWNER__)
-> 메서드 8개 검사 runtime-adapters.ts:135-160
readSubject 없음 -> createUnavailableSessionAdapter -> integration-failed
external-session-adapter.ts:157-170
readSubject() === null (인증 상태)
-> identity null -> 알림마다 fence + SUBJECT_MISSING warn
server-state-scope-runtime.ts:99-115, 218-249
-> 메모리 diagnostics(기본 sink 없음) runtime-adapters.ts:322
백엔드 쪽 [계약]: x-correlation-id CORS 허용(03-02), 같은 키 재생(U-5, 03-01)
```
- tech-log: owner가 상태가 바뀔 때만 알린다(`bff-session-owner.ts:48-52`, `readSubject: () => null` 127행). 로그인·로그아웃은 원래도 fence가 일어나므로 추가 비용은 없다. 경고는 로그인마다 1건이다.
- memento: 외부 owner가 없다. `AUTH_MODE=external` 운영 설정은 이전부터 `integration-failed`이고 이번 변경으로 달라지지 않았다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 이유·근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | P | effect 확실성 lattice(`http-effect-certainty.ts:36-73`)와 intent 검증(`http-execution-v3.ts:378-436`)은 일관된다. 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 요청 계약 위반이 된다(03-05) |
| 2 | 구조적 성숙도 | > | 경계 검사는 12 영역. 오케스트레이터 `check:architecture` PASS |
| 3 | 변경 용이성 | P | 명령 추가는 계약 + 바인딩으로 끝난다. 새 명령이 키 없는 명령이어도 재전송 연결이 그대로 동작한다(03-03) |
| 4 | 인지 부하 | P | V3 `execute()`가 한 함수 약 620줄(`http-execution-v3.ts:472-1090`)이지만 39.7 기준으로 한 곳에 둘 이유가 있다. 결과 불명 쓰기 규칙은 분류기·mutation 코디네이터·폼·폼 페이지·AsyncSurface 다섯 곳에 나뉘어, 409 한 줄이 키 보호를 푼다는 사실을 한 곳에서 알 수 없다(03-01) |
| **5** | 위험 가시성 | P | 결과 union이 실패 종류와 effect를 타입으로 드러낸다(`http-execution-v3.ts:126-182`). 재전송이 안전한 조건(키가 있음)은 훅 계약에 없다(`application-query.ts:229-234`, 03-03). 교차 origin CORS 전제는 설정·코드에서 보이지 않는다(03-02) |
| **6** | 실패 성숙도 | P | 마감 하나, 재시도 권한 하나, `MAYBE_APPLIED` 자동 재전송 금지가 유지된다(M1·M7 검출). 504 뒤 같은 키 재전송은 E2(`reference-production-vertical.test.tsx:123-167`). "처리 중" 409 뒤 키 보호가 풀린다(03-01, 재현). 키 없는 명령도 재전송된다(03-03) |
| 7 | 운영 성숙도 | P | 텔레메트리 라벨은 닫혀 있고 build/release가 찍히며(`telemetry-collector.ts:91-94`) 본문은 60KiB 아래로 나뉜다(58-84). diagnostics는 기본 sink가 없어(`runtime-adapters.ts:322`) `SUBJECT_MISSING`·`correlation_id`가 운영자에게 가지 않는다. FE-RB-003이 CORS를 원인 후보로 두지 않는다(03-02) |
| **8** | 디버깅 가능성 | P | 요청마다 `x-correlation-id`를 보내고(`http-execution-v3.ts:817-826`, M2 검출) 서버 반사값을 `requestId`로 싣는다(`feature-http-binding.ts:297-318`, M3 검출). 결과 불명 쓰기에는 문의 식별자가 없다(03-04). CORS 거절은 JS에서 일반 네트워크 오류와 구분되지 않는다(E3, 03-02). 마감 창 오분류(03-05) |
| 9 | 유지보수 성숙도 | P | 런북 상태표가 코드 위치를 가리킨다(`api-contract-and-server-state-recovery.md:20-35`). 백엔드 계약 §5의 허용 헤더 목록이 코드의 `TRANSPORT_OWNED_HEADERS`(`http-contract-bridge.ts:114-122`)와 따로 관리되고 `traceparent`가 빠져 있다(03-02) |
| 10 | 테스트 성숙도 | P | 대상 569건 통과. 변이 7개 중 6개 검출, 1개 생존(03-06). live-authority 파일은 부하에서 1/48 실패(03-05). "처리 중" 응답, 키 없는 재전송, 엄격한 CORS를 다루는 테스트가 없다 |
| 11 | 데이터 성숙도 | - | 이 영역은 영속 데이터를 쓰지 않는다. 메모리 캐시와 intent만 있다. cursor·conditional runtime은 설치된 operation이 쓰지 않는다(런북 상태표 31-32행) |
| **12** | 동시성 성숙도 | P | 세대 fence가 늦은 응답을 버린다(scope-fence 테스트 통과, M5 검출). 같은 세대에서 같은 입력은 같은 intent다. 첫 요청이 아직 처리 중일 때 같은 키 재전송이 `NOT_APPLIED`로 닫혀, 다음 저장이 다른 작업으로 식별된다(03-01). 새로고침·로그아웃·다른 탭은 새 키다(런북 6.3-7에 적힌 한계) |
| 13 | 확장성 | > | extreme-scale은 11 영역 |
| 14 | 성능 성숙도 | O | 본문·JSON 구조·재시도·텔레메트리 배치 상한이 계약값이고 해당 테스트가 통과한다(E1·E2). 이번 라운드에 부하 측정은 하지 않았다 |
| **15** | 보안 성숙도 | O | 자격증명 헤더는 프로필이 정한다(`http-contract-bridge.ts:58-106`). 요청은 `redirect:"error"`, `no-referrer`, `no-store`(`http-execution-v3.ts:905-916`). subject를 못 대면 닫힘 방향이다(`server-state-scope-runtime.ts:218-237`, M5 검출). 서버 반사 correlation 값은 문법 검사 뒤에만 쓴다(`http-execution-v3.ts:1618-1631`). 알림 없는 계정 전환은 owner 계약 밖이다 |
| 16 | 의존성 성숙도 | > | 13 영역 |
| **17** | API / Contract | P | 0.2.0 변경은 [계약] 행으로 알린다(`CHANGELOG.md:24-27`, `:43`). 공개 포트를 단계 없이 필수로 바꿨다(4절 B). "처리 중" 응답의 status·분류가 계약에 없다(03-01). `commandRecovery.mode`는 실행 코드가 여전히 읽지 않는다(03-03). 교차 origin CORS 요구는 문서 통제뿐이다(03-02) |
| 18 | 배포 성숙도 | > | 13 영역. 03-02는 배포 절차에도 걸린다 |
| 19 | 설정 성숙도 | P | `REQUEST_TIMEOUT_MS`는 상한으로만 쓴다(`http-execution-v3.ts:450-456`). 기본 설정의 API가 다른 origin인데 그에 따른 CORS 요구를 확인하는 설정·검사가 없다(03-02) |
| 20 | 개발자 경험 | > | 14 영역 |
| 21 | Guardrail 성숙도 | P | owner 메서드 누락은 시작 때 막힌다(`runtime-adapters.ts:135-160`). KEYED 명령은 recovery descriptor가 필수다(`external-contract-runtime.ts:492-494`). 재전송은 descriptor를 읽지 않고(03-03), CORS 전제는 검사하지 않는다(03-02) |
| **22** | 추상화 성숙도 | P | `FeatureHttpBinding`은 전송 정책을 숨기고 좁다. V3 실행기의 단일 조율부는 유지가 맞다(4절 판단). `useApplicationMutation`은 모든 명령에 `resendUnknownEffect`를 주면서 안전 조건을 내보내지 않는다(03-03). 분류기 추상화는 "처리 중"을 표현할 수 있지만(`MAYBE_APPLIED`) 샘플과 계약이 그렇게 쓰지 않는다(03-01) |
| 23 | 일관성 | O | 전송별 KEYED 재시도·`Retry-After`·timeout 의미가 한 표에 있다(`backend-api-and-server-state-contract.md:600-611`) |
| 24 | 네이밍 / 의미 | P | `resendUnknownEffect` 주석은 "keyed command carries the same key"(`application-query.ts:229-234`)인데 키 없는 명령에도 동작한다. `IDEMPOTENCY_REPLAY`라는 mode 이름과 달리 실행 경로가 mode를 보지 않는다(03-03) |
| 25 | 조직 확장성 | > | 14 영역 |
| 26 | Ownership | P | owner 책임(`starter-experience.md:48-76`)과 백엔드 CORS·멱등 책임(`backend-api-and-server-state-contract.md:251-300`)이 문서에 있다. 두 다운스트림 기록은 subject·같은 키는 백엔드 질문으로 올렸지만 CORS 헤더는 올리지 않았다(03-02) |
| 27 | 삭제 가능성 | > | 09·14 영역. 오케스트레이터 `test:sample-removal` PASS |
| 28 | 회복 가능성 | P | 결과 불명 쓰기는 같은 세대 안에서 같은 키로 복구된다(E2). "처리 중" 409 뒤와 새로고침·fence 뒤에는 새 키다(03-01, 런북 6.3-7) |
X(미충족)는 없다. 6·8·12·17·28은 지난 라운드의 결함이 닫혔지만 이번 라운드 발견 때문에 P다.
## 4. 설계 선택 설명 (41절)
`[사실]`은 코드·실행으로 확인한 것, `[기록]`은 커밋·문서에 적힌 의도, `[추론]`은 리뷰어의 해석이다.
### A. 모든 V3 요청에 `x-correlation-id`를 항상 붙인다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 사용자 문의 한 건을 서버 로그 한 건과 잇는다. `[기록]` 지난 03-03, `CHANGELOG.md:24` |
| 2. 지킬 성질 | 논리 실행당 id 하나, 재시도가 공유, telemetry에 넣지 않음, id 생성 실패가 요청을 막지 않음 |
| 3. 현재 보장 | `[사실]` `http-execution-v3.ts:817-826`(생성 실패는 삼킴), projector가 diagnostics에만 넣음(`runtime-adapters.ts:250-253`), M2·M3 검출. 짝 백엔드는 들어온 `X-Correlation-Id`를 MDC에 싣는다(`tech-log-backend .../RequestLoggingFilter.java:24-41`). 보장하지 않음: 교차 origin에서 백엔드 CORS 허용 |
| 4. 대안 | (a) 현 상태 + 문서 (b) 현 상태 + 배포 전 preflight 점검 (c) 설정·프로필 스위치로 끌 수 있게 (d) 같은 origin BFF를 기본으로 권장 |
| 5. 비교 | (a) 비용 0. 누락하면 전면 실패. (b) 명령 한 줄·런북 한 줄. 자동화하면 CI가 API에 닿아야 한다. (c) 설정 표면이 늘고, 끄면 03-03의 목적을 잃는다. 긴급 우회 수단은 된다. (d) 인프라 결정이라 템플릿 범위 밖 |
| 6. 현재 조건에서 | `[추론]` 헤더 자체는 유지가 맞다. bearer 프로필의 `Authorization`이 이미 preflight를 만들어서, 헤더 하나를 더 허용하는 비용이 작다. 빠진 것은 누락을 배포 전에 드러내는 수단이다(03-02의 최소안 = (b)의 문서판) |
| 7. 재검토 조건 | 같은 origin 배포가 기본이 될 때, 조직 표준이 `X-Request-Id`로 바뀔 때, preflight 없는 simple request가 필요한 성능 요구가 생길 때 |
### B. `readSubject`를 필수로 하고, subject가 없으면 알림마다 fence한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 같은 사용자의 토큰 갱신에는 캐시를 지키고, 계정 전환에는 반드시 비운다. `[기록]` `c6300e9` 커밋 메시지 |
| 2. 지킬 성질 | 이전 사용자의 서버 상태가 새 세션에 보이지 않는다(15). 같은 (상태, subject) 알림은 fence하지 않는다 |
| 3. 현재 보장 | `[사실]` 메서드 누락은 `integration-failed`(`runtime-adapters.ts:135-160`). 인증 상태에서 subject가 null·빈 값이면 identity를 null로 두고 매번 fence + 경고(`server-state-scope-runtime.ts:99-115`, `218-249`). M4·M5 검출. 보장하지 않음: owner가 알리지 않는 계정 전환(포트 계약 밖) |
| 4. 대안 | (a) 현재: 필수 메서드 (b) 선택 메서드, 없으면 null과 같게 처리 (c) 선택 → 경고 → 필수의 두 릴리스 이행 |
| 5. 비교 | (a) 이행을 빠뜨리면 인증 경로 전체가 닫힌다. 요란하지만 데이터는 안전하다. (b) 같은 안전성, 이행 비용 0. 대신 누락이 "갱신마다 캐시 삭제"라는 조용한 비용으로 남고, 경고는 메모리에만 있어 아무도 못 본다. (c) 안전하지만 두 릴리스에 걸친 관리 비용 |
| 6. 현재 조건에서 | `[사실]` 두 다운스트림은 이미 이행했다(tech-log는 `null` 반환, memento는 owner 없음). `[추론]` 되돌리면 또 하나의 계약 변경이 된다. **현 상태 유지.** subject 없는 경로는 닫힘 방향이라 안전하다. tech-log처럼 상태 변화 때만 알리는 owner에서는 추가 fence가 없고, 경고는 로그인마다 메모리에 1건이라 소음이 되지 않는다. 경고가 "원래도 일어날 fence"에도 찍힌다는 점은 문서 설명(`starter-experience.md:64-69`)과 일치한다 |
| 7. 재검토 조건 | 제품이 diagnostics sink를 붙여 경고가 운영 로그로 나갈 때(그때는 상태가 바뀐 fence에서는 경고를 생략하는 편이 신호가 선명하다). 다음에 공개 포트를 필수로 바꿀 때 (c)를 쓸지 정한다(FOLLOW-UP 2절) |
### C. 결과 불명 쓰기의 키를 세대 안 메모리에 두고, 사용자가 누를 때만 다시 보낸다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 응답을 잃은 쓰기를 다시 보낼 때 서버가 같은 작업으로 알아보게 한다. `[기록]` 지난 03-01, 런북 6.3-4 |
| 2. 지킬 성질 | 같은 논리 요청은 같은 키. 입력이 바뀌면 새 키. 자동 재전송 없음. 이전 세대의 intent는 새 세대로 넘기지 않음 |
| 3. 현재 보장 | `[사실]` `application-query.ts:502-545`, `601-613`, `736-747`. 504 → 재전송 E2(`reference-production-vertical.test.tsx:123-167`). M1·M7 검출, M6 생존. 보장하지 않음: 새로고침·fence·다른 탭(런북 6.3-7), "처리 중" 응답 뒤(03-01), 키 없는 명령(03-03) |
| 4. 대안 | (a) 현재 (b) intent를 sessionStorage에 두어 새로고침 뒤에도 유지 (c) 백오프 자동 재전송 (d) inspect operation으로 조회한 뒤 결정 |
| 5. 비교 | (b) 사용자 범위·만료·정리 비용이 생기고 다른 계정으로 새는 경로를 막아야 한다. (c) 사용자 모르게 반복되고 서버 멱등이 확인돼야 한다(U-5 미확인). (d) 백엔드 조회 엔드포인트가 필요하다 |
| 6. 현재 조건에서 | `[추론]` 백엔드 멱등 계약이 확인되지 않았고 조회 엔드포인트도 없다. (a)가 가장 작고 한계가 런북에 적혀 있다. 유지하되, 키 결합이 서버의 "처리 중" 답에 풀리지 않게 하는 보강이 필요하다(03-01) |
| 7. 재검토 조건 | 백엔드가 status·inspect 엔드포인트를 주면 (d). 새로고침 뒤 중복이 실제로 관측되면 (b) |
V3 `execute()`의 크기(약 620줄)는 39.7로 따로 봤다. 마감·재시도·취소·effect 누적이 한 요청의 같은 상태를 공유하고, 순서가 정확성에 영향을 준다. 순수 판정은 이미 `http-retry-lifecycle.ts`·`http-effect-certainty.ts`로 빠져 있다. 더 나누면 호출자가 순서를 외워야 하므로 **현 상태 유지**가 맞다. 03-05는 이 조율부 안의 분기 하나를 고치는 문제다.
## 5. 발견 사항 (36.3)
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 03-01 | High | P1 | 확인된 결함 | 6, 12, 17, 28, 5, 4 | 같은 키 재전송이 "처리 중" 409를 받으면 샘플 분류기가 `NOT_APPLIED`로 닫아 키 보호가 풀린다 |
| 03-02 | Medium | P2 | 구조적 위험 | 17, 19, 8, 6, 26, 21 | `x-correlation-id` CORS 허용이 교차 origin 배포의 전제인데 문서 통제뿐이다 |
| 03-03 | Medium | P2 | 구조적 위험 | 6, 5, 22, 24, 17, 21 | 결과 불명 재전송이 키 없는 명령에도 열려 있다 |
| 03-04 | Medium | P2 | 확인된 결함 | 8, 7, 6 | 결과 불명 쓰기에 문의 식별자가 없다 |
| 03-05 | Low | P2 | 확인된 결함 | 6, 8, 10, 1 | 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"이 된다 |
| 03-06 | Low | P3 | 개선 제안 | 10, 6 | UNKNOWN 동안 identity lease를 잡는 코드를 검증하는 테스트가 없다 |
### 03-01 같은 키 재전송이 "처리 중" 409를 받으면 샘플 분류기가 `NOT_APPLIED`로 닫아 키 보호가 풀린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 12, 17, 28, 5, 4 |
| 근거 | ① reference 생성 분류기는 모든 409를 `NOT_APPLIED`로 판정한다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:37-51`). ② 템플릿 백엔드 계약은 409를 "idempotency fingerprint, domain revision 또는 semantic conflict"로 쓰고(`docs/architecture/backend-api-and-server-state-contract.md:211`), 같은 키의 동시 재전송은 "bounded `IN_PROGRESS` 결과"라고만 적어 status를 정하지 않는다(`:298-300`). ③ 짝 백엔드 템플릿은 처리 중인 같은 키 요청에 `409 IDEMPOTENT_IN_FLIGHT`(retryable=false, "client polls")를 준다(`../clean-architecture-backend-template/src/shared-contract/.../OperationalError.java:47`, 같은 계열 `../tech-log-backend/.../GlobalExceptionHandler.java:190-198`). ④ 재전송을 시작할 때 이전 UNKNOWN admission을 먼저 정리한다(`src/presentation/adapters/query/application-query.ts:523-528`). 재전송 결과가 `NOT_APPLIED`면 새 admission도 정리하고 conflict를 켠다(`:583-589`). ⑤ 폼은 CONFLICT에서 결과 불명 기록을 지우고(`src/presentation/forms/use-app-form.ts:227-230`), 화면은 "충돌을 해결한 뒤 다시 제출할 수 있습니다."를 보이며 저장 버튼을 다시 연다(`reference-resource-form-page.tsx:53-54`, `:120-121`, `:175`). ⑥ 다시 저장하면 UNKNOWN admission이 없어 새 intent·새 키를 만든다(`application-query.ts:504-508`, `:537-543`). **재현(격리 worktree):** 수직 테스트 harness에 MSW로 504 → 409(`IDEMPOTENT_IN_FLIGHT`) → 201을 주고 저장 → 재전송 → 저장을 눌렀다. `Idempotency-Key`가 `[K, K, K′]`였고, 409 뒤 화면에 충돌 문구가 떴다(`review-2026-09-29/03/experiments/zz-review03-in-flight-409.test.tsx`). 다운스트림 tech-log의 분류기는 4xx 전체를 `NOT_APPLIED`로 판정한다(`tech-log-frontend` `src/features/tech-log/contracts/tech-log-studio-contract-contribution.ts:144-146`) |
| 발생 조건 | 첫 쓰기의 응답을 잃었는데(게이트웨이 504, 클라이언트 마감) 서버는 아직 처리 중이다. 사용자가 "같은 요청으로 다시 보내기"를 누르거나 같은 입력으로 다시 저장한다. 느린 서버 때문에 시간 초과가 난 경우라면 흔한 순서다 |
| 영향 | 화면이 "충돌"로 안내해 사용자가 다시 제출하게 한다. 그 제출은 새 키라 서버가 막지 못한다. 첫 요청이 끝나면 같은 리소스가 두 번 생긴다. 사용자는 마지막 성공만 본다. 지난 라운드 03-01(High)과 같은 피해다. 복제 범위는 샘플 분류기와 폼 흐름을 복사한 모든 KEYED 명령이다 |
| 심각도·우선순위 | High · P1 — 35.2의 "결과 불명 작업의 무방비 재실행"이다. 짝 백엔드의 기본 응답과 템플릿 샘플의 기본 판정만으로 생기는 경로다. 실제 중복 피해를 관측하지는 않아 P0는 아니다 |
| 통제·증거 | M1(런북 6.3-4 "UNKNOWN에 새 key 금지"). 코드 통제는 분류기 정확성에 달려 있다 · E2(격리 재현) + E1(백엔드 코드 읽기) |
| 확실성과 남은 가정 | 프론트 경로는 재현으로 확정했다. in-flight가 409라는 것은 짝 백엔드 코드로 확인했다(실행은 안 함). tech-log 제품 폼이 이 순서를 허용하는지는 실행하지 않았다(동기화 기록 372-378행은 "같은 입력 재시도가 원래 키"라고 적는다) |
| 결정의 근거 | `[사실]` 분류기는 기능 패키지 몫이고(`reference-feature-contract-contribution.ts:33-36` 주석), 플랫폼은 분류 결과를 그대로 믿는다. `[추론]` 03-01 수정 전에는 같은 키가 서버에 다시 가는 경로가 없어서 "409 → NOT_APPLIED"가 안전했다. 같은 키 재전송이 생기면서 409의 뜻이 하나 늘었고, 샘플·계약이 따라오지 않았다 |
| 이해 비용 | 명령을 추가하는 사람은 분류기 한 줄(409)과 mutation 코디네이터·폼의 정리 규칙을 함께 알아야 키가 유지되는지 판단할 수 있다. 이 관계를 적은 곳이 없다 |
| 최소 개선 방향 | ① 백엔드 계약 §6에 "처리 중" 응답을 409 + 코드(짝 백엔드와 같은 `IDEMPOTENT_IN_FLIGHT`)로 고정하고, 분류 규칙 "같은 키가 처리 중이면 `MAYBE_APPLIED`"를 적는다. ② reference 분류기가 그 코드를 `MAYBE_APPLIED`로 판정한다. ③ (플랫폼 방어) 같은 intent로 보낸 재전송이 `NOT_APPLIED`를 받아도 canonical 입력과 intent의 결합은 `APPLIED_CONFIRMED` 전까지 풀지 않는다 |
| 대안 비교 | ①+②만: 문서 한 절과 분류기 한 줄. 모든 패키지가 분류기를 맞게 써야 한다(tech-log는 이미 4xx 전체를 `NOT_APPLIED`로 쓴다). ①+②+③: 분류기가 틀려도 키가 유지된다. 대가로 같은 입력의 진짜 거절(예: 422)은 계속 같은 키로만 나가고, 사용자가 입력을 바꿔야 새 요청이 된다. 이는 "입력이 바뀌면 새 키" 규칙과 같다. 현상 유지는 지난 03-01의 피해를 다시 연다 |
| 단순화의 보존 조건 | 입력이 바뀌면 새 키. 자동 재전송 없음. fence 뒤 이전 세대 intent를 넘기지 않음. UNKNOWN head FIFO(`application-query.ts:855-865`) |
| 비용·부작용 | ③은 admission 수명이 길어진다(`MUTATION_COORDINATOR_BOUNDS.activeIntentsTotal` 안). in-flight일 때 화면 문구는 "충돌"이 아니라 "아직 처리 중"이어야 한다(08 영역과 겹침) |
| 재검토 조건 | 백엔드가 in-flight에 409가 아닌 status를 쓰거나, inspect 엔드포인트가 생기면 분류 대신 조회로 바꾼다 |
| 완료 기준 | 504 → 409(in-flight) → 다시 저장 순서에서 세 요청이 모두 같은 `Idempotency-Key`를 쓰고, 409 뒤 화면이 결과 불명 상태를 유지한다 |
| 검증 방법 | 재현 테스트를 `tests/features/reference-feature/`에 넣고 기대값을 `[K, K, K]`로 둔다. ③을 넣으면 분류기가 409를 `NOT_APPLIED`로 두어도 같은 결과인지 따로 단언한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 03-01의 수정(`dfb1b9e`)에서 생긴 새 경로. 지난 03-01 자체의 회귀는 아니다(504 → 재전송 테스트는 통과) |
### 03-02 `x-correlation-id` CORS 허용이 교차 origin 배포의 전제인데 문서 통제뿐이다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 19, 8, 6, 26, 21 |
| 근거 | V3는 모든 논리 실행에 `x-correlation-id`를 붙이고(`src/adapters/http/http-execution-v3.ts:817-826`) 끄는 설정이 없다(`runtime-adapters.ts:489-533`). 기본 설정의 API는 다른 origin이다(`config/runtime/production.json:3`, `local.json`은 `http://localhost:8080/`). 요구는 문서 세 곳에만 있다(`CHANGELOG.md:24`, `backend-api-and-server-state-contract.md:251-258`, `api-contract-and-server-state-recovery.md:184-191`). 백엔드 계약 목록에는 추적을 켠 실행이 보내는 `traceparent`(`http-contract-bridge.ts:114-122`, `http-execution-v3.ts:814-816`)가 없다. 네트워크 실패 런북 `docs/runbooks/FE-RB-003.md`는 CORS를 원인 후보로 적지 않는다. **브라우저 실험(3엔진):** Allow-Headers에서 이 헤더를 빼면 서버에는 OPTIONS만 오고 POST는 오지 않았다. JS는 원인 없는 TypeError만 받았다(chromium "Failed to fetch", firefox "NetworkError when attempting to fetch resource.", webkit "Load failed"). 원인은 개발자 도구 콘솔에만 나왔다. 헤더를 허용하면 POST가 id를 싣고 도착했다. V3는 fetch 거절을 전송 뒤(`DISPATCHED`)로 기록해(`http-execution-v3.ts:951-965`) 명령은 `MAYBE_APPLIED`(`http-effect-certainty.ts:36-49`), 조회는 재시도 뒤 `NETWORK_FAILURE`(`http-execution-v3.ts:975-995`) → "네트워크에 연결할 수 없습니다."(`src/presentation/i18n/catalog.ts:154`)가 된다. **다운스트림:** tech-log 동기화 기록은 "correlation ids"를 받은 변경 목록(59행)에만 적고, 제품 질문 5개(517-541행)에 CORS가 없다. memento 기록에는 언급이 없다. tech-log-backend의 운영 허용 헤더는 환경 변수라 repo에서 값을 알 수 없다(`application.yml:539`) |
| 발생 조건 | API가 다른 origin이고, 백엔드 CORS가 헤더를 목록으로 허용하면서 `x-correlation-id`를 빠뜨린다 |
| 영향 | 그 origin으로 가는 V3 요청이 전부 실패한다. 쓰기는 모두 "변경 결과를 확인할 수 없습니다"가 되고 재전송도 같은 이유로 실패한다. 서버가 쓰기를 받지 않으므로 데이터 피해는 없다(실험). 운영자는 `api.request.failed`의 `NETWORK_FAILURE` 급증만 본다. diagnostics의 `correlation_id`는 서버에 도착하지 않은 값이다 |
| 심각도·우선순위 | Medium · P2 — 전면 실패지만 첫 요청에서 바로 드러나고, 데이터 피해가 없고, 정적 프론트 롤백이나 백엔드 설정 한 줄로 복구된다. 다운스트림이 교차 origin으로 v0.2.0을 처음 배포하기 전에는 그 제품의 출시 전 확인 항목이다 |
| 통제·증거 | M1(문서 3곳) · E3(브라우저 3엔진) + E1(코드·다운스트림 기록) |
| 확실성과 남은 가정 | 기전은 실험으로 확정했다. 두 제품의 실제 운영 CORS 값은 확인하지 못했다 |
| 결정의 근거 | 4절 A. 헤더를 항상 보내는 선택은 유지할 근거가 있다. 빠진 것은 누락을 배포 전에 드러내는 수단이다 |
| 이해 비용 | 제품 배포 담당자가 CHANGELOG [계약] 행을 읽고 백엔드 팀에 전해야 한다. 보내는 헤더 목록은 코드(`TRANSPORT_OWNED_HEADERS` + 인증 프로필 헤더)와 문서에 따로 있다 |
| 최소 개선 방향 | ① FE-RB-003 첫 분류에 "배포 직후 모든 요청이 `NETWORK_FAILURE`면 브라우저 콘솔의 CORS 메시지와 preflight `Access-Control-Allow-Headers`를 본다"를 넣는다. ② README 업데이트 절이나 배포 절차에 실행 가능한 점검 한 줄을 둔다: `curl -si -X OPTIONS -H 'Origin: <앱 origin>' -H 'Access-Control-Request-Method: POST' -H 'Access-Control-Request-Headers: authorization,content-type,idempotency-key,x-correlation-id' <API_BASE_URL>api/...`. ③ 백엔드 계약 §5 목록에 `traceparent`(추적을 켠 경우)를 넣는다 |
| 대안 비교 | 4절 A 표. 설정 스위치는 설정 표면을 늘리고 끄면 문의 식별자를 잃는다. staging smoke 스크립트는 자동으로 잡지만 CI가 API에 닿아야 한다(U-4와 함께 할 때 추가). 최소안은 문서·절차만 바꾼다 |
| 단순화의 보존 조건 | 논리 실행당 id 하나, 재시도가 공유, telemetry에 넣지 않음, id 생성 실패가 요청을 막지 않음(`http-execution-v3.ts:819-825`) |
| 비용·부작용 | 문서 3곳 수정 |
| 재검토 조건 | 같은 origin BFF가 기본이 되거나, 조직 표준 헤더가 바뀌거나, preflight를 없애야 하는 성능 요구가 생기면 |
| 완료 기준 | 배포 절차에 preflight 점검이 있고, FE-RB-003이 CORS를 첫 후보로 안내하고, 백엔드 계약 목록이 코드가 보내는 헤더와 같다 |
| 검증 방법 | 문서 리뷰. 실험 스크립트(`review-2026-09-29/03/experiments/cors-preflight-exp.mjs`)의 거절·허용 서버에 ②의 명령을 보내 결과가 갈리는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 03-03 수정의 "비용·부작용"(CORS 허용 헤더 필요)이 실제 통제로 이어졌는지 본 항목 |
### 03-03 결과 불명 재전송이 키 없는 명령에도 열려 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 5, 22, 24, 17, 21 |
| 근거 | `resendUnknownEffect`는 head가 UNKNOWN이고 intent가 있는지만 본다(`src/presentation/adapters/query/application-query.ts:736-747`). `requiresIdempotencyKey`가 false면 intent에 키가 없다(`:537-543`). 계약은 NEVER 명령을 recovery descriptor 없이 허용한다(`src/contracts/external-contract-runtime.ts:476-494`). `commandRecovery.mode`는 설치 검사와 예제 화면 표시(`src/presentation/examples/platform-overview-page.tsx:272-274`) 외에 읽는 곳이 없다(grep). AsyncSurface는 핸들러만 주면 버튼을 보인다(`async-surface.tsx:201-206`). 문서는 재전송을 "같은 `Idempotency-Key`"로 설명하고(`api-contract-and-server-state-recovery.md:254-257`, `VD-04-native-form-facade.md:37-40`), FE-RB-003은 "never retry an unkeyed mutation"이라 적는다. **실험:** `requiresIdempotencyKey: false`인 bound mutation에서 `MAYBE_APPLIED` 뒤 `resendUnknownEffect()`가 execute를 한 번 더 불렀고, 두 번째 intent에도 키가 없었다(`review-2026-09-29/03/experiments/zz-review03-keyless-resend.test.tsx`) |
| 발생 조건 | 다운스트림이 NEVER(키 없음) 또는 INSPECT_OPERATION 명령의 폼에 reference 폼처럼 `onResendUnknownEffect`를 연결한다 |
| 영향 | 응답을 잃은 키 없는 쓰기가 다시 실행된다. 첫 요청이 적용됐다면 중복 부작용이 생긴다. 템플릿의 유일한 쓰기 샘플은 KEYED라 지금은 해당 없다. tech-log에는 NEVER 명령이 있지만(`tech-log-management-contract-contribution.ts:143`) 재전송 버튼을 연결하지 않았다 |
| 심각도·우선순위 | Medium · P2 — 피해는 중복 쓰기지만 템플릿과 두 다운스트림에 도달 경로가 아직 없다. 폼을 한 번 복사하면 생긴다 |
| 통제·증거 | M1(런북·FE-RB-003 문장) / 훅 수준 M0 · E2(격리 실험) |
| 확실성과 남은 가정 | 훅 동작은 실험으로 확정. 다운스트림 도달은 없다 |
| 결정의 근거 | 적용 제외 — "키 없는 명령은 재전송하지 않는다"는 규칙이 이미 런북에 있다. mode까지 반영할지만 아래에서 비교한다 |
| 이해 비용 | 기능 작성자는 계약의 `retrySemantics`와 화면의 버튼 연결을 스스로 맞춰야 한다 |
| 최소 개선 방향 | head intent에 `idempotencyKey`가 없으면 `resendUnknownEffect`가 `null`을 돌려주고, 컨트롤러가 `canResendUnknownEffect`를 내보내 AsyncSurface가 버튼을 숨긴다 |
| 대안 비교 | 키 유무만 본다: 조건 1개와 플래그 1개. INSPECT 모드는 가리지 못한다. mode를 bound mutation에 싣는다: 바인딩 경로가 늘지만 INSPECT 명령을 조회로 보낼 자리가 생긴다. INSPECT 구현이 아직 없으므로 키 유무 검사로 충분하다 |
| 단순화의 보존 조건 | KEYED 재전송은 같은 키(기존 테스트 4건) |
| 비용·부작용 | 공개 컨트롤러 필드 1개 |
| 재검토 조건 | INSPECT_OPERATION 구현이 생기면 mode 기반으로 바꾼다 |
| 완료 기준 | 키 없는 UNKNOWN head에서 `resendUnknownEffect`가 `null`이고 버튼이 없다. KEYED 재전송 테스트는 그대로 통과한다 |
| 검증 방법 | 실험 테스트의 기대를 "execute 1회"로 바꿔 넣는다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 03-01의 "선언된 descriptor를 실행 코드가 읽지 않는다"가 mode에 대해서는 여전히 사실이다 |
### 03-04 결과 불명 쓰기에 문의 식별자가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 7, 6 |
| 근거 | 바인딩은 서버가 돌려준 `x-correlation-id`만 `requestId`로 싣는다(`src/adapters/http/feature-http-binding.ts:297-318`). `TRANSPORT_FAILURE`·`CANCELLED`에는 metadata가 없어 `requestId`가 비어 있다(`:407-416`). 실행기는 보낸 id를 알지만(`http-execution-v3.ts:589`, `826`) observation에만 넣고(`:597`, `613`), observation은 기본 sink가 없는 메모리 diagnostics로 간다(`runtime-adapters.ts:243-255`, `322`). 결과 불명 화면은 문의 식별자를 그리지 않는다(`src/presentation/components/async-surface.tsx:172-208`. 종료 오류는 `146-165`에서 그린다). 폼의 `MAYBE_APPLIED` 분기도 실패를 넘기지 않는다(`use-app-form.ts:221-224`). 교차 origin에서는 반사값도 `Access-Control-Expose-Headers`가 있어야 읽힌다(`backend-api-and-server-state-contract.md:256-257`) |
| 발생 조건 | 쓰기가 `MAYBE_APPLIED`로 끝난다: 클라이언트 마감, 연결 끊김, 반사 헤더 없는 504 |
| 영향 | 사용자가 "저장됐는지" 물을 때 줄 식별자가 없다. 요청에는 id가 실려 서버 로그에 있는데도 지원 담당은 시각·사용자로 찾아야 한다. 결과 불명 쓰기는 문의가 가장 필요한 경우다 |
| 심각도·우선순위 | Medium · P2 — 35.2의 "주요 진단 정보 부족". FOLLOW-UP 4절 03-03 행(P3)의 범위를 넓혀 올린다. 반사 헤더가 없을 때만이 아니라, 보낸 id를 알고 있는 전송 실패와 결과 불명 화면 전체가 해당된다 |
| 통제·증거 | M2(반사값 경로, M3 검출) / M0(전송 실패, 결과 불명 화면) · E1 |
| 확실성과 남은 가정 | 경로는 확정. 게이트웨이가 504에 id를 반사하는지는 배포마다 다르다 |
| 결정의 근거 | 적용 제외 — 이미 정한 계약(문의 식별자 → 서버 기록)을 빠진 경로에 적용하는 문제다 |
| 이해 비용 | 운영자는 어느 실패에 식별자가 붙고 어느 실패에 안 붙는지 코드를 읽어야 안다 |
| 최소 개선 방향 | ① 실행 결과에 보낸 요청 id를 싣고(metadata 없는 결과에 선택 필드), 반사값이 없으면 바인딩이 그 값을 `requestId`로 쓴다. ② 결과 불명 상태가 실패의 `requestId`를 들고 있다가 AsyncSurface indicator 분기에서 `template.supportReference`로 보인다(08 영역과 겹침) |
| 대안 비교 | 적용 제외 — 기존 계약을 따르는 단순 보강이다 |
| 단순화의 보존 조건 | telemetry에는 id를 넣지 않는다(VD-07 5-1) |
| 비용·부작용 | 공개 결과 타입에 선택 필드 1개. 서버가 id를 바꿔 쓰면 두 값이 다를 수 있어 문구는 "요청 ID"로 둔다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 마감 초과 쓰기에서 화면의 식별자가 요청에 보낸 `x-correlation-id`와 같다 |
| 검증 방법 | 수직 테스트: MSW가 응답을 마감보다 늦게 준다 → 화면 식별자 = 요청 헤더 값 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | FOLLOW-UP 4절 03-03 행의 확대 |
### 03-05 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"이 된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 8, 10, 1 |
| 근거 | 시도마다 `budget = remaining()`을 확인한 뒤(`src/adapters/http/http-execution-v3.ts:884-890`) 같은 동기 구간에서 `checkFinalInvariants`가 `remaining()`을 다시 읽는다(`:918-928`). 두 번째 값이 0 이하면 `DEADLINE_EXPIRED`다(`http-contract-bridge.ts:407`). 실행기는 `SCOPE_FENCED`가 아닌 실패를 모두 `FINAL_REQUEST_INVARIANT_FAILED`로 바꾼다(`http-execution-v3.ts:929-941`). 바인딩은 이를 `VALIDATION_REJECTED`(재시도 불가, 행동 없음)로 바꾼다(`feature-http-binding.ts:468-471`, `src/contracts/errors.ts:77`). 화면 문구는 "서버가 입력값을 받아들이지 않았습니다."다(`catalog.ts:185`). **결정적 재현:** 시계를 두 읽기 사이에서 마감 뒤로 옮기면 fetch 0회, 결과 `CONTRACT_VIOLATION`/`FINAL_REQUEST_INVARIANT_FAILED`(`review-2026-09-29/03/experiments/zz-review03-deadline-window.test.ts`). **부하 재현:** `tests/integration/http-execution-v3-live-authority.test.ts`를 12개 동시 × 4회(부하 평균 19~30) 돌리자 1회 실패했다. 실패한 테스트는 "observes a late native rejection"(`:563-604`)이고 메시지는 `expected 'CONTRACT_VIOLATION' to be 'TRANSPORT_FAILURE'`다. 이 테스트는 실제 시간 5ms 마감을 쓴다 |
| 발생 조건 | 남은 시간이 두 동기 읽기 사이에 0이 된다. lease 대기나 백오프가 마감 직전에 끝나거나 메인 스레드가 멈출 때다. 드물다 |
| 영향 | 시간 초과가 "입력 거절"로 보이고 다시 시도 버튼이 없다. `api.request.failed`의 `error_kind`가 `FINAL_REQUEST_INVARIANT_FAILED`가 되어 운영자는 클라이언트 결함으로 읽는다. CI를 켜면 테스트가 무작위로 실패한다(FOLLOW-UP 3절) |
| 심각도·우선순위 | Low · P2 — 창이 좁고 데이터 피해가 없다. 수정이 분기 하나이고 CI 활성화(U-1)를 막는 flaky의 원인이라 P2로 둔다 |
| 통제·증거 | M2 · E2(결정적 재현) + E3(부하 재현) |
| 확실성과 남은 가정 | 확정. 실제 사용자 환경의 발생 빈도는 모른다 |
| 결정의 근거 | 적용 제외 — 분류 누락이다 |
| 이해 비용 | 운영자가 `FINAL_REQUEST_INVARIANT_FAILED`를 보면 요청 조립 결함을 찾아 코드를 읽게 된다 |
| 최소 개선 방향 | `checkFinalInvariants`의 `DEADLINE_EXPIRED`를 `SCOPE_FENCED`처럼 따로 받아 `abandonedTransportFailure("TIMEOUT")`로 끝낸다. live-authority의 실제 시간 5~20ms 마감 테스트는 `monotonicNow`·`sleep` 주입으로 바꾼다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 다른 불변식 실패는 그대로 `FINAL_REQUEST_INVARIANT_FAILED` |
| 비용·부작용 | 분기 1개, 테스트 수정 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 두 읽기 사이 마감 경과가 `TRANSPORT_FAILURE`/`TIMEOUT`이다. live-authority 파일이 같은 부하 실행에서 실패 0이다 |
| 검증 방법 | 결정적 재현 테스트를 넣는다. 12개 동시 × 4회 부하 실행을 반복한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | FOLLOW-UP 3절 "재현 조건을 찾는다"의 답 |
### 03-06 UNKNOWN 동안 identity lease를 잡는 코드를 검증하는 테스트가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 10, 6 |
| 근거 | 결과 불명이 되면 입력 identity lease를 잡는다(`src/presentation/adapters/query/application-query.ts:601-608`). 이 코드를 지워도 영역 테스트 569건이 모두 통과했다(변이 M6). lease가 없으면 행의 참조 수가 0이 되고, 등록부가 4,096개·4MiB를 넘을 때 오래된 행부터 지워진다(`src/contracts/query-keys.ts:198-232`). 그 뒤 같은 입력은 새 token → 새 intent·새 키가 된다(`application-query.ts:428-430`, `504-508`) |
| 발생 조건 | 결과 불명 쓰기 뒤 같은 세대에서 4,096개가 넘는 다른 입력이 intern된다(긴 세션, 많은 필터 조합) |
| 영향 | 지금은 코드가 막는다. 이 줄이 사라져도 테스트가 잡지 못한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2(구현) / 검출 없음 · E2(변이 생존) |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 적용 제외 — 테스트 추가 문제다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | `maxEntries`가 작은 등록부로 scope를 만들고, UNKNOWN 뒤 다른 입력으로 등록부를 채운 다음 같은 입력 저장이 같은 키인지 단언하는 컴포넌트 테스트 1건 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 1건 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 변이 M6이 그 테스트로 검출된다 |
| 검증 방법 | 변이 M6 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| 2절 P2 `readSubject` 필수화 — README 업데이트 절에 이행 절차 한 줄, 단계 정책 결정 | **유효(일부 해소)** | 이행 절차는 `docs/architecture/starter-experience.md:72-76`과 `CHANGELOG.md:43`에 있다. README 업데이트 절(`README.md:330-346`)은 "[계약] 행이 요구하는 백엔드·배포 변경을 적용한다"는 일반 규칙만 있고 이 한 줄은 없다. "선택 → 경고 → 필수" 단계 정책은 결정 기록이 없다. 두 다운스트림은 이행을 마쳤다(4절 B) |
| 3절 P2 `http-execution-v3-live-authority` 간헐 실패 | **유효 — 원인 확인** | 03-05. 부하에서 1/48 재현, 결정적 재현 성공. 제품 코드의 분류 누락과 실제 시간 5ms 마감 테스트가 겹친 결과다 |
| 4절 P3 03-03 "서버가 correlation 헤더를 돌려주지 않으면 `requestId`가 비어 있다" | **유효 — 범위를 넓혀 03-04로 올림** | `feature-http-binding.ts:297-318`, `async-surface.tsx:172-208` |
| 6절 U-5 백엔드 멱등 키 계약 | **판단 불가(사용자 몫)** | 짝 백엔드 코드에서 재생, 본문 불일치 422, 처리 중 409를 읽었다(실행 안 함). 템플릿 문서는 불일치를 409로 적는다(`backend-api-and-server-state-contract.md:298`). 처리 중 409는 03-01로 이어진다 |
이 영역에 해당하는 나머지 FOLLOW-UP 항목은 없다(07-03은 07 영역, 06-05·06-08은 06 영역).
## 7. 미검증 목록
| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 두 제품의 운영 CORS 허용 헤더 | tech-log-backend는 환경 변수(`APP_SECURITY_CORS_ALLOWED_HEADERS`)라 값이 repo에 없다. memento 백엔드는 README만 있다 | 배포 환경 설정 또는 staging에 대한 preflight 요청 |
| 03-01이 tech-log 운영 폼에서 실제로 일어나는지 | 제품 repo는 읽기만 했고 제품 테스트를 돌리지 않았다 | tech-log 브랜치에서 504 → 409 → 재저장 시나리오 테스트 |
| 백엔드 멱등 계약 전체(U-5) | 짝 백엔드는 코드만 읽었다. 보관 기간·동시 재전송 처리를 실행하지 않았다 | 백엔드 통합 환경 |
| 앱 전체를 브라우저에 띄운 상태의 CORS 거절 화면 | 실험은 fetch 수준만 했다. 화면 문구는 코드로만 확인했다 | 교차 origin 실제 서버를 둔 e2e(현재 e2e는 `page.route`로 API를 가로챈다) |
| 여러 탭의 결과 불명 쓰기 | intent가 탭 메모리에만 있다는 것은 코드로 확인했다. 두 탭 시나리오는 돌리지 않았다 | 두 컨텍스트 e2e |
| Browser RPC 실제 provider | 기본 조합에 들어 있지 않다(확장 지점) | Connect/gRPC-Web 통합 |
| 게이트웨이 리다이렉트형 세션 만료 | 쿠키 프로필을 쓰는 설정이 템플릿에 없다(지난 라운드와 같음) | `SAME_ORIGIN_COOKIE` 프로필 조합과 302 로그인 응답 |
| 성능 | 이번 라운드에 측정하지 않았다 | 13·11 영역의 측정 |
@@ -0,0 +1,334 @@
# 04 realtime 어댑터 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 깊게 본 관점: 6, 7, 12, 13, 14, 17
## 0. 머리말 (36.1)
| 항목 | 기록 |
| --- | --- |
| 영역 | realtime reference runtime: SSE·WebSocket 연결, reconnect coordinator, stream coordinator, event codec·consumer, bounded polling, live↔poll handoff |
| 경로 | `src/adapters/realtime/` 16파일 9,790줄, `tests/unit/realtime/` 16파일 9,914줄. 연결 지점: `src/contracts/realtime-streams.ts`, `src/application/ports/realtime/shared.ts`, `config/recipes/frontend-capability-recipes.json:29-74` |
| 기준 커밋·작업 상태 | `af3d8e6`. 워킹트리 변경은 리뷰 가이드 문서 2개뿐이고 코드는 `af3d8e6`과 같다 |
| 전제 (0.1) | 템플릿. realtime은 `RECIPE_AVAILABLE` / `AVAILABLE_NOT_COMPOSED`이고 production 조합이 없다(`frontend-capability-recipes.json:30-32`, `:59`). 조합 코드(attempt·session bridge, 환경 신호, 닫기)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개(설계 5.6) |
| 읽은 코드 | `reconnect-coordinator.ts`, `reconnect-policy.ts`, `sse/fetch-sse-connection.ts` 전부. `event-codec.ts`, `event-consumer.ts`, `stream-coordinator.ts`, `websocket/websocket-connection.ts`, `polling/bounded-poll-coordinator.ts`, `result.ts`, `sse/sse-parser.ts`는 지난 리뷰 뒤 바뀐 부분과 이번 판정에 필요한 부분(`git diff 4626b73 af3d8e6`) |
| 읽은 테스트 | `realtime-reconnect-coordinator.test.ts` 전부, `event-consumer.test.ts:224-400`, `fetch-sse-connection.test.ts`의 04-05·04-06 절, `websocket-connection.test.ts:1150-1175` |
| 읽은 문서(주장) | `CHANGELOG.md:50`, 설계 `realtime-events-web-push-and-bounded-polling.md` 5.3~5.6·6.3~6.4·11·13.1·15.2~15.4절, `decisions/VD-28-…md:252-275`, `optional-adapter-recipes.md:171-188`, 지난 리뷰 `2026-09-25-maturity-review/04-adapters-realtime.md`, `README.md` 11절, `FOLLOW-UP.md` |
| 소비자 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`: 둘 다 realtime 32파일을 그대로 싣고 조합하지 않는다(`AVAILABLE_NOT_COMPOSED`, 예산 40,900). 동기화 기록에 realtime 충돌·수정은 없다 |
| 실행한 테스트 | 분리 worktree에서 `node scripts/run-vitest.ts run tests/unit/realtime/` → **14 files, 221 passed** |
| 스크래치 실험 | E1~E11. worktree `tests/unit/realtime/`에 넣고 돌린 뒤 뺐다. 파일은 `scratchpad/review-2026-09-29/04/zz-review04-exp.test.ts`(E1~E9), `zz-review04-exp2.test.ts`(E10·E11). 정책은 실제 값에 가깝게 두었다(base 1s, max delay 30s, 10회, 5분, stable 30s). 가짜 clock·fetch·socket을 썼다 |
| 변이 실험 | 18건(`mutate.py`, `mutate2.py`, 결과 `mutation-results*.txt`). **18건 모두 검출.** M14 하나는 실패 메시지 없이 테스트 프로세스가 멈추는 방식으로만 드러났다 |
| 가드레일 | worktree에서 `node scripts/check-realtime-boundaries.ts` → PASS. `node scripts/check-realtime-boundary-fixtures.ts` → PASS(규칙 2건 거절). 지난 리뷰의 세 번째 규칙은 `7f2a1607`에서 dependency-cruiser 그래프 규칙으로 옮겨졌다 |
| 번들 측정 | `scripts/lib/optional-recipe-bundle.ts`의 `measureOptionalRecipeBundle`을 직접 불렀다(`zz-measure.ts`). `af3d8e6`: **40,886 / 40,900 gzip bytes, 여유 14바이트**. lane D 전 `8ffb04e` 39,903 → lane D `46417e3` 40,605 → lane F `96cf513` 40,886 |
| 수정 후보 시험 | 04-01의 최소 수정(2줄)을 worktree에 넣고 E10·E11과 기존 reconnect 테스트 36건을 돌렸다. E10·E11은 재시도하고 끝났고 기존 36건은 모두 통과했다. 시험 뒤 되돌렸다 |
| 확인하지 못한 범위 | `test:realtime-removal`: worktree의 `node_modules`가 메인 링크라 pnpm 실행이 위험하다(오케스트레이터 경고, 06 영역도 같은 이유로 중단). 실제 브라우저·실제 SSE/WS 서버·프록시, 여러 클라이언트 재연결 분포, 브라우저 파서 성능. 7절에 적었다 |
| 이전 리뷰와 비교 | 2026-09-25 04-01~04-08은 모두 닫혔고 회귀는 없다(6.2절). 이번 High(04-01)는 지난 04-01과 다른 경로다. 해당 코드는 `6c52cdb9`(2026-07-30)부터 있었다 |
**영역 판정 (35.8)**
- codec·stream coordinator·WebSocket 연결·polling·handoff: **지정 범위에서 사용 가능.** 입력 검증, 자원 상한, 순서·중복·gap 처리, 늦은 콜백 fence가 유지되고 변이로 검출된다.
- reconnect coordinator + WebSocket: **조건부 사용 가능.** 지난 04-01(오래 열린 연결의 재연결 중단)은 고쳐졌다. 채택 조건은 heartbeat ACK를 `markValidHeartbeatOrEvent`로 넘기는 것이다. hidden 탭에서 heartbeat를 멈추면 예산이 초기화되지 않는다(04-04).
- reconnect coordinator + SSE: **해당 용도의 사용 보류.** 브라우저가 online인 채로 서버가 내려가거나 스트림이 끊기면 재연결도 종료도 없이 멈춘다(04-01, High). 2줄 수정이다. SSE를 coordinator에 잇는 세션 bridge도 없다(04-02).
## 1. 결론
- **04-01 (High):** SSE는 fetch 거절과 읽기 중 네트워크 오류를 모두 `OFFLINE`으로 보고한다. reconnect coordinator는 `OFFLINE` 실패 뒤 새 `online` 이벤트가 올 때까지 기다린다. 브라우저는 네트워크 상태가 바뀌지 않으면 `online` 이벤트를 보내지 않는다. 그래서 서버 다운·배포 중 연결 reset에서 run이 `RUNNING`으로 영원히 멈춘다. 실험에서 20분 동안 시도 1회, 재시도 예약 0회, 종료 결과 없음이었다. 관측 이벤트도 `ATTEMPT_STARTED` 하나뿐이다.
- **04-02 (Medium):** 템플릿이 주는 SSE↔reconnect 도구는 연결 전 실패만 다룬다(`readSseForReconnect`). 열린 SSE 세션을 attempt·session으로 나누고, EOF·`NO_RECONNECT`·`RECOVERY_COMMITTED`를 재연결 결과로 옮기는 규칙은 코드·문서 어디에도 없다. 열린 SSE 세션이 coordinator를 지나는 테스트도 없다. 04-01이 숨어 있던 곳이 여기다.
- **Low 3건:** SSE `retry:` 값 처리 규칙이 설계 두 곳과 코드에서 달라 서버가 더 긴 대기를 요구하면 오히려 더 빨리 재연결한다(04-03). hidden 탭에서 heartbeat를 멈춘 조용한 WS는 예산을 새로 받지 못한다(04-04). CHANGELOG의 [계약] 문장이 실제 초기화 조건보다 넓게 말한다(04-05).
- **확인된 강점:** 지난 04-01~04-08의 수정은 코드와 실험으로 확인했다. 오래 열린 연결의 offline 깜빡임, 같은 틱 안의 offline/online, `waitClosed` 예외, 12번 연속 긴 세션 모두 재연결했다(E1·E1b·E2·E3). 변이 18건을 모두 테스트가 잡았다.
- **FOLLOW-UP:** realtime 레시피 번들 예산은 여유가 14바이트다. 04-01 수정을 포함해 realtime을 한 줄만 고쳐도 예산을 다시 올려야 할 가능성이 높다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — 조용한 WebSocket 구독이 서버 재시작 뒤 재연결한다
```text
입력 조합 코드가 coordinator.run() 호출
정책 attempt(context) → createWebSocketConnection(observe=HEARTBEAT_ACK→context.markValidHeartbeatOrEvent)
(reconnect-coordinator.ts:640-699, websocket-connection.ts:375-378)
상태 WELCOME → SESSION_OPENED(:877-878). heartbeat ACK마다 validSignalObserved=true(:685-687)
외부I/O 6분 동안 이벤트 없이 heartbeat만 오감
실패 서버 재시작 close 1012 → RESTART → PROVIDER_UNAVAILABLE retryable(websocket-connection.ts:1811-1817)
세션 종료 시 "유효 신호 + 30초 이상 유지"면 retriesUsed=0, budgetStartedAt=종료 시각(reconnect-coordinator.ts:886-900)
결과 full jitter 대기 뒤 새 소켓으로 재연결(테스트 realtime-reconnect-coordinator.test.ts:1830-1913, 변이 M1·M6 검출)
```
같은 흐름에서 네트워크가 1초 끊기면 세션은 offline 경로로 끝난다. 예산은 같은 규칙으로 초기화된다. online 복귀 시 elapsed 예산을 다시 시작한다(`:550-559`). E1·E1b·E2에서 확인했다.
### 2.2 피해가 큰 흐름 — SSE 스트림 중 서버가 연결을 끊는다 (04-01)
```text
입력 열린 SSE 세션. 브라우저 네트워크는 정상(navigator.onLine=true, 이벤트 없음)
외부I/O 백엔드 재시작·프록시 upstream 종료로 청크 종료 없이 연결이 끊김 → reader.read() reject
실패 fetch-sse-connection.ts:396-400 → OFFLINE(RECEIVE, retryable:true)
서버 다운으로 연결 거절이면 fetch reject → :213-218 → OFFLINE(CONNECT)
정책 coordinator가 OFFLINE 실패를 받으면 requireOnline()(reconnect-coordinator.ts:798, :994-998)
→ requiredOnlineVersion = 현재+1(:424-429)
상태 다음 루프에서 waitOnline()(:455-479)이 새 online 이벤트만 기다린다. 타이머 없음
결과 run은 RUNNING으로 남는다. 재시도 0회, 종료 결과 없음, RETRY_SCHEDULED·RUN_ENDED 관측 없음(E10·E11)
stream freshness는 마지막 값(CURRENT)을 유지한다. 조합 코드는 fallback으로 넘어갈 신호를 받지 못한다
```
### 2.3 변경 흐름 — 백엔드가 기존 stream에 이벤트 종류를 추가한다
```text
입력 새 백엔드가 registry에 없는 eventType을 보냄. 이전 번들 탭이 열려 있음
정책 codec: stream을 찾은 뒤 eventType 조회 실패 → PROTOCOL_MISMATCH / operation REGISTRY(event-codec.ts:170-176)
실패 객체와 stream을 WeakMap에 기록(:72-106)
상태 consumer가 해당 stream을 invalidate → freshness UNKNOWN(event-consumer.ts:87-91, stream-coordinator.ts:998-1001)
외부I/O SSE는 읽기를 끝낸다. WS는 receipt.error에 같은 실패를 담아 닫는다(websocket-connection.ts:1060-1072, :1379-1384)
실패 retryable:false → reconnect coordinator는 그대로 반환
결과 조합 코드가 operation REGISTRY를 보고 reload를 유도한다(설계 13.1, :1921-1926)
테스트: event-codec.test.ts:70-78, event-consumer.test.ts:318-400(변이 M7·M8·M9·M15 검출). WS 경로 테스트는 없다
```
템플릿 쪽에서 이벤트 종류를 추가하려면 registry 항목, payload schema codec, mapper binding을 함께 맞춰야 한다. 생성 시 서로 대조해 어긋나면 거절한다(`src/contracts/realtime-streams.ts:313-321`).
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 근거·잔여 위험 |
| --- | --- | --- | --- |
| 1 | 코드 성숙도 | O | 상태 기계(IDLE/RUNNING/DRAINING/CLOSED)와 terminal·idempotent close가 유지된다. 221건 통과 |
| 2 | 구조적 성숙도 | O | kernel(`platform/`)과 ports·contracts만 import한다. `check:architecture` PASS(오케스트레이터) |
| 3 | 변경 용이성 | P | 이벤트 종류 추가는 registry·schema·mapper를 생성 시 대조한다. SSE를 조합하려면 bridge를 직접 써야 한다(04-02) |
| 4 | 인지 부하 | P | `runLoop`가 약 670줄이다(`reconnect-coordinator.ts:360-1031`). 조합 코드는 markValid 출처, classifyClosed, hint 통로, OFFLINE 의미를 알아야 한다 |
| 5 | 위험 가시성 | P | `isCurrent`·markValid·환경 신호 책임은 타입 주석에 적혔다(`:58-63`, `:106-113`, `:175-181`). OFFLINE 실패가 "online 이벤트 대기"라는 의미는 코드 안쪽(`:798`)에만 있다(04-01) |
| 6 | 실패 성숙도 | **X** | 지난 04-01은 해소됐다(E1~E3, M1·M2·M3 검출). 새 결함: SSE 네트워크 오류가 OFFLINE이 되어 run이 무기한 멈춘다(04-01, E10·E11). 서버 hint 상한 처리도 값에 따라 뒤집힌다(04-03, E9) |
| 7 | 운영 성숙도 | P | reconnect·poll에 닫힌 관측 어휘가 생겼다(`:128-152`, 변이 M12 검출). online 대기 상태는 관측도 결과도 없다(E10: `ATTEMPT_STARTED`만 1건) |
| 8 | 디버깅 가능성 | P | operation `REGISTRY`로 구버전 클라이언트를 구분한다. `getState()`는 연결 중과 online 대기를 모두 `RUNNING`으로 보여 준다(04-01) |
| 9 | 유지보수 성숙도 | P | VD-28·설계 5.3이 코드와 맞다(`VD-28-…md:258-271`). CHANGELOG [계약] 문장이 넓다(04-05). 설계 문서의 줄 번호 참조는 지금은 맞지만 검사 대상이 아니다 |
| 10 | 테스트 성숙도 | P | 221건 통과, 변이 18/18 검출. 열린 SSE 세션이 coordinator를 지나는 테스트가 없다. 04-01 수정 후보(2줄)를 넣어도 기존 36건이 모두 통과한다. 즉 이 동작을 고정한 테스트가 없다 |
| 11 | 데이터 성숙도 | O | cursor는 effect 성공 뒤에만 전진하고 메모리에만 있다. 이번 라운드에 바뀐 곳 없음(E1) |
| 12 | 동시성 성숙도 | O | 한 번에 run 1개(`:363-364`), recovery single-flight(`stream-coordinator.ts:665`), 중단 뒤 늦게 온 세션 닫기(`:1615-1621`), scope·generation fence. 변이 C1·C2·C3 모두 검출. 탭별 연결과 hidden 닫기는 설계상 조합 코드 몫이다(설계 5.6) |
| 13 | 확장성 | P | 구독 32, 큐 256건/4MiB, dedupe 2,048건 등 상한은 그대로다(설계 11절). 레시피 번들 여유 14바이트(측정). 서버 재시작 뒤 여러 클라이언트 재연결 분포는 측정하지 않았다 |
| 14 | 성능 성숙도 | P | 1MB 단일 chunk를 256KB씩 나눠 넣는다(`fetch-sse-connection.ts:423-446`, 변이 M10 검출). 번들 40,886/40,900. 브라우저 파서 성능은 미측정 |
| 15 | 보안 성숙도 | O | 고정 same-origin HTTPS/WSS, URL에 credential 없음, 401/403 즉시 종료(`fetch-sse-connection.ts:583-588`). 이번 라운드 변경 없음(E1) |
| 16 | 의존성 성숙도 | O | 외부 패키지 없음. native API는 facade로 주입. boundary 검사 PASS |
| 17 | API/Contract 성숙도 | P | REGISTRY 실패 계약은 구현·테스트됐다(SSE 경로). OFFLINE 의미가 "네트워크 오류 전반"과 "online 이벤트 대기"로 갈린다(04-01). SSE `retry:` 상한 규칙이 설계 5.3과 6.3에서 다르다(04-03). consumer의 `invalidate`는 선택 의존성이라 빠져도 타입이 통과한다(`event-consumer.ts:67-68`) |
| 18 | 배포 성숙도 | P | 새 이벤트 종류가 구버전 탭에서 REGISTRY로 드러난다. 백엔드 배포가 SSE 연결을 reset하면 멈춘다(04-01) |
| 19 | 설정 성숙도 | P | 정책은 생성 시 검증하고 상한은 낮추기만 한다(`reconnect-policy.ts:43-67`). 파서의 `maxRetryMs`(60s)와 정책 `maxDelayMs`가 따로 놀아 04-03이 생긴다 |
| 20 | 개발자 경험 | P | WS는 테스트 안에 조합 예시가 있다. SSE는 세션 bridge 예시가 없다(04-02) |
| 21 | Guardrail 성숙도 | O | `check-realtime-boundaries`·fixture PASS. CI 게이트에 등록(`config/ci/gates.json:364-370`, `:526-527`). 조합 금지 규칙은 그래프 규칙으로 옮겨졌다(12 영역) |
| 22 | 추상화 성숙도 | P | attempt/session 경계가 transport를 잘 숨긴다. SSE는 한 번의 `read()`가 연결과 수신을 모두 해서 이 경계에 맞추는 부품이 없다(04-02) |
| 23 | 일관성 | P | 같은 네트워크 오류가 WS에서는 PROVIDER_UNAVAILABLE, SSE에서는 OFFLINE이다(04-01). 상한 넘은 hint가 헤더면 종료, SSE `retry:`면 무시다(04-03) |
| 24 | 네이밍/의미 | P | `OFFLINE`이 SSE에서는 "기기 offline"이 아닌 "요청이 네트워크 단계에서 실패"를 뜻한다(04-01) |
| 25 | 조직 확장성 | - | 작성자 1인. registry에 `owner` 필드가 필수인 것만 확인 |
| 26 | Ownership | - | 제품 조합이 없다. recipe `owner: project-owner-required`(`frontend-capability-recipes.json:68`) |
| 27 | 삭제 가능성 | ? | `test:realtime-removal`은 worktree에서 pnpm이 필요해 돌리지 않았다. CI 게이트에는 있다(`gates.json:526-527`) |
| 28 | 회복 가능성 | P | gap·cursor 만료 → snapshot 복구는 유지. WS·offline 깜빡임 재연결은 해소. SSE 네트워크 오류 뒤 스스로 회복하지 못한다(04-01) |
## 4. 설계 선택 설명 (41절)
### 4.1 재시도 예산은 "유효 신호 + 안정 유지"를 모두 채운 세션이 끝날 때만 초기화하고, offline 뒤에는 elapsed만 다시 시작한다
1. **무엇이 필요한가:** 오래 건강했던 연결이 끊기면 다시 붙어야 한다. 곧바로 끊기는 서버에는 재연결 폭주를 만들지 않아야 한다.
2. **지킬 성질:** 시도 횟수와 경과 시간은 연속 실패 구간에만 쌓인다. 열리자마자 끊기는 연결은 예산을 새로 받지 못한다.
3. **현재 보장:** 세션이 어떤 방식으로 끝나든 한 곳에서 판정한다(`reconnect-coordinator.ts:886-900`). 판정 함수는 두 조건을 모두 요구한다(`reconnect-policy.ts:137-149`). offline 대기 뒤에는 `budgetStartedAt`만 다시 잡고 `retriesUsed`는 둔다(`:550-559`). 변이 M1~M4가 모두 검출됐다. **보장하지 않는 것:** 유효 신호를 조합 코드가 넘겨야 한다. 넘기지 않거나 heartbeat를 멈춘 조용한 세션은 예산을 새로 받지 못한다(E6, E7 → 04-04). 30초보다 짧은 세션이 offline으로 10번 끊기면 run이 끝난다(E5, 시도 11회 뒤 `OFFLINE retryable:true`).
4. **대안:** (a) 세션이 열리기만 하면 초기화. (b) 안정 유지 시간만 요구. (c) 유효 신호만 요구. (d) 현재 방식.
5. **비교:** (a)는 열리자마자 닫는 서버에 영구 재연결을 만든다. (b)는 이벤트 없이 열려만 있는 반쯤 죽은 연결도 보상한다. (c)는 comment 하나 보내고 끊는 서버에 예산을 계속 준다. (d)는 조합 코드가 신호를 넘겨야 하는 비용이 있다.
6. **현재 조건에서의 이유:** 기록된 의도는 `reconnect-policy.ts:131-136` 주석과 VD-28 7절(`:258-260`)에 있다. 확인한 코드도 그 의도대로 동작한다. 리뷰어 판단으로는 유지가 맞다.
7. **재검토 조건:** hidden 탭에서 연결을 유지하는 제품이 생기면 heartbeat 정지와 예산 규칙을 함께 다시 본다(04-04). 짧은 세션이 반복되는 모바일 환경의 실제 종료율이 측정되면 `stableOpenMs`와 시도 상한을 다시 본다.
### 4.2 `OFFLINE` 실패는 새 `online` 이벤트를 기다린다 (04-01의 뿌리)
1. **무엇이 필요한가:** 기기가 실제로 offline이면 타이머로 헛된 재시도를 하지 않는다.
2. **지킬 성질:** 어떤 실패 뒤에도 run은 재연결하거나, 정해진 예산 안에서 끝나야 한다. 무기한 대기는 조합 코드가 fallback을 고를 기회를 없앤다(설계 5.3 "budget을 소진하면 … fallback").
3. **현재 보장:** 환경이 offline을 알린 경우는 맞게 동작한다(E1·E8). **보장하지 않는 것:** transport가 스스로 `OFFLINE`을 보고하면 환경이 online이어도 새 online 이벤트를 요구한다(`:798`, `:994-998`). SSE는 모든 fetch·reader 거절을 OFFLINE으로 보고한다(`fetch-sse-connection.ts:213-218`, `:396-400`). 설계 13.1은 `OFFLINE`을 "network hint/attempt failure → online hint 뒤 bounded check"로 적는다(`:1889`). 같은 설계 5.3은 "`navigator.onLine`은 실제 backend reachability authority가 아니다"라고 적는다(`:780`). 두 문장이 어긋난다.
4. **대안:** (a) 현상 유지. (b) coordinator에서 환경이 offline일 때만 online 이벤트를 요구한다. (c) SSE가 fetch·reader 거절을 `PROVIDER_UNAVAILABLE` retryable로 보고한다(WS의 NETWORK_LOST와 같게). (d) online 대기에 상한 시간을 둔다.
5. **비교:** (a)는 멈춤이 남는다. (b)는 2줄이고 모든 transport에 적용된다. 수정 후보 시험에서 기존 36건이 모두 통과했다. 환경 이벤트보다 먼저 transport가 실패를 보면 한두 번 헛시도가 생기지만 시도 상한 안이다. (c)는 SSE만 고치고 실패 어휘 의미를 바꾼다. 13.1 표도 고쳐야 한다. (d)는 새 상수와 상태가 늘어난다.
6. **현재 조건에서의 판단:** 작성 의도는 기록에 없다. 현재 조건에서 (a)를 유지할 근거는 찾지 못했다. (b)를 권한다.
7. **재검토 조건:** 실제 reachability 확인(예: 가벼운 health 요청)을 환경 신호로 쓰게 되면 (d)나 별도 대기 상태를 다시 비교한다.
### 4.3 서버 hint가 상한을 넘으면 낮춰 자르지 않고 run을 끝낸다
1. **무엇이 필요한가:** 과부하인 서버가 늦게 오라고 하면 그보다 먼저 가지 않는다.
2. **지킬 성질:** 서버가 요구한 시각보다 먼저 재시도하지 않는다(설계 5.3 `:761-766`).
3. **현재 보장:** 헤더 `Retry-After`는 지킨다. 상한(60s) 안이면 대기하고, 넘으면 transport가 `retryable:false`로 끝낸다(`fetch-sse-connection.ts:592-614`). coordinator는 정책 `maxDelayMs`를 넘는 hint를 받으면 끝낸다(`reconnect-coordinator.ts:1509-1514`). 변이 M5 검출. **보장하지 않는 것:** SSE `retry:` 필드는 파서가 60초를 넘으면 버린다(`sse-parser.ts:330-341`). 그러면 hint가 없는 것으로 보고 로컬 지터(0.5초)로 재연결한다. 60초 이하이면서 정책 `maxDelayMs`를 넘으면 모든 끊김이 즉시 종료된다(E9, 04-03).
4. **대안:** (a) 현상 유지. (b) 상한을 넘는 hint를 상한으로 자른다. (c) SSE `retry:`도 상한을 넘으면 transport가 종료로 보고한다(헤더와 같게). (d) SSE `retry:`는 "기본 재연결 간격"으로만 쓰고 not-before로 쓰지 않는다.
5. **비교:** (b)는 서버 요구보다 먼저 재시도한다. 설계가 금지한다. (c)는 규칙이 하나가 되고 코드는 몇 줄이다. 대신 과도한 `retry:` 값이 SSE 재연결을 끈다. (d)는 표준 SSE 의미에 가깝지만 5.3 문장을 바꿔야 한다.
6. **현재 조건에서의 판단:** 헤더 hint를 종료로 처리하는 것은 유지할 근거가 있다. 과부하 신호이고 설계에 기록돼 있다. `retry:` 필드는 설계 5.3과 6.3(`:1031-1032`)이 다른 규칙을 말한다. 둘 중 하나로 정해야 한다.
7. **재검토 조건:** 채택 서버가 `retry:`를 60초 넘게 보내거나, 정책 `maxDelayMs`를 서버 `retry:`보다 작게 잡는 경우가 생기면 바로 정한다.
## 5. 발견 사항 (36.3)
### 04-01 SSE 네트워크 오류가 `OFFLINE`이 되어, 브라우저가 online이면 reconnect run이 재시도도 종료도 없이 멈춘다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 28, 18, 7, 8, 17, 23, 24, 5, 10 |
| 근거 | ① SSE는 fetch 거절을 `OFFLINE(CONNECT, retryable)`로(`src/adapters/realtime/sse/fetch-sse-connection.ts:213-218`), 읽기 중 reader 거절을 `OFFLINE(RECEIVE, retryable)`로 보고한다(`:396-400`). 중단(abort)이 아닌 모든 네트워크 오류가 여기로 온다. ② coordinator는 attempt 실패(`reconnect-coordinator.ts:798`)와 세션 종료 분류(`:994-998`)에서 kind가 `OFFLINE`이면 `requireOnline()`을 부른다. 이 함수는 현재보다 큰 online 버전을 요구한다(`:424-429`). ③ 다음 루프에서 `waitOnline()`(`:455-479`)은 abort나 새 online 이벤트만 기다린다. 타이머가 없다. ④ WebSocket은 같은 상황을 `NETWORK_LOST → PROVIDER_UNAVAILABLE retryable`로 보고한다(`websocket-connection.ts:1811-1817`). 이 경로는 정상 백오프를 탄다. **실험**(`zz-review04-exp2.test.ts`, 브라우저 online 유지·이벤트 없음): E10 연결 전 fetch 거절 → 20분 동안 시도 1회, `getState()` `RUNNING`, 종료 결과 없음, 관측은 `ATTEMPT_STARTED` 하나. online 이벤트를 한 번 보내자 그제야 2번째 시도를 했다. E11 40초 열린 스트림에서 reader가 거절 → 20분 동안 시도 1회, `RUNNING` |
| 발생 조건 | SSE를 reconnect coordinator에 조합했을 때. 기기 네트워크는 정상인데 요청이 네트워크 단계에서 실패하는 경우다. 서버 다운(연결 거절), 배포·재시작 중 프록시가 청크 종료 없이 연결을 끊는 경우, DNS·TLS 오류, CORS 설정 오류가 여기에 해당한다 |
| 영향 | 그 탭의 realtime이 조용히 멈춘다. run이 끝나지 않으므로 조합 코드는 polling fallback이나 stale 표시로 넘어갈 신호를 받지 못한다(설계 5.3 "budget 소진 → fallback"을 우회한다). stream freshness는 마지막 값(보통 `CURRENT`)이다. 사용자 네트워크가 바뀌거나 조합 코드가 `close()` 후 새 run을 만들 때까지 이어진다. reference runtime이라 SSE를 고른 다운스트림에 그대로 복제된다 |
| 심각도·우선순위 | High · P1. 설계가 지원한다고 적은 장애(설계 6.4 "deploy/drain 중 reconnect", 15.3 "server restart")에서 핵심 기능이 멈추고 탐지 신호도 없다. production 조합 전이라 P0는 아니다. SSE realtime 도입 전에 풀어야 할 차단 항목이다 |
| 통제·증거 | M0(transport OFFLINE + 환경 online 경로에 종료 수단 없음) · E2(스크래치 실험, 가짜 fetch) |
| 확실성과 남은 가정 | 코드 경로와 실험으로 확인했다. 실제 브라우저가 이 오류들을 `TypeError` 거절로 주는지는 표준 fetch 동작으로 판단했고 실제 브라우저·서버로 재현하지는 않았다. 조합 코드가 visibility 변화 때마다 `close()`→새 run을 한다면 멈춤이 그 시점에 풀린다. 그런 배선은 저장소에 없다 |
| 결정의 근거 | 4.2절. 현재 선택을 유지할 근거는 찾지 못했다. 설계 13.1(`:1889`)과 5.3(`:780`)이 어긋난다 |
| 이해 비용 | 조합 코드 작성자는 SSE의 `OFFLINE`이 "기기 offline"이 아니라는 점과, coordinator가 그 kind에 특별한 대기를 건다는 점을 둘 다 알아야 한다. 두 사실은 서로 다른 파일의 안쪽 줄에 있다 |
| 최소 개선 방향 | coordinator의 두 곳에서 환경이 offline일 때만 online 이벤트를 요구한다. `if (kind === "OFFLINE" && !online) requireOnline();`. 환경이 online이면 일반 retryable 실패처럼 시도·시간 예산 안에서 백오프한다. 설계 13.1의 `OFFLINE` 행에 "환경이 online이면 bounded retry"를 적는다 |
| 대안 비교 | 4.2절 표. SSE에서 거절을 `PROVIDER_UNAVAILABLE`로 바꾸는 (c)도 가능하다. 다만 SSE만 고치고 실패 어휘 의미가 바뀐다. online 대기에 상한 시간을 두는 (d)는 상태가 늘어난다 |
| 단순화의 보존 조건 | 환경이 offline일 때 타이머 재시도를 하지 않는 동작(기존 테스트 `realtime-reconnect-coordinator.test.ts:400-435`, `:437-467`, E8)을 유지한다 |
| 비용·부작용 | 2줄. 환경 이벤트보다 먼저 transport가 실패를 보면 헛시도가 한두 번 생긴다. 시도 상한(10회) 안이다. 레시피 번들 여유가 14바이트라 예산을 다시 올려야 할 수 있다(6절) |
| 재검토 조건 | 4.2절 7번 |
| 완료 기준 | E10·E11과 같은 조건에서 run이 재시도하거나, 예산을 소진해 `RUN_ENDED(EXHAUSTED)`로 끝난다. 환경 offline 경로의 기존 동작은 그대로다 |
| 검증 방법 | `realtime-reconnect-coordinator.test.ts`에 "브라우저 online인 채 fetch 거절", "열린 스트림 reader 거절" 두 케이스를 ManualClock으로 추가한다. `:798`의 조건을 되돌리는 변이가 실패해야 한다. 수정 후보를 넣은 시험에서 E10은 `RETRY_SCHEDULED:OFFLINE` 뒤 두 번째 시도를 했다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-01(예산 초기화)과 다른 경로다. 지난 라운드 실험은 환경 이벤트로 offline을 만들어 이 경로를 지나지 않았다 |
### 04-02 SSE를 reconnect coordinator에 잇는 세션 bridge가 없고, 열린 SSE 세션이 coordinator를 지나는 테스트가 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 20, 22, 10, 17, 4, 3 |
| 근거 | coordinator는 attempt가 열린 세션(`waitClosed`, `classifyClosed`, `close`)을 돌려주길 요구한다(`reconnect-coordinator.ts:94-104`, `:159-169`). WebSocket은 `connect()`와 `waitClosed()`가 나뉘어 있어 그대로 맞는다(테스트 `realtime-reconnect-coordinator.test.ts:1772-1803`). SSE는 한 번의 `read()`가 연결과 수신을 모두 한다(`fetch-sse-connection.ts:77-83`). 템플릿이 주는 도구는 `readSseForReconnect` 하나다(`:487-506`). 이 함수는 read 전체를 기다린 뒤 실패에 hint를 붙일 뿐이다. 그래서 조합 코드는 다음을 직접 써야 한다. `onOpen`에서 attempt를 끝내고 read를 세션으로 넘기기, recovery barrier(`waitForRecoveryBarrierConfirmation`, `establishedRecoveryBarrier`) 연결, `onComment`→markValid, 종료 결과 매핑. 종료 결과 중 `EOF`는 `ok:true`다(`:38-47`). 이를 그대로 넘기면 coordinator는 run을 성공(`COMPLETED`)으로 끝낸다(`reconnect-coordinator.ts:976-979`). EventSource처럼 재연결하려면 retryable 실패로 바꾸고 `retryHintMs`를 hint로 옮겨야 한다. 이 규칙은 설계 6.3 상태 표(`:1039-1050`)에도 없다. 저장소의 SSE↔coordinator 테스트 4건(묶음 2개)은 모두 "Only connect failures are exercised here"다(`realtime-reconnect-coordinator.test.ts:1931`, `:1995`) |
| 발생 조건 | 다운스트림이 SSE realtime을 조합할 때 |
| 영향 | 채택자마다 가장 실수하기 쉬운 부분을 따로 만든다. EOF를 성공으로 매핑하면 서버의 정상 종료 뒤 재연결하지 않는다. 04-01 같은 결함이 템플릿 테스트에 드러나지 않는다. 이번 04-01은 리뷰어가 bridge를 직접 써 보고서야 재현됐다 |
| 심각도·우선순위 | Medium · P2. 결함 자체는 조합 코드에서 생기지만, 템플릿이 "fetch-stream SSE"와 "bounded reconnect ownership"을 제공 범위로 적는다(`frontend-capability-recipes.json:33-36`) |
| 통제·증거 | M1(연결 전 실패 bridge만) · E1(코드 읽기), E2(04-01 재현에 쓴 bridge) |
| 확실성과 남은 가정 | 코드와 테스트 목록으로 확인했다. 채택자가 실제로 EOF를 성공으로 매핑하는지는 조합 코드가 없어 미확인이다 |
| 결정의 근거 | 확인한 사실: WS에는 연결·종료 분리 API가 있고 SSE에는 없다. 기록된 의도: `onOpen` 주석이 "A reconnect bridge can hold this gate…"라고 bridge를 전제한다(`fetch-sse-connection.ts:58-62`). 리뷰어 추론: bridge를 전제한 설계인데 부품만 빠졌다 |
| 이해 비용 | 채택자는 coordinator의 결과 모양, SSE 종료 결과 3종, barrier 증명 규칙, hint 통로를 모두 읽어야 한다. 대략 `reconnect-coordinator.ts` 앞 200줄과 `fetch-sse-connection.ts` 전체다 |
| 최소 개선 방향 | `sse/`에 `connectSseForReconnect(connection, input, context)` 같은 함수를 하나 둔다. attempt 결과(열린 세션 또는 연결 전 실패+hint)와 `classifyClosed`(EOF→retryable+`retryHintMs`, `NO_RECONNECT`→성공 종료, `RECOVERY_COMMITTED`→`RECOVERY_RECONNECT`, 실패→그대로+hint)를 만든다. 열린 세션의 EOF·reader 거절·`retry:`를 coordinator까지 지나는 테스트를 붙인다 |
| 대안 비교 | (a) 현상 유지 + 설계 6.3에 매핑 표만 추가: 코드 0줄. 채택자가 여전히 직접 쓴다. (b) bridge 함수 1개(제안): 수십 줄, 번들 예산 인상 필요. 매핑 규칙이 한 곳에 모이고 테스트로 고정된다. (c) SSE 연결을 WS처럼 `connect()`/`waitClosed()`로 나누기: API가 일관되지만 기존 `read()` 소비자와 테스트를 모두 바꾼다 |
| 단순화의 보존 조건 | `read()`의 기존 계약(연결 전 실패, 종료 결과, `onOpen` 게이트)은 바꾸지 않는다 |
| 비용·부작용 | bridge 수십 줄과 테스트. 번들 예산을 올려야 한다 |
| 재검토 조건 | 템플릿이 SSE를 기본 transport에서 빼거나, 제품 조합이 하나 생겨 그 코드가 사실상 기준이 되면 다시 판단한다 |
| 완료 기준 | 채택자가 attempt·classifyClosed를 직접 쓰지 않고 SSE를 조합할 수 있다. EOF 뒤 재연결, `retry:` hint, `NO_RECONNECT` 종료, recovery barrier가 coordinator를 지나는 테스트로 고정된다 |
| 검증 방법 | 새 테스트 + "EOF를 성공으로 매핑" 변이가 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-02("Retry-After가 실패 결과에 안 실림")의 수정이 연결 전 실패만 다뤘다. 지난 README 20번 관점 "조합 예시가 테스트 안에만 있다"의 SSE 부분이 남았다 |
### 04-03 SSE `retry:` 값 처리 규칙이 설계 5.3·6.3과 코드에서 달라, 서버가 더 긴 대기를 요구하면 오히려 더 빨리 재연결한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 17, 19, 23 |
| 근거 | 파서는 `retry:` 값이 `maxRetryMs`(60,000)를 넘으면 버린다(`sse/sse-parser.ts:330-341`, 테스트 `sse-parser.test.ts:105-110`이 99,999를 버리는 동작을 고정). `readSseForReconnect`는 받은 마지막 `retry:` 값을 이후 모든 실패의 not-before로 붙인다(`fetch-sse-connection.ts:296-301`, `:497-505`). coordinator는 hint가 정책 `maxDelayMs`를 넘으면 끝낸다(`reconnect-coordinator.ts:1509-1514`). 실험 E9(정책 max delay 30s, 스트림이 `retry:`를 보낸 뒤 idle timeout): `retry: 45000` → fetch 1회, 재시도 없이 `IDLE_TIMEOUT`으로 종료. `retry: 90000` → 0.5초 뒤 재연결. 설계 5.3(`:761-766`)은 SSE `retry`도 not-before이고 상한을 넘으면 종료라고 적는다. 설계 6.3(`:1031-1032`)은 상한을 통과한 경우에만 hint로 쓴다고 적는다 |
| 발생 조건 | 서버가 `retry:`를 60초보다 크게 보내거나, 정책 `maxDelayMs`보다 크게 보낼 때 |
| 영향 | 60초 초과: 서버가 요구한 시각보다 먼저 재연결한다(5.3 위반). 정책 상한 초과: `retry:`는 보통 스트림 시작에 한 번 오는 기본값이라 그 뒤 모든 끊김(offline 포함)이 재시도 없이 끝난다. 시도 상한이 있어 폭주는 없다 |
| 심각도·우선순위 | Low · P3. 흔한 `retry:` 값(수 초)에서는 나타나지 않는다 |
| 통제·증거 | M1(설계 두 곳이 서로 다름) · E2(E9) |
| 확실성과 남은 가정 | 코드와 실험으로 확인. 채택 서버의 실제 `retry:` 값은 모른다 |
| 결정의 근거 | 4.3절. 헤더 hint의 종료 처리는 유지할 근거가 있다. `retry:` 필드 규칙은 설계 안에서 먼저 하나로 정해야 한다 |
| 이해 비용 | 파서 상한, 정책 상한, bridge의 hint 전파, coordinator의 종료 조건을 네 파일에서 맞춰 읽어야 결과를 예측할 수 있다 |
| 최소 개선 방향 | 규칙을 하나로 정한다. (c) 상한 초과 `retry:`는 헤더처럼 종료로 보고하거나, (d) `retry:`를 not-before가 아닌 기본 간격으로만 쓴다. 정한 쪽에 맞춰 5.3·6.3 문장과 파서 테스트를 고친다 |
| 대안 비교 | 4.3절 4·5번 |
| 단순화의 보존 조건 | 헤더 `Retry-After`의 현재 동작(M5로 검출됨)은 바꾸지 않는다 |
| 비용·부작용 | 몇 줄과 테스트 1~2건 |
| 재검토 조건 | 4.3절 7번 |
| 완료 기준 | `retry:` 값을 키울수록 재연결이 늦어지거나 종료된다(단조). 설계 5.3·6.3이 같은 규칙을 말한다 |
| 검증 방법 | E9와 같은 두 값 케이스를 테스트로 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 04-04 hidden 탭에서 heartbeat를 멈춘 조용한 WebSocket은 예산을 새로 받지 못해, 그 사이 서버가 재시작하면 재시도 없이 끝난다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 28, 20, 5 |
| 근거 | WS는 `heartbeatEligible()`가 false면 heartbeat를 보내지 않는다(`websocket-connection.ts:1083-1088`). 테스트는 이 훅을 "visibility provider"로 쓴다(`websocket-connection.test.ts:1156-1159`). 설계 6.4는 hidden 상태에서 watchdog을 멈추라고 권한다(`:1053-1056`). heartbeat가 없으면 `HEARTBEAT_ACK` 관측이 없고, 조용한 stream은 유효 신호가 없다. 예산 초기화에는 유효 신호가 필요하다(`reconnect-policy.ts:143-148`). 실험 E7: `heartbeatEligible: () => false`로 6분 동안 이벤트 없음 → 1012 → ACK 0건, 소켓 1개, `PROVIDER_UNAVAILABLE retryable:true`로 종료. `heartbeatEligible` 자체에는 주석이 없다(`:177`) |
| 발생 조건 | 조합 코드가 hidden 탭 연결을 닫지 않고 heartbeat만 멈추며, 이벤트가 드문 stream이 `maxElapsedMs`보다 오래 hidden인 채 서버가 재시작할 때 |
| 영향 | 그 탭의 realtime이 끝난다. 결과가 돌아오므로 조합 코드가 visible 복귀 때 새 run을 만들면 회복된다(설계 5.4 visible 행) |
| 심각도·우선순위 | Low · P3. 설계는 hidden 연결을 grace 뒤 닫으라고 권한다(5.4). 그 권고를 따르면 나타나지 않는다 |
| 통제·증거 | M1 · E2(E7) |
| 확실성과 남은 가정 | 실험으로 확인. 채택자가 hidden 연결을 유지하는지는 조합 코드가 없어 미확인이다 |
| 결정의 근거 | 적용 제외 — 4.1절의 규칙은 유지하고, 그 규칙이 heartbeat 정지와 만날 때의 결과를 드러내는 문제다 |
| 이해 비용 | `heartbeatEligible`, markValid, 예산 규칙을 세 파일에서 이어 읽어야 알 수 있다 |
| 최소 개선 방향 | `heartbeatEligible` 주석과 설계 5.3 예산 문단에 "heartbeat를 멈춘 동안은 예산을 새로 받지 못한다. hidden 연결은 닫거나 visible 복귀 때 새 run을 만든다"를 적는다 |
| 대안 비교 | 적용 제외 — 문서 보강만 제안한다 |
| 단순화의 보존 조건 | 적용 제외 — 동작을 바꾸지 않는다 |
| 비용·부작용 | 주석 몇 줄 |
| 재검토 조건 | 적용 제외 — 4.1절 7번과 같다 |
| 완료 기준 | 채택자가 `heartbeatEligible` 옆 주석만 보고 결과를 안다 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-01 (c)(조용한 WS)의 남은 조건 |
### 04-05 CHANGELOG [계약] 문장이 실제 예산 초기화 조건보다 넓게 말한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(문서) |
| 관련 관점 | 9, 17 |
| 근거 | `CHANGELOG.md:50`은 "세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다"고 적는다. 코드는 유효 신호와 안정 유지를 모두 채운 세션만 초기화한다(`reconnect-coordinator.ts:886-900`, E6: 조용한 세션은 초기화 안 됨). offline은 멈춤(누적 보존)이 아니라 online 복귀 시 elapsed를 처음부터 다시 시작한다(`:557-559`). 설계 5.3(`:766-783`)과 VD-28(`:258-265`)은 정확하다 |
| 발생 조건 | 채택자가 CHANGELOG로 업그레이드 영향을 판단할 때 |
| 영향 | 조용한 stream도 초기화된다고 오해해 markValid 배선을 빠뜨릴 수 있다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 확인됨 |
| 결정의 근거 | 적용 제외 — 선택 비교가 필요한 문제가 아님 |
| 이해 비용 | 문장 하나 |
| 최소 개선 방향 | "유효 heartbeat·event를 받고 안정 유지 시간을 넘긴 세션이 끝나면 초기화한다. offline 동안의 시간은 elapsed 예산에 넣지 않는다"로 고친다 |
| 대안 비교 | 적용 제외 — 문장 교정 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | CHANGELOG, 설계 5.3, VD-28이 같은 조건을 말한다 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 지난 04-01·04-08 수정 때 CHANGELOG 요약만 따로 쓰였다 |
## 6. FOLLOW-UP 재확인
### 6.1 `FOLLOW-UP.md` 중 이 영역 항목
| 항목 | 결과 | 근거 |
| --- | --- | --- |
| 1절 P2 레시피 번들 예산 인상(realtime 40,000 → 40,900, `2c5e268`) | **유효** | 측정 40,886 / 40,900, 여유 14바이트. 늘어난 983바이트 중 lane D(realtime 수정)가 702, lane F(web-push)가 281이다. realtime 부분만 떼면 30,160 → 30,858이다. 원인은 지난 라운드 04-01~04-07 수정(관측 훅, bridge, chunk 분할, invalidate)이다. 측정은 tree-shaking을 끄므로 모든 코드가 그대로 잡힌다(`scripts/lib/optional-recipe-bundle.ts:61-64`, `:131-134`). 이번 라운드의 04-01·04-02를 고치면 다시 넘을 가능성이 높다. 줄일 대상은 이번에 찾지 않았다 |
FOLLOW-UP의 나머지 항목(초기 JS 예산, flaky 테스트 등)은 이 영역 밖이다. realtime은 production 번들에 들어가지 않는다.
### 6.2 지난 04 발견의 회귀 확인
| 지난 ID | 현재 | 근거 |
| --- | --- | --- |
| 04-01 오래 열린 연결의 재연결 중단 | 해소 | E1(10분 뒤 1초 offline → 재연결), E1b(같은 틱 offline/online), E2(1분 세션 12번 연속 → 시도 13회, 계속 RUNNING), E3(`waitClosed` 예외), 기존 테스트 `:1830-1913`. 변이 M1·M2·M3·M6 검출 |
| 04-02 SSE Retry-After 유실 | 해소(연결 전 실패 한정) | `readSseForReconnect`(`fetch-sse-connection.ts:487-506`), 변이 M5 검출. 열린 세션 부분은 04-02(이번)로 이어짐 |
| 04-03 모르는 이벤트 종류 | 해소 | `PROTOCOL_MISMATCH/REGISTRY`, freshness `UNKNOWN`. 변이 M7·M8·M9·M15 검출. WS 경로 테스트는 없다 |
| 04-04 hidden·logout·kill switch 책임 | 해소(문서) | `realtime-streams.ts:74-79`, `reconnect-coordinator.ts:106-113`, `:175-181`, 설계 5.4 머리 문단 |
| 04-05 256KB 초과 chunk | 해소 | `fetch-sse-connection.ts:423-446`, 변이 M10 검출 |
| 04-06 SSE idle timeout 테스트 | 해소 | 변이 M11 검출(테스트 2건 실패) |
| 04-07 관측 지점 | 해소 | `RealtimeReconnectObservation`, `BoundedPollObservation`. 변이 M12 검출. online 대기 중 관측이 없는 점은 04-01(이번)에 포함 |
| 04-08 VD-28·설계 5.3 불일치 | 해소 | `VD-28-…md:258-271`과 코드 일치. CHANGELOG 요약은 04-05(이번) |
### 6.3 변이 실험 목록
| ID | 변이 | 결과 |
| --- | --- | --- |
| M1 | 세션 종료 시 예산 초기화 제거 | 검출(4건 실패) |
| M2 | offline 뒤 elapsed 재시작 제거 | 검출(1건) |
| M3 | offline로 끝난 세션은 초기화 안 함 | 검출(1건) |
| M4 | 초기화 조건 `&&` → `||` | 검출(2건) |
| M5 | SSE bridge가 hint를 버림 | 검출(2건) |
| M6 | WS `HEARTBEAT_ACK` 관측 제거 | 검출(1건) |
| M7 | 모르는 이벤트 종류를 다시 `MALFORMED_EVENT` | 검출(2건) |
| M8 | consumer가 invalidate 안 함 | 검출(1건) |
| M9 | `invalidate` 무동작 | 검출(1건) |
| M10 | SSE chunk 분할 제거 | 검출(1건) |
| M11 | SSE `IDLE_TIMEOUT` retryable:false | 검출(2건) |
| M12 | `EXHAUSTED`를 `TERMINAL`로 보고 | 검출(1건) |
| M13 | EOF의 `retryHintMs` 기록 제거 | 검출(1건) |
| M14 | offline 대기 건너뛰기 | 검출(테스트 프로세스가 멈춤, 실패 요약 없음) |
| M15 | codec이 실패 stream을 기록 안 함 | 검출(2건) |
| C1 | recovery single-flight 제거 | 검출(1건) |
| C2 | run 동시 실행 허용 | 검출(2건) |
| C3 | 중단 뒤 늦게 온 세션 안 닫음 | 검출(4건) |
M1 변이에서도 실패 요약이 나온 뒤 vitest 프로세스가 끝나지 않았다. 실패한 테스트가 남긴 대기 때문으로 보인다. 원인은 이 영역 밖(10 영역)이라 여기서는 적기만 한다.
## 7. 미검증 목록
| 항목 | 확인하지 못한 이유 | 확인하려면 |
| --- | --- | --- |
| 04-01이 실제 브라우저·서버에서 같은 모양으로 나타나는지(fetch·reader 거절이 `TypeError`인지, `online` 이벤트가 오지 않는지) | 실제 스트리밍 서버와 브라우저 실행 없음 | 로컬 SSE 서버를 띄우고 Playwright에서 서버 프로세스를 죽였다 살리는 시나리오(설계 15.3 "server restart") |
| `test:realtime-removal` | pnpm이 필요하고, worktree의 `node_modules`가 메인 링크라 pnpm 실행이 메인 설치를 지울 위험이 있다(오케스트레이터 경고) | CI 또는 메인 트리에서 단독 실행 |
| 서버 재시작 직후 여러 클라이언트의 재연결 분포 | 부하 실험 없음. full jitter 공식은 코드와 단위 테스트로만 확인 | N개 클라이언트 시뮬레이션으로 초당 재연결 수 측정 |
| hidden 탭 타이머 throttling, bfcache 복귀, freeze | 브라우저 실행 없음 | Playwright에서 visibility·bfcache 시나리오 |
| 브라우저에서 SSE 파서·chunk 분할 성능 | Node 실험도 이번에는 다시 돌리지 않음 | 실제 브라우저 performance 측정 |
| WS 경로의 REGISTRY 실패 전달 | 코드로는 receipt에 같은 실패가 실린다(`websocket-connection.ts:1379-1384`). 테스트·실험은 SSE만 | `websocket-connection.test.ts`에 모르는 이벤트 종류 케이스 추가 |
| 레시피 번들을 줄일 수 있는 부분 | 증가 원인만 나눴고 줄일 대상은 찾지 않음 | lane D 추가분 702바이트의 파일별 측정 |
@@ -0,0 +1,464 @@
# 05 저장소·adapter kernel 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 수정본), 실행 순서는 `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/`, `src/application/ports/browser-file-storage/`, 관련 테스트
> 깊게 본 관점: 1, 11, 12, 22, 27, 28
> 영역 판정(35.8): **조건부 사용 가능.** kernel과 Web Storage 어댑터는 지정 범위에서 쓸 수 있다. IndexedDB 런타임은 개인 데이터 dataset에도 쓸 수 있다. 다만 릴리스 롤백 중 계정 삭제는 데이터가 남는다(05-05). OPFS 런타임은 "계정 삭제 뒤 기기에 바이트가 남지 않는다"를 요구하는 제품이라면 05-01·05-02를 고친 뒤 조합한다.
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`(태그 `v0.2.0` + docs 커밋 1개). 코드는 `af3d8e6`과 같다. 미커밋은 리뷰 가이드 문서 2개뿐이다 |
| 목적·실행 구성 | 템플릿 reference runtime. 브라우저 SPA + 정적 호스팅 + Service Worker. 여러 탭 동시 실행을 지원한다. SSR은 없다 |
| 조합 상태 | IndexedDB·OPFS 런타임은 `AVAILABLE_NOT_COMPOSED`다(`config/recipes/frontend-capability-recipes.json:76-102`). repo bootstrap은 조합하지 않는다. 제품 repo 2개(`tech-log-frontend`, `memento-frontend`, 둘 다 `chore/template-sync-v0.2.0`)도 소스만 복사했고 조합하지 않았다. 아래 결함은 **다운스트림이 이 런타임을 조합할 때** 복제된다. 심각도는 그 조합을 기준으로 매겼다 |
| 규모·운영 목표 | 없다. 13·14번은 미검증으로 둔다 |
| 읽은 코드 | kernel 전 파일(`platform/*.ts` 10개), `browser-file-storage/result.ts`·`storage-manager-adapter.ts`, IndexedDB 런타임(`indexeddb-runtime.ts`, `-maintenance`, `-governance`, `-records`), OPFS(`opfs-byte-store-adapter.ts`, `opfs-worker-runtime.ts`, `indexeddb-opfs-journal.ts`, `opfs-policy.ts`, `opfs-prepared-object.ts`), port 3개(`indexeddb-port.ts`, `opfs-ports.ts`, `shared.ts` 일부), `tests/helpers/memory-indexeddb.ts` 헤더, 05-0x 테스트, `recipes/frontend-capabilities/browser-file-storage-contracts.ts`·`-fakes.ts`의 durable object 부분, `.dependency-cruiser.json:241-251`, `docs/architecture/layers.md:38-52`, `docs/operations/browser-file-storage-recovery.md`의 05-0x 관련 절 |
| 주장으로만 읽은 것 | `CHANGELOG.md` 0.2.0 [보안]·[계약] 행, 지난 리뷰 `2026-09-25-maturity-review/05-*.md`, `FOLLOW-UP.md`, `tasks/todo.md:83` |
| 실행한 명령 | 모두 분리 worktree(`scratchpad/review-2026-09-29/05/wt`, `af3d8e6`)에서 했다. 메인 워킹트리에는 이 문서만 썼다.<br>① `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts` → **101/101 통과**<br>② `... indexeddb-runtime.test.ts indexeddb-maintenance.test.ts indexeddb-connection.test.ts` → **86/86 통과**<br>③ `node scripts/check-optional-recipes.ts` → `offline-indexeddb:36891/36900`, `realtime:40886/40900`, `file-transfer:55623/55700`<br>④ `node scripts/check-architecture.ts`(교차 import 2건 주입) → **2건 모두 `adapters-do-not-know-other-concrete-adapters`로 검출**<br>⑤ `node scripts/test-browser-file-storage-runtime-removal.ts` → 1회차 **실패**(`tests/component/router.test.tsx` "reaches the platform overview…", load average 약 21에서 기본 1초 `waitFor` 초과), 2회차 **PASS**(7개 기본 검사, 런타임 의존 테스트 55개 제거). **주의:** 처음에는 `corepack pnpm run test:browser-file-storage-removal`로 시작했고, pnpm이 symlink된 `node_modules`를 지우려다 no-TTY 가드(`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`)로 멈췄다. 메인 `node_modules`는 그대로다(항목 수·`.pnpm` 확인). 그 뒤 스크립트를 `node`로 직접 돌렸다. 드릴은 fixture 안에서 pnpm을 부른다(설치 검사 끔). 오케스트레이터의 2026-09-29 지시에 따라 이 드릴은 worktree에서 다시 돌리지 않는다. 이 결과를 증거로 받을지는 오케스트레이터가 정한다<br>⑥ Playwright(`indexeddb-runtime.spec.ts`, `opfs-runtime.spec.ts`, chromium·firefox, 별도 포트 4195) → **16/16 통과**. 두 엔진 모두 `inspectBrowserOpfsSupport`가 `available: true`여서 OPFS spec이 조기 반환 없이 실제로 돌았다 |
| 변이 실험 | 수정을 되돌리는 변이 7개를 넣고 해당 테스트를 돌렸다. **7개 모두 검출됐다.**<br>M1 reconcile이 transaction lock을 무시 → 05-01 테스트 2개 실패. M2 빈 receipt를 JSON으로 파싱 → 05-02 테스트 2개 실패. M3 reconcile이 첫 실패 row에서 멈춤 → 1개 실패. M4 purge의 chunk sweep 제거 → 05-04 테스트 2개 실패. M5 전체 DB 삭제 경로 제거 → 05-03 테스트 3개 실패. M6 `VersionError`를 다시 `MIGRATION_FAILED`로 → 05-06 테스트 1개 실패. M7 admission 중 versionchange 핸들러 제거 → 05-13 테스트 1개 실패.<br>예산 변이: reconcile 보고 뒤에 관측 이벤트 7줄 추가 → `offline-indexeddb (36909 > 36900 gzip bytes)`로 **게이트 실패**. `result.ts` `mapIndexedDbException`에 `case "TimeoutError":` 한 줄 추가 → 통과했지만 레시피 예산 3개가 함께 움직였다 |
| 재현 실험 | 실제 adapter·worker·journal 코드에 메모리 FS와 메모리 IndexedDB를 붙이고, Web Locks는 Node 24 내장 `navigator.locks`를 썼다. 파일: `scratchpad/review-2026-09-29/05/experiments/review05-*.appended.ts`(worktree 삭제 전 보관).<br>X1a·X1b·X1c(05-01 후속 단계), X2(purge vs 같은 객체 덮어쓰기), X3·X4·X5(손상 journal 행·receipt), I1~I4(IndexedDB purge 경계) |
| 확인하지 못한 범위 | WebKit 실행, 실제 quota 초과와 실제 저장소 손상, 2 GiB 객체 검증 시간, v0.1.0 탭과 v0.2.0 탭 공존, X2·X3를 실제 브라우저에서 재현, IndexedDB만 제거하는 드릴(7절) |
| 이전 리뷰와 비교 | 지난 발견 05-01~05-14는 모두 "해결"로 기록돼 있다. 현재 코드에서 다시 확인했고 회귀는 없다(6.2절). 새 발견은 수정 범위 밖에 남은 같은 계열의 빈틈이다 |
## 1. 요약
- **05-01(OPFS reconcile vs 진행 중 put)과 05-02(첫 receipt quota 실패 뒤 GC 정지)는 고쳐졌다.**
- 05-01: 테스트가 보는 PREPARING 단계 외에 FILES_READY(commit 대기)와 COMMITTED(finalize 대기) 단계에서도 다른 탭 reconcile이 row를 건너뛴다(X1a·X1b). 같은 탭 reconcile도 건너뛴다(X1c). 실제 브라우저 2탭 spec이 chromium·firefox에서 통과했다.
- 05-02: 0바이트 receipt는 없는 것으로 보고, reconcile은 실패 row를 세고 GC까지 간다. 두 수정 모두 되돌리면 테스트가 잡는다(M1~M3).
- **CHANGELOG 0.2.0 [보안]·[계약] 주장은 정상 경로에서 사실이다.** 손상된 budget·binding 행 때문에 열리지 않는 IndexedDB dataset은 승인된 LOGOUT·ACCOUNT_DELETION에서 통째로 지워진다(I4, Playwright). OPFS purge는 남은 chunk를 grace 없이 지운다. 미래 스키마는 `INCOMPATIBLE`/`ONLINE_ONLY`다.
- **그러나 삭제 보장에 빈틈이 셋 남았다.**
- OPFS journal의 목록 조회는 손상 행 하나에 전체가 실패한다. 그 partition의 계정 삭제 purge는 객체를 하나도 못 지우고, authority 전체의 reconcile·GC도 멈춘다(05-01, X3·X4·X5). IndexedDB 쪽에서 고친 "손상 한 건이 정리 전체를 막는" 패턴이 OPFS journal에는 남았다.
- 다른 탭이 같은 객체를 덮어쓰는 중에 purge가 돌면 그 객체를 건너뛴다. 그런데도 `moreObjectsAvailable: false`, `chunkSweep: "COMPLETED"`로 보고한다(05-02, X2).
- IndexedDB 전체 삭제 경로는 open 실패 코드 두 개에서만 열린다. 릴리스 롤백 중(`INCOMPATIBLE`)이나 migration 실패 중 계정 삭제는 데이터를 남긴다(05-05, I1).
- **kernel은 정책 저장소가 되지 않았다.** `platform/` 파일 집합은 지난 리뷰와 같다. 이번 라운드에 kernel로 들어간 것은 IndexedDB 예외표 하나이고, 브라우저 데이터 번들 안에서만 쓰인다. 현 상태 유지가 맞다(4.3절). 대신 kernel로 올릴 만한 canonical JSON이 3벌로 갈라져 있다(05-07). kernel 범위 문서가 실제보다 좁다(05-08).
- **같은 이름의 port가 두 벌이다.** `recipes/frontend-capabilities/browser-file-storage-contracts.ts`의 `DurableObjectStorePort`·`DurableObjectMaintenancePort`는 2026-07-30 이후 바뀌지 않았고 src port와 계약이 다르다. catalog는 그 fake를 이 런타임의 fake로 안내한다(05-03).
- **offline-indexeddb 레시피 예산 여유는 9바이트다.** 이 영역에 진단 코드 7줄만 넣어도 게이트가 실패한다(05-04).
## 2. 대표 흐름
### 2.1 정상 흐름 — OPFS put 하나와 다른 탭의 reconcile
```
tab A put ──► per-transaction Web Lock 획득 (adapter:219, :1026-1047)
│ │
│ ├─► journal.begin: PREPARING row + budget 예약 (journal:288-503)
│ ├─► worker BEGIN_PUT: origin 전역 lease 획득 (worker:365-399)
│ ├─► APPEND_CHUNK: chunk 쓰기 → receipt 갱신 (worker:422-478)
│ ├─► FINISH_PUT: manifest·FILES_READY receipt → lease 해제 (worker:480-556)
│ ├─► journal.markFilesReady → commitPut (journal:505-577)
│ ├─► worker FINALIZE_PUT: 이전 세대·staging 삭제 (worker:918-965)
│ └─► journal.complete: row 삭제 (journal:579-615)
└──► lock 해제 → 성공 보고
tab B reconcile ──► listIncomplete → 각 row lock을 ifAvailable로 시도 (adapter:630-648)
├─ 못 잡음 → skippedLiveTransactions += 1
└─ 잡음 → 같은 page를 다시 읽고 정리 (adapter:649-679) → orphan GC
```
- 입력: objectId, expectedGeneration, ByteSource.
- 정책: objectId 문법(`opfs-policy.ts:163-172`), media type, 크기, budget(`journal:457-465`).
- 상태 변화: journal row PREPARING → FILES_READY → COMMITTED → 삭제. committed object row와 chunk reference가 commit 트랜잭션에서 함께 바뀐다(`journal:872-1024`).
- 외부 I/O: OPFS 파일, IndexedDB journal, Web Locks.
- 실패: 보상 실패면 put 자기 코드 + recovery `RECONCILE`(`adapter:1064-1087`). commit 뒤 finalize 실패는 성공이 아니라 실패로 보고하고 row를 reconcile에 남긴다(`adapter:318-330`).
- 결과: 성공이면 open이 같은 바이트를 읽는다. 확인: 단위 테스트, X1a·X1b·X1c, Playwright 05-01 spec(chromium·firefox).
### 2.2 피해가 큰 흐름 — 승인된 ACCOUNT_DELETION purge
```
composition ──► IDB enforceLifecycleBatch(ACCOUNT_DELETION)
├─ 정책 허용? (runtime:2005-2033) → authority proof (runtime:2046-2077)
├─ 연결 없음 → open 시도 (runtime:2574-2579)
│ ├─ POLICY_REJECTED / CORRUPT_DATA → deleteDatabase (runtime:2580-2611) → datasetDeleted
│ ├─ MIGRATION_FAILED / UNSUPPORTED(INCOMPATIBLE) → 그 실패를 그대로 반환 (데이터 남음, 05-05)
│ └─ 성공 → 행 단위 purge (runtime:2281-2503)
──► OPFS enforcePolicies(ACCOUNT_DELETION)
├─ request + consume authority (adapter:886-995)
├─ listCommittedObjects page → objects.remove 각각 (adapter:785-848)
│ ├─ CONFLICT / NOT_FOUND → 건너뜀 (adapter:820-823) ← 05-02
│ └─ 손상 row → 목록 전체 CORRUPT_DATA (journal:785-794) ← 05-01
└─ 남은 객체 없음으로 판단되면 grace 없는 chunk sweep (adapter:849-873)
```
- 입력: action, maxRows/maxObjects, 시간 예산.
- 정책: dataset의 `accountDeletionAction`이 `PURGE_PARTITION`이어야 한다. 삭제마다 composition 승인이 필요하다.
- 상태 변화: IDB 행 또는 DB 전체 삭제. OPFS 객체 디렉터리 삭제, journal object row·chunk reference 갱신, chunk 파일 삭제.
- 실패: 손상 governance(IDB)는 DB 삭제로 끝난다. 손상 journal row(OPFS)는 purge 전체 실패로 끝나고 바이트가 남는다(X3). 동시 덮어쓰기는 건너뛰고 완료로 보고된다(X2).
- 결과: 정상 경로에서는 partition 파일 0개(05-04 테스트). 위 두 경우에는 개인 바이트가 남는다.
### 2.3 변경·삭제 흐름 — IndexedDB `schemaVersion`을 올리는 새 release
```
새 release 탭(v2) open ──► upgrade: 추가만 하는 DDL + binding 확인 (runtime:693-717, governance:167-222)
구 release 탭(v1) 연결 ──► versionchange → kernel이 닫음 (connection:483-489)
구 release 탭 재open ──► VersionError → UNSUPPORTED / ONLINE_ONLY, status INCOMPATIBLE (runtime:662-675, :767-775)
구 release 탭 read/CAS/purge ──► UNSUPPORTED (runtime:865-867)
```
- admission이 도는 동안 온 versionchange도 이제 연결을 닫는다(`connection:430-439`, 05-13). M7로 되돌리면 테스트가 잡는다.
- 롤백 배포(모든 탭이 v1)라면 모든 purge가 `UNSUPPORTED`로 끝난다. v2를 다시 배포할 때까지 계정 삭제 데이터가 남는다(05-05).
- 번들 삭제: `test-browser-file-storage-runtime-removal.ts`가 ports·browser-files·browser-transfer·cache-storage·storage/indexeddb·storage/opfs를 함께 지우고 타입·lint·아키텍처·test:all·build·레시피·CI 계약을 돈다. 2회차 PASS. 1회차 실패는 부하 중 component 테스트의 1초 대기 초과였다(영역 10·11 소관).
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 통제(목표/확인) | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | O | M2 / M2 | E2(101+86 통과), E2 변이 M1~M7 | CAS·revision·generation·fencing 규칙이 put·remove·CAS·reconcile 경로에서 지켜진다(`adapter:204-216`, `journal:395-407`). 05-01 수정이 세 단계에서 유지된다(X1a·b·c). 보고값의 정확성 문제는 11·24에서 센다(05-02) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E3(교차 import 2건 주입 → 2건 검출) | kernel 예외 밖 교차 import 0건(`grep` 전수). 같은 `storage` 그룹 안 indexeddb↔opfs import는 규칙이 보지 않는다. 지금은 0건이다(05-11 해소) |
| 3 | 변경 용이성 | P | M3 / M3 | E3(예산 측정·변이) | 진단 7줄 추가가 레시피 예산 게이트에 막힌다(05-04). 제품이 OPFS 이름을 adapter 소스에서 고쳐 들고 다닌다(05-10) |
| 4 | 인지 부하 | P | — | E1 | 파일 4개가 1.7k~2.6k줄이다(`indexeddb-runtime.ts` 2641줄). journal `begin`은 요청 콜백이 7단 중첩된다(`indexeddb-opfs-journal.ts:301-500`). 대신 05-0x 수정 주석이 "왜"를 가까이 적는다(`adapter:630-633`, `worker:1303-1308`) |
| 5 | 위험 가시성 | P | M1 / M1 | E1 | port 주석이 origin 전역 쓰기 직렬화(`opfs-ports.ts:79-84`), 교체된 세대의 stream `NOT_FOUND`(`:87-95`), `INCOMPATIBLE`(`indexeddb-port.ts:46-52`)을 드러낸다. `chunkSweep`(`opfs-ports.ts:136-141`)과 `datasetDeleted`(`indexeddb-port.ts:154-160`) 설명은 실제 동작과 다르다(05-02, 05-05) |
| 6 | 실패 성숙도 | P | M2 / M2 | E2 | "건너뛰고 세고 보고한다"가 retention sweep·receipt prune·reconcile 루프에 적용됐다. journal 목록 조회는 여전히 손상 행 하나에 전체가 실패한다(05-01) |
| 7 | 운영 성숙도 | P | M1 / M1 | E1 | safe bucket 관측(`observe`)과 연결점만 있다. 조합이 없어 알림 경로는 없다(0.1 전제상 비대상) |
| 8 | 디버깅 가능성 | P | M2 / M2 | E2 | receipt 손상이 `CORRUPT_DATA`로, 미래 스키마가 `INCOMPATIBLE`로 바로잡혔다. reconcile 보고에 `skippedLiveTransactions`·`failedTransactions`가 있다. purge 보고에는 건너뛴 객체 수가 없다(05-02) |
| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | IndexedDB 예외표가 1벌이 됐다(`result.ts:110-171`, 05-11 해소). canonical JSON 3벌·`sameScope` 2벌(05-07), kernel 범위 문서가 낡았다(05-08) |
| 10 | 테스트 성숙도 | P | M3 / M3 | E2(변이 7/7 검출), E3(Playwright 16/16) | 메모리 IndexedDB가 DB 이름 분리·트랜잭션 직렬화·비활성 요청 예외를 흉내 내고, 흉내 내지 않는 것을 헤더에 적는다(`memory-indexeddb.ts:849-876`). 빈틈: purge vs 동시 덮어쓰기, 손상 journal 행, binding 손상 행(FOLLOW-UP), recipe fake가 다른 계약을 구현(05-03) |
| **11** | 데이터 성숙도 | P | M3 / M2 | E2(X2·X3·I1·I4), E3(Playwright 05-03·05-06) | 손상 governance의 DB 삭제와 미래 스키마 처리는 실제 브라우저에서 확인했다. OPFS purge는 손상 행에 막히고(05-01), 동시 덮어쓰기에서 완료로 잘못 보고한다(05-02). 롤백·migration 실패 중 계정 삭제는 데이터를 남긴다(05-05) |
| **12** | 동시성 성숙도 | P | M3 / M3 | E2(X1a·b·c, M1), E3(Playwright 05-01 chromium·firefox) | 05-01 수정이 후속 단계에서도 유지된다. 잔여: purge와 같은 객체 쓰기의 경합(05-02), lock 이름이 다른 release 탭 공존(미검증), idle bound와 lock wait 관계 미검사(05-09) |
| 13 | 확장성 | ? | — | E1 | 규모 목표가 없다. 코드에는 배치 상한(500행/30초, 스캔 5000행, reconcile 100행/5초)만 있다 |
| 14 | 성능 성숙도 | ? | — | E1 | 2 GiB 객체 검증 시간, dedup 재쓰기 비용을 측정하지 않았다. 번들 크기는 05-04 |
| 15 | 보안 성숙도 | P | M2 / M2 | E2 | opaque DB·경로 이름(`governance:71-83`, `worker:1636-1643`), 관측에서 key·값 제외, 삭제마다 승인. 계정 삭제 뒤 잔존 경로 셋(05-01·05-02·05-05). 두 런타임의 승인 계약이 다르다(05-06) |
| 16 | 의존성 성숙도 | - | — | — | 이 영역은 외부 패키지 없이 브라우저 API만 쓴다 |
| 17 | API / Contract | P | M2 / M2 | E1 | port 변경은 추가만 했고 CHANGELOG [보안]·[계약]에 있다(`CHANGELOG.md:30`, `:42`). 같은 이름의 recipe port가 다른 계약이다(05-03). 주석과 코드가 다른 곳 둘(05-02·05-05) |
| 18 | 배포 성숙도 | P | M2 / M2 | E3(Playwright 05-06) | N-1 탭이 `INCOMPATIBLE`/`ONLINE_ONLY`로 닫힌다. transaction lock이 없는 v0.1.0 탭과 공존하면 그 탭의 put은 보호받지 못한다(미검증, 7절) |
| 19 | 설정 성숙도 | P | M3 / M2 | E1, 실행(`resolveOpfsRuntimePolicy`) | objectId 문법 확장 거절(05-10 해소). `putIdleTimeoutMs < mutationLockWaitTimeoutMs`는 검사하지 않는다(05-09). journal DB 접두사를 설정으로 바꿀 수 없다(05-10) |
| 20 | 개발자 경험 | > | — | — | 영역 14 |
| 21 | Guardrail 성숙도 | P | M3 / M3 | E3(아키텍처 주입, 제거 드릴, 예산 변이) | 세 게이트 모두 동작한다. 예산 게이트는 여유 9바이트라 신호보다 마찰이 크다(05-04). 제거 드릴은 부하 중 타이밍 테스트 하나로 한 번 실패했다 |
| **22** | 추상화 성숙도 | P | M2 / M2 | E3(주입), E1 | kernel은 메커니즘만 갖고 정책·실패 코드는 호출자 `translate`에 둔다(`indexeddb-connection.ts:19-24`, `:42-80`). 현 상태 유지가 맞다(4.3절). 갈라진 중복(05-07), 낡은 범위 문서(05-08), 같은 이름 recipe port(05-03), 두 승인 계약(05-06) |
| 23 | 일관성 | P | M1 / M1 | E1 | 승인 proof 정규식이 `{16,128}`(`indexeddb-runtime.ts:97`)와 `{16,512}`(`opfs-byte-store-adapter.ts:1785`)로 다르다. 비유한 수 처리가 canonical JSON마다 다르다(05-06, 05-07) |
| 24 | 네이밍 / 의미 | P | M1 / M1 | E2(X2) | `chunkSweep: "COMPLETED"`는 "partition이 비었다"로 읽히지만 객체가 남을 수 있다(05-02). `datasetDeleted` 설명의 적용 범위가 코드와 다르다(05-05) |
| 25 | 조직 확장성 | ? | — | E0 | 팀이 하나다. dataset별 opaque scope와 kernel 공유 구조만 준비돼 있다 |
| 26 | Ownership | ? | — | E0 | runbook owner 칸을 조합 branch가 채운다. 조합이 없어 확인할 대상이 없다 |
| **27** | 삭제 가능성 | P | M3 / M3 | E3(제거 드릴 2회차 PASS, 실행 조건은 0절 ⑤ 주의) | 번들 코드 제거는 검증된다. 기기 데이터 삭제는 IDB 쪽이 확인됐다. OPFS는 손상 행·동시 쓰기에서 바이트가 남는다(05-01·05-02). IndexedDB만 제거하는 경우는 드릴 밖이고 그 사실이 주석에 있다(`storage/index.ts:1-10`) |
| **28** | 회복 가능성 | P | M2 / M2 | E2(M2·M3, X4·X5) | 흔한 원인(quota로 남은 빈 receipt)의 영구 정지는 풀렸다. 손상 journal 행이나 읽을 수 없는 receipt는 authority 전체 reconcile·GC를 멈춘다. runbook은 row 수동 삭제와 DB 삭제를 금지하므로 승인된 탈출 경로가 없다(05-01) |
적용 항목 26개(16 제외, 20은 영역 14): 충족 2(1, 2), 부분 충족 20, 미충족 0, 미검증 4(13, 14, 25, 26).
## 4. 설계 선택 설명 (41)
각 항목에서 **[사실]**은 현재 코드·실행 결과, **[기록]**은 코드 주석·문서에 적힌 의도, **[추론]**은 리뷰어의 해석이다.
### 4.1 OPFS 동시성: origin 전역 lease + transaction별 Web Lock (05-01, D-3)
1. **필요:** 같은 origin의 여러 탭이 같은 OPFS root와 journal을 쓴다. 앱 시작 때 reconcile을 돌리는 조합이 흔하다. **[사실]** journal DB는 authority 단위이고 `listIncomplete`는 scope로 거르지 않는다(`journal:685-741`).
2. **지킬 성질:** 성공으로 보고한 put은 읽혀야 한다. reconcile은 주인이 사라진 row만 정리해야 한다. GC는 참조 중이거나 staging 중인 chunk를 지우면 안 된다. 탭이 죽으면 잠금이 풀려야 한다.
3. **현재 보장:** **[사실]** worker는 BEGIN~FINISH 동안 origin 전역 lease를 쥔다(`worker:365-399`, `:545-548`). page는 journal `begin` 전부터 반환까지 transaction별 Web Lock을 쥔다(`adapter:219-364`, `:1003-1047`). reconcile은 row lock을 `ifAvailable`로 잡고, 잡은 뒤 page를 다시 읽는다(`adapter:630-682`). **[사실]** X1a(commit 대기)·X1b(finalize 대기)·X1c(같은 탭)에서 row를 건너뛰고 put이 읽혔다. M1 변이는 테스트 2개가 잡았다. Playwright 05-01 spec이 chromium·firefox에서 통과했다. **보장하지 않는 것:** lock 이름은 `policy.mutationLockName`에서 나온다(`adapter:1012`). release마다 이 값이 다르거나 v0.1.0 탭(transaction lock 없음)과 섞이면 보호가 없다. 쓰기 처리량은 origin 전체에서 하나다.
4. **대안:** (a) 시작한 지 N분 지난 row만 정리한다. (b) journal에서 fencing token을 CAS로 넘겨받고 heartbeat로 주인 생존을 본다. (c) reconcile도 origin lease 아래서만 돈다. (d) 객체별 lock.
5. **비교:** (a)는 시계에 기대고 느린 put을 죽은 put과 구분하지 못한다. 성질 1을 깨뜨릴 수 있다. (b)는 heartbeat 주기와 만료 판단이 새로 생긴다. (c)는 lease가 FINISH에서 풀리므로 FILES_READY~complete 구간을 막지 못한다. 막으려면 origin 직렬화가 commit까지 길어진다. (d)는 chunk가 객체 사이에서 dedup되므로 GC 경합을 막지 못한다.
6. **현재 조건에서의 선택 이유:** **[추론]** Web Locks는 탭이 죽으면 브라우저가 풀어 준다. 그래서 크래시 복구에 시계도 heartbeat도 필요 없다. 비용은 lock 이름 규칙 하나와 reconcile의 재조회 한 번이다. **[기록]** "The lock stays origin-wide so GC and dedup keep seeing one writer; only the wait is bounded"(`worker:1355-1359`), `tasks/todo.md:83`.
7. **재검토 조건:** Web Locks가 없는 realm이 같은 journal을 써야 할 때. release마다 lock 이름을 바꾸는 운영이 생길 때. 여러 탭의 동시 업로드 처리량이 요구될 때(D-3 재검토).
**판단:** 유지한다. 다만 lock 이름이 release 사이에 같아야 한다는 조건을 `opfs-policy.ts`의 `mutationLockName` 설명에 적으면 다음 수정자가 알 수 있다(작은 보강, 발견으로 세지 않음).
### 4.2 승인된 purge에서 DB 전체를 지우는 조건 (05-03)
1. **필요:** LOGOUT·ACCOUNT_DELETION 뒤 기기에 개인 데이터가 남으면 안 된다. 행 단위 purge는 open(admission)이 성공해야 돈다.
2. **지킬 성질:** 승인 없이 지우지 않는다. 다른 partition을 건드리지 않는다. 정상 경로에서 다른 탭의 연결을 끊지 않는다. 결과를 사실대로 보고한다.
3. **현재 보장:** **[사실]** 승인(`runtime:2526-2527`) 뒤 연결이 없으면 open을 시도하고, `POLICY_REJECTED`·`CORRUPT_DATA`일 때만 `deleteDatabase`를 부른다(`runtime:2574-2611`). DB 이름은 partition 토큰 셋에서만 만든다(`governance:71-83`). **[사실]** budget 손상(테스트·Playwright)과 binding 손상(I4) 모두 `datasetDeleted: true`로 끝났다. **보장하지 않는 것:** `MIGRATION_FAILED`·`UNSUPPORTED`(I1)에서는 지우지 않는다. `else` 분기라 SESSION_END에도 적용된다(I2). OPFS에는 같은 경로가 없다(05-01).
4. **대안:** (a) 현상 유지. (b) 승인된 LOGOUT·ACCOUNT_DELETION이면 `BLOCKED`를 뺀 모든 open 실패에서 지운다. (c) purge를 항상 DB 삭제로 한다. (d) admission을 건너뛰고 읽을 수 있는 행만 지우는 open 모드.
5. **비교:** (b)는 롤백 창과 migration 실패에서도 개인 데이터를 지운다. 대신 `EXPORT_THEN_PURGE` dataset에서 export하지 못한 데이터도 지운다. 그 판단은 authority가 해야 한다. (c)는 단순하다. 하지만 정상 경로에서도 다른 탭의 연결을 versionchange로 끊고, governance 행을 다시 만들어야 한다. (d)는 손상됐을 수 있는 DB를 여는 두 번째 open 경로가 생긴다.
6. **선택 이유:** **[기록]** "A LOGOUT or ACCOUNT_DELETION purge must not depend on the dataset passing admission"(`runtime:2566-2573`), runbook "runtime이 스스로 DB를 지우는 경우는 하나뿐이다"(`browser-file-storage-recovery.md:275-289`). **[추론]** 정상 경로는 행 단위로 두고, 영영 열리지 않는 경우만 전체 삭제로 보내는 선택은 타당하다. 제외한 두 코드의 이유는 기록에 없다.
7. **재검토 조건:** 릴리스 롤백 절차를 문서로 정할 때. `EXPORT_THEN_PURGE` dataset이 실제로 조합될 때. OPFS 쪽에 같은 경로를 만들 때.
**판단:** 선택은 유지하되 적용 범위를 정하고 문서를 맞춘다(05-05).
### 4.3 kernel 경계: 메커니즘만 공유하고 정책은 호출자에 둔다
1. **필요:** **[기록]** IndexedDB 사용처 4곳이 open·blocked·upgrade·늦은 연결 처리를 손으로 복제했다(`indexeddb-connection.ts:1-10`). abort 경쟁·Retry-After 파싱·JSON 멤버 스캔도 여러 그룹에 필요하다.
2. **지킬 성질:** kernel은 DB 이름·스키마·실패 코드표·관측 형태를 모른다. adapter는 kernel 밖의 다른 adapter를 import하지 않는다.
3. **현재 보장:** **[사실]** `platform/` 파일 10개는 `4626b73`과 같다(`git ls-tree`). 이번 라운드의 kernel 변화는 `result.ts`에 IndexedDB 예외표가 들어온 것(+81줄)과 05-13 핸들러(+16줄)뿐이다. `translate` 콜백이 실패 코드를 호출자에 둔다(`indexeddb-connection.ts:42-80`). 교차 import 주입 2건이 검출됐다. 소비자: `abortable-operation.ts`는 7개 그룹 21개 파일, `result.ts`는 4개 그룹 30개 파일, IndexedDB kernel은 storage와 browser-transfer 체크포인트(`grep`). **보장하지 않는 것:** `result.ts`의 두 예외표는 정책(복구 힌트)이다. 다만 둘 다 browser-file-storage 번들 안에서만 쓰이고 번들과 함께 지워진다. kernel 편입 기준은 한 파일 머리말에만 있다(05-08).
4. **대안:** (a) 현상 유지. (b) IndexedDB kernel을 `storage` 그룹 안으로 내린다. (c) 예외표를 각 adapter로 되돌린다. (d) kernel을 별도 패키지로 뺀다.
5. **비교:** (b)는 browser-transfer 체크포인트가 storage를 import할 수 없어 복제가 다시 생긴다. (c)는 05-11에서 두 표의 차이가 이미 결함이었다. (d)는 강제력이 커지지만 이행 비용이 템플릿 규모에 비해 크다.
6. **선택 이유:** **[추론]** 현재 조건에서 유지가 맞다. kernel에 쌓인 것은 상태 기계와 파서이고, 업무 정책은 없다. 감수하는 비용은 파급 범위다. `result.ts`에 `case` 한 줄을 더하는 변이가 레시피 예산 3개(file-transfer 55623→55626, offline-indexeddb 36891→36893, service-worker-pwa 9662→9668)를 함께 움직였다(05-04).
7. **재검토 조건:** 재시도 값·관측 이벤트 형태 같은 도메인 판단이 kernel로 들어오려 할 때. 한 그룹만 쓰는 코드가 kernel에 들어올 때. kernel 변경이 레시피 예산을 반복해서 깰 때.
**판단:** 현 상태 유지. 문서 보강(05-08)과 canonical JSON 통합(05-07)만 권한다.
## 5. 발견 사항 (36.3)
| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 05-01 | Medium | P2 | 확인된 결함 | 11, 28, 15, 6, 27 | OPFS journal·staging의 손상 한 건이 그 partition의 계정 삭제 purge와 authority 전체의 reconcile·GC를 멈춘다 |
| 05-02 | Medium | P2 | 확인된 결함 | 11, 12, 15, 24, 5, 8 | purge가 지우지 못한 객체를 건너뛰고도 `chunkSweep: "COMPLETED"`로 보고한다 |
| 05-03 | Medium | P2 | 확인된 결함 | 22, 23, 17, 10, 9 | recipe의 같은 이름 port·fake가 src port와 다른 계약으로 갈라져 있다 |
| 05-04 | Low | P2 | 구조적 위험 | 3, 21, 14 | offline-indexeddb 레시피 예산 여유 9바이트: 이 영역의 다음 수정이 게이트에 막힌다 |
| 05-05 | Low | P3 | 확인된 결함 | 11, 15, 17, 24 | IndexedDB 전체 삭제 경로의 적용 범위가 port·runbook 설명과 다르다 |
| 05-06 | Low | P3 | 개선 제안 | 22, 23, 15 | 한 레시피의 두 런타임이 삭제 승인 계약을 다르게 요구한다 |
| 05-07 | Low | P3 | 개선 제안 | 22, 9, 23 | kernel로 올릴 canonical JSON이 3벌로 갈라져 있다 |
| 05-08 | Low | P3 | 확인된 결함 | 22, 9, 2 | kernel 범위 설명이 실제보다 좁고 편입 기준이 한 파일에만 있다 |
| 05-09 | Low | P3 | 확인된 결함 | 19, 12 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 |
| 05-10 | Low | P3 | 개선 제안 | 19, 3 | OPFS journal DB 이름 접두사를 설정으로 바꿀 수 없어 제품이 소스를 고친다 |
### 05-01 OPFS journal·staging의 손상 한 건이 그 partition의 계정 삭제 purge와 authority 전체의 reconcile·GC를 멈춘다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 11, 28, 15, 6, 27 |
| 근거 | ① `listCommittedObjects`는 손상 행 하나에 `context.fail(corrupt)`로 목록 전체를 실패시킨다(`indexeddb-opfs-journal.ts:785-794`). purge는 그 실패를 그대로 반환한다(`opfs-byte-store-adapter.ts:797-799`).<br>② `listIncomplete`도 같다(`indexeddb-opfs-journal.ts:714-723`). reconcile은 row를 하나도 보지 못하고 GC 전에 반환한다(`adapter:592-595`).<br>③ `isChunkReferenced`도 손상 참조 행에 실패하고, GC·sweep은 그 자리에서 멈춘다(`journal:849-855`, `adapter:1264-1266`, `:867`).<br>④ 비어 있지 않은 읽을 수 없는 receipt는 staging을 "unsafe"로 만들어 GC를 영구히 `STAGING_STATE_UNREADABLE`로 둔다(`worker:1130-1135`, `:893-903`).<br>⑤ 재현(메모리 FS·IndexedDB, Node Web Locks):<br>X3 — 객체 2개 중 하나의 object row를 손상 → `enforcePolicies(ACCOUNT_DELETION)` = `CORRUPT_DATA/READ_ONLY`, partition 파일 4개(정상 객체 포함)가 그대로, 정상 객체 `object_secret_1`을 여전히 읽을 수 있었다.<br>X4 — 손상 journal row 1개 → `reconcile` = `CORRUPT_DATA`, orphan chunk 남음.<br>X5 — 내용이 깨진 receipt → reconcile 2회 모두 `failedTransactions: 1`, `orphanGcStatus: "STAGING_STATE_UNREADABLE"`, 같은 id 재시도 `CONFLICT` |
| 발생 조건 | journal의 object·journal·chunk reference 행 하나가 validator를 통과하지 못할 때(저장소 손상, 또는 새 release가 row 모양을 바꿨는데 구 탭이 읽을 때). receipt 파일 내용이 깨졌을 때. 원자적 쓰기 때문에 정상 동작에서는 생기지 않는다 |
| 영향 | ① 계정 삭제·로그아웃 purge가 그 partition의 **정상 객체까지** 하나도 지우지 못한다. 개인 바이트가 기기에 남는다. ② journal DB는 authority 단위라 손상 행 하나가 authority의 모든 partition에서 reconcile·GC를 멈춘다. quota가 회수되지 않는다. ③ runbook은 journal row 수동 삭제와 journal DB·OPFS root 삭제를 금지한다(`browser-file-storage-recovery.md:37-40`). 승인된 탈출 경로가 없다. IndexedDB 런타임에는 같은 상황의 출구(05-03 전체 삭제)가 생겼지만 OPFS에는 없다 |
| 심각도·우선순위 | Medium · P2. 손상이 있어야 생기고 피해는 기기 한 대다. 하지만 계정 삭제 계약이 걸렸고, 한번 생기면 스스로 풀리지 않는다. 지난 리뷰의 같은 계열 IndexedDB 결함(05-03)과 같은 등급이다. 개인 파일을 다루는 OPFS 조합 전에 고친다 |
| 통제·증거 | "승인된 purge는 손상이 있어도 끝난다" 규칙: M0 확인(목록 실패 뒤 진행할 코드 경로가 없음) · E2(X3·X4·X5). 실제 브라우저 손상은 미검증 |
| 확실성과 남은 가정 | 경로는 코드와 재현으로 확인했다. 실제 기기에서 journal 행이 손상되는 빈도는 모른다. X5의 "내용이 깨진 receipt"는 원자적 쓰기에서는 저장소 손상으로만 생긴다고 본다 |
| 결정의 근거 | [기록] 손상 데이터는 자동 삭제하지 않는다(runbook "corrupted user-authored row 자동 삭제 0", `worker:894` "Keep unreadable staging in place so orphan GC fails closed"). [추론] fail-closed 자체는 맞다. 문제는 범위다. 행 하나가 목록 전체와 authority 전체를 막는다. 05-02·05-05에서 이미 "건너뛰고 세고 보고한다"로 바꾼 것과 같은 판단이 journal 목록에는 적용되지 않았다 |
| 이해 비용 | 운영자는 `CORRUPT_DATA/READ_ONLY`만 본다. 어느 행인지, 어느 partition이 막혔는지 보고가 없다. 다운스트림은 journal 코드를 읽어야 원인을 안다 |
| 최소 개선 방향 | ① `listCommittedObjects`·`listIncomplete`는 손상 행을 건너뛰고 세어 보고한다(행은 지우지 않는다). ② 승인된 LOGOUT·ACCOUNT_DELETION에 한해, 손상 때문에 purge를 끝낼 수 없으면 그 partition 디렉터리(`authorities/<a>/<ns>/<p>`)를 mutation lease 안에서 통째로 지우고 journal의 그 partition 행을 정리한다. 05-03의 IndexedDB 경로와 같은 승인 조건을 쓴다 |
| 대안 비교 | (a) 현상 유지: 손상 시 삭제 계약이 영구히 깨진다. (b) ①만: reconcile·GC와 정상 객체 purge는 계속된다. 손상 행의 바이트는 남는다. (c) ①+②: 계정 삭제가 끝난다. partition 디렉터리 삭제는 진행 중인 같은 partition put과 경합하므로 lease 안에서 해야 한다. (d) journal DB 전체 삭제: authority의 다른 partition까지 지우므로 부적합 |
| 단순화의 보존 조건 | 손상 행을 자동 수정·삭제하지 않는다(승인된 partition purge 제외). 다른 partition의 행·파일을 건드리지 않는다. 건너뛴 행은 관측으로 보고한다 |
| 비용·부작용 | 목록 API 결과에 "건너뛴 행 수"가 늘어난다(추가만). partition 전체 삭제 경로는 새 위험 경로이므로 승인과 lease 조건을 테스트로 고정해야 한다 |
| 재검토 조건 | journal row 모양을 release 사이에 바꾸는 변경이 생기면(구 탭이 새 행을 손상으로 볼 수 있다) 우선순위를 올린다 |
| 완료 기준 | object row 하나를 손상시킨 partition에서 승인된 ACCOUNT_DELETION이 partition 파일 0개로 끝난다. 손상 journal row 하나가 있어도 reconcile이 나머지 row와 GC를 진행하고 손상 1건을 보고한다 |
| 검증 방법 | X3·X4를 단위 테스트로 옮긴다(`experiments/review05-opfs.appended.ts`). 가능하면 Playwright OPFS spec에 X3을 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-02 purge가 지우지 못한 객체를 건너뛰고도 `chunkSweep: "COMPLETED"`로 보고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현) |
| 관련 관점 | 11, 12, 15, 24, 5, 8 |
| 근거 | ① purge는 `remove`가 `CONFLICT`·`NOT_FOUND`면 그 객체를 건너뛴다(`opfs-byte-store-adapter.ts:820-823`). 다시 목록을 읽지 않는다.<br>② chunk sweep 조건은 "남은 객체가 없다"가 아니라 `!moreObjectsAvailable && !deadlineReached && !aborted`다(`adapter:855-861`).<br>③ port 주석은 "once every object is removed"라고 적고, "Chunk bytes are gone only when it is `COMPLETED`"라고 약속한다(`opfs-ports.ts:136-141`). runbook도 "`chunkSweep`이 `COMPLETED`여야 bytes가 지워진 것이다"라고 적는다(`browser-file-storage-recovery.md:431-435`).<br>④ 재현 X2: 탭 W가 `object_secret_1`을 덮어쓰는 동안 탭 P가 `ACCOUNT_DELETION` purge → 보고 `{inspectedObjects: 1, removedObjects: 0, moreObjectsAvailable: false, chunkSweep: "COMPLETED"}`. purge 뒤 partition에 manifest와 chunk가 남았고, 객체(gen 2)를 그대로 읽을 수 있었다. 두 번째 purge가 지웠다 |
| 발생 조건 | purge가 도는 동안 다른 탭(같은 사용자의 다른 탭 등)이 같은 객체에 put·remove를 진행 중일 때. 그 put이 진행 중이면 journal의 logical key unique 제약으로, 이미 commit됐으면 세대 불일치로 purge의 `remove`가 `CONFLICT`가 된다(`journal:487-494`, `adapter:480-489`) |
| 영향 | 계정 삭제 뒤 개인 파일이 남는데, 보고는 완료로 읽힌다. `inspectedObjects - removedObjects`로 짐작할 수는 있지만 port·runbook 어디에도 그 신호가 적혀 있지 않다. 호출자는 재시도할 이유를 모른다 |
| 심각도·우선순위 | Medium · P2. 경합 조건이 필요하지만 로그아웃은 여러 탭이 열린 상태에서 흔하게 일어난다. 피해가 개인정보 잔존이고, 거짓 완료 보고라 발견이 늦다 |
| 통제·증거 | "purge 완료 보고는 partition이 비었을 때만" 규칙: M1(주석·runbook에만 있음) · E2(X2) |
| 확실성과 남은 가정 | 코드 경로와 재현이 일치한다. 실제 브라우저 재현은 하지 않았다. 같은 조건은 remove의 `NOT_FOUND` 뒤 다른 탭이 같은 id를 새로 만드는 순서에서도 생길 수 있다(코드로만 판단) |
| 결정의 근거 | 적용 제외 — 문서화된 계약과 구현이 다른 단순 결함이다. purge가 point-in-time이라는 성질 자체(끝난 뒤 새로 쓴 객체는 남는다)는 IndexedDB purge와 같아서 문제로 보지 않는다. 문제는 **본 객체를 못 지우고도** 완료로 보고하는 것이다 |
| 이해 비용 | 조합 코드 작성자가 port 주석을 믿으면 재시도 루프를 만들지 않는다 |
| 최소 개선 방향 | 건너뛴 객체가 있으면 `moreObjectsAvailable: true`로 보고하고 chunk sweep을 하지 않는다(`chunkSweep` 생략). 또는 `skippedObjects` 수를 보고에 추가하고 주석·runbook의 완료 조건을 "`skippedObjects === 0` 그리고 `chunkSweep === COMPLETED`"로 고친다 |
| 대안 비교 | 적용 제외 — 기대 계약(주석)이 이미 있다. 두 방향 모두 추가만 하는 변경이다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 작다. purge를 한 번 더 부르는 경우가 늘어난다 |
| 재검토 조건 | 적용 제외 — 선택을 바꾸는 판단이 아니다 |
| 완료 기준 | X2 순서에서 purge 보고가 미완료를 드러내고, 같은 purge를 다시 부르면 partition 파일 0개로 끝난다 |
| 검증 방법 | X2를 `opfs-worker-runtime.test.ts`의 05-04 describe에 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-03 recipe의 같은 이름 port·fake가 src port와 다른 계약으로 갈라져 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (갈라진 중복 복사본) |
| 관련 관점 | 22, 23, 17, 10, 9 |
| 근거 | ① `recipes/frontend-capabilities/browser-file-storage-contracts.ts`는 `DurableObjectStorePort`(`:590-622`), `DurableObjectMaintenancePort`(`:632-639`), `StorageDurabilityPort`, `FilePickerPort` 등을 src port와 **같은 이름**으로 다시 정의한다. 마지막 변경은 `6c52cdb9`(2026-07-30)이다.<br>② 계약이 다르다. recipe `put`은 `id`·`declaredByteLength`·`dataClass`를 받고, `open(id)`이고, `reconcile({timeBudgetMs, maxEntries, cursor})`는 `{resumedCount, purgedCount, quarantinedCount}`를 돌려준다. src는 `open(request)`, `reconcile({budgetMs, maxTransactions})` → `OpfsReconciliationReport`, `enforcePolicies`가 있다(`opfs-ports.ts:77-193`).<br>③ 의미도 반대다. recipe 보고는 resume·quarantine을 세지만, 런타임은 PREPARING을 resume하지 않고 FILES_READY 검증 실패를 quarantine하지 않는다(05-09 수정, `browser-file-storage-recovery.md:418-427`).<br>④ catalog의 offline-indexeddb 행은 src `sourceRoots`와 함께 `port: "... DurableObjectStorePort / DurableObjectMaintenancePort ..."`, `fake: "... MemoryDurableObjectStore ..."`를 적는다(`config/recipes/frontend-capability-recipes.json:85-107`). 그 fake는 recipe 계약을 구현한다(`browser-file-storage-fakes.ts:1691-1692`) |
| 발생 조건 | 다운스트림이 catalog를 보고 이 런타임의 fake를 고를 때. 런타임 port를 바꿀 때(recipe 쪽은 따라오지 않는다) |
| 영향 | ① 05-01~05-14의 port 변경(`skippedLiveTransactions`, `chunkSweep`, `INCOMPATIBLE` 등)이 recipe 쪽에 하나도 반영되지 않았다. "정책 중복으로 변경 누락이 반복됨"(35.2 Medium 예시)의 실제 사례다. ② 같은 이름이라 import 경로를 봐야 어느 계약인지 안다. ③ recipe fake로 쓴 기능 테스트는 실제 런타임에 없는 resume·quarantine을 전제한다 |
| 심각도·우선순위 | Medium · P2. 런타임 피해는 없다. 타입이 달라 섞으면 컴파일에서 드러난다. 하지만 템플릿이 "이 런타임의 fake"로 안내하는 대상이 다른 계약이다 |
| 통제·증거 | "catalog가 가리키는 fake는 src port를 구현한다" 규칙: M0 확인(둘을 잇는 검사 없음) · E1 |
| 확실성과 남은 가정 | 파일과 git 이력으로 확인했다. recipe 계약이 "제품이 복사해 좁혀 쓰는 설계 초안"이라는 의도(`browser-file-storage-contracts.ts:7-13`)는 기록돼 있다. 그 의도와 catalog 안내가 어긋난다. browser-files 쪽 port(영역 02)와 레시피 문서(영역 14)에도 같은 원인이 걸린다. 오케스트레이터가 합칠 수 있다 |
| 결정의 근거 | [기록] recipe 계약은 런타임보다 먼저(7월) 만든 심층 설계다(`docs/architecture/optional-adapter-recipes.md:22-24`). [추론] src 런타임이 생긴 뒤 두 벌을 맞추는 담당이나 검사가 없어 갈라졌다 |
| 이해 비용 | 조합 작성자는 같은 이름 interface 두 개를 비교해야 한다. 런타임 port를 고치는 사람은 recipe 복사본의 존재를 모른다 |
| 최소 개선 방향 | 런타임이 있는 port는 recipe 쪽 정의를 지우고 src port를 re-export한다. recipe fake(`MemoryDurableObjectStore` 등)는 src port를 구현하게 고치거나, catalog의 `fake` 칸에서 뺀다 |
| 대안 비교 | (a) 현상 유지: 변경 누락이 계속된다. (b) 이름만 바꿔 recipe 쪽을 `*Sketch`로 표시: 싸지만 중복 유지비는 남는다. (c) src port로 통합: 한 벌만 남는다. recipe fake를 고치는 비용이 든다. (d) 두 벌을 비교하는 타입 테스트: 차이를 잡지만 두 벌을 유지한다. (c)를 권한다 |
| 단순화의 보존 조건 | recipe 계약이 보장하던 "File·IDBDatabase 같은 브라우저 객체를 노출하지 않는다"는 src port도 지킨다(확인함: `indexeddb-port.ts:178-181`). recipe 계약 테스트(`tests/recipes/browser-file-storage-contracts.test.ts`)는 src port 기준으로 옮긴다 |
| 비용·부작용 | recipe 파일 수정과 테스트 이동. 제품 repo가 recipe 계약을 import했다면 깨진다(두 제품 모두 확인 안 함) |
| 재검토 조건 | recipe가 런타임 없는 순수 설계로만 남는다면 이름을 구분하는 (b)로 충분하다 |
| 완료 기준 | `recipes/`와 `src/application/ports/`에 같은 이름의 서로 다른 interface가 없다. catalog `fake` 칸의 클래스가 src port를 `implements`한다 |
| 검증 방법 | `check:types:recipes`, 이름 충돌을 찾는 `grep`, recipe 계약 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-04 offline-indexeddb 레시피 예산 여유 9바이트: 이 영역의 다음 수정이 게이트에 막힌다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (측정·변이로 확인) |
| 관련 관점 | 3, 21, 14 |
| 근거 | ① 측정: `offline-indexeddb:36891/36900`, `realtime:40886/40900`, `file-transfer:55623/55700`(`node scripts/check-optional-recipes.ts`).<br>② 변이: reconcile에 관측 이벤트 7줄 추가 → `REFERENCE_RUNTIME_BUNDLE_BUDGET_EXCEEDED: offline-indexeddb (36909 > 36900)`.<br>③ 예산 이력은 측정값을 따라 올리기만 했다: 8000 → 36000(`6c52cdb9`) → 36900(`6fe4aa9e`). 예산 근거 문서는 "측정값을 100바이트 단위로 올림"뿐이다(FOLLOW-UP 1절).<br>④ 레시피 측정은 `sourceRoots` 전체와 그 import를 묶는다(`scripts/lib/optional-recipe-bundle.ts:65-100`). kernel(`platform/`, `result.ts`)도 들어간다 |
| 발생 조건 | 이 영역이나 kernel에 코드를 조금이라도 더할 때. 05-01·05-02를 고칠 때도 해당한다 |
| 영향 | 결함 수정이 "예산 인상" 커밋을 함께 요구한다. 예산이 목표가 아니라 직전 측정값이라 커진 이유를 묻는 신호가 되지 못한다. kernel 한 줄이 레시피 예산 여러 개를 함께 움직인다. `result.ts`에 `case` 한 줄을 더하는 변이가 예산 3개를 함께 바꿨다(4.3절) |
| 심각도·우선순위 | Low · P2. 사용자 피해는 없다. 다음 수정 작업을 막는다 |
| 통제·증거 | M3(게이트는 동작) · E3(측정·변이) |
| 확실성과 남은 가정 | 측정은 이 호스트의 Vite·esbuild 버전 기준이다. 번들 예산 정책 자체는 영역 13 소관이라 겹칠 수 있다 |
| 결정의 근거 | 적용 제외 — 예산 수치를 어떻게 정할지는 영역 13·FOLLOW-UP의 결정이다. 여기서는 이 영역의 변경 비용만 기록한다 |
| 이해 비용 | 수정자는 레시피 측정 방식과 kernel 포함 여부를 알아야 실패 원인을 이해한다 |
| 최소 개선 방향 | 05-01·05-02 수정과 같은 커밋에서 예산을 정하되, 목표치와 근거(예: "OPFS·IDB 런타임 전체 gzip 40KB 이하")를 catalog 옆에 적는다 |
| 대안 비교 | (a) 수정마다 100바이트 인상(현상): 게이트가 증가를 막지 못한다. (b) 목표치로 한 번 정함: 근거 문서가 필요하다. (c) 레시피 예산에서 kernel을 뺌: kernel 증가를 놓친다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 문서 한 줄과 수치 결정 |
| 재검토 조건 | 레시피가 실제로 조합되어 초기 번들에 들어갈 때 |
| 완료 기준 | 예산에 근거가 적혀 있고, 05-01·05-02 수정 뒤에도 게이트가 통과한다 |
| 검증 방법 | `node scripts/check-optional-recipes.ts` |
| 담당·기한·상태 | 미정 · 미정 · FOLLOW-UP P2 이월 |
### 05-05 IndexedDB 전체 삭제 경로의 적용 범위가 port·runbook 설명과 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서·코드 불일치 + 범위 공백, 재현) |
| 관련 관점 | 11, 15, 17, 24 |
| 근거 | ① 코드: `RETENTION_SWEEP`이 아닌 모든 action이 `deleteUnadmittedDataset`을 거친다(`indexeddb-runtime.ts:2554-2558`). SESSION_END도 포함된다.<br>② 삭제 조건은 open 실패 코드가 `POLICY_REJECTED`·`CORRUPT_DATA`일 때뿐이다(`:2580-2587`).<br>③ 설명: port는 "authorized LOGOUT or ACCOUNT_DELETION"만 적는다(`indexeddb-port.ts:154-160`). 코드 주석(`:2566-2573`)과 runbook(`browser-file-storage-recovery.md:278-281`)도 같다.<br>④ 재현 I2: SESSION retention dataset, budget 손상 → `SESSION_END` = `datasetDeleted: true`.<br>⑤ 재현 I1: v1 DB에 개인 행, v2 runtime의 migration 실패 → `ACCOUNT_DELETION` = `MIGRATION_FAILED/READ_ONLY`, `deleteDatabase` 호출 0회, 행 남음.<br>⑥ 코드: 롤백 배포로 모든 탭이 이전 bundle이면 open이 `UNSUPPORTED`(`:662-675`)라 purge가 같은 답으로 끝난다 |
| 발생 조건 | I2는 SESSION dataset의 governance 손상. I1은 기기에서 migration이 실패하거나, 새 release가 DB를 올린 뒤 이전 release로 롤백했을 때의 계정 삭제 |
| 영향 | SESSION_END 쪽은 동작이 오히려 안전하다. 설명만 틀렸다. 롤백·migration 실패 쪽은 계정 삭제 뒤 개인 데이터가 다음 배포까지 남는다. `deleteDatabase`는 버전과 무관하게 지울 수 있으므로 구 bundle에서도 막을 이유가 기술적으로는 없다 |
| 심각도·우선순위 | Low · P3. 롤백과 migration 실패는 드물고, 그 자체가 사고 절차를 탄다 |
| 통제·증거 | M1(설명이 코드와 다름) · E2(I1·I2) |
| 확실성과 남은 가정 | 두 코드를 뺀 의도는 기록에 없다. `EXPORT_THEN_PURGE` dataset에서 export 실패 데이터를 지우는 판단은 authority 몫이라고 본다 |
| 결정의 근거 | 4.2절 |
| 이해 비용 | runbook을 보는 운영자는 롤백 중 계정 삭제가 왜 `UNSUPPORTED`로 끝나는지 찾을 곳이 없다 |
| 최소 개선 방향 | 적용 action을 정한다(SESSION_END 포함 여부). 승인된 LOGOUT·ACCOUNT_DELETION에서 `MIGRATION_FAILED`·`UNSUPPORTED`도 삭제할지 정한다. 결정에 맞게 코드 조건, port 주석, runbook 조건을 한 번에 고친다 |
| 대안 비교 | 4.2절 (a)~(d) |
| 단순화의 보존 조건 | 승인 없이는 지우지 않는다. 다른 partition을 건드리지 않는다. 정상 governance에서는 행 단위 purge만 한다(현 테스트 `indexeddb-runtime.test.ts:1580-1613`) |
| 비용·부작용 | 범위를 넓히면 롤백 중 export 못 한 데이터가 지워질 수 있다. authority 구현 지침에 적어야 한다 |
| 재검토 조건 | 릴리스 롤백 절차가 정해질 때 |
| 완료 기준 | port 주석·runbook·코드의 적용 action과 open 실패 코드 목록이 같다. I1·I2가 결정한 결과를 내는 테스트가 있다 |
| 검증 방법 | I1·I2를 단위 테스트로 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-06 한 레시피의 두 런타임이 삭제 승인 계약을 다르게 요구한다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 22, 23, 15 |
| 근거 | ① IndexedDB: 콜백 하나(`authorizeLifecycle`)가 `{authorized, proofToken}`을 돌려준다. 런타임은 형식(`/^[A-Za-z0-9_-]{16,128}$/`)만 보고 버린다(`indexeddb-runtime.ts:97`, `:2046-2077`). port 주석은 "short-lived"라고 하지만 만료 시각이 없다(`indexeddb-port.ts:170-176`).<br>② OPFS: 콜백 둘(`requestMaintenanceAuthority`, `consumeMaintenanceAuthority`)이 필요하다. proof 형식은 `{16,512}`이고 `expiresAtEpochMs`가 5분 이하여야 하며, consume으로 재사용을 막는다(`opfs-byte-store-adapter.ts:886-995`, `:1785-1786`).<br>③ 타입 위치도 다르다. IDB는 port(`indexeddb-port.ts:163-176`), OPFS는 adapter(`opfs-byte-store-adapter.ts:49-84`)에 있다 |
| 발생 조건 | 같은 LOGOUT 이벤트에서 두 런타임을 함께 조합할 때 |
| 영향 | 조합 작성자는 같은 승인을 두 방식으로 구현한다. IDB의 "short-lived"는 런타임이 확인할 수 없는 약속이다. 두 런타임 모두 proof를 스스로 요청하고 바로 버리므로, 형식 검사가 보안에 더하는 것은 없다(추론) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 두 계약을 다르게 둔 이유는 기록에서 찾지 못했다. OPFS의 consume은 "composition consumer owns atomic replay prevention across runtimes"(`adapter:983-984`)라고만 적혀 있다 |
| 결정의 근거 | [사실] 위 근거. [추론] OPFS 쪽이 나중에 더 엄격하게 설계됐고 IDB 쪽은 따라가지 않았다 |
| 이해 비용 | 승인 경로 둘, 정규식 둘, 타입 위치 둘을 따로 읽어야 한다 |
| 최소 개선 방향 | 하나의 승인 계약을 port(`shared.ts`)에 두고 두 런타임이 같이 쓴다 |
| 대안 비교 | (a) 현상 유지: 차이를 문서화만 한다. (b) IDB를 OPFS 방식(request+consume+만료)으로 올린다: 조합 비용이 늘지만 약속과 검사가 일치한다. (c) 둘 다 boolean 승인으로 줄인다: proof 형식 검사가 주던 것이 없다면 가장 단순하다. 다만 서버가 발급한 일회용 proof를 composition이 검증하는 설계라면 proof 전달이 필요하다. 그 요구가 확인되지 않아 (b)와 (c) 중 결정은 조건부다 |
| 단순화의 보존 조건 | 삭제마다 composition 승인을 거친다. proof를 호출자·로그·관측에 노출하지 않는다. 승인 실패는 삭제 0건이다 |
| 비용·부작용 | port 계약 변경이다. 조합한 다운스트림은 승인 콜백을 고쳐야 한다(현재 조합 0건) |
| 재검토 조건 | 서버 발급 proof를 실제로 쓰는 조합이 생길 때 |
| 완료 기준 | 두 런타임이 같은 승인 타입과 같은 proof 검사를 쓴다 |
| 검증 방법 | 두 런타임의 승인 거절 테스트가 같은 입력에서 같은 결과를 낸다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-07 kernel로 올릴 canonical JSON이 3벌로 갈라져 있다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 22, 9, 23 |
| 근거 | ① `opfs-prepared-object.ts:138-163` `stableJson` — 비유한 수·`undefined`를 throw한다(05-10에서 일부러 그렇게 바꿨다. 주석: "two different values never compare equal").<br>② `cache-storage/public-cache-codec.ts:632-652` `stableJson` — 같은 구조지만 `NaN`을 `"null"`로 쓴다.<br>③ `realtime/event-codec.ts:414-438` `canonicalJson` — 같은 구조, `NaN` → `"null"`. 이 값은 이벤트 fingerprint 해시에 들어간다(`:216`).<br>④ OPFS 폴더 안 `sameScope`도 두 벌이다(`indexeddb-opfs-journal.ts:1303-1313`, `opfs-worker-runtime.ts:1657-1667`). 내용은 같다 |
| 발생 조건 | canonical JSON 규칙을 한 곳에서 고칠 때 |
| 영향 | 지금은 ②·③의 입력이 `JSON.parse` 결과라 `NaN`이 올 수 없다. 도달하는 결함은 없다. 하지만 05-10이 OPFS에서 고친 판단이 다른 두 벌에는 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 적용 제외(규칙 없음) · E1 |
| 확실성과 남은 가정 | 코드로 확인했다. ②는 영역 02, ③은 영역 04 코드다 |
| 결정의 근거 | [기록] kernel에는 이미 공유 파서가 있다(`platform/json-member-scanner.ts`, Q-6.4-8). [추론] canonical 직렬화도 같은 성격의 메커니즘이다 |
| 이해 비용 | 세 곳 중 하나만 고치면 fingerprint나 비교 결과가 영역마다 달라진다 |
| 최소 개선 방향 | ①을 `src/adapters/platform/`으로 옮기고 ②·③이 쓴다(폴더 단위 kernel이라 새 예외가 필요 없다). `sameScope`는 OPFS 폴더 안 한 파일로 합친다 |
| 대안 비교 | (a) 현상 유지: 차이가 커질 수 있다. (b) 통합: realtime fingerprint가 `NaN`에서 throw하게 된다. 입력이 JSON이라 실제 변화는 없다 |
| 단순화의 보존 조건 | realtime fingerprint 값이 지금과 같아야 한다(키 정렬·구분자 동일). OPFS는 비유한 수를 계속 거절한다 |
| 비용·부작용 | 작다. 레시피 예산 3개가 조금 움직인다(05-04) |
| 재검토 조건 | 비교 대상에 JSON 밖 값(Date, BigInt)이 들어올 때 |
| 완료 기준 | `src/adapters`에 canonical JSON 구현이 하나다 |
| 검증 방법 | 기존 fingerprint·manifest 비교 테스트 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-08 kernel 범위 설명이 실제보다 좁고 편입 기준이 한 파일에만 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서 불일치) |
| 관련 관점 | 22, 9, 2 |
| 근거 | ① `docs/architecture/layers.md:42-45`와 `.dependency-cruiser.json:242` 주석은 `platform/**`을 "clock, abort primitive, capacity guard", `result.ts`를 "browser-data result helpers"라고 적는다.<br>② 실제 `platform/`에는 IndexedDB connection·transaction 상태 기계, Retry-After 파서, JSON 멤버 스캐너, lifecycle 런타임, mutation intent factory가 있다. `result.ts`에는 예외→실패 표 두 개가 있다(`result.ts:43-96`, `:110-171`).<br>③ "kernel이 가지면 안 되는 것" 목록은 `indexeddb-connection.ts:19-24`에만 있다. `.dependency-cruiser.json:242`는 "a new shared primitive goes into src/adapters/platform/"라고만 한다 |
| 발생 조건 | 새 공유 코드를 kernel에 넣을지 판단할 때 |
| 영향 | 문서만 읽으면 kernel이 세 가지 작은 도구라고 오해한다. 무엇을 넣으면 안 되는지는 한 파일을 열어야 안다. 지금까지는 그 파일의 기준이 지켜졌다(4.3절) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1(문서가 틀림) · E1 |
| 확실성과 남은 가정 | 문서와 파일 목록을 대조했다 |
| 결정의 근거 | 적용 제외 — 문서를 사실에 맞추는 단순 수정이다 |
| 이해 비용 | kernel 파일 10개와 `result.ts`를 모두 열어야 범위를 안다 |
| 최소 개선 방향 | `layers.md` kernel 절에 실제 파일 목록 대신 **편입 기준**을 적는다: 둘 이상의 그룹이 쓰는 메커니즘, 이름·스키마·실패 코드·관측 형태 같은 정책은 호출자가 소유. 규칙 주석은 그 절을 가리킨다 |
| 대안 비교 | 적용 제외 — 선택을 바꾸지 않는다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 두 곳 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 문서의 kernel 설명이 현재 파일과 맞고, 편입 기준이 문서에 있다 |
| 검증 방법 | 수동 대조. `verify:documentation` 범위 밖이다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-09 `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 12 |
| 근거 | ① 주석: "Keep it below `mutationLockWaitTimeoutMs` so a queued writer outlasts it"(`opfs-policy.ts:23-29`).<br>② 검사는 각 값의 범위(1초~60분)만 본다(`opfs-policy.ts:102-107`).<br>③ 실행: `resolveOpfsRuntimePolicy({putIdleTimeoutMs: 3_600_000, mutationLockWaitTimeoutMs: 1_000})`가 거절 없이 받아들여졌다 |
| 발생 조건 | 다운스트림이 두 값 중 하나만 조정할 때 |
| 영향 | source가 멈춘 put이 lock을 풀기 전에 다른 탭의 모든 쓰기·GC가 `BLOCKED`로 먼저 실패한다. 05-07 수정의 효과가 사라진다 |
| 심각도·우선순위 | Low · P3. 기본값(2분 < 10분)에서는 생기지 않는다 |
| 통제·증거 | M1 · E1 + 실행 |
| 확실성과 남은 가정 | 정책 검사 코드와 실행으로 확인했다 |
| 결정의 근거 | 적용 제외 — 주석에 적힌 규칙을 검사로 옮기는 단순 수정이다 |
| 이해 비용 | 설정 작성자가 두 값의 관계를 주석에서만 알 수 있다 |
| 최소 개선 방향 | `assertOpfsRuntimePolicy`에 `putIdleTimeoutMs < mutationLockWaitTimeoutMs`를 추가한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 한 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 위 조합이 정책 생성에서 거절된다 |
| 검증 방법 | 정책 단위 테스트 1개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-10 OPFS journal DB 이름 접두사를 설정으로 바꿀 수 없어 제품이 소스를 고친다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 (제품 repo 증거) |
| 관련 관점 | 19, 3 |
| 근거 | ① OPFS root·lock 이름은 정책으로 바꿀 수 있다(`opfs-policy.ts:59-60`, `resolveOpfsRuntimePolicy`). journal DB 이름은 `ca-frontend-opfs-metadata-v1:` 접두사가 고정이고, `databaseName`을 넘겨도 기대값과 같아야 한다(`indexeddb-opfs-journal.ts:125-132`, `:156-163`). IndexedDB dataset 이름도 `ca-idb-v1:` 고정이다(`indexeddb-governance.ts:83`).<br>② `memento-frontend`(`chore/template-sync-v0.2.0`)는 `opfs-policy.ts` 기본값 두 개와 journal 접두사를 소스에서 `memento-...`으로 고쳐 들고 다닌다(`git diff af3d8e6 chore/template-sync-v0.2.0 -- src/adapters/storage/opfs/`, 2파일 3줄). `ca-idb-v1`은 그대로 뒀다 |
| 발생 조건 | 제품이 물리 이름에서 템플릿 이름을 빼고 싶을 때 |
| 영향 | 제품이 adapter 소스를 고치므로 템플릿 동기화 때 같은 줄이 바뀌면 충돌한다. 이번 동기화에서는 충돌하지 않았다. 배포 뒤 이름을 바꾸면 기존 데이터가 고아가 된다(제품 책임) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1(제품 diff) |
| 확실성과 남은 가정 | 제품이 이름을 바꾼 이유는 전체 rename 커밋(`c7caeef`)뿐이다. 조합하지 않은 코드라 정책 주입 대신 기본값을 고친 것으로 보인다(추론) |
| 결정의 근거 | [추론] 물리 이름을 템플릿 브랜드로 고정한 것은 의도라기보다 초기값이다. 기록은 찾지 못했다 |
| 이해 비용 | 제품 담당자는 이름 세 개가 어디서 오는지 파일 세 곳을 봐야 한다 |
| 최소 개선 방향 | 물리 이름 접두사 하나를 정책 값으로 받아 root·lock·journal·IDB 이름을 모두 거기서 만든다. 또는 "이름을 바꾸지 말라, 배포 뒤 바꾸면 데이터가 고아가 된다"를 README 업데이트 절에 적는다 |
| 대안 비교 | (a) 현상 유지 + 문서: 가장 싸다. (b) 접두사 정책화: 제품이 소스를 고칠 이유가 없어진다. 대신 정책 값이 release 사이에 바뀌면 안 된다는 조건이 새로 생긴다 |
| 단순화의 보존 조건 | 이름은 opaque 토큰만으로 만든다는 규칙(`governance:71-83`)을 유지한다 |
| 비용·부작용 | (b)는 기본값을 바꾸지 않으면 기존 데이터에 영향이 없다 |
| 재검토 조건 | 제품이 실제로 런타임을 조합할 때 |
| 완료 기준 | 제품이 adapter 소스를 고치지 않고 이름을 정할 수 있거나, 바꾸지 말라는 안내가 있다 |
| 검증 방법 | 다음 템플릿 동기화 기록에서 이 파일들의 제품 diff 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP과 지난 발견 재확인
### 6.1 FOLLOW-UP (2026-09-28) 중 이 영역 항목
| FOLLOW-UP 항목 | 결과 | 근거 |
|---|---|---|
| 1절 P2 레시피 번들 예산: offline-indexeddb 36,891/36,900 | **유효** | 현재 측정값이 같다. 7줄 변이로 게이트가 실패한다 → 05-04 |
| 4절 P3 05-10: 넓힌 id 정책은 생성 시점에 못 막고 BEGIN_PUT에서 `INVALID_INPUT` | **유효** (의도된 설계) | 표본 검사(`opfs-policy.ts:130-160`)와 쓰기 때 문법 재검사(`:163-172`, `worker:332`). 동작은 FOLLOW-UP 설명과 같다 |
| 4절 P3 05-03 테스트: 손상된 budget 행만 테스트, binding 행은 없음 | **유효** | `tests/unit/indexeddb-runtime.test.ts:1485-1542`, Playwright `indexeddb-runtime.spec.ts:1081`은 budget만 손상시킨다. 동작 자체는 I4로 확인했다: binding 손상도 `POLICY_REJECTED` → `datasetDeleted: true` |
### 6.2 지난 발견 05-01~05-14 (회귀 확인)
| ID | 결과 | 근거 |
|---|---|---|
| 05-01 | 해소 | X1a·X1b·X1c, M1, Playwright chromium·firefox |
| 05-02 | 해소 | M2·M3. 손상 receipt(비어 있지 않음)는 범위 밖 → 새 05-01 |
| 05-03 | 해소 | M5, I4, Playwright. 적용 범위 문제 → 새 05-05 |
| 05-04 | 해소 | M4. 완료 신호 문제 → 새 05-02 |
| 05-05 | 해소 | 테스트 `indexeddb-runtime.test.ts:1616-1678`, prune 실패 코드 `CORRUPT_DATA`(`indexeddb-maintenance.ts:149-155`) |
| 05-06 | 해소 | M6, Playwright. journal도 `UNSUPPORTED`(`indexeddb-opfs-journal.ts:1691-1702`) |
| 05-07 | 해소 | 테스트 `opfs-worker-runtime.test.ts:2402-2446`. 설정 관계 검사 누락 → 새 05-09 |
| 05-08 | 해소 | fake 헤더(`memory-indexeddb.ts:849-876`), `memory-indexeddb-fidelity.test.ts` |
| 05-09 | 해소 | `EFFECT_UNKNOWN`이 storage 코드·runbook에 없다(`grep`). runbook 7절이 삭제·rollback만 적는다 |
| 05-10 | 해소 | 위 6.1 |
| 05-11 | 해소 | `storage/opfs` → `storage/indexeddb` import 0건. IndexedDB 표 1벌(`result.ts:110-171`) |
| 05-12 | 해소 | kernel 밖 `oncomplete` 0건(`grep`), `governance:229-271`이 kernel 트랜잭션을 쓴다 |
| 05-13 | 해소 | M7 |
| 05-14 | 해소 | port 주석(`opfs-ports.ts:87-95`) |
## 7. 미검증 목록
| 항목 | 이유 | 확인에 필요한 것 |
|---|---|---|
| WebKit에서 05-01·05-03·05-06 spec | 이번에는 chromium·firefox만 돌렸다 | `playwright.capabilities.config.ts`의 webkit project 실행 |
| X2(purge vs 같은 객체 덮어쓰기)·X3(손상 object row)의 실제 브라우저 재현 | 메모리 FS·IndexedDB와 Node Web Locks로만 재현했다 | Playwright OPFS spec에 두 탭 시나리오 추가 |
| v0.1.0 탭과 v0.2.0 탭 공존 | v0.1.0 put은 transaction lock을 잡지 않으므로 v0.2.0 reconcile이 그 row를 정리할 수 있다(코드 판단). 두 release를 동시에 띄우는 환경이 없었다 | 두 빌드를 다른 탭에 띄우는 e2e |
| release마다 `mutationLockName`이 다른 경우 | 설정값 조합이라 재현하지 않았다 | 정책만 다른 두 런타임을 한 root에서 돌리는 단위 테스트 |
| 실제 quota 초과, 실제 저장소 손상 | 브라우저 quota를 제어할 환경이 없다 | quota를 줄인 프로필 또는 대용량 채우기 |
| 2 GiB 객체 검증이 60초 RPC 안에 끝나는지 | 성능 측정 환경이 없다 | 저사양 기기 측정 |
| IndexedDB만 제거하는 드릴 | 드릴은 번들 전체만 지운다(`storage/index.ts:1-10`이 명시) | 드릴 변형 |
| 제거 드릴 1회차 실패의 원인 | 2회차 통과로 타이밍으로 판단했다. 같은 테스트의 기본 1초 대기는 영역 10·11 소관이다 | 부하를 준 상태에서 `tests/component/router.test.tsx` 반복 실행 |
| 제품 repo가 recipe 계약(05-03)을 import하는지 | 이번에는 조합 여부만 확인했다 | 두 제품의 `recipes/` import 검색 |
@@ -0,0 +1,358 @@
# 06 Service Worker / Web Push 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 깊게 본 관점: 7, 12, 15, 18, 19, 28
## 0. 머리말 (36.1)
| 항목 | 기록 |
| --- | --- |
| 영역 | Service Worker(이하 SW) 정적 자산 캐시·활성화·제거, Web Push 구독·수신·클릭, SW 빌드 |
| 경로 | `src/adapters/service-worker/`(7파일), `src/adapters/web-push/`(12파일), `vite.service-worker.config.ts`, `scripts/lib/service-worker-build-input.ts`, `scripts/generate-service-worker-assets.ts`, `scripts/lib/self-unregistering-service-worker.ts`, `tsconfig.service-worker.json` |
| 기준 커밋·작업 상태 | `af3d8e6`. 워킹트리 변경은 리뷰 가이드 문서 2개뿐이고 코드는 `af3d8e6`과 같다 |
| 전제 (0.1) | 템플릿. SW 기본값은 `null`(`src/features/installed-runtime-capabilities.ts:39`). Web Push는 빌드 단계에서 거절한다(`scripts/lib/service-worker-build-input.ts:162-166`). 브라우저 SPA + 정적 호스팅 + SW. 여러 탭과 하위 경로 배포(`VITE_ROUTER_BASE_PATH`)는 지원 범위다(`vite.config.ts:26-33`) |
| 읽은 코드 | 범위 안 파일 전부. 연결 확인: `scripts/build-frontend.ts`, `scripts/generate-runtime-config.ts`, `scripts/generate-build-manifest.ts`, `scripts/check-release-admission.ts`, `src/contracts/deployment-admission.ts`, `scripts/verify-hosting-headers.ts`, `scripts/lib/hosting-probe.ts`, `config/hosting/cache-policy.json`, `src/contracts/service-worker.ts`, `src/contracts/web-push.ts`, `src/application/ports/out/web-push-control.ts`, `src/bootstrap/{register-service-worker,optional-runtime-host,create-runtime-composition}.ts`, `vite.config.ts`, `scripts/lib/optional-recipe-bundle.ts`, Vite 8.1.5의 `prepareOutDir`·`copyDir` |
| 읽은 테스트 | `tests/e2e/service-worker-update.spec.ts`, `tests/e2e/service-worker-recovery.spec.ts`, `tests/e2e/support/service-worker-builds.ts`, `tests/unit/web-push-subscription-adapter.test.ts`(06-02·06-06 절), `tests/unit/sub-path-deployment.test.ts` |
| 읽은 문서(주장) | `CHANGELOG.md:48-49`, `docs/architecture/optional-adapter-recipes.md` 3절, `config/recipes/frontend-capability-recipes.json`(`service-worker-pwa`), `docs/operations/release-cache-rollback.md` SW 절, `docs/operations/browser-file-storage-recovery.md` 8절, `docs/architecture/realtime-events-web-push-and-bounded-polling.md:1314-1370`, 설계 문서 `…closed-deep-design.md:327`, `:3398-3418`, `:3781-3850`, `:5897` |
| 소비자 증거 | `../memento-frontend` `chore/template-sync-v0.2.0`: 동기화 기록과 `git diff af3d8e6 chore/template-sync-v0.2.0`(SW 관련 4파일). `../tech-log-frontend` 같은 브랜치: SW `null` 유지 확인 |
| 실행한 테스트 | 분리 worktree에서 `node scripts/run-vitest.ts run` + 이 영역 단위 10파일 → **10 files, 153 passed** |
| 실행한 e2e | 분리 worktree, 별도 Playwright 설정(webServer 없음), `service-worker-update.spec.ts` + `service-worker-recovery.spec.ts` → chromium **6 passed**, webkit **6 passed**, firefox **3 passed / 3 skipped**(격리 표기된 Playwright Firefox 제약) |
| 변이 실험 | ① Web Lock 우회 → 06-02 테스트 3개 실패. ② kill switch 분기 무력화 + `revokeForeign`의 같은 세대 검사 제거 → 4개 실패. ③ 선택을 `ACTIVE`로 바꾼 트리에서 SW update spec → `beforeAll` 오류로 5개 모두 실패·미실행(06-04) |
| 빌드 실험 | ① SW `ACTIVE` + `APP_PROFILE=production` 빌드 → `dist/config.json`이 local 문서로 바뀜, release admission 거절(06-01). ② SW `ACTIVE` + `VITE_ROUTER_BASE_PATH=/app/` → manifest URL이 `/assets/…`(06-02). ③ `publicDir: false` 한 줄 추가 → 같은 production + `/app/` 빌드의 config가 맞고 admission 통과 |
| 브라우저 실험 | ④ `/app/` 빌드를 Chromium으로 열기: 그대로면 `/release-manifest.json` 404로 부팅 실패(06-01). config만 고치면 앱은 뜨고 워커 설치가 `/assets/…` 404로 실패(06-02). ⑤ 워커 등록 뒤 스크립트를 404로 바꾸고 `update()`와 새 navigation: Chromium·WebKit·Firefox 모두 등록과 active 워커 유지(06-06) |
| 확인하지 못한 범위 | `test:realtime-removal`(시작했으나 worktree의 링크된 `node_modules`에 pnpm이 설치를 시도해 안전을 위해 중단), 실제 CDN 캐시 동작, 실제 푸시 서비스·VAPID 흐름, 얼어 있는 탭의 Web Lock 보유, 여러 창 활성화(앱이 아닌 창) 실제 브라우저. 7절에 적었다 |
| 이전 리뷰와 비교 | 2026-09-25 06-01~06-10은 모두 닫혔다. 이번에 코드와 변이로 다시 본 것: 06-01(`service-worker-runtime.ts:283` `"data" in`, WebIDL 모양 fake `tests/unit/web-push-worker-runtime.test.ts:110-120`), 06-02·06-04·06-06(변이로 검출 확인), 06-03(e2e 3엔진 중 2엔진 통과), 06-07·06-08·06-09(코드 확인). 회귀는 없다 |
**영역 판정 (35.8)**
- 기본 구성(SW `null`, Web Push 미선택): 이 영역의 결함이 나타나지 않는다. 지정 범위에서 사용 가능.
- SW `ACTIVE`: **해당 용도의 사용 보류.** SW를 켜면 local이 아닌 모든 빌드의 런타임 설정이 local 문서로 바뀐다(06-01, High). 한 줄 수정이다. 하위 경로 배포에서는 워커가 설치되지 않는다(06-02).
- Web Push: **조건부 사용 가능.** 지난 라운드의 실제 브라우저 결함 2건(클릭 무시, 탭 경합)은 해소됐고 변이로 검출된다. 서버의 짧은 association TTL·send-time 인가와 `revokeForeign` 호출 규칙이 채택 조건이다.
## 1. 결론
- **06-01 (High):** SW 빌드는 Vite를 한 번 더 돈다. 이 두 번째 빌드가 `public/`을 다시 복사해서 프로필로 만든 `dist/config.json`을 `public/config.json`(local 프로필)으로 덮어쓴다. production 빌드가 `APP_ENV: local`, `AUTH_MODE: demo`, `API_BASE_URL: http://localhost:8080/`을 싣고 성공한다. release admission이 이를 거절해서 배포 피해는 막히지만, SW를 켠 제품은 릴리스를 만들 수 없다. 하위 경로 빌드는 부팅하지 못한다. memento는 이미 같은 결함을 만나 `publicDir: false`로 막았다.
- **06-02 (Medium):** SW 사전 캐시 목록은 router base path를 모른다. `/app/`에 배포하면 워커가 `/assets/…`를 받으려다 404로 설치를 포기한다.
- **06-03 (Medium):** 레시피 catalog는 "오프라인 셸 요구"를 SW 레시피의 설치 조건으로 적는다. 코드와 설계는 오프라인 셸을 금지하고, 제품이 켤 확장 지점도 없다. memento는 템플릿 파일 3개를 고쳤다.
- **06-04 (Medium):** SW e2e 도우미는 선택이 `null`인 줄을 찾아 바꾼다. SW를 켠 제품에서는 update·recovery spec이 준비 단계에서 모두 멈춘다.
- **06-05 (Medium):** 설계는 `service-worker.js`의 `Cache-Control: no-cache`를 호스팅 설정에 맡겼다. 호스팅 정책 파일과 live probe에는 그 항목이 없다.
- **06-06 (Low):** 제거 2·3단계는 `service-worker.js`를 내보내지 않는다. 부팅을 막는 워커는 1단계 기간에 오지 않은 사용자에게 남는다.
- 확인된 강점:
1. 설치 무결성: 개수·크기 상한, 상태·타입·바이트 수·sha256 검증, 전부 성공해야 캐시를 쓴다(`service-worker-static-assets.ts:119-208`, `:269-349`). `credentials: "omit"`, `redirect: "error"`로 받는다(`:280-285`).
2. 새 배포 뒤 옛 탭: 이전 릴리스 캐시에서 옛 청크를 준다. 이번에 chromium·webkit e2e로 다시 확인했다(`service-worker-update.spec.ts:222-264`).
3. 비상 해제: `REMOVE_REGISTRATION`이 자기 해제 워커를 내보낸다(`scripts/build-frontend.ts:72-77`). 페이지가 부팅하지 못하는 워커를 브라우저 update만으로 걷어낸다. chromium·webkit e2e 통과(`service-worker-recovery.spec.ts:75-151`).
4. 탭 경합: enable·reconcile·revoke를 origin 단위 Web Lock으로 직렬화한다(`push-subscription-adapter.ts:467-506`). 우회 변이를 넣으면 테스트 3개가 실패한다.
5. 다중 방어: 06-01이 만든 잘못된 설정을 release admission(`src/contracts/deployment-admission.ts:64-110`)이 거절했다. 설정 결함이 production으로 가는 경로를 다른 게이트가 막는 것을 실제로 확인했다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — SW를 켠 앱의 첫 방문과 다음 방문 (루트 배포)
```text
사용자 첫 방문 /
→ [정책] resolveRuntimeCapabilities: serviceWorker ACTIVE
첫 React effect 뒤 optional.startAfterMount() (optional-runtime-host.ts:97-120)
→ [상태] container.register(/service-worker.js, {type: module, updateViaCache: none})
(service-worker-page-controller.ts:157-161)
→ [외부 I/O] 워커 install: manifest 자산 28개(이번 빌드)를 no-store·omit·redirect:error로 받음
→ 크기·타입·sha256 검증 → ca-static-v1-<digest16>에 저장 (service-worker-static-assets.ts:154-208)
→ [실패] 하나라도 틀리면 이번에 만든 후보 캐시만 지우고 install 거절
→ 페이지 start() = FAILED(INSTALL_FAILED) → telemetry service-worker.start.failed 1건
(optional-runtime-host.ts:105-120)
→ [결과] 성공이면 RELOAD_TO_ENABLE (clients.claim 없음, page-controller.ts:206-211)
다음 navigation부터 해시 GET만 cache-first, navigation·config·API는 가로채지 않음
(service-worker-static-assets.ts:45-59)
```
증거: e2e `installs the static asset set …` 2개(3엔진 통과), `serves A's removed chunk …`(chromium·webkit 통과).
### 2.2 피해가 큰 흐름 — SW를 켠 production 빌드 (06-01)
```text
APP_PROFILE=production VITE_BUILD_ID=rev node scripts/build-frontend.ts
→ [3] Vite 앱 빌드: public/ 복사 → dist/config.json = local 문서
→ [4] generate-runtime-config: dist/config.json = production 문서 (generate-runtime-config.ts:38-86)
→ [5] 자산 목록 생성 (config.json 제외)
→ [6] SW Vite 빌드: 설정 로드 시 dist/config.json(production) 읽고 APP_ENV 검사 통과
→ 출력 준비 단계에서 public/ 다시 복사 → dist/config.json = local 문서
(vite.service-worker.config.ts:51-55, :69-82;
vite node.js:32813-32815)
→ [7] generate-build-manifest: local 문서에 BUILD_ID·RELEASE_ID만 다시 찍어 저장 (:58-60, :76-77, :123-127)
→ [결과] 빌드 성공. dist/config.json = APP_ENV local · AUTH_MODE demo · API http://localhost:8080/
→ [게이트] check:release-admission(RELEASE_TARGET=production) → 거절 4건
→ [게이트 없이 배포] demo 인증·loopback API 설정이 사용자에게 감
→ [하위 경로] RELEASE_MANIFEST_URL이 /release-manifest.json으로 되돌아가 부팅 실패
```
### 2.3 변경 흐름 — 제품이 오프라인 탐색 셸을 켠다 (06-03, 06-04)
```text
제품 요구: 오프라인에서도 앱 셸이 열려야 함
→ 레시피 catalog: service-worker-pwa trigger = "a measured offline-shell requirement"
(frontend-capability-recipes.json:140)
→ 템플릿 정책: navigation → NETWORK_ONLY, index.html은 사전 캐시에서 제외, 해시 이름만
(static-assets.ts:47, generate-service-worker-assets.ts:33-39, :56)
→ 확장 지점: 없음. handler는 3종으로 닫혀 있고 엔트리는 runtime.intercepts 하나만 부름
(service-worker-entry.ts:94-111, service-worker-build-input.ts:148-161)
→ 실제 변경(memento): service-worker-lifecycle.ts +44줄(isShellNavigation, intercepts 첫 줄),
generate-service-worker-assets.ts(index.html·사진 11개 포함), vite.service-worker.config.ts
→ 검증: 템플릿 SW e2e 도우미가 null 선택 줄을 못 찾아 멈춤, 사전 캐시 기대값도 다름 (06-04)
→ 결과: 템플릿 동기화마다 같은 파일에서 충돌. "HTML과 자산은 같은 릴리스" 보호 조건의 재증명이 제품 몫
```
제거 흐름(`ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null`)은 06-06에서 다룬다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | P | M2 / M2 | E1·E2 | 런타임 검증은 exact하다. 빌드 설정이 앱 산출물을 바꾸고(06-01), 사전 캐시 URL이 base를 잃는다(06-02) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E1 | worker realm과 page realm을 tsconfig로 나눈다(`tsconfig.service-worker.json:8-17`). 엔트리는 web-push를 import하지 않는다(`service-worker-entry.ts:144-158`). 전체 의존성 게이트는 영역 12 |
| 3 | 변경 용이성 | P | M1 / M1 | E1 | 오프라인 셸·WEB_PUSH 조립 모두 템플릿 파일 수정이 필요하다(06-03, `service-worker-entry.ts:144-158`) |
| 4 | 인지 부하 | P | - | E1 | 계약 주석은 충실하다. page controller 642줄, lifecycle 736줄, push adapter 1203줄. 오프라인 셸 주장이 catalog·레시피·설계 3곳에서 다르다(06-03) |
| 5 | 위험 가시성 | P | M1 / M1 | E1 | `build-frontend.ts:31-37`은 3단계의 `public/` 복사만 설명하고 6단계의 같은 복사는 적지 않는다(06-01) |
| 6 | 실패 성숙도 | P | M2 / M2 | E1·E2 | install 실패 11종, drain 시간 초과와 명시 거절을 구분한다(06-07 해소). 워커의 거절 코드는 페이지에 오지 않아 `INSTALL_FAILED`만 남는다(06-02 조사 중 확인) |
| 7 | 운영 성숙도 **(깊게)** | P | M2 / M2(시작 실패만) | E1·E2 | 시작 실패는 `service-worker.start.failed`로 남는다(`optional-runtime-host.ts:105-120`, `tests/component/runtime-composition-service-worker-telemetry.test.ts`). 업데이트 설치 실패, `observe`, `health()`는 연결되지 않았다(FOLLOW-UP 06-05 유효: `src`에서 `.health()` 호출 0건, composition이 `observe`·`blockers`를 넘기지 않음). 06-02의 설치 실패는 이 이벤트로만 보이고 원인은 워커 안에 남는다 |
| 8 | 디버깅 가능성 | P | M2 / M1 | E1 | `observe` hook과 reason 코드는 있으나 조립되지 않는다(7번과 같은 원인) |
| 9 | 유지보수 성숙도 | P | M1 / M1 | E1 | `void SERVICE_WORKER_BOUNDS.retainedPreviousCaches`(`service-worker-lifecycle.ts:169`)는 여전히 아무 일도 하지 않는다. 운영 문서는 코드 경로를 가리키도록 고쳐졌다 |
| 10 | 테스트 성숙도 | P | M3 / M3(기본 구성) | E2·E3 | 단위 153 통과, 변이 3종 모두 검출, SW e2e 3엔진 확인. SW를 켠 비 local 빌드(06-01)·하위 경로(06-02) 테스트가 없고, SW를 켠 트리에서는 e2e가 멈춘다(06-04) |
| 11 | 데이터 성숙도 | O | M2 / M2 | E1 | 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다. 소유 캐시 이름은 exact 비교(`src/contracts/service-worker.ts` `isOwnedStaticCacheName`). push fence에 계정 ID와 endpoint가 없다 |
| 12 | 동시성 성숙도 **(깊게)** | P | M3 / M3 | E2 | 탭 사이 enable·reconcile·revoke는 Web Lock으로 직렬화되고 변이로 검출된다(`push-subscription-adapter.ts:494-499`, 테스트 `:976-1172`). SW 활성화는 single-flight·nonce·source 동일성 검사. 남은 것: 응답하지 않는 창 하나가 활성화를 막는다(`service-worker-lifecycle.ts:344-347` `includeUncontrolled: true`, 안전한 쪽 실패). `revokeForeign`은 호출자가 최신 세션 authority를 넘긴다는 규칙에 기댄다(`web-push-control.ts:29-38`, M1). lock 대기 자체에는 상한이 없고 호출자 signal에 기댄다(추론, 4.3절) |
| 13 | 확장성 | P | M2 / M2 | E1 | 256개·5 MiB 상한을 빌드에서 막는다(`generate-service-worker-assets.ts:60-86`). 이번 production 빌드는 28개. 기능 증가에 따른 도달 시점은 미측정 |
| 14 | 성능 성숙도 | O | M2 / M2 | E1·E2 | fetch 리스너는 `PWA_STATIC_ASSETS`일 때만 등록되고 `/assets/` 아래 해시 GET만 가로챈다(06-08 해소, `service-worker-runtime.test.ts:1985-1996`). `assets/` 하드코딩은 FOLLOW-UP 06-08로 남음 |
| 15 | 보안 성숙도 **(깊게)** | P | M3 / M2~M3 | E1·E2·E3 | payload를 신뢰하지 않고, 클릭 URL은 same-origin만 연다. 클릭 facade는 WebIDL 모양으로 고쳐졌다(`web-push/service-worker-runtime.ts:283`). 06-01은 demo 인증 설정을 production 산출물에 넣지만 admission이 거절했다(실행 확인). `revokeForeign`은 증명 없이 fence를 넘기므로 오래된 세션 탭이 부르면 현재 계정 연결을 끊는다(문서화, 끊는 방향이라 노출은 없음) |
| 16 | 의존성 성숙도 | P | - | E3 | 런타임 외부 패키지는 없다. SW 빌드가 Vite 8.1.5에서 `inlineDynamicImports option is deprecated` 경고를 낸다(빌드 로그). "출력 1파일" 규칙(`…closed-deep-design.md:3400-3405`)을 확인하는 테스트는 파일 존재만 본다(`service-worker-update.spec.ts:266-271`) |
| 17 | API / Contract 성숙도 | P | M2 / M2 | E1 | SW 메시지 V1 exact, push 포트는 `revokeForeign` 추가만(파괴적 변경 없음). SW handler 계약에 오프라인 셸이 없는데 catalog는 이 용도를 약속한다(06-03) |
| 18 | 배포 성숙도 **(깊게)** | P | M3 / M2 | E3 | 옛 탭 청크 fallback과 업데이트 핸드셰이크는 e2e로 확인했다. SW를 켜면 릴리스 산출물의 설정이 틀리고(06-01), 워커 스크립트의 CDN 캐시 정책은 선언·검사되지 않는다(06-05) |
| 19 | 설정 성숙도 **(깊게)** | X | M3 / M1 | E3 | SW를 켜는 순간 프로필 설정·`RUNTIME_*` 주입·base path 재작성이 모두 local 문서로 되돌아간다(06-01). 06-10의 APP_ENV 검사(`service-worker-build-input.ts:179-183`)는 덮어쓰기 전 입력만 본다. 사전 캐시 URL과 SW의 runtime config URL 기본값이 base를 무시한다(06-02, `vite.service-worker.config.ts:94-96`) |
| 20 | 개발자 경험 | P | M1 / M1 | E1·E3 | SW 켜기 체크리스트가 있다(`optional-adapter-recipes.md:109-131`). 활성화 UI·observe는 `create-runtime-composition.ts`를 직접 고쳐야 한다. SW를 켜면 템플릿 e2e가 멈춘다(06-04) |
| 21 | Guardrail 성숙도 | P | M3 / M3(일부) | E2·E3 | build-input 거절, hosting 검사의 워커 파일 검사, release admission은 동작한다. SW 빌드가 dist를 바꾸지 않는지(06-01)와 워커 스크립트 헤더(06-05)는 검사하지 않는다 |
| 22 | 추상화 성숙도 | O | M2 / M2 | E1·E2 | 구조적 facade로 워커 없이 테스트한다. fake가 WebIDL 모양을 따르도록 고쳐져 06-01(2026-09-25) 같은 차이를 가리지 않는다(`web-push-worker-runtime.test.ts:110-120`) |
| 23 | 일관성 | P | - | E1 | 같은 repo의 두 번째 Vite 빌드(`scripts/lib/optional-recipe-bundle.ts:117`, `:127`)는 `publicDir: false`·`copyPublicDir: false`인데 SW 빌드만 없다(06-01). `validateActiveFence` 두 벌(`push-event-adapter.ts:196`, `notification-click-adapter.ts:353`)은 operation 이름만 다르고 갈라지지 않았다 |
| 24 | 네이밍 / 의미 | P | - | E1 | 06-07로 시간 초과가 `CLIENT_DRAIN_TIMEOUT`으로 분리됐다. `retainedPreviousCaches` 상수는 읽히지 않고 "이전 1개"는 코드에 고정돼 있다(9번과 같은 항목) |
| 25 | 조직 확장성 | - | - | - | 적용 제외: 1인 관리 전제(0.1). 구조적 준비는 다른 영역 |
| 26 | Ownership 성숙도 | P | M1 / M1 | E1 | 운영 문서가 코드 경로를 가리킨다(`release-cache-rollback.md:79-109`, `browser-file-storage-recovery.md` 8절). 제거 1단계의 유지 기간이 없다(06-06) |
| 27 | 삭제 가능성 | ? | M3 / 미확인 | E1 | 엔트리가 web-push를 import하지 않아 파일 삭제로 뺄 수 있다고 주장한다. `test:realtime-removal`은 이번에 끝까지 돌리지 못했다(7절) |
| 28 | 회복 가능성 **(깊게)** | P | M3 / M3(페이지·워커) | E2·E3 | 런타임 kill switch는 변이로 검출되고(06-04 해소), 부팅을 막는 워커는 자기 해제 워커로 걷어낸다(e2e chromium·webkit). 그 경로는 CDN이 `service-worker.js`를 캐시하지 않는다는 전제에 기대는데 검사가 없다(06-05). 제거 2·3단계에서 비상 경로가 사라진다(06-06, 404 등록 유지 3엔진 확인) |
집계: 적용 27개 중 O 5 · P 20 · X 1 · ? 1, 적용 제외 1.
## 4. 설계 선택 설명 (41절)
### 4.1 오프라인 셸 없이 해시 파일만 캐시한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 새 배포 뒤 옛 탭이 청크를 잃지 않는 것, 캐시된 바이트가 빌드 산출물과 같은 것. 오프라인 셸은 catalog의 설치 조건에 있지만(`frontend-capability-recipes.json:140`) 설계는 비지원이다(`…closed-deep-design.md:327`) |
| 2. 지킬 성질 | HTML과 자산이 같은 릴리스에서 온다. 새 배포 뒤 HTML은 항상 새것이다. 인증 응답은 캐시하지 않는다(`:3842-3850`) |
| 3. 현재 보장 | navigation은 `NETWORK_ONLY`(`service-worker-static-assets.ts:47`), `index.html` 제외(`generate-service-worker-assets.ts:33-39`), install 시 sha256 검증. 오프라인 부팅은 보장하지 않는다 |
| 4. 대안 | (a) 현상 유지 (b) 비지원 유지 + catalog·레시피 정정 + 졸업 경로 문서 (c) 선택 handler `OFFLINE_NAVIGATION_SHELL`: navigation은 네트워크 먼저, 실패 시 **현재 릴리스 캐시의** `index.html` (d) 워커 런타임에 일반 interceptor 배열 |
| 5. 비교 | (a) 비용 0, 주장 모순과 제품의 템플릿 파일 수정이 남음. (b) 문서 수정만, 제품 수정 비용은 그대로지만 예측 가능. (c) 조합 1개 추가(30.2)·e2e 1개·설계 금지 목록 수정. 현재 릴리스 캐시의 HTML만 쓰면 "같은 릴리스" 성질을 지킨다. (d) 동기 `intercepts` 결정을 여러 hook이 나눠 가져 순서·충돌 규칙이 새로 생긴다. 가장 비쌈 |
| 6. 현재 조건의 선택 | 기본값(오프라인 셸 없음)은 유지가 타당하다. 소비자 2개 중 1개만 필요하다. 다만 (a)는 catalog 주장과 코드가 반대라 받아들일 수 없고 최소 (b)가 필요하다(06-03) |
| 7. 재검토 조건 | 두 번째 소비자가 오프라인 셸을 요구하거나, memento의 lifecycle 수정이 다음 동기화에서 다시 충돌하면 (c)를 비교한다 |
- 확인한 사실: 코드의 분류 규칙, memento diff(템플릿 파일 3개 수정).
- 기록된 의도: 설계 문서의 "baseline has no offline shell", "installability/offline document is a separate product capability".
- 리뷰어의 추론: (c)가 "같은 릴리스" 성질을 지킨다는 판단. memento 구현이 이 성질을 지키는지는 이 리뷰 범위 밖이다.
### 4.2 SW를 두 번째 Vite 빌드로 만든다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 워커가 앱 빌드의 해시 자산 목록을 컴파일 시점에 가진다(`scripts/build-frontend.ts:10-13`, 설계 "the worker never fetches one"). |
| 2. 지킬 성질 | 워커 출력은 `dist/service-worker.js` 하나다. 두 번째 빌드는 앱 산출물을 바꾸지 않는다(암묵적 성질, 어디에도 적혀 있지 않음) |
| 3. 현재 보장 | 입력 1개, `emptyOutDir: false`, `inlineDynamicImports`(`vite.service-worker.config.ts:69-82`). 앱 산출물 불변은 보장하지 않는다. `public/` 복사가 `dist/config.json`을 바꾼다(06-01) |
| 4. 대안 | (a) 현상 유지 + `publicDir: false` (b) 앱 빌드 plugin의 `closeBundle`에서 워커를 만든다 (c) Vite `build()`를 `configFile: false`로 호출(`optional-recipe-bundle.ts:112-130`과 같은 방식) (d) 워커가 런타임에 목록을 받는다 |
| 5. 비교 | (a) 한 줄, 단계가 나뉘어 실패 지점이 분명하고 e2e가 실제 스크립트를 탄다. (b) 빌드 1회로 줄지만 앱 빌드 설정에 워커 지식이 섞인다. (c) 기본값이 명시적이지만 스크립트 한 개 추가. (d) 설계가 금지한다(목록 위조·신선도 문제) |
| 6. 현재 조건의 선택 | two-pass 유지가 타당하다. 다만 성질 2를 설정(`publicDir: false`)과 테스트로 고정해야 한다 |
| 7. 재검토 조건 | Vite가 `inlineDynamicImports`를 없애거나(이미 경고), 워커가 여러 청크를 필요로 하면 (b)·(c)를 다시 비교한다 |
- 확인한 사실: Vite 8.1.5 `prepareOutDir`의 복사, 빌드 재현.
- 기록된 의도: `build-frontend.ts:31-37` 주석은 `public/` 복사를 알고 4단계를 3단계 뒤에 뒀다. 6단계의 복사는 기록에 없다.
- 리뷰어의 추론: 성질 2는 작성자가 전제했지만 적지 않은 규칙으로 본다.
### 4.3 탭 사이 Web Push 제어를 Web Lock으로 직렬화하고, 계정 전환은 증명 없는 `revokeForeign`으로 푼다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 여러 탭이 native 구독 1개와 origin fence 1개를 공유한다. 로그아웃 없이 계정이 바뀌면 새 세션은 이전 authority를 모른다 |
| 2. 지킬 성질 | `PUSH_READY`를 보고한 탭이 있으면 native 구독과 서버 연결이 살아 있다. 이전 계정의 push가 새 계정에 계속 표시되지 않는다(최종 방어는 서버 send-time 인가) |
| 3. 현재 보장 | `exclusive`가 `navigator.locks.request("web-push-control")` 안에서 mutation을 돌린다(`push-subscription-adapter.ts:467-506`). 우회 변이 → 3개 실패. `revokeForeign`은 같은 `fenceGeneration`이면 건드리지 않는다(`:410-447`). 검사 제거 변이 → 2개 실패. 보장하지 않는 것: lock 대기 자체의 상한(호출자 signal에 기댐), 오래된 세션 탭의 호출(포트 문서가 금지, `web-push-control.ts:29-38`) |
| 4. 대안 | (a) CAS 실패 뒤 fence를 다시 읽어 수렴 (b) Web Lock(현재) (c) BroadcastChannel 리더 선출 (d) 서버 상태만 신뢰 |
| 5. 비교 | (a) lock 없이 되지만 보상 분기마다 수렴 규칙이 필요하다. 지난 리뷰 재현 순서 2개를 각각 따로 막아야 한다. (b) 브라우저 기본 기능 하나로 두 순서가 사라진다. 없으면 `PUSH_UNSUPPORTED`로 닫는다. (c) 리더 교체 중 경합이 다시 생긴다. (d) native 구독이 브라우저에만 있어 불가능 |
| 6. 현재 조건의 선택 | (b)가 타당하다. `revokeForeign`의 무증명은 `fenceGeneration`이 순서 없는 문자열(`src/contracts/web-push.ts` `PushAuthoritySnapshot`)이라 순서 검사를 할 수 없는 현재 계약에서 가장 작은 수단이다. 잘못 부르면 연결을 끊는 쪽이라 노출은 없다 |
| 7. 재검토 조건 | 서버가 순서 있는 세대 값을 주면 `revokeForeign`에 "저장된 세대 < 다음 세대" 검사를 넣는다. lock 대기 중 멈춤이 관측되면 `exclusive`에 대기 상한을 둔다 |
- 확인한 사실: 변이 결과, 포트 문서.
- 기록된 의도: `realtime-events-web-push-and-bounded-polling.md:1319-1328`, `:1348-1366`.
- 리뷰어의 추론: 얼어 있는 탭이 lock을 쥔 채 멈출 수 있는지는 브라우저 정책에 달렸다. 재현하지 않았다.
## 5. 발견 사항 (36.3)
### 06-01 SW를 켜면 두 번째 Vite 빌드가 `public/`을 다시 복사해 프로필의 `dist/config.json`을 local 문서로 덮어씀
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 18, 15, 10, 21, 23 |
| 근거 | `vite.service-worker.config.ts:69-82`에 `publicDir`·`build.copyPublicDir` 설정이 없다. Vite 8.1.5는 `emptyOutDir: false`여도 출력 준비 단계에서 `public/`을 `fs.copyFileSync`로 덮어쓴다(`node_modules/vite/dist/node/chunks/node.js:32813-32815`, `:2426-2434`). 6단계 SW 빌드는 설정 로드 때 `dist/config.json`(production)을 읽어 06-10 검사를 통과한 뒤(`:51-55`, `service-worker-build-input.ts:179-183`) 같은 파일을 `public/config.json`으로 덮는다. 7단계는 그 문서에 식별자만 다시 찍고 저장한다(`scripts/generate-build-manifest.ts:58-60`, `:76-77`, `:123-127`). **재현 1**(worktree, SW `ACTIVE`, `APP_PROFILE=production VITE_BUILD_ID=rev-prod-1`): 빌드 exit 0, 결과 `APP_ENV: local`, `AUTH_MODE: demo`, `API_BASE_URL: http://localhost:8080/`, `TELEMETRY_ENABLED: false`, 식별자만 `rev-prod-1`. `RELEASE_TARGET=production node scripts/check-release-admission.ts` → 거절 4건(APP_ENV, AUTH_MODE, API http, localhost). **재현 2**(`VITE_ROUTER_BASE_PATH=/app/`, local): `generate-runtime-config.ts:59-67`이 만든 `/app/release-manifest.json`이 `/release-manifest.json`으로 되돌아간다. Chromium에서 `/app/`을 열면 `404 /release-manifest.json` 뒤 "애플리케이션을 시작할 수 없습니다." **변이**: `publicDir: false` 한 줄을 넣으면 같은 production + `/app/` 빌드가 `APP_ENV: production`, `/app/release-manifest.json`을 유지하고 admission이 ADMITTED. 같은 repo의 다른 두 번째 빌드는 이미 끈다(`scripts/lib/optional-recipe-bundle.ts:117`, `:127`). 소비자: memento는 SW `ACTIVE`로 이 결함을 만나 `publicDir: false`를 유지했고 "latent template defect"로 기록했다(`docs/operations/template-sync-2026-09-29.md` Service Worker 절, follow-up 2) |
| 발생 조건 | SW `ACTIVE` + local이 아닌 프로필, 또는 `VITE_ROUTER_BASE_PATH`, 또는 `RUNTIME_API_BASE_URL`·`RUNTIME_TELEMETRY_ENDPOINT` 주입 |
| 영향 | development·staging·production 산출물이 모두 local 설정을 싣는다. admission이 돌면 배포가 거절되는데 메시지("artifact declares local")로는 SW와 연결하기 어렵다. admission 없이 배포하면(템플릿 CI는 아직 Gitea runner에서 돈 적이 없다, U-1) demo 인증·loopback API 설정이 사용자에게 간다. 하위 경로 배포는 프로필과 관계없이 부팅하지 못한다 |
| 심각도·우선순위 | High · P1. SW `ACTIVE`는 레시피가 안내하는 지원 옵션이다(`optional-adapter-recipes.md:112-113`). 켜는 순간 모든 비 local 릴리스가 불가능하거나 틀린다. 기본 구성(`null`)에는 영향이 없다 |
| 통제·증거 | 빌드 단계 M0(두 번째 빌드가 dist를 바꾸지 않게 하는 장치 없음), 사후 admission M3 · E3(빌드·admission·Chromium) + 소비자 기록 |
| 확실성과 남은 가정 | 확인. Vite 8.1.5 기준이다 |
| 결정의 근거 | 적용 제외 — 두 번째 빌드가 `public/`을 복사할 이유가 없고 같은 repo의 다른 두 번째 빌드가 이미 끈다. two-pass 자체는 4.2절에서 유지가 타당하다고 봤다 |
| 이해 비용 | `build-frontend.ts:31-37`이 3단계 복사만 설명해서, 6단계도 같은 복사를 한다는 사실은 Vite 내부를 읽어야 안다 |
| 최소 개선 방향 | `vite.service-worker.config.ts`에 `publicDir: false`. `build-frontend.ts` 6단계 주석에 "public 복사 없음" 한 줄 |
| 대안 비교 | 적용 제외 — 명백한 계약 위반의 단순 수정이다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 한 줄. 워커 빌드는 `public/` 파일을 쓰지 않는다 |
| 재검토 조건 | 적용 제외 — 선택을 바꾸는 판단이 아니다 |
| 완료 기준 | SW `ACTIVE` + `APP_PROFILE=production` + `VITE_ROUTER_BASE_PATH=/app/` 빌드 뒤 `dist/config.json`이 `generateRuntimeConfig("production", env)` 결과와 같다 |
| 검증 방법 | SW를 켠 빌드(e2e 도우미나 fixture)를 production 프로필로 돌려 `dist/config.json`을 대조하는 테스트 1개. `publicDir: false`를 지우는 변이로 실패하는지 본다. FOLLOW-UP 06-10(P3, SW Vite 설정 입력 테스트 없음)도 이 테스트로 닫힌다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 2026-09-25 06-10(설정 출처)에서 놓쳤다. 06-10의 완료 기준(워커가 프로필 값을 씀)은 충족되지만 페이지 설정은 틀린다. 회귀가 아니라 처음부터 있던 결함이다(`4626b73`의 빌드 순서도 같음) |
### 06-02 SW 사전 캐시 목록이 router base path를 무시해 하위 경로 배포에서 워커 설치가 항상 실패함
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 18, 1, 10, 7 |
| 근거 | generator가 URL을 `/${relative}`로 만든다(`scripts/generate-service-worker-assets.ts:66`). base를 읽지 않는다. 워커는 manifest URL을 scope 기준으로 풀지만 root-relative라 base가 사라진다(`service-worker-lifecycle.ts:67-88`). 앱은 `/app/assets/…`를 요청한다(`vite.config.ts:64-67` `base`). **재현**(worktree, SW `ACTIVE`, `VITE_ROUTER_BASE_PATH=/app/`, 06-01 영향을 빼려고 config의 manifest URL만 `/app/…`로 고침, 서버는 `/app/` 아래만 서빙): Chromium에서 앱은 부팅하고 `/app/service-worker.js`를 받는다. 워커 install이 `/assets/application-provider-….js` 등 base 없는 경로를 요청해 404 → install 거절 → `getRegistration()` undefined, owned cache 0개. 같은 설정 안에서 06-08 fallback은 base를 따른다(`service-worker-static-assets.ts:66-78`). SW 빌드의 runtime config URL 기본값도 base를 무시한다(`vite.service-worker.config.ts:94-96`, 페이지는 `/app/config.json`, `tests/unit/sub-path-deployment.test.ts:23-31`). `vite.config.ts:26-33`은 "하위 경로 배포가 일관되거나 빌드에서 실패한다"고 주장한다. 하위 경로 SW 테스트는 없다 |
| 발생 조건 | SW `ACTIVE` + `VITE_ROUTER_BASE_PATH`가 `/`가 아님. 06-01을 고친 뒤에 드러난다 |
| 영향 | 워커가 설치되지 않는다. 앱은 네트워크로 정상 동작한다(안전한 쪽 실패). 옛 탭 청크 보존 등 SW의 이점이 전부 없다. 페이지에는 `service-worker.start.failed`(`INSTALL_FAILED`)만 남고 원인(`STATUS_INVALID`)은 워커 안에 있다 |
| 심각도·우선순위 | Medium · P2. 피해가 기능 부재로 한정된다 |
| 통제·증거 | M0(base와 manifest URL 일치 검사 없음) · E3(Chromium 1회) |
| 확실성과 남은 가정 | WebKit·Firefox는 돌리지 않았다. 같은 URL 해석이라 결과가 같다고 추론한다 |
| 결정의 근거 | 적용 제외 — "하위 경로 일관성"이 이미 정해진 계약이다 |
| 이해 비용 | 하위 경로 값을 읽는 곳이 `vite.config.ts`, `generate-runtime-config.ts`, `expectedServiceWorkerUrls`, 06-08 fallback 네 곳인데 generator와 SW 빌드는 빠졌다 |
| 최소 개선 방향 | generator가 `VITE_ROUTER_BASE_PATH`를 URL 앞에 붙인다(root-relative라 `isCanonicalStaticAssetUrl`을 그대로 통과). SW 빌드의 runtime config URL은 `getBuildConfig`(`src/contracts/env.ts`)로 계산한다 |
| 대안 비교 | 적용 제외 — 워커 쪽에서 scope 상대로 푸는 방법도 있지만 계약 차이는 없고 generator 수정이 워커를 바꾸지 않아 더 작다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 수 줄. manifest digest가 base마다 달라진다(의도된 결과) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `/app/` 빌드의 manifest URL이 모두 `/app/assets/`로 시작하고, e2e 도우미를 base 옵션으로 돌린 첫 설치가 `RELOAD_TO_ENABLE`이다 |
| 검증 방법 | `collectStaticAssets` 단위 테스트 1개 + e2e 도우미에 base 옵션 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음. 06-09(클릭 fallback base)와 같은 부류다 |
### 06-03 레시피는 오프라인 셸을 SW 설치 조건으로 적지만, SW 계약은 이를 금지하고 제품이 켤 확장 지점도 없음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(주장과 코드 불일치 포함) |
| 관련 관점 | 17, 3, 20, 5, 4 (30.3, 30.7) |
| 근거 | catalog: `"trigger": "Installability, a measured offline-shell requirement, …"`(`config/recipes/frontend-capability-recipes.json:140`), failureKinds에 `offline-fallback`. 레시피 문서: "install/offline shell"(`optional-adapter-recipes.md:94`). 코드: navigation `NETWORK_ONLY`(`service-worker-static-assets.ts:47`), `intercepts()`는 두 분류만(`service-worker-lifecycle.ts:272-278`), `index.html` 제외·해시 이름만(`generate-service-worker-assets.ts:33-39`, `:56`). 설계: 오프라인 셸 비지원(`…closed-deep-design.md:327`, `:3842-3850`), 금지 목록 "cache index.html navigation fallback"(`:5897`). 확장 지점: handler 3종 고정(`service-worker-build-input.ts:148-161`), 엔트리는 `runtime.intercepts` 하나만 부른다(`service-worker-entry.ts:94-111`). 소비자: memento는 `service-worker-lifecycle.ts`(+44줄, `isShellNavigation`과 `intercepts` 첫 줄), `generate-service-worker-assets.ts`(`index.html`·사진 11개), `vite.service-worker.config.ts`를 고쳤다(`git diff af3d8e6 chore/template-sync-v0.2.0`) |
| 발생 조건 | 제품이 설치형 PWA나 오프라인 탐색을 요구한다 |
| 영향 | 제품이 템플릿 소유 파일의 동기 가로채기 결정을 고친다. 이후 동기화마다 같은 파일에서 충돌한다(memento는 이번 동기화에서 실제로 충돌을 풀었다). 템플릿이 금지한 동작을 템플릿 검증 없이 넣으므로 "HTML과 자산은 같은 릴리스" 성질(`:3847-3849`)을 제품이 다시 증명해야 한다. catalog를 보고 온 사용자는 코드가 이를 금지한다는 것을 뒤늦게 안다 |
| 심각도·우선순위 | Medium · P2. 기능 결함이 아니라 도입·업데이트 비용과 주장 불일치다 |
| 통제·증거 | 설계 문서 M1, catalog는 반대 주장 · E1(코드) + 소비자 diff |
| 확실성과 남은 가정 | 소비자 한 곳의 사례다. tech-log는 SW `null`이다 |
| 결정의 근거 | 4.1절. 확인한 사실: 분류 규칙과 memento diff. 기록된 의도: 설계의 비지원 명시. 추론: 선택 handler가 "같은 릴리스" 성질을 지킬 수 있다 |
| 이해 비용 | 제품 개발자는 catalog·레시피 문서·설계 문서의 서로 다른 주장을 읽고, 엔트리 → lifecycle → static-assets → generator 4파일을 따라가야 오프라인 셸을 넣을 곳을 안다 |
| 최소 개선 방향 | catalog와 레시피 문서의 "offline shell"을 설계와 맞춘다. 비지원을 적고, 졸업 경로(제품이 넘겨받는 파일, 바꿔야 할 e2e와 기대값)를 둔다. 선택 handler는 재검토 조건이 오면 한다 |
| 대안 비교 | 4.1절 표: 현상 유지(주장 모순 남음) / 문서 정정 + 졸업 경로(최소) / 선택 handler `OFFLINE_NAVIGATION_SHELL`(조합 1개·e2e 1개) / 일반 interceptor hook(순서·충돌 규칙이 새로 생겨 가장 비쌈) |
| 단순화의 보존 조건 | 기본 구성에서 navigation은 network-only, `index.html`은 기본 manifest에 없다. handler를 추가한다면 현재 릴리스 캐시의 HTML만 쓰고 이전 릴리스 HTML은 쓰지 않는다 |
| 비용·부작용 | 문서 정정은 작다. handler는 설계 금지 목록 수정과 조합 검증 책임(30.2)이 생긴다 |
| 재검토 조건 | 두 번째 소비자가 오프라인 셸을 요구하거나, memento의 lifecycle 수정이 다음 동기화에서 다시 충돌하면 handler를 비교한다 |
| 완료 기준 | catalog·레시피·설계의 오프라인 셸 주장이 같다. 제품이 템플릿 파일을 고치지 않고 켜는 경로가 있거나, 없다는 사실과 졸업 절차가 문서에 있다 |
| 검증 방법 | 세 문서 대조. handler를 고르면 오프라인 navigation e2e와 "이전 릴리스 HTML 비사용" 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음 |
### 06-04 SW e2e 도우미가 선택 `null` 줄을 문자열로 바꿔서, SW를 켠 제품에서는 update·recovery spec이 모두 멈춤
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 20, 21 (30.4) |
| 근거 | 도우미는 `const SERVICE_WORKER: InstalledServiceWorkerSelection \| null = null;`을 찾아 바꾸고(`tests/e2e/support/service-worker-builds.ts:125-129`), 정확히 한 번 없으면 throw한다(`:83-93`). recovery spec은 그 결과 문자열을 다시 찾는다(`service-worker-recovery.spec.ts:42-49`). install spec은 캐시 경로가 `dist/assets` 전체와 같아야 한다고 본다(`service-worker-update.spec.ts:86-90`, `:124`). **변이**: worktree에서 선택을 `ACTIVE`로 바꾸고 update spec을 돌렸더니 `beforeAll`에서 `Expected exactly one "const SERVICE_WORKER: … = null;"`로 5개 모두 실패·미실행. `builds`가 undefined라 temp 폴더(`ca-sw-builds-*`)도 남는다. 소비자: memento e2e의 새 템플릿 spec 실패 3 / 미실행 4 중 SW spec 2개를 "후속"으로 남겼다 |
| 발생 조건 | 다운스트림이 SW를 켠다. 이 spec이 실제로 필요한 유일한 상황이다 |
| 영향 | 업데이트 핸드셰이크·옛 청크 fallback·자기 해제 복구의 브라우저 증거(18, 28)가 SW를 쓰는 제품에서만 사라진다. 제품은 템플릿 테스트를 고치거나 격리해야 한다 |
| 심각도·우선순위 | Medium · P2 |
| 통제·증거 | 템플릿 기본 상태 M3, SW를 켠 제품 M0 · E3(변이 실행) |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 적용 제외 — 도우미 입력 방식의 결함이다 |
| 이해 비용 | 제품 개발자가 도우미의 문자열 치환 두 단계를 읽어야 실패 원인을 안다 |
| 최소 개선 방향 | 도우미가 현재 `SERVICE_WORKER` 선언 전체를 값과 무관하게 찾아 `ACTIVE_SELECTION`으로 바꾼다. install spec의 기대값은 그 빌드가 만든 `.generated/frontend-runtime/service-worker-assets.ts` 목록과 비교한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 도우미 수 줄. 06-03의 사전 캐시 확장과 함께 보면 기대값 비교가 자연스럽다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 선택이 `ACTIVE`인 트리와 `null`인 트리에서 두 spec이 모두 통과한다 |
| 검증 방법 | 위 변이를 다시 적용해 통과하는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 해당 없음. FOLLOW-UP P3("route chunk를 바꾸는 변경"을 도우미 옵션으로)와 같은 도우미다 |
### 06-05 설계가 호스팅 설정에 맡긴 `service-worker.js`의 `no-cache`가 호스팅 정책 파일과 live probe에 없음
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(설정 누락) + 구조적 위험(복구 경로) |
| 관련 관점 | 18, 28, 19, 21 |
| 근거 | 설계: `service-worker.js Cache-Control = no-cache` … "Static delivery configuration owns this requirement"(`…closed-deep-design.md:3411-3418`). 레시피 6단계도 같다(`optional-adapter-recipes.md:130-131`). 정적 전달 설정 `config/hosting/cache-policy.json`에는 index·config·release manifest·`/assets/*`만 있다. live probe도 이 네 곳만 요청한다(`scripts/verify-hosting-headers.ts:120-125`). SW 관련 검사는 dist에 파일이 있는지뿐이다(`scripts/lib/hosting-probe.ts:37-58`). 등록은 `updateViaCache: "none"`이라 브라우저 HTTP 캐시는 우회한다(`service-worker-page-controller.ts:157-161`). CDN·프록시 캐시는 우회하지 못한다(표준 동작, 추론) |
| 발생 조건 | SW `ACTIVE`(또는 `REMOVE_REGISTRATION`) + CDN이 루트 `.js`에 긴 TTL을 준다(예: `*.js`를 immutable로 묶는 규칙) |
| 영향 | 새 워커와 자기 해제 워커가 edge TTL 동안 사용자에게 가지 않는다. 롤백과 비상 해제가 늦어지고 게이트는 이를 알리지 않는다 |
| 심각도·우선순위 | Medium · P2. 발생은 호스팅 설정에 달렸지만, 막히는 것이 페이지 없는 유일한 복구 경로다 |
| 통제·증거 | M1(문서만) · E1 |
| 확실성과 남은 가정 | 실제 CDN에서 재현하지 않았다 |
| 결정의 근거 | 적용 제외 — 설계가 이미 요구와 책임 위치를 정했다 |
| 이해 비용 | 운영자는 cache-policy.json이 전체 정적 전달 정책이라고 믿기 쉽다 |
| 최소 개선 방향 | cache-policy.json에 `serviceWorker` 항목(`/service-worker.js`, `no-cache`, `text/javascript`)을 둔다. 선택이 `ACTIVE`·`REMOVE_REGISTRATION`일 때 live probe가 요청한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 설정 1항목, probe 조건 1개. SW `null` 구성에는 추가 요청이 없다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | SW를 켠 구성에서 fixture의 `service-worker.js` Cache-Control을 틀리게 바꾸면 `verify:hosting-headers`가 FAIL |
| 검증 방법 | fixture 변이 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 2026-09-25 판정표 19번에 "Cache-Control 미검사"로 적혔지만 발견 항목이 아니어서 닫히지 않았다 |
### 06-06 제거 2·3단계는 `service-worker.js`를 내보내지 않아, 부팅을 막는 워커가 1단계 기간에 오지 않은 사용자에게 남음
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 28, 18, 26 |
| 근거 | 자기 해제 워커는 `REMOVE_REGISTRATION`에서만 쓴다(`scripts/build-frontend.ts:72-77`). hosting 검사는 `PURGE_OWNED_RESOURCES`·`null`에서 워커 파일이 있으면 실패시킨다(`scripts/lib/hosting-probe.ts:43-45`). **실험**: 워커 등록 뒤 스크립트를 404로 바꾸고 `update()`와 새 navigation → Chromium·WebKit·Firefox 모두 update는 TypeError로 거절되고 등록과 active 워커가 남는다. 운영 문서는 세 단계 순서만 적고 1단계 유지 기간을 적지 않는다(`docs/operations/release-cache-rollback.md:99-109`) |
| 발생 조건 | 부팅을 막는 워커 → `REMOVE_REGISTRATION` 배포 → 그 기간에 방문하지 않은 사용자가 `PURGE_OWNED_RESOURCES` 이후에 방문 |
| 영향 | 페이지가 부팅하지 않아 페이지 쪽 해제도 못 한다. 사용자가 사이트 데이터를 지우기 전까지 복구되지 않는다 |
| 심각도·우선순위 | Low · P3. 이미 드문 비상 상황 중 일부 사용자다 |
| 통제·증거 | M1 · E3(404 등록 유지, 3엔진) |
| 확실성과 남은 가정 | 사용자 방문 분포는 제품마다 다르다 |
| 결정의 근거 | 적용 제외 — 절차 누락이다 |
| 이해 비용 | 운영자는 "1단계를 언제 끝내도 되는가"를 코드와 브라우저 동작에서 추론해야 한다 |
| 최소 개선 방향 | 운영 문서에 "부팅을 막는 워커였다면 1단계를 사용자 최대 미방문 기간만큼 유지" 한 줄. 또는 2단계도 자기 해제 워커를 내보내고 hosting 허용 목록을 맞춘다 |
| 대안 비교 | 적용 제외 — 두 방법 모두 작고, 문서 한 줄이 먼저다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 한 줄. 코드로 가면 빌드 분기 1개와 hosting 검사 수정 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 운영 문서에 유지 기간 조건이 있다. 또는 2단계 dist에 자기 해제 워커가 있고 hosting 검사가 통과한다 |
| 검증 방법 | 문서 대조. 코드로 가면 `service-worker-recovery.spec.ts`에 "B 대신 PURGE 빌드" 사례 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 직전 리뷰 | 2026-09-25 미검증 목록의 "404일 때 등록 유지"를 이번에 3엔진에서 확인했다 |
## 6. FOLLOW-UP 재확인 (`2026-09-25-maturity-review/FOLLOW-UP.md`)
| 항목 | 결과 | 현재 근거 |
|---|---|---|
| P2 06-05: 업데이트 설치 실패·`observe`·`health()` 미연결 | 유효 | `watchForUpdates`는 `installed`만 알린다(`service-worker-page-controller.ts:328-349`). `src`에 `.health()` 호출 0건. `create-runtime-composition.ts`는 `telemetry`만 넘기고 `observe`·`blockers`는 넘기지 않는다 |
| P2 06-08: fallback이 `assets/`를 하드코딩 | 유효 | `service-worker-static-assets.ts:66` `BUILD_ASSET_DIRECTORY = "assets/"`. `vite.config.ts`는 `build.assetsDir`를 정하지 않는다 |
| P3 06-10: SW Vite 설정의 `dist/config.json` 읽기에 단위 테스트 없음 | 유효 | 테스트는 `resolveServiceWorkerBuildInput`만 본다. 이 빈틈 때문에 06-01이 보이지 않았다. 06-01의 검증 테스트가 함께 닫는다 |
| P3 `service-worker-update.spec.ts`의 route chunk 변경용 export 덧붙이기 | 유효 | `service-worker-update.spec.ts:38-57`(`CHANGED_ROUTE_SOURCE`에 export 추가). 도우미 옵션으로 올리지 않았다. 06-04와 같은 도우미다 |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| `test:realtime-removal`(web-push 삭제 가능성, 27) | worktree에서 `pnpm`이 링크된 `node_modules`에 설치를 시도했다(`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`). 메인 `node_modules`를 지울 위험이 있어 재시도를 중단했다 | 오케스트레이터 게이트나 CI에서 실행 |
| 06-02의 WebKit·Firefox | Chromium 한 번만 돌렸다 | 도우미에 base 옵션을 넣고 3엔진 실행 |
| 06-05의 실제 CDN 동작 | CDN 환경 없음 | staging CDN에서 `service-worker.js` 응답 헤더 확인 |
| 얼어 있는 탭이 Web Lock을 쥔 경우(4.3) | 브라우저 정책 의존, 재현 환경 없음 | 두 탭 중 하나를 `Page.setWebLifecycleState(frozen)`으로 얼린 채 enable 중 revoke |
| 여러 창 활성화(앱이 아닌 창, 06-07 잔여) | 실제 브라우저 두 창 시나리오를 돌리지 않았다 | e2e 도우미로 두 번째 page를 `/config.json`에 두고 `requestActivation()` |
| Web Push end-to-end(실제 푸시 서비스, VAPID, 클릭) | 푸시 서버 없음. WEB_PUSH는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 |
| memento의 lifecycle 변경이 "같은 릴리스" 성질을 지키는지 | 소비자 코드는 리뷰 범위 밖 | 제품 리뷰에서 확인 |
| Firefox의 SW 제어(update·recovery spec) | Playwright Firefox 제약으로 격리됨(`quarantine … expires=2027-03-31`) | 수동 확인 또는 Playwright 업데이트 뒤 재실행 |
@@ -0,0 +1,393 @@
# 07 contracts (공유 어휘·외부 계약) — 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` (코드 변경 없음, 리뷰 가이드 문서 2개만 미커밋) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 영역 판정(35.8): **조건부 사용 가능** — 외부 입력 검증(런타임 설정·릴리스 매니페스트·exact decode)과 런타임 설정 스키마 기준선(FE-GATE-014)은 그대로 써도 된다. 레지스트리 호환성 게이트(`check:registries`)의 증거 절차는 믿고 복제하면 안 된다. 한 번 남긴 증거가 뒤의 다른 변경까지 통과시키고(07-01), 추가 성격의 변경을 breaking으로 막고(07-02), 기능 라우트 하나에도 템플릿 governance 파일 수정을 요구한다(07-03). 두 다운스트림 모두 이 절차에서 비용을 냈다(07-04).
## 1. 머리말
### 1.1 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`, 2026-09-29 |
| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 영역 경로 | `src/contracts/`(41파일, 8.7k줄), `schemas/`(5파일), `config/contracts/`(4파일), `config/compatibility/`, `tests/contract/`, `tests/runtime-schema/`. 이 영역을 실행하는 스크립트 `scripts/check-registries.ts`, `scripts/lib/registry-compatibility.ts`, `scripts/check-compatibility.ts`, `scripts/update-registry-baseline.ts`, `vite.config.ts`의 `VITE_*` 검사 |
| 깊게 본 관점 | 1, 3, 17, 19, 22, 23, 24 (+39.5) |
| 읽은 가이드 절 | 0, 1, 3, 17, 19, 22~24, 29, 30, 32, 34~36, 39, 41 |
| 줄 단위로 읽은 코드 | `compatibility.ts`, `env.ts`, `zod.ts`, `errors.ts`(1~232행), `release-artifacts.ts`(1~215행), `external-contract-runtime.ts`(55~110행), `boundary-mapper.ts`(1~30행), `routes.ts`(1~25행), `scripts/lib/registry-compatibility.ts` 전체, `scripts/check-registries.ts`(1~200, 515~722행), `scripts/check-compatibility.ts`, `scripts/update-registry-baseline.ts`, `config/contracts/registry-governance.json`의 FE-REG-ROUTE·FE-REG-ENV 블록, `registry-change-evidence.json`, `tests/unit/http-operation-v2-v3-parity.test.ts`, `tests/unit/second-api-feature-registries.test.ts`(1~40행), `tests/fixtures/registry/compatibility/semantic-diff.json`. 흐름 추적용: `src/bootstrap/load-runtime-config.ts:94-175`, `src/bootstrap/runtime-config-schema.ts:1-100`, `scripts/check-architecture.ts:330-520, 918-940`, `vite.config.ts:1-60`, `docs/contracts/compatibility.md`, `docs/operations/ci-quality-gates.md:60-70`, `docs/architecture/starter-experience.md:120-150` |
| 다운스트림 증거 | `../tech-log-frontend` 브랜치 `chore/template-sync-v0.2.0`(`42d1ae1f`)을 `git archive`로 scratchpad에 풀어 실행했다. `../memento-frontend` 브랜치 `chore/template-sync-v0.2.0`(`d3810a0`)는 `git diff af3d8e6 <branch>`와 동기화 기록만 읽었다. 두 repo의 브랜치·워킹트리는 바꾸지 않았다 |
| 이전 리뷰와 비교 | `docs/reviews/2026-09-25-maturity-review/07-contracts.md`의 07-01~07-07과 FOLLOW-UP의 07-03·07-07을 현재 코드에서 다시 확인했다(6절). 이전 실행 결과는 증거로 쓰지 않았다 |
### 1.2 실행한 명령과 실험
템플릿 실험은 모두 격리 worktree(`<scratchpad>/review-2026-09-29/07/wt`, `af3d8e6`, 메인 `node_modules` 심볼릭 링크)에서 했다. 끝난 뒤 worktree를 지웠다.
| ID | 무엇 | 결과 |
|---|---|---|
| R1 | `node scripts/check-registries.ts` (변경 없음) | `11 registries PASS; compatibility=breaking`. 현재 diff는 3건: breaking 2건(`FE-REG-ENV:VITE_BUILD_ID:defaultValue:field-type-changed`, `FE-REG-ROUTE:REFERENCE_RESOURCE_DETAIL:path:field-changed`, 둘 다 증거 있음), additive 1건. 증거 파일 15건 중 **13건은 현재 diff의 어떤 변경과도 맞지 않는다** |
| R2 | tech-log 브랜치를 풀어 `check-registries.ts` 실행 | 구조 오류 5건(TechLog 스키마 id 미등록, `has unknown value` 3건 포함) + `breaking change missing evidence` 6건: `TECH_LOG_RELEASES`의 `navigationLabel`·`navigationOrder` `field-type-changed`, `TECH_LOG_STUDIO_{DOCUMENTS,PUBLICATIONS}`의 `searchSchema` `field-type-changed`와 `searchCodec` `field-changed` |
| X1 | `EXAMPLES_AUTH.navigationLabel` "인증 연동" → "인증 예시" | PASS. `behavior-change` |
| X2 | `EXAMPLES_AUTH.navigationLabel`·`navigationOrder` → `null` (메뉴에서 숨김) | **FAIL.** `navigationLabel:field-type-changed`, `navigationOrder:field-type-changed` 2건이 breaking 증거 누락 |
| X3 | `REFERENCE_RESOURCE_DETAIL.path` → `/examples/reference-resources/entries/:resourceId` (08-13 증거가 설명하는 `/items/`와 다른 값) | **PASS.** 같은 `changeId`의 기존 증거가 새 변경을 덮었다 |
| X4 | governance FE-REG-ROUTE `allowedValues.loadingSurface`에 값 1개 추가 | **FAIL.** `FE-REG-ROUTE:$contract:allowedValues:contract-field-changed` breaking 증거 누락 |
| X5 | 참조 기능의 `REFERENCE_RESOURCE_STATUS.loadingSurface`를 기능 전용 새 값으로 | **FAIL.** `has unknown value reference-resource-archive` |
| Z1 | `src/presentation/routes/platform-route-codecs.ts`의 `z` import를 `"zod/v4"`로 바꾸고 `corepack pnpm check:architecture` | **PASS.** 같은 곳을 `"zod"`로 바꾸면 `zod-is-reached-through-contracts-zod` 위반으로 실패 |
| Z2 | `corepack pnpm build` 뒤 `tests/e2e/production-csp.spec.ts`를 chromium 1개 프로젝트, 별도 포트(4297) 설정으로 실행. (가) 변경 없음, (나) Z1 변이, (다) `src/bootstrap/initialize-color-scheme.ts` 맨 위에 `zod/v4` object schema와 모듈 수준 `safeParse` 추가 | 세 경우 모두 통과(CSP 위반 0). `dist`를 보면 `a({jitless:!0})`가 zod 코드 바로 뒤, 같은 청크(`reference-feature-runtime-descriptor-*.js`)에 있다 |
| V1 | `VITE_FEATURE_FLAG_URL=… corepack pnpm build` | 빌드 실패: `Undeclared VITE_* build variables: VITE_FEATURE_FLAG_URL. Declare them in ENV_REGISTRY (src/contracts/env.ts) or unset them` |
| V2 | `ENV_REGISTRY`의 runtime 행과 `z.toJSONSchema(runtimeConfigV2ArtifactSchema, {io:"input"})` 비교 스크립트 | 불일치 5곳, 스키마에만 있는 키 2개(07-05) |
| M1 | 변이: `createFailure`의 "효과가 있었을 수 있으면 `retryable=false`" 규칙 제거(`errors.ts:166-169`) | killed (`error-classification.test.ts` 1건 실패). 지난 라운드 M1 survived → 해소 |
| M4 | 변이: `isValidReleaseManifestUrl`의 origin·pathname 재확인 제거(`release-artifacts.ts:44`) | killed (4건 실패) |
| M6 | 변이: exact decode의 non-enumerable 거부 제거(`exact-snapshot.ts:104`) | killed (2건 실패) |
| G1 | `git show --stat 17d617a`, `git log -- scripts/lib/registry-compatibility.ts` | 07-02·13-10 커밋은 `scripts/check-compatibility.ts`·`config/compatibility/`만 바꿨다. 레지스트리 분류기 파일은 최초 커밋 이후 바뀐 적 없다(07-07) |
| D1 | 두 제품의 템플릿 대비 diff | tech-log: 런타임 설정 키 2개를 `env.ts`·`release-artifacts.ts`·`runtime-config-schema.ts` 세 파일에 손으로 적었다. memento: `registry-change-evidence.json`에 10건 추가, 그중 7건이 같은 문장("never deployed")의 `FE-REG-STORAGE:*:physicalKey` |
오케스트레이터가 이미 돌린 게이트(`test:contract` 15/15, `test:runtime-schema` 56/56, `check:architecture` PASS 등)는 다시 돌리지 않았다. 변이 실험에서 필요한 테스트 파일만 돌렸다.
R1·R2·X1~X5·V2·M1·M4·M6은 `node scripts/…`와 `node scripts/run-vitest.ts`로 직접 돌렸다. Z1·Z2·V1은 worktree에서 `corepack pnpm run`/`exec`로 돌렸다(`pnpm_config_verify_deps_before_run=false`로 설치 검사를 끔). 실험 뒤 메인 `node_modules`의 직접 의존성 35개가 모두 해석되는 것을 확인했다.
### 1.3 오케스트레이터 검증 후보의 결과
- **"tech-log는 0.2.0 분류기 때문에 라우트 변경 6건이 막혀 있다."** 부분만 맞다. 0.2.0에서 바뀐 분류기는 런타임 설정 스키마용 `classifyObjectSchemaChange`다(G1). 레지스트리 분류기 `diffRegistrySnapshots`는 바뀌지 않았다. tech-log 기록도 동기화 전 `8210d48`에서 같은 출력이 났다고 적는다. 6건 중 4건(`searchSchema`, `searchCodec`)은 governance가 스스로 breaking 필드로 선언한 변경이다. 나머지 2건(`navigationLabel`, `navigationOrder`)은 분류기의 과잉 판정이다(07-02). 증거 절차의 이해 가능성은 07-04에 적었다.
- **`src/contracts/zod.ts` 강제.** 규칙은 정확히 `"zod"`라는 이름만 막는다. `"zod/v4"`는 통과한다(Z1). 다만 현재 번들에서는 CSP 위반이 재현되지 않았다(Z2). 07-06.
- **`ENV_REGISTRY`.** `VITE_*` 추가 경로는 분명하다. 선언하지 않으면 빌드가 이유와 고칠 파일을 말하며 멈춘다(V1, `tests/unit/build-environment-bundle.test.ts:83`이 고정). 런타임 설정 키는 다르다. 같은 사실이 세 파일에 있고 이미 어긋나 있다(07-05).
- **39.5 (같은 사실의 반복).** 5.1절 표에 사본마다 불일치 검출이 있는지 정리했다.
### 1.4 확인하지 못한 범위
- `browser-rpc.ts`, `realtime-streams.ts`, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `web-push.ts`, `cache-invalidation.ts`, `query-invalidation.ts`는 이번에 줄 단위로 읽지 않았다. 지난 라운드 결과를 증거로 쓰지 않고 판정표에서 해당 부분을 `?` 또는 범위 밖으로 둔다.
- memento에서 `check:registries`를 직접 돌리지 않았다. 동기화 기록(`PASS, compatibility=breaking`)과 diff만 읽었다.
- CSP 검사는 chromium 한 엔진에서만 했다. tech-log처럼 `manualChunks`를 바꾼 제품에서 `zod.ts`가 zod와 같은 청크에 남는지는 빌드하지 않았다.
## 2. 대표 흐름
### 2.1 정상 흐름 — 런타임 설정을 읽어 부팅한다
```text
입력 dist/config.json (배포자가 쓰는 문서)
→ 정책 getBuildConfig()가 설정 URL을 정한다 src/contracts/env.ts:131-147
→ I/O 크기 제한 있는 JSON 읽기 src/bootstrap/load-runtime-config.ts:100-114
→ 정책 비밀처럼 보이는 키 이름 거부 src/contracts/env.ts:85-117, load-runtime-config.ts:118-125
→ 정책 CONFIG_SCHEMA_VERSION으로 파서 하나만 고른다 src/bootstrap/runtime-config-schema.ts:75-98
→ 정책 zod strict 스키마 + 불변식(HTTPS, demo는 local만) src/contracts/release-artifacts.ts:91-149, 169-177
→ 정책 HTML의 buildId와 설정의 BUILD_ID 일치 load-runtime-config.ts:152-167
→ 상태 검증된 스냅샷을 freeze해서 반환 load-runtime-config.ts:170-176
실패 BootConfigError(CONFIG_SECRET_NAME_REJECTED / CONFIG_SCHEMA_INVALID / CONFIG_BUILD_MISMATCH).
invalidKeys는 키 이름만, 개수 제한(load-runtime-config.ts:136-142)
결과 부트 오류 화면. 모르는 키·타입 오류는 fail-closed
```
이 흐름은 잘 막혀 있다. 모르는 키는 `.strict()`가 거부한다. 스키마 변경은 FE-GATE-014가 커밋된 기준선과 비교한다(`scripts/check-compatibility.ts:28-51`). 변이 M4가 killed였다.
### 2.2 피해가 큰 흐름 — 공개 계약(라우트 경로)을 깨는 변경이 게이트를 지난다
```text
입력 기능 계약의 route path 변경 (북마크·외부 링크가 의존하는 URL)
→ 조립 생성기 → ROUTE_REGISTRY scripts/generate-product-feature-index.ts
→ 투영 레지스트리 스냅샷 scripts/check-registries.ts:489-519
→ 비교 승인된 기준선과 diff (fail-closed) scripts/lib/registry-compatibility.ts:96-279
→ 정책 breaking이면 changeId로 증거 조회, 5개 필드 비었는지만 확인 registry-compatibility.ts:300-336
→ 결과 PASS / FAIL
실패 증거 행은 changeId(registry:row:field:kind)만 가진다. 값(before/after)을 모른다.
기준선을 다시 찍지 않는 한, 같은 row·field의 두 번째 다른 변경도 기존 증거로 통과한다(X3)
결과 예전 URL이 404가 되는데 새 이행 계획·롤백 계획 없이 머지된다
```
### 2.3 변경 흐름 — 다운스트림이 기능 라우트와 설정 키를 추가한다
```text
[라우트] 기능 계약에 route + routeRuntime + 스키마 등록 (기능 디렉터리 안)
→ check:registries: 새 search schema id·loading surface 이름이 governance allowedValues에 없음
→ "has unknown value" (X5, tech-log R2)
→ 템플릿 소유 config/contracts/registry-governance.json:42-60을 고친다
→ check:registries: $contract:allowedValues 변경 = breaking (X4)
→ 증거 5필드를 쓰거나(memento) 기준선을 재승인하거나(update:registry-baseline) 그대로 둔다(tech-log)
→ 다음 동기화에서 governance·baseline·evidence JSON을 손으로 3-way merge (tech-log 기록)
[VITE_*] .env에 VITE_X → 빌드 실패, 메시지가 env.ts를 가리킴(V1) → ENV_REGISTRY에 행 추가(additive, 증거 불필요) → 끝
[런타임 설정 키] ENV_REGISTRY 행 + release-artifacts.ts의 zod 필드 + runtime-config-schema.ts의 타입과 정규화
+ FE-GATE-014 기준선 갱신. 템플릿 소유 파일 3개(tech-log D1). ENV_REGISTRY 행은 아무도 대조하지 않는다(07-05)
```
기능 디렉터리만 고치면 된다는 문서의 약속(`docs/architecture/starter-experience.md:145-147`)은 API만 가진 기능에서만 맞다. 그 약속을 고정하는 테스트도 `routes: {}`인 기능만 쓴다(`tests/unit/second-api-feature-registries.test.ts:11-15, 38`).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 통제 (목표 / 확인) | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | O | M4 / M4 | E2 (M1·M4·M6 killed) | 외부 JSON은 strict 파서나 exact decode를 거친다(2.1). 효과를 모르는 쓰기는 `retryable=false`가 되고 `createFailure`·`withFailureEffect` 양쪽을 테스트가 고정한다(`errors.ts:156-221`, M1). `invokeValidator`는 결과 읽기까지 try 안에 있다(`external-contract-runtime.ts:72-101`) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E2 (오케스트레이터 `check:architecture` PASS) | contracts → application·presentation·bootstrap·adapters 금지 규칙이 있다(`.dependency-cruiser.json` `contracts-do-not-know-*`) |
| **3** | 변경 용이성 | P | M3 / M1 | E2 (X4, X5, R2, D1) | `VITE_*` 추가는 1파일, 오류 종류 추가는 문구 누락까지 테스트가 잡는다(`tests/unit/i18n-contract.test.ts:42`). 기능 라우트 추가는 템플릿 governance 수정 + breaking 증거가 필요하다(07-03, 07-02). 런타임 설정 키는 템플릿 파일 3개를 고친다(07-05, 확장 지점은 09-02) |
| 4 | 인지 부하 | P | M1 / M1 | E1 | 레지스트리 변경 하나에 changeId 문법, 증거 5필드, "증거 vs 재승인" 선택, governance의 allowedValues·references·breakingFields를 알아야 한다(07-04) |
| 5 | 위험 가시성 | P | M2 / M2 | E2 (R1) | 상한·효과 확실성은 타입과 상수로 드러난다. 그러나 템플릿의 정상 상태 출력이 `PASS; compatibility=breaking`이다. 어느 breaking이 어떤 증거로 덮였는지, 그 증거가 지금 변경을 설명하는지 출력에 없다(07-01) |
| 6 | 실패 성숙도 | O | M3 / M3 | E1·E2 | 설정·매니페스트는 fail-closed로 부트 오류 화면에 간다(2.1). 오류 코드는 `ERROR_REGISTRY`로 닫혀 있다 |
| 7 | 운영 성숙도 | > | - | - | 영역 03·13 |
| 8 | 디버깅 가능성 | P | M2 / M2 | E2 (V1, R2) | `VITE_*` 누락 메시지는 고칠 파일을 말한다. `breaking change missing evidence: <changeId>`는 어느 파일에 무엇을 써야 하는지, 재승인이 대안인지 말하지 않는다(07-04) |
| 9 | 유지보수 성숙도 | P | M2 / M1 | E1 (R1) | 증거 15건 중 13건이 현재 변경과 무관한 이력이다(07-01). 폐기 별칭은 표시만 있고 새 import를 막는 lint가 없다(FOLLOW-UP 07-07). `docs/contracts/compatibility.md`의 줄 번호(`release-artifacts.ts:163-171` 등)가 실제(169-177)와 어긋난다 |
| 10 | 테스트 성숙도 | P | M3 / M3 | E2 (M1·M4·M6 killed, X1~X5) | 입력 경계 변이는 모두 잡힌다. 레지스트리 분류기 fixture에 "확장(widening)", "nullable 전환", "다른 값에 같은 증거" 사례가 없다(`tests/fixtures/registry/compatibility/semantic-diff.json`: 7개 사례 모두 좁히기·순서·추가·삭제). V2/V3 일치 테스트는 V2 행이 없어도 통과한다(FOLLOW-UP 07-03) |
| 11 | 데이터 성숙도 | > | - | - | 저장 키 계약의 실행은 영역 05. 이 영역에서는 키 버전·`migration: "discard"`만 확인 |
| 12 | 동시성 성숙도 | - | - | - | contracts는 순수 선언과 파서다 |
| 13 | 확장성 | P | M2 / M1 | E2 (X5, R2) | 기능이 늘수록 governance의 중앙 allowlist와 증거 파일이 함께 커진다(07-03, 07-01). 규모 실측은 영역 11 |
| 14 | 성능 성숙도 | - | - | - | 상한이 정해진 계산만 한다 |
| 15 | 보안 성숙도 | P | M4 / M3 | E2 (V1, Z1) · E3 (Z2) | 선언하지 않은 `VITE_*`는 빌드를 멈춘다. 비밀처럼 보이는 설정 키는 부팅이 거부한다. zod facade 규칙은 subpath import를 놓친다. 지금 번들에서는 CSP 위반이 재현되지 않았다(07-06) |
| 16 | 의존성 성숙도 | > | - | - | 영역 13 |
| **17** | API / Contract 성숙도 | P | M3 / M3(과잉·누락 검출 둘 다) | E2 (R1, X1~X4) · E3 (R2, D1 다운스트림) | 런타임 설정은 이전 reader 기준선과 비교한다(FE-GATE-014, 경계별 표 `docs/contracts/compatibility.md:14-32`). 레지스트리 게이트는 breaking을 증거 없이 통과시키는 경로가 있고(07-01), 추가 성격 변경을 breaking으로 막는다(07-02). 다운스트림 절차가 문서화돼 있지 않다(07-04). HTTP 응답 DTO 형태의 호환성은 외부 계약 패키지 책임으로 두고 이 게이트 밖이다 |
| 18 | 배포 성숙도 | > | - | - | 영역 13. FE-GATE-014 기준선 갱신은 "reader 먼저 배포" 절차를 문서에 둔다(`docs/contracts/compatibility.md:58-64`) |
| **19** | 설정 성숙도 | P | M3 / M2 | E2 (V1, V2) | build 변수: 선언 목록·기본값 일치 테스트·명확한 오류(`vite.config.ts:13-24`, `tests/unit/deployment-admission.test.ts:211-224`). 런타임 설정 키: `ENV_REGISTRY`가 zod 스키마와 다른 기본값·필수 여부를 적고 있고 대조하는 곳이 없다(07-05) |
| 20 | 개발자 경험 | P | M2 / M1 | E3 (D1, R2) | memento는 "배포한 적 없음" 증거 7건을 복사해 썼다. tech-log는 두 번의 동기화 동안 게이트를 빨간 채로 뒀다(07-04). 기능 추가 문서가 governance 수정을 부정한다(07-03) |
| 21 | Guardrail 성숙도 | P | M3 / M3(부분) | E2 (X2~X5, Z1) | 레지스트리 게이트의 누락 검출(07-01)과 과잉 검출(07-02), zod 규칙의 subpath 누락(07-06), V2/V3 일치 테스트의 빈 집합 통과(FOLLOW-UP) |
| **22** | 추상화 성숙도 | P | M2 / M2 | E2 (X4, X5) | 선언형 governance(`requiredFields`·`fieldTypes`·`references`·`breakingFields`)는 레지스트리 11개를 한 검사기로 다룬다. 유지할 가치가 있다(4.1). 그러나 `allowedValues`의 스키마 id 목록은 `references` 검사와 같은 사실의 세 번째 사본이다. `loadingSurface` 목록은 `data-surface` 속성(`app-router.tsx:78`) 말고 읽는 곳이 없는데 닫혀 있다(07-03). `consumers`는 파일에 문자열이 있는지만 본다(`check-registries.ts:554-567`, 예: FE-REG-ENV의 `APP_ENV`는 타입 필드 이름으로 충족) |
| **23** | 일관성 | P | M2 / M1 | E2 (X1·X2) | 같은 필드의 변경이 값에 따라 등급이 갈린다: 라벨 바꾸기는 behavior-change, 라벨 숨기기는 breaking(07-02). 기준선 4종의 갱신 절차가 다르다: CI 계약·레지스트리·의존성은 `*_OWNER`·`*_REASON`을 요구하고, 런타임 설정 스키마 기준선은 `--update-baseline`만 받는다(`scripts/check-compatibility.ts:29-33`). `MappingResult` 두 모양은 D-15 결정으로 유지(문서화됨) |
| **24** | 네이밍 / 의미 성숙도 | P | M2 / M1 | E1 (G1) | `field-type-changed`가 선언된 `string|null` 안의 null 전환까지 부른다(07-02). CHANGELOG 0.2.0의 "레지스트리 호환성 분류기" 행이 다른 분류기를 가리킨다(07-07). `ENV_REGISTRY`는 환경 변수가 아닌 런타임 설정 문서 키까지 담는다(07-05) |
| 25 | 조직 확장성 | P | M2 / M1 | E3 (D1) | 기능 팀마다 같은 governance JSON의 allowlist와 같은 evidence JSON을 고친다. memento는 evidence를 "양쪽 합집합"으로 병합했다(동기화 기록 236행) |
| 26 | Ownership 성숙도 | P | M2 / M1 | E1 | 증거·승인에는 owner가 있다. 오래된 증거를 정리할 책임과 절차가 없다(07-01). 폐기 별칭은 "다음 minor에 제거, owner frontend-platform"(`errors.ts:139-141`) |
| 27 | 삭제 가능성 | > | - | - | 영역 14. 행 삭제는 행마다 breaking 증거가 필요하다는 점만 기록(tech-log는 참조 기능 제거에 13건) |
| 28 | 회복 가능성 | - | - | - | contracts는 복구 절차를 소유하지 않는다 |
X(미충족)인 관점은 없다.
## 4. 설계 선택 설명 (41절)
### 4.1 레지스트리 호환성 게이트: 승인된 기준선 + fail-closed diff + changeId별 증거
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 라우트·API·스키마·설정·저장 키·오류·텔레메트리 등 레지스트리 11개의 공개 계약 변경을 리뷰 단계에서 식별한다. 깨지는 변경이면 이행 정보(버전, 이행, 호환 기간, 롤백, 담당)를 남긴다 |
| 2. 지킬 성질 | (a) breaking 변경은 그 변경을 설명하는 증거 없이 통과하지 않는다. (b) 모르는 변경은 breaking으로 본다. (c) breaking이 아닌 변경은 증거 없이 통과한다 |
| 3. 현재 보장 | 확인한 사실: 승인 파일의 digest·owner로 기준선을 고정한다(`registry-compatibility.ts:281-298`). 순서 차이는 변경으로 세지 않는다(`:35-56`). 분류 규칙이 없는 변경은 breaking이다. 증거는 changeId마다 5필드가 비어 있지 않은지만 본다(`:300-336`). **보장하지 않는 것:** 증거와 값의 연결(07-01, X3), 선언된 nullable 타입과 allowlist 확장의 인식(07-02, X2·X4), 재승인할 때의 증거 요구(07-04) |
| 4. 현실적인 대안 | (A) 현 상태. (B) 현 구조에 세 가지를 더한다: 증거 행에 `after` 값을 적고 비교, 현재 diff와 맞지 않는 증거 행은 실패, nullable 전환·allowlist 확장은 선언을 보고 분류. (C) 증거 파일을 없애고 재승인(owner·reason)만 둔다. (D) 게이트를 없애고 PR 리뷰에 맡긴다 |
| 5. 대안의 비용 | (A) 비용 0. 누락·과잉 둘 다 남는다. (B) 스크립트 수십 줄과 fixture 몇 개. 증거 행에 값이 들어가 파일이 조금 길어진다. (C) 가장 단순하다. 그러나 이행·롤백 기록이 "reason" 한 줄로 줄고, 무엇이 breaking인지 리뷰어가 diff에서 직접 찾아야 한다. (D) 데이터 피해는 없지만 공개 URL·API 경로 변경이 조용히 들어간다 |
| 6. 현재 조건에서의 선택 | fail-closed 기준선 비교는 유지할 근거가 있다: 기록된 의도(`registry-compatibility.ts:92-95` 주석, `docs/operations/ci-quality-gates.md:67`)와 현재 동작이 맞고, 레지스트리가 11개라 손으로 하는 리뷰보다 싸다. 부족한 것은 증거의 연결과 분류의 정확도다. 확인한 조건에서는 (B)가 가장 작은 보강이다. "증거를 changeId만으로 묶은 이유"는 기록이 없다(미확인) |
| 7. 재검토 조건 | 레지스트리 스냅샷을 외부 소비자(백엔드, 다른 앱)가 읽게 되면 breaking 정의를 그 소비자 기준으로 다시 정한다. 다운스트림이 증거 대신 재승인만 쓰는 것이 계속 관찰되면 (C)로 줄이는 것을 다시 비교한다 |
### 4.2 zod를 `src/contracts/zod.ts` 한 곳으로만 가져오게 하는 규칙
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 운영 CSP(`unsafe-eval` 없음) 아래에서 zod의 `new Function("")` 시험이 `securitypolicyviolation`을 만들지 않게 한다 |
| 2. 지킬 성질 | 어떤 object schema도 `jitless` 설정 전에 만들어지지 않는다 |
| 3. 현재 보장 | 확인한 사실: `zod.ts:12`가 `z.config({ jitless: true })`를 부른다. zod 4.4.3은 jitless면 시험을 건너뛴다(`node_modules/zod/v4/core/util.js:145-150`). 규칙은 외부 모듈 이름을 import 문자열 그대로 비교한다(`scripts/check-architecture.ts:360-365`, 규칙 `^zod$` `.dependency-cruiser.json:59-70`). 실제 브라우저 검사가 있다(`tests/e2e/production-csp.spec.ts`). **보장하지 않는 것:** `"zod/v4"` 같은 subpath(Z1). 현재 번들은 `zod.ts` 본문을 zod 코드 바로 뒤, 같은 청크에 둔다(Z2). 그래서 규칙이 뚫려도 지금은 위반이 나지 않는다. 이 배치는 번들러의 선택이지 계약이 아니다 |
| 4. 현실적인 대안 | (A) 현 상태. (B) 규칙을 `^zod(/|$)`로 넓힌다. (C) 엔트리(`main.tsx`)에서 `globalThis.__zod_globalConfig`를 미리 만든다. (D) CSP에 `unsafe-eval` 허용. (E) `zod/mini`로 전환(JIT가 없어 시험 자체가 없다) |
| 5. 대안의 비용 | (B) 정규식 한 줄 + fixture 1개. (C) import 순서에 기대지 않지만 zod 내부 전역 이름에 의존한다. (D) 보안 약화라 제외. (E) API가 달라 모든 스키마 코드를 바꾼다 |
| 6. 선택 | 기록된 의도(`zod.ts:3-11` "the dependency, not import order … puts this first")와 맞는 것은 현 구조다. (B)로 빈틈만 막는다 |
| 7. 재검토 조건 | zod가 jitless를 기본으로 하거나 시험을 없애면 facade와 규칙을 지운다. 다운스트림이 `manualChunks`로 zod를 다른 청크에 떼면 e2e가 유일한 실측이다 |
### 4.3 `ENV_REGISTRY`를 zod 런타임 설정 스키마와 따로 손으로 둔다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | (a) 번들에 들어갈 수 있는 `VITE_*` 이름을 닫힌 목록으로 둔다(13-06). (b) 설정 키의 공개 범위(`public`, `public-sensitive`)와 필수 여부를 적는다 |
| 2. 지킬 성질 | 선언하지 않은 `VITE_*`는 빌드가 멈춘다. 레지스트리의 기본값·필수 여부는 실제 적용되는 값과 같다 |
| 3. 현재 보장 | build 행: `vite.config.ts:13-24`가 키 목록을 쓰고, `deployment-admission.test.ts:211-224`가 기본값을 `getBuildConfig`와 대조한다. **runtime 행: 읽는 실행 코드가 없다.** `phase`·`classification`·`required`는 governance 검사만 읽는다(grep). zod 스키마(`release-artifacts.ts:137-149`)와 다섯 곳이 다르다(V2) |
| 4. 현실적인 대안 | (A) 현 상태. (B) runtime 행을 zod 스키마와 대조하는 테스트 1개(build 행 테스트와 같은 모양). (C) runtime 행을 zod 스키마에서 생성. (D) runtime 행 삭제 |
| 5. 대안의 비용 | (B) 테스트 1개, 지금 틀린 값 5곳 수정. (C) 생성 코드와 FE-REG-ENV 기준선 재승인. (D) 행 11개 삭제가 각각 breaking 증거를 요구한다(07-01·07-04의 절차 비용이 그대로 나온다) |
| 6. 선택 | build 행은 현 상태 유지가 맞다: 실제 빌드 검사가 쓰고 불일치 검사가 있다. runtime 행은 (B)가 가장 작다 |
| 7. 재검토 조건 | `classification`을 실제로 읽는 코드(예: 텔레메트리 비식별, 설정 진단 출력)가 생기면 (C)로 옮겨 사본을 없앤다 |
## 5. 발견 사항 (36.3)
### 5.1 같은 사실의 사본과 불일치 검출 (39.5)
| 사실 | 사본 | 실제 소비자 | 불일치 검출 |
|---|---|---|---|
| 라우트의 스키마 id | 라우트 행, FE-REG-SCHEMA 행, governance `allowedValues` | 라우터·코덱 | 행 ↔ SCHEMA: `references` 검사. allowedValues: 새 사본이 늘 때마다 손으로 추가(07-03) |
| loading surface 이름 | 라우트 행, governance `allowedValues` | `data-surface` 속성뿐 | 닫힌 목록 자체가 검사. 보호하는 실행 동작 없음(07-03) |
| 런타임 설정 키·기본값·필수 | `ENV_REGISTRY` runtime 행, zod 필드, `RuntimeConfig` 타입과 V1 정규화 | zod와 타입 | zod ↔ 타입: 컴파일러. `ENV_REGISTRY` ↔ zod: **없음**, 이미 불일치(07-05) |
| build 변수 기본값 | `ENV_REGISTRY` build 행, `getBuildConfig` | `getBuildConfig` | 테스트 있음(`deployment-admission.test.ts:211-224`) |
| 런타임 설정 스키마 | zod, `config/compatibility/runtime-config.schema.baseline.json` | 부팅 파서 | 의도된 기준선 비교(FE-GATE-014) |
| 산출물 JSON Schema | zod, `schemas/artifacts/*.json` | CI·릴리스 스크립트 | 생성 + `check:artifact-schemas --check` |
| HTTP operation | V2 행(governance 대상), V3 descriptor(실행) | V3 | 일치 테스트 있음. 빈 V2 집합·V3 전용 operation·스키마 id는 안 본다(FOLLOW-UP 07-03) |
| breaking 변경의 설명 | 증거 행(changeId만) | `check:registries` | changeId 존재만. 값 연결 없음(07-01) |
| 오류 문구 키 | `ERROR_REGISTRY`(kind에서 생성), 카탈로그 ko·en | 화면 | 테스트 있음(`i18n-contract.test.ts:42`) |
### 07-01 breaking 증거가 값과 묶이지 않아, 같은 row·field의 다음 변경을 새 증거 없이 통과시킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (가드레일 누락 검출) |
| 관련 관점 | 17, 21, 10, 5, 9, 26 |
| 근거 | 증거 조회 키는 `registryId:rowName:field:kind`뿐이다(`scripts/lib/registry-compatibility.ts:83-90`, `:305-313`). 값(`before`·`after`)은 diff에 있지만(`:268-269`) 증거와 비교하지 않는다. 증거 검사는 5개 필드가 빈 문자열이 아닌지만 본다(`:317-330`). **실험 X3:** `REFERENCE_RESOURCE_DETAIL.path`를 08-13 증거가 설명하는 `/items/:resourceId`가 아닌 `/entries/:resourceId`로 바꿨다. `check-registries`는 `11 registries PASS`였다. **R1:** 증거 파일 15건 중 13건은 현재 diff의 어떤 changeId와도 맞지 않는다(예: `FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed`, 07-04 이후 그 필드는 없다). 오래된 행을 찾는 검사가 없다 |
| 발생 조건 | breaking 변경을 "재승인 대신 증거로 유지"한 뒤(`docs/operations/ci-quality-gates.md:67`가 안내하는 방식), 같은 row·field를 다시 바꿀 때. 오래된 행은 같은 이름의 row가 다시 생겼다가 바뀌거나 지워질 때 |
| 영향 | 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백 계획 없이 게이트를 통과한다. 증거 문장은 이전 변경을 설명하므로 리뷰어도 오해한다. 템플릿의 현재 기준선이 바로 이 상태다(REFERENCE_RESOURCE_DETAIL) |
| 심각도·우선순위 | Medium · P2 — 코드 변경은 PR 리뷰를 거치므로 게이트가 유일한 방어는 아니다. 그러나 "breaking은 증거가 필요하다"는 게이트의 약속이 조용히 깨지고, 증거 파일은 두 다운스트림에 그대로 복제됐다 |
| 통제·증거 | 목표 M3 / 확인 M3(부분: 첫 변경만) · E2 (X3, R1) |
| 확실성과 남은 가정 | 재현했다. 다운스트림에서 실제로 두 번째 변경이 들어간 사례는 찾지 않았다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 재승인하지 않고 증거로 유지하는 경로를 문서가 안내한다(`ci-quality-gates.md:67`). 값과 묶지 않은 이유는 기록이 없다. 리뷰어 추론: 증거 행이 "이 변경"이 아니라 "이 칸의 모든 변경"을 허가하는 것은 의도와 다르다 |
| 이해 비용 | 리뷰어는 PASS를 보고 증거 파일을 열어 changeId를 찾고, 그 문장이 지금 diff를 설명하는지 직접 비교해야 한다. 출력(`compatibility=breaking`)은 이 비교를 돕지 않는다 |
| 최소 개선 방향 | (1) 증거 행에 `after`(canonical JSON)를 필수로 두고, diff의 `after`와 다르면 "증거가 다른 값을 설명함"으로 실패한다. (2) 현재 diff와 맞지 않는 증거 행이 있으면 실패하거나 목록으로 출력한다. (3) `update:registry-baseline`이 새 기준선으로 설명이 끝난 증거 행을 지운다 |
| 대안 비교 | 4.1절. (C) 증거를 없애고 재승인만 두면 이 결함은 사라지지만 이행·롤백 기록도 사라진다 |
| 단순화의 보존 조건 | 모르는 변경은 계속 breaking이다. 증거 5필드 요구는 유지한다 |
| 비용·부작용 | 스크립트 수십 줄. 기존 증거 2건에 `after` 추가, 오래된 13건 정리(삭제 또는 이력 파일로 이동). 두 다운스트림도 한 번 정리해야 한다 |
| 재검토 조건 | 4.1의 7번 |
| 완료 기준 | X3을 다시 하면 실패한다. 증거 파일에 현재 diff와 무관한 행이 있으면 실패한다 |
| 검증 방법 | `tests/fixtures/registry/compatibility/semantic-diff.json`에 "같은 changeId, 다른 after" 사례와 "오래된 증거" 사례 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-02 레지스트리 분류기가 추가 성격의 변경(nullable 전환, allowlist 확장)을 breaking으로 막고, governance의 `breakingFields` 선언을 건너뛴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (과잉 검출) |
| 관련 관점 | 17, 23, 24, 21, 20, 3 |
| 근거 | 값의 JS 타입이 다르면 `breakingFields`를 보기 전에 breaking이다(`scripts/lib/registry-compatibility.ts:237-239`). `null`과 문자열은 타입이 다르다(`:77-81`). governance는 이 필드들을 `string|null`로 선언하고(`config/contracts/registry-governance.json:38-39`) breaking 필드에서 뺐다(`:84-91`). contract 필드는 어떤 변경이든 breaking이다(`:157-172`). allowlist에 값을 더하는 것도 마찬가지다. **실험:** X1 라벨 이름 변경 → behavior-change, PASS. X2 같은 라벨을 `null`로(메뉴에서 숨김) → breaking 2건. X4 `loadingSurface` 허용값 1개 추가 → breaking. fixture에는 좁히기 사례만 있다(`semantic-diff.json`의 `registry-contract-narrowing`, `field-type-narrowing`). **실제 피해:** 템플릿 스스로 `VITE_BUILD_ID.defaultValue` null → `"local-build"`에 증거를 썼고, 그 증거는 "the value itself did not change"라고 적는다(`config/contracts/registry-change-evidence.json:109-115`). tech-log의 6건 중 2건이 이것이다(R2). memento는 allowlist 확장에 "The new allowed values are additive"라고 적은 breaking 증거를 썼다(D1) |
| 발생 조건 | nullable 필드(`navigationLabel`, `navigationOrder`, `paramsSchema`, `searchSchema`, API `timeoutMs`, 저장 `ttl`, ENV `defaultValue`)를 null ↔ 값으로 바꿀 때. governance의 allowlist에 값을 더할 때(새 기능 라우트마다, 07-03) |
| 영향 | 증거 5필드에 쓸 내용이 없는 변경에 "마이그레이션", "롤백"을 지어서 쓰게 한다. 그러면 증거 문장의 신호가 약해진다. 쓰지 않는 팀은 게이트를 빨간 채로 둔다(tech-log). 둘 다 07-01의 누락보다 더 흔하게 게이트를 무력하게 만든다 |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 흔한 변경마다 비용을 반복해서 만들고, 템플릿·두 다운스트림 모두에서 발생했다 |
| 통제·증거 | 목표 M3 / 확인 M3(과잉) · E2 (X1, X2, X4) · E3 (다운스트림 R2, D1) |
| 확실성과 남은 가정 | 재현했다. `searchSchema` null → 값은 이 수정 뒤에도 breaking이다(`breakingFields`에 있음). 그 선언이 맞는지는 제품 판단이다 |
| 결정의 근거 | 확인한 사실: fail-closed 기본값은 유지할 가치가 있다(4.1). 리뷰어 추론: 선언된 타입 안의 변화와 allowlist 확장은 "모르는 변경"이 아니라 governance가 이미 설명한 변경이다. 이 둘까지 fail-closed로 묶을 근거는 기록에 없다 |
| 이해 비용 | 기능 작성자는 라벨 이름 바꾸기와 숨기기의 등급이 왜 다른지 분류기 코드를 읽어야 안다 |
| 최소 개선 방향 | (1) 한쪽이 `null`이고 다른 쪽이 선언된 `fieldTypes`에 맞으면 `field-changed`로 보고 `breakingFields`로 등급을 정한다. (2) `$contract.allowedValues`가 필드별로 이전 값을 모두 포함하면 additive, 하나라도 빠지면 breaking. 나머지 contract 변경은 지금처럼 breaking. (3) 두 사례를 fixture에 추가한다 |
| 대안 비교 | (A) 현 상태 + "이런 변경은 재승인하라"는 문서: 코드 변경 없음, 대신 재승인이 증거를 대체하는 길을 더 넓힌다(07-04). (B) 위 개선: 분류 두 줄 + fixture. (C) nullable 필드를 모두 `breakingFields`에서 판단하도록 규칙 전체를 바꿈: 범위가 넓고 다른 레지스트리 영향을 다시 봐야 한다 |
| 단순화의 보존 조건 | 타입이 선언과 다른 변경, allowlist 축소, 모르는 contract 키 변경은 계속 breaking |
| 비용·부작용 | 스크립트 몇 줄, fixture 2개. 템플릿의 `VITE_BUILD_ID` 증거 행은 필요 없어진다 |
| 재검토 조건 | nullable 필드의 null이 "기능 꺼짐" 같은 의미를 갖게 되면 그 필드를 `breakingFields`에 넣는다 |
| 완료 기준 | X2·X4가 PASS(behavior-change / additive)다. `field-type-narrowing`, `registry-contract-narrowing` fixture는 계속 breaking이다 |
| 검증 방법 | 위 실험 재실행, `check:registries:compatibility-fixtures` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-03 기능 라우트 하나를 추가해도 템플릿 소유 governance의 중앙 allowlist를 고쳐야 한다 — 문서는 고칠 필요가 없다고 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서 약속과 실제 절차의 불일치) |
| 관련 관점 | 3, 20, 22, 25, 13, 30.3, 39.5 |
| 근거 | FE-REG-ROUTE governance가 `paramsSchema`·`searchSchema`·`loadingSurface`를 참조 기능 값까지 열거한 닫힌 목록으로 둔다(`config/contracts/registry-governance.json:42-60`). 검사기는 목록 밖 값을 `has unknown value`로 거부한다(`scripts/check-registries.ts:483`). 스키마 id는 이미 `references`가 FE-REG-SCHEMA와 대조한다(`registry-governance.json:61-77`). 그래서 allowlist는 같은 사실의 세 번째 사본이다. `loadingSurface`는 실행 코드에서 `data-surface` 속성으로만 쓰인다(`src/presentation/routes/app-router.tsx:78`). 문서는 "the registry governance file do not change"라고 적는다(`docs/architecture/starter-experience.md:145-147`). 이 약속을 고정하는 테스트는 라우트가 없는 기능만 쓴다(`tests/unit/second-api-feature-registries.test.ts:11-15, 38`). **실험 X5:** 참조 기능 라우트의 `loadingSurface`를 기능 전용 새 이름으로 → 실패. **다운스트림:** tech-log `has unknown value` 3건(R2), memento는 allowlist를 고치고 breaking 증거를 썼다(D1) |
| 발생 조건 | 새 기능이 자기 params/search 스키마나 자기 로딩 화면 이름을 가진 라우트를 추가할 때. 화면이 있는 기능은 대부분 해당한다 |
| 영향 | 기능 추가가 템플릿 파일 수정 + breaking 증거(07-02) 또는 재승인을 요구한다. 모든 기능 팀이 같은 JSON 목록을 고치므로 병합 충돌 지점이 된다. 템플릿 동기화 때마다 이 목록을 손으로 합친다 |
| 심각도·우선순위 | Medium · P2 — 기능 실패는 없다. 그러나 템플릿의 핵심 약속(기능 디렉터리만 고친다)을 대표 과제에서 깨고, 두 다운스트림 모두에서 발생했다 |
| 통제·증거 | 목표 M3(기능 로컬 추가를 테스트로 고정) / 확인 M0(라우트 있는 기능은 검증 안 됨, 문서는 반대로 적음) · E2 (X4, X5) · E3 (R2, D1) |
| 확실성과 남은 가정 | 확인했다. `errorSurface` allowlist는 라우터가 의미로 읽으므로(`app-router.tsx:116, 350`) 닫힌 목록이 맞다. 이 발견에서 뺀다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 없음. 참조 기능이 유일한 기능이던 때의 값이 남은 것으로 보인다(추론). 리뷰어 추론: 스키마 id 목록은 `references`로 충분하고, `loadingSurface`는 보호할 실행 동작이 없다 |
| 이해 비용 | 기능 작성자는 실패 메시지를 보고 governance JSON의 구조, allowlist가 contract의 일부라 breaking이라는 사실, 증거·재승인 절차까지 알아야 한다 |
| 최소 개선 방향 | (1) `paramsSchema`·`searchSchema`를 FE-REG-ROUTE `allowedValues`에서 뺀다(`references`가 남는다). (2) `loadingSurface`는 allowlist 대신 이름 형식만 본다(예: `fieldTypes`의 `string` + 정규식), 또는 목록을 없앤다. (3) 두 번째 기능 테스트에 search 스키마와 전용 loading surface를 가진 라우트 1개를 넣어 "governance 무수정"을 고정한다. (4) 문서가 이 테스트를 가리키게 한다 |
| 대안 비교 | (A) 현 상태 + 문서를 "allowlist를 고치고 증거를 쓴다"로 정정: 코드 비용 0, 기능마다 비용 반복. (B) 위 개선: governance 두 줄 삭제 + 테스트 확장. (C) 기능 계약이 자기 allowlist 값을 기여하게 하는 확장 메커니즘: 유연하지만 새 등록 규약이 하나 더 생긴다(39.10) |
| 단순화의 보존 조건 | 라우트가 등록되지 않은 스키마 id를 쓰면 계속 실패한다(`references`). `errorSurface`·`access`는 닫힌 목록을 유지한다 |
| 비용·부작용 | allowlist 축소는 contract 변경이라 템플릿 기준선을 한 번 재승인한다. 두 다운스트림은 다음 동기화에서 자기 allowlist 추가분을 지운다 |
| 재검토 조건 | `loadingSurface`가 로딩 컴포넌트 선택 같은 실행 의미를 갖게 되면 닫힌 목록을 다시 둔다(그때는 기능이 값을 기여하는 방식과 비교) |
| 완료 기준 | 자기 스키마·로딩 화면 이름을 가진 라우트를 기능 디렉터리만 고쳐 추가해도 `check:registries`가 PASS다 |
| 검증 방법 | 확장한 `second-api-feature-registries.test.ts`, X5 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-04 다운스트림이 breaking 증거를 남기는 절차가 안내되지 않고, 템플릿의 기준선·증거가 제품의 이력처럼 복제된다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (다운스트림에서 비용 발생 확인) |
| 관련 관점 | 20, 17, 8, 26, 25, 30.3, 30.4 |
| 근거 | **안내:** 실패 메시지는 `breaking change missing evidence: <changeId>`뿐이다(`scripts/lib/registry-compatibility.ts:314`). 어느 파일, 어떤 5필드, 재승인이라는 대안을 말하지 않는다. 절차는 `docs/operations/ci-quality-gates.md:67` 표의 한 칸에만 있다. 계약 문서(`docs/contracts/compatibility.md`)는 레지스트리 증거를 다루지 않는다. **두 길의 차이:** `update:registry-baseline`은 `REGISTRY_BASELINE_OWNER`·`_REASON`만 요구하고, 그 순간의 breaking 변경에 증거를 요구하지 않는다(`scripts/update-registry-baseline.ts:10-18, 26-43`). 언제 어느 길을 쓰는지 기준이 없다. **첫 도입:** 템플릿의 `registry-baseline.json`·`approval.json`·`registry-change-evidence.json`은 템플릿 자신의 릴리스 이력이다. 제품이 복사한 뒤 처음 하는 이름 변경도 "템플릿 기준선 대비 breaking"이 된다. 기준선을 제품 것으로 다시 찍으라는 안내는 없다(docs grep). **세분도:** 증거는 changeId 하나에 행 하나라, 한 결정이 row 7개를 바꾸면 같은 문장을 7번 쓴다. **다운스트림:** memento는 저장 네임스페이스 변경에 "This repository had never been deployed … no origin holds data" 증거 7건을 복사해 썼다(D1, 동기화 기록 258행). tech-log는 두 번의 동기화 동안 게이트를 빨간 채로 두었고, 이번에는 두 승인 기준선을 row 단위로 3-way merge했다(동기화 기록 290-293행). 그 결과 `test:sample-removal`과 `second-api-feature-registries` 테스트도 같은 원인으로 막혔다(같은 기록 475-476행) |
| 발생 조건 | 템플릿을 복사한 직후 첫 커스터마이즈, 여러 row에 걸친 한 번의 결정, 템플릿 동기화 |
| 영향 | 증거가 의식(ritual)이 된다. "배포한 적 없음"을 롤백·이행 칸에 적는 문서가 쌓인다. 쓰지 않는 팀은 게이트를 끈 것과 같은 상태로 지낸다. 동기화마다 승인된 스냅샷을 손으로 병합한다 |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 두 다운스트림 모두에서 반복 비용과 게이트 무력화가 관찰됐다 |
| 통제·증거 | 목표 M2(절차 문서 + 안내하는 오류) / 확인 M1(표 한 칸) · E1 · E3 (두 다운스트림의 diff와 기록) |
| 확실성과 남은 가정 | 다운스트림 파일과 기록으로 확인했다. 두 팀이 절차를 몰라서인지, 알고도 비용 때문에 미뤘는지는 기록만으로 가를 수 없다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `ci-quality-gates.md:67`의 두 갈래 안내. 리뷰어 추론: 템플릿 저장소의 기준선·증거는 템플릿 제품의 이력이지 다운스트림의 이력이 아니다(30.3 "생성·복사 후 수정 권한") |
| 이해 비용 | 제품 개발자는 changeId 문법, 증거 5필드의 뜻, 재승인과의 차이, 동기화 때 어느 쪽 기준선을 남길지를 코드와 기록에서 찾아야 한다 |
| 최소 개선 방향 | (1) `docs/contracts/compatibility.md`에 "레지스트리 변경" 절: 증거와 재승인을 언제 쓰는지, 첫 도입 때 기준선을 제품 것으로 한 번 재승인하는 단계, 동기화 때 이 세 파일은 제품 소유라는 규칙. (2) 실패 메시지에 파일 경로·5필드·재승인 명령을 한 줄로 붙인다. (3) 증거 행이 `changeIds` 목록을 받게 해 한 결정에 행 하나로 쓴다 |
| 대안 비교 | (A) 현 상태. (B) 위 개선: 문서 1절 + 메시지 + 스크립트 몇 줄. (C) 기준선·증거를 템플릿 파일에서 빼고 첫 실행에 제품이 생성하게 함: 동기화 충돌은 사라지지만 템플릿 자신의 게이트 설정이 더 복잡해진다 |
| 단순화의 보존 조건 | breaking 변경은 계속 증거나 owner·reason이 남는 재승인 없이 통과하지 않는다 |
| 비용·부작용 | 문서 1절, 메시지 1줄, `changeIds` 지원 몇 줄 |
| 재검토 조건 | 07-01·07-02가 고쳐진 뒤에도 다운스트림이 증거 대신 재승인만 쓰면 4.1의 (C)를 다시 비교한다 |
| 완료 기준 | 처음 보는 사람이 실패 메시지와 문서만으로 증거를 쓰거나 재승인할 수 있다. 한 결정은 증거 행 하나로 기록된다 |
| 검증 방법 | 메시지 스냅샷 테스트, `changeIds` fixture. 다음 다운스트림 동기화 기록에서 증거 행 수·재승인 이유 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-05 `ENV_REGISTRY`의 런타임 설정 행이 zod 스키마와 따로 적혀 있고, 이미 기본값·필수 여부가 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (선언과 실행의 불일치, 검출 없음) |
| 관련 관점 | 19, 23, 24, 9, 3, 39.5 |
| 근거 | runtime 행(`src/contracts/env.ts:50-62`)을 읽는 실행 코드는 없다. `phase`·`classification`·`required`는 governance 검사와 기준선만 읽는다(grep: `src`·`scripts`에 소비자 없음). 실제 설정 계약은 zod다(`src/contracts/release-artifacts.ts:137-149, 169-177`). **실험 V2(입력 기준 JSON Schema와 비교):** `TELEMETRY_ENABLED` 레지스트리 기본값 `false` / 스키마는 필수·기본값 없음. `AUTH_MODE` 기본값 `"external"` / 스키마는 필수·기본값 없음. `RELEASE_MANIFEST_URL` 필수 / 스키마는 선택·기본값 있음. `CAPABILITY_OVERRIDES`·`FEATURE_OVERRIDES` 기본값 `null` / 스키마는 객체 기본값. `BUILD_ID`·`RELEASE_ID`는 스키마에만 있다. **다운스트림(D1):** tech-log는 설정 키 2개를 `env.ts`, `release-artifacts.ts`, `runtime-config-schema.ts`(타입·V1 정규화)에 따로 적었다. 기본값 `"MOCK"`이 세 번 나온다 |
| 발생 조건 | 누가 `ENV_REGISTRY`를 설정 키 목록으로 믿을 때(이름이 그렇게 읽힌다). 설정 키를 추가·변경할 때 |
| 영향 | 프로필 파일에서 `AUTH_MODE`를 빼도 된다고 읽으면 빌드가 실패한다(fail-closed라 피해는 작다). FE-REG-ENV 게이트는 실행되지 않는 `required`를 바꿀 때 breaking 증거를 요구하고, 실제 스키마 변경은 따로 FE-GATE-014가 본다. 같은 사실을 두 게이트가 두 사본으로 감시한다 |
| 심각도·우선순위 | Low · P3 — 실제 설정은 zod가 fail-closed로 지킨다. 오해와 이중 관리 비용이 남는다 |
| 통제·증거 | 목표 M3 / 확인 M0(runtime 행 ↔ zod 대조 없음). build 행은 M3(`deployment-admission.test.ts:211-224`) · E2 (V2) |
| 확실성과 남은 가정 | 불일치는 실행으로 확인했다. 제품 설정 키를 넣을 확장 지점 문제는 영역 09의 09-02가 다룬다. 여기서는 사본 불일치만 센다 |
| 결정의 근거 | 4.3절 |
| 이해 비용 | 설정 키 하나에 네 곳을 맞춘다. 그중 하나는 아무도 대조하지 않는다 |
| 최소 개선 방향 | `deployment-admission.test.ts`의 build 기본값 테스트 옆에 runtime 행 테스트 1개: 키 집합, 필수 여부, 기본값을 `z.toJSONSchema(runtimeConfigV2ArtifactSchema, { io: "input" })`와 대조. 지금 틀린 5곳과 빠진 2개 키를 맞춘다 |
| 대안 비교 | 4.3절 (B)~(D). (D) 삭제는 07-01·07-04 때문에 행 11개의 breaking 증거가 필요해 지금은 가장 비싸다 |
| 단순화의 보존 조건 | `VITE_*` 선언 검사와 build 기본값 테스트는 그대로 둔다 |
| 비용·부작용 | 테스트 1개, 레지스트리 값 수정(FE-REG-ENV 기준선 재승인 1회) |
| 재검토 조건 | 4.3의 7번 |
| 완료 기준 | runtime 행과 zod가 다르면 테스트가 실패한다 |
| 검증 방법 | 새 테스트 실행. `AUTH_MODE` 기본값을 다시 `"external"`로 둔 변이로 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-06 zod facade 규칙이 정확히 `"zod"`만 막아서 `"zod/v4"` import가 검사를 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (가드레일 빈틈 확인, 피해는 재현 안 됨) |
| 관련 관점 | 15, 21, 10 |
| 근거 | 규칙 `to.path`가 `^zod$`다(`.dependency-cruiser.json:67-69`). 검사기는 외부 모듈의 대상을 import 문자열 그대로 둔다(`scripts/check-architecture.ts:360-365`). zod 4.4.3은 `./v4`, `./v4/core`, `./mini`, `./v3` 등을 export한다. `zod/v4`는 `zod`와 같은 classic 구현이고 JIT object schema를 만든다(`node_modules/zod/v4/classic/schemas.js:737`). **Z1:** `"zod/v4"` import는 `check:architecture` PASS. 회귀 fixture는 `"zod"`만 시험한다(`check-architecture.ts:924-938`). **Z2:** 현재 번들은 `zod.ts`의 설정 호출을 zod 코드 바로 뒤 같은 청크에 두어, 두 위치의 변이 모두 CSP 위반이 나지 않았다. 같은 모양의 규칙: `icon-vendor-is-facade-only`의 `^lucide-react$`(영역 08·12 판단) |
| 발생 조건 | 다운스트림이 zod v4 문서를 따라 `import { z } from "zod/v4"`를 쓰고, 번들러가 그 모듈을 `zod.ts`보다 먼저 평가하는 청크 배치를 만들 때(예: `manualChunks` 변경) |
| 영향 | 운영에서 부팅마다 CSP 위반 보고가 난다(13-08이 고친 증상). 기능 동작은 같다(zod가 거부를 잡는다) |
| 심각도·우선순위 | Low · P3 — 현재 번들에서 재현되지 않았고, e2e가 실제 위반을 잡는다 |
| 통제·증거 | 목표 M3 / 확인 M3(부분: 정확한 이름만) · E2 (Z1) · E3 (Z2, chromium만) |
| 확실성과 남은 가정 | 규칙 빈틈은 확인했다. 위반이 나는 청크 배치는 만들지 못했다 |
| 결정의 근거 | 4.2절. 적용 제외 — 선택은 유지하고 정규식만 고친다 |
| 이해 비용 | 적음 |
| 최소 개선 방향 | `to.path`를 `^zod(/|$)`로 바꾸고, `"zod/v4"`를 import하는 fixture 1개를 `check-architecture.ts` 회귀 목록에 추가 |
| 대안 비교 | 적용 제외 — 기대 계약(모든 zod 접근은 facade 경유)이 이미 정해져 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 정규식 1줄, fixture 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | Z1이 `zod-is-reached-through-contracts-zod` 위반으로 실패한다 |
| 검증 방법 | Z1 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 07-07 CHANGELOG 0.2.0의 [계약] 행이 바뀌지 않은 레지스트리 분류기와 경로를 가리킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서) |
| 관련 관점 | 24, 9, 17, 30.4 |
| 근거 | `CHANGELOG.md:45`는 "레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다"고 적고 영향 경로를 `src/contracts/compatibility.ts`, `scripts/check-registries.ts`, `config/contracts/`로 든다. 커밋 `17d617a`가 바꾼 것은 `classifyObjectSchemaChange`(런타임 설정 스키마)와 `scripts/check-compatibility.ts`, `config/compatibility/`다(G1). 레지스트리 분류기 `scripts/lib/registry-compatibility.ts`는 최초 커밋 이후 바뀐 적이 없다 |
| 발생 조건 | 다운스트림이 CHANGELOG로 동기화 영향을 판단할 때(CHANGELOG 3행이 그 용도라고 적는다) |
| 영향 | 제품 팀과 리뷰어가 레지스트리 게이트의 기존 실패를 이 변경 탓으로 돌린다. 실제로 이번 라운드 검증 후보도 그렇게 적혔다. 반대로 FE-GATE-014 기준선(`config/compatibility/runtime-config.schema.baseline.json`)을 갱신해야 한다는 사실은 이 행에서 찾기 어렵다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 (G1) |
| 확실성과 남은 가정 | 확인했다 |
| 결정의 근거 | 적용 제외 — 선택 비교가 필요 없는 문서 오류다 |
| 이해 비용 | 적음 |
| 최소 개선 방향 | 행을 "런타임 설정 스키마 분류기가 … FE-GATE-014가 커밋된 기준선과 비교한다"로 고치고 경로를 `scripts/check-compatibility.ts`, `config/compatibility/`로 바꾼다. "레지스트리 분류기는 바뀌지 않았다"를 한 줄 덧붙인다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 1행 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 행의 경로가 `git show --stat 17d617a`와 맞다 |
| 검증 방법 | G1 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| 항목 | 결과 | 근거 |
|---|---|---|
| P2 07-03 — V2 행이 없어도 V2/V3 일치 테스트가 통과하고, V3에만 있는 operation을 보지 않는다 | **유효** | `tests/unit/http-operation-v2-v3-parity.test.ts:26-54`는 V2 행에서 V3를 찾는 한 방향 루프다. V2 행 수가 0이어도 단언이 없다. 추가로, FE-REG-API의 breaking 필드인 `requestSchema`·`responseSchema`(`registry-governance.json:199` 블록)는 비교 목록에 없다. V3 validator의 스키마 id를 바꿔도 이 테스트와 governance 모두 모른다(코드 읽기, E1) |
| P3 07-07 — `no-deprecated` lint를 켜지 않았다 | **유효** | `eslint.config.ts`에 `deprecated` 규칙 없음(grep). 폐기 별칭 사용처: `ApiFailure` 8파일, `MappingResult`(boundary-mapper) 6파일. 주석의 제거 조건은 "다음 minor"(`errors.ts:139-141`, `boundary-mapper.ts:20-22`) |
지난 라운드에 닫힌 이 영역 발견의 회귀 확인:
| ID | 결과 | 근거 |
|---|---|---|
| 07-01 오류 문구 누락 | 회귀 없음 | `tests/unit/i18n-contract.test.ts:42`가 `ERROR_REGISTRY` 전체를 두 카탈로그와 대조 |
| 07-02 분류기 "none" | 회귀 없음 (런타임 설정 분류기 기준) | `compatibility.ts:110-144` fail-closed. 레지스트리 분류기의 과잉 판정은 이번 07-02로 따로 적었다 |
| 07-04 읽지 않는 오류 레지스트리 필드 | 회귀 없음 | 필드 4개만 남음(`errors.ts:22-27`). M1 killed |
| 07-05 diagnostics fixture | 회귀 없음 | 위반마다 `@ts-expect-error`(`tests/fixtures/typecheck/invalid-diagnostics-port.ts:10, 16, 19`) |
| 07-06 `invokeValidator` | 회귀 없음 | 결과 읽기가 try 안(`external-contract-runtime.ts:76-101`) |
## 7. 미검증 목록
| 무엇 | 왜 못 했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| `zod/v4` 우회가 실제 CSP 위반으로 이어지는 청크 배치 | 두 위치의 변이 모두 같은 청크 배치라 재현되지 않았다. 제품 빌드(tech-log `manualChunks`)는 하지 않았다 | tech-log 브랜치를 풀어 `zod/v4` 변이로 빌드하고 CSP spec 실행 |
| firefox·webkit에서의 CSP spec | chromium만 돌렸다(동시 실행 중인 다른 영역과 포트·부하 충돌 회피) | 세 엔진 프로젝트로 Z2 재실행 |
| 07-01의 두 번째 변경이 다운스트림에서 실제로 들어간 사례 | 두 제품의 git 이력을 changeId별로 추적하지 않았다 | 두 제품에서 증거 행별로 `git log -S '<changeId>'`와 해당 row 값 이력 대조 |
| 07-04의 원인(절차를 몰랐는지, 비용 때문에 미뤘는지) | 동기화 기록만으로는 가를 수 없다 | 제품 담당자 확인 |
| memento의 `check:registries` 현재 출력 | 직접 실행하지 않고 기록(`PASS, compatibility=breaking`)을 읽었다 | memento 브랜치를 풀어 실행 |
| 줄 단위로 읽지 않은 contracts 파일(`browser-rpc.ts`, `realtime-streams.ts`, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `web-push.ts`, `cache-invalidation.ts`, `query-invalidation.ts`) | 이번 라운드 깊게 볼 관점(레지스트리·설정·계약 절차)에 시간을 썼다 | 해당 파일의 경계 검증식 읽기와 변이 실험 |
| HTTP 응답 DTO 형태의 구·신 버전 공존 | 게이트가 다루지 않는 범위다(외부 계약 패키지 책임). 브라우저 공존 실험은 하지 않았다 | 구 번들 탭에 필드가 바뀐 응답을 주는 Playwright 시나리오 |
@@ -0,0 +1,412 @@
# 08 presentation 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 판)
> 깊게 본 관점: 4, 5, 8, 14, 15, 23, 24 · 추가로 읽은 절: 29, 32(특히 32.1, 32.3), 34~36, 39, 41
## 0. 머리말
### 0.1 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`. 워킹트리의 미커밋 변경은 리뷰 가이드 문서 2개뿐이다. 코드는 커밋과 같다 |
| 목적·실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 영역 경로 | `src/presentation/`(routes, layouts, pages, forms, design-system, i18n, boundaries, components, adapters/query), 샘플 화면 `src/features/reference-feature/presentation/`, 관련 component·e2e 테스트, `scripts/check-i18n.ts`, `config/hosting/security-headers.json` |
| 읽은 코드 | `src/presentation/` 중 routes 전부, forms 전부, components 전부, boundaries 전부, i18n 전부, `layouts/app-shell.tsx`, `providers/session-provider.tsx`, `security/safe-text.tsx`, `styles/theme.css`, `adapters/query/application-query.ts`(폼·재전송 경로 440~770행). 샘플 화면 8파일과 `reference-message-catalog.ts`, `reference-feature-contract.ts`. 연결 확인용으로 `src/contracts/errors.ts`, `src/contracts/routes.ts`, `src/platform/errors/*.tsx`, `src/features/installed-feature-messages.ts`, `src/application/create-application.ts:55-85`, `src/application/ports/auth-session-port.ts` |
| 읽은 문서 | VD-06, `docs/security/browser-boundary.md`, `docs/architecture/optional-adapter-recipes.md` 4절, `docs/architecture/routing-pages-and-patterns.md`, `docs/architecture/starter-experience.md`, `docs/styling/design-system-platform.md`, `CHANGELOG.md` 0.2.0, 지난 리뷰 `08-presentation.md`·`README.md` 11절·`FOLLOW-UP.md` |
| 제품 증거 | `../memento-frontend`, `../tech-log-frontend`의 `chore/template-sync-v0.2.0`을 `git show`·`git archive`로만 읽었다. 동기화 기록 `docs/operations/template-sync-2026-09-29.md` 두 개 |
| 이전 리뷰와 비교 | 지난 08-01~08-13은 현재 코드에서 다시 확인했다(6절). 지난 실행 결과는 증거로 쓰지 않았다 |
### 0.2 실행한 명령과 실험
실험은 분리 worktree(`git worktree add --detach … af3d8e6`, 메인 `node_modules` 링크)에서 했고, 끝난 뒤 지웠다. 빌드는 `corepack pnpm build` 대신 `node scripts/build-frontend.ts`로 직접 돌렸다. 처음 한 번 `corepack pnpm build`를 부르자 pnpm이 링크된 `node_modules`를 다시 설치하려다 `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`로 멈췄다. 아무것도 지우지 않았고, 메인 `node_modules`는 그대로다. Playwright는 다른 에이전트와 겹치지 않게 전용 설정(chromium 한 개, 포트 4291, `npx vite preview`)으로 돌렸다.
| ID | 명령·실험 | 결과 |
|---|---|---|
| R1 | `node scripts/run-vitest.ts run` form-foundation, async-surface, route-status-surfaces, router, chunk-recovery-boundary, render-boundary, locale-platform, page-header-focus, context-route-gateway, pagination, app-shell, reference-page | 12 files / 113 tests 통과 |
| R2 | 빌드 후 Playwright chromium: scroll-restoration, reference-form, reference-save, reference-route, production-csp, i18n | 18/18 통과 |
| R3 | `node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts` | PASS, 초기 JS 203,481 / 204,800 gzip bytes |
| E1 | 변이: 샘플 목록 화면에 한글 주석 한 줄만 추가 → `node scripts/check-i18n.ts` | **실패**(`hardcoded common user-facing locale literal`) |
| E1b | 변이: 같은 파일에 영어 JSX 문구 `<p>Nothing selected yet</p>` 추가 | **통과**(214 keys PASS) |
| E2 | memento 브랜치를 `git archive`로 scratchpad에 풀고 템플릿의 `scripts/check-i18n.ts` 실행 | 21 files 실패(`memento-demo-model.ts`, stories 파일 포함) |
| E3 | 변이: 샘플 기능 catalog에서 `en-US`를 지우고 `tsc -p tsconfig.app.json` | `src/presentation/i18n/catalog.ts(400,6): error TS7053` |
| E4 | probe: `formatMessage("ko-KR", "reference.list.resultCount")`와 `{ count: 1 }`를 넣은 호출을 타입 검사·실행 | 파라미터 없는 호출은 **통과**하고 실행 시 "요청한 문구를 표시할 수 없습니다."를 반환. 파라미터를 넣은 호출은 **TS2345** |
| E5 | component probe: `requestId`가 있는 같은 실패를 `AsyncSurface`와 `FormFailureStatus`에 넣음 | 조회 화면은 `req-123` 표시, 폼 화면은 표시 안 함 |
| E6 | 브라우저 probe(chromium): 목록 500·저장 500에 `x-correlation-id`를 붙여 응답, `Access-Control-Expose-Headers` 유무 비교. 저장 응답 유실(`connectionreset`) 뒤 "같은 요청으로 다시 보내기" | 목록: expose 없으면 지원 참조 없음, 있으면 "지원 참조: corr-list-500". 저장 500: expose와 무관하게 결과 불명 화면에 식별자 없음. 재전송: 두 요청의 `Idempotency-Key`가 같고 "저장했습니다." |
| E7 | component probe: context 라우트 모듈이 청크 오류가 아닌 `ReferenceError`로 실패 | 화면은 "지원 참조: build-x"(incident 없음). `ui.render.failed` 진단 0건 |
| E8 | 변이: 샘플 catalog에서 `route.REFERENCE_RESOURCE_LIST.title`·`.navigation`을 두 locale 모두 삭제 → `check-i18n`, `tsc`, 관련 테스트 20 files | 전부 통과(변이 생존) |
| E9 | 변이: `theme.css` 첫 줄에 jsdelivr Pretendard `@import` 추가 → 빌드 → `production-csp.spec.ts` | 실패. `style-src-elem https://cdn.jsdelivr.net/…` 위반 검출 |
| E10 | 변이: 샘플 상세 화면에 `dangerouslySetInnerHTML` 추가 → `npx eslint` | `FE-OC-019` 오류로 검출 |
| E11 | component probe: `AppRouter basename="/app"`, URL `/app/fixture/items?x=1#results`에서 "로그인 시작" | `beginSignIn("/fixture/items?x=1#results")`. base path가 빠진다 |
### 0.3 확인하지 못한 범위
- Playwright는 chromium만 돌렸다. firefox·webkit, visual, storybook은 돌리지 않았다.
- 실제 스크린리더와 수동 접근성 검토. 기록 10건이 여전히 `pending-manual-review`다(U-2).
- 실제 외부 세션 owner. 두 제품 모두 `returnTo`로 리다이렉트하는 owner가 없다.
- 운영 호스팅이 실제로 보내는 CSP. e2e는 preview 응답에 헤더를 붙여 흉내 낸다.
- HTTP 상태 → 실패 종류·effect 분류(영역 03). 7절에 이 전제에 걸린 시나리오를 적었다.
## 1. 결론
- **조회·폼·결과 불명 흐름은 CHANGELOG 주장대로 동작한다.** 폼 저장 실패는 재로그인·권한 없음·나중에 재시도·사용 불가로 나뉜다(R1, R2의 429 재시도). 응답을 잃은 저장은 같은 멱등 키로 다시 보낸다(E6). 뒤로 가기 스크롤과 해시 이동도 브라우저에서 확인했다(R2).
- **i18n은 "한국어 + 영어"를 전제로 고정돼 있어, 두 제품이 모두 막혔다.** 제품이 지원 locale을 선언할 곳이 없다(08-01). `check:i18n`은 "파일에 한글이 있는가"만 본다. 그래서 주석은 걸고 영어 문구는 놓친다(08-02). memento에서는 merge 단계 게이트 FE-GATE-010에 속한 `check:i18n`이 실패하고, tech-log는 검사 스크립트를 고쳐 썼다.
- **기능 문구의 보간 파라미터가 타입 계약에 없다(08-03).** 타입 있는 `message()`가 틀린 호출을 통과시키고 맞는 호출을 거절한다. 샘플은 타입 없는 resolver로 우회하고, tech-log는 템플릿 파일에 11개 키를 넣었다.
- **지원 참조는 조회·라우트·청크 실패에만 붙었다.** 폼 저장 실패와 결과 불명 화면에는 식별자가 없다(08-04). context 라우트 모듈이 청크 오류가 아닌 이유로 실패하면 진단 이벤트도 남지 않는다(08-05).
- 운영 CSP는 외부 폰트를 제대로 막고 e2e가 이를 잡는다(E9). 다만 폰트·전역 스타일을 넣는 자리와 방법이 문서에 없다(08-07).
- 판정표에 X(미충족)는 없다. High 이상 발견은 없다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — 보호 목록 진입과 언어 전환
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | URL `/examples/reference-resources?limit=20` | — |
| 정책 | context 라우트 경로 선언 → (생성 인덱스) → 기능의 `context-routes.ts` → gateway가 leaf 하나를 고른다. 보호 라우트는 세션이 없으면 로그인 안내를 보인다 | `src/contexts/reference-context/context-module.ts:9`, `src/features/reference-feature/context-routes.ts:6-19`, `src/presentation/routes/app-router.tsx:435-528`, `:231-290` |
| 상태 변화 | route codec이 search를 파싱한다. 조회 결과는 세션 세대별 QueryClient에 들어간다 | `app-router.tsx:347-348`, `src/features/reference-feature/presentation/use-reference-feature.ts:116-147` |
| 외부 I/O | `GET /api/reference-resources` | `use-reference-feature.ts:133-134` |
| 실패 | 500 → `TerminalErrorSurface` + "다시 시도". `x-correlation-id`를 CORS로 노출하면 "지원 참조"가 붙는다(E6). 권한·인증·없음은 디자인 시스템의 `AccessSurface` 계열로 그린다 | `src/presentation/components/async-surface.tsx:138-168` |
| 결과 | 결과 수는 success·empty일 때만 보인다. 언어를 바꾸면 `<html lang/dir>`과 catalog 문구가 바뀐다 | `reference-resource-page.tsx:46-55`, `src/presentation/layouts/app-shell.tsx:93-107`, `src/presentation/i18n/locale-provider.tsx:89-92` |
관찰: ko-KR 화면의 h1은 코드에 박힌 영어 "Reference feature"다(`reference-resource-page.tsx:25`). 문서 제목은 catalog의 "Reference resources"라서 둘이 다르다(08-06). 필터 문구 `limit 20`과 목록의 접근성 이름 `Reference resources`도 코드에 박혀 있다(`:37`, `:62`). `check:i18n`은 이것을 보지 못한다(08-02).
### 2.2 피해가 큰 흐름 — 응답을 잃은 저장
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | 폼 제출 | `src/features/reference-feature/presentation/reference-resource-form-page.tsx:58-68` |
| 정책 | zod 검증 → 제출 하나를 검증부터 결과까지 묶는다(`pendingRef`). 결과를 모르는 제출이 남아 있으면 새 제출을 막는다 | `src/presentation/forms/use-app-form.ts:299-313` |
| 상태 변화 | mutation admission을 만들고 intent·멱등 키를 붙인다. 같은 canonical 입력의 결과 불명 admission이 있으면 그 intent를 다시 쓴다 | `src/presentation/adapters/query/application-query.ts:502-545` |
| 외부 I/O | `POST /api/reference-resources` + `Idempotency-Key` | — |
| 실패 | 연결 끊김·500 → `MAYBE_APPLIED` → admission `UNKNOWN` → 폼 `effect-unknown`. 화면은 "변경됨으로 확인", "같은 요청으로 다시 보내기", "목록을 새로 불러와 확인"을 준다 | `application-query.ts:601-613`, `use-app-form.ts:221-224`, `reference-resource-form-page.tsx:146-171` |
| 결과 | 재전송은 원래 입력과 같은 키로 나가고 성공하면 "저장했습니다."(E6: 키 두 개가 같음) | `application-query.ts:736-748`, `use-app-form.ts:321-344` |
빈틈: 이 화면에는 문의 식별자가 없다. 서버 500에 `x-correlation-id`를 노출해도 마찬가지다(08-04). 재로그인이 필요한 결과 불명은 확인하지 못했다(7절).
### 2.3 변경 흐름 — 제품이 기능 화면을 얹는다
같은 과제를 두 제품이 실제로 했다. 템플릿 소유 presentation 파일을 얼마나 고쳤는지 `af3d8e6`과 제품 브랜치의 diff 줄 수(`<`·`>` 줄 합)로 쟀다.
| 제품이 한 일 | 필요한 수정 | memento | tech-log | 관련 |
|---|---|---|---|---|
| 한국어 전용 화면 | catalog에 en-US를 만들거나 검사를 고침 | `check:i18n` 실패 21 files(E2), 미해결 | `scripts/check-i18n.ts` 30줄 | 08-01, 08-02 |
| 보간이 있는 기능 문구 | 플랫폼 `MessageParameters`에 키 추가 | 0 | `message-contract.ts` 13줄(키 11개) | 08-03 |
| 제품 폰트 | `theme.css` 또는 `main.tsx`에 import | `theme.css` +2(jsdelivr CDN → 운영 CSP 차단) | `main.tsx` 7줄(npm 패키지 자기 호스팅) | 08-07 |
| 제품 셸·레이아웃 | `app-router.tsx` 수정 | 145줄 | 574줄 | > 09-03 |
결과: 두 제품 모두 템플릿 소유 파일을 고쳤다. 템플릿이 이 파일들을 바꾸면 동기화마다 손 병합이 생긴다(memento 기록은 라우터 충돌을 "the substantive one"이라고 적었다).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | P | M4 / M4(폼 결과 상태·AsyncState가 닫힌 union) | E2 | 폼 결과는 `FormResultState` union이다(`form-contracts.ts:16-26`). 타입 있는 `message()`가 파라미터 누락을 허용한다(08-03). 샘플은 search를 `as ReferenceListFilters`로 단언한다(`use-reference-feature.ts:120`) |
| 2 | 구조적 성숙도 | O | M3 / M3 | E3 | presentation 레이어 규칙은 ESLint가 강제한다. `check:architecture` 통과(오케스트레이터). FE-OC-019 변이가 검출됐다(E10) |
| 3 | 변경 용이성 | P | M3 / M1~M3 | E3 | 오류 종류 추가는 `tests/unit/i18n-contract.test.ts:41`이 잡는다. locale 추가·제거(08-01), 기능 문구 파라미터(08-03), 라우트 제목(08-06)은 템플릿 파일 수정이나 수동 맞춤이 필요하다 |
| **4** | 인지 부하 | P | — | E1 | 3.1 참고. 지난 라운드의 막힘 4개 중 2개가 줄었다. 새로 라우트 제목 세 곳(08-06), 파라미터 문구의 우회 경로(08-03)가 생겼다 |
| **5** | 위험 가시성 | P | M2 / M2 | E3 | 결과 불명 화면은 확인 경로와 "NOT_APPLIED는 근거가 필요"를 prop 주석으로 드러낸다(`async-surface.tsx:118-121`). `resendUnknown`도 같은 키 재사용을 적는다(`use-app-form.ts:315-320`). 반면 `message()`는 파라미터 누락을 조용히 대체 문구로 바꾼다(E4, 08-03). `beginSignIn(returnTo)`의 경로 의미는 계약에 없다(08-08) |
| 6 | 실패 성숙도 | P | M2 / M2 | E3 | 폼 실패 5종 분리(R1, R2 429 재시도), 결과 불명 재전송 같은 키(E6). context 라우트 모듈의 비청크 실패는 기록 없이 화면만 바뀐다(08-05) |
| 7 | 운영 성숙도 | > | — | — | 영역 09·13 |
| **8** | 디버깅 가능성 | P | M3 / M3(조회·라우트·청크), M0(폼·결과 불명·context 경계) | E3 | 라우트 렌더 실패·청크 실패는 화면의 `build:incident`와 진단 `correlation_id`가 같다(`tests/component/render-boundary.test.tsx:73-77`, `chunk-recovery-boundary.test.tsx:163-167`). 조회 실패는 서버가 헤더를 노출하면 `requestId`를 보인다(E6). 폼 저장 실패·결과 불명 화면은 식별자가 없다(E5, E6, 08-04). context·feature 경계와 비청크 모듈 실패는 진단이 없다(E7, 08-05) |
| 9 | 유지보수 성숙도 | P | — | E1 | locale 목록이 네 곳에 있다(08-01). 라우트 제목이 세 곳에 있다(08-06) |
| 10 | 테스트 성숙도 | P | M3 / M3 일부 | E3 | 검출된 변이: FE-OC-019(E10), CDN 폰트(E9), 한글 literal. 살아남은 변이: 라우트 문구 삭제(E8), 영어 문구(E1b). 폼·결과 불명의 지원 참조, context 비청크 실패 보고는 테스트가 없다. en-US 브라우저 검사는 목록·폼만 본다(FOLLOW-UP 08-04) |
| 11 | 데이터 성숙도 | - | — | E2 | presentation은 저장을 소유하지 않는다. 폼 값은 URL·storage에 남지 않는다(`form-foundation.test.tsx:239`) |
| 12 | 동시성 성숙도 | O | M3 / M3(화면 쪽) | E3 | 중복 제출 차단(`use-app-form.ts:302-305`), 결과 불명 뒤 같은 키(E6), 세션 세대 fence. application-query 내부 경쟁은 영역 03. 재로그인+결과 불명 조합은 미검증(7절) |
| 13 | 확장성 | > | — | — | 영역 09·11. 문구 catalog가 설치 기능 수만큼 초기 청크에 쌓이는 점은 14번에 적었다 |
| **14** | 성능 성숙도 | P | M3 / M3(예산 게이트) | E2 | 페이지 14개가 lazy 청크다(빌드 출력). `check:bundle` PASS, 여유 1,319 bytes(R3). 초기 청크 `design-system-*.js`(66 KB gzip)에 디자인 시스템 barrel 전체, 라우터, 모든 locale의 플랫폼·기능 문구가 들어 있다(빌드 청크에서 문구 문자열 확인). 샘플 기능 catalog 하나의 소스 gzip이 약 1.6 KB로, 남은 여유보다 크다(소스 기준 추정). FOLLOW-UP P1과 연결된다 |
| **15** | 보안 성숙도 | P | M3 / M3 | E3 | raw HTML은 ESLint가 막는다(E10). 운영 CSP로 부팅·이동하는 e2e가 통과하고(R2), CDN 스타일 주입을 잡는다(E9). 폰트·스타일을 CSP에 맞게 넣는 안내가 없다(08-07). 로그인 복귀 경로 의미가 계약에 없다(08-08). 서버 인가는 범위 밖 |
| 16 | 의존성 성숙도 | > | — | — | 영역 13 |
| 17 | API / Contract 성숙도 | P | M3 / M2 | E3 | route codec 파싱 뒤에만 입력을 쓴다(`app-router.tsx:347-348`). 기능 문구 파라미터 계약이 없다(08-03). `returnTo`가 라우터 기준인지 문서 경로인지 정하지 않았다(08-08) |
| 18 | 배포 성숙도 | O | M3 / M3(화면 쪽) | E2 | 라우트 청크·context 모듈 청크 실패가 reload-once 복구로 간다(`context-route-gateway.test.tsx:98`, R1). 구 탭 e2e는 이번에 돌리지 않았다 |
| 19 | 설정 성숙도 | P | M2 / M2 | E3 | `routerBasePath`는 링크에 반영된다(`route-status-surfaces.test.tsx:140`). 로그인 복귀 주소에는 반영되지 않는다(E11, 08-08). 제품이 locale을 설정할 수 없다(08-01) |
| 20 | 개발자 경험 | P | — | E3 | 2.3의 표. 두 제품이 i18n·폰트·라우터 때문에 템플릿 파일을 고쳤다 |
| 21 | Guardrail 성숙도 | P | M3 / M3(FE-OC-019, CSP e2e), M1(i18n 정밀도, 라우트 문구) | E3 | `check:i18n`의 거짓 양성·거짓 음성(E1, E1b, 08-02). 라우트 문구 누락 무검출(E8, 08-06) |
| 22 | 추상화 성숙도 | O | — | E1 | `FormFailureStatus`가 `TerminalErrorSurface`를 재사용하고, 조회 실패가 `AccessSurface` 계열을 쓴다(`async-surface.tsx:138-155`). 페이지 템플릿은 데이터를 가져오지 않고 슬롯만 가진다. `application-query.ts` 925줄의 bound/legacy 겸용은 학습 비용이 크다(관찰) |
| **23** | 일관성 | P | — | E3 | 같은 실패 화면인데 조회는 식별자를 보이고 폼은 보이지 않는다(E5, 08-04). 라우트 제목 세 곳이 서로 다르다(08-06). ko-KR 화면에 영어 문구가 섞인다(08-02). 샘플 상세의 날짜는 VD-06 결정 6의 UTC 기본값으로 보인다(`reference-resource-detail-page.tsx:37-39`). 기록된 결정이라 발견으로 올리지 않았다 |
| **24** | 네이밍 / 의미 성숙도 | P | — | E3 | `check:i18n`의 실패 문구 "hardcoded common user-facing locale literal"과 주석 "must take its words from the catalog"가 실제 규칙(한글 유무)보다 넓다(08-02). 샘플 지원 안내가 고정 문자열 `REFERENCE-STATUS-DEMO`를 "지원 참조"로 보인다(08-04). `FormResultState`의 `retry-later`는 `retryAfterMs`를 쓰지 않고 버튼이 바로 다시 보낸다(`reference-resource-form-page.tsx:140-143`, 관찰). `MessageKey` 타입이 파라미터까지 보장하는 것처럼 보인다(08-03) |
| 25 | 조직 확장성 | P | — | E1 | 기능 문구 catalog는 기능마다 나뉜다. 파라미터 타입(`MessageParameters`)과 locale 목록은 중앙 파일이라 여러 팀이 같은 파일을 고친다(08-01, 08-03) |
| 26 | Ownership 성숙도 | ? | — | E1 | 수동 접근성 기록 10건이 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/`). 서명 검토는 release 게이트 FE-GATE-028이고 사용자 몫(U-2)이다 |
| 27 | 삭제 가능성 | > | — | — | 영역 09. 제거 검증이 `check:i18n`을 건너뛰는 FOLLOW-UP 09-07은 09가 유효로 확인했다 |
| 28 | 회복 가능성 | O | M2 / M2 | E2 | 라우트 렌더 실패·청크 실패·context 모듈 실패 화면에 "한 번 새로고침"이 있다(`app-router.tsx:108-114`, `chunk-recovery-boundary.tsx:137-140`) |
### 3.1 대표 과제 (관점 4)
지난 라운드와 같은 과제를 다시 했다. "목록 화면이 어느 API를 호출하고, 실패하면 어떤 화면을 보여 주는가."
```text
URL /examples/reference-resources
→ context 경로: src/contexts/reference-context/context-module.ts:9 (grep으로 찾음)
→ 기능 라우트: src/features/reference-feature/context-routes.ts (파일 이름 규약으로 찾음)
두 파일을 잇는 것은 생성 인덱스(src/.generated/, git 밖)다 ← 규약을 알아야 함
→ 페이지: reference-feature-runtime.ts의 lazy import
installed-feature-runtimes.tsx의 ROUTE_RUNTIME에는 기능 항목이 비어 있다.
descriptor 주석이 이유(boot-safe)를 적는다 ← 줄어든 막힘
→ 호출: use-reference-feature.ts:133 → application input → HTTP gateway
→ 실패: AppFailure.kind → ERROR_REGISTRY 행 → error.* 문구
registry와 catalog의 연결은 i18n-contract 테스트가 지킨다 ← 해소된 막힘
→ AsyncSurface → TerminalErrorSurface 또는 AccessSurface
버튼은 registry action과 페이지의 onAction이 둘 다 있어야 보인다 ← 그대로
```
- 줄어든 막힘: 기능 라우트가 기능 폴더의 `context-routes.ts`에 있다. 문구 키 규칙은 테스트가 지킨다.
- 그대로인 막힘: 생성 인덱스 규약, 버튼 표시 조건 두 곳(`async-surface.tsx:96`, `use-reference-failure-action.ts:44-49`).
- 새 막힘: 목록 제목을 바꾸려면 계약·catalog·페이지 세 곳을 봐야 한다(08-06). `{count}` 문구는 타입 있는 `message()`로 쓸 수 없어 주석(`reference-resource-page.tsx:47-49`)을 읽어야 우회 경로를 안다(08-03).
## 4. 설계 선택 설명 (41절)
### 4.1 지원 locale 집합과 catalog parity를 플랫폼 코드에 고정한다 → 변경 권고(08-01)
1. **무엇이 필요한가.** 템플릿은 i18n 동작(pseudo 확장, RTL)을 스스로 검증해야 한다. 제품은 실제로 지원할 locale만 선언하고 그 locale의 문구만 쓰고 싶다. memento는 한국어 전용이다(동기화 기록의 open question 1).
2. **지킬 성질.** 선언한 모든 locale에서 모든 키가 있다. 사용자 선택지에는 선언한 locale만 나온다. 누락은 안전한 대체 문구로 끝난다.
3. **현재 보장.** 확인한 사실: locale은 `SUPPORTED_LOCALES`(`src/presentation/i18n/message-contract.ts:8-13`), `MESSAGE_CATALOGS`(`catalog.ts:403-407`), 셸 선택지(`app-shell.tsx:97-102`), `normalizeLocale` 분기(`message-contract.ts:44-53`), `catalogKeys` 인자 타입(`:129-133`)에 따로 적혀 있다. `EN_MESSAGES`는 모든 키를 갖도록 `satisfies`로 강제된다(`catalog.ts:396`, `:401`). 기능 catalog에서 en-US를 빼면 타입 검사가 실패한다(E3). 셸은 개발용 `Pseudo`, `RTL smoke`를 운영 화면에도 보인다. 보장하지 않는 것: 제품이 locale 집합을 줄이거나 바꾸는 방법.
기록된 의도: VD-06 결정 2(한국어 canonical + 영어·RTL catalog parity), 결정 5(en-XA·ar-EG는 제품 번역이 아님).
4. **대안.** (A) 현 상태. (B) locale 선언을 한 곳에 둔다. 예: `src/presentation/i18n/locales.ts`의 `PRODUCT_LOCALES`와 `DEV_LOCALES`. 나머지 네 곳과 `check:i18n`이 이 목록에서 파생된다. parity는 선언한 locale에만 강제한다. (C) i18n 라이브러리 도입.
5. **비용.** (A) 한 언어 제품은 가짜 영어 문구를 만들거나 템플릿 파일을 고친다. (B) 파일 4~5개와 타입 파생, i18n e2e를 선언에 맞춰 조건화한다. 템플릿 자체의 선언은 지금과 같게 둔다. (C) VD-06 재검토 조건(세 개 이상의 승인 locale 등)이 없다. 번들과 학습 비용만 는다.
6. **판단.** (B). 확인한 조건에서 두 제품 중 하나가 한국어 전용이고, 템플릿의 parity 성질은 "선언한 locale 안에서"로 좁혀도 그대로 지킬 수 있다.
7. **재검토 조건.** 서버 locale 협상, 세 개 이상 실제 locale, 번역 추출 workflow가 생기면 (C)를 다시 비교한다(VD-06 재검토 조건).
### 4.2 폼 저장 실패의 분기 순서와 결과 불명 화면의 두 행동 → 현 상태 유지
1. **무엇이 필요한가.** 모든 다운스트림 폼이 `useAppForm`을 쓴다. 저장 실패마다 사용자가 할 수 있는 행동이 달라야 한다(32.2).
2. **지킬 성질.** 입력 오류만 ErrorSummary에 간다. 재로그인이 필요하면 다른 판단보다 먼저 알린다. 결과를 모르는 저장은 자동으로도, 새 키로도 다시 보내지 않는다.
3. **현재 보장.** 확인한 사실: `applyOutcome`이 422 → reauth → MAYBE_APPLIED → APPLIED_CONFIRMED → CONFLICT → FORBIDDEN·retry → 나머지 순서로 나눈다(`use-app-form.ts:198-248`). 결과 불명 화면은 "변경됨으로 확인"과 "같은 요청으로 다시 보내기"만 준다. "변경되지 않음"은 근거가 없어서 빠졌다(`async-surface.tsx:118-121`). 재전송은 같은 intent·키를 쓴다(E6). 테스트: `form-foundation.test.tsx:150-236`, `reference-page.test.tsx:425`, `:481-534`. 보장하지 않는 것: 재로그인이 결과 불명을 가릴 때의 처리(7절).
기록된 의도: 코드 주석 D-1, D-2, F-10.
4. **대안.** (A) 현 상태. (B) 실패마다 `TerminalErrorSurface` 하나로 통일하고 action만 바꾼다. (C) "변경되지 않음" 선택지를 되살린다.
5. **비용.** (B)는 입력 오류의 필드 연결과 포커스 이동을 잃는다. (C)는 지난 08-03의 결함(근거 없는 판정 뒤 새 키)을 되살린다.
6. **판단.** 현 상태 유지. 분기 순서와 이유가 한 함수와 짧은 주석에 모여 있어 국소적으로 읽힌다(39.3).
7. **재검토 조건.** 서버가 결과 조회(inspect) operation을 제공하면 "변경되지 않음"을 근거와 함께 다시 넣는다. 재로그인+결과 불명 조합이 실제로 생기는 것이 확인되면 분기 순서를 다시 본다.
### 4.3 `check:i18n`이 파일 전체에서 한글을 찾는다 → 변경 권고(08-02)
1. **무엇이 필요한가.** 화면 문구가 catalog를 거치게 해서 번역 누락을 막는다. 32.3은 버튼·오류·empty·loading·알림·접근성 이름을 범위로 든다.
2. **지킬 성질.** 사용자에게 보이는 문구와 접근성 이름이 catalog에서 온다. 주석·테스트 데이터는 대상이 아니다.
3. **현재 보장.** 확인한 사실: 정규식 `/[가-힣]/`를 파일 전체에 적용한다(`scripts/check-i18n.ts:12`, `:95-99`). 한글 주석 한 줄에 실패하고(E1), 영어 JSX 문구는 통과한다(E1b). 샘플에 영어 문구가 이미 있다(`reference-resource-page.tsx:25`, `:37`, `:62`, `reference-resource-detail-page.tsx:24-36`, `reference-resource-form-page.tsx:80`). 기록된 의도: VD-06 검증 절은 "화면 코드의 한국어 literal"이라고 정확히 적는다. 스크립트 주석(`check-i18n.ts:55-57`)과 실패 문구는 "catalog에서 문구를 가져와야 한다"로 더 넓게 말한다.
4. **대안.** (A) 현 상태. (B) 이미 쓰는 ESLint `no-restricted-syntax`에 선택자를 더한다. 예: presentation 파일에서 공백이 아닌 `JSXText`, `aria-label`·`title`·`alt`·`placeholder` 속성의 문자열 literal. 주석은 AST에 없어 자연히 빠진다. (C) tech-log처럼 "행동·상태 문구"만 정규식으로 고르는 제품 정책(`tech-log-frontend:scripts/lib/tech-log-i18n-policy.ts`).
5. **비용.** (A) 두 제품이 각각 막히거나 스크립트를 고쳤다. (B) 새 의존성이 없다. 구두점·고유명사 같은 예외를 어떻게 허용할지 정해야 하고, 샘플의 영어 문구를 catalog로 옮겨야 한다. (C) 한국어 문장 목록에 기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 규칙이 제품 특화다.
6. **판단.** (B). 기존 도구로 주석 거짓 양성과 영어·접근성 이름 거짓 음성을 함께 없앤다. 한 언어 제품에서 이 규칙을 끌지는 4.1의 선언에 맡긴다.
7. **재검토 조건.** 번역 추출 도구를 도입하면 그 도구의 추출 규칙으로 대체한다.
## 5. 발견 사항 (36.3)
### 08-01 제품이 지원 locale을 선언할 곳이 없어, 한 언어 제품은 가짜 번역을 만들거나 템플릿 파일을 고쳐야 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 19, 20, 23, 25, 14 |
| 근거 | locale 집합이 다섯 곳에 따로 있다: `src/presentation/i18n/message-contract.ts:8-13`(`SUPPORTED_LOCALES`), `:44-53`(`normalizeLocale`), `:129-133`(`catalogKeys`), `src/presentation/i18n/catalog.ts:403-407`(`MESSAGE_CATALOGS`), `src/presentation/layouts/app-shell.tsx:97-102`(셸 선택지). `EN_MESSAGES`는 모든 키를 가지도록 `satisfies Record<MessageKey, string>`로 강제된다(`catalog.ts:401`). E3: 샘플 기능 catalog에서 en-US를 빼자 `catalog.ts(400,6): error TS7053`. 셸은 개발용 `Pseudo`·`RTL smoke`를 모든 사용자에게 보인다(`app-shell.tsx:100-101`, `catalog.ts:37-38`). 제품 증거: memento는 한국어 전용이라 문구를 JSX에 두었고, merge 단계 게이트 FE-GATE-010에 속한 `check:i18n`이 실패한다(E2, 동기화 기록 "Introduced and escalated"와 open question 1) |
| 발생 조건 | 제품이 ko-KR 한 언어만 지원할 때. 또는 en-US 대신 다른 locale을 원할 때 |
| 영향 | 한 언어 제품은 (1) 쓸 일 없는 영어 문구를 키마다 만들거나, (2) 템플릿 소유 파일 다섯 곳을 고치거나, (3) merge 게이트가 실패한 채로 둔다. 모든 locale 문구가 초기 청크에 들어가므로 쓰지 않는 locale도 번들 비용이 된다(14번). 운영 사용자에게 개발용 locale이 보인다 |
| 심각도·우선순위 | Medium · P1 — 데이터·보안 피해는 없다. 다만 실제 제품 하나에서 템플릿 계약 때문에 merge 단계 검사가 실패하고, 두 번째 한국어 전용 제품도 같은 길을 간다 |
| 통제·증거 | 선언 수단 M0 · E3(E2, E3) |
| 확실성과 남은 가정 | 확인. memento가 영어 문구를 쓰지 않기로 할지는 제품 결정이다(미정) |
| 결정의 근거 | 4.1절. 확인한 사실은 위 근거. 기록된 의도는 VD-06 결정 2·5. 리뷰어 추론: VD-06은 한 언어 제품을 고려하지 않았다 |
| 이해 비용 | locale을 바꾸려는 제품 개발자가 파일 다섯 곳과 `check:i18n`, e2e `i18n.spec.ts`를 함께 맞춰야 한다 |
| 최소 개선 방향 | locale 선언 파일 하나를 두고(예: `PRODUCT_LOCALES`, `DEV_LOCALES`) 다섯 곳이 여기서 파생되게 한다. parity는 선언한 locale에만 강제한다. 셸 선택지는 `DEV_LOCALES`를 개발 빌드에서만 보인다. `check:i18n`은 선언한 locale이 하나면 문구 literal 규칙을 끄는 대신 그 결정을 산출물(`artifacts/quality/i18n.json`)에 남긴다 |
| 대안 비교 | 4.1절 (A)~(C) |
| 단순화의 보존 조건 | 템플릿 자신의 선언은 ko-KR·en-US·en-XA·ar-EG 그대로다. 기존 parity 테스트와 타입 fixture(`check:types:fixture:i18n-key`, `:i18n-params`)는 그대로 통과한다. 누락 키의 대체 문구 동작은 바뀌지 않는다 |
| 비용·부작용 | 파일 4~5개, 타입 파생, i18n e2e의 조건화. 복사한 제품은 선언 파일 하나를 새로 채워야 한다(CHANGELOG [계약]) |
| 재검토 조건 | 서버 locale 협상이나 번역 추출 workflow가 생길 때 |
| 완료 기준 | ko-KR만 선언한 fixture에서 en-US catalog 없이 `check:types`와 `check:i18n`이 통과한다. 템플릿 기본 선언에서는 지금과 같은 검사가 돈다. 운영 빌드 셸에 `Pseudo`·`RTL smoke`가 없다 |
| 검증 방법 | 한 locale 선언 fixture 타입 검사, 셸 선택지 component 테스트, E2 재실행(memento가 선언을 바꾼 뒤) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-02 `check:i18n`이 "파일에 한글이 있는가"만 봐서, 주석은 걸고 영어 문구·접근성 이름은 놓친다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 23, 24, 10, 20 |
| 근거 | 규칙은 `/[가-힣]/`를 파일 전체 문자열에 적용한다(`scripts/check-i18n.ts:12`, `:95-99`). E1: 한글 주석 한 줄만 넣어도 실패. E1b: 영어 JSX 문구를 넣어도 통과. 샘플 화면의 영어 literal이 이미 통과 중이다: h1 `"Reference feature"`(`reference-resource-page.tsx:25`), `limit {filters.limit}`(`:37`), 목록 접근성 이름 `aria-label="Reference resources"`(`:62`), 상세의 `"DetailPage"`·`"Reference detail"`·`Resource ID`·`Created`(`reference-resource-detail-page.tsx:24-36`), 폼 eyebrow `"FormPage"`(`reference-resource-form-page.tsx:80`). 실패 문구 "hardcoded common user-facing locale literal"과 주석 "must take its words from the catalog"(`check-i18n.ts:55-57`)는 실제 규칙보다 넓다. fixture는 한글 literal 양성 사례만 있다(`tests/fixtures/i18n/forbidden/`). E2: memento의 걸린 21개 파일에는 데모 데이터(`memento-demo-model.ts`)와 stories 파일이 들어 있다. 제품 증거: tech-log는 "comment와 literal을 구분하지 못한다"는 이유로 스크립트를 고쳤다(tech-log 동기화 기록 open 4, `scripts/check-i18n.ts` 30줄 diff) |
| 발생 조건 | 기능 화면 파일에 한글 주석·데이터가 있을 때(거짓 양성). 영어로 문구를 박을 때(거짓 음성) |
| 영향 | ko-KR 사용자에게 영어 제목·필터 문구·스크린리더 이름이 섞인다. 이 샘플을 복사한 제품은 같은 패턴을 검출 없이 퍼뜨린다. 반대로 한국어 주석을 쓰는 팀은 게이트를 끄거나 스크립트를 고친다. 지난 08-04의 완료 기준("en-US 화면에 한국어가 없다")은 통과했지만, 검사 범위가 "catalog 사용"이 아니라 "한글 유무"다 |
| 심각도·우선순위 | Medium · P2 — 문구 누락과 게이트 불신이 반복되지만 기능은 동작한다 |
| 통제·증거 | 한글 literal M3 / 영어·접근성 이름 M0 / 주석 구분 M0 · E3(E1, E1b, E2) |
| 확실성과 남은 가정 | 확인. 어떤 영어 문자열을 허용할지(고유명사, 구두점)는 정해야 한다 |
| 결정의 근거 | 4.3절. 기록된 의도(VD-06 검증 절)는 "한국어 literal"로 좁다. 스크립트 주석·실패 문구는 "catalog 사용"으로 넓다. 리뷰어 추론: 템플릿이 막고 싶은 것은 후자다 |
| 이해 비용 | 게이트가 실패하면 개발자가 주석인지 문구인지 파일을 열어 찾아야 한다. 실패 메시지에 줄 번호가 없다 |
| 최소 개선 방향 | 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로 옮긴다(`JSXText`, 접근성·표시 속성의 문자열 literal). `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다. 샘플의 영어 literal을 catalog로 옮긴다. fixture에 "주석만 있는 파일은 통과"와 "영어 JSX 문구는 실패"를 더한다 |
| 대안 비교 | 4.3절 (A)~(C) |
| 단순화의 보존 조건 | 한글 JSX 문구, `dangerouslySetInnerHTML`, `{failure.message}` 렌더링은 지금처럼 실패한다. `examples` 제외는 유지한다 |
| 비용·부작용 | 샘플 문구 약 10개 이동. 선택자 허용 목록을 관리해야 한다 |
| 재검토 조건 | 번역 추출 도구를 도입할 때 |
| 완료 기준 | E1 변이(한글 주석)는 통과하고 E1b 변이(영어 JSX 문구)는 실패한다. ko-KR 샘플 화면의 main 영역에 catalog 밖 영어 문구가 없다 |
| 검증 방법 | E1·E1b 변이 재실행, 새 fixture 2개, `reference-form.spec.ts`에 ko-KR 검사 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-03 기능 문구의 보간 파라미터가 타입 계약에 없어, `message()`가 틀린 호출은 통과시키고 맞는 호출은 거절한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 5, 17, 21, 22, 23, 25 |
| 근거 | 파라미터 타입은 플랫폼 파일의 닫힌 목록 `MessageParameters`(`src/presentation/i18n/message-contract.ts:17-26`)에만 있다. 목록에 없는 키는 `[parameters?: never]`가 된다(`:32-35`). 기능 catalog의 `"reference.list.resultCount": "총 {count}개 항목"`은 목록에 없다. E4: `formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를 통과하고 실행하면 "요청한 문구를 표시할 수 없습니다."를 돌려준다. `{ count: 1 }`을 넣으면 TS2345로 거절된다. 샘플은 타입 없는 `resolveMessage`로 우회하고 이유를 주석에 적었다(`reference-resource-page.tsx:47-53`). 제품 증거: tech-log는 `techLog.notice.*` 11개 키를 템플릿 `message-contract.ts`에 넣었다(diff 13줄) |
| 발생 조건 | 기능이 `{name}` 같은 보간이 있는 문구를 추가할 때 |
| 영향 | 기능 작성자는 (1) 타입 없는 resolver를 쓰거나(키 오타·파라미터 누락 검출을 잃는다), (2) 템플릿 소유 파일을 고친다(동기화마다 병합). 타입 있는 호출이 파라미터를 빠뜨리면 화면에 대체 문구가 조용히 뜬다 |
| 심각도·우선순위 | Medium · P2 — 화면 오류는 대체 문구로 끝난다. 모든 기능이 부딪히는 경로이고 타입 안전을 우회하게 만든다 |
| 통제·증거 | 플랫폼 키 M4(타입 fixture) / 기능 키 M0 · E3(E4) |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: VD-06 결정 3("보간이 필요한 key는 `MessageParameters`에 선언"). 기능 catalog가 설치 모듈에서 합쳐지는 구조(`src/features/installed-feature-messages.ts:32-62`)는 결정 3 뒤에 생겼다. 리뷰어 추론: 결정 3이 기능 catalog를 고려하지 않았다 |
| 이해 비용 | 기능 작성자가 `{count}` 문구 하나를 쓰려고 플랫폼 i18n 타입과 샘플 주석을 읽어야 한다 |
| 최소 개선 방향 | catalog가 `as const`라 문자열 literal 타입에서 placeholder 이름을 뽑을 수 있다. `MessageArguments<Key>`를 "catalog 문자열의 `{이름}`에서 파생"으로 바꾸면 플랫폼·기능 키가 같은 규칙을 쓴다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로 덮어쓴다 |
| 대안 비교 | (A) 현 상태: 비용 0, 위 영향이 남는다. (B) placeholder에서 파생: 새 개념이 없고 기능이 템플릿 파일을 고치지 않는다. 값 타입은 `string \| number`로 넓어진다. 템플릿 리터럴 타입 재귀로 타입 검사 시간이 조금 는다. (C) 기능 모듈이 `messageParameters` 타입을 선언하고 설치 조립이 교집합을 만든다(`installed-feature-messages.ts`의 `UnionToIntersection`과 같은 방식): 값 타입을 정확히 쓸 수 있지만 catalog와 파라미터 선언을 따로 맞춰야 한다. (B)가 가장 작다 |
| 단순화의 보존 조건 | 기존 타입 fixture(`check:types:fixture:i18n-params`)가 잘못된 파라미터를 계속 거절한다. 누락 보간의 실행 시 대체 동작은 그대로다 |
| 비용·부작용 | 타입 몇 줄과 fixture 1개. tech-log가 넣은 11개 키는 파생으로 대체된다 |
| 재검토 조건 | ICU 복수형·select처럼 placeholder만으로 표현하지 못하는 문구가 생길 때(VD-06 재검토 조건) |
| 완료 기준 | E4의 두 호출 결과가 뒤집힌다: 파라미터 없는 호출은 타입 오류, `{ count: 1 }` 호출은 통과. 샘플이 타입 있는 `message()`로 결과 수를 그린다 |
| 검증 방법 | 기능 키 타입 fixture 추가, E4 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-04 폼 저장 실패와 결과 불명 화면에 문의 식별자가 없고, 샘플 지원 안내는 고정 문자열을 보여 준다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 23, 24, 6 |
| 근거 | 조회 실패는 `supportReference={state.failure.requestId}`를 넘긴다(`src/presentation/components/async-surface.tsx:146-152`, `:165`). 폼의 `FormFailureStatus`는 `userMessageKey`·`action`·`description`만 넘긴다(`src/presentation/forms/form-components.tsx:95-106`). 결과 불명 화면은 `AsyncSurface`의 indicator 분기라 실패 객체가 없다(`async-surface.tsx:170-207`). 폼도 결과 불명일 때 실패를 보관하지 않는다(`use-app-form.ts:221-224`). E5: 같은 `requestId`가 조회 화면에만 보였다. E6: 저장 500에 `x-correlation-id`와 `Access-Control-Expose-Headers`를 붙여도 결과 불명 화면에 식별자가 없었다. 같은 조건의 목록 500은 "지원 참조: corr-list-500"을 보였다. 샘플의 contact-support 행동은 요청 식별자를 버리고 고정 경로로 이동한다(`use-reference-failure-action.ts:7`, `:33-35`). 그 화면은 `supportReference="REFERENCE-STATUS-DEMO"`를 "지원 참조"로 보인다(`reference-resource-status-page.tsx:23`) |
| 발생 조건 | 저장이 5xx·연결 끊김으로 실패할 때. 저장 실패의 action이 contact-support일 때 |
| 영향 | 사용자가 가장 문의하고 싶은 경우(결과를 모르는 저장)에 줄 식별자가 없다. 진단 이벤트에는 `correlation_id`가 남지만(VD-07 결정 4) 사용자 신고와 이을 수 없다. 샘플을 복사한 제품의 모든 폼이 같다. "지원 참조: REFERENCE-STATUS-DEMO"는 식별자처럼 보여 오히려 잘못 전달된다 |
| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 "주요 진단 정보 부족" |
| 통제·증거 | 조회 M3 / 폼·결과 불명 M0 · E3(E5, E6) |
| 확실성과 남은 가정 | 확인. 서버가 헤더를 노출하지 않으면 조회 화면도 식별자가 없다(FOLLOW-UP 03-03, 6절) |
| 결정의 근거 | 적용 제외 — 지난 08-07의 계약("실패 화면에 지원 참조를 보인다")이 이미 정해져 있고 적용 범위만 빠졌다 |
| 이해 비용 | 폼을 만드는 개발자가 조회와 폼의 실패 화면이 다르게 동작한다는 것을 코드를 읽어야 안다 |
| 최소 개선 방향 | `FormFailureStatus`가 `supportReference={failure.requestId}`를 넘긴다. 폼은 결과 불명일 때도 실패를 보관하고, 결과 불명 화면에 식별자를 보인다. 샘플 contact-support 이동은 식별자를 state로 넘기고, 상태 페이지는 받은 값만 보인다(없으면 줄을 숨긴다) |
| 대안 비교 | 적용 제외 — 기대 계약이 고정돼 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 컴포넌트 2개와 샘플 2파일, 테스트 3개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E5의 폼 쪽 단언이 뒤집힌다. E6 저장 500(expose 있음)에서 "지원 참조: corr-save-500"이 보인다. 상태 페이지에 고정 문자열이 없다 |
| 검증 방법 | `form-foundation.test.tsx`에 requestId 단언, `reference-save.spec.ts`에 결과 불명 식별자 단언 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-05 context 라우트 모듈의 비청크 실패와 feature·context 경계의 실패가 진단을 남기지 않고, 화면에는 build id만 보인다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 6, 10, 28 |
| 근거 | `ContextRouteGateway`는 라우트 모듈 로드가 청크 오류가 아닌 이유로 실패하면 `RouteFailureSurface supportReference={buildId}`만 그린다(`src/presentation/routes/app-router.tsx:478-496`). 진단 호출이 없다. 같은 파일의 `ContextErrorBoundary`·`FeatureErrorBoundary`에는 `onError`를 넘기지 않는다(`:466-472`, `:519-525`). 두 경계는 `onError`를 받을 수 있다(`src/platform/errors/scoped-error-boundary.tsx:20`, `:35-43`). `APP_SHELL`의 `errorElement`도 같다(`app-router.tsx:569`). 반면 라우트 안쪽 경계는 incident id를 만들어 보고한다(`:383-391`, `src/presentation/boundaries/render-error-boundary.tsx:38-55`). E7: context 모듈이 `ReferenceError`로 실패하자 화면은 "지원 참조: build-x", `ui.render.failed` 기록은 0건이었다. 이 경로의 테스트는 없다(`tests/component/context-route-gateway.test.tsx`는 청크 실패만 본다) |
| 발생 조건 | 배포 뒤 context 라우트 모듈이 평가 중 throw할 때(중복 키로 `composeUniqueRecord`가 throw, 잘못된 import 등). 라우트 안쪽 경계 밖(예: `RouteLifecycle`, `RouteSurface`의 경계 이전 코드)에서 렌더 오류가 날 때 |
| 영향 | bounded context 하나의 화면 전체가 실패 화면이 되는데 진단 이벤트가 없다. 운영자는 신고를 받기 전에는 알 수 없고, 신고의 build id만으로는 사건을 찾을 수 없다. 지난 09-03(부트 모듈 평가 실패)과 같은 종류의 실패가 context 수준에 남았다 |
| 심각도·우선순위 | Medium · P2 — 발생 가능성은 낮지만 영향 범위가 context 전체이고 탐지 수단이 없다 |
| 통제·증거 | M0 · E3(E7) |
| 확실성과 남은 가정 | 확인. 운영에서 이런 실패가 얼마나 나는지는 모른다 |
| 결정의 근거 | 적용 제외 — 라우트 경계에 이미 있는 보고 계약을 같은 파일의 다른 경계에 적용하지 않은 누락이다 |
| 이해 비용 | 필요한 범위만: `app-router.tsx`의 경계 네 곳 중 두 곳만 보고한다는 사실을 파일을 끝까지 읽어야 안다 |
| 최소 개선 방향 | 비청크 실패 분기와 세 경계의 fallback을 `RenderErrorBoundary`처럼 incident id를 만들고 `diagnostics.reportRenderFailure`를 부르는 형태로 바꾼다. 가장 작은 방법은 이 세 곳도 `RouteBoundary`(incident 함수형 fallback)를 쓰는 것이다 |
| 대안 비교 | 적용 제외 — 기대 계약이 고정돼 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | `app-router.tsx` 수십 줄, component 테스트 1~2개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E7 probe에서 화면의 지원 참조가 `build-x:<incident>`이고, 같은 incident의 `ui.render.failed`가 1건 기록된다 |
| 검증 방법 | `context-route-gateway.test.tsx`에 비청크 실패 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-06 라우트 제목이 계약·catalog·페이지 세 곳에 따로 있고, 샘플에서도 서로 다르며, catalog에서 빠져도 아무 검사도 실패하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23, 24, 21, 4, 10 |
| 근거 | 목록 라우트 하나의 제목: 계약 `title: "Reference feature"`, `navigationLabel: "Reference feature"`(`src/features/reference-feature/contracts/reference-feature-contract.ts:85-86`). catalog `route.REFERENCE_RESOURCE_LIST.title: "Reference resources"`(`reference-message-catalog.ts:4`, `:49`). 페이지 h1 literal `"Reference feature"`(`reference-resource-page.tsx:25`). 문서 제목은 catalog, h1은 literal, 탐색은 catalog의 navigation을 쓴다(`app-router.tsx:173-178`, `app-shell.tsx:189`). 계약의 `title`·`navigationLabel` 문자열은 e2e·성능 스크립트의 기대값(`tests/e2e/accessibility.spec.ts:47`, `old-tab-chunk-recovery.spec.ts:93`, `scripts/test-performance.ts:47`)과 "탐색에 넣을지" 판정에만 쓰인다. 플랫폼 `NOT_FOUND`도 계약 "페이지를 찾을 수 없음"과 catalog "페이지를 찾을 수 없습니다."가 다르다(`src/contracts/routes.ts:94`, `catalog.ts:55`). E8: catalog에서 목록 라우트의 title·navigation을 지워도 `check:i18n`, `tsc`, 관련 테스트 20 files/90 tests가 모두 통과했다. 이 키는 `` resolve(`route.${id}.title`) ``처럼 문자열로 조립돼 타입 검사를 받지 않는다 |
| 발생 조건 | 기능 라우트를 추가·이름 변경할 때 |
| 영향 | 탐색 링크와 문서 제목에 "요청한 문구를 표시할 수 없습니다."가 조용히 뜰 수 있다. 같은 화면의 탭 제목과 h1이 다르다. 제목을 바꾸는 사람이 세 곳을 모두 찾아야 한다 |
| 심각도·우선순위 | Low · P3 — 표시 문제다 |
| 통제·증거 | M0 · E3(E8) |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: `starter-experience.md:34`("Navigation labels and order come from `ROUTE_REGISTRY`"). 실제 표시 문구는 catalog에서 온다. 리뷰어 추론: 계약의 제목 문자열은 catalog 이전의 흔적이고 지금은 테스트 기대값으로만 남았다(39.5의 "어느 도구도 읽지 않는 선언"에 가깝다) |
| 이해 비용 | 대표 과제에서 제목 하나를 바꾸려면 계약·catalog 두 locale·페이지를 열어야 했다(3.1) |
| 최소 개선 방향 | (1) 등록된 모든 라우트에 `route.<id>.title`(탐색 라우트는 `.navigation`도)이 모든 locale에 있는지 단위 테스트로 검사한다. (2) 페이지 h1은 `route.<id>.title`을 쓰거나 페이지 전용 키를 쓰되 literal은 없앤다. (3) 계약의 `title`은 지우거나 "테스트 기대값 전용"이라고 이름을 바꾼다 |
| 대안 비교 | (A) 현 상태. (B) 위 (1)만: 테스트 하나로 누락은 막고 중복은 남는다. (C) (1)~(3): 한 곳으로 모으고 e2e는 catalog에서 기대값을 읽는다(`accessibility.spec.ts`가 이미 그렇게 한다). (B)를 먼저, (C)는 계약 변경이라 CHANGELOG [계약]이 필요하다 |
| 단순화의 보존 조건 | `navigationLabel: null`로 탐색에서 빼는 기능은 유지한다. 성능 스크립트의 대상 링크 선택이 계속 동작한다 |
| 비용·부작용 | 테스트 1개. (C)는 계약 필드 변경과 제품 이행 안내 |
| 재검토 조건 | 라우트 제목을 서버에서 받게 되면 |
| 완료 기준 | E8 변이가 테스트 실패로 잡힌다. ko-KR 샘플 목록의 h1과 문서 제목이 같은 문구다 |
| 검증 방법 | E8 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-07 폰트·전역 스타일을 넣을 제품 쪽 자리와 운영 CSP에 맞는 방법이 안내돼 있지 않다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 15, 19, 20 |
| 근거 | 운영 CSP는 `style-src 'self'; font-src 'self'`다(`config/hosting/security-headers.json:4`). CSP를 넓히는 안내는 선택 기능 세 가지(다른 origin realtime, blob 미리보기, 이미지 CDN)만 있다(`docs/architecture/optional-adapter-recipes.md:155-165`, `docs/security/browser-boundary.md:18-20`). 폰트·전역 스타일에 대한 안내는 `docs/`·README 어디에도 없다(grep `font-src`, `@font-face`, `self-host`: 0건). 기본 토큰은 싣지 않는 `Inter`를 가리킨다(`src/presentation/design-system/tokens/semantic.css:33`). 전역 스타일 진입점은 템플릿 소유 `theme.css`(`src/presentation/styles/theme.css:1-10`)와 `main.tsx`뿐이다. 제품 증거: memento는 `theme.css`에 jsdelivr `@import`를 넣었고 운영 CSP에서 막혔다(동기화 기록 open question 2). tech-log는 npm 폰트 패키지를 `main.tsx`에서 import해 same-origin으로 번들했다(diff 7줄). E9: 같은 `@import`를 넣자 `production-csp.spec.ts`가 `style-src-elem` 위반으로 실패했다. 즉 검출은 된다 |
| 발생 조건 | 제품이 폰트나 전역 스타일시트를 추가할 때 |
| 영향 | 제품이 CDN 경로를 고르면 운영에서 폰트 없이 렌더된다. 검출은 e2e(FE-GATE-008)에서야 된다. 두 제품 모두 템플릿 소유 파일을 고쳐 동기화 충돌 지점이 하나 늘었다 |
| 심각도·우선순위 | Low · P2 — 보안 통제는 제대로 동작한다. 문서 몇 줄과 파일 하나로 두 제품의 반복 비용을 줄인다 |
| 통제·증거 | 차단 M4(CSP) · 검출 M3(e2e, E9) · 안내 M0 · E3 |
| 확실성과 남은 가정 | 확인 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: CSP에 `unsafe-inline`이 없는 것은 의도다(`browser-boundary.md:8-10`). 리뷰어 추론: 폰트는 "선택 기능"이 아니라 거의 모든 제품이 하는 일이라 안내 대상에서 빠졌다 |
| 이해 비용 | 제품 개발자가 CSP 파일, e2e, Vite 자산 처리 방식을 함께 알아야 올바른 방법을 고른다 |
| 최소 개선 방향 | (1) 제품 스타일 진입 파일을 하나 둔다(예: `src/presentation/styles/product.css`를 `theme.css` 끝에서 import하고 템플릿은 비워 둔다). (2) `docs/styling/`에 "폰트는 npm 패키지나 `src/assets`로 자기 호스팅한다. CDN을 쓰려면 `style-src`·`font-src`를 넓히고 보안 결정을 기록한다"를 적는다. (3) 토큰의 `Inter`는 시스템 글꼴 스택으로 바꾸거나 "제품이 교체"라고 적는다 |
| 대안 비교 | (A) 현 상태. (B) 위 (1)~(3). (C) 빌드 시점에 외부 URL `@import`를 거절하는 정적 검사: e2e보다 이르지만 새 검사 비용이 든다. (B)로 충분하다. e2e가 이미 검출한다 |
| 단순화의 보존 조건 | CSP 기본값은 바꾸지 않는다 |
| 비용·부작용 | 빈 CSS 파일 1개, 문서 한 절 |
| 재검토 조건 | 운영 CSP를 배포 환경별로 생성하게 되면(`browser-boundary.md:21-26`) |
| 완료 기준 | 문서에 폰트 추가 절차가 있고, 제품이 `theme.css`·`main.tsx`를 고치지 않고 폰트를 넣을 수 있다 |
| 검증 방법 | 예제 폰트를 `product.css`로 넣은 브랜치에서 `production-csp.spec.ts` 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 08-08 로그인 복귀 주소가 라우터 기준 경로라 base path 배포에서 앱 밖을 가리킬 수 있고, 포트 계약에 그 의미가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 19, 24, 5 |
| 근거 | 셸과 보호 라우트의 로그인 버튼은 `useLocation()`의 `pathname+search+hash`를 넘긴다(`src/presentation/providers/session-provider.tsx:70-81`). 샘플 실패 행동도 같다(`use-reference-failure-action.ts:23`). `useLocation()`은 router basename을 뺀 경로다. E11: `basename="/app"`에서 `beginSignIn("/fixture/items?x=1#results")`가 불렸다. 포트 계약 `beginSignIn(returnTo?: string)`에는 이 값이 라우터 기준인지 문서 경로인지 적혀 있지 않다(`src/application/ports/auth-session-port.ts:22`, `docs/architecture/frontend-ports-adapters-and-boundaries.md:500`). 외부 owner는 `routerBasePath`를 받지 않는다(`src/adapters/auth/external-session-adapter.ts:66`). 앱 안의 링크는 basename을 지킨다(`route-status-surfaces.test.tsx:140`) |
| 발생 조건 | `routerBasePath`가 `/`가 아닌 배포에서, 외부 owner가 `returnTo`를 그대로 리다이렉트 주소로 쓸 때 |
| 영향 | 로그인 뒤 `/fixture/items`처럼 앱 밖 경로로 돌아가 호스트의 404나 다른 앱을 본다 |
| 심각도·우선순위 | Low · P3 — 두 제품 모두 아직 `returnTo`를 쓰는 owner가 없다. 계약 한 줄로 막을 수 있다 |
| 통제·증거 | M0 · E3(E11). owner 동작은 미확인 |
| 확실성과 남은 가정 | 라우터 쪽 값은 확인했다. 실제 owner가 이 값을 어떻게 쓰는지는 repo 밖이다 |
| 결정의 근거 | 확인한 사실은 위 근거. 기록된 의도: 없음. 리뷰어 추론: base path 지원(19번)과 인증 seam이 따로 만들어졌다 |
| 이해 비용 | owner를 구현하는 사람이 presentation 코드를 읽어야 값의 의미를 안다 |
| 최소 개선 방향 | presentation이 문서 경로를 넘긴다(`useHref(location)` 또는 router의 `createHref`). 포트 주석에 "같은 origin의 문서 경로(basename 포함). owner는 open redirect를 막기 위해 같은 origin만 허용한다"를 적는다 |
| 대안 비교 | (A) 현 상태. (B) 문서 경로로 바꾸고 계약에 적는다: owner가 그대로 쓸 수 있다. (C) 라우터 기준으로 두고 계약에 적은 뒤 owner에 `routerBasePath`를 넘긴다: owner마다 조립 코드가 는다. (B)가 작다 |
| 단순화의 보존 조건 | 해시·search 보존(`route-status-surfaces.test.tsx`의 기존 단언)은 유지한다 |
| 비용·부작용 | 호출부 2곳, 테스트 기대값 변경. 이미 라우터 기준 값을 가정한 owner가 있으면 [계약] 변경이다 |
| 재검토 조건 | 로그인 복귀를 서버(BFF)가 전적으로 정하게 되면 |
| 완료 기준 | E11에서 `beginSignIn("/app/fixture/items?x=1#results")` |
| 검증 방법 | basename 케이스 component 테스트 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 없음(신규) |
### 5.1 다른 영역으로 넘긴 것
- **제품 셸·레이아웃 자리가 없다.** 두 제품이 `app-router.tsx`를 고쳤다(145줄, 574줄). 09-03이 이미 적었다. presentation 쪽 추가 근거: 라우팅 문서는 "nested layout이 필요하면 contract에 parent ID를 두고 registry gate에서 검사한다"고 약속한다(`docs/architecture/routing-pages-and-patterns.md:210-212`). `RouteDefinition`에는 parent 필드가 없다(`src/contracts/routes.ts:1-13`). 문서의 확장 경로가 구현되지 않았다.
- **디자인 시스템 primitive 수정.** memento는 `unstyled` prop을 더했고(`core.tsx` 57줄), tech-log는 `Pagination`·`StatusPage` 옵션을 더했다(168줄, 115줄). 문서는 `className`을 escape hatch로 정하고 제품 전용 조합을 primitive에 넣지 말라고 한다(`docs/styling/design-system-platform.md:298`, `:105-107`). 템플릿 결함으로 보지 않았다. 제품이 템플릿 barrel에 자기 컴포넌트를 넣은 것(memento `design-system/index.ts`)은 동기화 비용으로만 기록한다.
## 6. FOLLOW-UP 재확인
| 항목 | 현재 코드에서 확인한 것 | 결과 |
|---|---|---|
| 4절 P3 08-04: en-US 브라우저 검사가 목록·폼만 본다 | en-US 검사는 목록과 폼 두 화면뿐이다(`tests/e2e/reference-form.spec.ts:55-80`). 검사 방식도 "한글이 없다"라 영어 literal은 보지 않는다(08-02) | 유효 |
| 4절 P3 08-07: 화면의 요청 ID와 진단 이벤트가 같은지 확인하지 않는다 | 라우트·청크 incident는 화면과 `correlation_id`를 같은 테스트에서 비교한다(`render-boundary.test.tsx:73-77`, `chunk-recovery-boundary.test.tsx:163-167`). HTTP 요청 ID는 화면 테스트가 합성한 `requestId`를 쓰고(`async-surface.test.tsx:144-151`), 진단 쪽은 HTTP 통합 테스트가 따로 본다(`tests/integration/http-diagnostics.test.ts:88`, `:120`). 한 흐름으로 잇는 테스트는 없다 | 유효(HTTP 요청 ID 쪽) |
| 4절 P3 03-03(영역 03, 화면에 보임): 서버가 헤더를 돌려주지 않으면 `requestId`가 빈다 | E6: CORS `Access-Control-Expose-Headers`가 없으면 목록 500 화면에 지원 참조가 없다. 문서는 expose가 필요하다고 적는다(`docs/operations/api-contract-and-server-state-recovery.md:184-188`). 클라이언트가 보낸 ID로 대체하지는 않는다 | 유효 |
| 1절 P1 초기 JS 예산 | R3: 203,481 / 204,800(여유 1,319 bytes). 초기 청크에 모든 locale 문구와 디자인 시스템 전체가 있다(14번) | 유효 |
| 6절 U-2 수동 접근성 10건 | `artifacts/tests/a11y-manual/*.md` 10건 모두 `pending-manual-review` | 유효(사용자 몫) |
| 지난 08-01~08-13(닫힌 발견) | 08-01 폼 실패 분리(R1, R2), 08-02 문구 누락(`i18n-contract.test.ts:41`), 08-03 같은 키 재전송(E6), 08-05 상태별 axe(R2), 08-08 스크롤·해시(R2), 08-09 결과 수(`reference-resource-page.tsx:50`), 08-10 언어 전환 재번역(`use-app-form.ts:62-83`), 08-11 접근 화면 통합(`async-surface.tsx:214-225`), 08-12 수정키 클릭(`navigation.tsx:273-281`), 08-13 `items/` 경로(`reference-feature-contract.ts:92`). 08-04는 한글 기준으로만 닫혔다(08-02). 08-07은 세 화면 밖에 빈 곳이 있다(08-04, 08-05). 08-06은 게이트를 FE-GATE-028로 옮겼고 기록은 여전히 pending이다 | 회귀 없음. 범위 밖 빈 곳은 새 발견으로 적음 |
## 7. 미검증 목록
| 무엇 | 왜 못 했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 재로그인이 필요한 결과 불명 저장 | 폼은 reauth를 결과 불명보다 먼저 처리하고(`use-app-form.ts:215-224`), 화면은 `form.failure`가 있으면 결과 불명 표시를 숨긴다(`reference-resource-form-page.tsx:137-146`). 로그인 뒤 scope가 바뀌면 결과 불명 기록과 입력이 사라져, 같은 내용을 다시 저장하면 새 키로 나갈 수 있다. 어떤 HTTP 응답 조합이 `AUTH_REQUIRED`+`MAYBE_APPLIED`를 만드는지는 영역 03의 분류에 달려 있다 | 영역 03의 effect 분류표, 해당 응답을 만드는 브라우저 probe |
| firefox·webkit에서 이번 presentation spec | 시간과 호스트 공유 때문에 chromium만 돌렸다 | `playwright.config.ts`의 세 엔진 실행 |
| 실제 스크린리더 발표 | 도구 없음. `LoadingSurface`는 `aria-busy="true"`와 `aria-live="polite"`를 같이 쓴다(`async-surface.tsx:22-28`). 로딩이 끝나면 영역이 사라져 "불러오는 중"이 발표되지 않을 수 있다 | NVDA·VoiceOver 수동 검토(U-2) |
| visual·storybook | 이번 범위에서 돌리지 않았다 | `test:visual`, `test:storybook` |
| 외부 owner의 `returnTo` 처리 | 템플릿·제품 모두 실제 리다이렉트 owner가 없다 | OIDC·BFF owner 구현 |
| 운영 호스팅의 실제 CSP 응답 | e2e는 preview 응답에 헤더를 붙인다 | `verify-hosting-headers`를 실제 배포에 실행(영역 13) |
| 초기 청크에서 문구 catalog가 차지하는 정확한 바이트 | 소스 gzip으로만 추정했다(플랫폼 약 6.4 KB, 샘플 기능 약 1.6 KB) | 번들 분석기로 `design-system-*.js` 모듈별 크기 측정 |
@@ -0,0 +1,350 @@
# 09 애플리케이션 코어·기능·조립 — 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` (코드 변경 없음, 리뷰 가이드 문서 2개만 미커밋) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 영역 판정(35.8): **조건부 사용 가능** — 템플릿의 틀(`AppShell` 아래 context, `http`·`telemetry` capability, 세션 기반 자격증명) 안에 들어가는 기능은 기능 디렉터리만 고쳐 설치할 수 있다. 제품이 홈(`/`)·자기 레이아웃·추가 capability·세션 밖 자격증명을 필요로 하면 템플릿 소유 파일을 고쳐야 하고, 다음 동기화에서 같은 파일이 다시 충돌한다(09-02, 09-03). `ANONYMOUS` 인증 프로필로 공개 API를 부르는 용도는 09-01 해결 전 사용 보류.
## 1. 머리말
### 1.1 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`, 2026-09-29 |
| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 영역 경로 | `src/application/`(3.6k줄), `src/features/`(2.9k줄), `src/bootstrap/`(2.2k줄), `src/platform/`(2.6k줄), `src/apps/`, `src/contexts/`, `scripts/generate-product-feature-index.ts`, `src/presentation/routes/app-router.tsx`의 조립 부분(`createRegisteredRoutes`, `ContextRouteGateway`) |
| 깊게 본 관점 | 2, 3, 4, 9, 13, 22, 25, 27 |
| 추가로 읽은 가이드 절 | 0, 2~4, 9, 13, 22, 25, 27, 29, 30(특히 30.3, 30.4, 30.7), 32(특히 32.4), 34~36, 39(특히 39.4, 39.6), 41 |
| 읽은 코드 | `src/features/` 최상위 조립 파일 전부(`feature-module.ts`, `feature-adapter-contribution.ts`, `installed-*` 8개), `local-draft-feature/NOT_INSTALLED`, `src/bootstrap/runtime-adapters.ts` 전체, `main.tsx`, `src/apps/*`, `src/contexts/*`, `src/platform/routing/context-route-module.ts`, `src/platform/cardinality/compose-unique-record.ts`, 생성기 전체, `app-router.tsx`의 1~72행·400~601행. 연결 확인용으로 `src/contracts/rest-profiles.ts`, `src/contracts/routes.ts`, `src/contracts/product-features.ts`, `src/adapters/http/http-execution-v3.ts`(자격증명 처리 부분), `src/adapters/http/http-contract-bridge.ts:66-96`, `.dependency-cruiser.json` 규칙 목록, `scripts/test-sample-removal.ts`, `docs/architecture/starter-experience.md` |
| 다운스트림 증거 | `../memento-frontend` 브랜치 `chore/template-sync-v0.2.0`(`d3810a0`, 템플릿과 이력 공유), `../tech-log-frontend` 브랜치 `chore/template-sync-v0.2.0`(`42d1ae1f`, 패치 이식). 두 제품의 `docs/operations/template-sync-2026-09-29.md`. `git diff af3d8e6 <branch> -- <path>`로 템플릿 대비 제품 변경만 읽었다. 브랜치는 바꾸지 않았다 |
| 이전 리뷰와 비교 | `docs/reviews/2026-09-25-maturity-review/09-app-core.md`의 09-01~09-12를 현재 코드에서 다시 확인했다(7절). 이전 실행 결과는 증거로 쓰지 않았다 |
### 1.2 실행한 명령과 실험
모두 격리 worktree(`<scratchpad>/review-2026-09-29/09/wt`, `af3d8e6`, 메인 `node_modules` 심볼릭 링크)에서 했다. 끝난 뒤 worktree를 지웠다.
| ID | 무엇 | 결과 |
|---|---|---|
| R1 | `node scripts/run-vitest.ts run tests/features tests/contract/reusable-capability/feature-adapter-composition.test.ts tests/unit/{product-features,two-feature-install-typecheck,product-feature-selection-build,runtime-adapters,feature-override-diagnostics,installed-feature-messages,product-index-entrypoints}.test.ts` | **27 files / 123 tests 통과** |
| E1 | 템플릿 fixture의 `ANONYMOUS` 프로필 operation(`tests/helpers/external-contract-fixture.ts`의 `TEST_LIST_ENTITIES`)을 설치한 상태로 실제 `createRuntimeAdapters`를 만들고, 기능이 받는 `http` capability로 실행했다. `installed-contract-contributions.ts`와 `installed-feature-adapters.ts`만 `vi.mock`으로 바꿨다 | 로그아웃: `UNAUTHENTICATED`, fetch 0회. 로그인(demo): `AUTH_INTEGRATION_FAILURE` / `CREDENTIAL_HEADER_NOT_ALLOWED`, fetch 0회 |
| E2 | 픽스처 기능(`home-feature`, context 경로 `*`)을 추가하고 생성기를 돌린 뒤 `ROUTE_REGISTRY`를 import했다. (가) 라우트 id `APP_HOME`, (나) 라우트 id `PRODUCT_HOME`·경로 `/` | (가) 모듈 평가 시 `TypeError: Duplicate route registry key: APP_HOME`. (나) 오류 없음, `/`에 라우트 2개(`APP_HOME`=platform, `PRODUCT_HOME`=home-feature) |
| E2b | `app-router.tsx:530-575`와 같은 모양(`APP_SHELL` 아래 index `APP_HOME` + context `*`)을 `react-router-dom`의 `matchRoutes`로 확인 | `/` → `APP_SHELL > APP_HOME`. 기능의 `/` 라우트는 조용히 가려진다 |
| E3 | 변이: `installed-feature-contracts.ts`에 `NOT_INSTALLED` 디렉터리(`local-draft-feature`)의 모듈을 직접 import하고, 그 값으로 만든 라우트를 `ROUTE_REGISTRY`에 끼워 넣었다. 그 뒤 `product-features.test.ts`, `feature-installation-surface.test.ts`, `installed-feature-messages.test.ts`, `corepack pnpm check:architecture` 실행 | 테스트 3 files / 19 tests 통과, `check:architecture` 통과. **변이가 살아남았다** |
| D1 | 두 제품에서 템플릿 대비 수정한 파일 목록(`git diff --name-status af3d8e6 <branch>`의 `M`)과 교집합 | memento 73개, tech-log 125개, 둘 다 고친 파일 32개(그중 `src/` 7개). 6절 |
| D2 | 조립 파일의 템플릿 변경 빈도: `git log --oneline ebea300..af3d8e6 -- <path>` | `runtime-adapters.ts` 15커밋, `app-router.tsx` 11커밋, `installed-feature-contracts.ts` 3커밋 등. 6절 |
### 1.3 확인하지 못한 범위
- 실제 브라우저에서 09-01의 공개 화면 실패. 코드 경로와 E1(vitest)로 확인했다. tech-log 기록은 "공개 사이트가 모든 화면에서 최종 오류 화면을 보였고 네트워크 로그에 요청이 없었다"고 적는다(제품 `src/bootstrap/runtime-adapters.ts:588-596` 주석). 이것은 주장이다.
- 외부 인증 owner(`AUTH_MODE=external`)로 로그인한 상태의 `ANONYMOUS` 호출. owner에게 인증 프로필이 전달되지 않는다는 것은 코드로 확인했다(`runtime-adapters.ts:513-520`). 실행하지 않았다.
- 제안한 확장 지점(4절)을 실제로 만들었을 때 두 제품의 다음 동기화 충돌이 줄어드는지. 설계 제안이며 검증하지 않았다.
- 다음 동기화의 충돌 수. 6절의 목록은 현재 diff와 템플릿 변경 빈도로 낸 추정이다.
## 2. 대표 흐름
### 2.1 정상 흐름 — 기능 하나를 설치해 첫 화면까지
```
feature-module.ts 선언 → 생성기 → src/.generated/* → installed-* 투영
→ main.tsx 동적 import → createRuntimeAdapters(capability 조립)
→ AppRouter(AppShell 아래 context gateway) → 기능 라우트 렌더
```
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | 기능은 `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID` 리터럴과 `FEATURE_MODULE`을 낸다. context는 경로·예산을 낸다 | `src/features/reference-feature/feature-module.ts`, `src/contexts/reference-context/context-module.ts:7-10` |
| 정책 | 생성기가 앱 → context → 기능 순서로 소유를 확인하고, 예산·중복 id·`VITE_PRODUCT_FEATURES` 선택을 적용한다. `feature-module.ts`도 `NOT_INSTALLED`도 없는 디렉터리는 실패한다 | `scripts/generate-product-feature-index.ts:187-239`, `:262-297` |
| 상태 변화 | 조립 카탈로그가 생성 인덱스를 투영한다. 키 중복은 `composeUniqueRecord`가 막는다 | `src/features/installed-feature-contracts.ts:23-39`, `src/platform/cardinality/compose-unique-record.ts:16-18` |
| 외부 I/O | 부트가 설정·매니페스트를 읽고 capability 객체(`http`, `telemetry`)를 만든다. 기능은 선언한 `needs`만 받는다 | `src/bootstrap/runtime-adapters.ts:592-598`, `src/features/feature-adapter-contribution.ts:177-190` |
| 실패 | 조립 검증 실패는 모듈 평가 시 throw한다. `main.tsx`가 앱 그래프를 동적 import해서 부트 실패 화면으로 받는다 | `src/bootstrap/main.tsx:14-17`, `src/bootstrap/render-boot-failure.tsx:25-28` |
| 결과 | 라우터가 모든 context를 `AppShell` 아래에 붙이고, gateway가 context 라우트 모듈을 늦게 읽어 leaf 라우트 하나를 렌더한다 | `src/presentation/routes/app-router.tsx:530-575`, `:435-527` |
### 2.2 피해가 큰 흐름 — 기능의 HTTP 호출과 자격증명
```
기능 → http capability(contractOperations) → V3 executor
→ attachCredentials(runtime-adapters) → 세션 상태 → credentialPatch
→ admitCredentialHeaders(프로필 허용 헤더) → fetch
```
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | operation 계약이 `authProfileId`를 가진다. `auth: "none"`이면 `ANONYMOUS` 프로필이어야 한다 | `src/contracts/rest-profiles.ts:68-74`, `:297` |
| 정책 | executor는 모든 operation에서 `attachCredentials`를 부른다. 조립 루트의 구현은 프로필을 보지 않고 세션만 본다 | `src/adapters/http/http-execution-v3.ts:719`, `src/bootstrap/runtime-adapters.ts:501-531` |
| 상태 변화 | 없음(전송 전 판단) | — |
| 외부 I/O | 헤더가 프로필 허용 목록을 벗어나면 fetch 0회로 끝난다 | `src/adapters/http/http-contract-bridge.ts:80-85` |
| 실패 | `ANONYMOUS` 호출이 로그아웃이면 `UNAUTHENTICATED`, 로그인이면 `CREDENTIAL_HEADER_NOT_ALLOWED`(E1) | 09-01 |
| 결과 | 공개 API가 어느 세션 상태에서도 나가지 않는다. 방향은 fail-closed라 정보 노출은 없다 | — |
### 2.3 변경·삭제 흐름 — 제품이 템플릿을 받아 기능을 얹고 다시 동기화
```
제품이 기능 추가 → 틀에 안 맞는 부분(홈·레이아웃·capability·자격증명)을 템플릿 파일에 직접 수정
→ 템플릿이 같은 파일을 계속 수정(runtime-adapters.ts 15커밋)
→ 다음 동기화에서 3-way 충돌(memento 25경로, tech-log 67경로) → 손으로 병합
→ 템플릿 테스트를 제품 내용으로 다시 겨눔
```
| 단계 | 내용 | 위치 |
|---|---|---|
| 입력 | 템플릿 문서는 "중앙 카탈로그(`installed-*`)는 바뀌지 않는다", `runtime-adapters.ts`는 `indexedDb`일 때만 고친다고 적는다 | `docs/architecture/starter-experience.md:143-147` |
| 정책 | memento는 `feature-module.ts`로 설치했지만 홈·셸·capability·자격증명을 위해 템플릿 파일 4개를 고쳤다. tech-log는 제품 도메인을 `NOT_INSTALLED`로 표시하고 조립 파일 5개·부트 파일 4개·라우터를 고쳤다 | 6절, 09-02~09-04 |
| 상태 변화 | 두 제품 모두 `runtime-adapters.ts`, `app-router.tsx`, `installed-feature-contracts.ts`를 템플릿과 다르게 가진다 | D1 |
| 외부 I/O | 없음 | — |
| 실패 | 병합 누락은 타입·테스트가 일부만 잡는다. 제품이 조립 파일에 직접 끼운 값은 어떤 검사도 잡지 않는다(E3) | 09-04 |
| 결과 | 템플릿 수정(보안·계약 포함)이 들어오는 파일이 제품이 가장 많이 고친 파일과 겹친다. 제품이 고친 템플릿 테스트 파일은 memento 31개, tech-log 34개다(이 영역 원인 외 것도 포함) | 6절 |
기능 제거는 `test:sample-removal -- --feature=<id>`로 생성기 설치 기능에는 일반화돼 있다(`scripts/test-sample-removal.ts:29-38`). 생성기 밖에서 조립한 도메인에는 제거 경로가 없다(09-04).
## 3. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 판정 | 근거·잔여 위험 |
|---|---|---|---|
| 1 | 코드 성숙도 | O | local-draft 쓰기 경로가 도메인 팩터리를 거친다(`local-draft-api.ts:60-73`). 조립 검증(중복 id·needs·예산)이 모듈 평가 시 throw한다 |
| 2 | 구조적 성숙도 | P | 템플릿 자체의 부트스트랩은 `installed-*`만 import한다. 그러나 `src/bootstrap`·`src/features/installed-*`가 기능 내부(`src/features/<x>/…`)를 직접 import하는 것을 막는 규칙이 없다(`.dependency-cruiser.json` 규칙 목록). E3: `NOT_INSTALLED` 디렉터리 직접 import가 `check:architecture`를 통과했다. tech-log 부트스트랩은 실제로 `features/tech-log/adapters/http/*`를 직접 import한다(제품 `runtime-adapters.ts` 38-42행) |
| 3 | 변경 용이성 | X (실제 제품 기능 추가 기준) | 템플릿 fixture 기능은 기능 디렉터리만 고쳐 설치된다(R1의 `two-feature-install-typecheck.test.ts` 통과). 실제 제품 2개는 둘 다 템플릿 소유 조립 파일을 고쳤다. 홈 교체·레이아웃·capability 추가·세션 밖 자격증명·제품 설정 키를 표현할 계약이 없다(09-02, 09-03). E2: 기능의 `/` 라우트는 오류 없이 가려진다 |
| 4 | 인지 부하 | P | 기능 작성자는 리터럴 선언 3종과 `defineFeatureModule` 추론만 알면 된다(39.4 기준 충족). 반면 `NOT_INSTALLED`가 세 가지 뜻으로 쓰인다(09-04). 틀 밖 요구는 제품마다 숨은 규약을 만든다: memento의 형식 없는 `ownsShell` 필드와 `APP_HOME` 허용 목록, tech-log의 `NOT_INSTALLED`="직접 조립" |
| 5 | 위험 가시성 | P | `needs` 누락은 기능 id와 capability 이름으로 실패한다(`feature-adapter-contribution.ts:186-189`). 자격증명 결정은 `attachCredentials` 안에 숨어 있고, 인증 프로필 차원을 보지 않는다는 사실이 호출부에서 보이지 않는다(09-01) |
| 6 | 실패 성숙도 | P | 모듈 평가 실패도 부트 실패 화면으로 간다(`main.tsx:14-17`). `ANONYMOUS` 호출은 안전한 방향으로 실패하지만 기능이 전혀 동작하지 않는다(09-01) |
| 7 | 운영 성숙도 | P | 모르는 `FEATURE_OVERRIDES` 키를 진단으로 남긴다(`runtime-adapters.ts:462-471`). 부트 실패는 설정 전이라 수집기로 갈 수 없다(설계 한계). SLO는 템플릿 범위 밖 |
| 8 | 디버깅 가능성 | P | 조립 오류는 키·기능·파일 이름을 담는다(`compose-unique-record.ts:17`, 생성기 `:291-293`). 기능 라우트가 `/`에서 가려지는 경우는 아무 신호가 없다(E2b). `ANONYMOUS` 실패 이유 `CREDENTIAL_HEADER_NOT_ALLOWED`는 원인(프로필 무시)과 멀다 |
| 9 | 유지보수 성숙도 | P | 이전 라운드 09-01~09-12는 코드에서 해소 확인(7절). 템플릿이 가장 자주 바꾸는 조립 파일(`runtime-adapters.ts` 15커밋, `app-router.tsx` 11커밋)을 두 제품도 고쳐, 동기화마다 손 병합이 반복된다(6절, D1·D2) |
| 10 | 테스트 성숙도 | P | 기능 2개 typecheck, 선택 빌드, needs 누락 테스트가 있고 통과한다(R1). 실제 조립 루트로 `ANONYMOUS` operation을 실행하는 테스트가 없다(09-01). "모든 카탈로그가 매니페스트를 참조" 테스트는 import 존재만 보고 직접 끼워 넣기를 놓친다(E3, `tests/unit/product-features.test.ts:175-208`) |
| 11 | 데이터 성숙도 | P | local-draft ABA는 주석으로만 막는다(`local-draft.ts:2-11`, FOLLOW-UP 09-08). 샘플 범위라 영향이 작다 |
| 12 | 동시성 성숙도 | > | 세대 fence·scope 판단은 03 영역(`adapters/query-cache`). 이 영역의 `attachCredentials`는 scope를 전송 전후 두 번 확인한다(`runtime-adapters.ts:502-504`, `:521-523`) |
| 13 | 확장성 | P | 기능 수 축: 2개 설치 typecheck 게이트(R1), context·app 예산(생성기 `:199-223`)이 있다. 설치 기능의 계약·메시지·런타임 설명자는 초기 그래프에 eager로 들어가고, 초기 JS 여유는 약 1.3KB다(FOLLOW-UP P1, 13 영역에서 측정). 제품 수 축: 제품 2개가 같은 조립 파일을 고친다(09-02, 09-03) |
| 14 | 성능 성숙도 | > | 번들 예산은 13 영역 |
| 15 | 보안 성숙도 | P | demo 인증 차단·외부 owner fail-closed는 유지된다. 자격증명 정책을 넓힐 방법이 조립 루트 closure 수정뿐이라, 제품이 fail-closed 코드를 손으로 병합한다(09-02). tech-log 주석은 그 수정 중 무한 재귀 결함을 한 번 냈다고 적는다(제품 `runtime-adapters.ts:496-530` 주석) |
| 16 | 의존성 성숙도 | - | 이 영역 고유 의존성 없음 |
| 17 | API / Contract 성숙도 | P | 템플릿이 설치한 `ANONYMOUS` 프로필 계약을 조립 루트가 지키지 않는다(09-01, E1). 기능 계약·컨텍스트 선언은 생성기와 조립 검증으로 강제된다 |
| 18 | 배포 성숙도 | > | 13 영역 |
| 19 | 설정 성숙도 | P | `VITE_PRODUCT_FEATURES`는 생성기 한 곳에서 적용된다(생성기 `:181-239`). 제품 전용 런타임 설정 키를 넣을 자리가 없어 tech-log는 템플릿 스키마(`src/bootstrap/runtime-config-schema.ts`, `src/contracts/release-artifacts.ts`)를 고쳤다(09-02) |
| 20 | 개발자 경험 | P | 기능 추가 안내가 실제 생성기 규칙과 맞는다(`starter-experience.md:112-147`). 그러나 "기능 디렉터리 밖에서 바꾸는 파일" 표가 실제 제품 경험과 다르다(09-02, 09-03) |
| 21 | Guardrail 성숙도 | P | 표시 없는 기능 디렉터리, needs 누락, 키 중복, 예산 초과는 막힌다. 조립 파일·부트스트랩에 기능 내부를 직접 끼우는 경로는 어떤 검사도 막지 않는다(E3, 09-04) |
| 22 | 추상화 성숙도 | P | `FeatureModule` 제네릭 6개는 호출부에서 추론된다. 기능 2개에서도 동작한다. `FeatureIndexedDbRepositories`는 확장 가능한 interface인데 `FeaturePlatformCapabilities`는 닫힌 type alias다(`feature-adapter-contribution.ts:14`, `:46-51`). 런타임 설명자는 `unknown`이라 제품이 붙인 필드(`ownsShell`)가 형식 없이 라우터로 흘러간다(09-03) |
| 23 | 일관성 | P | 위 22의 interface/alias 불일치. 플랫폼 라우트는 기능 소유가 아니라는 불변식이 테스트에만 있고(`product-features.test.ts:212-222`), memento는 그 테스트를 고쳐 `APP_HOME`을 기능 소유로 바꿨다 |
| 24 | 네이밍 / 의미 성숙도 | P | `NOT_INSTALLED`가 (1) 생성기 표시 파일, (2) 런타임 상태 "선언됐지만 선택 안 됨"(`src/contracts/product-features.ts:32`, `:122`), (3) tech-log의 "직접 조립"으로 쓰인다(09-04). 두 제품 모두 앱 id `template-app`과 `TEMPLATE_APP_MODULE`을 그대로 쓴다(두 기록의 follow-up) |
| 25 | 조직 확장성 | X (구조 + 실제 다운스트림 증거) | 팀은 하나지만 제품이 2개다. 두 제품이 같은 템플릿 파일 7개(`src/` 기준)를 고쳤고, 그중 조립 파일 3개는 확장 지점이 없어서 고쳤다(6절). 기능 팀이 플랫폼 소유 파일을 고치지 않고는 홈·레이아웃·capability를 바꿀 수 없다 |
| 26 | Ownership 성숙도 | > | 파일별 템플릿/제품 소유 표(30.3)는 14 영역 문서 범위. 이 영역에서는 소유가 섞인 파일 하나를 09-05로 적었다 |
| 27 | 삭제 가능성 | P | 생성기 설치 기능은 `--feature=<id>`로 제거를 검증한다. 제거 검증은 lint·`check:i18n`·e2e를 건너뛴다(`scripts/test-sample-removal.ts:415-428`, FOLLOW-UP 09-07). 생성기 밖에서 조립한 도메인은 제거 경로가 없다(09-04) |
| 28 | 회복 가능성 | P | 부트 실패 화면에 재시도가 있다(`boot-error-shell.tsx:24-38`). reload 반복은 TTL guard가 막는다(`release-mismatch-recovery.ts:60-90`). 부트 실패 후 자동 회복은 의도적으로 없다 |
집계(이 영역에서 판정한 23개): 충족 1 · 부분 충족 20 · 미충족 2(3, 25) · 미검증 0. 적용 제외 1(16), 다른 영역 4(12, 14, 18, 26).
## 4. 설계 선택 설명 (41절)
### 4.1 조립 카탈로그(`installed-*`)를 생성 인덱스의 투영으로만 둔다
1. **무엇이 필요한가.** 기능이 늘어도 중앙 파일을 고치지 않아야 한다. 기능 선택(`VITE_PRODUCT_FEATURES`)과 킬스위치가 모든 소비자에게 같게 적용돼야 한다.
2. **지킬 성질.** 설치된 기능 집합은 생성 인덱스 하나에서 나온다. 키 중복은 부트 전에 실패한다.
3. **현재 보장.**
- 확인한 사실: 카탈로그 5개가 `INSTALLED_PRODUCT_FEATURE_*`만 투영한다(`installed-feature-contracts.ts:23-96`, `installed-feature-adapters.ts:11-47`). 생성기가 선택을 적용한다. 테스트가 매니페스트 import를 확인한다(`product-features.test.ts:175-208`).
- 보장하지 않는 것: 매니페스트 **외의** 값을 카탈로그에 끼우는 것(E3). 틀 밖 요구(홈 교체, 직접 조립 도메인)를 표현하는 방법.
- 기록된 의도: "Adding a feature changes its descriptor and the generated index, not this composer"(`installed-feature-adapters.ts:25-29`), "The central catalogs … do not change"(`starter-experience.md:145-147`).
4. **대안.** (A) 현 상태. (B) 템플릿이 빈 채로 내보내는 제품 소유 파일(예: `src/features/product-composition.ts`) 하나를 카탈로그가 매니페스트와 함께 읽는다. 템플릿은 그 파일을 절대 고치지 않는다. (C) 모든 제품 도메인이 `feature-module.ts`로 들어오게 틀(레이아웃·capability)을 넓힌다(4.2, 4.3).
5. **비용 비교.** (A) 추가 비용 0. 실제 제품은 카탈로그를 고쳐 충돌을 떠안는다(tech-log 5개, memento 1개). (B) 파일 1개 + 가드 테스트 1개. 직접 조립 도메인은 여전히 선택·킬스위치 밖이지만, 그 사실이 파일 이름으로 드러나고 템플릿 파일 충돌이 사라진다. (C) 가장 깨끗하지만 4.2·4.3 작업이 먼저 필요하다. 기존 제품의 이행 비용이 크다(tech-log follow-up 6: 라우터 전체 이동).
6. **현재 조건에서의 판단.** 투영 구조 자체는 유지할 근거가 있다. 기능 2개 이상과 선택 빌드가 테스트로 고정돼 있다(R1). 부족한 것은 틀 밖 요구의 자리다. 단기에는 (B)의 가드 테스트만으로도 조용한 splice를 드러낼 수 있다. 목표는 (C)다.
7. **재검토 조건.** 4.2·4.3 확장 지점이 생겨 두 제품이 모두 `feature-module.ts`로 옮기면 (B)의 제품 소유 파일은 지운다.
### 4.2 `createRuntimeAdapters` 한 함수가 capability 객체와 자격증명 정책을 만든다
1. **무엇이 필요한가.** 기능은 선언한 capability만 받는다. 자격증명은 전송 직전에 scope·세션을 확인하고 실패하면 fetch 0회로 닫힌다.
2. **지킬 성질.** 세션이 없으면 인증 요청을 익명으로 낮추지 않는다. scope가 바뀌는 중에는 보내지 않는다. 프로필이 허용한 헤더만 나간다.
3. **현재 보장.**
- 확인한 사실: capability 객체는 `http`·`telemetry` 두 개다(`runtime-adapters.ts:592-595`). 타입은 `FeaturePlatformCapabilities`라는 닫힌 alias다(`feature-adapter-contribution.ts:46-51`). `attachCredentials`는 scope → 세션 상태 → `credentialPatch` 순서로 판단하고 프로필을 보지 않는다(`runtime-adapters.ts:501-531`). owner에게는 origin·method·operationId만 전달된다(`:513-520`).
- 보장하지 않는 것: `ANONYMOUS` 프로필(09-01). 제품의 추가 capability·세션 밖 자격증명(CSRF 쿠키, BFF)·제품 설정 키.
- 기록된 의도: `indexedDb`는 opt-in이라 제품이 이 객체에 추가한다(`runtime-adapters.ts:586-591`, `starter-experience.md:143`). "The provider is a composition capability; feature use cases never import it"(`feature-adapter-contribution.ts:10-13`).
4. **대안.** (A) 현 상태: 제품이 closure를 고친다. (B) 제품 소유 확장 파일(예: `src/bootstrap/product-composition.ts`, 템플릿은 빈 구현)을 두고, `FeaturePlatformCapabilities`를 `FeatureIndexedDbRepositories`처럼 확장 가능한 interface로 바꾼다. `attachCredentials`는 (1) `ANONYMOUS`면 빈 헤더로 READY, (2) 제품이 프로필 id로 등록한 자격증명 제공자가 있으면 그것, (3) 나머지는 지금의 세션 경로로 나눈다. (C) 기능 계약 기여가 인증 프로필과 자격증명 제공자를 함께 가져온다.
5. **비용 비교.** (A) 템플릿 비용 0. 두 제품이 같은 closure를 고쳤다(memento +61줄, tech-log +118줄). 이 파일은 템플릿이 가장 자주 바꾸는 파일이다(D2 15커밋). fail-closed 코드를 손으로 병합한다. (B) 템플릿 수십 줄 + 분기 테스트. scope·세션 fence는 템플릿에 남고, 제품 코드는 판정만 제공한다. 제품 제공자가 fence를 우회하지 못하게 호출 순서를 템플릿이 쥔다. (C) 가장 유연하지만 인증 정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다.
6. **현재 조건에서의 판단.** 한 함수에서 fence 순서를 쥐는 것은 옳다(39.7: 같은 요청의 상태를 조율해야 한다). 바꿀 것은 확장 방법이다. (B)가 fence 소유를 유지하면서 제품 수정 지점을 템플릿 밖으로 옮긴다.
7. **재검토 조건.** 제품이 요청별 자격증명(예: 테넌트 전환)처럼 fence 순서 자체를 바꿔야 하면 (B)의 제공자 계약을 다시 본다. 제품이 1개로 줄면 (A)의 비용이 작아진다.
### 4.3 모든 context를 `AppShell` 아래에 두고 플랫폼이 홈을 가진다
1. **무엇이 필요한가.** 라우트 경계·청크 복구·not-found 처리를 한 곳에서 준다. 플랫폼 화면(브랜드 링크, not-found 링크)은 기능 없이도 완결돼야 한다.
2. **지킬 성질.** 모르는 URL은 `NOT_FOUND`로 간다. context 라우트는 늦게 읽힌다. 기능을 꺼도 플랫폼 탐색이 사라지지 않는다(`product-features.test.ts:216-219` 주석).
3. **현재 보장.**
- 확인한 사실: 라우터는 `APP_SHELL` 하나 아래에 플랫폼 라우트와 context gateway를 둔다(`app-router.tsx:530-575`). gateway는 context 라우트 중 leaf 하나만 렌더하고, 경로 없는 레이아웃 라우트의 `Component`는 쓰지 않는다(`:500-527`). `APP_HOME`은 플랫폼 소유다(`src/contracts/routes.ts:20-32`). 같은 id는 throw, 다른 id의 `/`는 가려진다(E2, E2b).
- 보장하지 않는 것: 기능/컨텍스트가 자기 레이아웃을 가지는 것, 제품 홈.
- 기록된 의도: "shell, providers, boundaries … remain reusable", "replaceable at the page level"(`starter-experience.md:1-6`, 실행 순서도 `:18`).
4. **대안.** (A) 현 상태. (B) context 선언에 레이아웃을 둔다(예: `context-routes.ts`가 선택적으로 레이아웃 컴포넌트를 내보내고, 라우터는 그런 context를 자기 레이아웃 아래 등록 경로별 자식으로 붙인다). 플랫폼은 "기능이 대신할 수 있는 라우트 id" 목록(`APP_HOME`)을 선언하고, 소유 기능은 최대 하나로 제한한다. memento 브리지가 이 모양이다(제품 `app-router.tsx:548-640`, `installed-feature-contracts.ts:26-61`). (C) `AppShell` 자체를 제품 소유 파일 하나로 교체 가능하게 한다.
5. **비용 비교.** (A) 비용 0. memento는 라우터 +145줄·카탈로그 +32줄 브리지를 가진다. tech-log는 라우터를 통째로 바꿨고 context gateway를 붙이지 않아 생성기 설치 기능을 쓸 수 없다(제품 `app-router.tsx`에 `ContextRouteGateway` 0회, follow-up 7). (B) 템플릿 라우터 수십~백 줄 + gateway·not-found·레이아웃 청크 실패 테스트. 설명자 필드를 형식 있는 계약으로 올린다. 기능을 끈 경우 `/`를 무엇으로 보일지 결정이 필요하다(memento는 현재 `DisabledFeatureSurface`가 된다). (C) 단순하지만 레이아웃 그룹이 둘인 tech-log(PUBLIC/STUDIO)를 표현하지 못한다.
6. **현재 조건에서의 판단.** 단일 셸은 템플릿 데모에는 맞다. 실제 제품 2개가 모두 이 가정을 깼다. (B)가 두 제품의 요구를 모두 담는 가장 작은 공통 형태다. 근거는 memento 브리지가 이미 템플릿 경계·청크 복구를 유지하며 동작한다는 기록(26개 시각 비교 통과, 주장)이다.
7. **재검토 조건.** 세 번째 제품이 레이아웃 외의 라우터 변형(예: 중첩 탭 라우팅)을 요구하면 (B)의 선언 형태를 다시 본다.
## 5. 발견 사항 (36.3)
### 09-01 조립 루트의 자격증명 판단이 인증 프로필을 보지 않아 `ANONYMOUS` operation이 절대 전송되지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 17, 6, 5, 10, 3, 30.5 (HTTP 실행 쪽은 03 영역과 겹침) |
| 근거 | 템플릿은 `ANONYMOUS` 프로필을 설치하고(`src/contracts/rest-profiles.ts:68-74`), `auth: "none"` operation은 이 프로필이어야 한다(`:297`). executor는 모든 operation에서 `attachCredentials`를 부른다(`src/adapters/http/http-execution-v3.ts:719`). 조립 루트 구현은 세션이 `authenticated`가 아니면 `UNAUTHENTICATED`를 돌려준다(`src/bootstrap/runtime-adapters.ts:509-511`). 로그인 상태면 세션의 `authorization` 패치를 그대로 주고, 프로필 허용 목록이 비어 있어 거절된다(`src/adapters/http/http-contract-bridge.ts:80-85`). owner에게 프로필 id가 전달되지 않아 owner가 바로잡을 수도 없다(`runtime-adapters.ts:513-520`). **E1**: 로그아웃 `UNAUTHENTICATED`·fetch 0회, 로그인 `AUTH_INTEGRATION_FAILURE`/`CREDENTIAL_HEADER_NOT_ALLOWED`·fetch 0회. 기존 테스트는 테스트용 `attachCredentials`를 쓰므로(`tests/integration/http-execution-v3-auth-profile.test.ts:115-222`) 조립 루트를 거치지 않는다 |
| 다운스트림 증거 | tech-log가 제품에서 같은 결함을 만나 고쳤다: "falling through below refused every public read before it left the browser. The public site rendered its terminal error surface on every screen"(제품 `src/bootstrap/runtime-adapters.ts:588-598`). memento는 BFF 프로필 id를 세션 확인 앞에서 분기해 피했다(제품 `runtime-adapters.ts:530-545`) |
| 발생 조건 | 제품이 공개 API(`auth: "none"`) operation을 V3 경로로 설치 |
| 영향 | 해당 기능은 어느 세션 상태에서도 요청을 보내지 못한다. 방향은 fail-closed라 정보 노출은 없다. 실패 이유가 "허용되지 않은 자격증명 헤더"라 원인을 찾기 어렵다 |
| 심각도·우선순위 | High · P1 — 템플릿이 지원한다고 설치한 프로필이 기본 조립에서 동작하지 않는다. 공개 화면은 흔한 요구다. 실제 제품 1곳이 모든 공개 화면 실패로 만났다 |
| 통제·증거 | 목표 M3(조립 루트 경유 테스트) / 확인 M0 · E2(E1 실험) + 다운스트림 기록(E0) |
| 확실성과 남은 가정 | 로그아웃·demo 로그인은 재현했다. 외부 owner 로그인은 코드 경로로만 확인했다. 브라우저 화면은 보지 않았다 |
| 결정의 근거 | 적용 제외 — 프로필 계약을 조립 루트가 지키지 않는 구현 결함이다. 확장 구조 선택은 09-02에서 다룬다 |
| 이해 비용 | 원인을 찾으려면 executor·bridge·조립 루트 세 파일을 함께 읽어야 한다 |
| 최소 개선 방향 | `attachCredentials` 첫 판단으로, operation의 프로필 transport가 `ANONYMOUS`면 세션을 보지 않고 `{ kind: "READY", headers: {} }`를 돌려준다(scope fence는 그대로 먼저 확인). tech-log 제품 수정과 같은 모양이다 |
| 대안 비교 | 적용 제외 — 계약이 이미 정해져 있다(`rest-profiles.ts:159-168`: 익명 프로필은 자격증명을 가질 수 없다) |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄. 로그인 상태에서 익명 호출에 토큰이 붙지 않는 것이 의도된 결과다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 실제 `createRuntimeAdapters`로 `ANONYMOUS` operation을 로그아웃·로그인 상태에서 실행하면 fetch 1회, 자격증명 헤더 없음 |
| 검증 방법 | `tests/unit/runtime-adapters.test.ts`에 E1과 같은 케이스(fixture contribution 설치) 추가. 수정 전 코드에서 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-02 제품 capability·자격증명·제품 설정을 넣을 확장 지점이 없어, 두 제품 모두 `runtime-adapters.ts`를 직접 고친다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(다운스트림 diff로 발생 확인) |
| 관련 관점 | 3, 9, 25, 22, 15, 19, 20, 13, 30.3, 30.4, 30.7 |
| 근거 | capability 타입은 닫힌 alias다(`src/features/feature-adapter-contribution.ts:46-51`). 반면 IndexedDB 저장소는 확장 가능한 interface다(`:14`). capability 객체와 자격증명 판단은 637줄 `createRuntimeAdapters` 안 closure다(`src/bootstrap/runtime-adapters.ts:501-531`, `:592-598`). 문서는 이 파일을 `indexedDb`일 때만 고친다고 적는다(`docs/architecture/starter-experience.md:143`). **memento**(`d3810a0`): `FeaturePlatformCapabilities`에 `offsetUpload`·`runtime` 추가(제품 `feature-adapter-contribution.ts:49-55`), `attachCredentials`에 프로필 id 분기(제품 `runtime-adapters.ts:530-545`), capability 객체 확장(`:649-655`), 제품 전송 어댑터를 템플릿 `src/adapters/http/`와 배럴에 추가, `rest-profiles.ts`에 프로필 2개·헤더 이름 1개 추가. **tech-log**(`42d1ae1f`): CSRF 제공자와 전방 참조 stub(제품 `runtime-adapters.ts:531-560`), 자격증명 분기(`:582-598`), capability 확장(`:706-710`), 부트 전에 BFF owner 설치(제품 `create-runtime-composition.ts:47`), 제품 설정 키(제품 `runtime-config-schema.ts:58`, `:156`). 템플릿은 같은 기간 이 파일을 15커밋 고쳤다(D2) |
| 발생 조건 | 제품이 `http`·`telemetry`·`indexedDb` 외 capability, 세션 owner 밖 자격증명(쿠키 CSRF·BFF), 제품 런타임 설정 키 중 하나라도 필요 |
| 영향 | 템플릿 수정(보안·계약 포함, 예: `readSubject` 필수화, 03-03 correlation, 09-05)이 들어오는 파일을 제품이 가장 많이 고친 상태다. 매 동기화에 fail-closed 코드를 손으로 병합한다. tech-log는 이 closure를 고치다 무한 재귀 결함(C1)을 한 번 냈다고 기록한다(제품 `runtime-adapters.ts:496-530` 주석) |
| 심각도·우선순위 | Medium · P1 — 템플릿 자체의 기능 실패는 아니다. 그러나 두 제품 모두에서 발생했고, 템플릿 패치 전파(30.4)라는 핵심 약속을 매번 손 병합으로 만든다. 제품을 더 늘리기 전에 해결할 항목이다 |
| 통제·증거 | 목표 M2(제품 소유 확장 파일 + 가드) / 확인 M0 · E3(실제 다운스트림 diff 2건, D1·D2) |
| 확실성과 남은 가정 | 두 제품의 수정은 diff로 확인했다. "다음 동기화에서도 충돌한다"는 템플릿 변경 빈도로 낸 추정이다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `indexedDb`만 opt-in으로 제품이 추가(`runtime-adapters.ts:586-591`). 리뷰어 추론: fence 순서를 한 함수가 쥐는 것은 맞지만(39.7), 제품 확장 방법이 그 함수의 수정뿐인 것은 30.3("사용자가 실제로 바꾸는 정책은 안정된 수정 지점으로 제공")에 어긋난다 |
| 이해 비용 | 제품 개발자는 capability 하나를 추가하려고 조립 루트 전체(스코프 fence, 세션, 텔레메트리 수명)를 읽어야 한다. 동기화 담당자는 양쪽 변경을 줄 단위로 맞춘다 |
| 최소 개선 방향 | 4.2의 (B). (1) `FeaturePlatformCapabilities`를 확장 가능한 interface로 바꾼다. (2) 템플릿이 빈 구현으로 내보내는 제품 소유 파일 하나(예: `src/bootstrap/product-composition.ts`)가 추가 capability와 "프로필 id → 자격증명 제공자"를 돌려준다. (3) `attachCredentials`는 fence → `ANONYMOUS`(09-01) → 등록 제공자 → 세션 순서를 템플릿이 쥔다. (4) 제품 설정 키는 제품 소유 zod 조각을 strict 스키마에 합치는 방식으로 연다 |
| 대안 비교 | 4.2절. (A) 현 상태: 템플릿 비용 0, 제품당 동기화 비용 반복. (C) 기능 기여가 인증 제공자를 가져옴: 유연하지만 인증 정책이 기능마다 흩어진다 |
| 단순화의 보존 조건 | 인증 요청을 익명으로 낮추지 않는다. scope 전환 중에는 보내지 않는다. 프로필 허용 헤더만 나간다. 제품 제공자가 예외를 던지면 `CREDENTIAL_OWNER_FAILED`로 닫힌다 |
| 비용·부작용 | 템플릿 수십 줄 + 분기 테스트. 두 제품은 한 번 이행해야 한다(제품 코드를 새 파일로 옮김) |
| 재검토 조건 | 제품이 fence 순서 자체를 바꿔야 하는 요구(요청별 테넌트 전환 등)가 생기면 제공자 계약을 다시 본다 |
| 완료 기준 | 두 제품의 현재 요구(offsetUpload, runtime 값, BFF 쿠키 XSRF, Studio CSRF, 제품 설정 키)를 템플릿 파일 수정 없이 표현할 수 있다. 템플릿 픽스처 제품이 그 경로를 한 번 쓴다 |
| 검증 방법 | 픽스처 제품 파일로 capability 1개·프로필 제공자 1개를 추가하고 `check:types`·`runtime-adapters` 테스트 통과. 제공자가 fence 전에 호출되지 않는지 순서 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-03 라우터 조립이 `AppShell` 한 틀과 플랫폼 홈을 고정해, 기능이 `/`나 자기 레이아웃을 가질 수 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(다운스트림 diff로 발생 확인) + 확인된 결함(기능의 `/` 라우트가 조용히 가려짐) |
| 관련 관점 | 3, 2, 22, 25, 8, 23, 27, 32.4, 30.3 |
| 근거 | (a) 홈: `APP_HOME`은 플랫폼 소유다(`src/contracts/routes.ts:20-32`). 같은 id를 기능이 선언하면 `composeUniqueRecord`가 throw한다(`src/platform/cardinality/compose-unique-record.ts:16-18`, E2(가)). 다른 id로 `/`를 선언하면 오류 없이 두 라우트가 공존하고, 라우터는 플랫폼 index를 고른다(E2(나), E2b). 경로 중복 검사는 어디에도 없다. (b) 레이아웃: 라우터는 모든 context를 `APP_SHELL` 아래에 붙인다(`src/presentation/routes/app-router.tsx:530-575`). gateway는 leaf만 렌더하고 context 라우트 모듈의 레이아웃 `Component`를 쓰지 않는다(`:500-527`). 기능 런타임 설명자는 `unknown`이라 레이아웃 선언 계약이 없다(`src/features/feature-module.ts:34-38`, `:63-70`). **memento**: `APP_HOME` 허용 목록(제품 `installed-feature-contracts.ts:26-61`), 설명자의 형식 없는 `ownsShell` 필드와 라우터 브리지(제품 `app-router.tsx:548-640`, `memento-feature-runtime-descriptor.ts`), 템플릿 테스트 2개 수정. **tech-log**: 라우터를 PUBLIC/STUDIO 그룹 라우터로 교체했고 `ContextRouteGateway`를 붙이지 않는다(제품 `app-router.tsx`에서 0회, 기록 follow-up 7) |
| 발생 조건 | 제품 홈이 기능 화면이거나, 기능 화면이 `AppShell`이 아닌 자기 레이아웃을 쓴다. 두 제품 모두 해당 |
| 영향 | (1) 제품마다 템플릿 라우터·조립 카탈로그에 브리지를 넣고 동기화마다 병합한다(`app-router.tsx` 11커밋). (2) tech-log에서는 템플릿의 기능 설치 경로(context gateway)가 꺼져 생성기 설치 기능을 쓸 수 없다. (3) memento는 `APP_HOME`을 기능 소유로 바꿔 "기능을 꺼도 플랫폼 탐색은 남는다"는 템플릿 불변식을 제품에서 깼다(제품 `product-features.test.ts` 수정). (4) 기능이 다른 id로 `/`를 선언한 실수는 아무 신호 없이 화면에서 사라진다 |
| 심각도·우선순위 | Medium · P1 — 템플릿 자체의 기능 실패는 아니다. 두 제품 모두에서 발생했고, 한 제품에서는 템플릿의 주 확장 모델을 끄는 결과가 됐다 |
| 통제·증거 | 목표 M3(선언 + 조립 검증) / 확인 홈 교체 M0, 경로 충돌 M0, 레이아웃 M0 · E2(E2·E2b) + E3(다운스트림 diff 2건) |
| 확실성과 남은 가정 | 조립·매칭 동작은 실험으로 확인했다. memento 브리지가 브라우저에서 동작한다는 것은 제품 기록의 주장(시각 비교 26개 통과)이다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 셸·경계는 재사용, 페이지 수준에서 교체(`starter-experience.md:1-6`). 리뷰어 추론: "페이지 교체"로는 홈 소유와 레이아웃을 표현하지 못한다. 두 제품이 같은 두 요구를 냈다 |
| 이해 비용 | 제품 개발자는 라우터 내부(gateway 매칭, 플랫폼 index 우선순위)를 알아야 브리지를 만들 수 있다. memento 브리지는 약 100줄의 새 규약이다 |
| 최소 개선 방향 | 4.3의 (B). (1) 플랫폼이 "기능이 대신할 수 있는 라우트 id" 목록(`APP_HOME`)을 선언하고, 소유 기능은 최대 하나, 소유 기능이 꺼지면 플랫폼 홈으로 돌아간다. (2) context가 선택적 레이아웃을 선언하면(예: `context-routes.ts`의 레이아웃 export 또는 context 선언 리터럴) 라우터가 그 context를 자기 레이아웃 아래 등록 경로별 자식으로 붙인다. 모르는 URL은 여전히 `AppShell`의 `NOT_FOUND`로 간다. (3) 조립 시 라우트 경로 중복을 검사한다 |
| 대안 비교 | 4.3절. (A) 현 상태: 제품마다 브리지. (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 제품을 못 담는다 |
| 단순화의 보존 조건 | context 라우트는 늦게 읽힌다. gateway의 경계·청크 복구·not-found 처리가 레이아웃 context에도 적용된다. 플랫폼 라우트는 기능을 꺼도 남는다 |
| 비용·부작용 | 라우터 수십~백 줄, 테스트(레이아웃 청크 실패, not-found 통과, 홈 소유 기능 비활성화). 레이아웃 청크가 페이지 청크보다 먼저 한 번 더 내려온다(memento 기록: 약 17KB) |
| 재검토 조건 | 세 번째 제품이 레이아웃 외 라우터 변형을 요구하면 선언 형태를 다시 본다 |
| 완료 기준 | memento의 두 브리지와 tech-log의 PUBLIC/STUDIO 구성을 템플릿 라우터 수정 없이 선언으로 표현할 수 있다. 다른 id의 `/` 중복은 조립 단계에서 실패한다 |
| 검증 방법 | 픽스처 context 2개(자기 레이아웃, `APP_HOME` 대체)를 설치한 컴포넌트 테스트. 경로 중복 픽스처가 부트 전에 실패하는지 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-04 생성기 밖에서 조립하는 제품 도메인의 공식 경로가 없고, `NOT_INSTALLED` 표시와 조립 파일 직접 수정을 아무 검사도 구분하지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 2, 21, 24, 27, 4, 9, 30.7 |
| 근거 | 생성기는 `NOT_INSTALLED` 파일의 **존재만** 본다. 내용은 읽지 않는다. `feature-module.ts`가 있으면 표시를 무시하고 설치한다(`scripts/generate-product-feature-index.ts:283-294`). 같은 이름이 런타임 상태 "선언됐지만 선택 안 됨"으로도 쓰인다(`src/contracts/product-features.ts:32`, `:122`). 표시한 디렉터리는 선언되지 않으므로 그 상태로 보고되는 일이 없다. 조립 파일·부트스트랩이 기능 내부를 import하는 것을 막는 의존성 규칙이 없다(`.dependency-cruiser.json`). "모든 카탈로그가 매니페스트를 참조" 테스트는 import 존재만 본다(`tests/unit/product-features.test.ts:175-208`). 설치 표면 테스트는 `REFERENCE_*` 이름만 본다(`tests/features/feature-installation-surface.test.ts:3-6`). **E3**: `NOT_INSTALLED` 디렉터리에서 값을 가져와 `ROUTE_REGISTRY`에 끼운 변이가 테스트 19개와 `check:architecture`를 모두 통과했다. **tech-log**: TechLog에 `NOT_INSTALLED`를 두고 "설치 안 됨이 아니라 직접 조립"이라고 적었다(제품 `src/features/tech-log/NOT_INSTALLED`). 조립 파일 5개를 고치고(예: 제품 `installed-feature-adapters.ts:59`), 템플릿 테스트 3개를 TechLog 예외로 고쳤다(`product-feature-selection-build.test.ts`, `installed-feature-messages.test.ts`, `product-features.test.ts`) |
| 발생 조건 | 제품 도메인이 템플릿 틀(09-02, 09-03)에 안 맞아 생성기 밖에서 조립 |
| 영향 | 그 도메인은 `VITE_PRODUCT_FEATURES`, `FEATURE_OVERRIDES`, 플랫폼 개요의 기능 목록, `test:sample-removal`의 적용을 받지 않는다. 이 사실이 코드 경계가 아니라 표시 파일의 자연어 설명에만 남는다. 누군가 실수로 조립 파일에 기능을 직접 끼워도 같은 이유로 검출되지 않는다 |
| 심각도·우선순위 | Medium · P2 — 원인의 큰 부분은 09-02·09-03이다. 이 항목은 "우회 경로의 이름과 검출"만 다룬다. 두 원인이 해결되면 필요성이 줄어든다 |
| 통제·증거 | 목표 M3(직접 조립 검출) / 확인 M0 · E2(E3 변이) + E3(tech-log diff) |
| 확실성과 남은 가정 | 변이 생존은 재현했다. `check:registries`·`test:sample-removal`에서 잡히는지는 돌리지 않았다(라우트 레지스트리 경로라 잡히지 않을 것으로 추론) |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 표시는 "not a product feature"인 아키텍처 샘플용(`src/features/local-draft-feature/NOT_INSTALLED`, `starter-experience.md:104-106`의 "the one intentional example"). 리뷰어 추론: 제품이 졸업(30.7)할 공식 경로가 없어 샘플용 표시가 우회로로 쓰였다 |
| 이해 비용 | 새 담당자는 `NOT_INSTALLED`를 볼 때마다 파일 내용과 조립 파일을 함께 읽어야 뜻을 안다 |
| 최소 개선 방향 | (1) 조립 파일(`src/features/installed-*`)과 `src/bootstrap/`가 `src/features/<x>/`를 직접 import하지 못하게 의존성 규칙을 추가하고, 허용할 곳은 4.1의 제품 소유 조립 파일 하나로 둔다. (2) 표시 이름을 뜻대로 나눈다(예: 샘플은 `NOT_A_FEATURE`, 직접 조립은 제품 소유 조립 파일에 선언). (3) `feature-module.ts`와 표시가 함께 있으면 생성기가 실패한다 |
| 대안 비교 | 4.1절. (A) 현 상태. (B) 제품 소유 조립 파일 + 가드. (C) 모든 도메인을 `feature-module.ts`로(09-02·09-03 선행) |
| 단순화의 보존 조건 | 생성기 설치 기능의 선택·킬스위치·제거 검증은 그대로다. 표시 없는 디렉터리는 계속 실패한다 |
| 비용·부작용 | 규칙 1개, 생성기 몇 줄, tech-log 이행(조립 코드를 제품 소유 파일로 옮김) |
| 재검토 조건 | 모든 제품 도메인이 `feature-module.ts`로 옮겨지면 제품 소유 조립 파일과 그 예외 규칙을 지운다 |
| 완료 기준 | E3 변이가 `check:architecture`에서 실패한다. 직접 조립 도메인이 파일 경계로 드러난다 |
| 검증 방법 | E3 변이를 다시 적용해 실패 확인. 표시 + `feature-module.ts` 동시 존재 픽스처로 생성기 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 09-05 제품이 고치도록 설계한 선택 파일에 템플릿 상태 설명이 같은 블록으로 섞여 있다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 9, 25, 30.3 |
| 근거 | `installed-runtime-capabilities.ts`는 "Adding an entry here is what installs a capability"라며 제품 수정 지점으로 설계됐다(`src/features/installed-runtime-capabilities.ts:15-20`). 같은 블록의 주석이 "Current template state"를 설명하고(`:22-33`), 바로 아래 상수가 제품 선택이다(`:35-41`). memento는 상수와 주석을 함께 고쳤다(SW `ACTIVE`) |
| 발생 조건 | 템플릿이 선택 설명 주석이나 기본값을 고침 |
| 영향 | 제품이 의도대로 쓴 파일인데도 동기화에서 주석 충돌이 난다. 영향은 작다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M1 / 확인 M1 · E3(memento diff) |
| 확실성과 남은 가정 | 이번 동기화에서 이 파일은 템플릿 변경이 0이라 실제 충돌은 없었다 |
| 결정의 근거 | 적용 제외 — 파일 배치의 작은 정리다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 템플릿 상태 설명을 문서(`optional-adapter-recipes.md`)로 옮기고, 파일에는 "이 상수는 제품이 소유한다" 한 줄만 둔다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 주석 이동 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 제품이 상수만 바꿔도 되고 템플릿 설명 변경과 줄이 겹치지 않는다 |
| 검증 방법 | 문서 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. 다음 동기화에서 충돌이 반복될 파일 (25, 9)
기준: `af3d8e6` 대비 제품이 고친 파일(D1)과 `ebea300..af3d8e6`에서 템플릿이 고친 횟수(D2). 이번 동기화에서 실제 충돌 경로는 memento 25개, tech-log 67개였다(두 기록의 "Conflicts" 절).
| 파일 | 고친 제품 | 제품이 고친 이유 | 템플릿 변경(커밋) | 원인 발견 |
|---|---|---|---|---|
| `src/bootstrap/runtime-adapters.ts` | 둘 다 | 제품 capability(`offsetUpload`, `runtime`, `studioSource`, `csrf`), 프로필별 자격증명(BFF 쿠키 XSRF, Studio CSRF), `ANONYMOUS` 우회 | 15 | 09-01, 09-02 |
| `src/presentation/routes/app-router.tsx` | 둘 다 | memento 셸 브리지, tech-log PUBLIC/STUDIO 라우터 전체 교체 | 11 | 09-03 |
| `src/features/installed-feature-contracts.ts` | 둘 다 | memento `APP_HOME` 허용 목록, tech-log 라우트·스키마 직접 조립 | 3 | 09-03, 09-04 |
| `src/contracts/rest-profiles.ts` | 둘 다 | 제품 인증 프로필·자격증명 헤더 이름 추가 | 3 | 09-02 (레지스트리 자체는 07 영역) |
| `src/features/feature-adapter-contribution.ts` | memento | 닫힌 `FeaturePlatformCapabilities`에 capability 추가 | 3 | 09-02 |
| `src/features/installed-{feature-adapters,contract-contributions,feature-messages}.ts`, `installed-feature-runtimes.tsx` | tech-log | 생성기 밖 도메인을 직접 조립 | 1~3 | 09-04 |
| `src/bootstrap/create-runtime-composition.ts` | tech-log | 번들 안에서 BFF 세션 owner 설치 | 1 | 09-02 |
| `src/bootstrap/runtime-config-schema.ts` (+ `src/contracts/release-artifacts.ts`) | tech-log | 제품 런타임 설정 키 | 1 (+3) | 09-02 |
| `src/features/installed-runtime-capabilities.ts` | memento | 설계된 수정 지점(SW `ACTIVE`). 템플릿 설명 주석과 제품 상수가 한 블록에 있다 | 0 | 09-05 |
| `src/bootstrap/main.tsx` | tech-log | 제품 폰트·스타일시트 import | 2 | > 08 영역(스타일 등록 지점) |
| `src/application/view-models/async-state.ts` | tech-log | `data: null`을 데이터로 취급하도록 의미 변경 | 0 | 발견 아님(제품 선택). 다만 템플릿 수정 시 조용히 갈라진다 |
| 템플릿 테스트: `tests/unit/product-features.test.ts`, `product-feature-selection-build.test.ts`, `installed-feature-messages.test.ts`, `tests/component/router.test.tsx`, `product-feature-switch.test.tsx`, `runtime-application.test.tsx` | 둘 다(일부) | 템플릿 홈·라우트 id·"모든 기능은 생성 인덱스에서"를 고정한 테스트를 제품 내용으로 다시 겨눔 | 2~6 | 09-03, 09-04 (테스트 설계는 10 영역) |
반복 원인은 셋이다.
1. 틀 밖 요구(홈, 레이아웃, capability, 자격증명, 제품 설정)를 표현할 제품 소유 자리가 없다. 제품은 템플릿이 가장 자주 바꾸는 파일에 코드를 넣는다.
2. 한 파일에 템플릿 설명과 제품 선택이 섞여 있다(`installed-runtime-capabilities.ts`).
3. 템플릿 테스트가 템플릿 콘텐츠(홈 h1, `EXAMPLES_*` 라우트 id)를 기대값으로 쓴다. 제품은 테스트를 고쳐야 게이트를 통과한다.
## 7. FOLLOW-UP 재확인
`docs/reviews/2026-09-25-maturity-review/FOLLOW-UP.md` 중 이 영역에 걸린 항목과, 이전 라운드 09-01~09-12의 회귀 여부다.
| 항목 | 현재 코드 | 결과 |
|---|---|---|
| FOLLOW-UP 4절 P3 09-07: 기능 제거 검증이 lint·`check:i18n`·e2e를 건너뜀 | 제거 검증 항목은 typecheck·architecture·registries·test:all·coverage·test-evidence-source·check:ci·home-smoke·build뿐이다(`scripts/test-sample-removal.ts:415-428`) | 유효 |
| FOLLOW-UP 4절 P3 09-08: local-draft ABA를 주석으로 닫음 | 주석만 있고 코드 강제는 없다(`src/features/local-draft-feature/domain/local-draft.ts:2-11`) | 유효(리뷰가 허용한 대안 그대로) |
| FOLLOW-UP 2절 P2 `readSubject` 필수화 이행 안내를 README 업데이트 절에 한 줄 | `starter-experience.md:69-74`에 Migration 문단, `CHANGELOG.md:43`에 [계약] 행이 있다. README "Updating a copied project"(`README.md:315-356`)에는 없다. tech-log는 CHANGELOG로 이 변경을 찾아 제품 owner에 `readSubject`를 추가했다(기록 "Fixes the transplant required") | 유효(README 한 줄 없음). 문서 쪽 판정은 14 영역 |
| FOLLOW-UP 1절 P1 초기 JS 예산 | 설치 기능의 계약·메시지·설명자가 eager로 초기 그래프에 들어가는 구조는 그대로다(`installed-*`가 생성 인덱스를 정적 import) | 판단 불가 — 수치는 13 영역에서 측정 |
| FOLLOW-UP 3절 P1 `tests/component/runtime-application.test.tsx` 부하 flaky | memento 기록도 같은 파일이 부하 중 한 번 실패했고 대기 시간을 5초로 늘렸다고 적는다. 템플릿 파일은 바뀌지 않았다 | 판단 불가 — 10 영역 |
| 이전 09-01 기능 2개 설치 시 타입 실패 | `tests/unit/two-feature-install-typecheck.test.ts` 통과(R1) | 해소 |
| 이전 09-02 `VITE_PRODUCT_FEATURES` 소비자별 불일치 | 생성기가 선택을 적용(`generate-product-feature-index.ts:181-239`), `product-feature-selection-build.test.ts` 통과(R1) | 해소 |
| 이전 09-03·09-04 부트 실패 경로 | `main.tsx:14-17` 동적 import, `render-boot-failure.tsx:25-28` `BOOT_UNEXPECTED_FAILURE` | 해소 |
| 이전 09-05 `needs` 미검사 | `feature-adapter-contribution.ts:177-190`, `feature-adapter-composition.test.ts` 통과(R1). 단, `indexedDb` 추가 방법은 여전히 `runtime-adapters.ts` 수정이다(09-02로 이어 적음) | 해소 |
| 이전 09-06 local-draft 도메인 규칙 미적용 | `local-draft-api.ts:69-73` | 해소 |
| 이전 09-07 중앙 정책 파일·제거 일반화 | 생성기 표시 규칙(`:262-297`), 레지스트리 거버넌스 glob(`config/contracts/registry-governance.json:195-198`, `:235-238`), `--feature=`(`test-sample-removal.ts:29-38`). 템플릿 fixture 기준 완료 기준은 충족한다. 실제 제품 2개는 조립 파일을 여전히 고쳤다(09-02~09-04로 이어 적음) | 해소(템플릿 fixture 기준) |
| 이전 09-09 override 오타 무진단 | `runtime-adapters.ts:462-471` | 해소 |
| 이전 09-10 부트 실패 재시도 | `boot-error-shell.tsx:24-38` | 해소 |
| 이전 09-11 `tests/features` 최상위 테스트 미실행 | `test:coverage`가 `tests/features` 전체를 포함(`package.json:81`) | 해소 |
| 이전 09-12 local-draft fixture 복사본 | `tests/contract/consumer-experience/fixtures/` 없음 | 해소 |
## 8. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 09-01의 실제 브라우저 화면과 외부 owner 로그인 경로 | vitest로 조립 루트만 실행했다 | `ANONYMOUS` operation을 가진 픽스처 기능으로 빌드해 Playwright로 로그아웃·로그인 상태 확인 |
| 09-02·09-03 제안이 실제 동기화 충돌을 줄이는지 | 설계 제안이다 | 확장 지점을 만든 뒤 두 제품 브랜치에 한 번 이식하고, 템플릿 파일 diff가 0이 되는지 확인 |
| 다음 동기화의 충돌 수 | 미래 사건이다 | 다음 동기화 기록의 충돌 경로 수를 이번(25, 67)과 비교 |
| E3 변이가 `check:registries`·`test:sample-removal`에서 잡히는지 | 무거운 검사라 돌리지 않았다 | 같은 변이로 두 명령 실행 |
| 기능 수에 따른 초기 JS·부트 시간 | 13 영역 측정 범위 | `config/scale/feature-shape-growth.json` 갱신 측정 |
| memento 셸 브리지의 브라우저 동작 | 제품 기록(시각 비교 26개 통과)만 있다 | memento 브랜치에서 legacy parity 스위트 실행 |
@@ -0,0 +1,345 @@
# 10 테스트 — 빠른 계층 성숙도 리뷰 (2026-09-29)
> 기준: `main` / `af3d8e6` (태그 `v0.2.0` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 체크리스트: `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능**. 개발 장비와 4코어 러너 조건에서는 빠른 계층이 믿을 만하다. 2코어 러너에서는 머지 게이트가 코드와 무관하게 떨어진다(10-01). CI를 켜기(U-1) 전에 10-01을 고친다.
## 요약
- **검출력은 좋아졌다.** 변이 12종 중 11종을 테스트가 잡았다. 지난 라운드에서 살아남던 7종(01-04, 02-02, 02-08, 04-06, 06-04, 07-04, 07-05)과 10-03(M1b)이 모두 이제 잡힌다. 새로 넣은 고위험 변이 4종 중 3종도 잡혔다. 살아남은 1종은 상위 계층이 같은 검사를 다시 하는 방어선이다(10-04).
- **부하 의존 테스트를 재현했다(10-01, Medium, P1).** 2코어로 묶고 worker 4개로 돌리면 FOLLOW-UP 3절의 세 테스트가 모두 실패했다(5회 중 3회, 회당 1건). `router.test.tsx`(3회 중 1회)와 `extreme-scale-registry.test.ts`(FE-GATE-005 재현 1회 중 1회)도 새로 실패했다. 원인은 셋이다. 지연 로딩 화면을 1초 기본값으로 기다린다. 자식 프로세스 기동 시간을 실제 시계 마감(350ms~3s)에 포함한다. 머지 게이트 안에 절대 시간 예산(1,500ms)이 있다.
- **`http-execution-v3-live-authority`의 실패는 환경 탓이 아니다(10-03, Low, P2).** 실행기가 마감 시각을 두 번 읽는다. 그 사이에 마감이 지나면 시간 초과가 `CONTRACT_VIOLATION`(`FINAL_REQUEST_INVARIANT_FAILED`)으로 보고되고, 화면에는 재시도 없는 `VALIDATION_REJECTED`로 간다. 주입한 시계로 결정적으로 재현했다. 테스트의 마감을 늘려 "고치면" 결함을 숨긴다.
- **플랫폼 테스트가 제품이 바꿀 콘텐츠를 대상으로 쓴다(10-02, Medium, P2).** 경계·라우터 테스트는 스타터 화면(`/`, `/examples/states`, `/examples/ui`)에 묶여 있다. 두 제품이 이번 동기화에서 이 테스트들을 옮기거나 고쳤다(tech-log 7파일, memento 9개 이상). 참조 샘플을 지우면 HTTP 실패 시나리오 카탈로그, 그 증거 게이트, 타입 음성 fixture 8개가 함께 지워진다.
- 게이트 소속(12-04 수정)은 지켜지고 있다. 테스트 파일 327개 중 321개가 게이트 명령에 속하고, 6개는 `config/ci/ungated-tests.json`에 있다. 깨끗한 체크아웃에서 빠른 계층이 통과한다(10-01 지난 수정 유지).
## 0. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 영역·경로 | `tests/unit`(173파일 약 68k줄), `tests/component`(35파일 6.6k줄), `tests/integration`(13파일 4.6k줄), `tests/contract`(3), `tests/runtime-schema`(3), `tests/features`(20), `tests/platform`(29), `tests/recipes`(3), `tests/helpers`(8), `tests/mocks`(5), `tests/support`(1), `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts` |
| 커밋·상태 | `main` `af3d8e6`. 코드는 이 커밋과 같다. 주 워킹트리에서 쓴 파일은 이 문서 하나다 |
| 전제 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. 빠른 계층은 Vitest 4.1.10, Node 24.14.0. 스타터 화면은 "페이지 단위로 교체 가능"하다고 선언돼 있다(`docs/architecture/starter-experience.md:3-6`). 참조 샘플은 제거 가능하다고 선언돼 있다(`README.md:85`, `:205-209`) |
| 읽은 코드·설정 | `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts` 전체. `scripts/lib/ungated-tests.ts` 전체, `config/ci/ungated-tests.json`, `config/ci/gates.json`의 테스트 명령, `package.json` 테스트 스크립트. FOLLOW-UP 3절 테스트 4개 파일 전체와 그 대상 코드(`src/adapters/http/http-execution-v3.ts:440-945`, `http-contract-bridge.ts:344-410`, `feature-http-binding.ts:405-475`, `scripts/lib/provider-guardian-client.ts`, `provider-guardian-protocol.ts:80-95`). `scripts/test-sample-removal.ts:1-300`. 스타터 화면을 쓰는 component 테스트 8개. `tests/helpers/fixture-feature.tsx` |
| 읽은 문서(주장으로만) | `docs/testing/taxonomy.md`, `docs/testing/frontend-platform-testing-strategy.md` 16.5절, `docs/architecture/starter-experience.md`, 지난 리뷰 `10-*.md`·README 11절·FOLLOW-UP |
| 실행한 명령 | 분리 worktree(`git worktree add --detach .../10/wt af3d8e6`, 메인 `node_modules` 심볼릭 링크)에서 `node scripts/run-vitest.ts`와 `node_modules/.bin/tsc`만 썼다. pnpm은 쓰지 않았다. 메인 `node_modules`는 그대로다(`.modules.yaml`·`.pnpm/lock.yaml` 수정 시각 16:26, 작업 시작 전) |
| 실험 | P1 부하 재현(`taskset`으로 CPU 제한, 아래 표). P2 변이 12종(`vitest related <파일> --run`, 07-05는 `tsc -p`). P3 마감 경계 탐침(주입 시계). P4 참조 샘플 테스트 유무에 따른 HTTP 모듈 커버리지 비교. P5 게이트 소속 전수 대조. 실험 파일은 scratchpad `review-2026-09-29/10/`에 있다. worktree는 끝난 뒤 지웠다 |
| 제품 repo 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`을 `git show`로만 읽었다 |
| 확인하지 못한 범위 | 실제 Gitea 러너(U-1), 1코어·저메모리 러너, jsdom과 실제 브라우저 차이(11 영역), 모듈별 테스트의 세부 검출력(01~09 영역) |
| 지난 리뷰와 비교 | 지난 결과는 증거로 쓰지 않았다. 10-01~10-07의 수정은 현재 코드와 실행으로 다시 확인했다(6절) |
부하 재현 조건(P1). 호스트는 22코어다. 다른 영역 에이전트가 함께 돌아 부하 평균이 8~23이었다. CPU 제한은 `taskset`으로 걸었다. 다른 에이전트에 부하를 더하지 않으려고 부하 발생기는 쓰지 않았다.
| 실험 | 조건 | 결과 |
|---|---|---|
| 기준 | 대상 5파일(75개), 제한 없음 / 4·2·1코어 | 모두 통과. 파일이 적으면 코어를 줄여도 경쟁이 생기지 않는다 |
| A | `tests/component`, 2코어, `--maxWorkers=4` × 3회 | 1회 실패: `router.test.tsx` 2개("플랫폼 구성", "UI 구성요소" heading 못 찾음) |
| B | `tests/component tests/features tests/integration`, 2코어, `--maxWorkers=4` × 5회 | 3회 실패, 회당 1개: `http-execution-v3-live-authority`(TRANSPORT_FAILURE 대신 CONTRACT_VIOLATION), `provider-guardian-transaction`("deadline guardian READY timed out"), `runtime-application`("Clean Architecture Frontend" heading 못 찾음) |
| C1 | FE-GATE-005 `test:coverage`의 Vitest 단계와 같은 경로·`--coverage --maxWorkers=4`, 4코어 | 277파일 3,164개 통과, 111s |
| C2 | C1과 같음, 2코어 | 1개 실패: `extreme-scale-registry.test.ts` "expected 1531.2 to be less than 1500". 169s |
변이 실험(P2). 원본은 실험마다 복원했다.
| ID | 규칙(출처) | 바꾼 곳 | 결과 | 잡은 테스트 |
|---|---|---|---|---|
| A | 부분 업로드 멱등 키 고정(01-04) | `upload-byte-source.ts:301` 뒤에 `String(Math.random())` 추가 | 잡힘(2) | `resumable-upload-runtime-recovery.test.ts` |
| C | Cache Storage 익명 요청(02-02) | `public-cache-response-validation.ts:232` `omit`→`include` | 잡힘(1) | `public-response-cache.test.ts` |
| D | 교차 출처 handoff 거부(02-08) | `download-input-validation.ts:346` 조건 제거 | 잡힘(1) | `browser-file-download.test.ts` |
| E | SSE idle timeout 재시도 가능(04-06) | `fetch-sse-connection.ts:394` `true`→`false` | 잡힘(2) | `realtime/fetch-sse-connection.test.ts` |
| F | 런타임 kill switch unregister(06-04) | `service-worker-page-controller.ts:117` 분기 끔 | 잡힘(2) | `service-worker-runtime.test.ts` |
| G | 결과 불명 실패는 재시도 불가(07-04) | `errors.ts:167` `MAYBE_APPLIED` 조건 제거 | 잡힘(1 / 817) | `error-classification.test.ts` |
| H | 진단 fixture 위반별 고정(07-05) | `telemetry-port.ts:7` `eventName: string` | 잡힘 | `tsc -p tests/fixtures/typecheck/tsconfig.diagnostics-port.json` → TS2578, exit 1(게이트는 pass 기대) |
| I | V3 실행기가 계약의 재시도 의미를 씀(10-03 M1b) | `http-execution-v3.ts:976` `"SAFE"` 고정 | 잡힘(1 / 631) | `http-execution-v3.test.ts` "does not replay a dispatched KEYED send even with budget left" |
| J | 결과 불명 재전송은 같은 키(03-01, 신규) | `application-query.ts:538` `replayed?.intent ??` 제거 | 잡힘(4) | `application-mutation-admission.test.tsx` 2, `reference-page.test.tsx` 1, `reference-production-vertical.test.tsx` 1 |
| K | 오래된 scope의 성공 응답 폐기(§10.8, 신규) | `http-execution-v3.ts:1377` 검사 끔 | **살아남음(0 / 631, 84파일)** | 없음 — 10-04 |
| L | 자격 증명 소유자 장애는 로그아웃 사유가 아님(LIVE-01, 신규) | `http-execution-v3.ts:770` UNAVAILABLE → `unauthenticated` | 잡힘(1) | `http-execution-v3-live-authority.test.ts` |
| N | 로컬 초기화는 캐시를 비움(로그아웃, 신규) | `tanstack-cache-coordinator.ts:257` `clear()` 제거 | 잡힘(2) | `tanstack-cache-coordinator.test.ts` |
## 1. 대표 흐름 (체크리스트 2절)
### 1.1 정상 흐름 — 개발자가 파일 하나를 돌리고, CI가 계층 전체를 돌린다
```text
node scripts/run-vitest.ts run <file>
→ Node 24.11 이상 확인, NODE_ENV=test, npm 전역 설정 제거 (scripts/run-vitest.ts:5-49)
→ src/.generated 생성 (scripts/run-vitest.ts:51-61)
→ vitest.config.ts: tests/**/*.test.{ts,tsx}만 수집, tests/system은 이름을 줄 때만 (vitest.config.ts:10-37)
→ tests/setup.ts: afterEach에서 cleanup + useRealTimers (tests/setup.ts:5-11)
→ 테스트 실행 (testTimeout 10s, retry 0)
→ 실패: 종료 코드 1, junit 파일(artifacts/tests/*.xml)
→ CI: run-ci-gate가 FE-GATE-004~007 명령을 차례로 실행 (config/ci/gates.json)
```
- 입력: 파일 경로 또는 계층 디렉터리.
- 정책: 수집 범위, 시간 제한, mock 초기화(`restoreMocks`·`clearMocks`·`mockReset`).
- 상태 변화: `src/.generated/`, `artifacts/tests/`.
- 외부 I/O: 없음(MSW 서버는 처리되지 않은 요청을 실패로 만든다, `tests/mocks/server.ts:8`).
- 실패: 테스트 실패는 그대로 드러난다. 재시도로 숨기지 않는다.
- 결과: 새 worktree에서 이 경로가 그대로 동작했다(P1·P2 전부 이 경로).
### 1.2 피해가 큰 흐름 — 작은 CI 러너에서 머지 게이트가 무작위로 떨어진다
```text
PR → FE-GATE-005: test:coverage (V8 계측, --maxWorkers=4)
→ 2 vCPU 러너: worker 4개가 CPU 2개를 나눠 씀
→ (a) lazy route가 1초 안에 안 뜸 → "Unable to find role=heading"
(b) guardian 자식 프로세스가 350ms 안에 안 뜸 → guardian이 만료된 guard를 거부 → "READY timed out"
(c) 1M 조회가 1,500ms를 넘음 → "expected 1531 to be less than 1500"
(d) 5ms 마감이 두 번의 시계 읽기 사이에 지나감 → CONTRACT_VIOLATION
→ 게이트 실패 → 머지 차단
```
- 입력: 코드 변경과 무관하다.
- 정책: 테스트가 실행 속도를 가정한다. 재시도는 없다(좋은 선택이다).
- 결과: (a)~(c)는 거짓 실패다. 실패 문구가 "화면에 제목이 없다", "READY 시간 초과"라서 원인이 속도라는 것을 가린다. (d)는 진짜 결함을 드문 조건에서만 드러낸다(10-03). 팀이 "다시 돌리면 된다"를 배우면 (d) 같은 진짜 신호도 무시된다.
- 파일: `tests/component/runtime-application.test.tsx:64-68`, `tests/component/router.test.tsx:74-79`, `:100-106`, `tests/integration/provider-guardian-transaction.test.ts:704`, `:727-730`, `:619-653`, `tests/platform/cardinality/extreme-scale-registry.test.ts:20`, `:78`, `tests/integration/http-execution-v3-live-authority.test.ts:357-380`.
### 1.3 변경·삭제 흐름 — 제품이 홈 화면을 바꾸고 참조 샘플을 지운다
```text
제품이 "/" 와 /examples/* 를 자기 화면으로 교체
→ 플랫폼 경계 테스트가 템플릿 화면을 기다림
(runtime-application: h1 "Clean Architecture Frontend", chunk-recovery·render-boundary: /examples/states,
router: 홈의 "플랫폼 구성 보기" 링크, route-status-surfaces: 홈 h1)
→ 테스트 실패 → 제품이 테스트를 자기 화면으로 옮김 (tech-log 7파일, memento 9개 이상)
→ 다음 템플릿 동기화 때 같은 파일이 다시 충돌
제품이 참조 샘플 제거 (scripts/test-sample-removal.ts의 절차)
→ SAMPLE_EXTRAS가 플랫폼 검사도 함께 지움:
tests/integration/http-scenario-catalog.test.ts + tests/mocks (HTTP 실패 시나리오 19개 × 3)
test:http-scenario-evidence (FE-GATE-007의 명령)
tests/component/product-feature-switch.test.tsx
타입 음성 fixture 8개와 check:types:fixture:* 8개 (FE-GATE-003)
→ test:sample-removal은 통과 → 제품은 플랫폼 검사가 줄었다는 것을 모름
```
- 파일: `scripts/test-sample-removal.ts:47-96`, `:154-172`(보존 확인 목록), `tests/fixtures/typecheck/invalid-http-wire-mapper.ts:1-2`.
- 제품 기록: `memento-frontend` `docs/operations/template-sync-2026-09-29.md:262`, `:297-301`, `tech-log-frontend` 같은 파일 `:72-78`, `:292-312`.
## 2. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 적용·통제(목표/확인)·증거 | 근거와 잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | > | 01~09 | 이 영역에서 찾은 실행기 결함은 10-03에 적고 03 영역과 공유한다 |
| 2 | 구조적 성숙도 | > | 12 | — |
| 3 | 변경 용이성 | P | 적용 · M2/M2 · E2 | 테스트 추가는 쉽다(`create-test-application.ts`, `fixture-feature.tsx`). 스타터 화면을 바꾸면 플랫폼 테스트를 옮겨야 한다(10-02) |
| 4 | 인지 부하 | P | 적용 · M2/M2 · E1 | `docs/testing/taxonomy.md`가 계층·파일 하나 실행법을 정확히 적는다. `test:all`과 CI가 돌리는 집합이 다르다(10-05) |
| 5 | 위험 가시성 | P | 적용 · M1/M1 · E1 | guardian 테스트는 watchdog이 프로토콜 마감이 아니라고 적는다(`provider-guardian-transaction.test.ts:21-34`). 같은 파일의 lease 마감(350ms~3s)이 기동 시간을 포함한다는 사실은 적지 않는다(10-01) |
| 6 | 실패 성숙도 | P | 적용 · M3/M3 · E2 | 실패 경로 변이 11/12 검출. 마감 경계에서 시간 초과가 계약 위반으로 분류된다(10-03) |
| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — |
| 8 | 디버깅 가능성 | P | 적용 · M2/M2 · E3 | 부하 실패 문구가 원인(느림)을 가린다: "Unable to find role", "READY timed out"(10-01). 두 번째 같은 종류 guardian은 거부 대신 5초 뒤 "READY timed out"으로 끝난다(`provider-guardian-client.ts:22`, 탐침 5,035ms) |
| 9 | 유지보수 성숙도 | P | 적용 · M1/M1 · E1 | 문서와 구성이 대체로 맞다. `test:platform`만 `--no-file-parallelism`인 이유가 없다(`package.json:141`). CI(`test:coverage`)는 같은 파일을 병렬로 돌리고 두 번 모두 통과했다 |
| **10** | **테스트 성숙도** | **P** | 적용 · 목표 M3 / 확인 M3 · E2(변이)·E3(부하) | 변이 12종 중 11종 검출, 지난 생존 7종 + M1b 전부 검출(0절 표). 깨끗한 체크아웃 통과(worktree에 `artifacts/release` 없음, C1 통과). 재시도 0(`vitest.config.ts`에 `retry` 없음). 남은 것: 부하 의존(10-01), 제품 콘텐츠에 묶인 플랫폼 테스트(10-02), §10.8 미고정(10-04). 한 규칙을 테스트 1개가 잡는 경우가 많다(G, I, L). 그 테스트가 사라지면 보호도 사라진다 |
| 11 | 데이터 성숙도 | > | 05 | IndexedDB 대역은 05 영역 |
| **12** | **동시성 성숙도** | **P** | 적용(테스트 격리·실행 경쟁) · M3/M2 · E3 | 테스트 사이 상태 격리는 좋다: `restoreMocks`·`mockReset`(`vitest.config.ts:20-22`), 전역 `useRealTimers`(`tests/setup.ts:5-11`). 병렬 실행 C1·C2에서 순서 의존 실패는 없었다. CPU 경쟁에서는 실제 시계에 기대는 테스트 4개가 실패한다(10-01). `vi.stubGlobal`을 되돌리지 않는 파일이 1개 있다(`tests/component/boot-unexpected-failure.test.tsx:25`, 설정에 `unstubGlobals` 없음, 영향은 같은 파일 안) |
| 13 | 확장성 | > | 11 | — |
| 14 | 성능 성숙도 | P | 적용(테스트 실행 시간) · M2/M2 · E3 | FE-GATE-005 Vitest 단계: 4코어 111s, 2코어 169s. 머지 게이트 안의 절대 시간 예산이 2코어에서 넘는다(10-01) |
| 15 | 보안 성숙도 | > | 02·03 | 변이 C·D·L은 잡혔다 |
| 16 | 의존성 성숙도 | > | 13 | — |
| 17 | API / Contract | P | 적용(계약 테스트) · M3/M3 · E2 | contract·runtime-schema 게이트 통과(오케스트레이터). V2/V3 일치 테스트는 V2 행이 0개여도 통과한다(`tests/unit/http-operation-v2-v3-parity.test.ts:31`, FOLLOW-UP 07-03 유효). 실행기 §10.8 미고정(10-04) |
| 18 | 배포 성숙도 | > | 11·13 | — |
| 19 | 설정 성숙도 | P | 적용(러너 설정) · M3/M2 · E2 | `include`·`exclude`·Node 확인·생성기 연결은 맞다(10-05 지난 수정 유지). 비동기 대기 기본값(1초)을 전역에서 정하지 않아 파일마다 다르다(10-01) |
| **20** | **개발자 경험** | **P** | 적용 · M2/M2 · E2 | 새 worktree에서 파일 하나 실행과 계층 실행이 문서대로 된다(`docs/testing/taxonomy.md` "To run one test file"). `test:all`("normal product-development loop")은 CI가 돌리는 6파일을 빠뜨린다(10-05). 제품 동기화 때 플랫폼 테스트 이식 비용(10-02). CI를 켜면 거짓 실패 조사 비용(10-01) |
| **21** | **Guardrail 성숙도** | **P** | 적용 · M3/M3 · E2 | 게이트 소속 검사: 비-fixture 테스트 327개 = Vitest 수집 293 + system 3 + Playwright spec 31. 게이트 경로 밖은 6개이고 전부 `ungated-tests.json`에 있다(`scripts/lib/ungated-tests.ts` 재계산). 빠른 계층에 skip·only·todo 없음. 변이 H로 07-05 수정 확인. 남은 것: 샘플 제거가 플랫폼 검사 10개를 함께 지운다(10-02). `tests/scale/tsc-diagnostics-parser.test.ts`는 CPU와 무관한 순수 파서 테스트인데, 제외 이유는 6개 공통 문구("CPU 모델에서만 시간을 비교")다 |
| 22 | 추상화 성숙도 | P | 적용(테스트 도우미) · M2/M2 · E1 | `fixture-feature.tsx`가 샘플 대신 쓸 테스트 전용 기능을 준다. 이 방식이 기능 라우트에만 적용되고, 플랫폼 화면·HTTP 시나리오·타입 fixture에는 적용되지 않았다(10-02) |
| 23 | 일관성 | P | 적용 · M2/M1 · E1 | 지연 로딩 대기 시간 지정이 세 방식이다: 호출마다 `{ timeout: 5000 }`(router 3곳), 파일 단위 `configure`(`reference-page.test.tsx:137-139`), 지정 없음(runtime-application, render-boundary 등 6파일) |
| 24 | 네이밍 / 의미 | O | 적용 · M1/M1 · E1 | 실패한 테스트 이름이 깨진 규칙을 말한다(변이 표의 테스트 이름). taxonomy가 `tests/unit`의 짧은 자식 프로세스 테스트를 허용 범위로 적는다 |
| 25 | 조직 확장성 | - | 작성자 1인 | — |
| 26 | Ownership | P | 부분 적용 · M2/M1 · E1 | 커버리지 모듈에는 owner가 있다(`config/testing/risk-coverage.json`). `ungated-tests.json` 항목에는 담당·재검토 시점이 없다 |
| **27** | **삭제 가능성** | **P** | 적용 · M3/M2 · E2 | `test:sample-removal`은 통과하고 플랫폼 테스트 4개의 보존을 확인한다(`scripts/test-sample-removal.ts:159-164`). 그러나 샘플 제거가 플랫폼 검사 일부를 지우고, 스타터 화면 교체는 플랫폼 테스트를 깨뜨린다(10-02) |
| 28 | 회복 가능성 | - | 테스트 계층 밖 | — |
집계(적용 22개 기준, `>`·`-` 제외): 충족 1(24) · 부분 충족 14 · 미충족 0 · 미검증 0.
## 3. 설계 선택 설명 (41절)
### 3.1 비동기 화면 대기 시간 — Testing Library 기본 1초를 두고 필요한 곳만 늘린다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | component·feature 테스트가 지연 로딩 route와 Suspense 표시를 기다려야 한다. React는 Suspense 표시를 최대 300ms 묶는다(`reference-page.test.tsx:131-136` 주석). CI 러너 속도는 정해져 있지 않다(목표 없음, U-1) |
| 2. 지킬 성질 | 진짜 멈춤은 빨리 실패해야 한다. 느림은 실패가 아니어야 한다. 실패 문구가 원인을 가리키면 좋다 |
| 3. 현재 보장 | [확인한 사실] 전역 설정이 없다(`tests/setup.ts:1-11`). 테스트 시간 제한은 10초다(`vitest.config.ts:23`). 10-02 수정은 `reference-page.test.tsx` 한 파일만 5초로 올렸다(`:137-139`). router는 호출 3곳만 5초다. runtime-application은 1초 그대로다. [보장하지 않음] 지연 로딩을 기다리는 나머지 호출. 실험 A·B에서 실패했다 |
| 4. 대안 | ⓐ 현 상태(호출·파일 단위) ⓑ `tests/setup.ts`에서 `configure({ asyncUtilTimeout })` 전역 지정 ⓒ route 청크를 `beforeAll`에서 미리 import ⓓ route 준비 신호(예: 첫 heading의 focus)를 기다리는 도우미 |
| 5. 비용 비교 | ⓐ 파일마다 따로 알아야 하고, 새 테스트는 1초로 시작한다(다운스트림 복제). ⓑ 한 줄이다. 모든 `findBy`가 길어져 "없어야 할 요소" 확인이 느려지지만, 부재 확인은 `queryBy`로 한다. 진짜 멈춤은 10초 테스트 제한이 잡는다. ⓒ 부하와 무관해지지만 lazy 경계 자체를 덜 검사한다. ⓓ 가장 정확하지만 새 도우미가 생긴다 |
| 6. 현재 조건에서의 선택 | [추론] ⓑ가 가장 작은 비용으로 원인을 한 곳에서 없앤다. 전략 문서는 "timeout만 계속 늘리지 않는다"고 쓴다(`frontend-platform-testing-strategy.md` 16.5). 이 경우는 CI 속도에 맞춘 증가가 아니라, 1초 기본값이 이 앱의 지연 로딩 비용(최소 300ms 묶음 + 청크 변환)과 맞지 않는 문제다. 테스트 제한(10초)이 멈춤 검출을 맡으므로 보호는 유지된다 |
| 7. 재검토 조건 | 지연 로딩을 쓰지 않게 되거나, route 준비 신호가 공개 계약이 되면 ⓓ로 바꾼다. 느린 러너에서 5초도 넘으면 그 테스트의 작업량을 본다 |
### 3.2 플랫폼 테스트의 대상 — 스타터 화면·참조 샘플을 그대로 쓴다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 경계(chunk 복구, render 경계), 라우터 수명주기, HTTP 실패 시나리오, 기능 등록 타입 규칙을 실제 화면·계약으로 검증해야 한다 |
| 2. 지킬 성질 | 제품이 스타터 화면을 바꾸거나 샘플을 지워도 플랫폼 검사는 그대로 남아야 한다. 템플릿 동기화가 이 테스트에서 충돌하지 않아야 한다 |
| 3. 현재 보장 | [확인한 사실] 기능 라우트는 이미 테스트 전용 기능을 쓴다(`tests/helpers/fixture-feature.tsx:7-20`, `router.test.tsx:15-24`). 플랫폼 화면 테스트는 스타터 화면을 쓴다(`chunk-recovery-boundary.test.tsx:20`, `:148`, `render-boundary.test.tsx:20`, `:58`, `runtime-application.test.tsx:61-68`, `route-status-surfaces.test.tsx:59-67`). HTTP 시나리오·타입 fixture는 샘플 계약을 쓴다(`http-scenario-catalog.test.ts:15`, `invalid-http-wire-mapper.ts:2`). [기록된 의도] 스타터 화면은 "페이지 단위로 교체 가능"하다(`starter-experience.md:3-6`). 샘플 제거 스크립트는 플랫폼 커버리지가 조용히 사라지는 것을 막으려고 4개 파일 보존을 확인한다(`test-sample-removal.ts:154-164`) |
| 4. 대안 | ⓐ 현 상태 ⓑ 플랫폼 화면 테스트도 `fixture-feature.tsx`처럼 테스트 전용 라우트·페이지를 mock으로 설치 ⓒ HTTP 시나리오와 타입 fixture를 `tests/helpers/external-contract-fixture.ts`의 테스트 계약으로 옮김 ⓓ 제품용 "이식 가이드"만 추가 |
| 5. 비용 비교 | ⓐ 템플릿 안에서는 실제 화면을 검사한다는 장점이 있다. 제품마다 이식 비용이 반복되고, 샘플 제거 때 검사가 줄어든다. ⓑ·ⓒ 테스트 전용 fixture 유지비가 생긴다. 스타터 화면 자체의 회귀는 e2e·visual이 맡아야 한다. ⓓ 비용은 작지만 제거 때 검사가 줄어드는 문제는 그대로다 |
| 6. 현재 조건에서의 선택 | [추론] 템플릿의 사용자는 거의 항상 `/`를 바꾼다(두 제품 모두 바꿨다). 이미 있는 ⓑ의 방식을 넓히는 쪽이 계약("페이지 교체 가능", "샘플 제거 가능")과 맞는다 |
| 7. 재검토 조건 | 스타터 화면을 템플릿의 고정 제품 화면으로 선언하면 ⓐ가 맞다. 그때는 README에서 "교체 가능"을 지운다 |
### 3.3 게이트 소속 검사 — 패키지 스크립트의 경로 접두사로 계산한다 (현 상태 유지)
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 테스트 파일이 어떤 CI 게이트에서도 돌지 않는 상태를 막는다(지난 12-04) |
| 2. 지킬 성질 | 새 테스트 파일은 게이트에 속하거나 이유와 함께 제외 목록에 있어야 한다. 게이트가 돌리게 된 파일이 제외 목록에 남으면 안 된다 |
| 3. 현재 보장 | [확인한 사실] `scripts/lib/ungated-tests.ts`가 게이트 명령에서 닿는 스크립트의 Vitest 경로, scale tier, Playwright `testDir`를 모은다. 파일이 그 경로 아래면 소속으로 본다. 현재 327개 전부 맞다(P5). [보장하지 않음] 파일이 경로 아래 있어도 러너가 수집하지 않으면(예: `tests/unit/x.spec.ts`, Playwright `testIgnore`) 소속으로 센다. 지금은 그런 파일이 없다 |
| 4. 대안 | ⓐ 현 상태 ⓑ 게이트마다 `vitest list --filesOnly`·`playwright test --list`로 실제 수집 목록을 대조 |
| 5. 비용 비교 | ⓐ 정적이고 빠르다. 위 틈이 있다. ⓑ 정확하지만 check:ci가 러너를 띄워야 해서 느려지고 브라우저 설치가 필요하다 |
| 6. 선택 | [추론] 지금은 ⓐ가 맞다. 틈은 이름 규칙 위반이 있어야 생기고, `vitest.config.ts`의 `include`가 `.spec`을 이미 거른다. 복잡도를 늘릴 근거가 없다 |
| 7. 재검토 조건 | `testIgnore`·`testMatch`가 늘거나, 테스트 파일 이름 규칙이 바뀌면 ⓑ를 다시 본다 |
## 4. 발견 사항 (36.3)
### 10-01 빠른 계층 머지 게이트에 실행 속도에 기대는 테스트가 남아 있다 — 2코어 러너에서 거짓 실패
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(조건부 재현) |
| 관련 관점 | 10, 12, 14, 20, 21, 8 |
| 근거 | 실험 A·B·C2(0절). 원인은 테스트마다 다르다. ① **지연 로딩을 1초 기본값으로 기다린다.** `runtime-application.test.tsx:64-68`(홈 h1), `router.test.tsx:74-79`(클릭 뒤 두 번째 lazy 화면을 기본 `waitFor`로), `:100-106`. 전역 설정이 없다(`tests/setup.ts:1-11`). 부하에서 이 테스트들이 0.9~3.5s 걸렸다. ② **자식 프로세스 기동 시간을 실제 시계 마감에 넣는다.** `provider-guardian-transaction.test.ts:704`는 spawn 직후 `Date.now() + 350`을 마감으로 보낸다. guardian은 받은 시점에 마감이 지났으면 guard를 거부한다(`scripts/lib/provider-guardian-protocol.ts:88`). 그러면 READY가 오지 않아 5초 watchdog이 "READY timed out"으로 끝난다. 같은 구조가 `:222`, `:327`, `:355`, `:671`, `:881`(2~3초)에 있다. `:727-730`은 lease 2초 중 1초를 잠든다. `:619-653`은 두 번째 guardian의 5초 응답 제한(`provider-guardian-client.ts:22`)을 그대로 기다려서, 10초 테스트 제한 중 5초를 쓴다(부하에서 5.35~5.81s). `PROCESS_HEAVY_TIMEOUT_MS`(30s)는 한 테스트에만 붙어 있다(`:717`). ③ **머지 게이트 안의 절대 시간 예산.** `extreme-scale-registry.test.ts:20` `MAX_LOOKUP_MS = 1_500`이 V8 계측 아래 `test:coverage`(FE-GATE-005)에서 돈다. 2코어에서 1,531ms로 실패했다. 이 파일은 scale tier(`run-scale-profile.ts:87`)에도 있다. ④ `http-execution-v3-live-authority`는 테스트 문제가 아니다(10-03) |
| 발생 조건 | CPU가 worker 수보다 적을 때. `test:coverage`는 `--maxWorkers=4`로 고정이라 2 vCPU 러너에서 항상 이 조건이다. 개발 장비에서 여러 작업을 함께 돌릴 때도 같다 |
| 영향 | CI를 켜면(U-1) 코드와 무관하게 머지가 막힌다. 실험 B 기준 실행 5번 중 3번 실패했다. 실패 문구가 원인을 가려 UI·프로세스 결함처럼 보인다. 재시도가 없으므로 팀은 수동 재실행을 배우고, 10-03 같은 진짜 신호도 함께 무시하게 된다. 두 제품도 같은 실패를 겪었다(memento `template-sync-2026-09-29.md:297-301`) |
| 심각도·우선순위 | Medium · P1 — 제품 피해는 없다. 게이트 신뢰를 깎고 조사 비용을 반복시킨다. FOLLOW-UP이 CI를 켜기 전 처리로 정했다 |
| 통제·증거 | 통제: 전략 문서의 flaky 정책(M1, `frontend-platform-testing-strategy.md` 16.5), 재시도 0(M2). 속도 의존을 막는 장치는 없다(M0) · 증거: E3(CPU 제한 실험, 조건 기록) |
| 확실성과 남은 가정 | 네 원인은 코드와 실패 문구로 확인했다. 실제 Gitea 러너의 코어 수와 실패율은 모른다(U-1) |
| 결정의 근거 | 3.1절. [확인한 사실] 10-02 지난 수정은 파일 하나에만 적용됐다. [추론] 원인이 테스트 도구 기본값이라 전역 한 곳에서 고치는 편이 맞다 |
| 이해 비용 | 새 component 테스트 작성자는 lazy 화면을 기다릴 때 5초를 직접 줘야 한다는 것을 알 방법이 없다. guardian 테스트 수정자는 lease 마감이 기동 시간을 포함한다는 것을 코드에서 추론해야 한다 |
| 최소 개선 방향 | ① `tests/setup.ts`에 `configure({ asyncUtilTimeout: 5_000 })`. 그 뒤 파일·호출 단위 override를 지운다. ② guardian 테스트는 guard를 보내기 전에 자식이 입력을 읽을 준비가 됐다는 신호를 기다린다(이미 있는 `guardian-spawned` 표식 방식, `:814-818`). 5초 대기를 쓰는 `:619` 테스트에 `PROCESS_HEAVY_TIMEOUT_MS`를 붙인다. ③ 절대 시간 예산은 scale tier에만 두고 `test:coverage` 대상에서 뺀다. 머지 게이트에는 증가율(`MAX_COMPOSE_GROWTH_RATIO`처럼 CPU와 무관한 비율)만 남긴다 |
| 대안 비교 | 3.1절. ③은 예산을 올리는 방법도 있다. 그러면 1코어 러너에서 같은 문제가 다시 생긴다 |
| 단순화의 보존 조건 | 진짜 멈춤은 여전히 10초(또는 30초) 테스트 제한에서 실패한다. guardian의 "만료된 guard 거부" 규칙은 별도 테스트로 계속 고정한다(마감을 과거로 보내는 경우) |
| 비용·부작용 | 수십 줄. `findBy`의 부재 대기가 길어지는 테스트가 있으면 `queryBy`로 바꿔야 한다 |
| 재검토 조건 | CI 러너 사양이 정해지면 실험 B·C2를 그 사양으로 다시 돈다 |
| 완료 기준 | 2코어·`--maxWorkers=4`로 `tests/component tests/features tests/integration`을 20회, `test:coverage`의 Vitest 단계를 5회 돌려 실패 0 |
| 검증 방법 | `taskset -c 0-1 node scripts/run-vitest.ts run tests/component tests/features tests/integration --maxWorkers=4`를 반복하고 실패를 센다 |
| 담당·기한·상태 | 미정 · U-1 전 · 신규(FOLLOW-UP 3절 P1 2건 + 새 2건) |
### 10-02 플랫폼 테스트가 제품이 바꾸거나 지울 콘텐츠(스타터 화면, 참조 샘플)를 대상으로 쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(스타터 화면 교체 — 두 제품에서 발생) + 구조적 위험(샘플 제거 — 아직 발생 전) |
| 관련 관점 | 27, 20, 10, 21, 3, 22, 30.5, 30.7 |
| 근거 | **스타터 화면.** 플랫폼 경계 테스트가 템플릿 화면에 묶여 있다: `chunk-recovery-boundary.test.tsx:20`(`state-gallery-page.tsx` mock), `:148`, `:177`(`/examples/states`), `render-boundary.test.tsx:20`, `:58`, `runtime-application.test.tsx:61-68`(`/`의 h1 "Clean Architecture Frontend"), `router.test.tsx:60-80`(홈의 "플랫폼 구성 보기" 링크), `:96-117`, `:213-233`, `route-status-surfaces.test.tsx:59-67`, `:170-187`, `app-shell.test.tsx:70`. 문서는 스타터 화면을 "페이지 단위로 교체 가능"이라고 선언한다(`starter-experience.md:3-6`). 제품 기록: tech-log는 템플릿 화면을 지운 뒤 플랫폼 테스트 7파일을 자기 라우트로 옮겼고 3파일은 가져오지 않았다(`tech-log-frontend` `template-sync-2026-09-29.md:72-78`, `:292-312`). memento는 `/`와 앱 이름을 가정한 테스트 9파일 이상을 고쳤다(`memento-frontend` 같은 파일 `:262`). **참조 샘플.** 제거 절차의 `SAMPLE_EXTRAS`가 플랫폼 검사를 함께 지운다(`scripts/test-sample-removal.ts:47-96`): HTTP 실패 시나리오 카탈로그와 `tests/mocks`, `test:http-scenario-evidence`(FE-GATE-007 명령), 기능 스위치 테스트, 플랫폼 API(`defineFeatureHttpOperation`, `createFeatureHttpBinding`, `defineFeatureAdapterContribution`)의 타입 음성 fixture 8개와 FE-GATE-003 명령 8개. 이 fixture들은 샘플 계약을 import한다(예: `invalid-http-wire-mapper.ts:1-2`). 실험 P4: 실행기 관련 테스트 84파일에서 샘플에 묶인 15파일을 빼면 `feature-http-binding.ts` 분기 78.7→62.3%, `http-contract-bridge.ts` 71.1→59.5%, `bounded-body-reader.ts` 71.7→60.4%로 준다. 단, 이 비교는 모듈을 직접 import하는 테스트를 넣지 않았다. 전체 스위트에서는 커버리지 하한(`risk-coverage.json`)이 샘플 제거 뒤에도 통과한다(오케스트레이터 `test:sample-removal` PASS) |
| 발생 조건 | 제품이 `/`나 `/examples/*`를 바꿀 때(두 제품 모두 해당). 제품이 문서대로 참조 샘플을 지울 때 |
| 영향 | 스타터 화면: 동기화마다 플랫폼 테스트 수정·이식 비용이 생기고, 다음 동기화 때 같은 파일이 다시 충돌한다. 이식하지 않고 지우면(tech-log가 3파일을 가져오지 않음) 그 경계 검사가 제품에서 사라진다. 샘플: 제거 게이트는 통과하므로 제품은 HTTP 실패 시나리오 증거와 플랫폼 타입 규칙 검사가 없어졌다는 것을 모른다. 두 제품 모두 아직 샘플 디렉터리를 남겨 두었다(tech-log는 `NOT_INSTALLED`로 두고 삭제 여부를 미결로 남김, `template-sync-2026-09-29.md:122-133`) |
| 심각도·우선순위 | Medium · P2 — 제품 피해는 없다. 복사한 모든 제품에서 반복되는 비용이고, 선언된 제거 경로에서 가드레일이 조용히 준다 |
| 통제·증거 | 통제: 기능 라우트는 테스트 전용 기능으로 분리됨(M2), 샘플 제거 시 플랫폼 테스트 4개 보존 확인과 커버리지 하한(M3). 스타터 화면 분리는 M0 · 증거: E1(코드), E2(커버리지 비교), 제품 동기화 기록 2건 |
| 확실성과 남은 가정 | 스타터 화면 결합은 두 제품의 실제 수정 기록으로 확인했다. 샘플 제거로 사라지는 검사 목록은 스크립트에서 확인했다. 같은 규칙을 다른 테스트가 얼마나 대신 지키는지는 모듈별로 확인하지 않았다 |
| 결정의 근거 | 3.2절 |
| 이해 비용 | 제품 개발자는 어떤 템플릿 테스트가 "플랫폼 규칙"이고 어떤 것이 "스타터 화면 검사"인지 파일 이름으로 알 수 없다. 샘플 제거 시 무엇이 함께 사라지는지는 스크립트 상수를 읽어야 안다 |
| 최소 개선 방향 | ① 플랫폼 화면 테스트를 `fixture-feature.tsx`와 같은 방식의 테스트 전용 라우트·페이지로 옮긴다. 스타터 화면 자체의 검사는 이름에 드러나는 별도 파일(예: `starter-*.test.tsx`)로 모아 제품이 통째로 지울 수 있게 한다. ② HTTP 시나리오 카탈로그와 타입 음성 fixture를 `tests/helpers/external-contract-fixture.ts`의 테스트 계약으로 옮겨 `SAMPLE_EXTRAS`에서 뺀다. ③ 그 전까지는 README 제거 절에 "함께 사라지는 플랫폼 검사" 목록을 적는다 |
| 대안 비교 | 3.2절 |
| 단순화의 보존 조건 | 옮긴 뒤에도 chunk 복구·render 경계·라우터 수명주기·HTTP 시나리오 19×3·타입 음성 규칙 8개가 같은 게이트에서 돈다. 스타터 화면 회귀는 e2e·visual이 계속 본다 |
| 비용·부작용 | 테스트 fixture 몇 개와 파일 이동. 제품은 다음 동기화 때 한 번 더 충돌을 푼다 |
| 재검토 조건 | 스타터 화면을 교체 불가 제품 화면으로 선언하면 ①은 필요 없다 |
| 완료 기준 | 템플릿 복사본에서 `src/presentation/pages/home-page.tsx`와 `src/presentation/examples/*`를 다른 화면으로 바꾸고 `starter-*` 테스트만 지웠을 때 나머지 component 테스트가 통과한다. `test:sample-removal` 뒤에도 HTTP 시나리오 증거와 타입 음성 fixture가 게이트에 남는다 |
| 검증 방법 | 위 두 조작을 worktree에서 한 뒤 `test:component`, FE-GATE-003·007 명령 실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 10-03 실행기가 마감 시각을 두 번 읽어, 그 사이에 마감이 지나면 시간 초과를 "요청 계약 위반"으로 보고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 12, 5, 8, 10, 24 |
| 근거 | `src/adapters/http/http-execution-v3.ts:884-889`이 남은 시간을 읽고 0 이하면 `TIMEOUT`을 돌려준다. 이어서 타이머·헤더를 만든 뒤 `:918-927`의 `checkFinalInvariants`가 남은 시간을 다시 읽는다. 여기서 0 이하면 `DEADLINE_EXPIRED`(`http-contract-bridge.ts:407`)가 나오고, 실행기는 `SCOPE_FENCED`가 아닌 모든 불변식 실패를 `FINAL_REQUEST_INVARIANT_FAILED` 계약 위반으로 바꾼다(`:929-941`). 화면 계층은 이것을 `VALIDATION_REJECTED`로 옮긴다(`feature-http-binding.ts:467-471`). `VALIDATION_REJECTED`는 재시도 불가·행동 없음이고 `REQUEST_TIMEOUT`은 재시도 가능·"retry"다(`src/contracts/errors.ts:43`, `:77`). 탐침 P3: 시계를 주입해(`monotonicNow`) k번째 읽기 뒤에 마감을 넘기게 하면 k=6·7에서 `CONTRACT_VIOLATION / FINAL_REQUEST_INVARIANT_FAILED`, 나머지 k에서 `TRANSPORT_FAILURE / TIMEOUT`이 나온다. 부하 실험 B에서 `http-execution-v3-live-authority.test.ts:357-380`(마감 5ms)이 같은 결과로 실패했다 |
| 발생 조건 | 요청 직전 두 시계 읽기 사이에 메인 스레드가 멈춰 마감이 지날 때. 재시도·대기로 남은 시간이 적을 때 가능성이 커진다(느린 기기, GC, 백그라운드 탭) |
| 영향 | 요청은 보내지지 않는다(`NOT_STARTED`). 데이터 피해는 없다. 사용자는 일시적 시간 초과에 "재시도" 대신 입력 거부 계열 결과를 받는다. 진단은 계약 위반으로 집계돼 조사 방향을 틀리게 만든다. FOLLOW-UP은 이 테스트를 "재현 조건을 찾는다"로 환경 탓에 두었다. 테스트 마감을 늘려 안정화하면 이 결함의 유일한 신호가 사라진다 |
| 심각도·우선순위 | Low · P2 — 드물고 피해가 작다. 우선순위는 10-01 수정 때 이 테스트를 잘못 고치지 않도록 먼저 정한다 |
| 통제·증거 | 구현 M2(두 검사 모두 있음), 분류 규칙 결정적 테스트 없음(M0) · E2(주입 시계 탐침)·E3(부하 재현) |
| 확실성과 남은 가정 | 경로와 매핑은 확인했다. 실제 사용자 기기에서의 빈도는 모른다 |
| 결정의 근거 | 적용 제외 — 기대 계약(마감 경과는 `TIMEOUT`)이 이미 정해져 있어 선택 비교가 필요 없다 |
| 이해 비용 | `checkFinalInvariants`가 마감도 검사한다는 사실을 호출부의 매핑 코드에서 알 수 없다 |
| 최소 개선 방향 | `:929-941`에서 `DEADLINE_EXPIRED`를 `abandonedTransportFailure("TIMEOUT")`으로 매핑한다(`SCOPE_FENCED`처럼 별도 분기). 주입 시계로 k=6·7 경우를 고정하는 단위 테스트를 추가한다. live-authority 테스트는 그대로 둔다 |
| 대안 비교 | 적용 제외 — 명백한 분류 오류를 바로잡는 수정이다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 몇 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 탐침 P3의 모든 k에서 `TRANSPORT_FAILURE / TIMEOUT`이 나온다. 실험 B 20회에서 live-authority 실패 0 |
| 검증 방법 | 주입 시계 단위 테스트, 실험 B 반복 |
| 담당·기한·상태 | 미정 · 미정 · 신규(03 영역 코드. 03 영역과 공유) |
### 10-04 실행기의 "오래된 scope의 성공 응답은 버린다"(§10.8) 마지막 검사를 어떤 테스트도 고정하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검출 공백) |
| 관련 관점 | 10, 12, 17, 15 |
| 근거 | 변이 K: `http-execution-v3.ts:1376-1382`의 검사를 꺼도 관련 84파일 631개가 모두 통과했다. 기존 scope 테스트는 fetch 안에서 scope를 바꾸면서 lifetime signal도 abort한다(`tests/unit/http-execution-v3.test.ts:532-572`). 그래서 본문 읽기가 abort 경로로 끝나 이 검사까지 오지 않는다. 조회 경로에서는 `application-query.ts:112`가 실행 뒤 scope를 다시 확인하므로, 지금 조립된 화면에서 다른 세션의 데이터가 캐시에 들어가지는 않는다 |
| 발생 조건 | 본문을 다 읽은 직후, 검증·매핑이 도는 동안 scope가 바뀌고 signal abort가 아직 반영되지 않았을 때. 실행기를 `application-query` 밖에서 직접 쓰는 기능·레시피 |
| 영향 | 실행기 리팩터링에서 이 검사가 빠져도 빠른 테스트가 모른다. 상위 계층의 재검사가 막아 주는 동안에는 사용자 피해가 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 구현 M2(두 계층에 검사), 실행기 단위 검출 M0 · E2(변이) |
| 확실성과 남은 가정 | 미검출은 확인했다. `application-query` 밖의 실제 호출자가 있는지는 01~09 영역 몫이다 |
| 결정의 근거 | 적용 제외 — 계약(§10.8)은 코드 주석에 이미 있고, 테스트 누락만의 문제다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | `isCurrent`가 본문 읽기 완료 뒤에만 false가 되는(signal은 abort하지 않는) 테스트 하나를 추가한다. 기대 결과는 `CONTRACT_VIOLATION / SCOPE_FENCED` |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 변이 K를 넣으면 새 테스트가 실패한다 |
| 검증 방법 | 변이 K 적용 후 `node scripts/run-vitest.ts related src/adapters/http/http-execution-v3.ts --run` |
| 담당·기한·상태 | 미정 · 미정 · 신규(03 영역과 공유) |
### 10-05 `test:all`("일상 개발 루프")이 CI가 돌리는 빠른 테스트 6파일을 빠뜨린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 4, 21 |
| 근거 | `test:coverage`(FE-GATE-005)는 `tests/features`, `tests/scripts`, `tests/scale/browser-soak.contract.test.ts`를 돌린다(`package.json:81`). `test:all`은 `tests/features/reference-feature`만 돌리고 나머지는 없다(`package.json:83`). 실험 C2 파일 목록과 대조한 결과 빠진 파일: `tests/features/feature-installation-surface.test.ts`, `feature-module.test.ts`, `product-features-scale.test.ts`, `tests/scale/browser-soak.contract.test.ts`, `tests/scripts/generate-product-feature-index.test.ts`, `verify-extreme-scale.test.ts`. taxonomy는 `test:all`을 "the normal product-development loop"라고 쓴다(`docs/testing/taxonomy.md:19-25`). `test:platform`은 `--no-file-parallelism`이고 CI는 같은 파일을 병렬로 돌린다(이유 기록 없음, `package.json:141`) |
| 발생 조건 | 개발자가 기능 모듈 선언·생성기를 바꾸고 `test:all`만 돌릴 때 |
| 영향 | 로컬에서 초록이고 CI에서 빨강이다. 기능 설치 표면·생성기 규칙은 기능 추가 때 자주 바뀌는 곳이다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1(문서) · E2(실행 목록 대조) |
| 확실성과 남은 가정 | 확인했다 |
| 결정의 근거 | 적용 제외 — 스크립트 경로 누락이다 |
| 이해 비용 | 개발자가 두 스크립트의 경로 목록을 직접 비교해야 안다 |
| 최소 개선 방향 | `test:all`의 `test:reference-feature`를 `tests/features` 전체로 넓히고 `tests/scripts`를 더한다. 또는 taxonomy에 "CI와 같은 집합은 `test:coverage`"라고 적는다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 한 줄. `test:all`이 몇 초 길어진다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `test:all`이 돌리는 파일 집합이 `test:coverage`의 Vitest 파일 집합을 포함한다 |
| 검증 방법 | 두 명령의 `vitest list --filesOnly` 결과 비교 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 5. 지난 라운드 수정의 현재 상태
| 지난 ID | 현재 | 근거 |
|---|---|---|
| 10-01 깨끗한 체크아웃 실패 | 유지됨 | 새 worktree(`artifacts/release` 없음)에서 C1·C2의 `tests/unit` 전부 통과 |
| 10-02 reference-page 첫 대기 | 부분 — 같은 원인이 다른 파일에 남음 | 10-01 발견 |
| 10-03 V3 재시도 의미 | 유지됨 | 변이 I 검출 |
| 10-04 커버리지 게이트 | 유지됨 | `http-contract-bridge.ts`·`http-retry-lifecycle.ts`가 하한 목록에 있음(`risk-coverage.json`) |
| 10-05 파일 하나 실행 | 유지됨 | taxonomy 명령이 새 worktree에서 동작, `include`가 `.spec`을 거름(수집 293 = 비-spec·비-system 전부) |
| 10-06 fake timer 복원 | 유지됨 | `tests/setup.ts:8-10` |
| 10-07 테스트 문서 | 유지됨 | taxonomy의 `test:all` 구성·파일 하나 실행법·자식 프로세스 분류가 현재와 같다 |
| 12-04 게이트 밖 테스트 | 유지됨 | P5 전수 대조. 제외 이유 중 `tsc-diagnostics-parser.test.ts`만 사실과 다름(2절 21) |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 근거 |
|---|---|---|
| 3절 P1 `provider-guardian-transaction` | 유효 | 실험 B에서 재현. 원인은 실제 시계 마감(350ms)에 자식 기동 시간이 들어가는 것과 5초 고정 대기(10-01 ②) |
| 3절 P1 `runtime-application` | 유효 | 실험 B에서 재현. 1초 기본 대기(10-01 ①). 이 테스트는 스타터 홈에도 묶여 있다(10-02) |
| 3절 P2 `http-execution-v3-live-authority` | 유효 — 원인이 바뀜 | 실험 B에서 재현. 테스트 환경 문제가 아니라 실행기의 분류 결함(10-03). "재현 조건"은 마감 5ms + 두 시계 읽기 사이의 지연 |
| 3절 P2 reference-page 나머지 대기 | 판단 불가 | 부하 실행 7회(B 5회, C 2회)에서 실패 없음. 첫 테스트가 부하에서 1.7~2.4s로 5초 설정 안이다 |
| 3절 P3 `tests/system/ci-runner/ci-artifact-contract.test.ts` | 다른 영역(11) | — |
| 4절 P2 07-03 V2/V3 일치 테스트 | 유효 | V2 행이 0개면 반복문이 돌지 않아 통과한다(`http-operation-v2-v3-parity.test.ts:31`). V3에만 있는 operation도 보지 않는다 |
| 4절 01-11·05-03·06-10·08-04·08-07 테스트 빈틈 | 다른 영역(01·05·06·08·11) | — |
| 5절 P3 fixture의 pnpm 설치 검사 끔(F-4, F-12) | 유효 | `scripts/lib/fixture-node-modules.ts:40-42`. fixture가 공유 `node_modules`를 링크로 쓰는 구조 그대로. 이번 리뷰 중 오케스트레이터가 같은 위험(링크된 `node_modules`에서 pnpm 실행)을 경고했다 |
| 5절 P3 00-03 남은 임시 폴더 | 해소(테스트 쪽) | 이 영역의 실행(전체 빠른 계층 2회 포함) 뒤 새 `repository-inventory-*`·`sw-assets-*`가 생기지 않았다. `/tmp`에 있는 324개는 모두 2026-09-29 14:3x~15:3x에 생긴 것이고, 누가 만들었는지(다른 실행·중단된 실행)는 확인하지 못했다 |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 실제 CI 러너에서의 실패율 | CI가 이 repo에서 돌지 않음(U-1). 러너 사양이 정해지지 않음 | U-1 뒤 FE-GATE-005~007을 20회 돌리고 실패를 센다 |
| 1코어·저메모리 조건 | 다른 에이전트와 호스트를 공유해 부하 발생기를 쓰지 않음 | 전용 호스트에서 `taskset -c 0` + `--maxWorkers=4` |
| 샘플 제거 뒤 사라지는 규칙을 다른 테스트가 얼마나 대신 지키는지 | 모듈별 변이는 01~09 영역 몫. P4는 관련 테스트 집합만 비교함 | 샘플 제거 fixture에서 HTTP 모듈 변이 실험 |
| 스타터 화면을 바꾼 복사본에서 실패하는 테스트의 전체 목록 | 제품 기록 2건으로 대신함 | 10-02 완료 기준의 조작을 worktree에서 실행 |
| `test:platform`의 `--no-file-parallelism`이 필요한 이유 | 기록 없음. 병렬 실행 2회는 통과 | `tests/platform` 병렬 20회 |
| `test:sample-removal`·`check:v8-coverage-counter-semantics` 직접 실행 | worktree에서 pnpm을 쓰지 않기로 함(오케스트레이터 지시). 오케스트레이터 실행 결과(PASS)를 따름 | 메인 트리에서 오케스트레이터가 실행 |
@@ -0,0 +1,417 @@
# 영역 11 — 테스트: 브라우저·릴리스·규모
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` (워킹트리 미커밋 변경은 리뷰 가이드 문서 2개뿐, 코드는 `af3d8e6`과 같다) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, 실행 순서: `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook`, `tests/release`, `tests/scale`, `tests/system`, `tests/architecture`, `tests/scripts`, `playwright*.config.ts` 5개, `scripts/scale/`, `scripts/drill-runbook.ts`. 판정에 필요해서 함께 읽은 것: `scripts/test-performance.ts`, `scripts/lib/lab-performance.ts`, `scripts/lib/performance-budgets.ts`, `scripts/lib/promotion-readiness.ts`, `scripts/contracts/release-artifacts.ts`(drill 판정 부분), `scripts/check-test-evidence.ts`(skip·only 검사), `scripts/verify-exact-promotion-bundle.ts`, `scripts/run-and-validate-provider.ts`(bwrap 부분), `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `config/scale/*`, `config/performance/budgets.json`, `docs/operations/{ci-quality-gates,release-cache-rollback,performance-evidence}.md`, `docs/architecture/optional-adapter-recipes.md`(SW 켜기 절), 제품 repo 2개의 동기화 기록.
> 깊게 본 관점: 10, 13, 14, 18, 28.
> 영역 판정(35.8): **조건부 사용 가능.** 브라우저 테스트(엄격 fixture, 재시도 0, 두 빌드 공존·구 탭 복구·깨진 SW 복구)는 템플릿 기본 구성에서 참고 구현으로 써도 된다. 다음은 그대로 쓰지 않는다. `test:system`이 들어 있는 merge 게이트 FE-GATE-013은 main에서 항상 실패한다(11-01). 운영 drill 게이트는 PASS에 도달할 입력이 없다(11-02). SW e2e는 SW를 켠 제품에서 준비 단계부터 실패한다(11-03). lab 성능 게이트는 부하가 있는 러너에서 판정이 뒤집힌다(11-04).
## 0. 결론
- **merge 게이트 FE-GATE-013(security)이 main에서 결정적으로 실패한다.** `tests/system`의 기대 문자열이 13-04 수정 뒤 바뀐 출력과 다르다. 지난 라운드 검증과 이번 오케스트레이터 게이트 목록 모두 `test:system`을 돌리지 않았다(11-01).
- **지난 11-01(거짓 PASS)은 해소됐다.** `dist/assets/*.js`를 지우면 FE-RB-002·005가 FAIL(exit 1)이고, 나머지는 UNVERIFIED(exit 3)다. 대신 5개 drill 모두 어떤 입력으로도 PASS할 수 없다. production 단계와 그 뒤의 field 단계(FE-GATE-018)는 템플릿 그대로는 끝까지 갈 수 없다(11-02).
- **SW e2e 두 spec은 "SW 꺼짐(null 선택) + 해시 파일만 캐시"를 소스 문자열 치환과 단언으로 가정한다.** 문서의 SW 켜기 1단계만 적용해도 두 spec이 준비 단계에서 실패한다(재현). memento-frontend가 같은 이유로 이 spec을 빨간 채로 미뤘다(11-03).
- **규모 증거는 과장 없이 범위를 적는다.** 실제 모양 기능으로 쟀고 "검증/비검증/조건"을 나눴다. 다만 기준선이 현재 코드와 달라졌고(기능당 초기 JS 2.9KB → 3.2KB) 어느 커밋을 쟀는지 기록이 없다(11-05). pr tier는 FE-GATE-005에서 돌고 CPU 경합에서도 10/10 통과했다.
- **lab 성능은 5회 중앙값으로 바뀌었지만 판정은 여전히 뒤집힌다.** 같은 빌드를 5번 돌려 PASS 2 / FAIL 3이었다(loadavg 16~22/22스레드)(11-04).
- **지난 11-02·11-06·11-08은 해소됐다.** a11y 변이는 두 라우트에서 5/5 검출, 스키마 위반 목 응답은 spec 단언이 잡는다. 4개 Playwright 설정 모두 `forbidOnly: true`다.
## 1. 범위와 방법 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template` 영역 11 |
| 커밋·상태·시점 | `main` / `af3d8e6`, 2026-09-29. 실험은 분리 worktree(`scratchpad/review-2026-09-29/11/wt`)와, `tests/system`만 `.git`이 디렉터리인 로컬 clone(`…/11/clone`)에서 했다. 둘 다 끝난 뒤 지웠다 |
| 실행 환경 | Node v24.14.0, Playwright 1.62.0, Intel Core Ultra 7 155H(22 스레드). 다른 영역 에이전트가 동시에 돌아 loadavg 2~42 |
| 목적·실행 형태 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 |
| 규모·운영 목표 | 선언 상한만 있다(`CONTEXT_MAX_FEATURES = 200`, `APP_MAX_CONTEXTS = 20`). 성능 예산은 `config/performance/budgets.json`. RPO/RTO 없음 |
| 확인하지 못한 범위 | Firefox·WebKit(지시에 따라 chromium만), e2e 전체, storybook spec, browser soak, main/nightly/release scale tier(기준선 CPU 필요), CI 러너 결과(U-1) |
| 이전 리뷰와 비교 | 2026-09-25 영역 11 문서의 발견 8건을 현재 코드로 다시 확인했다(6절). 지난 결과는 증거로 쓰지 않았다 |
실행 목록. worktree는 원본 `node_modules`를 심볼릭 링크했다. 스크립트는 `node scripts/…`로 직접 불렀다. Playwright는 포트 충돌을 피하려고 포트만 바꾼 설정 사본(4411~4414, `--strictPort`)을 worktree 안에 두고 chromium만 돌렸다.
| 명령·실험 | 결과 |
|---|---|
| `node scripts/run-vitest.ts run tests/release tests/architecture tests/scripts tests/scale tests/unit/{runbook-drill,lab-performance,feature-shape-growth}.test.ts` | 28파일 165개 통과 |
| `node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts` | 성공(local 프로필, SW 없음) |
| `node scripts/drill-runbook.ts FE-RB-001..005` (완전한 dist) | 5개 모두 `UNVERIFIED`, exit 3 |
| 같은 명령, `dist/assets/*.js` 전부 삭제 | FE-RB-002·005 `FAIL` exit 1. 001·003·004 `UNVERIFIED` exit 3(자산을 읽지 않는 drill) |
| lazy chunk 1개만 삭제 | FE-RB-002 `FAIL` |
| 엔트리 JS를 0바이트로 | FE-RB-002·005 `UNVERIFIED`, 메시지 "no local check failed"(파일 존재만 본다) |
| 변이: FE-RB-001·002의 관측 불가 항목 2개를 `assertion(…, "PASS")`로 | `tests/unit/runbook-drill.test.ts` 9/9 통과. record에 `product root mount: PASS` 기록(11-08) |
| `node scripts/scale/run-scale-profile.ts pr` | PASSED 4단계. 추적 중인 로그 3개가 바뀌고 새 로그 1개 생김(11-09) |
| `run-composition-scale.ts --profiles=S0,S1,S2` 10회, `taskset -c 2`로 busy loop 3개와 CPU 1개 공유 | 10/10 PASS |
| Playwright chromium: `service-worker-update`, `service-worker-recovery`, `old-tab-chunk-recovery`, `boot-module-failure` | 8/8 통과 |
| 전제 변경: `installed-runtime-capabilities.ts`의 SW 선택을 `ACTIVE`로(문서의 SW 켜기 1단계) | SW spec 6개 중 2 failed, 4 did not run. `/tmp/ca-sw-builds-*` 2개(각 18MB) 남음(11-03, 11-07) |
| a11y 변이: `/examples/states`에 alt 없는 `img`·이름 없는 `button`, 보호 라우트 상세에 이름 없는 `button`. `--repeat-each=5` | 5/5, 5/5 검출 |
| `reference-route`, `reference-save`, `reference-form`, `production-csp` chromium | 14/14 통과 |
| 변이: reference-route 목 응답을 `[{ wrong: true }]`로 | spec 단언 `getByText('Browser reference')`에서 실패 |
| visual(`platform.visual.spec.ts`) chromium | 5/5 통과. 상태 화면 기준 이미지는 본문을 담고 있다 |
| browser-capabilities chromium, 포트 4414 | 20 통과 / 1 실패(`resumable-upload` CORS, 포트 하드코딩) |
| `node scripts/test-performance.ts` 5번(각 5회 측정) | PASS 2 / FAIL 3(11-04) |
| `node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25 --repeats=1` | 0개: 716,418 inst, 초기 203,481 B, lazy 23,572 B. 25개: 3,616,223 / 284,609 / 149,766(11-05) |
| `tests/system` (worktree) | 17 failed / 95 passed. 15건은 bwrap `Can't mkdir …/.git: Not a directory`(worktree는 `.git`이 파일) |
| `tests/system` (clone, `.git` 디렉터리, 전제 검사 PASS) | 2 failed / 110 passed. 단독 재실행과 기대 문자열 수정 실험 → 11-01, 11-06 |
주의: `test-performance.ts`는 안에서 `corepack pnpm preview`를 띄운다. 오케스트레이터의 경고(worktree에서 pnpm 금지) 전에 `pnpm_config_verify_deps_before_run=false`로 5번 실행했다. 실행 뒤 원본 `node_modules`가 그대로인 것을 확인했고, 경고 뒤에는 pnpm을 부르는 명령을 돌리지 않았다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — merge 게이트 FE-GATE-008의 저장 E2E
```
PR 커밋
→ playwright.config.ts: forbidOnly(:5), retries 없음(기본 0), webServer가 build+preview(:17-22)
→ dist 재빌드, 새 브라우저 context
→ reference-save.spec.ts: API는 page.route로 목(:21-35), 저장·429 뒤 재시도(:47-99)
→ 실패: strict fixture가 console/pageerror/requestfailed를 모아 테스트 끝에 실패(tests/support/browser/strict-browser-test.ts:27-58)
의도한 실패만 좁은 정규식으로 허용(reference-save.spec.ts:67-70)
→ 결과: junit(artifacts/tests/e2e/results.xml) → 게이트 증거. forbidOnly 누락은 check-test-evidence가 잡음(scripts/check-test-evidence.ts:384-393)
```
이 흐름은 chromium에서 끝까지 확인했다(14/14, 스키마 변이 검출).
### 2.2 피해가 큰 흐름 — 운영 승격 drill
```
workflow_dispatch stage=production
→ promotion job의 archive를 SHA로 대조해 추출(.gitea/workflows/quality-gates.yml:399-405)
→ production_gate 매트릭스 FE-GATE-021~025(:381-387), 각 drill에 --release-root(config/ci/gates.json:484-494, :530-573), expect "pass"
→ drill: 추출한 release의 dist/release-manifest.json, config.json, .vite/manifest.json 읽기(scripts/drill-runbook.ts:88-108, :145-166)
→ 외부 I/O 없음(브라우저·provider·live API 없음)
→ 실패: 자산 누락·tuple 불일치 → FAIL exit 1 / 관측 못 한 항목 → UNVERIFIED exit 3(:458-475)
→ 결과: 모든 실행에서 production_gate 실패 → field_gate는 needs 때문에 건너뜀(:416-418) → PROD_PROMOTION_READY·FIELD_SLO_READY 거짓(scripts/lib/promotion-readiness.ts:56-58)
```
로컬 판정은 정직하다. PASS로 가는 입력이 없다는 점이 11-02다.
### 2.3 변경 흐름 — 다운스트림이 Service Worker를 켠다
```
docs/architecture/optional-adapter-recipes.md:112-113 "SERVICE_WORKER를 ACTIVE로"
→ src/features/installed-runtime-capabilities.ts:39 수정
→ FE-GATE-008 e2e: service-worker-*.spec.ts beforeAll → prepareServiceWorkerBuilds
→ repo를 /tmp로 복사(tests/e2e/support/service-worker-builds.ts:118-124)
→ "= null;" 문자열을 정확히 1회 찾아 치환(:125-129) → 없음 → 예외(:89-91)
→ 결과: 2 failed / 4 did not run, 임시 복사본은 지우지 않음
```
재현했고, memento-frontend 동기화 기록에도 같은 결과가 있다(11-03).
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
| 번호 | 관점 | 판정 | 이유와 근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | > | src 담당 영역 |
| 2 | 구조적 성숙도 | > | 12 |
| 3 | 변경 용이성 | P | 테스트 기대값을 레지스트리에서 읽는다(`tests/e2e/accessibility.spec.ts:24`, `old-tab-chunk-recovery.spec.ts:22-23`). SW harness는 소스 문자열에 묶여 있어 기본값을 바꾸면 깨진다(11-03) |
| 4 | 인지 부하 | P | 어느 테스트가 어느 게이트에서 도는지는 `config/ci/gates.json`과 `ungated-*.json`에서 찾을 수 있다. SW spec의 전제 4개는 코드를 거꾸로 읽어야 안다(11-03) |
| 5 | 위험 가시성 | P | drill record가 관측하지 못한 항목과 필요한 증거를 적는다(`scripts/drill-runbook.ts:136-139`). PASS 경로가 없다는 사실(11-02)과 SW spec 전제(11-03)는 드러나지 않는다 |
| 6 | 실패 성숙도 | O | 브라우저에서 429 뒤 재시도(`reference-save.spec.ts:72-99`), 스키마 위반 표시(변이로 확인), 깨진 SW 해제(`service-worker-recovery.spec.ts:75-151`), 청크 누락 뒤 1회 reload(`old-tab-chunk-recovery.spec.ts:79-127`)를 실제로 돌린다. chromium 통과 |
| 7 | 운영 성숙도 | P | drill이 거짓 PASS를 내지 않는다(자산 삭제 → FAIL 재현). production·field 단계는 PASS할 수 없다(11-02) |
| 8 | 디버깅 가능성 | P | trace `retain-on-failure`, UNVERIFIED 메시지가 빠진 항목을 나열한다(`drill-runbook.ts:462-474`). strict fixture는 `pageerror`의 이름만 남긴다(`strict-browser-test.ts:36-37`). 엔트리 JS가 0바이트여도 drill은 "no local check failed"라고 쓴다(재현) |
| 9 | 유지보수 성숙도 | P | 현재 코드와 다른 규모 기준선(11-05), 커밋된 실행 로그(11-09), 두 벌로 갈라진 helper(11-07) |
| 10 | 테스트 성숙도 (깊게) | P | 강점: 모든 Playwright 설정에 `forbidOnly: true`(`playwright*.config.ts:5`), `retries` 없음, 엄격 fixture. a11y 변이 5/5·5/5, 스키마 변이 검출, drill 자산 삭제 FAIL(모두 이번 실행). 약점: FE-GATE-013의 `test:system`이 main에서 항상 실패(11-01, E3), 부하 레이스(11-06), 죽은 가드 테스트(11-08), SW를 켠 제품에서 SW spec이 준비 단계 실패(11-03) |
| 11 | 데이터 성숙도 | - | 이 영역에 데이터 이관·보관 경로가 없다 |
| 12 | 동시성 성숙도 | O | 두 페이지로 BroadcastChannel·IndexedDB versionchange 등을 확인하는 capability 테스트가 chromium에서 통과(20/21, 실패 1건은 포트 하드코딩). Firefox·WebKit은 이번에 돌리지 않음 |
| 13 | 확장성 (깊게) | P | pr tier가 FE-GATE-005에서 돈다(`config/ci/gates.json:217-218`, `scripts/scale/run-scale-profile.ts:14-19`). CPU 1개를 busy loop 3개와 나눠도 S0~S2 성장 검사 10/10 통과. 실제 모양 기능으로 재고 검증·비검증을 나눴다(`config/scale/feature-shape-ceilings.json:8-40`). 선언 상한은 "검증된 용량이 아니다"라고 적었다(`:8`). 기준선이 현재 코드와 다르고 커밋 기록이 없다(11-05) |
| 14 | 성능 성숙도 (깊게) | P | lab: 5회 cold 중앙값, 조건 기록, `--strictPort`, 서빙 빌드 확인(`scripts/lib/lab-performance.ts:36-111`, `scripts/test-performance.ts:54`, `:182`, `:193`). 같은 빌드에서 PASS 2 / FAIL 3(11-04). 재측정한 초기 JS 여유는 1,319 B다(204,800 − 203,481) |
| 15 | 보안 성숙도 | > | 13(`tests/system`의 샌드박스·아카이브 검증). 11-01만 이 영역에서 다룬다 |
| 16 | 의존성 성숙도 | O | `@playwright/test` 1.62.0, `@axe-core/playwright` 4.12.1 고정(`package.json:164`, `:170`). CI가 3엔진을 설치한다(`quality-gates.yml:69`) |
| 17 | API / Contract | > | 07 |
| 18 | 배포 성숙도 (깊게) | P | SW 없는 기본 구성의 구 탭 청크 복구(`old-tab-chunk-recovery.spec.ts:79-127`)와 SW 켠 A→B 업데이트·이전 캐시 응답(`service-worker-update.spec.ts:222-262`)이 chromium에서 통과. SW를 켠 제품에서는 이 spec이 돌지 않는다(11-03). 자산 보존·전환은 provider 몫이고 drill로 PASS를 기록할 수 없다(11-02). Firefox SW는 quarantine(만료 2027-03-31) |
| 19 | 설정 성숙도 | P | lab 포트는 환경변수 + `--strictPort`. `tests/browser-capabilities/resumable-upload.spec.ts:7`에 4174가 박혀 있다(다른 포트에서 CORS 실패 재현) |
| 20 | 개발자 경험 | P | spec 하나도 전체 빌드를 한다(`playwright.config.ts:17-22`). git worktree에서는 `test:system` 15건이 bwrap `.git` 오류로 실패한다(`scripts/run-and-validate-provider.ts:271-276`, 영역 13). worktree에서 pnpm 스크립트는 공유 `node_modules`를 건드릴 위험이 있다(FOLLOW-UP 5절 F-4 계열) |
| 21 | Guardrail 성숙도 | P | `forbidOnly` 누락 검사와 quarantine 만료 검사가 있다(`scripts/check-test-evidence.ts:294-304`, `:384-393`). merge 게이트 하나가 main에서 빨간 것을 어느 장치도 알리지 않았다(11-01). quarantine 주석 하나가 같은 파일의 모든 skip을 허용한다(`:293-304`) |
| 22 | 추상화 성숙도 | P | 두 빌드 준비 helper가 두 벌이다(11-07). 나머지 테스트 helper는 얇다 |
| 23 | 일관성 | P | 공용 strict fixture를 쓰고, 예외(`service-worker-recovery.spec.ts:87-90`)는 이유가 주석에 있다. helper 두 벌의 제외 목록·실패 정리가 다르다(11-07) |
| 24 | 네이밍 / 의미 | P | drill 문구는 정직해졌다("not observed locally; needs …"). 테스트 이름 "keeps no constant recovery verdict"는 실제 검사보다 넓다(11-08). `CONTEXT_MAX_FEATURES`를 "direct-feature budget"이라 부르지만 검증 용량이 아니다(`src/contexts/reference-context/context-module.ts:4`). FE-RB-001·003·004 record에는 `--release-root` release의 releaseId가 적히지만, 검사 대상은 그 release가 아니라 체크아웃한 소스의 정책이다(`drill-runbook.ts:168-193`, `:244-314`, `:405-414`) |
| 25 | 조직 확장성 | > | 14 |
| 26 | Ownership 성숙도 | P | quarantine에 owner·expires, 기준선에 승인자가 있다. 라운드 검증에서 FE-GATE-013 결과를 아무도 보지 않았다(11-01) |
| 27 | 삭제 가능성 | P | 샘플 제거가 샘플 e2e 3개를 함께 지운다(`scripts/test-sample-removal.ts:52-54`). 제거 뒤 e2e는 돌지 않는다(FOLLOW-UP 09-07). 커밋된 로그를 다운스트림이 매번 지운다(11-09) |
| 28 | 회복 가능성 (깊게) | P | 깨진 SW를 `REMOVE_REGISTRATION` release로 해제하는 흐름이 chromium에서 통과. drill은 자산 누락을 FAIL로 잡는다(재현). provider 전환 뒤 smoke를 증거로 넣을 방법이 없다(11-02). 이전 release 재검증(`verify:promotion --archived`)의 system test가 main에서 실패한다(11-01) |
집계(적용 22개): 충족 3(6, 12, 16) · 부분 충족 18 · 미충족 0 · 미검증 0 · 적용 제외 1(11) · 다른 영역 6.
미충족이 없는 이유: 각 관점의 핵심 통제는 동작한다. 남은 결함은 특정 게이트·구성에 한정된다. 다만 11-01은 merge 게이트 하나를 통째로 빨갛게 만든다. 오케스트레이터가 종합 판정에서 21번을 미충족으로 볼 근거는 충분하다.
## 4. 설계 선택 설명 (41절)
### 4.1 drill 판정: 로컬에서 관측한 것만 PASS/FAIL, 나머지와 provider 범위는 항상 UNVERIFIED
1. **무엇이 필요한가:** 운영 승격 전에 런북 5개의 복구 수단이 동작한다는 증거. 소비자는 CI `production_gate`와 롤백하는 운영 담당자다.
2. **지킬 성질:** 관측하지 않은 것을 PASS로 적지 않는다. 로컬에서 확인할 수 있는 결함(자산 누락, tuple 불일치)은 FAIL로 끝낸다.
3. **현재 보장:** 3상태와 결합 규칙(`scripts/contracts/release-artifacts.ts:736-743`). record 스키마가 result와 개별 판정의 일치를 강제한다(`:771-787`). 자산 누락 FAIL을 재현했다. **보장하지 않는 것:** provider 전환, smoke, live traffic. 파일 내용 무결성(0바이트 엔트리는 UNVERIFIED). PASS 도달.
4. **대안:** (a) 현상 유지. (b) 외부 증거 파일을 받는 입력(hosting 헤더의 live 모드와 같은 방식). (c) 로컬 흉내: 두 release 디렉터리 + active pointer + 브라우저 smoke(지난 11-01의 제안 2). (d) production·field 단계를 기본으로 끄고 켤 조건을 문서화.
5. **대안별 비용:** (a) 비용 0, 정직, 단계가 항상 빨갛다. (b) 스키마·검증 코드가 늘고 증거 위조 방지(서명·run id 연결)가 필요하다. 대신 PASS가 가능하고 다운스트림 구현이 한 형식으로 모인다. `scripts/lib/provider-evidence.ts`의 서명 검증을 재사용할 수 있다. (c) 템플릿 안에서 절반을 검증하지만 production job에 브라우저가 필요하고 provider 특성은 여전히 모른다. (d) 가장 싸지만 게이트가 문서로 물러난다.
6. **현재 조건에서의 판단:** 기록된 의도(D-14, `SPEC.md:58`)는 "거짓 PASS 제거"와 "운영 승격은 provider 증거를 요구"다. (a)는 앞의 것을 달성했다. 뒤의 것은 증거를 넣을 입구가 없어 구현되지 않았다. 리뷰어 추론: (a)는 중간 상태로는 맞다. 하지만 넘을 방법이 없는 게이트를 기본값으로 복제하는 비용이 크다. (b)나 (d)로 끝을 맺어야 한다(11-02).
7. **재검토 조건:** 공식 지원 호스팅 provider가 정해지면 (c)를 넘어 실제 전환 drill이 가능하다. CI(U-1)가 켜지고 production 단계를 실제로 쓰는 다운스트림이 생기면 (b)가 우선이다.
### 4.2 두 빌드 브라우저 harness: repo를 임시 폴더에 복사하고 소스 문자열을 치환해 두 번 빌드
1. **무엇이 필요한가:** 신·구 빌드 공존(구 탭, SW 업데이트, 깨진 SW 복구)을 실제 브라우저와 실제 production build로 확인한다. 작업 트리와 e2e 서버가 쓰는 `dist`는 건드리지 않는다.
2. **지킬 성질:** 제품의 빌드 스크립트를 그대로 쓴다(`service-worker-update.spec.ts:264-271`). 두 빌드가 실제로 다르다(`:239`, `old-tab-chunk-recovery.spec.ts:88-89`). 치환이 조용히 무효가 되지 않는다.
3. **현재 보장:** `replaceOnce`가 정확히 1회 일치를 요구한다(`tests/e2e/support/service-worker-builds.ts:83-93`). 그래서 조용한 무효 치환은 없다. **보장하지 않는 것:** 소스가 다른 모양(이미 ACTIVE, 수정된 fetch 처리)이면 준비 단계에서 실패한다. SW 쪽 helper는 실패 시 복사본을 지우지 않는다.
4. **대안:** (a) 현상 유지. (b) helper가 현재 선택을 읽고 필요한 치환만 한다(이미 ACTIVE면 건너뜀). 캐시 단언은 빌드가 만든 SW 자산 목록과 비교한다. (c) 빌드 입력(환경변수·define)으로 변형을 주입한다. (d) 제품별 fixture 설정 파일을 둔다.
5. **대안별 비용:** (a) 단순하지만 템플릿 기본값에서만 동작한다. (b) 수십 줄. 전제 1·2가 풀리고 3·4(fetch 한 줄, host 함수 선언)는 남는다. (c) 제품 코드에 테스트용 입구가 생긴다. "설정 문자열로 경로를 만들지 않는다"는 정적 선택 원칙(`src/features/installed-runtime-capabilities.ts:18-20`)과 부딪힌다. (d) 개념이 하나 늘어난다.
6. **현재 조건에서의 판단:** 정적 선택 원칙(기록된 의도)을 지키려면 소스를 편집하는 방식이 맞다. 문제는 방식이 아니라, 전제를 적지 않고 템플릿 기본값만 가정한 것이다. (b)와 전제 주석으로 충분하다(11-03, 리뷰어 추론).
7. **재검토 조건:** 다운스트림 두 곳 이상이 같은 spec을 고쳐 쓰게 되면 (d)를 검토한다. 템플릿의 SW 기본값이 ACTIVE로 바뀌면 전제 1이 뒤집힌다.
### 4.3 lab 성능 게이트: 절대 예산, 5회 cold 중앙값, CPU 4배·네트워크 제한, 페이지 안의 시계
1. **무엇이 필요한가:** 릴리스 후보가 LCP·CLS·route 전환 예산을 넘지 않는다는 판정(FE-GATE-026).
2. **지킬 성질:** 같은 빌드면 같은 판정. 측정 대상이 그 빌드. 측정 조건 기록.
3. **현재 보장:** 대상 빌드 확인, 포트 충돌 거부, 조건과 모든 표본 기록, 중앙값 판정. **보장하지 않는 것:** 러너 부하에 따른 판정 안정(PASS 2 / FAIL 3 재현). INP 자체. 클릭의 Event Timing 길이(`clickEventDurationMs`, 이번 중앙값 48ms)는 기록만 하고 판정하지 않는다. 판정하는 interaction에는 lazy chunk 다운로드가 들어간다(`docs/operations/performance-evidence.md:52-55`에 적혀 있음).
4. **대안:** (a) 현상 유지. (b) 측정 전 부하 가드: 기준을 넘으면 UNVERIFIED(exit 3). (c) 같은 job에서 기준 빌드와 A/B로 재고 차이로 판정. (d) 반복 수를 9~15회로. (e) lab은 참고용으로 내리고 field가 판정.
5. **대안별 비용:** (b) 코드 몇 줄. drill·hosting과 같은 3상태 패턴이다. 부하가 높으면 결과가 없다. (c) 시간 2배, 러너 속도 차이를 상쇄한다. (d) 분산은 줄지만 모든 표본이 함께 느려지는 부하 편향은 못 없앤다. 이번 두 번째 실행은 표본 5개가 모두 195ms 이상이었다. (e) field 단계는 11-02 때문에 CI에서 닿지 않아 지금은 대체가 안 된다.
6. **현재 조건에서의 판단:** 러너 조건은 미정이다(U-1). (b)가 가장 작고 정직하다(리뷰어 추론).
7. **재검토 조건:** 전용·고정 러너가 생기면 (a)를 유지할 수 있다. 기준 빌드 산출물을 캐시할 수 있으면 (c)가 낫다.
## 5. 발견 사항 (36.3)
심각도 분포: Critical 0 · High 1 · Medium 3 · Low 5.
### 11-01 `tests/system`의 기대 문자열이 13-04 뒤의 출력과 달라, merge 게이트 FE-GATE-013(security)이 main에서 항상 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 26, 9 (+30.8) |
| 근거 | `scripts/verify-exact-promotion-bundle.ts:78`은 `Exact promotion bundle verification (${freshness}): PASS`를 출력한다(`839205c`, 13-04에서 바뀜). `tests/system/ci-runner/ci-artifact-contract.test.ts:1259`는 `"Exact promotion bundle verification: PASS"`를 기대한다. `test:system`은 FE-GATE-013의 명령이다(`config/ci/gates.json:232-233`, `:1987-1990`). FE-GATE-013은 `MERGE_READY`에 있다(`scripts/lib/promotion-readiness.ts:14`). CI merge 매트릭스에도 있다(`.gitea/workflows/quality-gates.yml:54`). **실행:** `.git`이 디렉터리인 clone(af3d8e6)에서 `check-system-test-prerequisites` PASS, `run-vitest run tests/system` → 2 failed / 110 passed. 이 케이스는 매번 실패했다. 기대값을 `(current)`가 들어간 문자열로 바꾸면 통과했다. 지난 라운드 검증 기록(`2026-09-25-maturity-review/README.md` 11절)과 이번 오케스트레이터 게이트 목록 모두 `test:system`이 없다 |
| 발생 조건 | FE-GATE-013을 실행하는 모든 CI 실행(PR·main), 로컬 `test:system` |
| 영향 | CI를 켜면(U-1) 모든 PR이 security 게이트에서 막힌다. 팀은 이 게이트를 무시하거나 끄게 된다. 그러면 샌드박스·아카이브 검증의 실제 회귀가 같은 빨간 결과에 섞여 보이지 않는다. 제품 repo 2곳도 이 커밋을 받았고, 두 동기화 기록의 게이트 표에 `test:system`이 없다 |
| 심각도·우선순위 | High · P1 — 지원하는 CI 조건에서 merge 게이트 하나가 결정적으로 실패한다. CI를 켜기 전에 고쳐야 한다. 수정은 한 줄이다. 지난 라운드는 같은 성격의 10-01("피해가 개발·CI 비용에 한정, 수정 비용 작음")을 Medium으로 조정했다. 일관성을 맞추려면 오케스트레이터가 조정할 수 있다 |
| 통제·증거 | 목표 M3 / 확인 M3(검사는 있음), 다만 라운드 검증이 결과를 보지 않아 실제 효과는 없었다 · E3 |
| 확실성과 남은 가정 | 결정적 실패다. 같은 파일의 cgroup 테스트 실패는 다른 원인이다(11-06). CI 러너가 systemd·bwrap·cgroup v2 전제를 만족하는지는 U-1 범위다 |
| 결정의 근거 | 적용 제외 — 기대 문자열 한 줄이 출력 변경을 따라가지 못한 단순 결함이다 |
| 이해 비용 | 적용 제외 — 지역 결함 |
| 최소 개선 방향 | 기대값을 `Exact promotion bundle verification (current): PASS`로 바꾼다. `--archived` 경로 케이스를 하나 더한다. 라운드 검증 목록(오케스트레이터 게이트 표)에 `test:system`을 넣는다 |
| 대안 비교 | 적용 제외 — 계약 위반을 바로잡는 단순 수정 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 전제를 갖춘 호스트에서 `test:system`이 이 케이스로 실패하지 않는다. 다음 라운드 게이트 기록에 `test:system` 결과가 있다 |
| 검증 방법 | clone에서 `node scripts/run-vitest.ts run tests/system/ci-runner/ci-artifact-contract.test.ts -t 'downstream CLI'` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-02 운영 drill은 어떤 입력으로도 PASS할 수 없어, production 단계와 field 단계가 구조적으로 막혀 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 7, 18, 28, 21, 5 (+30.8) |
| 근거 | FE-RB-002~005는 `providerVerificationRequired: true`가 상수다(`scripts/drill-runbook.ts:240`, `:270`, `:312`, `:353`). 이 값이 true면 결과는 무조건 UNVERIFIED다(`scripts/contracts/release-artifacts.ts:741`). FE-RB-001은 관측 불가 항목 3개와 `negativeFixtureFailedAsExpected: "UNVERIFIED"`가 무조건이다(`drill-runbook.ts:179-190`). drill은 runbook id와 `--release-root`만 읽는다(`:437-450`). provider 증거를 넣는 인자·환경변수·파일이 없다. 대조: hosting 헤더 게이트는 `HOSTING_BASE_URL` live 모드로 PASS할 수 있다(`docs/operations/release-cache-rollback.md:57-62`). CI는 FE-GATE-021~025를 `expect: "pass"`로 돌리고(`config/ci/gates.json:484-494`, `:530-573`), `field_gate`는 `needs: production_gate`다(`.gitea/workflows/quality-gates.yml:416-418`). 단위 테스트가 "PASS가 아니다"를 고정한다(`tests/unit/runbook-drill.test.ts:100-104`). 문서는 "the production stage stays open. That is the intended result"(`docs/operations/ci-quality-gates.md:331-333`), "It ends UNVERIFIED until the provider switch and smoke are recorded"(`release-cache-rollback.md:38-39`)라고 적는다. 기록 위치와 형식은 어디에도 없다. **실행:** 완전한 빌드에서 5개 모두 exit 3 |
| 발생 조건 | stage `production`·`field`로 workflow를 돌릴 때마다 |
| 영향 | 템플릿 그대로는 `PROD_PROMOTION_READY`와 `FIELD_SLO_READY`가 참이 될 수 없다(`promotion-readiness.ts:56-58`). FE-GATE-018은 CI에서 한 번도 실행되지 않는다. 다운스트림은 (a) 빨간 단계를 무시하거나, (b) 각자 입력 경로를 만들거나, (c) 단계를 끈다. (a)는 게이트 무시를 습관으로 만든다. (b)는 제품마다 형식이 갈라진다. 지난 11-01의 거짓 PASS는 사라졌다. 이 발견은 그 반대편의 빈칸이다 |
| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 운영 단계 게이트 전체가 쓸 수 없는 상태로 복제된다 |
| 통제·증거 | 목표 M3 / 확인 M2(로컬 판정은 정직, PASS 경로 없음) · E2(단위 테스트) + E3(drill 실행) |
| 확실성과 남은 가정 | PASS가 불가능하다는 것은 코드로 확정이다. "production 단계는 열린 채로 둔다"는 기록된 의도다. 증거 형식을 템플릿이 정해야 하는지는 판단의 문제다. 리뷰어 추론: 형식만이라도 템플릿이 정해야 다운스트림 구현이 갈라지지 않는다 |
| 결정의 근거 | 4.1절. 확인한 사실(상수·결합 규칙), 기록된 의도(D-14, `SPEC.md:58`), 추론(형식 부재의 비용)을 나눠 적었다 |
| 이해 비용 | production 단계를 켜려는 운영 담당자가 drill 소스, record 스키마, workflow, promotion formula 네 곳을 읽고 PASS 경로가 없다는 것을 스스로 알아내야 한다 |
| 최소 개선 방향 | drill에 외부 증거 입력 하나를 둔다. 예: `--provider-evidence <record.json>`(releaseId, 전환 시각, smoke 결과, run id 또는 서명). 스키마를 통과하고 releaseId가 맞으면 해당 관측 불가 항목을 PASS/FAIL로 바꾼다. 또는 production·field 단계를 기본으로 끄고, 켤 때 필요한 것을 문서의 체크리스트로 둔다 |
| 대안 비교 | 4.1절 (a)~(d). (b) 외부 증거는 PASS를 가능하게 하지만 검증 코드가 는다. (d) 단계 끄기는 가장 싸지만 게이트가 문서로 물러난다 |
| 단순화의 보존 조건 | 로컬에서 관측하지 못한 항목을 PASS로 적지 않는다(D-14). 자산 누락은 계속 FAIL이다 |
| 비용·부작용 | 입력 스키마·검증·테스트. 운영 담당자의 증거 생성 절차 |
| 재검토 조건 | 공식 지원 호스팅 provider가 정해지면 drill이 전환·smoke를 직접 할 수 있다 |
| 완료 기준 | 유효한 provider 증거를 주면 FE-RB-005가 PASS다. releaseId가 다르거나 만료된 증거는 PASS가 아니다. 또는 production·field 단계가 기본 꺼짐으로 문서화되고, `field_gate`가 도달할 수 없는 선행 조건에 묶이지 않는다 |
| 검증 방법 | 단위 테스트에 증거 있음·없음·불일치 3케이스 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-03 SW e2e 두 spec의 전제가 소스 문자열 치환과 단언 안에 숨어 있어, 문서대로 SW를 켜기만 해도 준비 단계에서 실패하고 무엇을 고칠지 알려 주지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 3, 5, 18, 28, 20 (+30.5) |
| 근거 | 전제는 네 개다. ① 선택 줄이 정확히 `const SERVICE_WORKER: InstalledServiceWorkerSelection \| null = null;`이다(`tests/e2e/support/service-worker-builds.ts:125-129`, 없으면 `:89-91`에서 예외). ② 캐시는 `dist/assets/*` 전부이고 그 밖은 없다(`service-worker-update.spec.ts:86-90`, `:124`). `PWA_STATIC_ASSETS` 기본 목록과 Vite 기본 `assets/` 폴더를 가정한다(FOLLOW-UP 06-08과 같은 가정). ③ SW fetch 처리의 한 줄(`service-worker-recovery.spec.ts:35-39`). ④ `createServiceWorkerRuntimeHost` 선언 문자열(`service-worker-builds.ts:130-136`). spec 머리 주석은 ①을 설명하지만(`service-worker-update.spec.ts:15-24`), 제품이 이미 ACTIVE일 때 어떻게 되는지와 ②~④는 전제로 적지 않는다. SW 켜기 체크리스트(`docs/architecture/optional-adapter-recipes.md:109-131`)와 선택 SSOT 주석(`src/features/installed-runtime-capabilities.ts:29-30`)은 이 spec을 언급하지 않는다. **실행:** worktree에서 체크리스트 1단계(선택을 `ACTIVE`로)만 적용 → chromium에서 SW spec 6개 중 2 failed, 4 did not run. 메시지는 `Expected exactly one "const SERVICE_WORKER: … = null;" in /tmp/ca-sw-builds-…/src/features/installed-runtime-capabilities.ts.`였다. **다운스트림:** memento-frontend `chore/template-sync-v0.2.0:docs/operations/template-sync-2026-09-29.md` "Introduced and escalated"에 두 spec이 "switches the template's null worker selection on by source replacement and expects the hashed-only asset set" 때문에 실패했다고 적혀 있다. 제품은 worker를 ACTIVE로 내보내고 `index.html`과 사진을 미리 캐시한다. e2e는 67 passed / 3 failed / 4 did not run이고, 후속 5번 "Adapt the template's Service Worker e2e specs to the product's PWA asset set"으로 미뤘다 |
| 발생 조건 | 다운스트림이 SW를 켜거나, 선택 줄 모양을 바꾸거나, 사전 캐시 목록을 넓히거나, fetch 처리를 고칠 때 |
| 영향 | SW를 켠 제품에서, SW 업데이트·구 자산 응답·kill switch를 실제 브라우저로 확인하는 유일한 spec이 빨갛게 된다. 제품은 이 spec을 quarantine하거나 지우기 쉽다. 그러면 보호가 템플릿(SW 꺼짐)에서만 돌고, SW가 실제로 켜진 곳에서 빠진다 |
| 심각도·우선순위 | Medium · P2 — 피해는 테스트 보호 상실이다. 제품 repo 한 곳에서 이미 일어났다 |
| 통제·증거 | 목표 M3 / 확인 M2(템플릿 기본 구성에서만 M3) · E3(재현 + 다운스트림 기록) |
| 확실성과 남은 가정 | ①은 재현했다. ②는 memento 기록과 코드 읽기로 확인했고 재현하지 않았다. ③·④는 코드 읽기다 |
| 결정의 근거 | 4.2절. 소스 편집 방식은 정적 선택 원칙(기록된 의도)에 맞다. 문제는 전제를 적지 않은 것이다(추론) |
| 이해 비용 | SW를 켠 제품 개발자가 spec 2개, helper 1개, SW 자산 생성기, SW 엔트리의 정확한 문자열을 읽고 전제 4개를 거꾸로 찾아야 한다. memento는 이를 "PWA가 무엇을 증명해야 하는지 결정이 필요"로 미뤘다 |
| 최소 개선 방향 | (1) helper가 현재 선택을 읽고, 이미 `ACTIVE`면 치환을 건너뛴다. (2) 캐시 단언을 `dist/assets` 목록 대신 빌드가 만든 SW 자산 목록(`.generated/frontend-runtime/service-worker-assets.ts`, `scripts/generate-service-worker-assets.ts:27`)과 비교한다. (3) 두 spec 머리에 "전제와 바꿀 곳" 3~4줄. (4) SW 켜기 체크리스트에 "e2e 두 spec이 제품 구성에서 도는지 확인" 한 줄 |
| 대안 비교 | 4.2절 (a)~(d). 빌드 입력 주입(c)은 정적 선택 원칙과 부딪혀 제외한다 |
| 단순화의 보존 조건 | A→B 업데이트, 서버에서 지운 구 청크를 이전 캐시가 응답, 깨진 worker를 `REMOVE_REGISTRATION`이 해제하는 것을 실제 브라우저로 확인하는 성질은 그대로 둔다 |
| 비용·부작용 | helper 수십 줄, 단언 1개 변경 |
| 재검토 조건 | 템플릿의 SW 기본값이 ACTIVE로 바뀌면 전제 ①이 뒤집힌다 |
| 완료 기준 | 선택을 ACTIVE로 바꾼 사본에서 두 spec이 준비 단계를 통과한다. 사전 캐시에 `index.html`을 더한 사본에서 캐시 단언이 생성된 목록 기준으로 통과한다 |
| 검증 방법 | 위 두 변이를 worktree에서 chromium으로 실행한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-04 lab 성능 게이트(FE-GATE-026)는 중앙값 판정도 같은 빌드에서 뒤집힌다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 14, 10, 21, 18 |
| 근거 | 5회 cold 측정의 중앙값으로 판정한다(`scripts/lib/lab-performance.ts:36`, `scripts/test-performance.ts:189-198`). CPU 4배 감속·네트워크 제한을 건다(`:91-98`). interaction은 클릭부터 대상 heading이 DOM에 들어올 때까지이고 lazy chunk 다운로드가 들어간다(`:119-146`). loadavg는 기록만 하고(`:188-191`, `:209`) 판정에 쓰지 않는다(`scripts/lib/performance-budgets.ts:35-64`). 예산은 interaction 200ms, LCP 2,500ms다(`config/performance/budgets.json:7-11`). 문서는 i5-10400F에서 "중앙값 판정은 두 번 모두 통과였다"고 적는다(`docs/operations/performance-evidence.md:60-65`). **실행**(같은 빌드, Core Ultra 7 155H 22스레드, loadavg 16~22): 5번 실행해 PASS 2 / FAIL 3. interaction 중앙값 173~364ms(표본 149~440ms), LCP 중앙값 2,224~2,728ms. 실패 3번 중 2번은 LCP도 예산을 넘었다 |
| 발생 조건 | 공유 러너, 다른 작업과 겹친 러너, 느린 CPU |
| 영향 | 릴리스 게이트 판정이 코드가 아니라 러너 상태로 바뀐다. 다시 돌려 통과시키면 숨은 재시도가 된다. 반대로 실제 회귀가 "러너 탓"으로 넘어간다. 지난 11-07의 완료 기준("뒤집힐 때 분산이 증거에 남는다")은 충족하지만, 게이트는 여전히 뒤집힌다 |
| 심각도·우선순위 | Medium · P2 — 사용자 피해는 없다. 릴리스 판정의 신뢰도 문제다. CI 러너 조건(U-1)을 모른다 |
| 통제·증거 | 목표 M3 / 확인 M2 · E3 |
| 확실성과 남은 가정 | 부하가 있는 호스트에서만 확인했다. 조용한 러너에서 판정이 안정적인지는 미확인이다. 다른 에이전트 부하가 실제 CI보다 클 수 있다 |
| 결정의 근거 | 4.3절 |
| 이해 비용 | 실패를 본 사람이 `lab.json`의 `context.runner.loadAverage`와 표본을 직접 해석해 "러너 탓인지"를 판단해야 한다 |
| 최소 개선 방향 | 측정 전 `loadavg[0] / logicalCpus`가 기준(예: 0.5)을 넘으면 `UNVERIFIED`(exit 3)로 끝낸다. drill·hosting과 같은 3상태 패턴이다 |
| 대안 비교 | 4.3절 (a)~(e). 반복 수 늘리기(d)는 모든 표본이 함께 느려지는 경우를 못 막는다 |
| 단순화의 보존 조건 | 측정 조건 기록, `--strictPort`, 서빙 빌드 확인은 그대로 둔다 |
| 비용·부작용 | 부하 기준 값을 정해야 한다. 부하가 높으면 결과가 없어 재실행이 필요하다 |
| 재검토 조건 | 전용 러너 라벨이 생기면 부하 가드는 필요 없어질 수 있다 |
| 완료 기준 | 같은 빌드를 부하 조건을 바꿔 10회 돌렸을 때 PASS·FAIL이 뒤집히지 않는다. 기준을 넘은 실행은 UNVERIFIED로 남는다 |
| 검증 방법 | CPU 부하를 준 상태와 조용한 상태에서 각 5회 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-05 기능 규모 기준선이 현재 코드와 달라졌는데, 측정 기록에 소스 커밋이 없어 알 수 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 13, 14, 9, 24 |
| 근거 | 기준선 `config/scale/feature-shape-growth.json`은 2026-09-27T04:03Z(13:03 KST)에 쟀다. 결과에 커밋·입력 트리 해시가 없다(`scripts/scale/measure-feature-shape-growth.ts:232-248`). 테스트는 모양만 본다(`tests/unit/feature-shape-growth.test.ts:62-99`). 측정 뒤 lane H 병합(`2b2cabb`, 13:19 KST, 08-04 문구 catalog 포함)과 08-13(`d7b81c6`)이 reference 기능을 바꿨다. **재측정**(af3d8e6, `--sizes=0,25 --repeats=1`): 기능 0개 초기 JS 203,481 B(기준선 200,001 B). 25개 284,609 B → 기능당 약 3,245 B(기준선 2,907 B, +12%). lazy는 기능당 약 5,048 B(기준선 6,800 B, −26%). instantiations는 기능당 115,992(기준선 114,680, 차이 작음). `config/scale/feature-shape-ceilings.json:24-26`은 "about 2.9 KB gzip per feature", "exceeded after a few more reference-shaped features"라고 적는다. 현재 여유는 204,800 − 203,481 = 1,319 B다. reference 모양 기능 하나면 넘는다 |
| 발생 조건 | 기준선 측정 뒤 기능 모양이나 부트 로딩이 바뀌는 변경 |
| 영향 | 다운스트림이 "기능당 2.9KB, 몇 개 더 가능"으로 계획한다. 실제로는 첫 기능에서 `check:bundle`이 실패한다. FOLLOW-UP P1과 같은 결론인데, 규모 문서의 표현이 이를 흐린다. 기준선이 어느 코드를 쟀는지 모르니 다음 측정과 비교할 수 없다 |
| 심각도·우선순위 | Low · P2 — 수치 차이는 10~30%이고 결론(초기 JS가 먼저 한계)은 같다. 규모가 이 템플릿의 선언된 목표 축이라 P2다 |
| 통제·증거 | 목표 M3 / 확인 M1(기준선 존재, 어긋남 검출 없음) · E3 |
| 확실성과 남은 가정 | 1회 재측정이다. 바이트와 instantiation 수는 결정적이라 반복하지 않았다. 시간 값은 비교하지 않았다 |
| 결정의 근거 | 적용 제외 — 기록 필드 누락과 오래된 수치의 단순 결함이다 |
| 이해 비용 | 기준선을 읽는 사람이 측정 시점의 코드를 git 이력과 시각으로 추정해야 한다 |
| 최소 개선 방향 | 측정 결과에 `git rev-parse HEAD`를 넣는다. 기준선을 현재 코드로 다시 잰다. ceilings의 "a few more"를 수치 대신 "`check:bundle` 여유 ÷ 기능당 증가"로 적는다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 필드 1개, 재측정 수 분(100개 포함 시 더 김) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 기준선에 소스 커밋이 있다. 그 커밋에서 다시 재면 바이트 수가 같다 |
| 검증 방법 | 기준선 커밋에서 `--sizes=0,25 --repeats=1`로 재측정해 비교한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-06 `tests/system`의 cgroup 테스트는 부하가 있으면 이미 끝난 프로세스를 조회하다 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 10, 8 |
| 근거 | `tests/system/ci-runner/ci-artifact-contract.test.ts:749-790`. provider는 1.5초 뒤 끝난다(`:759`). `systemctl show`와 cgroup 파일 읽기 뒤에 `showProcessArguments(execution.child.pid)`를 부른다(`:790`). 이 함수는 `/proc`에서 못 읽으면 `ps`를 부르고, 실패하면 예외를 던진다(`:1860-1871`). 같은 파일은 이런 레이스를 알고 샘플러(`recordProviderProcessTree`)를 두었지만(`:1875-1900`), 이 단언은 샘플이 아니라 지금 시점 조회다. **실행:** clone, loadavg 13~20에서 3/3 실패(`ps failed:`, 각 15~17초) |
| 발생 조건 | 러너 부하 |
| 영향 | 11-01을 고쳐도 FE-GATE-013이 부하에서 무작위로 빨갛다. FOLLOW-UP 3절 P3(같은 파일의 시간 초과)와 같은 계열이다 |
| 심각도·우선순위 | Low · P2 — 테스트만의 문제다. CI를 켜기 전에 처리한다 |
| 통제·증거 | M2 · E3(부하 조건). 조용한 호스트 결과는 미확인 |
| 확실성과 남은 가정 | 부하와의 관계는 추론이다. 조용한 호스트에서 통과하는지 확인하지 못했다 |
| 결정의 근거 | 적용 제외 — 테스트 레이스의 단순 결함이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 이 단언을 이미 있는 `recordProviderProcessTree` 샘플(프로세스가 살아 있던 동안의 argv)에 대해 한다 |
| 대안 비교·보존 조건·재검토 | 적용 제외 |
| 비용·부작용 | 수 줄 |
| 완료 기준 | loadavg 20 부근에서 5회 연속 통과 |
| 검증 방법 | `-t 'aggregate cgroup'`로 부하를 준 상태에서 5회 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-07 두 빌드 준비 helper가 두 벌로 갈라져, SW 쪽은 준비에 실패하면 임시 복사본을 남긴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 23, 22, 20 |
| 근거 | `tests/e2e/support/service-worker-builds.ts`와 `tests/e2e/support/fixture-builds.ts`가 같은 일(repo 복사 → `node_modules` 링크 → 문자열 치환 → 두 번 빌드)을 따로 한다. `replaceOnce`(`service-worker-builds.ts:83-93`)와 `editOnce`(`fixture-builds.ts:40-50`)가 같다. `run`도 같다(`:95-106`, `:52-63`). 갈라진 곳: SW 쪽 제외 목록에 `.tmp`가 없다(`:39-47` 대 `:18-27`). fixture 쪽은 실패하면 복사본을 지우고(`:69-90`), SW 쪽은 지우지 않는다(`:113-146`). **실행:** 11-03 실험에서 준비가 실패하자 `/tmp/ca-sw-builds-*` 2개(각 18MB)가 남았다 |
| 발생 조건 | 한쪽만 고치는 변경, SW spec 준비 실패 |
| 영향 | 한쪽 수정이 다른 쪽에 반영되지 않는다. 실패한 실행마다 /tmp에 repo 복사본이 쌓인다(FOLLOW-UP 00-03과 같은 종류) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2 · E3 |
| 확실성과 남은 가정 | 누수는 재현했다. `.tmp` 차이의 실제 영향(개발자 `.tmp`에 Node 설치가 있으면 복사량이 는다)은 추론이다 |
| 결정의 근거 | 현재 선택은 "SW 전용 helper"와 "일반 helper"의 병존이다. 기록된 이유는 없다. SW helper가 먼저 생겼고(R3-6) 일반 helper가 나중에 11-05에서 생겼다(추론, 파일 주석 기준) |
| 이해 비용 | 두 빌드 spec을 새로 쓰는 사람이 어느 helper를 쓸지, 왜 둘인지 알 수 없다 |
| 최소 개선 방향 | SW helper가 `prepareFixtureBuilds`를 쓰고, SW 선택·probe 치환만 `edit`로 넘긴다. `startBuildServer`는 공용 파일로 옮긴다 |
| 대안 비교 | 현상 유지: 파일 2개, 갈라짐 계속. 통합: 새 개념 없이 중복 약 60줄이 준다. 통합이 더 작다 |
| 단순화의 보존 조건 | 작업 트리·`dist`를 건드리지 않는다. 빌드 ID 주입, `beforeBuild`가 빌드 직전에 돌고 다음 빌드까지 남는 순서 |
| 비용·부작용 | SW spec 2개와 old-tab·boot spec의 import 수정 |
| 재검토 조건 | 두 helper가 서로 다른 복사 규칙을 가져야 하는 이유가 생기면 다시 나눈다 |
| 완료 기준 | 두 빌드 준비 코드가 한 곳에 있다. 준비 실패 뒤 /tmp에 남는 것이 없다 |
| 검증 방법 | 11-03의 ACTIVE 변이로 준비를 실패시키고 /tmp를 확인한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-08 drill의 "상수 판정 금지" 테스트가 옛 모양(`true`)만 찾아, 상수 `"PASS"`를 통과시킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 24, 28 |
| 근거 | `tests/unit/runbook-drill.test.ts:123-128`은 `assertion(…, true)`, `Asserted: true`, `injectedMountFailure = true` 정규식만 검사한다. 판정 타입은 이제 `"PASS" \| "FAIL" \| "UNVERIFIED"`라서 `true`는 타입 검사가 이미 막는다(`scripts/drill-runbook.ts:31-35`). **변이:** FE-RB-001 "product root mount"와 FE-RB-002 "critical route smoke"를 `assertion(…, "PASS")`로 바꿔도 9/9 통과했다. FE-RB-001 record에 `product root mount: PASS`가 남았다. drill 전체 결과는 다른 UNVERIFIED 때문에 여전히 UNVERIFIED였다 |
| 발생 조건 | 관측하지 않은 항목을 상수 PASS로 바꾸는 변경 |
| 영향 | 증거 record에 관측하지 않은 PASS 항목이 들어가도 테스트가 모른다. D-14의 "코드에 상수 판정을 두지 않는다"를 지키는 검출 장치가 사실상 없다. 행동 테스트가 일부를 대신 잡는다: FE-RB-001의 UNVERIFIED 항목을 전부 PASS로 바꾸면 `:100-104`가 잡는다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M3 / 확인 M2 · E3(변이) |
| 확실성과 남은 가정 | 변이 결과로 확정이다 |
| 결정의 근거 | 적용 제외 — 검사 대상이 타입 변경을 따라가지 못한 단순 결함이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 정규식을 `assertion\([^)]*,\s*"PASS"\s*\)`와 `Asserted:\s*"PASS"`로 바꾼다. 더 나은 방법은 PASS를 내는 항목마다 음성 입력 케이스를 두는 것이다(자산 누락 케이스처럼) |
| 대안 비교·보존 조건·재검토 | 적용 제외 |
| 비용·부작용 | 수 줄 |
| 완료 기준 | 위 변이가 테스트에서 실패한다 |
| 검증 방법 | 같은 변이를 다시 넣고 `node_modules/.bin/vitest run tests/unit/runbook-drill.test.ts` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-09 규모 tier 실행 로그가 커밋돼 있어, merge 게이트를 로컬에서 돌리면 추적 파일이 바뀌고 커밋된 로그는 현재 tier와 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 20, 27 (+30.5) |
| 근거 | `git ls-files artifacts`: `artifacts/scale/{pr,main,nightly,release}` 35개, `artifacts/quality/extreme-scale-gates` 24개, `artifacts/phase5` 4개가 커밋돼 있다. `scripts/scale/run-scale-profile.ts:20-21`이 `artifacts/scale/<tier>/<step>.log`를 쓴다. `.gitignore:11-14`는 json·xml·txt만 무시한다. **실행:** `run-scale-profile.ts pr`(FE-GATE-005의 `check:scale:pr`) 한 번에 추적 로그 3개가 바뀌고 `composition-s0-s2.log`가 새로 생겼다. 커밋된 pr 로그는 이 단계를 넣기 전(지난 11-03 수정 전)의 것이다. **다운스트림:** 두 제품 모두 이 63개를 "아무도 읽지 않는 템플릿 기계의 기록"으로 지웠다(memento 기록 "What was deliberately not kept", tech-log 기록 66행) |
| 발생 조건 | 로컬에서 `check:scale:*`·`verify:extreme-scale` 실행, 템플릿 동기화 |
| 영향 | 게이트를 돌리면 git status가 더러워진다. 커밋된 로그가 현재 tier 구성·기계와 다른 증거처럼 보인다. 동기화할 때마다 다운스트림이 지워야 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E3 |
| 확실성과 남은 가정 | 이 로그를 읽는 코드가 없다는 것은 두 제품 기록의 확인 결과다. 이번에 따로 grep하지는 않았다 |
| 결정의 근거 | 적용 제외 — 산출물 관리의 단순 누락이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 이 로그들을 지우고 `.gitignore`에 `artifacts/**/*.log`를 넣는다. 필요한 요약은 `docs/reviews/2026-09-23-extreme-scale-acceptance.md`에 있다 |
| 대안 비교·보존 조건·재검토 | 적용 제외 |
| 비용·부작용 | 파일 63개 삭제 |
| 완료 기준 | `git ls-files 'artifacts/**/*.log'`가 비어 있다. `check:scale:pr` 뒤 git status가 깨끗하다 |
| 검증 방법 | 위 명령 2개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
### 6.1 지난 라운드(2026-09-25) 영역 11 발견
| 지난 ID | 내용 | 현재 | 근거 |
|---|---|---|---|
| 11-01 | drill 거짓 PASS | 해소 | `dist/assets/*.js` 삭제 → FE-RB-002·005 FAIL(재현). 대신 PASS 경로 부재(새 11-02), 죽은 가드(새 11-08) |
| 11-02 | axe·visual이 로딩 화면 검사 | 해소 | h1 대기(`accessibility.spec.ts:33-49`, `platform.visual.spec.ts:8-10`). 변이 5/5·5/5. 상태 화면 기준 이미지에 본문이 있다 |
| 11-03 | 규모 게이트 CPU 결합·CI 없음 | 해소 | pr tier가 FE-GATE-005에 있다. CPU 경합에서 10/10 |
| 11-04 | stub 기능 규모 증거 | 해소(범위 표기), 수치는 낡음 | 실제 모양 기능 측정과 검증·비검증 표. 현재 코드와 차이(새 11-05) |
| 11-05 | 기본 구성 구 탭 복구 미확인 | 해소 | `old-tab-chunk-recovery.spec.ts` chromium 통과. release 테스트 이름·주석을 fixture 계약으로 낮췄다(`old-asset-reachability.test.ts:5-12`) |
| 11-06 | 핵심 흐름 E2E가 약함 | 해소 | 스키마 변이가 spec 단언에서 실패. 저장 성공·429 재시도 E2E |
| 11-07 | lab 1회 측정·포트·시계 | 해소(완료 기준 충족), 판정은 여전히 뒤집힘 | 5회 중앙값·strictPort·페이지 시계. PASS 2 / FAIL 3(새 11-04) |
| 11-08 | `test.only`·quarantine 만료 | 해소 | 4개 설정 `forbidOnly`, 만료일 검사(`check-test-evidence.ts:302-304`). 주석 하나가 파일 전체 skip을 허용하는 점은 남았다(완료 기준 밖) |
### 6.2 `FOLLOW-UP.md` 중 이 영역 항목
| FOLLOW-UP 항목 | 결과 | 근거 |
|---|---|---|
| 5절 P2 `resumable-upload.spec.ts:7` 포트 하드코딩 | 유효 | 포트 4414로 돌리면 `requestfailed:POST:/uploads/create:net::ERR_FAILED`로 1건 실패(재현) |
| 5절 P3 SW 업데이트 spec의 route chunk 변경을 helper 옵션으로 | 유효 | 여전히 spec 안에서 not-found 페이지에 export를 덧붙인다(`service-worker-update.spec.ts:38-56`) |
| 5절 P3 fixture의 pnpm 설치 검사 끔(F-4) | 유효 | `scripts/lib/fixture-node-modules.ts:40-42` 그대로. 오늘 오케스트레이터가 worktree에서 pnpm이 공유 `node_modules`를 지우려 한 사례를 알렸다 |
| 5절 P3 00-03 남은 임시 폴더 | 판단 불가 | `/tmp`의 `repository-inventory-*`·`sw-assets-*` 324개가 모두 2026-09-29 생성이다(22개·5개씩 묶음). 두 테스트 모두 `afterEach`로 지운다. 어느 실행이 정리 없이 끝났는지 구분하지 못했다(영역 10). 이번 실험의 SW helper 누수는 11-07 |
| 3절 P3 `ci-artifact-contract.test.ts` 시간 초과 | 유효(형태가 바뀜) | 지금은 결정적 문자열 실패(11-01)와 부하 레이스(11-06)다. worktree 실행(loadavg 42)에서 30초 시간 초과도 1건 났다 |
| 4절 P2 06-08 `assets/` 하드코딩 | 유효(영역 06) | SW spec의 `hashedAssets`도 같은 가정이다(`service-worker-update.spec.ts:86-90`). 11-03에 포함 |
| 4절 P3 08-04 en-US 브라우저 검사가 목록·폼만 | 유효(영역 08) | `reference-form.spec.ts:55-81`은 목록과 폼만 본다 |
| 4절 P3 09-07 제거 검증이 e2e를 건너뜀 | 유효(영역 14) | 샘플 제거가 e2e 3개를 지우지만(`scripts/test-sample-removal.ts:52-54`) 제거 뒤 e2e는 돌지 않는다 |
| 1절 P1 초기 JS 예산 | 유효(영역 13) | 재측정: 기능 0개 초기 JS 203,481 B, 여유 1,319 B, reference 모양 기능당 약 3,245 B |
## 7. 미검증 목록
| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| Firefox·WebKit 실행 | 지시에 따라 chromium만 돌렸다 | 3엔진 `test:e2e`, `test:browser-capabilities` 1회 |
| e2e 전체, a11y 전체 태그, storybook spec | 필요한 spec만 돌렸다 | 조용한 호스트에서 `test:e2e`, `test:a11y`, `test:storybook` |
| CI 러너 결과(FE-GATE-008·013·026) | Gitea runner가 없다(U-1) | 같은 커밋의 CI 실행 기록 |
| lab 성능의 조용한 호스트 값 | 다른 에이전트 부하(16~22) | 부하 없는 기계에서 10회 |
| cgroup 테스트의 조용한 호스트 결과(11-06) | 같은 이유 | 부하 없는 기계에서 5회 |
| SW 전제 ②(해시 파일만 캐시)의 재현 | memento 기록과 코드 읽기로만 확인 | 사전 캐시에 `index.html`을 더한 사본에서 SW update spec 실행 |
| SW를 켠 구성의 `publicDir`(memento 후속 2) | 영역 06·13. 두 빌드 harness가 local 프로필로만 빌드해 `public/config.json`과 `dist/config.json`이 같을 수 있어 이 결함을 못 잡을 가능성이 있다(추론) | ACTIVE + 다른 배포 프로필로 두 빌드 후 `dist/config.json` 비교 |
| browser soak, main/nightly/release scale tier | 기준선 CPU(i5-10400F)와 긴 시간이 필요 | 기준선 기계에서 `check:scale:nightly` |
| 200개(한 context 가득)·400개 기능 측정 | 수 GB 메모리와 긴 시간 | 전용 기계에서 `measure-feature-shape-growth.ts --sizes=200` |
| provider 전환 실제 리허설 | repo 밖 | 스테이징 호스팅과 전환 절차 |
| git worktree에서 `test:system` 15건 실패의 처리 | bwrap `.git` 파일 문제로 확인했지만 영역 13 코드(`scripts/run-and-validate-provider.ts:271-276`)다 | 영역 13에서 판단 |
@@ -0,0 +1,351 @@
# 12 — 가드레일·CI 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 영역 판정(35.8): **조건부 사용 가능** — 로컬 게이트의 직접 경계 검사와 CI 계약 검사는 변이를 모두 잡았다. 다만 머지 시점 강제는 템플릿과 두 제품 repo 어디에도 없다(U-1). 새 N+1 게이트와 i18n 게이트는 다운스트림에서 오탐을 내고 실제 위반은 놓친다. 제품이 쓰기 전에 12-01·12-02를 고치거나 예외 절차를 문서로 정해야 한다.
## 0. 머리말
### 0.1 결론
- **지난 라운드 12번 발견 12건은 회귀가 없다.** 고친 규칙마다 변이를 넣었고 모두 실패했다.
- 생성기가 첫 게이트만 그리게 되돌리면 `check:ci`가 `FE-GATE-027`을 잡는다(지난 12-02).
- 게이트 밖 테스트 파일과 검사 스크립트를 새로 넣으면 `check:ci`가 잡는다(지난 12-04).
- feature 루트 재수출, `import.meta.glob`, 서브배럴, design-system deep import가 모두 `check:architecture`에서 실패한다(지난 12-03, 12-06, 12-07, 12-08).
- **`check:request-fanout`은 요청 사이의 의존을 보지 않는다(12-01, Medium).**
- "transport 이름의 변수에 대한 호출이 반복 구문 안에 글자로 있는가"만 본다.
- 그래서 tech-log의 커서 페이지네이션(최대 50페이지)을 N+1로 거부했다. 제품 repo의 merge 게이트 FE-GATE-010·005가 빨간 채로 남았다.
- 반대로 helper로 뺀 행별 호출, 이름이 다른 receiver, `useQueries` 행별 조회는 통과한다. 12개 probe 중 정상 4개를 모두 거부했고, 실제 N+1 8개 중 7개를 통과시켰다.
- 빠져나갈 길은 문서에 없는 같은 줄 주석뿐이다. 실패 메시지는 이유도 탈출 경로도 알려 주지 않는다.
- **`check:i18n`의 "하드코딩 문구" 검사는 "파일 안에 한글 문자가 있는가"다(12-02, Medium).** 한글 주석 한 줄이면 실패하고, 영어 하드코딩 문구는 통과한다. 로케일 정책을 바꿀 설정이 없어서 tech-log는 스크립트를 고쳤고 memento는 게이트를 빨간 채로 두었다.
- **feature 안의 layer 폴더 밖 폴더(`contracts/`, 새 이름)는 규칙이 없다(12-03, Medium).** feature presentation이 자기 `contracts/`나 `hooks/`의 재수출로 `src/adapters/http`에 닿아도 그래프·lint·tsc가 모두 통과한다. 규칙 주석은 "feature 안에서는 `adapters/`만 `src/adapters`에 닿는다"고 적는다.
- **CI 계약 크기가 기준선 파일 밖에 테스트 상수로 한 번 더 있다(12-04, Medium).** 문서 절차대로 게이트를 바꾸면 `check:ci`는 통과하고 `test:unit`이 실패한다. 제거 게이트는 이 테스트를 지운 뒤에 통과를 증명한다.
- Low 3건: 실행하지 않는 `dependency-cruiser` 의존성(12-05), Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 세는 목록 검사(12-06), 예외 목록에 담당·재검토 시점이 없음(12-07).
- **머지 시점 강제는 여전히 없다.** 2026-09-29 Gitea API로 다시 확인했다. 템플릿, tech-log, memento 모두 `has_actions: false`이고 main HEAD 상태가 0개다. repo 쪽은 고쳤고 README가 이 사실을 밝힌다. 남은 것은 사용자 몫 U-1이다.
### 0.2 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, 영역 12 |
| 커밋·작업 상태 | `main` / `af3d8e6`. 미커밋 변경은 리뷰 가이드 문서 2개뿐이다 |
| 목적과 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + SW. CI는 Gitea Actions용 생성 workflow |
| 읽은 코드·설정 | `scripts/check-request-fanout.ts` 전체, `scripts/check-i18n.ts` 전체, `scripts/check-ci-contract.ts` 전체, `scripts/lib/ungated-tests.ts`·`ungated-scripts.ts` 전체, `scripts/update-ci-contract-baseline.ts`, `scripts/contracts/ci-gates.ts:440-545`, `scripts/generate-ci-workflow.ts:190-210`·`:367-385`, `scripts/check-architecture.ts` 앞부분·`:105-270`, `scripts/lib/architecture-violation-message.ts`, `.dependency-cruiser.json` 전 규칙, `eslint.config.ts:1-110`, `tsconfig*.json`, `config/ci/*.json` 전체, `.gitea/workflows/quality-gates.yml` 트리거·권한·action 고정, `package.json` 검사 스크립트, `vitest.config.ts` |
| 읽은 문서(주장) | `docs/operations/ci-quality-gates.md:1-145`, `README.md:286-340`, `docs/operations/api-contract-and-server-state-recovery.md:31`, `src/platform/traffic/request-fanout.ts`, `tests/features/reference-feature/reference-request-fanout.test.ts` |
| 제품 repo 증거 | `../tech-log-frontend`, `../memento-frontend`의 `chore/template-sync-v0.2.0`. 동기화 기록 `docs/operations/template-sync-2026-09-29.md`, `git show`·`git diff af3d8e6 <branch>`로 가드레일 파일 차이 확인. 두 repo 모두 읽기만 했다 |
| 실행한 명령 | `node scripts/check-request-fanout.ts`(74파일 PASS)·`--fixture`(PASS) · `node scripts/check-remediation-ledger.ts`(exit 1, 4건) · Gitea API 읽기 7회(아래 12-01 FOLLOW-UP 절) |
| 실험 | worktree(`scratchpad/review-2026-09-29/12/wt`, 끝나고 삭제)에서 경계 probe 9종, CI 계약 변이 4종, i18n probe 2종, scale·system 테스트 단독 실행. `findRequestFanout` 직접 호출 probe 12종(scratchpad 스크립트). worktree에서는 `corepack pnpm`을 부르지 않았다. 스크립트는 `node scripts/<file>.ts`로 돌렸고, `check-architecture.ts`가 부르는 `pnpm exec eslint`는 `node_modules/.bin/eslint`를 직접 실행하는 shim으로 대신했다. 예외: `ci-artifact-contract.test.ts`는 테스트 자신의 임시 fixture에서 `corepack pnpm build:release-candidate`를 부른다(설치 검사 끔, `scripts/lib/fixture-node-modules.ts`). 실행 뒤 메인 `node_modules`와 pnpm 상태 파일이 그대로인 것을 확인했다 |
| 확인하지 못한 범위 | 7절 |
## 1. 검사의 실제 효용 — 다운스트림 동기화에서 무엇이 걸렸나 (21절, 39.5)
두 제품 repo가 `af3d8e6`을 받을 때 가드레일이 실제로 무엇을 잡았는지 정리한다. 게이트 통과 여부가 아니라 "진짜 문제를 잡았는가"를 본다.
| 검사 | 제품 | 무엇을 잡았나 | 판정 |
|---|---|---|---|
| `check:adapter-inventory` | memento | 제품 파일 `src/adapters/http/offset-upload.ts`가 인벤토리에 없고 abort listener를 손으로 짝지었다 | 진짜 문제. 공용 abort primitive를 쓰지 않은 중복을 잡았다 |
| risk coverage(FE-GATE-005) | memento | `http-contract-bridge.ts`의 제품 추가분(`If-Match` 투영)에 테스트가 없었다 | 진짜 문제. 제품이 테스트 14개를 추가했다 |
| `check:ci`의 게이트 밖 스크립트 검사 | memento, tech-log | 제품 스크립트 4개·1개가 게이트에 없었다 | 진짜 누락. 이유를 적어 목록에 올렸다 |
| `check:request-fanout` | tech-log | 커서 페이지네이션(`collect-catalog.ts:30`) | **오탐**(12-01). FE-GATE-010·005가 빨간 채로 남았다 |
| `check:i18n` | memento / tech-log(이전 동기화) | 한국어 전용 제품의 한국어 문구 21파일 / 한글 주석 | 정책 불일치와 오탐(12-02). 한쪽은 빨간 채, 한쪽은 스크립트를 고쳤다 |
| `check:remediation-ledger` | tech-log | 템플릿의 옛 원장 문구 | 템플릿 쪽 기록 문제. 두 repo 모두 게이트 밖이라 머지에는 영향 없다 |
- 정리: 인벤토리·커버리지·게이트 목록 검사는 제품 코드에서 실제 결함을 찾았다.
- 반대로 이름·문자 기반 휴리스틱 두 개(fanout, i18n)는 올바른 코드를 막았다. 막힌 뒤 선택지가 "스크립트 수정" 또는 "게이트를 빨간 채로 두기"뿐이었다.
## 2. 대표 흐름 (체크리스트 2절)
### 2.1 정상 흐름 — 개발자가 로컬에서 FE-GATE-010을 돌린다
1. **입력:** `corepack pnpm ci:gate -- FE-GATE-010`(`package.json:119`).
2. **정책:** `scripts/run-ci-gate.ts`가 `config/ci/gates.json:1909-1934`의 명령 21개를 순서대로 돈다. 각 명령의 기대값(`pass`/`fail`)은 `scripts/lib/ci-step-result.ts`가 판정한다.
3. **상태 변화:** `check:architecture`가 생성 인덱스(`src/.generated/`)를 만들고 import 그래프를 그린다(376 모듈, 1,176 간선). 규칙은 `.dependency-cruiser.json`에서 읽는다.
4. **외부 I/O:** 없음. 파일 읽기와 `artifacts/quality/*` 쓰기뿐이다.
5. **실패:** 위반은 `Architecture violation [규칙]: a -> b (import "…")`와 규칙 `comment`(이유·가야 할 곳)로 나온다(`scripts/lib/architecture-violation-message.ts:6-17`).
6. **결과:** `artifacts/quality/gates/FE-GATE-010.txt` 로그와 증거 파일. 한 번 도는 데 `check:architecture`만 약 14초 걸렸다(worktree, 부하 있음).
### 2.2 피해가 큰 흐름 — 경계 우회가 머지까지 가는 경로
1. **입력:** feature presentation에서 `src/adapters/http`를 직접 import하면 그래프와 lint가 막는다.
2. **우회:** 같은 feature의 `contracts/`나 새 폴더(`hooks/`)에 `export * from "../../../adapters/http/index.ts"`를 두고 presentation이 그것을 import한다.
3. **정책:** `feature-presentation-does-not-know-outbound-adapters`(`.dependency-cruiser.json:118`)는 직접 간선만 본다. `contracts/`·`hooks/` → `src/adapters` 간선에는 규칙이 없다(12-03).
4. **검출:** `check:architecture` exit 0, ESLint exit 0, `tsc -p tsconfig.app.json` exit 0(실험 Q10·Q11).
5. **외부 I/O:** 머지를 막을 CI가 없다. `has_actions: false`, 상태 0개(U-1).
6. **결과:** 우회가 main에 들어가고, 다운스트림은 그 main을 복사한다.
### 2.3 변경 흐름 — 다운스트림이 게이트에 명령 하나를 추가한다
1. **입력:** `config/ci/gates.json`의 FE-GATE-010에 명령을 추가한다.
2. **정책:** `check:ci`가 기준선 불일치로 실패하고, 갱신 명령을 알려 준다(`scripts/contracts/ci-gates.ts:517-545`).
3. **상태 변화:** 문서 절차(`docs/operations/ci-quality-gates.md:19-27`)대로 `update:ci-contract-baseline` → `generate:ci-workflow` → `check:ci` PASS.
4. **실패:** 그런데 `test:unit`(FE-GATE-005)이 `tests/unit/ci-workflow-generation.test.ts:187-205`의 개수 단언에서 실패한다(실험 M5). 문서에는 이 단계가 없다(12-04).
5. **동기화:** 템플릿을 다시 받을 때 `gates.json`을 id별로 합치고, 기준선·테스트 개수를 다시 계산한다. tech-log는 기준선 `27/101/106/141/5`와 테스트 개수 119를 새로 계산했다. memento는 `gates.json`을 바꾸지 않아 비용이 없었다.
6. **결과:** 절차를 알면 한 번에 끝난다. 모르면 게이트를 바꿀 때마다 테스트 실패를 따로 찾아 고친다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | - | 이 영역에 도메인 규칙이 없다 |
| **2** | 구조적 성숙도 | P | 직접 간선 규칙은 M3로 동작한다. probe Q4a·Q5·Q6·Q7이 모두 실패했다(E3). feature 안의 layer 폴더 밖 폴더는 규칙이 없어 재수출 우회가 통과한다(12-03, `.dependency-cruiser.json:96-139`, `:290-300`). TS `paths`·Vite alias는 없다 |
| 3 | 변경 용이성 | P | 게이트 하나를 바꾸면 `gates.json`·기준선·workflow·테스트 개수 4곳이 움직인다(12-04). 기준선과 workflow는 명령으로 갱신된다 |
| 4 | 인지 부하 | P | CI 메타 층이 여전히 크다: `gates.json` 2,940줄, `ci-gates.ts` 1,287, `package-script-graph.ts` 1,025, `ci-artifact-validator.ts` 742, `generate-ci-workflow.ts` 530. workflow는 470줄이다. 지난 12-10의 삭제 방향은 반영됐고 새로 늘지는 않았다 |
| 5 | 위험 가시성 | P | 규칙 주석이 강제하지 않는 범위를 강제한다고 적는다(12-03). fanout·i18n 실패 메시지에 이유가 없다(12-01, 12-02) |
| 6 | 실패 성숙도 | - | 런타임 실패 처리가 없는 영역이다. 검사기의 fail-closed 동작은 21에서 본다 |
| 7 | 운영 성숙도 | > | 영역 13(릴리스·운영 게이트) |
| 8 | 디버깅 가능성 | P | 그래프 위반은 규칙 이유까지 출력한다(지난 12-11 해소, probe 출력 확인). fanout은 `FAIL 파일:줄 호출 inside 구문`만, i18n은 파일 이름만 출력한다(12-01, 12-02) |
| 9 | 유지보수 성숙도 | P | 실행하지 않는 `dependency-cruiser` 의존성(12-05), 같은 개수의 두 사본(12-04), 게이트 밖에서 빨간 원장 검사(FOLLOW-UP) |
| 10 | 테스트 성숙도 | P | 음성 fixture와 목록 검사가 변이를 잡았다(E3). Vitest 폴더의 `*.spec.ts`는 "게이트 안"으로 세지만 돌지 않는다(12-06). fanout fixture에 페이지네이션·helper 추출 사례가 없다(12-01) |
| 11 | 데이터 성숙도 | - | 이 영역에 저장 데이터가 없다 |
| 12 | 동시성 성숙도 | - | 해당 없음 |
| 13 | 확장성 | > | 영역 09·11(기능 수 축) |
| 14 | 성능 성숙도 | ? | CI 소요 시간을 잴 runner가 없다. 로컬 `check:architecture` 약 14초만 확인했다 |
| 15 | 보안 성숙도 | O | workflow 범위만 본다. `permissions: contents: read`(`quality-gates.yml:23-24`), action 33개 전부 40자 SHA 고정, `--frozen-lockfile --ignore-scripts`, `persist-credentials: false`, `pull_request_target` 없음(E1). 공급망 전체는 영역 13 |
| **16** | 의존성 성숙도 | P | lint·타입 도구가 exact pin이고 `minimumReleaseAgeExclude`에 이유·담당·재검토가 있다(`pnpm-workspace.yaml:9-13`). 실행하지 않는 `dependency-cruiser@18.1.0`과 직접 의존 18개가 남아 있다(12-05, `package.json:182`) |
| 17 | API / Contract | P | "모든 게이트 id가 run step에 있다"를 검사한다(`generate-ci-workflow.ts:367-385`, 변이 M1로 확인). 계약 크기가 두 곳에 있다(12-04) |
| 18 | 배포 성숙도 | > | 영역 13. 지난 12-02(FE-GATE-027 누락)는 변이로 회귀 없음을 확인했다 |
| 19 | 설정 성숙도 | P | 검사 정책(i18n 필수 로케일, 검사 폴더, 문자 판정)이 설정이 아니라 스크립트 코드에 있다(12-02) |
| 20 | 개발자 경험 | P | 그래프·lint 메시지는 해결 방향을 준다. fanout은 탈출 경로가 스크립트 머리 주석에만 있다(12-01). 게이트 변경 절차 문서가 테스트 갱신을 빠뜨린다(12-04) |
| **21** | Guardrail 성숙도 | X (머지 시점) / P (로컬) | **머지 시점:** 세 repo 모두 Actions가 꺼져 있고 상태가 0개다(2026-09-29 API, U-1). **로컬:** 직접 경계·CI 계약·게이트 목록 검사는 M3이고 변이 7종을 모두 잡았다(E3). 새 휴리스틱 게이트 둘은 오탐·미탐이 크고(12-01, 12-02), feature 폴더 우회가 열려 있다(12-03) |
| 22 | 추상화 성숙도 | P | CI 기준선 파일은 유지할 근거가 있다(4.2절). fanout·i18n은 정책보다 좁은 대리 규칙이다(4.1절) |
| 23 | 일관성 | P | 지난 12-11의 "규칙 이유 출력" 관례를 새 게이트 둘이 따르지 않는다. 예외 목록마다 메타데이터 모양이 다르다(12-07) |
| 24 | 네이밍 / 의미 | P | "hardcoded user-facing locale literal"이 실제로는 "한글 문자 포함"이다(12-02). 규칙 주석의 "only its adapters/ folder"가 사실과 다르다(12-03) |
| **25** | 조직 확장성 | P (구조만) | 팀이 하나라 실제 검증은 미확인이다. 다운스트림 기록: tech-log는 가드레일 파일 8개(+558줄), memento는 6개(+393줄)를 템플릿과 다르게 들고 있다(`git diff --stat af3d8e6 <branch>`). 제품 정책을 표현할 설정이 없어 템플릿 소유 스크립트를 고친다(12-02). `gates.json` 한 파일이 동기화 충돌 지점이다(4.2절) |
| **26** | Ownership | P | 경계 예외 주석과 `pnpm-workspace.yaml` 예외에는 담당·재검토 조건이 있다(지난 12-07 해소). `ungated-*.json` 항목과 fanout 주석에는 담당·재검토 시점이 없다(12-07). 게이트에 담당 필드가 없다(`gates.json` gate 키: id·name·commandIds·artifact·retention). 원장 검사는 빨간 채로 결정자가 없다(FOLLOW-UP) |
| 27 | 삭제 가능성 | P | 제거 게이트 4개가 CI 테스트를 지운 뒤에 통과를 증명한다(12-04). 샘플 제거 자체는 영역 14 |
| 28 | 회복 가능성 | - | 이 영역에 복구 경로가 없다 |
## 4. 설계 선택 설명 (41절)
### 4.1 N+1 소스 게이트를 글자 위치로 판정하는 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | feature·application 코드가 컬렉션 행마다 요청을 보내지 않게 한다. 정책은 "N개 행을 읽는 비용은 한 페이지 또는 bulk 요청 수로 제한된다"이다(`src/platform/traffic/request-fanout.ts:1-5`). 쓰는 사람은 기능 작성자와 다운스트림이다 |
| 2. 지킬 성질 | 요청 수가 행 수에 비례하지 않는다. 페이지 단위 요청(최대 `ceil(N/100)+1`)은 허용된다. 템플릿 자신의 테스트가 커서 루프를 "never one per row"라고 정의한다(`tests/features/reference-feature/reference-request-fanout.test.ts:35-52`) |
| 3. 현재 보장 | 같은 파일 안에서 transport 이름(`http`, `client`, `gateway`, `api`, `*Gateway` 등)의 receiver 호출이 반복 구문이나 `map`·`forEach` 등의 콜백 안에 글자로 있으면 거부한다(`scripts/check-request-fanout.ts:23-42`, `:97-111`). 중첩 함수 선언은 반복 문맥을 지운다(`:102-104`). **보장하지 않는 것:** 반복 횟수가 행 수와 무관한지, 요청 사이에 의존이 있는지, helper·다른 이름·구조 분해를 거친 호출 |
| 4. 대안 | (a) 현 규칙 + 같은 줄 `fanout-reviewed:` 주석. (b) 데이터 흐름 규칙: 반복 요소가 요청 인자로 흘러가는지 본다. (c) 규칙은 두고, feature가 쓸 페이지네이션 경로를 제공한다: feature `adapters/`에서 `createCursorPaginationRuntime`(`src/adapters/query-cache/cursor-pagination-runtime.ts:49`)을 조립하게 안내한다. (d) 소스 게이트를 없애고 런타임 요청 예산과 테스트에만 맡긴다 |
| 5. 대안별 비용 | (a) 코드 비용 0. 정상 루프마다 사람이 주석을 달아야 하고, 주석 수를 세는 곳이 없다. (b) 정확도는 오르지만 자체 AST 데이터 흐름 분석기가 된다(21절 비용 기준 위배). 파일을 넘는 helper는 여전히 못 본다. (c) 커서 루프가 검사 밖(`src/adapters`)으로 가고 snapshot 변경·반복 cursor·상한·abort 검사를 함께 얻는다. 비용은 `CursorPage` 모양(`items`, `nextCursor`, `hasMore`, `snapshotToken`)으로 바꾸는 매핑과 문서 한 단락이다. 규칙상 feature `adapters/` → `src/adapters/query-cache/index.ts`는 허용된다(`.dependency-cruiser.json:140`은 최상위 `application` 등만 막는다. reference-feature adapters가 이미 `http` 배럴을 import한다). (d) 실행된 경로만 본다. 행별 요청이 테스트에 없으면 못 잡는다 |
| 6. 현재 조건에서의 선택 | **(a)는 유지하되 (c)의 안내를 붙인다.** 실패 메시지가 두 탈출 경로를 알려 주고, 허용 fixture로 "주석이 달린 커서 페이지네이션"을 고정한다. 억제된 호출 수를 출력한다. (b)는 비용 대비 효과가 작다. 리뷰어 추론이며 작성 당시 의도 기록은 없다 |
| 7. 재검토 조건 | 억제 주석이 여러 제품에서 반복되면 (b)나 "반복 요소가 인자에 쓰일 때만 거부"하는 좁은 규칙을 다시 비교한다. 실제 N+1이 게이트를 통과해 문제가 되면 (d)의 런타임 예산 연결을 먼저 본다 |
### 4.2 CI 계약 크기를 기준선 파일로 승인하는 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 게이트·명령·산출물이 의도 없이 늘거나 줄지 않게 하고, 바뀌면 리뷰에서 보이게 한다(D-13, `scripts/contracts/ci-gates.ts:454-460`) |
| 2. 지킬 성질 | `gates.json` 모양이 바뀌면 `check:ci`가 실패한다. 갱신은 담당·이유와 함께 명령 하나로 끝난다 |
| 3. 현재 보장 | `assertCiContractBaseline`(`ci-gates.ts:517-545`)이 개수 5개와 게이트 모양 SHA-256을 비교한다. 불일치 메시지가 갱신 명령을 알려 준다. **보장하지 않는 것:** 테스트 상수(`tests/unit/ci-workflow-generation.test.ts:196-204`)가 같은 사실을 따로 고정한다(12-04) |
| 4. 대안 | (a) 기준선을 없애고 `gates.json` diff만 리뷰한다. (b) 현 상태(기준선 + 테스트 상수). (c) 기준선만 둔다. 테스트는 기준선 파일을 읽고, 테스트에만 있는 측정값 3개(job 수, `expect: fail` 명령 수, 증거 참조 수)는 기준선에 넣는다 |
| 5. 대안별 비용 | (a) 가장 단순하다. 동기화 때 파생값 충돌도 없다. 대신 2,940줄 JSON diff에서 게이트 삭제를 놓치기 쉽고, 제거 스크립트가 "무엇을 줄였는지"를 기록할 곳이 없다. (b) 한 사실이 세 곳에 있다. 이번 수정 라운드에서만 테스트 개수를 4개 커밋이 따로 고쳤다(`15a946f`, `fa3de53`, `710436b`, `7f889a6`). (c) 원본(`gates.json`)과 승인된 요약(기준선) 두 곳만 남는다. 39.5절 기준으로 기준선이 이미 "독립 선언과 실제 대조"를 한다 |
| 6. 현재 조건에서의 선택 | **기준선 파일은 유지한다. 테스트 사본만 걷어 낸다((c)).** 다운스트림 증거: memento는 `gates.json`을 바꾸지 않아 기준선이 템플릿과 같았고 비용이 없었다. tech-log는 합친 뒤 명령 하나로 다시 계산했고 기록에 "recomputed, not chosen"으로 남겼다. 비용은 감당할 만하다 |
| 7. 재검토 조건 | 제품이 `gates.json`을 템플릿과 따로 자주 바꿔 동기화마다 충돌이 반복되면(tech-log는 이미 +276줄), 제품 게이트를 별도 파일로 분리하는 안과 (a)를 다시 비교한다 |
### 4.3 경계 규칙을 폴더 이름별 직접 간선으로 적는 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | presentation(공용·feature)이 concrete adapter(http 등)를 모르게 한다 |
| 2. 지킬 성질 | presentation이 import할 수 있는 모듈은 concrete adapter를 재수출하지 않는다 |
| 3. 현재 보장 | 간선 하나씩 규칙에 맞춘다(`scripts/check-architecture.ts:698`). 지난 12-03 수정은 중간 경유지(feature 루트 파일, `contexts`, `apps`)에서 `src/adapters`로 가는 간선을 막았다(`.dependency-cruiser.json:290-313`). feature 안은 `domain`·`application`·`presentation`(금지)과 `adapters`(허용)만 규칙이 있다. **보장하지 않는 것:** 그 밖의 폴더(`contracts/`, 새 이름)는 제약이 없다(12-03) |
| 4. 대안 | (a) 현 상태. (b) feature 안에서 `src/adapters`로 가는 간선은 `adapters/`에서만 허용하도록 규칙 하나를 허용 목록 방식으로 뒤집는다. (c) 도달 가능성 규칙: presentation에서 출발해 `src/adapters`에 닿는 경로를 금지한다 |
| 5. 대안별 비용 | (a) 우회가 CI를 통과한다. (b) 규칙 1개 교체와 fixture 1개. 새 폴더 이름도 자동으로 막힌다. 현재 템플릿 간선 1,176개 중 이 규칙에 걸리는 것은 0개다(`artifacts/quality/dependency-report.json` 계산). 두 제품 repo에서도 해당 import를 찾지 못했다(`git grep`). (c) 가장 정확하다. 그러나 지금은 설치 레지스트리(`src/features/installed-*`) 조립 경로로 presentation 다수가 합법적으로 adapter에 닿는다(지난 12-03 측정 45/55). 조립이 bootstrap으로 옮겨지기 전에는 예외 목록이 커진다 |
| 6. 현재 조건에서의 선택 | **(b).** 비용이 가장 작고, 주석이 이미 약속한 성질("feature 안에서는 `adapters/`만")을 코드로 만든다 |
| 7. 재검토 조건 | 설치 조립이 bootstrap으로 옮겨지면 (c)로 바꿔 폴더별 규칙 여러 개를 하나로 줄인다(`generic-presentation-does-not-compose-the-product`의 재검토 조건과 같은 시점) |
### 4.4 선언·실행·검증 반복 점검 (39.5)
| 대상 | 원본 | 실제 소비자 | 불일치 검출 | 판단 |
|---|---|---|---|---|
| CI 계약 크기 | `gates.json` | `check:ci`(기준선 비교), 단위 테스트(상수 비교) | 둘 다 검출 | 기준선이 독립 선언 역할을 한다. 테스트 상수는 중복 유지 비용이다(12-04) |
| 게이트 밖 테스트·스크립트 | `ungated-*.json` 항목 | `check:ci` | 게이트가 이제 돌리면 "stale"로 실패 | 독립 선언과 실제 게이트 그래프를 대조한다. 유지할 가치가 있다 |
| 규칙 주석의 범위 설명 | `.dependency-cruiser.json` `comment` | 사람, 위반 메시지 | 없음 | 주석이 규칙보다 넓게 약속한다(12-03) |
| ESLint `layerPatterns` | `eslint.config.ts:9-37` | 편집기·`lint` | 없음 | "편집기 보조, 기준은 그래프"라고 적혀 있다. 부분집합임을 밝혔으므로 유지 가능하다 |
## 5. 발견 사항 (36.3)
### 12-01 `check:request-fanout`이 요청 사이의 의존과 반복 횟수를 보지 않는다 — 제한된 커서 페이지네이션을 거부하고, helper를 거친 행별 요청은 통과시킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10, 5, 8, 20, 24, 26, 14 |
| 근거 | **규칙:** `scripts/check-request-fanout.ts:23`(receiver 이름 정규식), `:24-41`(반복 구문·메서드), `:97-111`(문맥 전파와 같은 줄 주석 판정). 반복 횟수나 인자의 출처는 보지 않는다. **실험(`findRequestFanout` 직접 호출, 12종):** 거부됨 — 커서 `for`(tech-log 모양), 커서 `do…while`, 3회 재시도 `for`, 고정 2개 배열의 `.map`. 통과됨 — `ids.map((id) => loadOne(gateway, id))`, `ids.map(one)`, `studio.getItem(id)`, 구조 분해 `get(id)`, 별칭 `g.get(id)`, `Array.from(ids, …)`, `useQueries`의 `queryFn: () => gateway.get(id)`. 거부된 실제 N+1은 `for await` 하나뿐이다. **다운스트림:** tech-log `src/features/tech-log/application/collect-catalog.ts:29-37`은 100건 페이지를 최대 50번, 앞 응답의 cursor로 이어 읽는다. 게이트가 `:30`을 거부했다. 동기화 기록은 `check:request-fanout`(FE-GATE-010)과 `tests/architecture/request-fanout.test.ts`(`test:coverage`, FE-GATE-005)가 빨간 채라고 적고 제품 소유자에게 결정을 넘겼다(tech-log 기록 "Open questions" 1). **탈출 경로:** 같은 줄 `// fanout-reviewed: <이유>`만 인정한다(`:109`). 위 줄에 달면 인정하지 않는다(실험). 이 관례는 스크립트 머리 주석(`:18-19`)에만 있고 `docs/`에는 없다. 실패 메시지는 `FAIL 파일:줄 호출 inside 구문`뿐이다(`:173-175`). 억제된 호출 수는 출력하지 않는다. **fixture:** 허용 fixture는 bulk 1회 조회 하나다(`tests/fixtures/architecture/request-fanout/allowed/bulk-read.ts`). 페이지네이션·재시도 허용 사례와 helper 추출 금지 사례가 없다. **페이지네이션 경로:** 템플릿의 `createCursorPaginationRuntime`은 검사 범위 밖(`src/adapters`)이지만 "runtime만 있다, 쓰는 operation이 없다"(`docs/operations/api-contract-and-server-state-recovery.md:31`). 게이트도 문서도 기능이 이것을 쓰도록 안내하지 않는다 |
| 발생 조건 | feature·application 코드에 제한된 반복 요청(커서 페이지네이션, 재시도, 고정 개수)을 쓸 때 → 오탐. 행별 요청을 helper·다른 이름·`useQueries`로 쓸 때 → 미탐 |
| 영향 | 오탐: 올바른 코드가 merge 게이트 2개를 빨갛게 만든다. 작성자는 스크립트를 읽어야 주석 관례를 안다. 미탐: `docs/reviews/2026-09-23-extreme-scale-acceptance.md` 9번이 "N+1 없음"의 근거로 이 게이트를 든다. 흔한 N+1 모양이 통과하므로 그 주장보다 보호 범위가 좁다 |
| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 한 줄 주석으로 풀린다. 다만 실제 제품에서 merge 게이트를 막았고, 보호한다고 기록된 N+1 대부분을 놓친다 |
| 통제·증거 | 목표 M3 / 확인 M3(fixture 모양 3종만), 일반 N+1에는 M1 · E3(probe 12종) + 다운스트림 기록 |
| 확실성과 남은 가정 | 규칙 동작은 실행으로 확정했다. 두 제품 repo 코드에 helper를 거친 실제 N+1이 있는지는 찾지 않았다 |
| 결정의 근거 | 4.1절. 확인한 사실: 규칙 동작과 템플릿 자신의 "커서 루프는 N+1이 아니다" 테스트. 기록된 의도: 스크립트 머리 주석의 "reviewed exception". 추론: 주석 탈출구는 드문 예외를 가정했다 |
| 이해 비용 | 게이트에 걸린 기능 작성자가 `scripts/check-request-fanout.ts`를 열어 머리 주석을 읽어야 한다. tech-log 동기화 담당은 여기서 멈추고 결정을 넘겼다 |
| 최소 개선 방향 | (1) 실패 메시지에 이유와 두 탈출 경로(feature `adapters/`에서 `createCursorPaginationRuntime` 조립 / 같은 줄 `fanout-reviewed:`)를 적는다. (2) 허용 fixture에 "주석이 달린 커서 페이지네이션"을 추가한다. (3) 결과 줄에 억제된 호출 수와 위치를 출력한다. (4) 머리 주석과 `docs/operations/ci-quality-gates.md`에 미탐 범위(파일 내 글자 위치·이름 기반)를 적는다 |
| 대안 비교 | 4.1절 |
| 단순화의 보존 조건 | 금지 fixture 3종은 계속 거부된다. 억제에는 이유 문구가 계속 필요하다 |
| 비용·부작용 | 수십 줄과 fixture 1개. 규칙 자체는 바뀌지 않는다 |
| 재검토 조건 | 4.1절 7번 |
| 완료 기준 | tech-log 모양 코드를 넣으면 메시지만 보고 두 해결 방법을 안다. 허용 fixture에 주석 달린 커서 루프가 있다. 게이트 출력에 억제 수가 보인다 |
| 검증 방법 | `tests/architecture/request-fanout.test.ts`에 메시지·억제 수 단언과 페이지네이션 fixture를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-02 `check:i18n`의 "하드코딩 문구" 검사가 "파일에 한글 문자가 있는가"다 — 한글 주석은 실패, 영어 하드코딩은 통과하고, 제품이 정책을 바꿀 설정이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 24, 19, 25, 20, 8, 30.3 |
| 근거 | `scripts/check-i18n.ts:12` `koreanLiteral = /[가-힣]/`. `:95-98`은 파일 전체 텍스트에 이 정규식을 적용하고 "hardcoded common user-facing locale literal"로 보고한다. 주석과 문자열을 구분하지 않는다. **실험:** feature presentation에 `// 이 컴포넌트는 목록의 빈 상태를 그린다.` 한 줄만 있는 파일 → 실패. `<h1>Hard-coded English title</h1>` 파일 → 통과. 필수 로케일은 `ko-KR`·`en-US` 고정이다(`:32-52`). 검사 폴더는 코드 상수다(`:59-68`). **다운스트림:** tech-log는 이전 동기화에서 "주석과 문구를 구분하지 못한다"를 기록했고, 이번에 스크립트를 고쳐 자기 feature를 빼고 문자열·JSX 텍스트만 읽는 별도 정책(`scripts/lib/tech-log-i18n-policy.ts`)을 붙였다(`git diff af3d8e6 chore/template-sync-v0.2.0 -- scripts/check-i18n.ts`, +30줄). memento는 한국어 전용 제품이라 21파일이 걸렸고, 영어 문구가 없어 FE-GATE-010을 빨간 채로 두고 제품 소유자에게 넘겼다(memento 기록 "Introduced and escalated") |
| 발생 조건 | 한국어로 주석을 쓰는 제품. 한 언어만 지원하는 제품. 영어 문구를 하드코딩한 화면 |
| 영향 | 올바른 코드가 merge 게이트를 막는다. 제품은 템플릿 소유 스크립트를 고치고, 그 차이는 다음 동기화마다 충돌 지점이 된다. 영어 하드코딩은 검사 이름과 달리 잡히지 않는다 |
| 심각도·우선순위 | Medium · P2 — 두 제품 모두 비용을 치렀다. 데이터·보안 피해는 없다 |
| 통제·증거 | 목표 M3 / 확인 M2(한글 문구만) · E3(probe 2종) + 다운스트림 기록 |
| 확실성과 남은 가정 | 동작은 확정했다. 화면 문구의 번역 완성도 자체는 영역 08에서 본다 |
| 결정의 근거 | 확인한 사실: 템플릿 기본 로케일이 `ko-KR`이라 한글 검출은 "catalog를 거치지 않은 기본 로케일 문구"의 대리 지표로 동작한다. 기록된 의도: `:53-58` 주석 "Screen code … must take its words from the catalog". 추론: 템플릿 코드의 주석이 영어라 주석 오탐이 템플릿 안에서는 드러나지 않았다 |
| 이해 비용 | 제품 작성자가 실패 원인을 알려면 스크립트의 정규식을 읽어야 한다. 메시지에 줄 번호가 없다 |
| 최소 개선 방향 | (1) 파일 전체 대신 문자열 리터럴·템플릿 문자열·JSX 텍스트만 검사한다. Babel 파서가 이미 의존성에 있고(`@babel/core`), tech-log가 같은 방식을 구현했다. (2) 필수 로케일과 검사 대상 문자를 설정(예: `config/i18n` 또는 catalog 선언)에서 읽는다. (3) 메시지에 줄과 해결 방향(catalog 키)을 적는다 |
| 대안 비교 | 현 상태 유지: 코드 0줄, 두 제품이 계속 포크한다. 주석만 제거하는 전처리: 수 줄, 영어 미탐은 남는다. AST 리터럴 검사 + 로케일 설정: 수십 줄, 제품이 스크립트를 고치지 않아도 된다. 로케일 설정만 추가: memento는 풀리지만 tech-log 주석 문제는 남는다. 리터럴 검사와 설정을 함께 하는 것이 두 제품의 실제 문제를 모두 푼다 |
| 단순화의 보존 조건 | `tests/fixtures/i18n/forbidden` 음성 fixture가 계속 실패한다. `rawFailureRender`, `dangerouslySetInnerHTML` 검사는 그대로 둔다 |
| 비용·부작용 | 수십 줄. 영어 문구 검출을 켜면 템플릿 `examples` 밖의 영어 문구가 새로 걸릴 수 있다(개수 미확인) |
| 재검토 조건 | 템플릿이 세 번째 로케일을 기본으로 들이거나, 제품 두 곳 중 하나라도 로케일 정책을 템플릿과 다르게 확정할 때 |
| 완료 기준 | 한글 주석만 있는 파일은 통과하고, 영어·한글 하드코딩 문구는 줄 번호와 함께 실패한다. 한 언어 제품이 스크립트 수정 없이 설정으로 게이트를 통과한다 |
| 검증 방법 | i18n fixture에 주석 전용 파일(허용)과 영어 문구 파일(금지)을 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-03 feature 안의 layer 폴더 밖 폴더는 경계 규칙이 없다 — feature presentation이 `contracts/`·`hooks/` 재수출로 `src/adapters/http`에 닿아도 모든 검사가 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 2, 21, 5, 24, 10 |
| 근거 | feature 규칙은 `domain`(`.dependency-cruiser.json:96`), `application`(`:107`), `presentation`(`:118`), `adapters`(`:129`) 네 폴더만 출발지로 적는다. `feature-and-app-roots-do-not-reach-adapters`(`:290-300`)는 feature 루트 파일, `contexts`, `apps`만 막는다. 이 규칙의 주석은 "Inside a feature, only its adapters/ folder reaches src/adapters"라고 적는다. **실험(worktree):** Q10 — `src/features/reference-feature/contracts/probe-reexport.ts`가 `src/adapters/http/index.ts`를 재수출하고 같은 feature presentation이 이를 import → `check:architecture` exit 0, ESLint exit 0, `tsc -p tsconfig.app.json` exit 0. Q11 — 새 폴더 `hooks/`로 같은 구성 → 그래프·ESLint exit 0. Q1·Q3 — 공용 presentation·`src/application` → feature `adapters/` 재수출 → 그래프는 통과, ESLint는 경로 문자열에 `adapters`가 있어 막았다. 같은 구성을 `contracts/`로 바꾸면 ESLint도 통과했다 |
| 발생 조건 | lint가 presentation의 직접 import를 막을 때 개발자가 feature의 `contracts/`나 새 폴더에 재수출을 두는 경우 |
| 영향 | "presentation은 concrete adapter를 모른다"(`presentation-does-not-fetch-directly`, `:163`)가 CI 통과 상태로 깨진다. 템플릿 규칙이므로 다운스트림도 같은 틈을 갖는다 |
| 심각도·우선순위 | Medium · P2 — 지난 12-03과 같은 종류다. 데이터·보안 피해로 바로 이어지지는 않는다 |
| 통제·증거 | 목표 M3 / 확인 M3(네 폴더만), 그 밖 M0 · E3 |
| 확실성과 남은 가정 | 우회는 실행으로 확인했다. 현재 템플릿과 두 제품 repo에는 이런 간선이 없다(그래프 계산, `git grep`) |
| 결정의 근거 | 4.3절 |
| 이해 비용 | 규칙을 믿는 사람은 주석대로 막힌다고 생각한다. 실제 범위를 알려면 규칙 30개의 출발지 정규식을 모두 읽어야 한다 |
| 최소 개선 방향 | 규칙 하나를 허용 목록 방식으로 바꾼다: 출발지 `^src/features/[^/]+/(?!adapters/)` → 도착지 `^src/adapters/` 금지. 기존 루트 파일 규칙과 예외(`feature-adapter-contribution.ts`)는 그대로 둔다 |
| 대안 비교 | 4.3절 |
| 단순화의 보존 조건 | feature `adapters/` → adapter 배럴 간선은 계속 허용된다. 기존 28개 그래프 fixture가 통과한다 |
| 비용·부작용 | 정규식 1줄과 그래프 fixture 1개. 현재 위반 0건 |
| 재검토 조건 | 4.3절 7번 |
| 완료 기준 | Q10·Q11 probe가 `check:architecture`에서 실패한다. 규칙 주석과 동작이 같다 |
| 검증 방법 | `tests/fixtures/architecture/dependency-graph/`에 feature `contracts/` 재수출 fixture를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-04 CI 계약 크기가 기준선 파일과 테스트 상수 두 곳에 있고, 문서의 갱신 절차는 테스트 쪽을 빠뜨린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 9, 20, 27, 25, 17, 30.4 |
| 근거 | 기준선: `config/ci/contract-baseline.json`(명령 98, 참조 103, 산출물 109 등). 같은 값이 `tests/unit/ci-workflow-generation.test.ts:196-204`에 상수로 있다. 테스트에는 기준선에 없는 값 3개(job 9, `expect: fail` 명령 30, 증거 참조 87)도 있다. 운영 문서의 절차(`docs/operations/ci-quality-gates.md:19-27`)와 "새 프로젝트가 다시 찍을 기준선" 표(`:60-66`)에는 이 테스트가 없다. 내부 작업 문서에만 "테스트 개수 갱신" 단계가 있다(`tasks/handoff.md:74`, `tasks/lanes/LANE-BRIEF.md:77`). **실험 M5(worktree):** FE-GATE-010에 명령 1개 추가 → 문서 절차(기준선 갱신 → workflow 생성 → `check:ci`) → `check:ci` PASS → `tests/unit/ci-workflow-generation.test.ts` 1개 실패("preserves the reviewed baseline"). **제거 게이트:** 네 제거 스크립트가 fixture에서 이 테스트와 스냅샷을 지운 뒤에 검증한다(`scripts/test-sample-removal.ts:214-221`, `test-browser-file-storage-runtime-removal.ts:114-126`, `test-realtime-runtime-removal.ts:105-111`, `test-optional-recipe-removal.ts:33-34`). **이력:** 이번 수정 라운드에서 이 상수를 4개 커밋이 따로 고쳤다(`git blame -L 196,204`). **다운스트림:** tech-log가 기준선과 함께 이 테스트의 증거 참조 수(120/87 → 119)를 다시 계산했다 |
| 발생 조건 | 게이트·명령·산출물을 추가하거나 지울 때. 템플릿 동기화에서 양쪽이 `gates.json`을 바꿨을 때 |
| 영향 | 문서대로 하면 merge 게이트 FE-GATE-005가 실패한다. 제거 게이트는 실제 다운스트림이 겪을 단계를 건너뛰고 "제거 가능"을 증명한다. 지난 14-02가 없애려던 "템플릿 자신의 모양에 고정된 계약"이 테스트 쪽에 남았다 |
| 심각도·우선순위 | Medium · P2 — 실패 메시지(기대값 차이)는 분명하고 고치기 쉽다. 게이트를 바꿀 때마다 반복된다 |
| 통제·증거 | 해당 없음(중복 유지 비용) · E3(변이 M5) + 다운스트림 기록 |
| 확실성과 남은 가정 | 확정. 전체 workflow 스냅샷은 명령 추가만으로는 바뀌지 않았다. 게이트·job을 바꾸면 스냅샷도 갱신해야 한다(추론) |
| 결정의 근거 | 4.2절 |
| 이해 비용 | 게이트를 바꾸는 사람이 `check:ci` 통과 뒤 `test:unit` 실패를 따로 만나고, 테스트의 상수 7개를 손으로 맞춘다 |
| 최소 개선 방향 | 테스트가 기준선 파일을 읽어 비교하게 한다. 테스트에만 있는 측정값 3개는 `measureCiContractBaseline`에 넣어 기준선 한 곳에서 관리한다. 그러면 제거 스크립트가 이 테스트를 지우지 않아도 된다 |
| 대안 비교 | 4.2절 |
| 단순화의 보존 조건 | 게이트 id 목록 단언(`:191-195`)과 FE-GATE-015·020 모양 단언은 독립 기대값이므로 남긴다 |
| 비용·부작용 | 수십 줄. 기준선 파일에 필드 3개가 늘고, 다운스트림은 한 번 다시 찍는다 |
| 재검토 조건 | 4.2절 7번 |
| 완료 기준 | 문서 절차만 따라 게이트를 바꾸면 `check:ci`와 `test:unit`이 모두 통과한다. 제거 스크립트가 이 테스트를 지우지 않는다 |
| 검증 방법 | 실험 M5를 다시 돌린다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-05 실행하지 않는 `dependency-cruiser`가 의존성에 남아 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 16, 9, 27, 24 |
| 근거 | `package.json:182` `"dependency-cruiser": "18.1.0"`. 지난 12-05 수정(D-11) 뒤로 이 도구를 실행하거나 import하는 코드가 없다(`git grep`: `scripts/check-architecture.ts:115-117` 주석과 "depcruise를 쓰지 않는다" 단언 `tests/unit/architecture-report.test.ts:66`뿐). lockfile의 직접 의존은 18개다(acorn 계열 5, `enhanced-resolve`, `tsconfig-paths-webpack-plugin`, `prompts`, `is-installed-globally`, `watskeburt` 등). 의존성 기준선(`config/security/dependency-baseline.json:3558`)에 올라가 승인·SBOM 대상이 된다 |
| 발생 조건 | 항상. 설치할 때마다 |
| 영향 | 쓰지 않는 코드가 설치·공급망 검토 범위에 남는다. 규칙 파일 이름과 함께 "dependency-cruiser가 검사한다"는 오해를 계속 만든다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0(사용하지 않는 의존성을 잡는 검사 없음) · E1 |
| 확실성과 남은 가정 | 사용하지 않음은 확정. 제거 시 lockfile에서 함께 빠지는 전이 패키지 수는 세지 않았다 |
| 결정의 근거 | 적용 제외 — 도구를 끄기로 이미 결정했고(D-11) 패키지 제거만 빠졌다 |
| 이해 비용 | 새 사람이 `.dependency-cruiser.json`과 이 의존성을 보고 depcruise 명령을 찾는다 |
| 최소 개선 방향 | `package.json`에서 빼고 lockfile·의존성 기준선을 갱신한다(`update:dependency-baseline`) |
| 대안 비교 | 적용 제외 — 선택지가 "빼기"뿐이다 |
| 단순화의 보존 조건 | `check:architecture`는 이 패키지를 쓰지 않으므로 영향이 없다 |
| 비용·부작용 | 기준선 재승인 1회(사용자 몫 F-11과 함께 처리 가능) |
| 재검토 조건 | 적용 제외 — 되돌릴 조건은 "dependency-cruiser가 TS 7을 지원해 다시 쓰기로 할 때"뿐이다 |
| 완료 기준 | `package.json`과 lockfile에 `dependency-cruiser`가 없다 |
| 검증 방법 | `git grep dependency-cruiser -- package.json pnpm-lock.yaml` 결과 없음, `check:architecture` 통과 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-06 게이트 밖 테스트 검사가 폴더 이름으로 판정해, Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 센다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10 |
| 근거 | `scripts/lib/ungated-tests.ts:18`은 `*.test.ts`와 `*.spec.ts`를 모두 테스트 파일로 센다. `:94-95`는 파일 경로가 게이트 경로(`tests/unit` 등)로 시작하면 "게이트 안"으로 본다. Vitest는 `tests/**/*.test.{ts,tsx}`만 실행한다(`vitest.config.ts:25`). **실험:** `tests/unit/probe-never-runs.spec.ts`(실패하는 단언) → `check-ci-contract.ts` PASS, `run-vitest.ts run <그 파일>` → "No test files found" |
| 발생 조건 | Playwright 습관으로 Vitest 폴더에 `.spec.ts`를 만들 때. 현재 템플릿·두 제품 repo에는 없다 |
| 영향 | 테스트가 아무 데서도 돌지 않는데 목록 검사는 통과한다. 지난 12-04가 막으려던 "조용히 게이트 밖" 상태의 한 경로다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M3(폴더 기준) · E3 |
| 확실성과 남은 가정 | 확정. Playwright `testIgnore`로 빠지는 파일도 같은 방식으로 "게이트 안"으로 셀 수 있다(추론, 미실험) |
| 결정의 근거 | 적용 제외 — 기존 검사의 판정 조건 누락이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | Vitest 경로에 속한 파일은 `vitest.config.ts`의 `include` 패턴(`.test.`)도 맞아야 "게이트 안"으로 본다. 아니면 이유 없이 실패시킨다 |
| 대안 비교 | 적용 제외 — 판정 조건 한 줄 보강이다 |
| 단순화의 보존 조건 | 기존 stale 판정과 이유 필수 규칙을 유지한다 |
| 비용·부작용 | 수 줄과 단위 테스트 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 위 probe에서 `check:ci`가 실패한다 |
| 검증 방법 | `tests/unit/ungated-tests.test.ts`(또는 해당 단위 테스트)에 `.spec.ts` 사례를 추가한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-07 게이트 예외 목록에 이유는 있지만 담당과 재검토 시점이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 26, 21, 23 |
| 근거 | `config/ci/ungated-tests.json`(6개)과 `ungated-scripts.json`(17개)의 스키마는 `path`/`script`와 `reason`뿐이다(`scripts/lib/ungated-tests.ts:20-32`, `ungated-scripts.ts:125-137`). `reason`은 공백이 아닌 1자 이상이면 된다. 재검토 장치는 "게이트가 이제 돌리면 stale로 실패"(`ungated-tests.ts:102-106`) 하나다. fanout 억제 주석은 이유 문구만 요구하고 목록이 없다(12-01). 반면 `contract-baseline.json`에는 `owner`가 있고, 경계 규칙 주석과 `pnpm-workspace.yaml` 예외에는 담당·재검토 조건이 있다. **실제 예:** `check:remediation-ledger`는 이유("history record … wiring it into a gate first needs …")만 있고, 리뷰 전부터 빨간 상태가 결정자 없이 이어진다. 게이트 밖 scale 테스트 6개의 마지막 기록은 2026-09-24다(`artifacts/scale/main/`). 이번에 6개를 한 번에 돌리자 23개 중 22개가 통과했다. 실패 1건(`telemetry-storm`)은 부하 평균 약 33에서 난 시간 초과였고, 단독 재실행에서 통과했다 |
| 발생 조건 | 예외가 쌓이거나, 예외의 전제(기준 CPU, 원장)가 바뀔 때 |
| 영향 | 누가 언제 다시 볼지 정해지지 않아 예외가 영구화된다. 다운스트림은 자기 예외와 템플릿 예외를 구분하기 어렵다 |
| 심각도·우선순위 | Low · P3 — 이유 문구는 구체적이고 대체 명령까지 적혀 있다. 1인 관리 템플릿이라 담당 필드의 효과는 제한적이다(26절 적용 범위) |
| 통제·증거 | M2(이유 필수, stale 검출) · E1 |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 현 형식의 근거: 이유 필수 + stale 자동 검출로 "게이트에 들어오면 목록에서 빠진다"는 가장 흔한 재검토를 자동화했다. 빠진 것은 "게이트에 못 들어온 채 오래된 것"이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 두 목록 스키마에 선택 필드 `owner`와 `revisit`(조건 문구 또는 날짜)을 추가한다. 템플릿 항목에는 `frontend-platform`을 적는다. 강제 만료 검사는 만들지 않는다 |
| 대안 비교 | 현 상태 유지: 비용 0, 원장 사례처럼 결정자가 없다. 선택 필드 추가: 수 줄, 다운스트림이 자기 항목을 구분한다. 만료 날짜 강제: 날짜가 지나면 게이트가 무작위로 빨개지는 비용이 크다. 선택 필드가 비용 대비 낫다 |
| 단순화의 보존 조건 | `reason` 필수와 stale 검출은 유지한다 |
| 비용·부작용 | 스키마 2줄, 항목 23개에 한 번 값 채우기 |
| 재검토 조건 | 템플릿 담당이 둘 이상이 되거나, 다운스트림 항목이 템플릿 항목보다 많아질 때 |
| 완료 기준 | 모든 항목에 담당이 있고, 재검토 조건이 이유 문구와 분리돼 있다 |
| 검증 방법 | 스키마 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| 출처 | 항목 | 결과 | 현재 근거 |
|---|---|---|---|
| FOLLOW-UP 1절 P2 | `check:remediation-ledger` 실패 | **유효 — 결정 필요** | `node scripts/check-remediation-ledger.ts` exit 1, 4건(TR-02·TR-03·TR-04 마커 없음, file-transfer 예산 55,700 문구 없음). `config/ci/ungated-scripts.json:17`에 이유와 함께 있다. tech-log도 같은 4건으로 빨갛고 "템플릿의 결정"으로 넘겼다. 필요한 결정: 원장을 현재 코드에 맞출지, 역사 기록으로 보고 검사·스크립트·목록 항목을 지울지. 목록의 이유 문구("history record run by hand, not a current contract")는 삭제 쪽을 가리킨다. 새 발견으로 세지 않는다 |
| FOLLOW-UP 4절 P3 | 12-12 `noUnusedParameters` 미적용 | 유효 | `tsconfig.base.json`에 `noUnusedLocals`만 있다 |
| FOLLOW-UP 4절 P3 | 07-07 `no-deprecated` lint 미적용 | 유효 | `eslint.config.ts`에 해당 규칙이 없다 |
| FOLLOW-UP 3절 P3 | `tests/system/ci-runner/ci-artifact-contract.test.ts` 시간 초과 | 유효 — 기록 정정 필요 | FOLLOW-UP은 "공통 게이트 밖"이라 적었지만 `test:system`은 merge 게이트 FE-GATE-013의 명령이다(`gates.json` FE-GATE-013, `package.json:52`). 이번에 부하 평균 약 30에서 한 번 돌렸을 때 10초 제한 테스트 8개가 시간 초과했다. 조용한 환경 재실행은 하지 않았다. 테스트 자체는 영역 11 |
| FOLLOW-UP 6절 | U-1 Actions·runner·required check | 유효 | Gitea API(2026-09-29): 템플릿 `has_actions: false`, `default_branch: main`. `af3d8e6`·`f753669`·`f1002fd`의 `/status`가 모두 `total_count: 0`. tech-log·memento도 `has_actions: false`, main HEAD 상태 0개. `/branch_protections` 401, `/actions/tasks` 403(토큰 필요). workflow push 트리거는 `[main, develop]`이다(`.gitea/workflows/quality-gates.yml:4-7`). 원격 `develop`은 `ebea300`에 멈춰 있다. README가 "상태 없음은 통과가 아니다, 머지 전 로컬 13개 게이트"를 밝힌다(`README.md:296-305`) |
| FOLLOW-UP 6절 | U-3 태그 `v0.2.0` push | 해소 | 원격에 `refs/tags/v0.2.0` → `f753669`가 있다. 영역 밖이라 참고로만 적는다 |
| FOLLOW-UP 4절 P2 | 13-03 production 단계가 runner에서 돈 적 없음 | 유효 | U-1과 같은 원인. 영역 13 |
| 지난 12-01~12-12 | 회귀 확인 | 회귀 없음 | 변이 M1(12-02), M2·M3(12-04), probe Q4a(12-03), Q5(12-06), Q6(12-07), Q7(12-08) 모두 실패. `config/architecture/layers.json` 삭제 확인(12-09, `3e1c421`). 그래프 위반 메시지에 규칙 이유 출력(12-11). `noUnusedLocals` 적용(12-12). 12-03·12-05의 잔여는 새 발견 12-03·12-05로 적었다 |
## 7. 미검증 목록
- **branch protection·Actions 실행 이력.** API가 401·403을 준다. 저장소 관리자 토큰으로 `/branch_protections`, `/actions/tasks`를 읽으면 확인할 수 있다.
- **생성된 workflow가 실제 Gitea runner에서 도는지, CI 소요 시간.** 세 repo 모두 Actions가 꺼져 있다. runner 1대와 PR 1건의 실행 기록이 필요하다.
- **fanout 미탐이 제품 코드에 실제로 있는지.** 두 제품 repo에서 helper·`useQueries`를 거친 행별 요청을 찾지 않았다. `src/features/**`에서 `Promise.all(… .map(` 호출을 따라가면 확인할 수 있다.
- **12-02 개선 뒤 영어 하드코딩이 템플릿에 몇 건 걸리는지.** 리터럴 검사를 켠 변이 실행이 필요하다.
- **`tests/system` 전체와 `ci-artifact-contract.test.ts`의 조용한 환경 결과.** 동시에 13개 에이전트가 돌아 부하가 높았다. 부하 없는 단독 실행이 필요하다(영역 11).
- **12-05 제거 시 빠지는 전이 패키지 수.** `pnpm remove` 결과 lockfile diff가 필요하다(이 리뷰는 설치 명령을 쓰지 않는다).
- **제거 게이트(`test:*-removal`)에서 12-04 개선안이 통과하는지.** 제거 스크립트는 fixture에서 `pnpm`을 부른다. worktree의 `node_modules`가 메인 링크라 돌리지 않았다.
- **전체 `lint`·`check:types`.** 오케스트레이터 결과(모두 PASS)를 따랐다. 이 영역에서는 probe 파일에 대해서만 ESLint·`tsc -p tsconfig.app.json`을 돌렸다.
@@ -0,0 +1,413 @@
# 13. 빌드·릴리스·설정·공급망 성숙도 리뷰
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6`(태그 `v0.2.0` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 영역 판정(35.8): **조건부 사용 가능.** 기본 구성(SW `null`, 루트 경로, 셸 환경변수로 빌드 변수 전달)의 빌드·설정·승인 흐름은 그대로 써도 된다. SW `ACTIVE`로 staging·production 릴리스를 하려면 13-01을 먼저 고친다. `.env*` 파일로 빌드 변수를 바꾸는 사용은 13-02를 고치기 전까지 피한다.
## 1. 머리말
| 항목 | 기록 |
|---|---|
| 영역 | 13 — 빌드·릴리스·설정·공급망 |
| 경로 | `scripts/build-frontend.ts`, `scripts/generate-runtime-config.ts`, `scripts/generate-build-manifest.ts`, `scripts/check-release-admission.ts`, `scripts/generate-supply-chain.ts`, `scripts/verify-exact-promotion-bundle.ts`, `scripts/verify-hosting-headers.ts`, `scripts/check-bundle.ts`, `scripts/check-browser-security.ts`, `scripts/lib/{supply-chain,classify-vite-bundle,hosting-probe,dist-permissions,secret-scan}.ts`, `vite.config.ts`, `vite.service-worker.config.ts`(빌드 두 번째 단계만), `config/{release,hosting,runtime,security,performance}`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.npmrc`, `.env.example`, `.gitea/workflows/quality-gates.yml`의 immutable_build·promotion·production_gate job |
| 기준 커밋·상태 | `af3d8e6`. 워킹트리 미커밋은 리뷰 가이드 문서 2개뿐이다. 모든 실험은 분리 worktree(`scratchpad/review-2026-09-29/13/wt`, `af3d8e6`)에서 했고 끝난 뒤 지웠다. |
| 전제 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + SW. SSR 없음. 운영 규모 목표 없음. 초기 JS 예산(`config/performance/budgets.json`)만 수치 목표가 있다. |
| 읽은 범위 | 위 경로 전체. 주장 자료로 `README.md:25-66`, `README.md:315-353`, `CHANGELOG.md` 0.2.0, `docs/security/browser-boundary.md`, `docs/architecture/optional-adapter-recipes.md` 9단계, `docs/operations/release-cache-rollback.md`. 지난 리뷰 `2026-09-25-maturity-review/13-*.md`, `README.md` 11절, `FOLLOW-UP.md`. 제품 기록 2개(`tech-log-frontend`, `memento-frontend`의 `chore/template-sync-v0.2.0:docs/operations/template-sync-2026-09-29.md`)와 두 제품의 `vite.config.ts`, `vite.service-worker.config.ts`, `config/hosting/security-headers.json`, `tests/unit/build-environment-bundle.test.ts`를 `git show`로 읽었다. |
| 실행한 테스트 | worktree에서 `node scripts/run-vitest.ts run tests/unit/{archived-promotion,build-environment-bundle,build-environment,bundle-classification,deployment-admission,dist-permissions,hosting-probe,promotion-readiness,release-artifacts,sub-path-deployment,supply-chain,vite-module-inventory}.test.ts tests/release tests/platform/release tests/runtime-schema/runtime-config.test.ts` → **19 files, 200 tests 통과** |
| 실험(모두 worktree) | ① `VITE_BUILD_ID`만 바꿔 두 번 빌드한 뒤 청크 이름 비교 ② `manualChunks`에 route 청크 이름을 붙이는 변이 → 번들 테스트·build manifest ③ route 페이지가 build id를 읽는 변이 → 번들 테스트 ④ SW `ACTIVE` + `APP_PROFILE=production` 빌드 → `dist/config.json`, admission, `verify-release` ⑤ SW `ACTIVE` + `VITE_ROUTER_BASE_PATH=/app/` 빌드 ⑥ `.env.production.local`에만 `VITE_ROUTER_BASE_PATH`·`VITE_BUILD_ID`를 둔 빌드 → `verify-release` ⑦ `build:app-only` 경로를 `APP_PROFILE=production`으로 실행 ⑧ `security-headers.json`에 CDN을 더한 뒤 `verify-hosting-headers` ⑨ `check-bundle.ts`, `check-optional-recipes.ts --require-dist` ⑩ `APP_PROFILE`·`RELEASE_TARGET` 불일치 admission ⑪ `VITE_BUILD_ID` 없는 staging·production 설정 생성 ⑫ `no-whole-import-meta-env` lint 변이(4가지 형태) ⑬ `build.rolldownOptions`를 추가하는 변이 ⑭ scratch 폴더에서 pnpm 11 `engineStrict` 강제 여부 ⑮ `pnpm list --json --depth Infinity`로 production 폐포와 SBOM scope 비교 |
| 확인하지 못한 범위 | 7절. 요약: 실제 호스팅·CDN, Gitea workflow 실행(U-1), 외부 provider, Playwright(`production-csp.spec.ts` 포함)는 이번에 돌리지 않았다. 다른 영역 에이전트가 같은 포트(4173)를 쓸 수 있어서다. |
### 1.1 CHANGELOG 0.2.0 [보안]·[계약] 재확인
| 항목 | 결과 | 근거 |
|---|---|---|
| `VITE_*`는 키로만 읽는다(13-06) | 확인 | `src/contracts/env.ts:131-137`. 선언 안 된 `VITE_PAYMENT_KEY`는 빌드를 멈춘다(`vite.config.ts:13-24`, 번들 테스트 2번째 케이스 통과). lint 변이 ⑫에서 전체 참조·캐스팅·computed·구조분해 4건을 모두 잡았다(`eslint.config.ts:900-944`). |
| 설정·매니페스트 URL이 `VITE_ROUTER_BASE_PATH`를 따른다(13-07) | 부분 | 앱 번들과 `dist/config.json`은 따른다(`src/contracts/env.ts:143-144`, `scripts/generate-runtime-config.ts:57-67`, `tests/unit/sub-path-deployment.test.ts`). SW 빌드와 호스팅 probe는 따르지 않는다(13-06). 값을 `.env*` 파일로 주면 base가 번들에만 들어간다(13-02). SW `ACTIVE`면 rebasing이 덮어써진다(13-01). |
| staging·production은 `VITE_BUILD_ID` 필수(13-15) | 확인 | 실험 ⑪: `config/runtime/staging.json: a staging build requires VITE_BUILD_ID`, 빈 값도 거절(`scripts/generate-runtime-config.ts:70-72`). README 변수 표에는 이 조건이 없다(13-09). |
| `RELEASE_TARGET`≠`APP_PROFILE`이면 승인 거절(12-02, 13-01) | 확인 | 실험 ⑩: exit 1(`scripts/check-release-admission.ts:45-55`). workflow의 immutable_build가 FE-GATE-027을 실행한다(`.gitea/workflows/quality-gates.yml:128-144`). |
| `engineStrict`·`saveExact`를 `pnpm-workspace.yaml`로(13-09) | 확인 | 실험 ⑭: `engines.node "<1.0.0"`에서 install exit 1. `pnpm config get engine-strict` → `true`. 회귀를 막는 검사는 없다(13-08). |
## 2. 대표 흐름
### 2.1 정상 흐름 — production 빌드와 승인
```
APP_PROFILE=production VITE_BUILD_ID=… RELEASE_ID=… RUNTIME_API_BASE_URL=… pnpm build
→ generate-product-feature-index
→ build-frontend.ts
1 dist 정리 → 2 contract set
→ 3 vite build (vite.config.ts: 선언 안 된 VITE_* 거절, base = process.env.VITE_ROUTER_BASE_PATH,
public/ 전체를 dist/로 복사 → dist/config.json = 로컬 프로필)
→ 4 generate-runtime-config (config/runtime/production.json → dist/config.json 덮어쓰기,
RUNTIME_* 두 값만 대체, manifest URL을 base로 rebase, VITE_BUILD_ID 필수)
→ 5·6 SW (기본 null이면 건너뜀)
→ 7 generate-build-manifest (dist/config.json을 읽고 BUILD_ID·RELEASE_ID를 넣어 다시 씀, release manifest)
→ 8 makeDistFilesPublic (0600 → 읽기 허용)
→ APP_PROFILE=production RELEASE_TARGET=production pnpm check:release-admission
(프로필≠대상 거절 → APP_ENV·AUTH_MODE·https·loopback/사설 호스트 규칙 → artifacts/release/deployment-admission.json)
```
- 입력: 셸 환경변수, `config/runtime/<profile>.json`.
- 정책: 런타임 스키마 한 벌(`runtimeConfigV2ArtifactSchema`), 공개 대상 규칙(`src/contracts/deployment-admission.ts:34-37`, `:75-`).
- 상태 변화: `dist/` 전체, `artifacts/release/deployment-admission.json`.
- 실패: 각 단계가 0이 아닌 코드면 즉시 중단(`scripts/build-frontend.ts:43-52`). admission은 fail-closed.
- 결과: 로컬에서 실험 ⑩·⑪로 확인했다. 이 흐름의 정확성은 **"4단계가 3단계의 public 복사를 덮어쓰고, 그 뒤에는 아무도 dist/config.json을 다시 덮어쓰지 않는다"는 단계 순서**에 기대고 있다. 끝에서 이 사실을 확인하는 검사는 없다(13-01).
### 2.2 피해가 큰 흐름 — SW `ACTIVE`로 운영 릴리스
```
installed-runtime-capabilities.ts: SERVICE_WORKER = { mode: "ACTIVE", … }
APP_PROFILE=production … pnpm build
→ 3 vite build → 4 generate-runtime-config (production 프로필)
→ 5 generate-service-worker-assets
→ 6 vite build --config vite.service-worker.config.ts
설정 로드 시 dist/config.json(production)을 읽어 SW에 manifest URL을 넣는다(:53-55)
emptyOutDir:false, publicDir 기본값 → public/config.json을 dist/로 다시 복사 ← 여기서 로컬 프로필로 돌아간다
→ 7 generate-build-manifest: 로컬 프로필에 BUILD_ID=rel-prod-1만 덮어씀
→ exit 0, verify-release PASS
→ check:release-admission (RELEASE_TARGET=production)
refused: APP_ENV local, AUTH_MODE demo, http:, localhost
```
- 외부 I/O: 없음(로컬 빌드).
- 결과: 실험 ④에서 그대로 재현했다. CI(FE-GATE-027)를 거치면 릴리스가 막힌다. admission을 거치지 않는 배포라면 demo 인증 + `http://localhost:8080/` 설정이 운영에 나간다. 제품 memento는 같은 결함을 `publicDir: false`로 막았다(제품 기록 204행, 345행).
### 2.3 변경 흐름 — 다운스트림이 청크 설정을 바꾼다
```
vite.config.ts manualChunks에 route 청크 이름 추가 (tech-log 방식)
→ rolldown 청크 경계·이름이 바뀐다
→ generate-build-manifest: entry.name === route moduleId 로 route 청크를 찾는다
이름이 "route-home-page"가 되면 "Missing built route chunk: APP_HOME" (실험 ②, build exit 1)
→ tests/unit/build-environment-bundle.test.ts: "design-system-*" 청크가 정확히 1개라고 가정
이름이 사라지면 "expected [] to have a length of 1" (실험 ②)
route 페이지가 build id를 읽어 route 청크가 매 빌드 바뀌어도 통과 (실험 ③)
```
- 결과: 청크 이름이 계약처럼 쓰이지만 어디에도 선언돼 있지 않다(13-03). tech-log는 이 테스트를 자기 청크 이름(`render-boot-failure-*`)으로 바꿨고 여전히 실패 중이다(제품 기록 470행).
## 3. 28개 관점 판정표
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. **굵은 번호**는 이번 영역의 깊게 볼 관점이다.
| 번호 | 관점 | 판정 | 이유·근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | > | `src/` 규칙은 각 영역 |
| 2 | 구조적 성숙도 | > | 영역 12 |
| 3 | 변경 용이성 | P | 프로필 추가는 `config/runtime/<name>.json`과 `DEPLOYMENT_TARGETS`면 된다. 청크 설정(13-03)과 CSP(13-04)를 바꾸면 선언되지 않은 곳이 함께 깨진다. |
| 4 | 인지 부하 | P | 빌드 8단계가 한 주석에 정리돼 있다(`scripts/build-frontend.ts:10-38`). 두 번째 Vite 단계가 `public/`을 다시 복사한다는 사실은 어디에도 없다(13-01). |
| 5 | 위험 가시성 | P | hosting fixture 모드가 이제 `UNVERIFIED`(exit 3)로 드러난다(`scripts/verify-hosting-headers.ts:231-236`). SW 빌드가 설정을 되돌린 경우 admission 오류는 "artifact declares local"만 말하고 원인을 가리키지 않는다(13-01). |
| 6 | 실패 성숙도 | O | 이 범위(빌드 단계 실패 처리)에서 각 단계 비정상 종료 시 즉시 중단(`scripts/build-frontend.ts:43-52`), 프로필 `APP_ENV` 불일치 throw(`scripts/generate-runtime-config.ts:48-52`). |
| 7 | 운영 성숙도 | > | telemetry는 영역 03 |
| 8 | 디버깅 가능성 | P | build id·release id가 config·manifest·admission 기록에 남는다. "Missing built route chunk" 메시지는 원인(청크 이름 = moduleId 규약)을 말하지 않는다(13-03). |
| 9 | 유지보수 성숙도 | P | CSP 문자열이 4벌이다(13-04). 청크 설정이 폐기 예정 키에 있다(13-07). |
| 10 | 테스트 성숙도 | P | 대상 테스트 200개 통과(E2). 빌드 테스트가 local 프로필·SW null·루트 base·셸 변수만 본다(13-01, 13-02, 13-06). 해시 안정성 테스트가 청크 이름에 묶여 있다(13-03). |
| 11 | 데이터 성숙도 | > | 브라우저 저장소 영역 |
| 12 | 동시성 성숙도 | > | 탭·저장소 영역 |
| 13 | 확장성 | > | extreme-scale(영역 11) |
| 14 | 성능 성숙도 | P | 실험 ⑨: 초기 JS **203,481 / 204,800** gzip bytes, 여유 1,319 B. `config/scale/feature-shape-growth.json`에서 기능 모양 1개 ≈ +2,980 B(25개 추가 시 200,001 → 274,493). 실험 ①: build id만 바꿔도 초기 JS 중 index·boot·render-boot-failure 3개 청크(약 96 KB gzip, react-dom 포함)가 매 빌드 바뀐다. |
| **15** | 보안 성숙도 | P | `VITE_*` 선언 강제(E3, `vite.config.ts:13-24`)와 lint(E3)는 충족. 운영 CSP를 넓히는 경로에 안내·내용 검사가 없다(13-04, E3). `connect-src 'self' https:`는 문서화된 한계(`docs/security/browser-boundary.md:21-25`). secret scan 규칙은 여전히 4개(`scripts/lib/secret-scan.ts:20-31`)지만 13-06 수정으로 번들 유입 경로 자체가 막혀 위험이 줄었다. |
| **16** | 의존성 성숙도 | P | lockfile 561행 모두 sha512, tarball·git 0개. `engineStrict` 동작 확인(실험 ⑭). SBOM이 `scheduler@0.27.0`을 development로 적는다(13-05, E3). 청크 설정이 폐기 별칭에 있다(13-07). 설치 정책 회귀 검사 없음(13-08). `build-frontend.ts:62`, `:71`은 여전히 `npx vite`를 쓴다. |
| 17 | API / Contract 성숙도 | > | 설정 스키마 호환은 영역 07 |
| **18** | 배포 성숙도 | P | drill이 승격 release를 입력으로 받는다(`config/ci/gates.json` `drill-runbook` 인자 `--release-root .release/promoted-release`). 보관 release 재검증 모드가 있다(`scripts/verify-exact-promotion-bundle.ts:58-60`, `tests/unit/archived-promotion.test.ts` 통과). SW `ACTIVE`의 공개 대상 릴리스가 막힌다(13-01). production_gate의 FE-GATE-019는 `build`를 다시 돌려 로컬 dist의 source map·SW를 본다(`gates.json` FE-GATE-019 `commandIds: [build, verify-hosting-headers]`). 같은 커밋이라 결과 차이는 작다. 실제 호스팅 미검증. |
| **19** | 설정 성숙도 | X | 기본 경로는 스키마 한 벌·프로필 정본·공개 대상 규칙으로 잘 막혀 있다. 그러나 문서가 약속한 두 규칙이 지원 입력에서 깨진다. "dist/config.json은 선택한 프로필이다"가 SW `ACTIVE`와 `build:app-only`에서 깨진다(13-01, E3). "하위 경로 배포는 일관되거나 빌드에서 실패한다"(`vite.config.ts:26-34`)가 `.env*` 파일 입력에서 깨진다(13-02, E3). |
| 20 | 개발자 경험 | P | README에 변수 표와 production 빌드 예시가 있다(`README.md:38-66`). `.env.example:11`의 "`.env.local`로 복사해 덮어쓰라"는 안내가 13-02를 부른다. 필수 조건 누락(13-09). |
| **21** | Guardrail 성숙도 | P | admission fail-closed(E3), 선언 안 된 `VITE_*` 거절(E2), lint 규칙(E3). 빌드 마지막에 dist/config.json을 확인하는 검사가 없다(13-01). 해시 안정성 검사가 대리 지표다(13-03). CSP 내용·설치 정책 검사가 없다(13-04, 13-08). |
| 22 | 추상화 성숙도 | > | 영역 09·12 |
| 23 | 일관성 | P | 기본 설정 URL을 두 곳에서 다르게 계산한다(13-06). 빌드 변수를 읽는 출처가 `loadEnv`와 `process.env`로 갈린다(13-02). `npx`와 `corepack pnpm` 혼용. |
| 24 | 네이밍 / 의미 성숙도 | P | `build:app-only`라는 이름이 "프로필을 무시하고 로컬 설정을 싣는다"는 사실을 드러내지 않는다(13-01). 테스트 이름 "keeps the values the app reads and nothing else" 안에 청크 해시 검사가 섞여 있다(13-03). |
| 25 | 조직 확장성 | - | 1인 관리 전제 |
| **26** | Ownership 성숙도 | P | 템플릿 결함 분류 규칙이 README에 있다(`README.md:348-353`). 이 규칙은 "선택 기능을 켜야 재현되는 템플릿 결함"을 제품 몫으로 분류하게 만든다. 이번 동기화의 제품 상향 보고 2건은 제품 문서에만 있다(13-10). 의존성 기준선 승인은 환경변수 자기 기재다(`scripts/update-dependency-baseline.ts:6-13`). |
| 27 | 삭제 가능성 | > | 영역 14(FE-GATE-020) |
| 28 | 회복 가능성 | P | 보관 release 재검증 모드와 drill `--release-root`가 생겼다(E2). `--archived`는 workflow에 없고 runbook 수동 절차뿐이다(`docs/operations/release-cache-rollback.md:30`). 실제 provider·호스팅 복구는 미검증(U-1). |
## 4. 설계 선택 설명 (41절)
### 4.1 런타임 설정을 빌드 단계 순서로 만든다 — "public 복사 → 프로필로 덮어쓰기"
1. **무엇이 필요한가.** `pnpm dev`는 `public/config.json`을 바로 서빙해야 한다. 배포 빌드는 선택한 환경의 설정을 실어야 한다.
2. **지킬 성질.** 배포 산출물의 `dist/config.json`은 `APP_PROFILE`의 프로필(+ `RUNTIME_*` 두 값, build identity)과 같아야 한다.
3. **현재 보장.** `build-frontend.ts`의 4단계가 3단계(Vite의 `public/` 복사)를 덮어쓴다(확인한 사실, `scripts/build-frontend.ts:31-37` 주석에도 적힘). admission이 공개 대상에서 `APP_ENV`를 대조한다(확인한 사실). **보장하지 않는 것:** 4단계 뒤에 다시 `public/`을 복사하는 경로(SW 두 번째 Vite 단계), 4단계를 건너뛰는 경로(`build:app-only`). 빌드 끝에서 성질을 확인하는 곳이 없다.
4. **대안.** (a) 현상 유지. (b) SW 설정에 `publicDir: false`만 추가. (c) 모든 경로가 거치는 마지막 단계(`generate-build-manifest.ts`)에서 `APP_ENV === (APP_PROFILE ?? "local")`을 확인. (d) `public/config.json`을 없애고 dev 서버가 프로필을 서빙.
5. **비교.** (b)는 한 줄이고 알려진 경로만 막는다. (c)는 한 곳에서 두 경로를 모두 잡고 다음에 생길 경로도 잡는다. 비용은 몇 줄이다. (d)는 dev 서버 미들웨어가 필요하다. memento는 dev 프로필 미들웨어를 이미 두고 있다(제품 기록 214행). 변경 폭이 크다.
6. **현재 조건에서의 판단(리뷰어 추론).** (b)+(c)가 가장 작은 변경으로 성질을 되찾는다. 현 구조(복사 후 덮어쓰기)는 유지해도 된다. 확인 한 줄이 빠진 것이 문제다.
7. **재검토 조건.** 빌드 단계가 더 늘거나, dev 서버가 프로필을 직접 서빙해야 할 요구(예: 여러 로컬 프로필)가 생기면 (d)를 다시 본다.
`APP_PROFILE`과 `RELEASE_TARGET`을 두 변수로 둔 선택도 같은 흐름에 있다. 빌드 입력과 승인 대상을 따로 선언하고 서로 대조한다. 한 변수로 합치면 "무엇을 빌드했는가"와 "어디에 올리려는가"를 따로 적는 이중 확인이 사라진다. 두 값이 repo 단위 변수 하나씩이라 환경을 바꿀 때 둘 다 바꿔야 한다는 비용이 남는다. 현재 조건에서는 유지가 맞다(리뷰어 추론). 환경별 변수(Gitea environment)가 생기면 다시 본다.
### 4.2 빌드 식별값을 JS 번들에 넣고, 청크 분할은 자동에 맡긴다
1. **무엇이 필요한가.** 부팅 시 JS와 `config.json`·release manifest가 같은 release인지 대조해야 한다(`src/bootstrap/load-runtime-config.ts:152-167`, `CONFIG_BUILD_MISMATCH`). 그러려면 JS가 자기 build id를 알아야 한다.
2. **지킬 성질.** build id만 바뀐 두 빌드에서 route 청크와 공용 UI 코드는 해시가 같아야 한다(09-03의 기록된 의도: `src/bootstrap/main.tsx:10-12`, `vite.config.ts:74-76`). 브라우저·SW 캐시를 release마다 버리지 않기 위해서다.
3. **현재 보장.** `getBuildConfig`가 키별로 읽어 build id 문자열을 `env.ts`가 들어간 청크에만 넣는다. preload helper를 따로 떼어 entry를 가볍게 한다(확인한 사실). 템플릿의 현재 청크 그래프에서는 `env.ts`가 `render-boot-failure` 청크(react-dom 포함, 약 58 KB gzip)에 들어가고, 이 청크는 entry와 boot만 import한다. 그래서 route 청크와 `design-system` 청크는 안정적이다(실험 ①). **보장하지 않는 것:** 어느 청크가 build id를 품을지는 rolldown의 자동 분할이 정한다. 설정이나 import 그래프가 조금 바뀌면 달라진다(실험 ②·③, tech-log). 검증은 청크 이름 하나만 본다(13-03).
4. **대안.** (a) 현상 유지. (b) 테스트를 "route 청크(Vite manifest의 `isDynamicEntry`)와 그 정적 import는 build id만 바뀐 두 빌드에서 파일명이 같다"로 바꾼다. (c) build identity를 `manualChunks`로 전용 청크에 격리한다. 이 경우 importer의 해시는 여전히 연쇄로 바뀐다. (d) build id를 JS 밖(HTML `meta` 등, HTML은 `no-cache`)에서 읽는다.
5. **비교.** (b)는 성질 자체를 검사하고 청크 이름과 무관하다. 비용은 테스트 수정뿐이다. (c)는 연쇄 변경을 막지 못해 효과가 작다. (d)는 JS를 release 간 바이트 동일하게 만들 수 있다. 대신 오래된 탭·SW 캐시가 HTML과 JS를 다른 release에서 받는 조합을 다시 따져야 하고, 부팅 대조 로직(`checkReleaseCoherence`)의 입력이 바뀐다.
6. **현재 조건에서의 판단(리뷰어 추론).** 성질 검사를 (b)로 바꾸는 것이 먼저다. 식별값 위치를 옮기는 (d)는 측정된 캐시 비용이 생긴 뒤에 검토해도 된다. 현재 매 빌드 약 96 KB gzip이 바뀌는 비용은 기록된 목표가 없어 결함으로 보지 않았다.
7. **재검토 조건.** 재방문 사용자의 전송량·SW 설치 비용 목표가 생기거나, 다운스트림이 route 청크 이름을 필수로 쓰게 되면(tech-log) 다시 본다.
### 4.3 모든 환경에 CSP 파일 하나를 둔다
1. **필요.** 운영 응답 헤더의 기준값 한 벌. 로컬 e2e(`tests/e2e/production-csp.spec.ts`)와 호스팅 live 검사(`scripts/verify-hosting-headers.ts`)가 같은 값을 읽는다.
2. **지킬 성질.** 인라인 스크립트·`eval` 없이 부팅한다. 선언과 실제 응답 헤더가 같다.
3. **현재 보장.** e2e가 선언 헤더를 붙여 두 화면을 열고 위반 0건을 확인한다(코드 확인, 이번에 실행하지 않음). live 모드는 선언과 응답을 문자열로 비교한다. **보장하지 않는 것:** 다운스트림이 CSP를 넓힐 때 무엇을 바꿔야 하는지(폰트·스타일), 넓힌 값이 안전한지(`'unsafe-inline'`, `*`)는 아무도 보지 않는다. `connect-src`를 API·telemetry origin으로 좁히는 것은 배포 단계 생성기가 필요하다고 문서가 스스로 적는다.
4. **대안.** (a) 현상 유지. (b) 파일 하나를 유지하되 금지 키워드 검사와 "넓히는 법" 문서를 더한다. (c) 프로필별 CSP를 배포 시 생성한다.
5. **비교.** (b)는 작고 기본값의 강도를 유지한다. (c)는 `connect-src`를 좁힐 수 있지만 provider adapter와 생성기가 필요하다.
6. **판단(리뷰어 추론).** 템플릿이 호스팅을 정하지 않은 현재 조건에서는 (b)가 맞다.
7. **재검토.** 호스팅 provider adapter가 템플릿에 들어오거나, 환경마다 API origin이 달라 `connect-src`를 좁혀야 하는 요구가 생기면 (c)를 본다.
## 5. 발견 사항
### 13-01 SW `ACTIVE` 빌드와 `build:app-only`가 선택한 프로필 대신 로컬 설정을 `dist/config.json`에 싣는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 18, 21, 10, 5 (+30.2) — SW 빌드 설정은 영역 06과 겹친다 |
| 근거 | `vite.service-worker.config.ts:69-82`는 `emptyOutDir: false`이고 `publicDir`를 끄지 않는다. Vite는 두 번째 빌드에서도 `public/`을 `dist/`로 복사한다. 그래서 4단계(`scripts/generate-runtime-config.ts`)가 쓴 프로필 문서를 `public/config.json`(로컬 프로필)이 덮는다. 7단계 `scripts/generate-build-manifest.ts:58-60`, `:76-77`, `:124-128`은 그 파일을 읽어 `BUILD_ID`·`RELEASE_ID`만 바꿔 다시 쓴다. 실험 ④: SW `ACTIVE` + `APP_PROFILE=production` + `VITE_BUILD_ID=rel-prod-1` 빌드 exit 0 → `dist/config.json`이 `APP_ENV=local, AUTH_MODE=demo, API_BASE_URL=http://localhost:8080/, BUILD_ID=rel-prod-1`. `verify-release` PASS. admission(`RELEASE_TARGET=production`)만 4개 위반으로 거절. 실험 ⑤: SW `ACTIVE` + `/app/`이면 로컬 빌드에서도 `RELEASE_MANIFEST_URL`이 `/app/release-manifest.json`에서 `/release-manifest.json`으로 되돌아간다(13-07 rebasing이 사라짐). 실험 ⑦: `build:app-only`(`package.json:125`)는 4단계와 권한 단계를 건너뛴다. `APP_PROFILE=production`으로 돌려도 `local demo` 설정과 mode 0600 파일 3개가 나온다. SW e2e 도우미는 `APP_PROFILE` 없이(로컬) 빌드한다(`tests/e2e/support/service-worker-builds.ts`의 `run`). 로컬 프로필은 `public/config.json`과 내용이 같아 결함이 드러나지 않는다. 제품 memento 기록 204행·345행: 같은 결함을 `publicDir: false`로 막고 "템플릿의 잠재 결함"으로 올렸다. |
| 발생 조건 | SW를 `ACTIVE`로 선택하고 local이 아닌 프로필이나 하위 경로로 빌드할 때. 또는 `build:app-only`를 배포 빌드로 쓸 때 |
| 영향 | 문서의 절차(빌드 → admission)를 따르면 staging·production 릴리스가 항상 거절된다. 오류는 "artifact declares local"이라서 원인을 찾기 어렵다. admission을 거치지 않는 배포라면 운영에 demo 인증 + localhost API가 나가 전면 장애가 난다. 하위 경로 배포면 부팅 시 manifest 404. |
| 심각도·우선순위 | Medium · P1 — 기본 구성(SW null)에는 영향이 없다. 문서화된 경로에서는 fail-closed로 막혀 조용한 피해는 없다. 대신 지원하는 선택 기능의 운영 릴리스를 막는 차단 항목이고, 실제 제품이 이미 부딪혔다. admission 없이 배포하는 사용이라면 High로 올린다. |
| 통제·증거 | 프로필 규칙 M2(4단계 구현) / 빌드 끝 확인 M0 / 공개 대상 승인 M3 · E3(실험 ④⑤⑦) |
| 확실성과 남은 가정 | 산출물을 직접 확인했다. 브라우저 부팅은 하지 않았다. |
| 결정의 근거 | 4.1절. 현재 구조(복사 후 덮어쓰기)는 유지하고, 빠진 확인을 더한다. 확인한 사실: 두 경로의 결과. 기록된 의도: `scripts/build-frontend.ts:31-37`. 추론: 마지막 공통 단계에서 확인하면 새 경로도 잡힌다. |
| 이해 비용 | SW를 켜는 제품 작성자가 Vite의 `publicDir` 기본 동작과 빌드 단계 순서를 알아야 원인을 찾는다. |
| 최소 개선 방향 | (1) `vite.service-worker.config.ts`에 `publicDir: false`. (2) 두 경로가 모두 거치는 `scripts/generate-build-manifest.ts`에서 `dist/config.json`의 `APP_ENV`가 `APP_PROFILE ?? "local"`과 다르면 실패시킨다. (3) `build:app-only`를 없애거나 4단계·권한 단계를 포함하게 한다. |
| 대안 비교 | 4.1절 (b)만 하면 `build:app-only`와 다음 경로가 남는다. (c)만 하면 SW 빌드가 실패로 바뀌지만 원인 수정은 여전히 필요하다. 둘 다 하는 것이 가장 작다. |
| 단순화의 보존 조건 | `pnpm dev`가 `public/config.json`을 그대로 쓰는 동작, 06-10(SW 설정이 프로필 문서를 읽음), 13-02(권한) 유지 |
| 비용·부작용 | 작다. SW의 `public/` 자산(예: 아이콘)을 두 번째 단계가 복사하던 효과는 첫 단계가 이미 하므로 잃지 않는다. |
| 재검토 조건 | 빌드 단계가 3개 이상 더 늘면 단계 대신 "산출물 검증 목록" 방식으로 바꾼다. |
| 완료 기준 | SW `ACTIVE` + `APP_PROFILE=production` 빌드의 `dist/config.json`이 production 프로필이다. `APP_PROFILE=production pnpm build:app-only`가 실패하거나 production 설정을 낸다. |
| 검증 방법 | 빌드 테스트 한 개: 임시 복사본에서 SW `ACTIVE`로 바꾸고(`service-worker-builds.ts`의 `replaceOnce` 재사용) `APP_PROFILE=staging`으로 빌드 → `APP_ENV === "staging"` 확인. `generate-build-manifest`에 불일치 fixture 단위 테스트. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-02 빌드 변수를 `.env*` 파일로 주면 번들과 빌드 스크립트가 서로 다른 값을 쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 19, 23, 21, 18, 20 |
| 근거 | Vite는 `.env`, `.env.local`, `.env.[mode]`, `.env.[mode].local`을 읽어 `import.meta.env`에 넣는다. `vite.config.ts:14`도 이를 알고 `loadEnv`로 미선언 변수를 거른다. 그런데 같은 파일의 base 결정과 설정 URL 검사는 `process.env`만 읽는다(`vite.config.ts:64-65`). 빌드 스크립트도 `process.env`만 읽는다: `scripts/generate-runtime-config.ts:59`, `:70-73`, `scripts/generate-build-manifest.ts:36-38`, `vite.service-worker.config.ts:57-58`, `:94-96`. 실험 ⑥: `.env.production.local`에 `VITE_ROUTER_BASE_PATH=/app/`, `VITE_BUILD_ID=env-file-id`를 두고 `node scripts/build-frontend.ts` → exit 0. 번들은 router base `/app/`, build id `env-file-id`. `index.html`은 `src="/assets/…"`(base `/`). `dist/config.json`은 `BUILD_ID=local-build`, `RELEASE_MANIFEST_URL=/release-manifest.json`. release manifest `buildId=local-build`. build id만 파일에 둔 두 번째 실행에서도 `verify-release` PASS. 부팅 시 `load-runtime-config.ts:152-167`이 JS build id와 config `BUILD_ID`를 대조하므로 `CONFIG_BUILD_MISMATCH`가 난다(코드 읽기). `.env.example:11`은 "`.env.local`로 복사해 덮어쓰라"고 안내하고, `:20-21`은 이 값이 "router, SW scope, Vite asset base를 함께 정한다"고 적는다. |
| 발생 조건 | 개발자나 제품이 `VITE_ROUTER_BASE_PATH`, `VITE_RUNTIME_CONFIG_URL`, `VITE_BUILD_ID`를 셸이 아닌 `.env*` 파일에 두고 빌드할 때. `.env.example`을 그대로 복사하면 값이 기본값과 같아 문제가 없다. 값을 바꾸는 순간 생긴다. CI는 셸 변수를 쓰므로 영향이 없다. |
| 영향 | 빌드와 `verify-release`는 통과하고 부팅이 실패한다(설정 404 또는 build 불일치). 13-07이 약속한 "하위 경로 배포는 일관되거나 빌드에서 실패한다"(`vite.config.ts:26-34`)가 이 입력에서는 성립하지 않는다. `.env.local`에 `VITE_RUNTIME_CONFIG_URL=/config.json`이 남아 있으면 셸로 base를 `/app/`로 줘도 `assertRuntimeConfigUnderBase`가 파일 값을 보지 못한다. |
| 심각도·우선순위 | Medium · P2 — 문서가 권하는 입력 방식에서 조용히 깨진 산출물이 나온다. CI 경로는 영향이 없고 첫 부팅에서 드러난다. |
| 통제·증거 | 선언 여부 M3(파일 포함) / 값 일관성 M0 · E3(실험 ⑥) |
| 확실성과 남은 가정 | 산출물을 직접 확인했다. 브라우저 부팅은 하지 않았다(부팅 실패는 코드 읽기). |
| 결정의 근거 | 적용 제외 — 한 값을 두 출처에서 읽는 구현 결함이다. |
| 이해 비용 | 빌드 변수가 어디서 읽히는지 파일 5개를 봐야 안다. |
| 최소 개선 방향 | 빌드 식별·경로 변수의 출처를 하나로 만든다. 가장 작은 방법: `vite.config.ts`에서 `loadEnv(mode, cwd, "VITE_")` 결과가 `VITE_BUILD_ID`·`VITE_ROUTER_BASE_PATH`·`VITE_RUNTIME_CONFIG_URL`에 대해 `process.env`와 다르면 빌드를 멈춘다("이 변수는 셸로만 준다"). `.env.example`에서 세 변수를 빼거나 "셸 전용"으로 적는다. |
| 대안 비교 | 모든 스크립트가 `loadEnv`를 쓰게 하는 방법도 있다. 스크립트 5곳을 바꿔야 하고 mode 개념을 node 스크립트까지 끌고 온다. 거절 한 곳이 더 작다. |
| 단순화의 보존 조건 | 미선언 `VITE_*` 거절(13-06) 유지 |
| 비용·부작용 | 작다. 파일로 build id를 주던 로컬 습관이 있다면 셸로 옮겨야 한다. |
| 재검토 조건 | 빌드 변수가 더 늘어 셸 전용 규칙이 불편해지면 `build-frontend.ts`가 한 번 `loadEnv`해서 모든 단계에 넘기는 방식을 본다. |
| 완료 기준 | 실험 ⑥이 빌드 단계에서 실패한다. |
| 검증 방법 | `tests/unit/build-environment-bundle.test.ts`에 임시 outDir 옆 `.env.production.local` 케이스 추가(또는 `vite.config.ts` 함수 단위 테스트) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-03 청크 이름이 계약처럼 쓰이지만 선언돼 있지 않다 — 해시 안정성 테스트와 route 청크 매핑
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 14, 3, 8 (+30.3, 30.7) |
| 근거 | (1) `tests/unit/build-environment-bundle.test.ts:68-76`은 이름이 `design-system-`으로 시작하는 청크가 정확히 1개이고 두 빌드에서 같기를 기대한다. 이 이름은 rolldown이 자동으로 붙인다. 실험 ②: route 페이지에 청크 이름을 붙이는 `manualChunks`(tech-log 방식) → build id만 바뀐 두 빌드에서 route 청크는 모두 같았다(성질 유지). 그러나 `design-system` 청크가 사라져(`route-auth-example-page`에 합쳐짐) 테스트가 "expected [] to have a length of 1"로 실패했다. 실험 ③: `not-found-page.tsx`가 `getBuildConfig().buildId`를 읽게 하자 `not-found-page` 청크 해시가 빌드마다 바뀌었다(성질 위반). 테스트는 통과했다. (2) `scripts/generate-build-manifest.ts:61-72`는 Vite manifest의 `entry.name === runtime.moduleId`로 route 청크를 찾는다. `name`은 청크 이름이다. 실험 ②에서 build가 "Missing built route chunk: APP_HOME"로 exit 1. 청크 이름이 moduleId와 같아야 한다는 규약은 문서·주석에 없다(grep). (3) 제품 기록: tech-log는 테스트를 자기 청크(`render-boot-failure-*`)로 바꿨고 여전히 실패한다(기록 470행, 509행). tech-log `vite.config.ts:59-60` 주석은 표를 빠뜨리면 "Missing built route chunk"로 멈춘다고 적는다. |
| 발생 조건 | 다운스트림이 `manualChunks`·페이지 파일명·import 그래프를 바꿀 때 |
| 영향 | 올바른 변경인데 `test:unit`(필수 게이트)이 빨갛다. 반대로 route 청크가 release마다 바뀌는 회귀는 통과한다. 빌드 실패 메시지가 원인을 말하지 않는다. tech-log는 현재 원인을 고치지 못해 실패를 안고 있다. |
| 심각도·우선순위 | Medium · P2 — 정확성 피해는 없다. 청크를 조정하는 모든 다운스트림에서 게이트 비용을 반복해서 만든다. |
| 통제·증거 | 해시 안정성 M3(대리 지표) / route 매핑 M3(fail-closed, 설명 없음) · E3(실험 ①②③) + 제품 기록 |
| 확실성과 남은 가정 | 두 방향의 변이로 확인했다. tech-log 트리를 직접 빌드하지는 않았다(의존성이 달라 템플릿 `node_modules`로 빌드할 수 없음). |
| 결정의 근거 | 4.2절. 확인한 사실: 템플릿 그래프에서는 성질이 지켜진다. 기록된 의도: `src/bootstrap/main.tsx:10-12`. 추론: 검사 대상을 이름에서 성질로 바꾸면 유지비가 준다. |
| 이해 비용 | 청크 설정을 바꾸는 제품 작성자가 rolldown 자동 명명 규칙과 두 소비자를 알아내야 한다. |
| 최소 개선 방향 | (1) 테스트: 두 빌드의 Vite manifest에서 `isDynamicEntry` route 청크와 그 정적 import 폐포의 파일명이 같은지 본다. 이름 가정을 없앤다. (2) `generate-build-manifest.ts`: route 청크를 청크 이름이 아니라 manifest의 소스 경로(키 또는 `src`)로 찾는다. 안 되면 오류 메시지에 "청크 이름이 moduleId와 같아야 한다"를 적는다. |
| 대안 비교 | 이름을 설정 상수로 선언하는 방법도 있다. 여전히 rolldown 자동 명명에 기대므로 소스 경로 매칭보다 약하다. |
| 단순화의 보존 조건 | 템플릿 기본 그래프에서 route·design-system 청크가 build id에 따라 바뀌지 않는다는 현재 성질 |
| 비용·부작용 | 작다. 테스트 1개와 매칭 함수 1개 |
| 재검토 조건 | Vite/rolldown이 manifest 형식(`name`, `src`, `isDynamicEntry`)을 바꾸면 다시 본다. |
| 완료 기준 | 실험 ②에서 테스트·빌드가 통과하고, 실험 ③에서 테스트가 실패한다. |
| 검증 방법 | 위 두 변이를 fixture로 테스트에 넣는다. |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-04 운영 CSP를 넓히는 경로에 안내와 내용 검사가 없고, 같은 문자열을 4곳에서 고쳐야 한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 15, 21, 9, 20 (+30.2) |
| 근거 | `config/hosting/security-headers.json:4`는 `style-src 'self'`, `font-src 'self'`다. 넓히는 법은 `docs/architecture/optional-adapter-recipes.md:157-165`에 realtime `wss:`, `blob:`, 이미지 CDN만 있다. 외부 폰트·스타일 안내는 없다(docs grep `font-src|style-src` 0건). CSP 내용을 검사하는 코드가 없다: `scripts/check-browser-security.ts`는 lint fixture와 source map만 본다. `unsafe-inline`·`unsafe-eval`을 찾는 검사는 repo에 없다(grep: `src/contracts/zod.ts:6` 주석뿐). `verify-hosting-headers`는 선언과 응답이 문자열로 같은지만 본다. 선언 CSP는 `config/hosting/response-headers.fixture.json`에 3번 더 복사돼 있다. 실험 ⑧: 선언에 CDN을 더하자 fixture 모드가 `FAIL`(index·runtimeConfig·releaseManifest의 `content-security-policy`)이 됐다. 이 파일을 고치라는 문서는 없다(grep). 제품 기록: memento는 `production-csp.spec.ts`에서 Pretendard CDN 폰트가 막혔고 "CSP를 넓힐지 자체 호스팅할지"를 제품 결정으로 남겼다(memento 기록 326행, 334행). tech-log는 `@fontsource`·`pretendard` 패키지로 자체 호스팅해 부딪히지 않았다. |
| 발생 조건 | 제품이 외부 폰트·스타일·다른 origin 리소스를 쓰려고 CSP를 바꿀 때 |
| 영향 | e2e가 막힘을 알려 주지만 해결 방법은 제품이 찾아야 한다. 넓힐 때 `'unsafe-inline'`이나 `https:` 같은 넓은 값을 넣어도 모든 게이트가 통과한다. 로컬 fixture 검사는 사본 3개를 맞출 때까지 실패한다. |
| 심각도·우선순위 | Low · P2 — 기본값은 안전하고 e2e가 차단을 잡는다. 제품마다 같은 조사를 반복하고, 넓히는 순간 보호 장치가 없다. |
| 통제·증거 | 기본 CSP 강도 M3(e2e, 코드 확인) / 확장 안내 M1(일부) / 내용 검사 M0 · E3(실험 ⑧) + 제품 기록. e2e는 이번에 실행하지 않았다. |
| 확실성과 남은 가정 | 브라우저에서 CDN 폰트 차단을 직접 재현하지 않았다(memento 기록에 의존). |
| 결정의 근거 | 4.3절 |
| 이해 비용 | CSP를 바꾸는 사람이 선언 파일, fixture 3곳, e2e 방문 화면, 문서 9단계를 스스로 찾아야 한다. |
| 최소 개선 방향 | (1) `browser-boundary.md`에 "외부 폰트·스타일: 자체 호스팅 권장, 불가하면 `style-src`·`font-src`에 정확한 origin"을 적는다. (2) `check:browser-security`가 `security-headers.json`을 읽어 `'unsafe-inline'`, `'unsafe-eval'`, `*`, `script-src`의 scheme-only 값을 거절한다. (3) fixture가 CSP를 복사하지 않고 선언 파일에서 읽게 한다. |
| 대안 비교 | 4.3절 (b)와 (c) |
| 단순화의 보존 조건 | fixture 모드가 `UNVERIFIED`로 끝나는 동작(13-05 수정) 유지 |
| 비용·부작용 | 작다. 금지 목록 예외가 필요한 제품은 명시적 예외를 둬야 한다. |
| 재검토 조건 | 호스팅 provider adapter가 들어오면 CSP 생성기를 검토한다. |
| 완료 기준 | 선언에 `'unsafe-inline'`을 넣으면 `check:browser-security`가 실패한다. CDN을 더할 때 선언 파일 한 곳만 고치면 된다. |
| 검증 방법 | 금지 값 fixture 1개, fixture 모드 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-05 SBOM이 `pnpm list`의 `deduped` 노드를 따라가지 않아 번들되는 전이 의존성을 development로 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 16, 24 |
| 근거 | `scripts/lib/supply-chain.ts:195-267`의 `visit`는 각 노드의 `dependencies`만 따라간다. 실험 ⑮: `pnpm list --json --depth Infinity`에서 production 루트의 `react-dom`은 `deduped: true`이고 자식이 없다. 하위 트리는 dev 경로(`@storybook/react-vite → … → @storybook/react-dom-shim → react-dom`)에만 출력된다. 그래서 `scheduler@0.27.0`이 `ca:scope: development`로 기록된다(`artifacts/release/sbom.cdx.json`, `config/security/dependency-baseline.json:5761-5768`). deduped 노드를 풀어 계산한 production 폐포는 11개, SBOM production은 10개이고 차이는 `scheduler`뿐이다. `react-dom` 클라이언트가 scheduler를 번들에 포함한다. FOLLOW-UP은 이를 F-11 "분류와 기준선 재승인"(사용자 몫)으로 넘겼다. 원인은 코드다. |
| 발생 조건 | production 패키지의 전이 의존성이 dev 경로에서 먼저 출력될 때. 제품이 의존성을 늘리면 늘어날 수 있다. |
| 영향 | SBOM·기준선이 배포물에 든 패키지를 개발용으로 적는다. 취약점 분류·감사에서 우선순위를 낮출 수 있다. 코드 수정 없이 기준선을 재승인하면 틀린 분류를 승인하게 된다. |
| 심각도·우선순위 | Low · P2 — 현재 1개. F-11 재승인 전에 고쳐야 재승인이 의미를 가진다. |
| 통제·증거 | M2(분류 구현, deduped 누락) · E3 |
| 확실성과 남은 가정 | pnpm 11.17.0 출력으로 확인했다. |
| 결정의 근거 | 적용 제외 — 입력 형식을 덜 처리한 구현 결함이다. |
| 이해 비용 | 분류가 틀린 이유를 찾으려면 pnpm JSON 형식을 알아야 한다. |
| 최소 개선 방향 | 먼저 모든 비-deduped 노드에서 `name@version → 자식` 표를 만들고, 그 표로 production 루트부터 폐포를 계산한다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 작다. 기준선 digest가 바뀌므로 재승인이 한 번 필요하다(F-11과 합친다). |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | SBOM에서 `scheduler@0.27.0`이 production이다. |
| 검증 방법 | deduped production 노드를 가진 fixture로 `tests/unit/supply-chain.test.ts`에 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-06 하위 경로 배포에서 base를 따르지 않는 소비자 두 곳이 남았다(13-07 잔여)
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23, 19, 18 |
| 근거 | 앱은 기본 설정 URL을 `${routerBasePath}config.json`으로 만든다(`src/contracts/env.ts:143-144`). SW 빌드는 `process.env.VITE_RUNTIME_CONFIG_URL ?? "/config.json"`이다(`vite.service-worker.config.ts:94-96`). 실험 ⑤: `/app/` 빌드의 `service-worker.js`에 `runtimeConfigUrl:"/config.json"`. 앱은 `/app/config.json`을 요청한다. 현재 `classifyFetch`(`src/adapters/service-worker/service-worker-static-assets.ts:45-58`)에서 이 요청은 `NETWORK_PASSTHROUGH`가 되어 가로채지 않으므로 동작 차이는 없다(코드 읽기). 호스팅 live probe는 `/`, `/config.json`, `/release-manifest.json`을 루트 절대 경로로 요청한다(`scripts/verify-hosting-headers.ts:120-122`). `HOSTING_BASE_URL=https://host/app/`이어도 `https://host/config.json`을 본다. |
| 발생 조건 | 하위 경로 배포 |
| 영향 | SW: 분류 규칙이 바뀌면(예: 설정 요청을 명시적으로 막는 규칙) 조용히 틀린다. probe: 하위 경로 배포에서 FE-GATE-019가 404로 실패하거나, 같은 호스트 루트의 다른 앱 헤더를 보고 통과한다. |
| 심각도·우선순위 | Low · P3 — 하위 경로 배포에서만, 현재 SW 동작 차이 없음 |
| 통제·증거 | M2(앱·설정) / M0(SW·probe) · E3(SW) + E1(probe) |
| 확실성과 남은 가정 | probe는 실제 호스트 없이 코드로만 확인했다. |
| 결정의 근거 | 적용 제외 — 같은 기본값을 두 곳에서 다르게 계산한 복사본이다. |
| 이해 비용 | 작다. |
| 최소 개선 방향 | SW 설정이 `getBuildConfig(process.env).runtimeConfigUrl`을 쓴다. probe는 경로를 `HOSTING_BASE_URL` 기준 상대 경로(`config.json`)로 요청한다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 작다. |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `/app/` 빌드의 SW에 `/app/config.json`이 들어간다. probe가 `HOSTING_BASE_URL` 아래 경로를 요청한다. |
| 검증 방법 | `tests/unit/sub-path-deployment.test.ts`에 SW 입력·probe URL 케이스 추가 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-07 청크 설정이 Vite 8의 폐기 예정 별칭(`build.rollupOptions`)에 있어, `rolldownOptions`를 더하면 조용히 무시된다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 16, 23, 9 |
| 근거 | 템플릿은 `vite.config.ts:72-80`에서 `build.rollupOptions.output.manualChunks`로 preload helper를 분리한다. Vite 8.1.5는 `build.rolldownOptions ??= build.rollupOptions`로 처리한다(`node_modules/.pnpm/vite@8.1.5…/dist/node/chunks/node.js:2753`). 사용자 설정에 두 키가 모두 있으면 경고 없이 `rolldownOptions`만 쓴다(경고는 plugin과 `optimizeDeps` 경로에만 있다: `:2754`, `:36209`). 실험 ⑬: `build.rolldownOptions: { output: { minify: true } }`만 더하자 `preload-helper` 청크가 사라졌다(0개). 이러면 09-03이 막은 문제(entry가 helper를 품어 모든 lazy 청크가 매 빌드 바뀜)가 돌아온다. tech-log는 이를 알아채고 두 설정을 `rolldownOptions` 하나로 합쳤다(tech-log `vite.config.ts:134-147`, 기록 224-227행). |
| 발생 조건 | 제품이 Vite 8 문서대로 `rolldownOptions`에 자기 설정을 더할 때 |
| 영향 | 템플릿 청크 정책이 경고 없이 꺼진다. 13-03의 테스트가 이 경우는 실패로 잡을 가능성이 높지만(성질 위반), 원인 설명은 없다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E3 |
| 확실성과 남은 가정 | 경고가 없는 것은 `--logLevel warn`으로 확인했다. |
| 결정의 근거 | 적용 제외 — 키 이름 이전이다. |
| 이해 비용 | 작다. |
| 최소 개선 방향 | `rollupOptions`를 `rolldownOptions`로 바꾼다. `vite.service-worker.config.ts:74`도 같이 바꾼다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | preload helper 분리 동작 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 두 설정 파일에 `rollupOptions`가 없다. |
| 검증 방법 | 빌드 후 `preload-helper-*.js` 존재 확인(기존 번들 테스트) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-08 pnpm 설치 정책이 파일에만 있고, 되돌림과 암묵 기본값을 잡는 검사가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 16, 21, 26 |
| 근거 | `pnpm-workspace.yaml:1-18`에 `engineStrict`, `saveExact`, `allowBuilds`, `minimumReleaseAgeExclude`가 있다. 이 값을 확인하는 스크립트·테스트는 없다(grep: `allowBuilds`는 `scripts/lib/package-script-graph.ts` 주석뿐). `minimumReleaseAge`는 파일에 없고 pnpm 11 기본값(1440분)에 기댄다. `pnpm config get minimum-release-age` → `undefined`. pnpm 11 공식 릴리스 노트에 따르면 기본 `minimumReleaseAgeStrict`는 `false`이고, 이 모드에서 pnpm은 조건을 못 맞추면 `minimumReleaseAgeExclude`에 항목을 자동으로 더한다(pnpm 11.0·11.4 릴리스 노트, E0). 템플릿 주석(`:9-13`)은 예외마다 owner와 재검토 조건을 요구하지만, 자동 추가된 항목에는 그런 기록이 없다. |
| 발생 조건 | 누군가 설정을 지우거나, 개발자가 `pnpm add`·`update`로 하루 안 된 버전을 받을 때 |
| 영향 | 13-09에서 고친 설정이 다시 사라져도 모른다. 공개 경과 기간 보호가 리뷰 없이 우회될 수 있다. CI는 `--frozen-lockfile`이라 설치 시점 영향은 로컬에 한정된다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M2(설정) / 검출 M0 · E3(`engineStrict` 동작, 실험 ⑭) + E0(pnpm 문서, 자동 추가 동작은 실행 확인 못 함) |
| 확실성과 남은 가정 | 자동 추가 동작은 새 패키지 공개가 필요해 재현하지 않았다. |
| 결정의 근거 | 적용 제외 — 설정 고정과 회귀 검사 누락이다. |
| 이해 비용 | 작다. |
| 최소 개선 방향 | `minimumReleaseAge: 1440`, `minimumReleaseAgeStrict: true`를 명시한다. `check:ci` 또는 단위 테스트 하나가 이 키들과 `engineStrict`·`saveExact`의 존재, 예외 항목이 정확한 버전 형식인지를 확인한다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | strict 모드에서는 새 버전 설치 시 확인 절차가 한 번 더 생긴다. |
| 재검토 조건 | pnpm 메이저 버전이 바뀔 때 |
| 완료 기준 | 키를 하나 지우면 검사가 실패한다. |
| 검증 방법 | 단위 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-09 README 변수 표가 staging·production의 `VITE_BUILD_ID` 필수 조건을 적지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 19 |
| 근거 | `README.md:46`은 기본값을 `local-build`로만 적는다. 코드는 staging·production에서 값이 없으면 실패한다(`scripts/generate-runtime-config.ts:70-72`, 실험 ⑪). `.env.example:13-15`도 "developer build falls back"만 적는다. `verify:documentation`은 변수 이름만 대조한다. |
| 발생 조건 | README만 보고 staging 빌드를 할 때 |
| 영향 | 빌드가 명확한 오류로 멈춘다. 피해는 시간뿐이다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 |
| 확실성과 남은 가정 | 정적 확인 |
| 결정의 근거 | 적용 제외 — 문서 누락 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 표의 기본값 칸에 "local·development만. staging·production은 필수"를 적는다. |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | README 표가 코드 조건과 같다. |
| 검증 방법 | 문서 검토 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 13-10 "선택 기능을 켜야 재현되는 템플릿 결함"의 책임이 정해져 있지 않다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 26 (+30.4) |
| 근거 | `README.md:348-353`: "수정하지 않은 `.template-origin` 체크아웃에서 재현되면 템플릿 결함, 제품 변경이 있어야 재현되면 제품 몫". 이번 동기화에서 두 제품이 올린 템플릿 문제는 둘 다 "지원하는 선택·설정을 바꿔야 재현"된다: memento의 SW `publicDir`(13-01, SW `ACTIVE` 선택 필요), tech-log의 번들 테스트(13-03, 청크 설정 변경 필요). 규칙을 글자대로 적용하면 둘 다 제품 몫이 된다. 두 건은 제품 문서에만 있고 템플릿 저장소 이슈에는 없다(Gitea API 읽기, 2026-09-29 기준 이슈·PR 3건, 모두 무관). 동기화가 같은 날이라 보고 지연일 수 있다. |
| 발생 조건 | 제품이 선택 기능·지원 설정에서 템플릿 결함을 만날 때 |
| 영향 | 제품마다 같은 결함을 따로 고친다(memento는 이미 고쳤고 tech-log는 SW를 켜면 같은 일을 겪는다). 템플릿의 잠재 결함이 남는다. |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M1 · E1 + 제품 기록 |
| 확실성과 남은 가정 | 제품이 앞으로 보고할지는 모른다. |
| 결정의 근거 | 규칙을 넓히면 템플릿이 모든 선택 조합을 책임지는 것처럼 보일 수 있다. 30.2절처럼 "기본 지원·선택 지원·실험·비지원" 중 선택 지원 기능은 템플릿 책임에 넣는 것이 가장 작은 변경이다(리뷰어 추론). |
| 이해 비용 | 작다 |
| 최소 개선 방향 | README 결함 절에 "수정하지 않은 체크아웃에서 **문서화된 선택 기능·설정만 바꿔** 재현되면 템플릿 결함"을 한 줄 더한다. |
| 대안 비교 | 현상 유지: 제품 기록에만 남고 템플릿에 모이지 않는다. |
| 단순화의 보존 조건 | 제품 고유 변경은 제품 책임으로 남긴다. |
| 비용·부작용 | 템플릿 유지보수 요청이 늘 수 있다. |
| 재검토 조건 | 제품이 3개 이상으로 늘거나 선택 기능 수가 늘면 선택 기능별 지원 상태 표를 둔다. |
| 완료 기준 | README 규칙이 선택 기능 재현을 명시한다. |
| 검증 방법 | 문서 검토 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| P1 초기 JS 예산 여유 약 1.3KB | **유효** | 실험 ⑨: 203,481 / 204,800(여유 1,319 B). `config/scale/feature-shape-growth.json` 기준 기능 모양 1개 ≈ +2,980 B. 다음 기능 하나가 게이트를 넘는다. 두 제품은 이번 동기화에서 `check:bundle`을 기록하지 않았다. |
| P2 레시피 번들 예산 인상 | **유효** | 실험 ⑨: file-transfer 55,623/55,700(여유 77), offline-indexeddb 36,891/36,900(여유 9), realtime 40,886/40,900(여유 14) |
| P2 13-03 운영 단계는 archive SHA만 대조 | **유효** | production_gate는 `verify-ci-candidate-archive.ts`(SHA·추출)만 한다(`.gitea/workflows/quality-gates.yml:404-405`). `--archived` 재검증은 workflow에 없고 runbook 수동 절차다(`docs/operations/release-cache-rollback.md:30`). |
| P3 06-10 SW 설정의 `dist/config.json` 읽기에 단위 테스트 없음 | **유효** | 테스트는 여전히 없다. 같은 두 번째 단계가 그 파일을 다시 덮어쓰는 결함이 있다(13-01). |
| P3 fixture pnpm 설치 검사 끔(F-4, F-12) | **유효** | `scripts/lib/fixture-node-modules.ts:41` `pnpm_config_verify_deps_before_run: "false"`. 영역 10·11과 겹친다. |
| F-11 SBOM `scheduler@0.27.0` 분류(사용자 몫) | **유효, 원인 재분류** | 여전히 development. 원인은 분류 코드다(13-05). 코드 수정 뒤 재승인해야 한다. |
| P2 `check:remediation-ledger` | 판단 불가 | 영역 12 소관. 오케스트레이터 게이트 결과에서 알려진 실패로 유지됨 |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| `production-csp.spec.ts`와 외부 폰트 차단 | Playwright를 돌리지 않았다. 다른 에이전트와 포트 4173이 겹칠 수 있다. | 포트를 바꾼 설정으로 chromium 실행, CSS에 외부 `@import`를 넣은 변이 |
| SW `ACTIVE` production 산출물의 실제 부팅 실패 | 브라우저 부팅 안 함(산출물만 확인) | SW e2e 도우미를 `APP_PROFILE=staging`으로 확장 |
| `.env*` 입력 산출물의 `CONFIG_BUILD_MISMATCH` | 코드 읽기만 | 실험 ⑥ dist를 preview로 띄워 부팅 |
| 실제 호스팅·CDN 헤더, 하위 경로 live probe | provider 미정 | 정적 서버에 `/app/`으로 배포 후 `HOSTING_BASE_URL` 지정 |
| Gitea workflow 실행(FE-GATE-027, production_gate) | U-1(Actions 꺼짐) | runner와 repo 변수 |
| 외부 vulnerability·provenance provider, `--archived` 실제 서명 번들 | provider 키 없음 | staging smoke(U-4) |
| pnpm `minimumReleaseAgeStrict: false`의 자동 예외 추가 | 새 패키지 공개가 필요 | 사설 registry에서 방금 공개한 버전 설치 |
| tech-log 트리에서 13-03 성질 측정 | 제품 의존성이 템플릿 `node_modules`와 달라 빌드 불가, 제품 `node_modules`에 쓰기 금지 | 제품 repo에서 직접 두 번 빌드 |
| 여러 runner 사이 빌드 재현성 | 단일 호스트 | 다른 runner 이미지에서 digest 비교 |
@@ -0,0 +1,328 @@
# 14 — 템플릿 제품성·문서·DX·업데이트 전파
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6`(태그 `v0.2.0` = `f753669` + docs 커밋 1개) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(워킹트리 판)
> 영역 판정(35.8): **조건부 사용 가능.** 복사해서 시작하는 용도와 태그 단위 동기화는 두 제품에서 실제로 동작했다(E3). 다만 동기화마다 같은 파일에서 충돌하고, 템플릿 자신의 기록을 제품이 매번 골라내며, CHANGELOG가 제품이 할 일을 일부 빠뜨린다(14-01~14-04).
## 1. 머리말 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` `af3d8e6`. 미커밋 변경은 리뷰 가이드 2개뿐이다(코드와 무관) |
| 목적·실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 소비자 | `../tech-log-frontend`(이력 비공유, 기준점 명시 3-way 병합), `../memento-frontend`(이력 공유, `git merge`). 둘 다 2026-09-29에 `ebea300` → `af3d8e6`(359커밋)을 받았다. 브랜치 `chore/template-sync-v0.2.0` |
| 읽은 것 | `README.md` 전체, `CHANGELOG.md` 전체, `docs/README.md`, `docs/architecture/starter-experience.md`, `docs/operations/ci-quality-gates.md` 1~75행, `docs/contracts/compatibility.md` 앞부분, `docs/architecture/optional-adapter-recipes.md` 3절 끝, `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md` 0~2절, `scripts/test-sample-removal.ts` 전체, `scripts/lib/removal-fixture.ts` 1~240행, `scripts/verify-extreme-scale.ts`·`scripts/scale/run-scale-profile.ts`의 기록 부분, `tests/unit/deletable-history-documents.test.ts`, `.gitignore`, `recipes/frontend-capabilities/index.ts`, `CLAUDE.md`, `SPEC.md`·`tasks/` 목록. 두 제품의 `docs/operations/template-sync-2026-09-29.md` 전체, tech-log `template-sync-2026-09-21.md` 목차와 충돌 절, 두 제품의 `.gitignore`·`config/runtime/*.json`·기준점 파일 |
| 실행한 것 | ① 두 제품을 scratchpad에 `git clone --no-checkout`하고 템플릿 `main`을 fetch했다(제품 repo 자체는 읽기만 함). ② 충돌 재현: `git merge-tree --write-tree --merge-base=ebea300 --name-only 8210d48 af3d8e6`(tech-log) → 67경로, `git merge-tree --write-tree --name-only 42eaf45 af3d8e6`(memento) → 25경로, `git merge-tree --write-tree --merge-base=5434760 --name-only afde2b1^ ebea300`(tech-log 09-21) → 23경로. ③ 템플릿 변경 분류: `git diff --numstat ebea300 af3d8e6`. ④ worktree(`af3d8e6`)에서 `node scripts/generate-product-feature-index.ts` 후 `node scripts/scale/run-scale-profile.ts pr`(= `check:scale:pr`, FE-GATE-005가 돌림) → PASS, 뒤이어 `git status --short`. worktree는 지웠다. ⑤ `git grep`으로 로그·기록 파일을 읽는 코드 탐색. ⑥ Gitea API 읽기: 템플릿 repo 설정, 이슈 목록, 태그 |
| 확인하지 못한 것 | 깨끗한 환경에서 템플릿 자체의 `install --frozen-lockfile` → `dev`(공유 node_modules 보호). 제품의 운영 CORS 설정 값(배포 변수라 repo에 없음). Playwright 계열. 나머지 제거 스크립트 3개(`test:optional-recipe-removal` 등)의 이번 커밋 실행 |
| 이전 리뷰와 비교 | 2026-09-25 14영역 발견 8건은 모두 닫혔다(11절). 이번 라운드의 새 증거는 두 제품의 실제 동기화다. 지난 결과는 증거로 쓰지 않았다 |
## 2. 대표 흐름
### 2.1 정상 흐름 — 문서만 보고 기능 하나를 설치한다
```text
feature-module.ts / context-routes.ts / context-module.ts 작성
-> 생성기 규칙 검사 (리터럴 export, 소속 context, 예산)
-> src/.generated/ 재생성, installed-* 가 인덱스를 투영
-> 라우터가 context 경계로 lazy mount
```
- 입력: `docs/architecture/starter-experience.md:112-147` "Adding a feature".
- 정책: `scripts/generate-product-feature-index.ts`. 선언이 없거나 예산을 넘으면 파일 이름을 대며 실패한다(`starter-experience.md:99-110`).
- 상태 변화: `src/.generated/`(git-ignored). 중앙 catalog는 고치지 않는다(`starter-experience.md:145-147`).
- 외부 I/O: 없음.
- 실패: 선언 누락·예산 초과·모르는 `VITE_PRODUCT_FEATURES`에서 첫 빌드 단계가 멈춘다.
- 결과(E3): memento가 이 절차로 `memento-web`을 설치했다(memento `template-sync-2026-09-29.md:168-186`). 단, 제품이 `/`와 셸을 가지는 부분은 이 절차 밖이라 템플릿 파일 두 곳에 다리를 놓았다(14-03).
### 2.2 피해가 큰 흐름 — 템플릿의 [계약] 변경이 제품 운영까지 전파된다
```text
템플릿 커밋 -> CHANGELOG [계약] 행 -> 제품 동기화 -> 제품·백엔드·배포 조치 -> 배포
```
- `x-correlation-id`: 모든 V3 실행이 헤더를 붙인다(`src/adapters/http/http-execution-v3.ts:817-826`). 다른 origin API는 GET도 preflight 대상이 된다. 행은 `CHANGELOG.md:24`에 있다.
- 실패: 백엔드 CORS가 헤더를 허용하지 않으면 V3 요청이 preflight에서 거절된다.
- 결과(E3): 두 제품의 `API_BASE_URL`은 앱과 다른 origin이다(`config/runtime/*.json`). 그런데 두 동기화 기록 어디에도 이 행의 조치나 질문이 없다. 같은 방식으로 전달된 `readSubject` 필수화(`CHANGELOG.md:43` → `starter-experience.md:54-76`)는 tech-log가 찾아서 고쳤다(tech-log 기록 316-328행). 차이는 14-04에서 다룬다.
### 2.3 변경·삭제 흐름 — 태그까지 따라잡고, 템플릿 기록을 빼고, 샘플 삭제를 판단한다
```text
새 태그 -> (문서) cherry-pick 1건 / (실제) 359커밋 범위 병합
-> 충돌 67 / 25 -> 파생 기준선 재계산 -> 템플릿 기록 삭제 -> 게이트 기준선과 비교
-> 실패 시 backup ref 로 되돌림
```
- 정책: `README.md:315-353`. 실제로 쓴 절차는 README에 없다(14-02).
- 상태 변화: tech-log는 템플릿 경로 127개를, memento는 70개를 가져오지 않았다. 둘 다 작업 기록을 따로 조사해 골라냈다(14-01).
- 샘플: `README.md:205-209`는 샘플 삭제를 안내한다. 두 제품 모두 지우지 않았다. tech-log는 "다음 동기화가 깨끗하게 병합되도록" `NOT_INSTALLED`로만 뒀다(tech-log 기록 122-125행). 삭제의 동기화 비용은 템플릿의 이력 문서에만 적혀 있다(14-03).
- 되돌림: 두 제품 모두 `backup/main-before-template-af3d8e6`를 먼저 만들었다. README는 이 단계를 안내하지 않는다.
## 3. 28개 관점 판정표 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
| 번호 | 관점 | 판정 | 통제·증거 | 근거와 잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | > | - | 01~13 영역 |
| 2 | 구조적 성숙도 | > | - | 09, 12 영역 |
| 3 | 변경 용이성 | P | M1 · E3 | 동기화 변경 비용: 8개 경로가 세 번 연속 충돌했다(34절 표, 14-03). 기능 추가 경로 자체는 E3로 동작 |
| 4 | 인지 부하 | P | M1 · E1 | `docs/README.md`가 현재 계약·목표 설계·이력을 나눈다. 문서는 136개 약 69.7k줄로 늘었다. 동기화에 필요한 지식(파생 기준선 재계산, 제외 목록)은 템플릿 문서 밖에 있다(14-02) |
| 5 | 위험 가시성 | > | - | 코드 수준은 다른 영역. 소비자에게 위험을 알리는 CHANGELOG는 17·26에서 본다 |
| 6 | 실패 성숙도 | > | - | 다른 영역 |
| 7 | 운영 성숙도 | > | - | 11, 13 영역 |
| 8 | 디버깅 가능성 | O | M3 · E1 | 제거 JUnit이 실패 수와 검사별 원인을 쓴다(`scripts/lib/removal-fixture.ts:218-236`). 지난 14-08 해소 |
| 9 | 유지보수 성숙도 | P | M1 · E3 | **깊게 봄.** 태그·CHANGELOG·색인이 생겼다. "제품이 고치는 템플릿 파일은 영구 충돌 지점"이라는 판단이 지워도 되는 이력 문서에만 있다(`docs/superpowers/specs/2026-09-20-memento-…:35,37,56`, 14-03). 현재 계약 문서에 코드와 다른 문장이 있다(`ci-quality-gates.md:69`, 14-05). `docs/README.md:72`의 "라운드가 쓰는 중" 사유는 만료됐다(14-01) |
| 10 | 테스트 성숙도 | P | M3 · E2(오케스트레이터) | 샘플 제거 13개 검사 PASS. lint·`check:i18n`·e2e는 검사하지 않는다(`scripts/test-sample-removal.ts:413-428`, FOLLOW-UP 09-07). 지울 수 있는 기록 검사는 `artifacts/`를 보지 않는다(`tests/unit/deletable-history-documents.test.ts:25-31`) |
| 11 | 데이터 성숙도 | - | - | 이 영역에 데이터 경계가 없다 |
| 12 | 동시성 성숙도 | - | - | 이 영역에 동시 실행 경로가 없다 |
| 13 | 확장성 | > | - | 11 영역 |
| 14 | 성능 성숙도 | > | - | 13 영역 |
| 15 | 보안 성숙도 | > | - | 다른 영역. CHANGELOG의 [보안] 행은 경로·커밋이 붙어 있다 |
| 16 | 의존성 성숙도 | P | M2 · E3 | 제품 입장에서 템플릿은 의존성이다. 태그 `v0.2.0`이 원격에도 있다(Gitea API tags → `f753669`). 기준점 기록 형식이 두 제품에서 다르다(14-02) |
| 17 | API / Contract 성숙도 | P | M1 · E3 | 템플릿→제품 계약 채널은 CHANGELOG [계약]이다. 게이트를 좁힌 변경 5종이 [계약] 표시 없이 들어가 제품 게이트를 깨뜨렸다. 저장소 밖 조치에 담당·확인이 없다(14-04). 공개 포트를 필수로 바꾸는 단계 정책이 없다(FOLLOW-UP 2절) |
| 18 | 배포 성숙도 | > | - | 13 영역 |
| 19 | 설정 성숙도 | P | M3 · E1 | README 변수 표는 `verify:documentation`이 검사한다(`README.md:50-51`). 기준선 표의 `FEATURE_OVERRIDES` 설명이 코드와 다르다(14-05) |
| 20 | 개발자 경험 | P | M1~M3 · E3 | **깊게 봄.** 과제 1·3·4는 문서로 가능하다(4는 memento E3). 과제 5 샘플 제거는 스크립트의 편집 약 12종을 손으로 따라 해야 하고 동기화 비용 설명이 없다. 과제 6 문제 해결 문서는 없다. "업데이트" 과제는 README 절차와 실제가 다르다(14-02) |
| 21 | Guardrail 성숙도 | P | M3(목록 안) / M0(목록 밖) · E3 | 지울 기록 5종은 읽는 코드가 없음을 테스트가 막는다. 추적 중인 실행 로그 63개는 README의 "생성 증거는 무시된다"(`README.md:309-310`)와 달리 추적되고, merge 게이트가 다시 쓴다(14-01, 실험) |
| 22 | 추상화 성숙도 | > | - | 09 영역 |
| 23 | 일관성 | P | M1 · E3 | 두 제품이 기준점 형식(`.template-origin` / `template.lock.json`), CHANGELOG·`docs/reviews` 처리에서 서로 다르게 판단했다. 템플릿이 정하지 않았기 때문이다(14-01, 14-02) |
| 24 | 네이밍 / 의미 성숙도 | P | M1 · E3 | `NOT_INSTALLED`는 "빌드에 없음"이다(`README.md:117`). tech-log는 생성기 밖에서 조립하는 자기 도메인 기능에 이 표식을 붙였다(`src/features/tech-log/NOT_INSTALLED`). 생성기에 "직접 조립" 상태가 없어서다. 표식 설계는 09 영역으로 넘긴다 |
| 25 | 조직 확장성 | P | M1 · E3 | 소비자 2개가 같은 템플릿 파일 17개에서 충돌했다. 소비자가 늘면 같은 비용이 곱해진다(14-03) |
| 26 | Ownership 성숙도 | P | M1 · E3 | **깊게 봄.** 결함 분류 규칙(`README.md:348-353`)은 tech-log가 실제로 썼다(수정 없는 `af3d8e6` export에서 재현, tech-log 기록 473행). 하지만 템플릿 이슈는 0건이고, 제품이 찾은 템플릿 결함 후보가 템플릿에 돌아오지 않는다(14-06). CHANGELOG에 조치 담당 칸이 없다(14-04) |
| 27 | 삭제 가능성 | P | M3 · E2(템플릿) / E3(제품) | **깊게 봄.** 템플릿의 샘플 제거 게이트는 통과한다. 제품은 삭제 대신 유지를 골랐다. 삭제한 파일이 동기화마다 충돌하기 때문이다(tech-log 09-29의 삭제 관련 충돌 18개(수정/삭제 17, 이름변경/삭제 1)가 모두 제품이 지운 샘플·예시 화면). README는 이 비용을 적지 않는다(14-03). 두 제품의 FE-GATE-020은 제품 사정으로 red다(tech-log registry 결함, memento 커버리지) |
| 28 | 회복 가능성 | > | - | 다른 영역. 동기화 되돌림은 30.4에서 본다 |
### 3.1 30절 템플릿 기준 판정
| 절 | 판정 | 근거 |
|---|---|---|
| 30.1 최소 구성과 안전한 기본값 | P | `public/config.json`은 demo 인증·텔레메트리 꺼짐이다. demo는 local/development 밖에서 파싱 단계에서 거절된다(`src/contracts/release-artifacts.ts:103-107`). staging·production 승인은 external 인증을 요구한다(`src/contracts/deployment-admission.ts:77-80`). 템플릿 자체의 깨끗한 환경 실행은 이번에 확인하지 못했다. memento는 파생 트리에서 `install --frozen-lockfile`을 깨끗한 worktree로 실행했다(memento 기록 37-39행) |
| 30.2 옵션 조합 | P | 기본/선택/실험/비지원 표와 상태 어휘 대응표가 있다(`README.md:94-124`). 조합의 검증 범위는 적혀 있지 않다. memento는 SW를 `ACTIVE`로 켠 첫 소비자로서 템플릿이 돌리지 않는 조합에서 결함 후보를 찾았다(memento 기록 202-207행, 14-06) |
| 30.3 생성·복사 후 수정 권한 | P | 생성 파일은 표시되고 drift가 검사된다(`.gitea/workflows/quality-gates.yml:1`, `src/.generated/`). 템플릿 자신의 기록과 복사 대상의 구분은 일부만 있다(14-01). 제품이 고치게 되는 템플릿 파일의 목록이 없다(14-03) |
| 30.4 버전과 업데이트 전파 | P | **E3.** 태그·CHANGELOG·업데이트 절·결함 분류 규칙이 있고, 두 제품이 수정 보존·충돌 설명·게이트 비교·되돌림 ref까지 갖춰 동기화했다. 문서 절차가 실제와 다르고(14-02), 같은 파일이 매번 충돌하며(14-03), CHANGELOG가 제품 조치를 일부 빠뜨린다(14-04). 측정은 34절 표 |
| 30.5 샘플 코드의 대표성 | P | 샘플은 목록·상세·폼·상태와 실패 분류를 보여 주고, 플랫폼 테스트는 테스트 전용 기능을 쓴다. 템플릿 테스트 일부가 템플릿 화면(`/`, `/examples/*`)에 묶여 있어 tech-log는 7개, memento는 9개 파일을 제품 화면으로 옮겼다(tech-log 기록 292-312행, memento 262행). 이 테스트는 다음 동기화의 충돌 후보다 |
| 30.6 도입·유지 비용 | P | package script 142개, CI 게이트 27개(명령 98개), 문서 약 69.7k줄. 동기화 비용은 34절 표: 충돌 67/25, 가져오지 않은 경로 127/70, 템플릿 때문에 새로 red가 된 게이트·테스트 5종/4종 |
| 30.7 템플릿에서 졸업할 수 있는가 | P | tech-log는 자기 도메인을 생성기 밖에서 조립하고, memento는 템플릿 파일에 다리 두 개를 두고, 둘 다 계속 동기화한다. 졸업은 가능하다. 대가는 템플릿 파일 안의 제품 코드와 그 충돌이다(14-03). 확장 지점 자체는 09 영역 |
| 30.8 배포 판단에 필요한 최소 증거 | P | "패치 전달"은 이번에 E3가 생겼다(두 소비자). "기본 패턴 복제"는 memento-web이 문서 절차로 설치됐지만 같은 소유자다(작성자 외 조건 미충족, U-4). "새 프로젝트 시작"의 깨끗한 환경 증거는 템플릿 자체로는 없다. "선택 기능 분리"는 템플릿에서 PASS, 제품에서는 제품 사정으로 red |
### 3.2 34절 측정 — 소비자 패치 적용의 수정·충돌
충돌 수는 scratchpad clone에서 `git merge-tree`로 다시 계산했다. 나머지는 각 제품 기록과 `git diff`에서 셌다.
| 측정 | tech-log 09-29 | memento 09-29 | tech-log 09-21 |
|---|---|---|---|
| 템플릿 범위 | `ebea300` → `af3d8e6`, 359커밋 | 같음 | `5434760` → `ebea300` |
| 반영 방식 | 이력 비공유. `git merge-recursive ebea300 -- HEAD template/main` | 이력 공유. `git merge --no-ff upstream/main` | 이력 비공유 |
| 기준점 기록 | `template.lock.json`(revision, tree, materialization) | `.template-origin` 한 줄 | `template.lock.json` |
| 템플릿 변경 파일 | 824 (+68,835 / −13,207) | 824 | - |
| 그중 템플릿 작업 기록 | 105 (13%, +13,681줄): `artifacts` 63, `docs/reviews` 35, `SPEC/CLAUDE/tasks` 7 | 같음 | - |
| 양쪽이 바꾼 파일 | 90 | 50 | - |
| 충돌 경로 | **67** (내용 49, 수정/삭제 17, 이름변경/삭제 1). 기록과 같음 | **25**. 기록과 같음 | 23 (기록은 19) |
| 가져오지 않은 템플릿 경로 | 127 | 병합 뒤 70개 삭제 | - |
| 동기화 뒤 템플릿 변경 824개 중 템플릿과 다른 경로 | 213 | 125 | - |
| 템플릿 때문에 새로 red | `check:request-fanout`(FE-GATE-010·005), `build-environment-bundle`, `second-api-feature-registries`, `test:sample-removal`(더 이른 단계), `check:remediation-ledger` | `check:i18n`, `production-csp` e2e, SW e2e 2개 | - |
| 되돌림 경로 | `backup/main-before-template-af3d8e6` | 같음 | `backup/main-before-template-ebea300` |
같은 경로가 반복해서 충돌했다.
- 09-29에 두 제품이 모두 충돌한 경로: 17개.
- 세 번의 동기화에서 모두 충돌한 경로: 8개. `package.json`, `README.md`, `src/bootstrap/runtime-adapters.ts`, `src/features/installed-contract-contributions.ts`, `src/features/installed-feature-adapters.ts`, `src/features/installed-feature-runtimes.tsx`, `src/presentation/pages/home-page.tsx`, `src/presentation/routes/app-router.tsx`.
측정의 한계: 두 동기화 모두 에이전트가 수행했고, 사람 작업 시간은 기록에 없다. 충돌 수는 병합 전략과 rename 탐지 설정에 따라 조금 달라진다(09-21 기록 19 vs 재현 23).
## 4. 설계 선택 설명 (41절)
### 4.1 템플릿을 "저장소 복사 + Git으로 수정 받기"로 전달한다
1. **무엇이 필요한가.** 제품이 빌드·CI·게이트·문서까지 자기 코드로 가진다. 그러면서 템플릿의 보안·계약 수정을 계속 받는다.
2. **지킬 성질.** 제품의 수정이 보존된다. 받은 수정이 어느 템플릿 버전에서 왔는지 안다. 잘못되면 되돌린다.
3. **현재 보장.** 태그(`v0.2.0`, 원격에도 있음), CHANGELOG, `README.md:315-353` 업데이트 절, 결함 분류 규칙. 두 제품이 수정 보존·충돌 기록·게이트 비교·backup ref로 동기화를 끝냈다(E3). 보장하지 않는 것: 범위 반영 절차, 제품 수정 지점 목록, 기준점 형식 통일(14-02, 14-03).
4. **대안.** (a) 현 상태. (b) 코드 생성기(`create-*` CLI와 재생성). (c) 플랫폼 커널(`src/adapters`, `src/platform`, `src/contracts`)을 패키지로 분리하고 앱 셸만 복사. (d) (a)+(c) 혼합.
5. **비교.**
- (b)는 재생성할 때 사용자 수정을 어떻게 보존할지가 새 문제가 된다. CI 계약·게이트 스크립트가 코드 모양에 묶여 있어 생성 대상의 경계를 긋기 어렵다.
- (c)는 업데이트가 버전 올리기로 끝난다. 대신 공개 API 호환 관리(semver, deprecation)가 필요하다. 두 제품이 템플릿 파일을 고친 이유는 셸·홈·조립의 확장 지점이 없어서였다. 패키지로 가면 그 수정이 아예 막힌다. 게이트 스크립트를 패키지로 옮기기도 어렵다.
- (a)는 제품이 무엇이든 고칠 수 있다. 비용은 충돌로 나타난다(67/25).
6. **현재 조건에서의 선택.** 소비자 2개, 템플릿과 제품의 소유자가 같고, 템플릿이 빠르게 바뀐다(9일에 359커밋). 이 조건에서는 (a)를 유지할 근거가 있다. 비용은 절차 문서화(14-02)와 제품 수정 지점 축소(14-03)로 줄인다.
- 기록된 의도: `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md:16,30-31`가 "upstream 추적"을 고르고 1회성 스냅샷과 동기화 스크립트 안을 기각했다. 이 문서는 지워도 되는 이력 폴더에 있다.
7. **재검토 조건.** 소비자가 늘거나 소유자가 달라질 때. 확장 지점을 만든 뒤에도 같은 파일 충돌이 줄지 않을 때. 이때 (c) 커널 패키지 분리를 다시 비교한다.
### 4.2 템플릿 자신의 작업 기록을 같은 저장소에 둔다
1. **무엇이 필요한가.** 템플릿 유지자가 리뷰·계획·실행 증거를 코드와 함께 관리한다. 이 repo의 `CLAUDE.md`는 리뷰 결과를 `docs/reviews/`에 쓰도록 요구한다.
2. **지킬 성질.** 제품이 복사·동기화할 때 템플릿의 기록을 자기 계약으로 오해하지 않는다. 게이트가 읽는 파일(`docs/reviews/adapters/INVENTORY.md` 등, `docs/README.md:40-46`)은 남는다.
3. **현재 보장.** `README.md:192-209` 목록과 `tests/unit/deletable-history-documents.test.ts`(목록 5종을 읽는 코드가 없음, M3). `docs/README.md`의 3구분. 보장하지 않는 것: 실행 로그·coverage 결과·CHANGELOG의 처리, 루트의 `SPEC.md`·`tasks/`(14-01).
4. **대안.** (A) 현 상태 + README 목록 보강. (B) 생성 로그 추적 중단 + 작업 기록을 이력 폴더 한 곳으로 모음. (C) 작업 기록을 별도 브랜치나 저장소로 옮김.
5. **비교.**
- (A)는 가장 싸다. 제품은 동기화마다 계속 골라내 지운다. 이력을 공유하는 제품은 템플릿이 그 파일을 고칠 때마다 수정/삭제 충돌을 받는다.
- (B)는 동기화 때 경로 하나만 빼면 된다. 이력 폴더를 옮기는 한 번의 비용(링크, `review-ledger.json` 같은 참조)이 든다.
- (C)는 흐름이 완전히 끊긴다. 대신 리뷰 문서와 해당 커밋을 한 저장소에서 대조하는 편의를 잃는다. 이 repo의 리뷰 절차와도 맞지 않는다.
6. **선택.** (B). 로그 추적은 `.gitignore`·README 규칙과 어긋난 한 번의 커밋(`6f6c48e`)이라 되돌리는 비용이 작다. `SPEC.md`·`tasks/`를 루트에 둔 사유(`docs/README.md:72` "라운드가 쓰는 중")는 끝났다.
7. **재검토 조건.** 템플릿을 생성기나 패키지로 배포하게 되면 복사 대상을 도구가 정하므로 다시 본다.
## 5. 발견 사항 (36.3)
### 14-01 템플릿의 실행 로그와 작업 기록이 복사·동기화 대상에 섞여 있다. 실행 로그는 merge 게이트가 다시 쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.3, 9, 20, 21, 23, 27 |
| 근거 | **실행 로그 63개가 추적된다.** `artifacts/phase5/*.log` 4, `artifacts/quality/extreme-scale-gates/*.log` 24, `artifacts/scale/{pr,main,nightly,release}/*.log` 35. 모두 `6f6c48e`(2026-09-24)에서 한 번 들어왔다. `.gitignore:11-20`은 `artifacts/`의 json·xml·txt·sarif만 무시하고 `.log`는 무시하지 않는다. `README.md:309-310`은 "generated evidence is ignored by Git"이라고 적는다. 쓰는 곳은 `scripts/scale/run-scale-profile.ts:143,153`, `scripts/verify-extreme-scale.ts:157,228`이다. 읽는 코드·테스트·설정은 없다. 참조는 이력 문서 `docs/reviews/2026-09-23-extreme-scale-acceptance.md:59` 하나다. **실험:** worktree에서 `check:scale:pr`(FE-GATE-005가 돌리는 명령, `config/ci/gates.json:217-218`)을 실행했다. PASS 뒤 `git status`에 추적 파일 3개 수정(`artifacts/scale/pr/{architecture-topology,scale-units,traffic-budgets}.log`)과 새 파일 1개(`composition-s0-s2.log`)가 생겼다. 추적 중인 `composition-s0-s1.log`는 지금 단계 이름과 맞지 않는 옛 결과다. **그 밖의 추적 산출물:** `artifacts/tests/coverage-gateway/**` 10개(커버리지 실행 결과, JS 3개 포함), `artifacts/local-preview/*.png` 3개. 둘 다 읽는 곳이 없다(`git grep`). **작업 기록:** `SPEC.md`, `tasks/`, `CLAUDE.md`는 `README.md:198-203` 목록에 있다. 하지만 루트에 그대로 있고, `docs/README.md:72`의 사유("이 라운드가 쓰는 중")는 만료됐다. 목록에 없는 것: 위 로그·coverage·preview, 그리고 제품의 CHANGELOG 경로를 차지하는 `CHANGELOG.md`. **E3:** 템플릿 변경 824개 중 105개(13%)가 작업 기록이었다(3.2절). 두 제품 모두 로그 63개와 `SPEC.md`·`tasks/`·`CLAUDE.md`를 따로 조사해서 지웠다(tech-log 기록 62-74행, memento 기록 87-102행, memento는 `git grep phase5`로 확인). CHANGELOG와 `docs/reviews`는 판단이 갈렸다(tech-log 제외, memento 유지). tech-log는 09-21 동기화에서도 coverage-gateway를 "실수로 커밋된 실행 결과"로 뺐고(09-21 기록 60행), memento는 아직 갖고 있다(memento 기록 354-355행) |
| 발생 조건 | 복사할 때, 동기화할 때마다. merge 게이트를 로컬에서 돌릴 때(`README.md:297-308`이 권장) |
| 영향 | 동기화마다 같은 조사와 삭제를 반복한다. 이력을 공유하는 제품은 템플릿이 이 파일을 다시 고칠 때 수정/삭제 충돌을 받는다. merge 게이트를 돌리면 작업 트리가 더러워져 옛 로그가 커밋에 섞이기 쉽다. 제품이 로그를 지운 뒤에는 같은 게이트가 무시되지 않는 새 로그를 만든다(두 제품 `.gitignore`에도 `*.log`가 없다). 템플릿의 리뷰 지시(`CLAUDE.md`)가 제품 루트에 남으면 제품의 에이전트가 "이 repo는 템플릿이다"라는 틀린 전제로 일한다. 데이터·보안 피해는 없다 |
| 심각도·우선순위 | Medium · P2 — 소비자 수 × 동기화 횟수만큼 반복되는 비용이다. 동작 결함은 아니다 |
| 통제·증거 | 목표 M3(지울 목록 + 읽는 코드 없음 검사). 확인: 목록 5종은 M3, 로그·coverage·CHANGELOG는 M0 · E3(worktree 실험, 두 제품 기록) |
| 확실성과 남은 가정 | 로그를 읽는 코드가 없다는 것은 `git grep`과 두 제품의 독립 조사가 일치한다. `copyReleaseEvidenceTree`(`scripts/lib/removal-fixture.ts:50-56`)가 `artifacts/`를 fixture로 복사하지만 로그를 읽지는 않는다 |
| 결정의 근거 | 확인된 사실: 로그는 `6f6c48e` 한 번만 커밋됐다. 기록된 의도: `.gitignore`와 `README.md:309-310`은 생성 증거를 추적하지 않는다는 규칙을 적는다. 로그를 추적하기로 한 기록은 찾지 못했다. 리뷰어의 추론: 규칙에서 벗어난 한 번의 커밋이다. 비교는 4.2절 |
| 이해 비용 | 제품 담당자가 동기화마다 템플릿 변경에서 "템플릿 자신의 기록"을 골라낸다. 근거는 `git grep`과 스크립트 읽기로 직접 찾아야 한다 |
| 최소 개선 방향 | ① `artifacts/**/*.log`와 `artifacts/tests/coverage-gateway/`를 `.gitignore`에 넣고 추적을 끊는다. 쓰는 곳 없는 `artifacts/local-preview/`도 지운다. ② `SPEC.md`·`tasks/`를 `docs/` 아래 이력 폴더 한 곳으로 옮긴다. ③ README 목록에 `CHANGELOG.md`(제품은 템플릿 repo의 CHANGELOG를 참조)와 `CLAUDE.md`(복사 뒤 교체)의 처리를 적는다. ④ `deletable-history-documents.test.ts`가 추적 중인 `artifacts/**/*.log`가 없는지도 확인하게 한다 |
| 대안 비교 | 4.2절: (A) 목록 보강만 / (B) 추적 중단 + 이력 폴더 통합 / (C) 별도 저장소. (B) 권장 |
| 단순화의 보존 조건 | 게이트가 읽는 파일(`docs/README.md:40-46`의 표, `artifacts/tests/a11y-manual/*.md`)은 옮기거나 지우지 않는다 |
| 비용·부작용 | 삭제 1커밋, 이동 시 참조 경로 수정. `CLAUDE.md`는 이 repo 작업에 필요하므로 남기고 목록에만 둔다 |
| 재검토 조건 | 템플릿 배포 방식이 생성기·패키지로 바뀔 때 |
| 완료 기준 | `git ls-files artifacts`에 `.gitkeep`과 게이트가 읽는 증거만 남는다. 새 worktree에서 `check:scale:pr` 뒤 `git status --short`가 비어 있다. README 목록에 복사 뒤 지울 경로가 빠짐없이 있다 |
| 검증 방법 | 새 worktree에서 `corepack pnpm check:scale:pr` → `git status --short`. 확장한 `deletable-history-documents.test.ts` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-02 README의 업데이트 절차가 실제 동기화(태그까지 범위 반영)를 다루지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.4, 20, 9, 16, 23 |
| 근거 | `README.md:315-353`은 수정 1건을 `cherry-pick -x`로 가져오고, 안 되면 `git diff`를 손으로 적용하라고 한다. "태그까지 따라잡으면 `.template-origin`을 갱신하라"(`:344-346`)고 하지만 따라잡는 방법은 없다. **실제로는 두 제품 모두 359커밋을 한 번에 받았다.** tech-log는 이력을 공유하지 않아 `git merge-recursive ebea300 -- HEAD template/main`으로 기준점을 지정한 3-way 병합을 했다(tech-log 기록 27-30행). memento는 이력을 공유해 `git merge --no-ff upstream/main`을 했다(memento 기록 31-33행). 충돌 67/25는 다시 계산해도 같았다. 두 제품은 README에 없는 단계를 각자 똑같이 만들었다: 되돌림 ref(`backup/main-before-template-af3d8e6`), 깨끗한 worktree에서 동기화 전 게이트 기준선(tech-log 32-51행, memento 35-64행), 제외 목록, 충돌 원칙("keep the template's mechanism, keep the product's content, never invent a third state", tech-log 82-84행, memento 4-8행), 파생 기준선 재계산(tech-log 272-290행: CI 계약 기준선·registry 승인 digest·runtime-config schema baseline. memento 80행: CI 계약 기준선). `docs/operations/ci-quality-gates.md:61-71`은 새 프로젝트가 초기화할 기준선을 적지만, 동기화 뒤 digest를 텍스트로 병합하지 말고 다시 계산하라는 말은 없다. 기준점 기록도 갈렸다: memento `.template-origin` 한 줄(`af3d8e6 2026-09-29`), tech-log `template.lock.json`(`sourceRevision`, `sourceTree`, `materialization`). tech-log는 README 형식보다 자기 형식이 "더 많은 것을 말한다"며 유지했다(tech-log 기록 264-266행). 템플릿은 두 형식 모두 읽지 않는다 |
| 발생 조건 | 제품이 태그 하나 이상을 따라잡을 때. 이력을 공유하지 않는 제품은 기준점을 틀리게 주면 이미 받은 변경을 다시 적용하거나 빠뜨린다 |
| 영향 | 동기화마다 절차를 새로 설계한다. 두 제품이 같은 절차를 따로 만들었다. 기준점이 한 줄 태그만 있으면 이력 비공유 제품이 정확한 3-way 기준을 복원하기 어렵다. 파생 기준선(`gateShapeSha256`, `registrySnapshotDigest`)을 텍스트로 병합하면 어느 쪽 값도 아닌 digest가 남는다 |
| 심각도·우선순위 | Medium · P2 — 모든 동기화에 드는 비용이다. 두 제품은 결국 올바르게 끝냈다 |
| 통제·증거 | M1(1건 반영만 문서화) · E3(두 제품 기록, `git merge-tree` 재현) |
| 확실성과 남은 가정 | 절차 부재는 README 전문으로 확인했다. 두 제품 모두 같은 소유자의 에이전트가 수행했으므로, 다른 팀이 같은 품질로 해낼지는 모른다 |
| 결정의 근거 | 확인된 사실: 두 제품의 실제 경로는 범위 병합이다. 기록된 의도: memento 부트스트랩 설계(`docs/superpowers/specs/2026-09-20-memento-…:16`)가 "upstream 추적 병합"을 택했다. 그 결정이 README 절에는 반영되지 않았다. 기준점 형식은 설계 선택이다. 한 줄 형식은 사람이 읽기 쉽다. JSON 형식은 기계 검사와 tree 대조가 가능하다. 둘 다 전체 커밋 SHA를 담으면 3-way 기준으로 충분하다 |
| 이해 비용 | 동기화 담당자가 Git 병합 전략, 파생 기준선의 계산 방식, 템플릿 기록 구분을 스스로 알아내야 한다 |
| 최소 개선 방향 | README "Updating a copied project"에 "태그까지 따라잡기" 절을 둔다. ① 되돌림 ref. ② 깨끗한 worktree에서 동기화 전 merge 게이트 기준선. ③ 이력 공유: `git merge <tag>`. 비공유: `git merge-recursive <기록된 기준점> -- HEAD <tag>`. ④ 제외 목록(14-01). ⑤ 파생 기준선은 `update:ci-contract-baseline`, `update:registry-baseline`, `check-compatibility.ts --update-baseline`으로 다시 계산하고 손으로 병합하지 않는다. ⑥ 충돌 원칙 한 줄. ⑦ CHANGELOG [계약] 행 점검(14-04). ⑧ 기준선과 게이트 비교. ⑨ 기준점 기록. 기준점 형식은 하나로 정하고 전체 커밋 SHA를 담는다. 두 제품 기록이 같은 목차(시작 상태 / 가져온 것 / 가져오지 않은 것 / 충돌 / 이행 수정 / 게이트 / 후속 / 질문)를 이미 쓰므로 그 목차를 기록 양식으로 싣는다 |
| 대안 비교 | (a) 현 상태: 비용 없음, 매번 재설계. (b) 문서 절 추가: 작은 비용, 절차가 한 곳에 모인다. (c) 동기화 스크립트 제공: 재현성은 높지만 병합 전략·충돌 해결은 자동화할 수 없고 유지비가 든다. memento 부트스트랩 설계도 스크립트안을 기각했다. (b) 권장 |
| 단순화의 보존 조건 | 1건 cherry-pick 절차와 결함 분류 규칙은 그대로 둔다 |
| 비용·부작용 | README 한 절. 기준점 형식을 바꾸면 tech-log나 memento 중 한쪽이 이행한다 |
| 재검토 조건 | 소비자가 늘어 동기화를 자동화할 가치가 생길 때 (c)를 다시 본다 |
| 완료 기준 | README 절차만 보고 이력 공유·비공유 제품 각각의 다음 동기화를 수행할 수 있다. 기준점 형식이 하나다 |
| 검증 방법 | 다음 템플릿 태그에서 두 제품 중 하나가 README 절차만으로 동기화하고, 기록에 README 밖 단계가 없음을 확인한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-03 제품이 고치게 되는 템플릿 파일과 그 이유가 문서에 없어, 같은 파일이 동기화마다 충돌한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 30.3, 30.4, 30.7, 3, 9, 25, 27 |
| 근거 | **반복 충돌.** 8개 경로가 세 번의 동기화(tech-log 09-21·09-29, memento 09-29)에서 모두 충돌했다(3.2절). 09-29에는 두 제품이 17개 경로에서 함께 충돌했다: 위 8개 + `src/features/installed-feature-contracts.ts`, `config/contracts/registry-change-evidence.json`, `config/contracts/registry-governance.json`, `scripts/check-design-system.ts`, `vite.config.ts`, `tests/e2e/accessibility.spec.ts`, `tests/visual/platform.visual.spec.ts`와 PNG 2개. **문서가 다루지 않는 수정 이유.** `starter-experience.md:136-147`은 기능 추가 때 `installed-*`를 고치지 않는다고 적는다. 기능 추가에는 맞다. 두 제품은 다른 이유로 이 파일을 고쳤다. memento는 `/`와 셸을 제품이 가진다: `installed-feature-contracts.ts`의 `APP_HOME` 교체 다리, `app-router.tsx`의 `ownsShell` 다리(memento 기록 108-166행). tech-log는 자기 도메인을 생성기 밖에서 조립한다: composer 5개에 직접 추가하고 `NOT_INSTALLED` 표식을 붙였다(tech-log 기록 94-104, 135-155행). `starter-experience.md:3-6`은 "page level에서 교체 가능"이라고만 한다. 템플릿 스크립트의 고정 목록도 수정 지점이다: `scripts/lib/removal-fixture.ts:25-39` `REMOVAL_FIXTURE_COPY_TARGETS`(memento가 Playwright 설정 2개를 추가, memento 기록 261행), `scripts/test-sample-removal.ts`(tech-log 두 번 연속 충돌), `scripts/check-design-system.ts`(두 제품 모두 제품 규칙 추가). 템플릿 화면에 묶인 템플릿 테스트도 수정 지점이다(30.5, `tests/component/router.test.tsx`는 tech-log에서 두 번 연속 충돌). **템플릿은 원리를 안다.** `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md:37,56`: "파생 프로젝트가 고치는 파일은 upstream 머지의 영구 충돌 지점이 된다". 그래서 식별자를 `package.json` name에서 파생하도록 바꿨다(`ebea300`). 같은 문서 `:35`: "삭제한 파일은 upstream 머지마다 충돌한다". 이 판단은 지워도 되는 이력 폴더에만 있다. 현재 계약인 `README.md:205-209`는 샘플 삭제를 안내하면서 이 비용을 적지 않는다. 두 제품 모두 샘플을 지우지 않았다. tech-log 09-29의 삭제 관련 충돌 18개(수정/삭제 17, 이름변경/삭제 1)는 모두 제품이 지운 샘플·예시 화면이다(`git merge-tree` 결과) |
| 발생 조건 | 제품이 홈·셸·라우터를 자기 것으로 바꾸거나, 생성기 밖에서 조립하거나, 템플릿 스크립트에 제품 규칙을 넣거나, 샘플·예시 화면을 지울 때. 그 뒤 템플릿이 같은 파일을 바꿀 때마다 |
| 영향 | 동기화마다 같은 파일에서 충돌을 푼다. 제품 코드가 템플릿 파일 안에 남아(memento 후속 1, tech-log 후속 6·7) 다음 동기화도 같은 충돌을 예약한다. 샘플 삭제를 안내대로 하면 동기화 비용이 늘고, 하지 않으면 쓰지 않는 샘플을 계속 들고 간다. 소비자가 늘면 비용이 곱해진다 |
| 심각도·우선순위 | Medium · P2 — 반복되는 유지 비용이다. 실패는 충돌로 드러나므로 조용한 결함은 아니다 |
| 통제·증거 | M0(수정 지점 목록 없음). 기능 추가 경로만 M1(`starter-experience.md:136-147`) · E3(세 번의 동기화 재현) |
| 확실성과 남은 가정 | 충돌 경로는 `git merge-tree`로 재현했다. 확장 지점이 생기면 몇 개가 사라질지는 09 영역의 판단에 달렸다 |
| 결정의 근거 | 확인된 사실: 8개 경로가 매번 충돌한다. 기록된 의도: 템플릿은 영구 충돌 지점을 줄이는 원리를 알고 한 번 적용했다(`ebea300`). 리뷰어의 추론: 그 원리가 현재 계약 문서로 옮겨지지 않아 나머지 파일에 적용되지 않았다 |
| 이해 비용 | 동기화 담당자가 충돌마다 "이 수정이 제품 고유인가, 템플릿에 요청할 확장 지점인가"를 새로 판단한다. 판단 근거가 두 제품 기록에 흩어져 있다 |
| 최소 개선 방향 | ① README 업데이트 절에 "제품이 고치게 되는 템플릿 파일" 표를 둔다: 파일, 제품이 고치는 이유(홈·셸 교체, 직접 조립, 제품 규칙), 충돌 때 원칙, 대신 요청할 확장 지점. ② `README.md:205-209`에 샘플 삭제의 동기화 비용과 대안(`NOT_INSTALLED`로 두기)을 적는다. ③ 영구 충돌 원리("제품 값은 제품 소유 파일에서 읽는다")를 이력 문서에서 `docs/architecture/`의 현재 계약으로 옮긴다. ④ 표의 8개 경로부터 제품 값을 제품 파일로 빼는 작업은 09 영역의 확장 지점 발견과 함께 다룬다 |
| 대안 비교 | (A) 문서만(표 + 샘플 삭제 비용): 비용이 작다. 충돌 수는 그대로다. (B) 문서 + 제품 값을 제품 소유 파일로 빼기(`ebea300` 방식, 예: `check-design-system`의 제품 규칙과 removal fixture 복사 목록을 설정에서 읽기, 홈·셸 확장 지점): 충돌이 준다. 템플릿 변경 비용이 크고 확장 지점 설계는 09 영역이다. (C) 기계 판독 소유 목록 + 검사: 새 도구와 유지비가 든다. 소비자 2개 규모에 과하다. (A) 먼저, (B)는 8개 경로부터 단계적으로 |
| 단순화의 보존 조건 | 기능 추가 때 중앙 catalog를 고치지 않는 현재 규칙(`starter-experience.md:145-147`)을 유지한다 |
| 비용·부작용 | (A)는 문서 한 표. 표가 낡지 않게 동기화 기록의 충돌 목록으로 갱신한다 |
| 재검토 조건 | 다음 동기화에서 표 밖의 경로가 두 제품 모두에서 충돌하면 표를 고친다. 확장 지점이 생긴 경로는 표에서 뺀다 |
| 완료 기준 | README에 표가 있고, 샘플 삭제 안내에 비용이 적혀 있다. 다음 동기화의 공통 충돌 경로가 모두 표에 있다 |
| 검증 방법 | 다음 태그에서 두 제품에 `git merge-tree`를 돌려 공통 충돌 경로를 표와 대조한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규. 확장 지점 자체는 09 영역 발견과 합칠 수 있다 |
### 14-04 CHANGELOG의 [계약] 표시가 제품 게이트를 깨는 변경을 빠뜨리고, 저장소 밖 조치에 담당과 확인 방법이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.4, 17, 26, 9, 21 |
| 근거 | 정의는 `CHANGELOG.md:8`: "[계약] 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경(헤더, 변수, 게이트, 공개 포트)". **(가) 게이트를 좁혀 제품을 깨뜨린 변경이 [계약]이 아니다.** ① 08-04 `check:i18n`이 `src/features/*/presentation`까지 검사(`411619c`) — `CHANGELOG.md:67`에 표시 없이 있다. memento는 21파일 408행이 red가 됐다(memento 기록 325행). ② F-5 `public/config.json` = local 프로필(`edf44a2`) — CHANGELOG에 없다. tech-log가 키 2개를 추가했다(tech-log 기록 345-352행). ③ 12-04 검증 package script는 게이트에 있거나 `config/ci/ungated-scripts.json`에 이유가 있어야 한다(`15a946f`) — `CHANGELOG.md:37`은 테스트 파일만 적는다. memento 4항목, tech-log 1항목. ④ 10-04 파일별 커버리지 하한(`d68e25a`, `config/testing/risk-coverage.json:182-189`) — `CHANGELOG.md:71` 표시 없음. memento가 테스트 파일 1개(케이스 14개)를 추가했다. ⑤ F-3·09-07 `second-api-feature-registries` 테스트(`606c191`) — `CHANGELOG.md:69` 표시 없음. tech-log에서 red. ⑥ 0.1.0 절(`CHANGELOG.md:80-88`)은 `ebea300..4626b73` 158커밋 중 보안 3건만 적는다. 기능·context·app 생성기와 `check:request-fanout`이 이 구간(`6f6c48e`)에 들어왔다. tech-log FE-GATE-010·005가 `check:request-fanout`으로 red다(tech-log 기록 469행). **(나) 저장소 밖 조치에 담당·확인 칸이 없다.** 표의 열은 표시·변경·영향 경로·커밋이고, 영향 경로는 템플릿 파일만 적는다. `CHANGELOG.md:24`(CORS의 `x-correlation-id`), `:25`(같은 멱등 키 재전송), `:27`(422 problem body 형식), `:28`(텔레메트리 수집기의 `build_id`·60KiB 분할)은 백엔드·게이트웨이·수집기가 할 일이다. 누가 하는지, 어떻게 확인하는지가 없다. 모든 V3 실행이 이 헤더를 보낸다(`src/adapters/http/http-execution-v3.ts:817-826`). 두 제품의 `API_BASE_URL`은 다른 origin이다(`config/runtime/local.json` `http://localhost:8080/`, staging·production `https://api.*.example.com/`). 두 제품 기록 모두 CORS 행에 대한 조치나 질문이 없다. 반면 멱등 키는 tech-log가 질문으로 남겼다(tech-log 기록 531-534행). tech-log 백엔드의 허용 헤더는 배포 변수(`APP_SECURITY_CORS_ALLOWED_HEADERS`)라 값을 확인하지 못했다 |
| 발생 조건 | 템플릿이 게이트 범위를 넓히거나 새 게이트를 추가할 때. 저장소 밖 조치가 필요한 [계약]을 제품이 동기화할 때 |
| 영향 | 제품은 게이트를 돌려 보고서야 해야 할 일을 안다. 두 제품이 템플릿 때문에 새로 red가 된 게이트·테스트는 5종·4종이다(3.2절). 저장소 밖 조치는 기록에서 빠질 수 있다. 제품이 다른 origin API로 배포하고 CORS가 `x-correlation-id`를 허용하지 않으면 V3 요청이 preflight에서 모두 거절된다. 이 경우는 High에 해당하지만 발생 여부는 확인하지 못했다 |
| 심각도·우선순위 | Medium · P2 — (가)는 게이트가 크게 실패하므로 조용하지 않다. (나)의 CORS 경로는 운영 조건이 확인되면 High로 올린다 |
| 통제·증거 | M1(표시 규칙은 있으나 적용이 빠짐) · E3(두 제품 기록, 커밋 대조) |
| 확실성과 남은 가정 | (가)의 누락은 커밋과 CHANGELOG 행을 대조해 확인했다. (나)의 운영 영향은 제품의 실제 배포 origin과 CORS 값에 달렸고, 둘 다 repo에 없다 |
| 결정의 근거 | 적용 제외 — 이미 정한 분류 규칙(`CHANGELOG.md:8`)을 행에 맞게 적용하고 칸을 하나 더하는 일이라 선택 비교가 필요하지 않다 |
| 이해 비용 | 동기화 담당자가 CHANGELOG의 "그 밖의 수정"까지 모두 읽고, 제품 게이트를 돌려 차이를 찾는다 |
| 최소 개선 방향 | ① 판정 규칙을 한 줄 더한다: "제품 코드를 고치지 않으면 제품의 게이트·빌드·런타임이 실패할 수 있는 변경은 [계약]". 게이트 범위를 넓힌 변경을 포함한다. ② [계약] 표에 "제품이 할 일 / 담당(프론트·백엔드·배포) / 확인 방법" 칸을 둔다. 예: CORS 행은 "API 게이트웨이의 `Access-Control-Allow-Headers`에 추가 / 백엔드·배포 / 다른 origin에서 V3 GET이 preflight를 통과". ③ 0.2.0의 ①~⑤를 [계약]으로 옮기고, 0.1.0 절에 생성기 토폴로지와 `check:request-fanout` 행을 더한다 |
| 대안 비교 | 적용 제외 — 규칙 보정과 칸 추가 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 릴리스마다 행 몇 개. 표가 넓어진다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 다음 동기화 기록의 "템플릿 때문에 새로 red" 항목이 모두 CHANGELOG [계약] 행과 연결된다. 저장소 밖 조치 행마다 담당과 확인 방법이 있다 |
| 검증 방법 | 태그 전 `git log <이전 태그>..HEAD -- config/ci config/testing scripts/check-*.ts`로 게이트 변경을 뽑아 [계약] 행과 대조한다. 다음 동기화 기록과 대조한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-05 기준선 표가 `FEATURE_OVERRIDES`의 남은 키를 "조용히 무시된다"고 적지만, 코드는 경고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 19, 24 |
| 근거 | `docs/operations/ci-quality-gates.md:69` "없음. 남은 키는 조용히 무시된다(리뷰 09-09)". 코드: 배포 승인이 경고를 쓴다(`scripts/check-release-admission.ts:84-94`). 부트가 `feature.override.unknown` 진단을 남긴다(`src/bootstrap/runtime-adapters.ts:462-470`). `CHANGELOG.md:58`도 09-09가 진단을 남긴다고 적는다 |
| 발생 조건 | 제품이 기능을 지우고 문서를 보고 프로필을 정리할 때 |
| 영향 | 남은 키를 찾을 수 있는 신호(승인 경고, 부트 진단)를 문서 독자가 모른다. tech-log는 이 경고를 알고 키를 지웠다(tech-log 기록 130-133행) |
| 심각도·우선순위 | Low · P3 — 한 칸의 문서 불일치 |
| 통제·증거 | M1(틀린 설명) · E1 |
| 확실성과 남은 가정 | 없음 |
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 수정 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 검사 위치 칸을 "`check:release-admission` 경고, 부트 진단 `feature.override.unknown`"으로 고친다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 없음 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 표의 문장이 두 코드 위치를 가리킨다 |
| 검증 방법 | 문서 대조. 이 문서는 `verify:documentation` 대상이 아니다(FOLLOW-UP 14-07) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 14-06 제품이 찾은 템플릿 결함 후보가 템플릿으로 돌아오지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 26, 30.4, 9 |
| 근거 | 분류 규칙과 신고 위치는 `README.md:348-353`에 있다. tech-log는 이 규칙대로 `check:remediation-ledger` 실패를 수정 없는 `af3d8e6` export에서 재현했다(tech-log 기록 473행). 그러나 템플릿 이슈는 0건이다(Gitea API `issues?state=all` → `[]`, `has_issues: true`). 템플릿 repo에서 두 제품의 발견을 적은 곳도 없다(`git grep -i 'tech-log\|memento'`는 2026-09-20 부트스트랩 설계만 찾는다). 제품 기록에 남은 템플릿 후보: memento 후속 2(`vite.service-worker.config.ts`에 `publicDir` 설정이 없어 `ACTIVE` worker 빌드가 `public/config.json`을 `dist/config.json` 위에 복사한다는 잠재 결함, memento 기록 202-207·345-346행), memento 후속 1(홈·셸 확장 지점 제안), memento의 SW e2e가 `null` worker를 가정(327행), tech-log 확대 표(`check:request-fanout`의 커서 페이지네이션 판정, `build-environment-bundle`의 청크 가정, 462-473행), tech-log 후속 7(context gateway 미장착) |
| 발생 조건 | 제품이 템플릿 결함이나 확장 지점 부족을 찾았을 때 |
| 영향 | 템플릿에서 고쳐지지 않으면 같은 조건의 다음 소비자가 같은 결함을 다시 찾는다. `publicDir` 후보가 사실이면, SW를 `ACTIVE`로 켠 운영 빌드의 `dist/config.json`이 local 프로필로 바뀐다. 배포 승인(FE-GATE-027)이 `APP_ENV` 불일치로 막을 가능성이 높지만 확인하지 못했다 |
| 심각도·우선순위 | Low · P3 — 전달 경로의 문제다. 후보 결함 자체의 심각도는 해당 영역이 정한다 |
| 통제·증거 | M1(신고 규칙) / 전달 단계 M0 · E3(제품 기록, Gitea API) |
| 확실성과 남은 가정 | 템플릿 소유자와 제품 소유자가 같아서 기록 밖에서 전달했을 수 있다. repo와 이슈에는 흔적이 없다 |
| 결정의 근거 | 적용 제외 — 이미 정한 신고 절차에 전달 단계를 잇는 일이다 |
| 이해 비용 | 템플릿 유지자가 소비자 repo의 동기화 기록을 직접 읽어야 결함을 안다 |
| 최소 개선 방향 | 14-02의 기록 양식에 "템플릿으로 보낼 것" 절을 두고, README 업데이트 절의 마지막 단계로 "그 절의 항목을 템플릿 이슈나 템플릿 FOLLOW-UP으로 옮긴다"를 둔다. 이번 두 기록의 후보는 이번 리뷰가 해당 영역(06, 09, 12, 13)으로 넘긴다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 동기화마다 이슈 몇 개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 두 제품 기록의 템플릿 후보가 템플릿 이슈나 FOLLOW-UP에 있고, 각각 처리 상태가 있다 |
| 검증 방법 | 다음 동기화 뒤 Gitea 이슈 목록과 제품 기록 대조 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 6. FOLLOW-UP 재확인
| FOLLOW-UP 항목 | 결과 | 현재 근거 |
|---|---|---|
| 2절 P2 `readSubject` 필수화: README 업데이트 절에 이행 한 줄, 단계적 도입 정책 결정 | 유효 | README에 없다(`README.md:315-353`). 이행 설명은 `starter-experience.md:72-76`에 있고 `CHANGELOG.md:43`이 그 문서를 가리킨다. tech-log는 이 경로로 이행했다(E3, tech-log 기록 316-328행). 그래서 README 한 줄의 효과는 작다. 남은 핵심은 "선택 → 경고 → 필수" 단계 정책이 어디에도 없다는 것이다(`docs/contracts/compatibility.md`는 런타임 산출물만 다룬다) |
| 4절 P3 14-07 `verify:documentation` 검사 범위가 좁다 | 유효 | 범위 밖에서 현재 계약 문서의 drift 1건을 새로 찾았다(14-05) |
| 4절 P3 09-07 기능 제거 검증이 lint·`check:i18n`·e2e를 건너뜀 | 유효 | 검사 목록 `scripts/test-sample-removal.ts:413-428`에 셋 다 없다. memento에서 `check:i18n`이 기능 presentation 때문에 red가 된 것처럼, 이 검사들이 제품의 기능 제거에서 실패할 수 있다 |
| 1절 P2 `check:remediation-ledger` 실패 | 유효(12 영역 소관) | 다운스트림 영향이 E3로 생겼다. tech-log는 동기화 전 PASS, 동기화 뒤 FAIL이며 템플릿 원인으로 확대했다(tech-log 기록 418·473행) |
| 6절 U-3 태그 `v0.2.0` push | 해소 | Gitea API tags: `v0.2.0` → `f753669` |
| 6절 U-4 작성자 외 기능 추가 기록 | 판단 불가 | memento가 문서 절차로 `memento-web`을 설치했다(E3). 같은 소유자라 "작성자 외" 조건은 충족하지 않는다 |
| 14-04 후속(버전·CHANGELOG) | 해소 | 태그, `CHANGELOG.md`, `README.md:315-353`이 있다. 실사용에서 드러난 빈틈은 새 발견 14-02, 14-04 |
| 14-05 후속(문서 색인) | 해소 | `docs/README.md`가 3묶음으로 나눈다. `:72`의 만료된 사유는 14-01에 포함했다 |
| 14-01 샘플 제거 게이트 | 해소 | 오케스트레이터 실행 `test:sample-removal` PASS(13개 검사) |
| 14-02 CI 계약 고정 | 해소 | `config/ci/contract-baseline.json` + `update:ci-contract-baseline`. 두 제품이 이 명령으로 기준선을 다시 계산했다(E3) |
| 14-03 기능 추가 안내 | 해소 | `starter-experience.md:86-147`. memento가 이 절차로 설치했다(E3) |
| 14-06 지원 범위 표 | 해소 | `README.md:94-124` |
| 14-08 제거 JUnit | 해소 | `scripts/lib/removal-fixture.ts:218-236`, `mkdtemp` `:172-175` |
## 7. 미검증 목록
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 두 제품의 운영 API가 `x-correlation-id` preflight를 허용하는지 | 허용 헤더가 배포 변수이고 값이 repo에 없다. 두 제품의 staging·production URL은 `example.com` 자리표시자다 | 실제 배포 origin과 API 게이트웨이 CORS 설정 확인. 다른 origin에서 V3 GET preflight 실행 |
| memento가 보고한 `vite.service-worker.config.ts` `publicDir` 잠재 결함 | SW `ACTIVE` 빌드가 필요하다. 06·13 영역 소관 | worktree에서 worker selection을 `ACTIVE`로 바꾸고 `APP_PROFILE=staging`으로 빌드한 뒤 `dist/config.json` 확인 |
| 템플릿 자체의 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules`를 보호하려고 생략 | 새 clone이나 컨테이너에서 README 명령만 실행 |
| 나머지 제거 스크립트 3개의 이번 커밋 결과 | 전체 묶음 실행 금지(공통 지시) | 단독 환경에서 `test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal` |
| 작성자 외 사람이 README 절차만으로 동기화할 수 있는지 | 두 동기화 모두 같은 소유자의 에이전트가 했다 | 14-02 개선 뒤 다른 사람에게 다음 태그 동기화를 맡기고 막힌 곳을 기록 |
| 사람 기준 동기화 시간 | 두 기록에 시간이 없다 | 다음 동기화에서 단계별 소요 시간 기록 |
@@ -0,0 +1,389 @@
# 템플릿 성숙도 리뷰 — 전체 종합 (2026-09-29)
> 검토일: 2026-09-29 · 기준: `main` / `af3d8e6`(태그 `v0.2.0` + docs 커밋 1개). 워킹트리에는 리뷰 가이드 문서 2개의 미커밋 변경만 있다. 코드는 `af3d8e6`과 같다.
>
> 기준 문서: [`TEMPLATE-MATURITY-REVIEW-GUIDE.md`](../TEMPLATE-MATURITY-REVIEW-GUIDE.md)(2026-09-28 보강판), [`TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`](../TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md)
>
> 범위: repo 전체를 지난 리뷰와 같은 14개 영역으로 나눴다. 영역별 리뷰 에이전트가 병렬로 읽었고, 이 문서는 그 결과를 오케스트레이터가 모은 것이다. 이번 라운드는 템플릿을 실제 제품 두 곳(`tech-log-frontend`, `memento-frontend`)에 적용한 기록을 증거로 함께 썼다.
>
> 이 리뷰에서 코드는 수정하지 않았다.
## 1. 사용 결정 (36.5-1)
전체 판정: **조건부 사용 가능.** 샘플을 두고 조회 화면 위주로 시작하고, 인증이 필요한 API만 쓰고, Service Worker·realtime을 켜지 않는 용도에 한한다.
지난 라운드의 차단 항목은 모두 풀렸다. 새로 막힌 곳은 대부분 "기본 구성 밖으로 한 걸음 나가는 순간"이다. 공개 API를 쓰거나, SW를 켜거나, 한 언어만 쓰거나, 제품 홈을 두는 경우다.
| 용도 | 결정 | 막는 항목 |
|---|---|---|
| 샘플을 두고 기능 1개로 시작, 인증이 필요한 조회 위주 | 조건부 사용 가능 | 없음. 쓰기를 복제하면 아래 행 참고 |
| 공개(`ANONYMOUS`) API를 쓰는 제품 | 사용 보류 | 09-01 |
| 쓰기(command) 샘플을 "결과 불명 처리" 예제로 복제 | 사용 보류 | 03-01, 03-03 |
| API가 다른 origin에 있는 배포 | 조건부 사용 가능 | 03-02(백엔드 CORS가 `x-correlation-id`를 허용하는지 먼저 확인) |
| Service Worker를 `ACTIVE`로 켜서 릴리스 | 사용 보류 | 06-01, 06-04 |
| 하위 경로(`/app/`) 배포 | 사용 보류 | 06-02, 13-02, 13-06, 08-08 |
| opt-in realtime(SSE)을 운영에 조립 | 사용 보류 | 04-01, 04-02 |
| opt-in OPFS·Cache Storage를 계정 삭제 보장에 사용 | 조건부 사용 가능 | 05-01, 05-02, 02-01 |
| 한 언어만 쓰는 제품 | 조건부 사용 가능 | 08-01, 08-02(템플릿 파일을 고쳐야 게이트가 통과) |
| 제품 홈·제품 레이아웃·제품 capability가 필요한 제품 | 조건부 사용 가능 | 09-02, 09-03, 14-03(템플릿 소유 파일을 고치게 되고, 동기화마다 충돌) |
| 이 repo의 CI를 머지 차단 장치로 믿기 | 사용 보류 | U-1(Actions 꺼짐), 11-01, 10-01 |
opt-in 런타임(realtime, OPFS, Cache Storage, Web Push, browser-transfer)은 기본 구성에 조립돼 있지 않다. 그래서 이 런타임들의 결함은 **기능을 켜는 다운스트림에서만** 나타난다. 두 제품이 이번에 겪은 문제 중 06-01(memento)과 09-01(tech-log)이 이 경우다. 두 제품은 각자 제품 쪽에서 막아 두었다.
## 2. 차단 항목 (P1)
같은 결함이 두 영역에서 나온 것은 하나로 합쳤다(9.3절). 심각도는 가이드 35.2절 기준이다. High 4건은 모두 오케스트레이터가 코드에서 다시 확인했다(9.2절).
**실제 사용자·데이터 피해로 이어지는 것**
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [09-01](09-app-core.md) | High | 공개 API(`ANONYMOUS` 인증 프로필)를 부르는 요청이 로그인 여부와 관계없이 전송되지 않는다. 조립 루트의 `attachCredentials`가 요청의 인증 프로필을 보지 않고 세션 상태만 본다. 로그아웃이면 `UNAUTHENTICATED`, 로그인이면 허용되지 않은 헤더로 거절된다. tech-log는 공개 화면 전체가 오류 화면이 되어 제품 쪽에서 고쳤다. | 코드 확인 + 에이전트 변이 실험(fetch 0회) |
| [03-01](03-adapters-http-state.md) | High | 결과 불명 쓰기를 같은 멱등 키로 다시 보냈을 때 서버가 "같은 키 처리 중" 409를 주면, 샘플 분류기가 모든 409를 `NOT_APPLIED`로 판정한다. 화면은 "충돌"로 바뀌고 다음 저장은 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번 생긴다. 짝 백엔드 템플릿은 실제로 이 상황에 409(`IDEMPOTENT_IN_FLIGHT`)를 준다. | 코드 확인 + 에이전트 재현(키 `[K, K, K′]`) |
| [04-01](04-adapters-realtime.md) | High | SSE 연결 중 서버가 죽거나 연결이 끊기면 SSE 어댑터가 이를 `OFFLINE`으로 보고한다. 재연결 코드는 "새 online 이벤트"를 기다린다. 브라우저 네트워크는 정상이라 그 이벤트가 오지 않는다. 그래서 재시도도 종료도 없이 영원히 멈춘다. 에이전트가 시험한 2줄 수정은 기존 재연결 테스트 36건을 모두 통과했다. 이 동작을 막는 테스트가 없다는 뜻이다. | 코드 확인 + 에이전트 재현(가짜 시계·fetch). 실제 브라우저·SSE 서버는 미검증 |
| [06-01](06-adapters-service-worker-push.md) (= 13-01) | High | SW를 `ACTIVE`로 켜면 SW용 두 번째 Vite 빌드가 `public/`을 다시 복사한다. 그러면 프로필로 만든 `dist/config.json`이 `public/config.json`(local, demo, `localhost:8080`)으로 덮어써진다. 빌드와 `verify-release`는 통과한다. release admission만 거절한다. 결과적으로 SW를 켠 제품은 릴리스를 만들 수 없다. `/app/` 빌드는 부팅하지 못한다. memento는 `publicDir: false`로 막아 두었다. | 코드 확인 + 에이전트 재현(빌드·admission·브라우저 부팅) |
**템플릿을 제품에 적용할 때 매번 드는 비용**
| ID | 심각도 | 내용 |
|---|---|---|
| [09-02](09-app-core.md) | Medium | 제품 capability, 세션 밖 자격증명(CSRF 쿠키·BFF), 제품 런타임 설정을 넣을 자리가 없다. 두 제품 모두 `src/bootstrap/runtime-adapters.ts`를 직접 고쳤다(memento +61줄, tech-log +118줄). 템플릿도 같은 기간에 이 파일을 15커밋 고쳤다. |
| [09-03](09-app-core.md) | Medium | 라우터가 `AppShell` 한 틀과 플랫폼 `APP_HOME`을 고정한다. 기능이 `APP_HOME`을 선언하면 조립에서 throw한다. 다른 id로 `/`를 선언하면 오류 없이 플랫폼 홈에 가려진다. memento는 라우터와 조립 카탈로그에 우회 코드를 넣었다. tech-log는 라우터를 통째로 바꿨다. |
| [08-01](08-presentation.md) | Medium | 제품이 지원 locale을 선언할 곳이 없다. 목록이 다섯 곳에 고정돼 있고 en-US가 필수다. 한 언어 제품은 가짜 번역을 만들거나 템플릿 파일을 고쳐야 한다. |
**검증 장치가 믿을 수 없게 동작하는 것**
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [11-01](11-tests-browser-release-scale.md) | Medium(조정) | merge 게이트 FE-GATE-013(security)의 첫 명령 `test:system`이 main에서 항상 실패한다. 13-04 수정(`839205c`) 뒤로 스크립트는 `…verification (current): PASS`를 출력하는데, 테스트는 옛 문자열 `…verification: PASS`를 기대한다. | 메인 repo에서 `test:system` 실행 → 2 failed / 110 passed. 그중 1건이 이것이다 |
| [10-01](10-tests-fast-layers.md) | Medium | 빠른 계층의 머지 게이트에 실행 속도에 기대는 테스트가 남아 있다. 2코어 조건에서 FOLLOW-UP 3절의 테스트 3개와 `router.test.tsx`, `extreme-scale-registry.test.ts`가 거짓으로 실패했다. | 에이전트 재현(`taskset` 2코어) |
## 3. 확인된 강점 (36.5-2)
- **지난 라운드의 수정이 유지되고 회귀가 없다.** 14개 영역 모두 지난 발견의 수정을 현재 코드에서 다시 확인했다. 수정을 되돌리는 변이도 테스트가 잡았다.
- 04: 18/18, 10: 11/12, 01: 12/13, 05: M1~M7 전부, 06: 전부
- 02: 수정한 규칙 12개 전부
- 지난번에 살아남던 변이 7종(01-04, 02-02, 02-08, 04-06, 06-04, 07-04, 07-05)도 이제 잡힌다(10).
- **게이트 결과가 좋아졌다.** 13개 게이트 중 12개가 통과했다(9.1절). 지난 라운드에 빨간색이던 `test:sample-removal`도 통과했다.
- 테스트 파일 327개 중 321개가 게이트에 속한다. 나머지 6개는 이유와 함께 제외 목록에 있다(10).
- 깨끗한 체크아웃에서도 빠른 계층이 통과한다(10).
- **다중 방어가 실제로 동작했다.** 06-01이 만든 잘못된 설정을 release admission이 거절했다(06, 13). 설정 결함이 production으로 가는 경로를 다른 게이트가 막는 것을 확인했다.
- **결과 불명 쓰기의 기본 경로가 동작한다.** 응답을 잃은 저장은 같은 멱등 키로 다시 보낸다. 브라우저에서 키가 같은 것을 확인했다(08). 폼 실패는 재로그인·권한 없음·나중에 재시도로 나뉜다(08). 남은 빈틈은 409 한 경우다(03-01).
- **`readSubject` 필수화는 안전하다.** subject가 없으면 닫힘 방향으로 동작하고, 경고 소음도 작다(03). 현 상태 유지가 맞다.
- **캐시·저장소 격리가 여러 겹이다.**
- 사용자 응답이 공개 캐시에 들어가는 경로를 막는다(02).
- 캐시 교체는 검증 뒤에만 성공을 말한다(02).
- SW 설치는 개수·크기·해시를 모두 검증한다(06).
- **kernel(`src/adapters/platform/`)에 정책이 쌓이지 않았다.** 파일 집합이 지난 리뷰와 같다. 교차 import를 넣으면 `check:architecture`가 잡는다(05). 현 상태 유지가 맞다.
- **realtime 재연결 수정이 여러 조건에서 동작한다.** 오래 열린 연결의 offline 깜빡임, 같은 틱의 offline/online, 12번 연속 세션에서 모두 재연결했다(04). 남은 빈틈은 SSE 서버 다운 한 경우다(04-01).
## 4. 반복되는 원인 (36.5-4)
고유 발견 89건은 다섯 원인으로 모인다. 고칠 때 원인 단위로 보는 편이 싸다.
1. **제품이 템플릿 소유 파일을 고쳐야 한다(확장 지점 부족).** 이번 라운드의 가장 큰 발견이다.
- 제품의 흔한 요구에 넣을 자리가 없다. 홈 라우트·레이아웃(09-03), 제품 capability·자격증명(09-02), 생성기 밖 조립(09-04), 지원 locale(08-01), 문구 파라미터(08-03), 오프라인 셸(06-03), 라우트 추가 시 governance 수정(07-03), journal DB 이름(05-10), 폰트·CSP(08-07, 13-04)가 여기 해당한다.
- 검사도 제품 정책으로 바꿀 수 없다(08-02).
- 플랫폼 테스트가 제품이 지울 화면에 묶여 있다(10-02).
- 이 문제는 두 제품의 동기화 비용으로 드러났다. 충돌은 tech-log 67경로, memento 25경로였다. 8개 경로는 세 번의 동기화에서 모두 충돌했다(14-03).
2. **선언과 실제 동작이 다르다.**
- 포트 표와 recovery가 다르다(01-01).
- CHANGELOG 행이 틀렸다(02-03, 04-05, 07-07). 게이트를 좁힌 변경을 [계약]으로 표시하지 않았다(14-04).
- 문서가 코드와 다르다(05-08, 07-03, 13-09, 14-05). 레시피 설명이 SW 계약과 다르다(06-03).
3. **실패를 한 단계에서 잘못 분류해 복구 경로가 닫힌다.**
- 409(처리 중)를 "적용 안 됨"으로 본다(03-01).
- 서버 다운을 "offline"으로 본다(04-01).
- 시간 초과를 "입력 거절"로 본다(03-05).
- 재시도 가능한 실패에 "할 일 없음"을 붙인다(01-01).
- 건너뛴 purge를 "완료"로 보고한다(05-02).
- High 4건 중 2건이 여기다.
4. **게이트가 실제 위험을 놓치거나 거짓으로 실패한다.**
- 항상 실패하는 merge 게이트(11-01), 부하 의존 테스트(10-01, 11-06), 판정이 뒤집히는 성능 게이트(11-04)가 있다.
- 어떤 입력으로도 통과할 수 없는 drill이 있다(11-02).
- 오탐과 미탐이 함께 있는 fanout 검사(12-01), 한글만 보는 i18n 검사(08-02), feature 폴더 우회(12-03)가 있다.
- 레지스트리 분류기가 과잉 판정과 과소 판정을 함께 한다(07-01, 07-02). zod facade 우회도 있다(07-06).
- 이 게이트들은 CI가 꺼져 있어(U-1) 아직 아무것도 막지 않는다. CI를 켜면 곧바로 드러난다.
5. **opt-in 경로는 켜 봐야 드러난다.**
- SW `ACTIVE`(06-01, 06-02, 06-04, 06-05), 하위 경로(13-02, 13-06, 08-08), SSE(04-01, 04-02)가 여기 해당한다.
- 템플릿 자신의 게이트는 기본 구성(SW `null`, 루트 경로)만 돌린다.
- 선택 기능을 켜야 재현되는 결함을 누가 맡는지도 정해져 있지 않다(13-10).
## 5. 결정이 필요한 것
| 항목 | 선택지 | 권고 | 승인자 |
|---|---|---|---|
| 확장 지점의 범위 (4절 원인 1) | (가) 템플릿이 확장 지점을 연다. (나) 제품이 템플릿 파일을 고치는 것을 공식 경로로 두고, 고칠 파일과 병합 방법을 문서화한다(14-03) | 세 번 모두 충돌한 파일부터 (가)를 적용한다. 예: 제품 홈·레이아웃(09-03), 제품 capability·자격증명(09-02), 지원 locale(08-01). 나머지는 (나)로 둔다. 효과는 다음 동기화의 충돌 수로 잰다 | 템플릿 소유자 |
| 03-01 수정 위치 | (가) 프론트 분류기가 problem code로 409를 나눈다(처리 중이면 결과 불명 유지). (나) 백엔드 계약 §6에 "처리 중" 응답 status를 정한다 | 둘 다 한다. 프론트는 모르는 409를 `MAYBE_APPLIED`로 본다 | 템플릿 소유자, 백엔드 템플릿 소유자 |
| 03-02 `x-correlation-id` | (가) 필수를 유지하고, 배포 체크리스트와 CORS 거절 진단을 추가한다. (나) 설정으로 끌 수 있게 한다 | (가). 동기화 기록 양식에 "백엔드 작업" 칸을 둔다(14-04) | 템플릿 소유자 |
| 12-01 fanout 검사 | (가) 규칙을 유지하고, 실패 메시지에 예외 방법을 적고, 커서 페이지네이션 허용 fixture를 추가한다. (나) 요청 사이 의존을 분석하도록 규칙을 고친다 | (가). 미탐 7종은 별도 개선으로 둔다 | 템플릿 소유자 |
| `check:remediation-ledger` (FOLLOW-UP P2) | 원장을 현재 코드에 맞춘다 / 검사를 없앤다 | 지난 라운드와 같은 결정이 남아 있다. tech-log도 같은 이유로 실패한다 | 템플릿 소유자 |
| 02-06 cross-context kernel 예외 | 타입 2개를 `src/contracts/`로 옮기고 파일 단위 예외를 지운다 / 유지한다 | 옮기는 실험이 모든 게이트를 통과했다(02). 12-07 때 정한 사항이라 재결정이 필요하다 | 템플릿 소유자 |
| 전체 리뷰 게이트 목록 (9.4절) | 루트 `CLAUDE.md` 2단계 목록에 `test:system`을 추가한다 | 추가한다. 이번 11-01은 이 목록 밖에서 나왔다 | 템플릿 소유자 |
## 6. 미검증 (36.5-5)
| 무엇 | 왜 | 확인하려면 |
|---|---|---|
| CI 러너에서의 실제 결과(FE-GATE-005~008·013·026·027, production 단계) | 세 repo 모두 Actions가 꺼져 있다(U-1). branch protection은 토큰 없이는 읽을 수 없다(401/403) | runner 1대와 PR 1건의 실행 기록 |
| 04-01을 실제 브라우저·SSE 서버에서 재현 | 가짜 시계·fetch로만 재현했다 | 로컬 SSE 서버를 띄우고 Playwright로 서버를 재시작 |
| 두 제품의 운영 CORS가 `x-correlation-id`를 허용하는지 | 허용 헤더가 배포 변수라 repo에 값이 없다. staging·production URL이 자리표시자다 | staging에 preflight 요청 |
| Firefox·WebKit | 대부분 영역이 chromium만 돌렸다. 01·02·06은 3엔진을 돌렸다 | 3엔진 `test:e2e`, `test:browser-capabilities` |
| 실제 호스팅·CDN 헤더, 하위 경로 live probe | provider가 정해지지 않았다 | 정적 서버에 `/app/`으로 배포한 뒤 `HOSTING_BASE_URL` 지정 |
| 여러 탭 시나리오(같은 uploadKey, purge와 덮어쓰기, 결과 불명 쓰기, 계정 전환 뒤 무효화 hint) | 단위 대역과 Node Web Locks로만 재현했다 | 두 컨텍스트 Playwright e2e |
| 실제 quota 초과·저장소 손상, 2 GiB 객체 검증 시간 | 제어할 환경이 없다 | quota를 줄인 프로필, 저사양 기기 측정 |
| 스크린리더 발표, 수동 접근성 서명(U-2) | 도구 없음 | NVDA·VoiceOver 검토 |
| 확장 지점 제안(09-02·09-03)이 실제로 동기화 충돌을 줄이는지 | 설계 제안이다 | 구현 뒤 두 제품에 한 번 이식하고, 템플릿 파일 diff가 0이 되는지 본다 |
| 작성자 외 사람이 README 절차만으로 동기화할 수 있는지 | 두 동기화 모두 같은 소유자의 에이전트가 했다 | 14-02 개선 뒤 다른 사람에게 다음 태그 동기화를 맡긴다 |
| 조용한 호스트에서 lab 성능(11-04)과 cgroup 테스트(11-06) | 13개 에이전트가 동시에 돌아 부하 평균이 16~36이었다 | 부하 없는 기계에서 5~10회 |
## 7. 개선 순서 (36.5-6)
사용자 계획은 "템플릿을 먼저 고치고 두 제품에 다시 반영한다"이다. 그 순서에 맞춘다.
| 단계 | 항목 | 이유 | 최소 변경 | 완료 기준 |
|---|---|---|---|---|
| 1 | 09-01, 03-01, 04-01, 06-01, 11-01 | High와 P1이고 수정이 작다. 09-01과 06-01은 제품이 이미 제품 쪽에서 막아 두었다. 템플릿이 고치면 다음 동기화에서 제품 패치를 지울 수 있다 | 각 영역 문서의 최소 개선 방향 | 각 문서의 완료 기준. 04-01은 막는 테스트를 함께 넣는다 |
| 2 | 09-02, 09-03, 09-04, 08-01, 08-02, 08-03, 07-03, 06-03, 10-02, 14-03 | 제품에 다시 반영하기 **전에** 해야 효과가 있다. 확장 지점 없이 다시 반영하면 같은 파일에서 또 충돌한다 | 5절 첫 행 결정 뒤, 충돌이 반복된 파일부터 | 두 제품의 다음 동기화에서 이 파일들의 충돌이 사라진다 |
| 3 | 두 제품에 재반영 | 1·2단계 결과를 받는다 | 지난 동기화 기록(`docs/operations/template-sync-2026-09-29.md`)의 방식 그대로 | 제품 쪽 우회 패치(tech-log 09-01, memento 06-01·09-03)를 지우고도 게이트가 통과한다 |
| 4 | 10-01, 11-06, 11-04, 12-04, 12-01, U-1 | CI를 켜기 전에 해야 한다. 켜는 순간 무작위로 머지를 막는다 | 각 문서 | 2코어 러너에서 빠른 계층을 20회 돌려 실패 0 |
| 5 | 14-01, 14-02, 14-04, 03-02, 07-04 | 다음 동기화의 비용과 백엔드 누락을 줄인다 | 업데이트 절차와 CHANGELOG 양식 | 다음 동기화 기록에 백엔드 작업 칸이 채워진다 |
| 6 | 05-01, 05-02, 02-01, 06-02, 06-04, 06-05, 13-02, 04-02, 01-01 | opt-in 런타임을 조립하기 전에 고친다 | 각 문서 | 각 문서 |
## 8. 재검토 조건 (36.5-7)
- 2단계의 확장 지점을 만든 뒤, 두 제품의 다음 동기화에서 충돌 경로 수를 이번(67, 25)과 비교한다.
- CI(U-1)를 켠 뒤에는 4절 원인 4의 게이트들을 실제 러너 결과로 다시 판정한다.
- SW·realtime·OPFS를 실제로 조립하는 제품이 생기면 해당 영역을 그 제품 기준으로 다시 본다.
- 백엔드 템플릿의 멱등·에러 계약이 바뀌면 03-01·03-03을 다시 본다.
- 템플릿이 locale 목록이나 i18n 검사를 바꾸면 08-01·08-02를 다시 본다.
- 초기 JS 예산 여유(현재 1,319 bytes, 기능 하나당 약 +3KB)를 넘는 기능이 들어오면 13·14번 관점을 다시 본다.
## 9. 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template`, `main` / `af3d8e6`. 미커밋 변경은 리뷰 가이드 문서 2개와 이 리뷰의 산출물뿐이다 |
| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + SW. SSR은 없다 |
| 필수 요구·규모·운영 목표 | 기능 수 증가 축만 목표가 있다. 요청량·SLO 목표는 없어서 연결점만 평가했다 |
| 읽은 범위 | `src/` 전체, `tests/` 전체(unit은 표본), `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정 |
| 제품 증거 | `tech-log-frontend`·`memento-frontend`의 `chore/template-sync-v0.2.0` 브랜치와 `docs/operations/template-sync-2026-09-29.md`(tech-log는 `-09-21.md`도). 읽기만 했다. 짝 백엔드 `clean-architecture-backend-template`은 03-01 근거로만 읽었다 |
| 수행한 테스트·실험 | 9.1절 게이트. 각 영역에서 대상 테스트 실행, 분리 worktree에서 변이·결함 주입, scratchpad 재현 스크립트. 01·02·06은 Playwright 3엔진, 05는 chromium·firefox, 나머지는 chromium만 |
| 확인하지 못한 범위 | 6절 |
| 이전 리뷰와 비교 | `2026-09-25-maturity-review`의 발견과 `FOLLOW-UP.md`를 현재 코드에서 다시 확인했다. 이전 실행 결과는 증거로 쓰지 않았다 |
### 9.1 게이트 실행 결과 (오케스트레이터, `af3d8e6`)
| 게이트 | 결과 |
|---|---|
| `check:architecture` | 통과 |
| `check:types` | 통과 |
| `lint` | 통과 |
| `check:adapter-inventory` | 통과 — 145파일 |
| `check:ci` | 통과 — 27 gates |
| `verify:documentation` | `PASS_SCOPED` |
| `test:unit` | 통과 — 164파일, 2349개 |
| `test:component` | 통과 — 34파일, 211개 |
| `test:integration` | 통과 — 13파일, 155개 |
| `test:contract` | 통과 — 3파일, 15개 |
| `test:runtime-schema` | 통과 — 3파일, 56개 |
| `test:sample-removal` | 통과 — 13 checks |
| `test:system` | **실패** — 2 failed / 110 passed. 1건은 11-01(기대 문자열). 1건은 11-06(부하 중 cgroup 레이스) |
| `test:realtime-removal` | 통과 — 7 base checks, runtime 의존 테스트 24개 제거 |
| `test:browser-file-storage-removal` | 통과 — 7 base checks, runtime 의존 테스트 53개 제거 |
| `test:optional-recipe-removal` | 통과 — 6 base checks |
| `check:remediation-ledger` | **실패** — 알려진 실패(FOLLOW-UP P2). `config/ci/ungated-scripts.json`에 이유와 함께 있다 |
`test:system`과 제거 드릴 3개는 루트 `CLAUDE.md`의 게이트 목록에 없다. 영역 에이전트가 11-01을 찾은 뒤, 그리고 worktree에서 돌리지 못한 영역이 있어서 오케스트레이터가 메인 repo에서 추가로 돌렸다.
### 9.2 오케스트레이터 재확인 (High 전부)
| ID | 방법 | 결과 |
|---|---|---|
| 09-01 | `http-execution-v3.ts:719-728`은 모든 operation에서 `attachCredentials`를 부르고 `authProfileId`를 넘긴다. `runtime-adapters.ts:501-531`은 `authProfileId`를 보지 않고 세션 상태만 본다(비로그인 → `UNAUTHENTICATED` `:509-511`). 로그인 상태면 세션 헤더를 붙이는데, `ANONYMOUS` 프로필은 허용 헤더가 0개다(`rest-profiles.ts:159-168`) | 확인 — 두 상태 모두 전송 전에 끝난다. 에이전트 변이 실험(fetch 0회)과 일치 |
| 06-01 (= 13-01) | `scripts/build-frontend.ts:65`이 프로필로 `dist/config.json`을 쓴 뒤 `:71`에서 SW용 `vite build`를 돌린다. `vite.service-worker.config.ts:69-82`에는 `publicDir`·`copyPublicDir` 설정이 없고 `emptyOutDir: false`다. Vite 기본값은 `public/`을 출력 폴더로 복사한다. `public/config.json`은 `APP_ENV: local`, `AUTH_MODE: demo`, `http://localhost:8080/`이다 | 확인 — 두 에이전트의 재현(빌드 exit 0, admission 거절 4건, `/app/` 부팅 실패)과 일치. 심각도는 06의 High를 따른다. 13은 admission이 막는다는 이유로 Medium을 줬지만, SW를 켠 제품이 릴리스를 만들 수 없다는 것 자체가 지원 구성의 중요한 기능 실패다(35.2) |
| 03-01 | `reference-feature-contract-contribution.ts:37-51`은 problem 종류와 관계없이 409를 `NOT_APPLIED`로 본다. `application-query.ts:583-589`는 `NOT_APPLIED`면 admission을 정리하고 conflict를 세운다. `use-app-form.ts:227-230`은 CONFLICT에서 `unknownSubmissionRef`를 비워 다음 저장이 새 제출(새 키)이 된다. 짝 백엔드 템플릿은 같은 키 처리 중에 `IDEMPOTENT_IN_FLIGHT` 409를 준다(`clean-architecture-backend-template/.../OperationalError.java:47`) | 확인 — 504 → 같은 키 재전송 → 409(처리 중) → 사용자가 다시 저장하면 새 키. 에이전트의 MSW 재현(키 `[K, K, K′]`)과 일치 |
| 04-01 | `fetch-sse-connection.ts:213-218`·`:396-400`은 fetch·reader 거절(서버 다운, 연결 reset)을 `OFFLINE`으로 보고한다. `reconnect-coordinator.ts:798`·`:994-998`은 `OFFLINE`이면 `requireOnline()`을 부르고, `:424-429`는 "지금보다 새로운 online 이벤트"를 요구한다. `:438-445`만 이 요구를 푼다. 브라우저가 계속 online이면 새 이벤트가 없어 `waitOnline`(`:455-479`)이 abort 전까지 끝나지 않는다 | 확인 — 에이전트의 가짜 clock·fetch 재현(20분 동안 시도 1회, 결과 없음)과 일치. 실제 브라우저·SSE 서버 재현은 하지 않았다 |
| 11-01 | `verify-exact-promotion-bundle.ts:78`은 항상 `(${freshness})`를 넣어 `Exact promotion bundle verification (current): PASS`를 출력한다. `ci-artifact-contract.test.ts:1259`는 `Exact promotion bundle verification: PASS`를 기대한다. `gates.json`에서 `test-system`은 FE-GATE-013의 첫 명령이다 | 확인(코드). 메인 repo `test:system` 실행 결과는 9.1절 |
### 9.3 중복 병합과 심각도 조정
같은 결함을 두 영역이 따로 적은 6쌍을 하나로 합쳤다. 앞의 ID를 대표로 쓴다. 뒤의 ID는 영역 문서에 남아 있지만 집계에서 뺐다.
| 대표 | 합친 것 | 이유 |
|---|---|---|
| 06-01 | 13-01 | 같은 원인(`vite.service-worker.config.ts`의 `publicDir` 누락). 13-01은 `build:app-only`도 같은 결과를 낸다는 근거를 더한다 |
| 08-02 | 12-02 | 같은 원인(`scripts/check-i18n.ts:12`의 한글 정규식) |
| 03-05 | 10-03 | 같은 원인(실행기가 마감을 두 번 읽음). FOLLOW-UP 3절 live-authority 간헐 실패의 원인이다 |
| 03-04 | 08-04 | 같은 결함(문의 식별자가 사용자까지 오지 않음). 03-04는 전송 쪽, 08-04는 화면 쪽 근거다 |
| 06-04 | 11-03 | 같은 원인(SW e2e 도우미의 `null` 문자열 치환) |
| 14-01 | 11-09 | 같은 결함(추적되는 실행 로그를 merge 게이트가 다시 씀) |
심각도 조정은 두 건이다.
- **06-01은 High를 유지한다.** 13-01은 release admission이 막는다는 이유로 Medium을 줬다. 그러나 SW를 켠 제품은 릴리스를 만들 수 없다. 지원 구성에서 중요한 기능이 실패하는 것이다(35.2).
- **11-01은 High에서 Medium으로 내렸다. P1은 유지한다.** 지난 라운드는 같은 성격의 10-01(새 clone에서 테스트 실패)을 같은 이유로 Medium으로 내렸다. 지금은 CI가 꺼져 있어 막히는 머지가 없고, 수정은 문자열 하나다. 다만 CI를 켜기 전에 반드시 고친다.
영역 07이 오케스트레이터의 전제 하나를 바로잡았다. "tech-log의 라우트 변경 6건이 0.2.0 분류기 때문에 막혔다"는 부분만 맞다. 0.2.0이 바꾼 것은 런타임 설정 스키마 분류기다. 레지스트리 분류기는 처음 만든 뒤로 바뀌지 않았다. 6건 중 4건은 governance가 선언한 breaking 필드이고, 2건이 07-02의 과잉 판정이다.
### 9.4 리뷰 절차에서 확인한 것
- **전체 리뷰 게이트 목록에 `test:system`이 없다.** 이 명령은 merge 게이트 FE-GATE-013의 첫 명령이다. 지난 라운드와 이번 라운드 모두 오케스트레이터가 돌리지 않았고, 11-01은 그 사이에 들어왔다. 루트 `CLAUDE.md` 2단계 목록에 추가할 것을 권한다(5절).
- **worktree에서 pnpm 스크립트를 돌리면 위험하다.** 영역 에이전트는 worktree의 `node_modules`를 메인 설치에 심볼릭 링크했다. 이 상태에서 `corepack pnpm <script>`를 부르면 pnpm이 링크를 통해 설치·삭제를 시도한다(`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`). 이번에는 no-TTY 가드가 막았고, 메인 `node_modules`는 그대로인 것을 여러 번 확인했다. 다음 리뷰에서는 worktree에서 `node`·`vitest`를 직접 부르고, pnpm이 필요한 드릴은 오케스트레이터가 메인 repo에서 돌린다.
- **13개 에이전트가 동시에 돌아 부하 평균이 16~36이었다.** 부하 의존 발견(10-01, 11-04, 11-06)은 이 조건에서 재현됐다. 조용한 호스트 결과는 6절 미검증에 있다.
### 9.5 영역 분할 (다음 리뷰에서 재사용)
| 번호 | 영역 | 경로 | 깊게 본 관점 | 문서 |
|---|---|---|---|---|
| 01 | browser-transfer | `src/adapters/browser-transfer/`, 포트 | 1, 5, 6, 12, 14, 17, 28 | [01](01-adapters-browser-transfer.md) |
| 02 | browser-files / cache / cross-context | `src/adapters/browser-files/`, `cache-storage/`, `cross-context-invalidation/` | 1, 5, 6, 11, 12, 15, 24 | [02](02-adapters-browser-files-cache.md) |
| 03 | HTTP·서버 상태·인증·진단 | `src/adapters/http/`, `browser-rpc/`, `query-cache/`, `auth/`, `diagnostics/`, `telemetry/` | 5, 6, 8, 12, 15, 17, 22 | [03](03-adapters-http-state.md) |
| 04 | realtime | `src/adapters/realtime/` | 6, 7, 12, 13, 14, 17 | [04](04-adapters-realtime.md) |
| 05 | 저장소·adapter kernel | `src/adapters/storage/`, `platform/`, `browser-file-storage/` | 1, 11, 12, 22, 27, 28 | [05](05-adapters-storage-kernel.md) |
| 06 | Service Worker / Web Push | `src/adapters/service-worker/`, `web-push/`, SW 빌드 설정 | 7, 12, 15, 18, 19, 28 | [06](06-adapters-service-worker-push.md) |
| 07 | contracts | `src/contracts/`, `schemas/`, `config/contracts/` | 1, 3, 17, 19, 22, 23, 24 | [07](07-contracts.md) |
| 08 | presentation | `src/presentation/` | 4, 5, 8, 14, 15, 23, 24 | [08](08-presentation.md) |
| 09 | 애플리케이션 코어·기능·조립 | `src/application/`, `features/`, `bootstrap/`, `platform/`, `apps/`, `contexts/` | 2, 3, 4, 9, 13, 22, 25, 27 | [09](09-app-core.md) |
| 10 | 테스트 — 빠른 계층 | `tests/unit`, `component`, `integration`, `contract`, `runtime-schema`, `features`, `platform`, `recipes`, `helpers`, `mocks`, `support` | 10, 12, 20, 21 | [10](10-tests-fast-layers.md) |
| 11 | 테스트 — 브라우저·릴리스·규모 | `tests/e2e`, `browser-capabilities`, `visual`, `storybook`, `release`, `scale`, `system`, `architecture`, `scripts` | 10, 13, 14, 18, 28 | [11](11-tests-browser-release-scale.md) |
| 12 | 가드레일·CI | 검사 스크립트, `.gitea/`, `config/ci`, `config/architecture`, lint·tsconfig·depcruise 설정 | 2, 16, 21, 25, 26 | [12](12-guardrails-ci.md) |
| 13 | 빌드·릴리스·설정·공급망 | 빌드·릴리스·보안 스크립트, `vite.config.ts`, `config/release·hosting·runtime·security`, `package.json`, lockfile | 15, 16, 18, 19, 26 | [13](13-build-release-supply-chain.md) |
| 14 | 템플릿 제품성·문서·DX·업데이트 전파 | `README.md`, `CHANGELOG.md`, `docs/`, `recipes/`, 제거 스크립트, 루트 추적 파일 | 9, 20, 26, 27, 30절 전체 | [14](14-template-product-docs.md) |
28개 관점은 모두 최소 한 영역에서 "깊게 본 관점"으로 배정했다. 각 영역은 28개 전부에 판정 기호와 한 줄 이유를 적었다. 영역마다 중요한 설계 선택 1~3개에 41절의 일곱 질문을 적용했다.
## 10. 28개 관점 판정 (36.2)
영역별 판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
종합 판정은 영역 판정을 평균하지 않는다. 한 영역이라도 미충족이면 그 이유를 적는다(35.7절).
| 번호 | 관점 | 영역 01~14 | 종합 판정 | 근거와 잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | O P P O O P O P O > > - > > | 부분 충족 | 입력 경계와 상태 전이는 강하다(01·04·05·07 O). recovery가 포트 표와 다르다(01-01). 정책을 바꾼 배포 뒤 캐시가 영구히 멈춘다(02-01). 건너뛴 purge를 완료로 보고한다(05-02). |
| 2 | 구조적 성숙도 | O P > O O O O O P > > P > > | 부분 충족 | 직접 import 위반은 `check:architecture`가 잡는다(05의 교차 import 2건 검출). feature 안의 다른 폴더를 거치면 우회된다(12-03). 생성기 밖 조립 경로가 없다(09-04). kernel 예외가 쓰임보다 넓다(02-06). |
| 3 | 변경 용이성 | O O P P P P P P X P P P P P | 미충족 | 제품의 흔한 요구(홈·레이아웃, 제품 capability, 지원 locale, 라우트 추가)에 템플릿 소유 파일을 고쳐야 한다(09-02, 09-03, 08-01, 07-03). 두 제품의 동기화 충돌이 67·25경로였다. |
| 4 | 인지 부하 | P P P P P P P P P P P P P P | 부분 충족 | 조립에 factory 6개와 같은 뜻의 값 여러 곳이 필요하다(01). locale 목록 다섯 곳(08-01), 라우트 제목 세 곳(08-06). 문서에 없는 한 줄 예외 규약(12-01). |
| 5 | 위험 가시성 | P P P P P P P P P P P P P > | 부분 충족 | 호출자가 결정에 쓰는 정보가 계약과 다르거나 없다. recovery(01-01), CORS 거절 원인(03-02), `inspect()` 비용(02-02), purge 결과(05-02). |
| 6 | 실패 성숙도 | P P P X P P O P P P O - O > | 미충족 (opt-in realtime) | SSE가 서버 다운 뒤 재시도도 종료도 없이 멈춘다(04-01). 처리 중 409가 키 보호를 푼다(03-01). 마감 경계에서 시간 초과가 입력 거절이 된다(03-05). 재시도 계층은 하나로 정리돼 있다. |
| 7 | 운영 성숙도 | O P P P P P > > P - P > > > | 부분 충족 | 관측 연결점은 있지만 sink는 다운스트림 몫이다. 운영 drill은 어떤 입력으로도 PASS할 수 없다(11-02). SLO는 템플릿 범위 밖이다. |
| 8 | 디버깅 가능성 | P P P P P P P P P P P P P O | 부분 충족 | 결과 불명·저장 실패 화면에 문의 식별자가 없다(03-04). 라우트 모듈 실패가 진단을 남기지 않는다(08-05). CORS 거절은 원인 없는 TypeError로만 보인다(03-02). |
| 9 | 유지보수 성숙도 | P P P P P P P P P P P P P P | 부분 충족 | CHANGELOG와 문서가 코드와 어긋난 곳이 여럿이다(02-03, 04-05, 07-07, 14-04, 14-05, 05-08). 갈라진 사본이 있다(05-03, 05-07, 11-07). |
| 10 | 테스트 성숙도 | P P P P P P P P P P P P P P | 부분 충족 | 변이 검출률이 높다(04 18/18, 10 11/12, 01 12/13). 부하 의존 테스트(10-01), 제품이 지울 화면에 묶인 플랫폼 테스트(10-02), 막는 테스트가 없는 규칙(04-01, 03-06, 10-04)이 남았다. |
| 11 | 데이터 성숙도 | P P - O P O > - P > - - > - | 부분 충족 | 계정 삭제 purge에 빈틈이 셋이다. 손상 행 하나가 purge 전체를 막고(05-01), 다른 탭과 겹치면 건너뛰며(05-02), 롤백·migration 실패 중에는 데이터가 남는다(05-05). |
| 12 | 동시성 성숙도 | O O P O P P - O > P O - > - | 부분 충족 | 인증 세대 fence와 탭 사이 Web Lock은 동작한다(03, 06). purge와 다른 탭의 덮어쓰기가 경합한다(05-02). |
| 13 | 확장성 | P O > P ? P P > P > P > > > | 부분 충족 | 기능 수 축: 기능 하나가 초기 JS를 약 3KB 늘리는데 예산 여유는 1,319 bytes다(13, FOLLOW-UP P1). 규모 기준선이 현재 코드와 다르고 측정 커밋 기록이 없다(11-05). |
| 14 | 성능 성숙도 | P P O P ? O - P > P P ? P > | 부분 충족 | 예산 여유가 초기 JS 1,319 B, 레시피 77·14·9 B다. lab 성능 게이트는 같은 빌드에서 판정이 뒤집힌다(11-04). |
| 15 | 보안 성숙도 | O O O O P P P P P > > O P > | 부분 충족 | CSP, 자격증명 헤더, 캐시 격리, demo 차단은 충족한다. 계정 삭제 뒤 데이터가 남는 경로(05-01), `zod/v4` facade 우회(07-06)가 있다. |
| 16 | 의존성 성숙도 | O - > O - P > > - > O P P P | 부분 충족 | lockfile·설치 정책은 동작한다. 실행하지 않는 `dependency-cruiser`가 남았다(12-05). SBOM이 deduped 노드를 development로 적는다(13-05). 설치 정책 회귀를 잡는 검사가 없다(13-08). |
| 17 | API / Contract | P P P P P P P P P P > P > P | 부분 충족 | recovery 표 불일치(01-01), `ANONYMOUS` 요청 불가(09-01), 레지스트리 분류기의 과잉·과소 판정(07-01, 07-02), 문구 파라미터가 타입에 없음(08-03). |
| 18 | 배포 성숙도 | O P > P P P > O > > P > P > | 부분 충족 | SW를 켜면 릴리스를 만들 수 없다(06-01). 하위 경로에서 SW 설치가 실패한다(06-02). `service-worker.js`의 `no-cache`가 호스팅 정책에 없다(06-05). |
| 19 | 설정 성숙도 | P P P P P X P P P P P P X P | 미충족 (SW `ACTIVE`·`.env` 입력·하위 경로 빌드) | SW `ACTIVE` 빌드가 local 설정을 싣는다(06-01). `.env*`로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다(13-02). 하위 경로 소비자가 base를 따르지 않는다(06-02, 13-06). |
| 20 | 개발자 경험 | P > > P > P P P P P P P P P | 부분 충족 | 업데이트 절차가 실제 동기화를 다루지 않는다(14-02). breaking 증거를 남기는 절차가 없다(07-04). 한 줄 예외 규약이 문서에 없다(12-01). |
| 21 | Guardrail 성숙도 | P P P O P P P P P P P X P P | 미충족 (머지 시점) | 세 repo 모두 CI가 꺼져 있다(U-1). CI를 켜면 FE-GATE-013이 항상 실패하고(11-01), 빠른 계층이 부하에서 거짓으로 실패한다(10-01). 로컬 검사는 부분 충족이다. fanout 오탐·미탐(12-01), 한글만 보는 i18n(08-02), feature 폴더 우회(12-03). |
| 22 | 추상화 성숙도 | O P P P P O P O P P P P > > | 부분 충족 | kernel은 현 상태 유지가 맞다(05). 제품이 넣을 확장 지점이 부족하다(09-02, 09-03). recipe port 사본이 갈라졌다(05-03). |
| 23 | 일관성 | P P O P P P P P P P P P P P | 부분 충족 | 같은 정보를 여러 곳에 적는다. CSP 네 곳(13-04), 라우트 제목 세 곳(08-06), CI 수치 두 곳(12-04), canonical JSON 세 벌(05-07). |
| 24 | 네이밍 / 의미 | P P P P P P P P P O P P P P | 부분 충족 | `NOT_INSTALLED`가 세 가지 뜻으로 쓰인다(09-04). 건너뛴 purge를 `COMPLETED`로 보고한다(05-02). `check:i18n`의 이름과 실제 검사가 다르다(08-02). |
| 25 | 조직 확장성 | - - > - ? - P P X - > P - P | 미충족 | 두 제품이 같은 템플릿 소유 파일을 고치고, 동기화마다 같은 곳에서 충돌한다. 8개 경로가 세 번의 동기화에서 모두 충돌했다(09-02, 09-03, 14-03). |
| 26 | Ownership | P > P - ? P P ? > P P P P P | 부분 충족 | 제품이 찾은 템플릿 결함 후보가 템플릿으로 돌아오지 않는다(14-06). 예외 목록에 담당·재검토 시점이 없다(12-07). 선택 기능 결함의 책임이 정해져 있지 않다(13-10). |
| 27 | 삭제 가능성 | P O > ? P ? > > P P P P > P | 부분 충족 | 샘플 제거와 레시피 제거 드릴은 통과한다(9.1절). file-transfer 어댑터만 지우면 게이트 3개가 실패한다(01-04). 샘플을 지우면 플랫폼 검사도 함께 지워진다(10-02). |
| 28 | 회복 가능성 | P X P P P P - O P - P - P > | 미충족 (opt-in cache-storage) | 정책을 바꾼 배포 뒤 Cache Storage가 영구히 멈추고 배포마다 캐시가 쌓인다(02-01). SW 제거 2·3단계가 일부 사용자에게 워커를 남긴다(06-06). drill은 복구를 판정하지 못한다(11-02). |
집계(적용 28개 기준): 충족 0 · 부분 충족 22 · 미충족 6(3, 6, 19, 21, 25, 28) · 미검증 0 · 적용 제외 0.
미충족 6개 중 6, 19, 28은 판정 칸에 적은 범위(opt-in 런타임, SW `ACTIVE`·하위 경로 빌드)에서만 미충족이다. 21은 머지 시점(CI)에서만 미충족이다.
## 11. 발견 색인
고유 발견 89건(영역 문서의 95건에서 9.3절의 중복 6건을 뺐다): High 4 · Medium 38 · Low 47. 우선순위는 P1 9 · P2 40 · P3 40. 성격은 확인된 결함 54 · 구조적 위험 26 · 개선 제안 9다.
심각도, 우선순위, ID 순서로 정렬했다.
| ID | 심각도 | 우선 | 성격 | 관련 관점 | 내용 | 비고 |
|---|---|---|---|---|---|---|
| [03-01](03-adapters-http-state.md) | High | P1 | 확인된 결함 | 6, 12, 17, 28, 5, 4 | 같은 키 재전송이 "처리 중" 409를 받으면 샘플 분류기가 `NOT_APPLIED`로 닫아 키 보호가 풀린다 | |
| [04-01](04-adapters-realtime.md) | High | P1 | 확인된 결함 | 6, 28, 18, 7, 8, 17, 23, 24, 5, 10 | SSE 네트워크 오류가 `OFFLINE`이 되어, 브라우저가 online이면 reconnect run이 재시도도 종료도 없이 멈춘다 | |
| [06-01](06-adapters-service-worker-push.md) | High | P1 | 확인된 결함 | 19, 18, 15, 10, 21, 23 | SW를 켜면 두 번째 Vite 빌드가 `public/`을 다시 복사해 프로필의 `dist/config.json`을 local 문서로 덮어씀 | 같은 결함: [13-01](13-build-release-supply-chain.md) |
| [09-01](09-app-core.md) | High | P1 | 확인된 결함 | 17, 6, 5, 10, 3, 30.5 (HTTP 실행 쪽은 03 영역과 겹침) | 조립 루트의 자격증명 판단이 인증 프로필을 보지 않아 `ANONYMOUS` operation이 절대 전송되지 않는다 | |
| [08-01](08-presentation.md) | Medium | P1 | 확인된 결함 | 3, 19, 20, 23, 25, 14 | 제품이 지원 locale을 선언할 곳이 없어, 한 언어 제품은 가짜 번역을 만들거나 템플릿 파일을 고쳐야 한다 | |
| [09-02](09-app-core.md) | Medium | P1 | 구조적 위험 | 3, 9, 25, 22, 15, 19, 20, 13, 30.3, 30.4, 30.7 | 제품 capability·자격증명·제품 설정을 넣을 확장 지점이 없어, 두 제품 모두 `runtime-adapters.ts`를 직접 고친다 | |
| [09-03](09-app-core.md) | Medium | P1 | 구조적 위험 | 3, 2, 22, 25, 8, 23, 27, 32.4, 30.3 | 라우터 조립이 `AppShell` 한 틀과 플랫폼 홈을 고정해, 기능이 `/`나 자기 레이아웃을 가질 수 없다 | |
| [10-01](10-tests-fast-layers.md) | Medium | P1 | 확인된 결함 | 10, 12, 14, 20, 21, 8 | 빠른 계층 머지 게이트에 실행 속도에 기대는 테스트가 남아 있다 — 2코어 러너에서 거짓 실패 | |
| [11-01](11-tests-browser-release-scale.md) | Medium | P1 | 확인된 결함 | 10, 21, 26, 9 (+30.8) | `tests/system`의 기대 문자열이 13-04 뒤의 출력과 달라, merge 게이트 FE-GATE-013(security)이 main에서 항상 실패한다 | 심각도 High → Medium 조정(8.3) |
| [01-01](01-adapters-browser-transfer.md) | Medium | P2 | 확인된 결함 | 17, 5, 6, 8, 23, 24 | `upload()` 실패의 recovery가 6개 경로에서 포트 표와 다른 행동을 가리킨다 | |
| [02-01](02-adapters-browser-files-cache.md) | Medium | P2 | 확인된 결함 | 28, 11, 18, 6, 19, 5, 24, 1 | Cache Storage pointer를 현재 정책으로 검증해, 정책을 바꾼 배포나 손상 뒤에는 조회·활성화·정리가 영구히 멈춘다 | |
| [03-02](03-adapters-http-state.md) | Medium | P2 | 구조적 위험 | 17, 19, 8, 6, 26, 21 | `x-correlation-id` CORS 허용이 교차 origin 배포의 전제인데 문서 통제뿐이다 | |
| [03-03](03-adapters-http-state.md) | Medium | P2 | 구조적 위험 | 6, 5, 22, 24, 17, 21 | 결과 불명 재전송이 키 없는 명령에도 열려 있다 | |
| [03-04](03-adapters-http-state.md) | Medium | P2 | 확인된 결함 | 8, 7, 6 | 결과 불명 쓰기에 문의 식별자가 없다 | 같은 결함: [08-04](08-presentation.md) |
| [04-02](04-adapters-realtime.md) | Medium | P2 | 구조적 위험 | 20, 22, 10, 17, 4, 3 | SSE를 reconnect coordinator에 잇는 세션 bridge가 없고, 열린 SSE 세션이 coordinator를 지나는 테스트가 없다 | |
| [05-01](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 11, 28, 15, 6, 27 | OPFS journal·staging의 손상 한 건이 그 partition의 계정 삭제 purge와 authority 전체의 reconcile·GC를 멈춘다 | |
| [05-02](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 11, 12, 15, 24, 5, 8 | purge가 지우지 못한 객체를 건너뛰고도 `chunkSweep: "COMPLETED"`로 보고한다 | |
| [05-03](05-adapters-storage-kernel.md) | Medium | P2 | 확인된 결함 | 22, 23, 17, 10, 9 | recipe의 같은 이름 port·fake가 src port와 다른 계약으로 갈라져 있다 | |
| [06-02](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 19, 18, 1, 10, 7 | SW 사전 캐시 목록이 router base path를 무시해 하위 경로 배포에서 워커 설치가 항상 실패함 | |
| [06-03](06-adapters-service-worker-push.md) | Medium | P2 | 구조적 위험 | 17, 3, 20, 5, 4 (30.3, 30.7) | 레시피는 오프라인 셸을 SW 설치 조건으로 적지만, SW 계약은 이를 금지하고 제품이 켤 확장 지점도 없음 | |
| [06-04](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 10, 20, 21 (30.4) | SW e2e 도우미가 선택 `null` 줄을 문자열로 바꿔서, SW를 켠 제품에서는 update·recovery spec이 모두 멈춤 | 같은 결함: [11-03](11-tests-browser-release-scale.md) |
| [06-05](06-adapters-service-worker-push.md) | Medium | P2 | 확인된 결함 | 18, 28, 19, 21 | 설계가 호스팅 설정에 맡긴 `service-worker.js`의 `no-cache`가 호스팅 정책 파일과 live probe에 없음 | |
| [07-01](07-contracts.md) | Medium | P2 | 확인된 결함 | 17, 21, 10, 5, 9, 26 | breaking 증거가 값과 묶이지 않아, 같은 row·field의 다음 변경을 새 증거 없이 통과시킨다 | |
| [07-02](07-contracts.md) | Medium | P2 | 확인된 결함 | 17, 23, 24, 21, 20, 3 | 레지스트리 분류기가 추가 성격의 변경(nullable 전환, allowlist 확장)을 breaking으로 막고, governance의 `breakingFields` 선언을 건너뛴다 | |
| [07-03](07-contracts.md) | Medium | P2 | 확인된 결함 | 3, 20, 22, 25, 13, 30.3, 39.5 | 기능 라우트 하나를 추가해도 템플릿 소유 governance의 중앙 allowlist를 고쳐야 한다 — 문서는 고칠 필요가 없다고 한다 | |
| [07-04](07-contracts.md) | Medium | P2 | 구조적 위험 | 20, 17, 8, 26, 25, 30.3, 30.4 | 다운스트림이 breaking 증거를 남기는 절차가 안내되지 않고, 템플릿의 기준선·증거가 제품의 이력처럼 복제된다 | |
| [08-02](08-presentation.md) | Medium | P2 | 확인된 결함 | 21, 23, 24, 10, 20 | `check:i18n`이 "파일에 한글이 있는가"만 봐서, 주석은 걸고 영어 문구·접근성 이름은 놓친다 | 같은 결함: [12-02](12-guardrails-ci.md) |
| [08-03](08-presentation.md) | Medium | P2 | 확인된 결함 | 3, 5, 17, 21, 22, 23, 25 | 기능 문구의 보간 파라미터가 타입 계약에 없어, `message()`가 틀린 호출은 통과시키고 맞는 호출은 거절한다 | |
| [08-05](08-presentation.md) | Medium | P2 | 확인된 결함 | 8, 6, 10, 28 | context 라우트 모듈의 비청크 실패와 feature·context 경계의 실패가 진단을 남기지 않고, 화면에는 build id만 보인다 | |
| [09-04](09-app-core.md) | Medium | P2 | 구조적 위험 | 2, 21, 24, 27, 4, 9, 30.7 | 생성기 밖에서 조립하는 제품 도메인의 공식 경로가 없고, `NOT_INSTALLED` 표시와 조립 파일 직접 수정을 아무 검사도 구분하지 못한다 | |
| [10-02](10-tests-fast-layers.md) | Medium | P2 | 확인된 결함 | 27, 20, 10, 21, 3, 22, 30.5, 30.7 | 플랫폼 테스트가 제품이 바꾸거나 지울 콘텐츠(스타터 화면, 참조 샘플)를 대상으로 쓴다 | |
| [11-02](11-tests-browser-release-scale.md) | Medium | P2 | 구조적 위험 | 7, 18, 28, 21, 5 (+30.8) | 운영 drill은 어떤 입력으로도 PASS할 수 없어, production 단계와 field 단계가 구조적으로 막혀 있다 | |
| [11-04](11-tests-browser-release-scale.md) | Medium | P2 | 구조적 위험 | 14, 10, 21, 18 | lab 성능 게이트(FE-GATE-026)는 중앙값 판정도 같은 빌드에서 뒤집힌다 | |
| [12-01](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 21, 10, 5, 8, 20, 24, 26, 14 | `check:request-fanout`이 요청 사이의 의존과 반복 횟수를 보지 않는다 — 제한된 커서 페이지네이션을 거부하고, helper를 거친 행별 요청은 통과시킨다 | |
| [12-03](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 2, 21, 5, 24, 10 | feature 안의 layer 폴더 밖 폴더는 경계 규칙이 없다 — feature presentation이 `contracts/`·`hooks/` 재수출로 `src/adapters/http`에 닿아도 모든 검사가 통과한다 | |
| [12-04](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 3, 9, 20, 27, 25, 17, 30.4 | CI 계약 크기가 기준선 파일과 테스트 상수 두 곳에 있고, 문서의 갱신 절차는 테스트 쪽을 빠뜨린다 | |
| [13-02](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 19, 23, 21, 18, 20 | 빌드 변수를 `.env*` 파일로 주면 번들과 빌드 스크립트가 서로 다른 값을 쓴다 | |
| [13-03](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 10, 21, 14, 3, 8 (+30.3, 30.7) | 청크 이름이 계약처럼 쓰이지만 선언돼 있지 않다 — 해시 안정성 테스트와 route 청크 매핑 | |
| [14-01](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 30.3, 9, 20, 21, 23, 27 | 템플릿의 실행 로그와 작업 기록이 복사·동기화 대상에 섞여 있다. 실행 로그는 merge 게이트가 다시 쓴다 | 같은 결함: [11-09](11-tests-browser-release-scale.md) |
| [14-02](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 30.4, 20, 9, 16, 23 | README의 업데이트 절차가 실제 동기화(태그까지 범위 반영)를 다루지 않는다 | |
| [14-03](14-template-product-docs.md) | Medium | P2 | 구조적 위험 | 30.3, 30.4, 30.7, 3, 9, 25, 27 | 제품이 고치게 되는 템플릿 파일과 그 이유가 문서에 없어, 같은 파일이 동기화마다 충돌한다 | |
| [14-04](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 30.4, 17, 26, 9, 21 | CHANGELOG의 [계약] 표시가 제품 게이트를 깨는 변경을 빠뜨리고, 저장소 밖 조치에 담당과 확인 방법이 없다 | |
| [03-05](03-adapters-http-state.md) | Low | P2 | 확인된 결함 | 6, 8, 10, 1 | 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"이 된다 | 같은 결함: [10-03](10-tests-fast-layers.md) |
| [05-04](05-adapters-storage-kernel.md) | Low | P2 | 구조적 위험 | 3, 21, 14 | offline-indexeddb 레시피 예산 여유 9바이트: 이 영역의 다음 수정이 게이트에 막힌다 | |
| [08-07](08-presentation.md) | Low | P2 | 개선 제안 | 15, 19, 20 | 폰트·전역 스타일을 넣을 제품 쪽 자리와 운영 CSP에 맞는 방법이 안내돼 있지 않다 | |
| [11-05](11-tests-browser-release-scale.md) | Low | P2 | 확인된 결함 | 13, 14, 9, 24 | 기능 규모 기준선이 현재 코드와 달라졌는데, 측정 기록에 소스 커밋이 없어 알 수 없다 | |
| [11-06](11-tests-browser-release-scale.md) | Low | P2 | 구조적 위험 | 10, 8 | `tests/system`의 cgroup 테스트는 부하가 있으면 이미 끝난 프로세스를 조회하다 실패한다 | |
| [13-04](13-build-release-supply-chain.md) | Low | P2 | 구조적 위험 | 15, 21, 9, 20 (+30.2) | 운영 CSP를 넓히는 경로에 안내와 내용 검사가 없고, 같은 문자열을 4곳에서 고쳐야 한다 | |
| [13-05](13-build-release-supply-chain.md) | Low | P2 | 확인된 결함 | 16, 24 | SBOM이 `pnpm list`의 `deduped` 노드를 따라가지 않아 번들되는 전이 의존성을 development로 적는다 | |
| [01-02](01-adapters-browser-transfer.md) | Low | P3 | 확인된 결함 | 28, 6, 11, 23 | complete가 반영된 뒤 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다 | |
| [01-03](01-adapters-browser-transfer.md) | Low | P3 | 확인된 결함 | 19, 5, 14, 20 | 느린 업링크 설정이 runtime 정책과 presigned 실행기에 따로 있고, 문서는 한쪽만 바꾸라고 한다 | |
| [01-04](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 27, 21, 20 (+30.4, 30.7) | file-transfer 어댑터만 지우면 게이트 3개가 실패한다 — 가드레일이 이 영역 파일 이름에 고정돼 있다 | |
| [01-05](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 17, 5, 24 | `abort()` 실패의 recovery에는 호출자 행동 표가 없다 | |
| [02-02](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 5, 14, 24, 10 | `inspect()`의 비용·취소·판정 불가가 포트 계약에 드러나지 않는다 | |
| [02-03](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 17, 9 (+30.4 업데이트 전파) | CHANGELOG 0.2.0의 browser-files [계약] 행이 실제 변경 경로·대상과 다르다 | |
| [02-04](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 9, 21 | 이 영역 설계 문서의 줄 번호 참조가 다시 밀렸다 | |
| [02-05](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 10, 6, 14 | bounded download에서 lease를 만든 뒤 handoff가 실패하면 lease를 돌려주는 규칙을 테스트가 고정하지 않는다 | |
| [02-06](02-adapters-browser-files-cache.md) | Low | P3 | 개선 제안 | 2, 21, 22, 5, 26 | cross-context-invalidation kernel 예외가 실제 쓰임(타입 2개)보다 넓다 | |
| [03-06](03-adapters-http-state.md) | Low | P3 | 개선 제안 | 10, 6 | UNKNOWN 동안 identity lease를 잡는 코드를 검증하는 테스트가 없다 | |
| [04-03](04-adapters-realtime.md) | Low | P3 | 확인된 결함 | 6, 17, 19, 23 | SSE `retry:` 값 처리 규칙이 설계 5.3·6.3과 코드에서 달라, 서버가 더 긴 대기를 요구하면 오히려 더 빨리 재연결한다 | |
| [04-04](04-adapters-realtime.md) | Low | P3 | 구조적 위험 | 6, 28, 20, 5 | hidden 탭에서 heartbeat를 멈춘 조용한 WebSocket은 예산을 새로 받지 못해, 그 사이 서버가 재시작하면 재시도 없이 끝난다 | |
| [04-05](04-adapters-realtime.md) | Low | P3 | 확인된 결함 | 9, 17 | CHANGELOG [계약] 문장이 실제 예산 초기화 조건보다 넓게 말한다 | |
| [05-05](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 11, 15, 17, 24 | IndexedDB 전체 삭제 경로의 적용 범위가 port·runbook 설명과 다르다 | |
| [05-06](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 22, 23, 15 | 한 레시피의 두 런타임이 삭제 승인 계약을 다르게 요구한다 | |
| [05-07](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 22, 9, 23 | kernel로 올릴 canonical JSON이 3벌로 갈라져 있다 | |
| [05-08](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 22, 9, 2 | kernel 범위 설명이 실제보다 좁고 편입 기준이 한 파일에만 있다 | |
| [05-09](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 19, 12 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 | |
| [05-10](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 19, 3 | OPFS journal DB 이름 접두사를 설정으로 바꿀 수 없어 제품이 소스를 고친다 | |
| [06-06](06-adapters-service-worker-push.md) | Low | P3 | 구조적 위험 | 28, 18, 26 | 제거 2·3단계는 `service-worker.js`를 내보내지 않아, 부팅을 막는 워커가 1단계 기간에 오지 않은 사용자에게 남음 | |
| [07-05](07-contracts.md) | Low | P3 | 확인된 결함 | 19, 23, 24, 9, 3, 39.5 | `ENV_REGISTRY`의 런타임 설정 행이 zod 스키마와 따로 적혀 있고, 이미 기본값·필수 여부가 다르다 | |
| [07-06](07-contracts.md) | Low | P3 | 구조적 위험 | 15, 21, 10 | zod facade 규칙이 정확히 `"zod"`만 막아서 `"zod/v4"` import가 검사를 통과한다 | |
| [07-07](07-contracts.md) | Low | P3 | 확인된 결함 | 24, 9, 17, 30.4 | CHANGELOG 0.2.0의 [계약] 행이 바뀌지 않은 레지스트리 분류기와 경로를 가리킨다 | |
| [08-06](08-presentation.md) | Low | P3 | 확인된 결함 | 23, 24, 21, 4, 10 | 라우트 제목이 계약·catalog·페이지 세 곳에 따로 있고, 샘플에서도 서로 다르며, catalog에서 빠져도 아무 검사도 실패하지 않는다 | |
| [08-08](08-presentation.md) | Low | P3 | 구조적 위험 | 17, 19, 24, 5 | 로그인 복귀 주소가 라우터 기준 경로라 base path 배포에서 앱 밖을 가리킬 수 있고, 포트 계약에 그 의미가 없다 | |
| [09-05](09-app-core.md) | Low | P3 | 개선 제안 | 9, 25, 30.3 | 제품이 고치도록 설계한 선택 파일에 템플릿 상태 설명이 같은 블록으로 섞여 있다 | |
| [10-04](10-tests-fast-layers.md) | Low | P3 | 구조적 위험 | 10, 12, 17, 15 | 실행기의 "오래된 scope의 성공 응답은 버린다"(§10.8) 마지막 검사를 어떤 테스트도 고정하지 않는다 | |
| [10-05](10-tests-fast-layers.md) | Low | P3 | 확인된 결함 | 20, 4, 21 | `test:all`("일상 개발 루프")이 CI가 돌리는 빠른 테스트 6파일을 빠뜨린다 | |
| [11-07](11-tests-browser-release-scale.md) | Low | P3 | 확인된 결함 | 9, 23, 22, 20 | 두 빌드 준비 helper가 두 벌로 갈라져, SW 쪽은 준비에 실패하면 임시 복사본을 남긴다 | |
| [11-08](11-tests-browser-release-scale.md) | Low | P3 | 확인된 결함 | 10, 21, 24, 28 | drill의 "상수 판정 금지" 테스트가 옛 모양(`true`)만 찾아, 상수 `"PASS"`를 통과시킨다 | |
| [12-05](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 16, 9, 27, 24 | 실행하지 않는 `dependency-cruiser`가 의존성에 남아 있다 | |
| [12-06](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 21, 10 | 게이트 밖 테스트 검사가 폴더 이름으로 판정해, Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 센다 | |
| [12-07](12-guardrails-ci.md) | Low | P3 | 개선 제안 | 26, 21, 23 | 게이트 예외 목록에 이유는 있지만 담당과 재검토 시점이 없다 | |
| [13-06](13-build-release-supply-chain.md) | Low | P3 | 확인된 결함 | 23, 19, 18 | 하위 경로 배포에서 base를 따르지 않는 소비자 두 곳이 남았다(13-07 잔여) | |
| [13-07](13-build-release-supply-chain.md) | Low | P3 | 구조적 위험 | 16, 23, 9 | 청크 설정이 Vite 8의 폐기 예정 별칭(`build.rollupOptions`)에 있어, `rolldownOptions`를 더하면 조용히 무시된다 | |
| [13-08](13-build-release-supply-chain.md) | Low | P3 | 구조적 위험 | 16, 21, 26 | pnpm 설치 정책이 파일에만 있고, 되돌림과 암묵 기본값을 잡는 검사가 없다 | |
| [13-09](13-build-release-supply-chain.md) | Low | P3 | 확인된 결함 | 20, 19 | README 변수 표가 staging·production의 `VITE_BUILD_ID` 필수 조건을 적지 않는다 | |
| [13-10](13-build-release-supply-chain.md) | Low | P3 | 개선 제안 | 26 (+30.4) | "선택 기능을 켜야 재현되는 템플릿 결함"의 책임이 정해져 있지 않다 | |
| [14-05](14-template-product-docs.md) | Low | P3 | 확인된 결함 | 9, 19, 24 | 기준선 표가 `FEATURE_OVERRIDES`의 남은 키를 "조용히 무시된다"고 적지만, 코드는 경고한다 | |
| [14-06](14-template-product-docs.md) | Low | P3 | 구조적 위험 | 26, 30.4, 9 | 제품이 찾은 템플릿 결함 후보가 템플릿으로 돌아오지 않는다 | |
@@ -0,0 +1,123 @@
# Template 프로젝트 성숙도 리뷰 — 실행 체크리스트
이 문서는 `TEMPLATE-MATURITY-REVIEW-GUIDE.md`의 **실행용 요약본**이다. 상세 판정 근거와 예외는 정본 가이드를 따른다. 체크리스트 자체를 별도 점수 체계로 사용하지 않는다.
## 1. 리뷰 시작 전에 고정
- 대상 저장소, 브랜치·커밋, 작업 트리 상태, 확인 시점
- 템플릿/프로젝트의 사용 목적과 지원 실행 형태
- 필수 요구, 데이터·권한 범위, 의존 시스템
- 규모 목표와 운영 목표가 있는지 여부
- 지원 기능·선택 기능·의도적 비지원 범위
- 템플릿 책임과 사용 프로젝트 책임
- 이번에 읽을 코드·설정·테스트 범위와 확인하지 못할 범위
목표가 없는 항목은 임의로 만들지 않는다. 목표가 없어서 판단할 수 없으면 `미검증` 또는 `판단 보류`로 남긴다.
## 2. 대표 경로를 먼저 따라간다
전체 파일을 균등하게 훑기 전에 실제 사용 흐름과 고위험 흐름을 선택한다.
- 정상 사용자 흐름 1개 이상
- 실패 시 피해가 큰 흐름 1개 이상
- 기능 추가·변경·삭제 흐름 1개 이상
- 필요하면 배포·복구·동시성·인증 경계 흐름
각 흐름에서 입력 → 정책 → 상태 변화 → 외부 I/O → 실패 → 사용자/운영 결과를 연결한다.
## 3. 28개 관점은 적용되는 것만 판정
- 적용 여부와 이유를 먼저 적는다.
- 목표 통제와 현재 통제를 분리한다.
- 근거 수준(E0~E4)과 통제 수준(M0~M4)을 혼동하지 않는다.
- 하나의 결함이 여러 관점에 걸리면 Finding은 하나로 두고 관련 관점만 연결한다.
- `미검증`을 완료율에서 빼지 않는다.
## 4. 먼저 찾을 고위험 문제
- 데이터 손상·권한 우회·민감정보 노출
- 결과 불명 쓰기와 잘못된 재시도·멱등성
- 동시성 경쟁·중복 처리·오래된 작업자의 쓰기
- 무제한 큐·병렬성·응답·메모리·재시도
- 배포·마이그레이션·복구 중 중간 상태
- CI/Guardrail이 있다고 문서에는 적혀 있지만 실제로 실행되지 않는 경우
## 5. 코드 품질은 “줄 수”보다 이해 부담과 보호 장치로 본다
대표 과제를 수행하면서 기록한다.
- 어디서 시작했는가?
- 반드시 알아야 하는 개념은 무엇인가?
- 이름과 실제 책임이 달라 다시 탐색한 곳은 어디인가?
- 숨은 등록 순서·전역 상태·문자열 키·설정 규약이 있는가?
- 중요한 위험과 실패 의미를 가까운 코드·타입·계약에서 찾을 수 있는가?
- 같은 사실을 annotation·descriptor·config·실행 코드에 반복한다면 각각 독립적인 역할과 불일치 검출이 있는가?
## 6. 추상화는 유지·내부화·통합·분리·제거 중에서 판단
각 추상화에 묻는다.
- 없으면 어떤 중복 지식·외부 결합·테스트 어려움이 생기는가?
- 호출자는 성공·실패·비용·수명주기를 추상화만 보고 이해할 수 있는가?
- 일반 사용자가 플랫폼 내부 개념까지 알아야 하는가?
- 더 작은 구조로 바꿨을 때 보호하던 계약을 그대로 유지할 수 있는가?
- 복잡하지만 현재 요구와 위험에 비해 정당하다면 **현 상태 유지**도 유효한 결론이다.
## 7. 중요한 설계 선택에는 Decision Explanation Test 적용
모든 한 줄에 적용하지 않는다. 객체 ownership, 공개 계약, 트랜잭션, 인가, retry/idempotency, cache, concurrency, module composition, template architecture처럼 계약·실패·유지비에 영향을 주는 선택에 적용한다.
1. 무엇이 필요한가?
2. 반드시 지킬 성질은 무엇인가?
3. 현재 코드는 어떻게 보장하는가? 무엇은 보장하지 않는가?
4. 현실적인 대안은 무엇인가?
5. 각 대안의 정확성·복잡성·성능·실패 특성·변경/운영 비용은?
6. 확인한 현재 조건에서는 왜 이 선택인가?
7. 어떤 요구·측정·규모·의존 계약이 바뀌면 선택도 달라지는가?
작성 당시 의도가 기록에 없으면 만들어내지 않는다. `작성자가 이렇게 생각했다`가 아니라 `현재 조건에서 이 선택을 유지할 근거는 ...`이라고 구분한다.
## 8. Finding 작성
필수:
- ID·제목
- 성격: 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안
- 관련 관점
- 현재 근거와 발생 조건
- 영향
- 심각도와 우선순위
- 확실한 사실과 남은 가정
- 최소 개선 방향
- 비용·부작용
- 완료 기준
- 검증 방법
설계 선택·구조 변경이면 추가:
- 현재 제약과 보호할 규칙
- 이해 비용
- 현실적인 대안과 차이
- 단순화 후 보존해야 할 계약
- 재검토 조건
단순 구현 결함이면 위 설계 선택 필드는 `적용 제외` 가능하다. 빈칸 대신 적용 제외 이유를 한 문장으로 남긴다.
## 9. 제안보다 검증을 우선
- 구조적 위험은 가능한 경우 작은 변경·변이 실험으로 실제 검출 여부를 확인한다.
- 실제 DB·브라우저·CI·외부 의존성 동작이 필요한 주장은 가능한 환경에서 해당 수준까지 검증한다.
- 실행하지 못한 브라우저·CI·부하·복구 조건은 정적 근거만으로 검증 완료라고 쓰지 않는다.
- 문서의 “구현 완료” 표시는 증거가 아니라 주장으로 취급한다.
## 10. 리뷰 종료 전 확인
- 현재 사용 가능한 범위와 보류 범위를 구분했는가?
- 차단 항목과 미검증 목록이 따로 있는가?
- 가장 중요한 Finding의 재현·검출 근거가 있는가?
- 단순화 제안이 기존 안전장치를 잃지 않는가?
- 중요한 기술 선택에 대해 `요구 → invariant → 현재 구현 → 대안 → trade-off → 선택 이유 → 재검토 조건`을 설명할 수 있는가?
- 수정하지 않는 것이 최선인 구조도 그렇게 기록했는가?
- 구현자가 “무엇을 바꾸면 끝나는지”와 “어떻게 다시 검증하는지”를 알 수 있는가?
충분한 근거가 모이면 리뷰를 끝낸다. 기준을 채우기 위해 새 프레임워크·불필요한 문서·장식성 메타데이터·중복 테스트를 추가하지 않는다.
File diff suppressed because it is too large Load Diff
@@ -31,7 +31,7 @@
| 파일 | 책임 | 주요 의존성 / 리뷰 결과 |
| --- | --- | --- |
| `src/adapters/browser-file-storage/index.ts` | browser data 공통 Result와 StorageManager adapter barrel export | 내부 두 모듈만 export. 경계가 작고 유지 대상. |
| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공 | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. |
| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공. IndexedDB 예외 표 `mapIndexedDbException`도 여기 있다(05-11, 옛 `storage/indexeddb/indexeddb-failure.ts`) | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. |
| `src/adapters/browser-file-storage/storage-manager-adapter.ts` | `estimate/persisted/persist` snapshot, pressure bucket, user-activation-bound persistence 요청 | storage durability port/result. estimate를 예약량으로 오인하지 않고 irreversible `persist()` truth를 보존한다. origin coordinator는 의도적으로 없음(GAP-03). |
### 1.2 `browser-files`
@@ -66,7 +66,6 @@
| `src/adapters/storage/browser-storage-adapter.ts` | registry key별 local/session/memory 저장, TTL, failure overlay/tombstone, quota fallback | `storage-keys`, `StoragePort`, codec, diagnostics. strict registry와 stale persistent suppression을 유지. adjacent physical-key migration/sweep는 문서상 미구현. |
| `src/adapters/storage/browser-storage-codec.ts` | bounded exact JSON envelope, exotic/accessor/unsafe-key/cycle/depth/node 거절 | 독립 codec. prototype pollution/JSON silent coercion 방어가 좋다. |
| `src/adapters/storage/indexeddb/index.ts` | IndexedDB runtime/maintenance/governance/migration export | native IDB type을 application port 밖으로 내보내지 않는 구조 유지. |
| `src/adapters/storage/indexeddb/indexeddb-failure.ts` | IDB/DOM failure를 closed browser failure로 변환 | common Result. raw native detail 비노출 유지. |
| `src/adapters/storage/indexeddb/indexeddb-governance.ts` | opaque dataset scope/physical DB identity 및 frozen policy binding | indexeddb/shared ports. account/business ID를 physical name에 쓰지 않는 양방향 binding 유지. |
| `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | post-open codec migration 및 idempotency receipt prune, keyset checkpoint, budget/revision fencing | IndexedDB port/types/failure/governance. async transform outside tx, row+sidecar+budget+checkpoint atomic commit은 좋다. STO-06 및 temporal drain lease 개선 후보. |
| `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | additive-only contiguous DDL planner/validator | indexeddb types. destructive DDL 거절 유지. |
+32 -33
View File
@@ -122,38 +122,37 @@
| 112 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 128 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 129 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 130 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 131 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 132 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 133 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 134 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 135 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 144 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 145 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 146 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 128 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 129 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 130 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 131 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 132 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 133 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 134 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 144 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 145 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
합계: **146/146**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **145/145**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
+5
View File
@@ -11,3 +11,8 @@ Close only when compatibility and release-coherence gates pass, critical smoke
passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
the restored release ID. Pointer-switch or cache-purge completion alone is not
recovery evidence.
Verify the prior release before switching to it: `verify:promotion -- --root
<bundle> --archived` and `drill:runbook -- FE-RB-005 --release-root <extracted
archive>`. The commands and inputs are in
[`docs/operations/release-cache-rollback.md`](../operations/release-cache-rollback.md).
+16 -1
View File
@@ -7,7 +7,22 @@ maps are prohibited defaults.
`config/hosting/security-headers.json` is the declared header set. Hosting
verification compares that declaration with live responses. CSP deliberately
omits `unsafe-inline` and `unsafe-eval`; production code and built assets must
remain compatible with that baseline.
remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of
`test:e2e`, FE-GATE-008) serves the build with these headers and fails on a
`securitypolicyviolation` event or console error (review 13-08). zod probes
`Function("")` on its first object schema, which the policy would report on
every boot. `src/contracts/zod.ts` sets `jitless` to skip that probe, and every
module that builds a schema imports `z` from there, so the setting is applied
before the first schema whatever order the bundler evaluates chunks in.
`z.config` in the entry module would be too late. Import `z` from
`src/contracts/zod.ts`, not from `zod`, in new schema code. Features that are off by
default need CSP additions when a project selects them; see step 9 in
[optional adapter recipes](../architecture/optional-adapter-recipes.md).
`connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to
the runtime config's `API_BASE_URL` and `TELEMETRY_ENDPOINT` origins needs a
header generated per environment at deploy time, because those values are set
per deployment (`scripts/generate-runtime-config.ts`). That generator does not
exist yet; a project that deploys should add it with its provider adapter.
Route guards are UX hints and client validation does not replace backend
authorization or validation.
+69
View File
@@ -39,6 +39,75 @@ Changing it requires `DEPENDENCY_BASELINE_OWNER` and
`DEPENDENCY_BASELINE_REASON`; editing the digest or hardcoding an empty diff is
rejected.
## 무엇을 증명하고 무엇을 증명하지 않는가
리뷰 13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
것으로 읽지 않는다.
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
|---|---|---|
| SBOM(`artifacts/release/sbom.cdx.json`) | lockfile에 고정된 설치 그래프(`pnpm list --depth Infinity`, `scripts/generate-supply-chain.ts`)와 각 패키지의 sha512 integrity, license | 배포물에 실제로 들어간 부분 집합, 취약점 없음 |
| 번들 패키지 목록(`artifacts/quality/vite-module-inventory.json`의 `packages`) | 배포 번들에 모듈이 하나 이상 들어간 패키지의 `name@version`. Vite가 번들에 넣은 모듈에서 바로 만든다(`scripts/lib/vite-module-inventory.ts`) | 패키지 안의 어떤 코드가 실행되는지, 취약점 없음 |
| local provenance(`artifacts/release/provenance.json`) | dist digest, lockfile, source set, SBOM digest가 서로 맞음 | 빌드 과정이 변조되지 않았음, 빌드한 주체. 서명이 없는 자기 보고다(`builder.id`가 `local:`, `invocationId`가 `LOCAL_UNSIGNED`). `predicateType`이 SLSA provenance v1이어도 SLSA 수준을 뜻하지 않는다 |
| 외부 provenance 서명 | 지정 키 보유자가 이 run, source revision, 후보 digest를 보고 서명함 | 빌드 job 자체의 격리, provider가 성실히 검사했음 |
| 외부 vulnerability 서명 | provider가 이 lockfile·dist에 대해 결과를 주장함 | 오프라인 DB의 최신성, 누락 없음 |
번들 패키지 목록은 SBOM의 production 항목에 모두 들어 있어야 한다. 2026-09-25
기준으로 한 건이 어긋난다. `scheduler@0.27.0`은 `react-dom`의 의존성이라 번들에
들어가지만, SBOM과 `config/security/dependency-baseline.json`은 이것을
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이 패키지를
다시 보여 주지 않고, 그래서 `scripts/lib/supply-chain.ts`의 순회가 development
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야 하므로
(`update:dependency-baseline`) 이 문서에 알려진 차이로 남긴다.
## 최소 구성과 전체 구성
리뷰 13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
systemd-run, systemd user manager 254 이상, cgroup v2 위임)과 오프라인 데이터로
Ed25519 서명 보고서를 내는 provider 두 개가 필요하다. 이 repo는 그 환경에서
workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나눠 적는다.
| 구성 | 켜는 것 | 보장하는 것 | 보장하지 않는 것 |
|---|---|---|---|
| 최소 구성(provider 없음) | merge·release stage 게이트, `immutable_build`(FE-GATE-015·027). provider 변수는 비워 둔다 | lockfile 무결성과 설치 스크립트 차단, SBOM과 local provenance의 digest 정합, secret scan, 재현 빌드, 후보 archive의 exact member와 digest, release 대상 환경 승인(FE-GATE-027) | 외부 취약점 검사, 서명된 provenance. provider job은 명령과 키가 없어 실패하고, `promotion` job은 두 provider job의 성공을 요구하므로 돌지 않는다. 승격은 사람이 결정한다 |
| 전체 구성 | 위 전부와 `vulnerability_provider`·`provenance_provider`·`promotion` job, 아래 runner 조건과 provider 키 | 위 전부와, 지정 키 보유자가 이 후보 digest·run·source에 서명했다는 것, 승격된 exact-five bundle(`verify:promotion`) | provider가 성실히 검사했는지, 빌드 job 격리(위 "무엇을 증명하고" 표 참고) |
최소 구성으로 운영할 때 승격은 수동 승인이다. 승인자는 `immutable_build`가
올린 후보 archive의 SHA-256(job output `archive_sha256`)과 local evidence를
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다. `production_gate`는
`promotion` 뒤에만 돌므로 이 구성의 workflow에서는 실행되지 않는다. 운영
게이트(FE-GATE-019, 021~025)는 배포한 release를 대상으로
`corepack pnpm ci:gate -- FE-GATE-0xx`로 따로 돌려 기록한다.
### provider 신뢰 키 교체와 폐기
신뢰 키는 repo 변수 `VULNERABILITY_PUBLIC_KEY_PATH`·`VULNERABILITY_KEY_ID`,
`PROVENANCE_PUBLIC_KEY_PATH`·`PROVENANCE_KEY_ID`가 가리키는 공개 키 파일이다
(`scripts/lib/provider-trust.ts`). 두 provider는 서로 다른 키를 써야 한다
(`assertDistinctProviderTrust`). 승격 기록은 키 ID·지문과 trust policy
SHA-256을 남긴다.
교체 순서:
1. provider가 새 키 쌍을 만들고 공개 키만 넘긴다.
2. 새 공개 키 파일을 runner가 읽을 수 있는 경로에 두고, 두 변수를 새 경로와 새
key ID로 한꺼번에 바꾼다. 키 ID는 새 값을 쓴다. 이전 ID를 재사용하면 기록만
보고 어느 키였는지 구분할 수 없다.
3. provider 쪽 서명 키를 새 키로 바꾼 뒤 release를 한 번 돌려 `promotion`이
통과하는지 확인한다.
4. 이전 공개 키 파일은 지우지 않고 보관한다. 이전 키로 승격된 release를 나중에
배포하거나 그 release로 롤백할 때 `verify:promotion -- --archived`가 그 키를
요구한다(`docs/operations/release-cache-rollback.md`).
폐기 순서(키 유출 등):
1. 해당 변수에서 그 키를 즉시 뺀다. 그 키로 서명된 새 승격은 이때부터 실패한다.
2. 보관 중인 이전 공개 키 파일도 지운다. 그 키로만 서명된 과거 release는
`verify:promotion -- --archived`를 통과하지 못한다.
3. 그런 release를 다시 써야 하면 새 키로 provider 검증을 다시 받는다. 같은 후보
archive를 대상으로 한 새 provider 실행이 필요하고, 다시 빌드하지 않는다. 이
repo에는 이 재검증 전용 job이 없다. 필요한 프로젝트가 만든다.
## External promotion controls
Promotion reads the provider files named by `VULNERABILITY_REPORT_PATH` and
+2 -2
View File
@@ -306,8 +306,8 @@ Pattern은 여러 primitive를 조합해 반복되는 사용자 문제를 해결
| Pattern | 필수 내용 |
| --- | --- |
| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh |
| `AccessSurface` | auth required, forbidden, not found |
| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh. 조회 실패가 `AUTH_REQUIRED`·`FORBIDDEN`·`NOT_FOUND`이면 `AccessSurface`와 같은 화면(`state-surfaces.tsx`)을 그린다(`async-surface.tsx`의 `ACCESS_SURFACES`) |
| `AccessSurface` | auth required, forbidden, not found. 조회 실패와 갤러리가 이 한 벌을 쓴다 |
| `Form` | submit, error summary, first-invalid focus, pending |
| `ConfirmationDialog` | destructive action 설명과 명시적 확인 |
| `ToastRegion` | queue, announcement, dismiss, focus policy |
@@ -142,8 +142,12 @@ rasterization과 실제 device farm은 프로젝트가 요구할 때 연결한
operation별 success/empty/slow/network/timeout/content/envelope/schema/auth/
403/404/409/422/429/retry/terminal을 포함한 19개 scenario catalog와 strict
unhandled-request server를 공유한다. clock/random/scheduler/storage helper와
browser console/page/network failure 정책으로 비결정적 우회를 차단한다.
unhandled-request server(`tests/mocks/server.ts`의
`onUnhandledRequest: "error"`)를 공유한다. browser test는 공용 fixture
(`tests/support/browser/strict-browser-test.ts`)가 console error/warning,
page error, 실패한 request를 test 실패로 만든다. 시간은 각 test가
`vi.useFakeTimers()`로 통제하고, 전역 `afterEach`가 실제 timer로 되돌린다
(`tests/setup.ts`). 공용 clock/random/scheduler helper는 두지 않는다.
#### Built-dist와 compact E2E
@@ -153,11 +157,25 @@ Chromium, Firefox, WebKit과 compact project로 실행한다. 빠른 Vite 개발
#### 위험 기반 coverage
V8 text/JSON/LCOV를 생성하고 전체 기준과 retry/storage/telemetry/application
composition/compatibility/performance/promotion/chunk/diagnostics/reference HTTP
operation/query-mutation/registry compatibility 19개 high-risk module에 80개
scoped threshold를 적용한다. critical module 누락 또는 threshold 미달 fixture는
merge gate를 실패시킨다.
V8 text/JSON/LCOV를 생성하고 `config/testing/risk-coverage.json`의 하한을
적용한다. 하한은 전체 평균 4개(`summary`: lines 75, statements 73, functions 80,
branches 68)와 `criticalModules` 20개의 모듈별 하한 80개(모듈마다 4개)다.
`check-risk-coverage.ts`는 두 종류를 합쳐 "84 thresholds"로 보고한다. 모듈은
HTTP 실행(`http-execution-v3.ts`, live 재시도 규칙 `http-retry-lifecycle.ts`,
계약 경로 규칙 `http-contract-bridge.ts`, legacy V2 `retry-policy.ts`, 요청 조립,
bounded body/JSON), server-state scope, Service Worker lifecycle, 저장소
(`browser-storage-adapter.ts`, `indexeddb-runtime.ts`), telemetry, application
조립, compatibility, chunk recovery, release manifest, boot JSON, diagnostics,
reference HTTP gateway, application query다. 모듈별 하한은 목표치가 아니라
등록할 때 측정값 근처로 둔 ratchet이다(되돌아가지 못하게 막는 하한). 새로
넣은 세 모듈은 2026-09-26 측정값을 내림한 값이다.
critical module 누락 또는 threshold 미달 fixture는 merge gate를 실패시킨다.
realtime(`src/adapters/realtime/`)과 Web Push(`src/adapters/web-push/`)는
`test:realtime-removal`이 통째로 지우는 선택 runtime이라
(`scripts/test-realtime-runtime-removal.ts`의 `runtimePaths`) 모듈별 하한에 넣지
않는다. 넣으면 그 runtime을 지운 다운스트림의 coverage gate가 없는 파일 때문에
실패한다. 두 영역은 전체 평균 하한만 받는다.
Repository inventory의 정적 provenance는 runtime 실행 가능 여부가 아니라 현재
Vitest/V8 producer가 file counter를 생성하는 문장의 존재 여부를 나타낸다. 따라서
@@ -724,15 +742,19 @@ tests/factories/
| `malformed-json` | 파싱 불가능한 JSON |
| `envelope-mismatch` | top-level contract 위반 |
| `schema-mismatch` | data payload contract 위반 |
| `auth-recover-once` | 첫 401 후 복구 성공 |
| `auth-persistent-401` | 복구 뒤에도 401 |
| `response-too-large` | 응답 본문이 크기 상한을 넘어 읽기를 멈춤 |
| `unauthenticated-401` | 401. 명령은 적용되지 않음(`NOT_APPLIED`) |
| `forbidden-403` | 권한 없음 |
| `not-found-404` | 리소스 없음 |
| `conflict-409` | mutation conflict |
| `validation-422` | 승인된 field/global error |
| `rate-limited-429` | Retry-After 포함 |
| `server-retry-success` | bounded retry 뒤 성공 |
| `server-terminal-500` | retry 소진 |
| `server-terminal-503` | 503. 조회는 retry 2회 뒤 소진, 명령은 retry 없이 결과 불명(`MAYBE_APPLIED`) |
이 표는 `tests/mocks/scenarios/catalog.ts`의 `HTTP_SCENARIO_IDS`와 같은 순서다.
401 뒤 인증 복구 흐름은 catalog가 아니라 `tests/integration/auth-recovery.test.ts`가
다룬다.
### 11.3 Catalog 규칙
@@ -951,6 +973,13 @@ fixture로 확인한다.
### 14.2 위험별 목표
아래 표는 올려 갈 **목표**다. 지금 gate가 막는 값은 이 표가 아니라
`config/testing/risk-coverage.json`의 현재값 ratchet이다(2.3절 "위험 기반
coverage"). 예를 들어 `service-worker-lifecycle.ts`의 branch 하한은 43,
`http-execution-v3.ts`는 52로 표의 목표보다 낮다. 테스트를 보강해 측정값이
오르면 그 모듈의 하한을 새 측정값으로 올린다. 하한을 내리는 변경은 이유를
커밋 메시지에 적는다.
| 영역 | Line/statement 참고 | Branch 우선 목표 |
| --- | --- | --- |
| registry/codec/schema | 95~100% | 100%에 가깝게 |
@@ -1103,8 +1132,11 @@ validate한다.
외부 배포 주소나 28일 field evidence가 없는 skeleton 개발 단계에서는 해당 gate가
실제 프로젝트가 채울 계약으로 남는다. 이를 fake data로 통과시키지 않는다.
현재 `FE-GATE-009`의 signed manual accessibility review는 merge gate다. 이
문서는 이를 production/field gate로 이동시키지 않는다.
signed manual accessibility review는 release gate `FE-GATE-028`이다
(`config/ci/gates.json`, 리뷰 08-06). 사람의 서명은 릴리스 후보 하나에 대해
하므로 merge마다 요구할 수 없다. merge gate `FE-GATE-009`는 자동 axe 검사와
기록 형식 검사(`review:a11y-manual -- --format-only`,
`scripts/lib/manual-a11y-evidence.ts`의 `validateManualA11yRecordFormat`)만 한다.
### 16.4 병렬화와 shard
+36 -8
View File
@@ -16,9 +16,11 @@ Each gate is blocking in its declared scope. Failures are not downgraded with
| end-to-end | `pnpm test:e2e` | pinned browser engines | `artifacts/tests/e2e/` |
| accessibility | `pnpm test:a11y` | pinned browser engines | `artifacts/tests/a11y.json` |
`test:all` is the normal product-development loop. It intentionally includes
runtime-schema, unit, capability-contract, component, integration, reference
feature and recipe suites, but does not include `test:system`. CI-runner and
`test:all` is the normal product-development loop. It runs, in order,
`test:runtime-schema`, `test:unit`, `test:contract`, `test:component`,
`test:integration`, `test:reference-feature`, `test:platform` (`tests/platform`
and `tests/architecture`), `check:release-coherence` and `test:recipes`
(`package.json` `test:all`). It does not include `test:system`. CI-runner and
supply-chain assurance has different host prerequisites and is invoked
explicitly in the assurance path.
@@ -37,6 +39,24 @@ That runner:
`vitest.config.ts` also fixes `NODE_ENV=test` so a direct Vitest invocation
cannot accidentally select React's production behavior.
To run one test file, use the same runner:
```sh
node scripts/run-vitest.ts run tests/component/router.test.tsx
```
The runner renders the gitignored `src/.generated/` product index first
(`scripts/run-vitest.ts`), so this works in a fresh clone. A direct
`pnpm exec vitest run <file>` skips that step and fails there with
`Failed to resolve import "../.generated/product-feature-index.ts"`.
`pnpm test:unit -- <file>` does not narrow the run, because the script already
passes the whole `tests/unit` directory.
`vitest.config.ts` collects only `tests/**/*.test.{ts,tsx}`; Playwright
`*.spec.ts` files are not Vitest tests. `tests/system/` is collected only when
the command names it, as `test:system` does, so a bare `vitest` run does not
start the CI-runner suite.
The system suite additionally runs
`scripts/check-system-test-prerequisites.ts` and fails with one prerequisite
report when the CI-runner host does not provide its required Linux facilities.
@@ -64,11 +84,19 @@ CI / release assurance:
A host-level process/sandbox test must not be placed in `tests/unit` merely
because it uses Vitest. The classification follows the system boundary and
prerequisites, not the test framework. Process-heavy tests that spawn child
processes but do not require privileged host facilities belong in
`tests/integration`; for example the provider guardian transaction protocol
lives at `tests/integration/provider-guardian-transaction.test.ts`. Its
handshake timeout is a test watchdog, not a production protocol deadline.
prerequisites, not the test framework:
- Tests that need systemd, bubblewrap, cgroup v2 or CI-provider process
controls belong in `tests/system`.
- Tests of a long-lived child-process protocol belong in `tests/integration`;
for example the provider guardian transaction protocol lives at
`tests/integration/provider-guardian-transaction.test.ts`. Its handshake
timeout is a test watchdog, not a production protocol deadline.
- A script's own tests may start that script, Node or Vitest as a short-lived
child process to check its command-line contract, and stay in `tests/unit`
next to the script's other tests. Such a suite declares its own longer
timeout instead of raising the global one; for example
`tests/unit/risk-coverage.test.ts` uses `PROCESS_HEAVY_TIMEOUT_MS`.
End-to-end and automated accessibility scenarios run on the pinned Chromium,
Firefox, and WebKit engines. The responsive contract explicitly exercises
+121 -43
View File
@@ -6,6 +6,10 @@ import type { Rule } from "eslint";
const sourceExtensions = "{ts,tsx,mts,cts}";
// 12-09. Editor-time aid only: these patterns show a layer violation while
// typing. The layer rules themselves live in .dependency-cruiser.json and are
// enforced by check:architecture, which resolves every import. Change a rule
// there first; these lists cover a subset and may lag behind it.
const layerPatterns = {
domain: [
"**/application/**",
@@ -33,8 +37,21 @@ const layerPatterns = {
adapters: ["**/presentation/**", "**/bootstrap/**"],
};
function restrictedImports(patterns: readonly string[]) {
return ["error", { patterns }];
// 12-11. Each pattern group carries the reason and the way out; the default
// message only named the pattern.
const layerMessages = {
domain:
"domain stays framework-neutral (.dependency-cruiser.json domain-is-framework-neutral). Move the code to application or pass the value in.",
application:
"application declares ports and never imports UI, adapters or bootstrap (application-does-not-know-concrete-runtime). Add a port under application/ports; bootstrap passes the adapter.",
presentation:
"presentation reaches the runtime through the application API (presentation-does-not-know-adapters). Use the application facade; bootstrap composes adapters.",
adapters:
"an adapter implements an application port and never imports UI or bootstrap (adapters-do-not-know-presentation). Pass what it needs through the port.",
} as const;
function restrictedImports(patterns: readonly string[], message: string) {
return ["error", { patterns: [{ group: [...patterns], message }] }];
}
const restrictedBrowserDataProperties = [
@@ -539,7 +556,7 @@ export default [
{
files: [`src/domain/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.domain),
"no-restricted-imports": restrictedImports(layerPatterns.domain, layerMessages.domain),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -564,7 +581,7 @@ export default [
{
files: [`src/application/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.application),
"no-restricted-imports": restrictedImports(layerPatterns.application, layerMessages.application),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -589,7 +606,7 @@ export default [
{
files: [`src/presentation/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.presentation),
"no-restricted-imports": restrictedImports(layerPatterns.presentation, layerMessages.presentation),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -613,24 +630,30 @@ export default [
`src/presentation/adapters/query/**/*.${sourceExtensions}`,
],
rules: {
"no-restricted-imports": restrictedImports([
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
],
"the TanStack Query binding may import @tanstack only; reach adapters through application ports (presentation-does-not-know-adapters).",
),
},
},
{
files: [`src/presentation/templates/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports([
"**/application/**",
"**/adapters/**",
"**/bootstrap/**",
"@tanstack/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/application/**",
"**/adapters/**",
"**/bootstrap/**",
"@tanstack/**",
],
"page templates own layout only (page-templates-own-layout-only). Take data and actions as props from the page.",
),
},
},
{
@@ -659,7 +682,7 @@ export default [
{
files: [`src/adapters/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.adapters),
"no-restricted-imports": restrictedImports(layerPatterns.adapters, layerMessages.adapters),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -700,7 +723,7 @@ export default [
{
files: [`src/features/*/domain/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.domain),
"no-restricted-imports": restrictedImports(layerPatterns.domain, layerMessages.domain),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -725,7 +748,7 @@ export default [
{
files: [`src/features/*/application/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.application),
"no-restricted-imports": restrictedImports(layerPatterns.application, layerMessages.application),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -750,15 +773,18 @@ export default [
{
files: [`src/features/*/presentation/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports([
"**/features/*/adapters/**",
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
"@tanstack/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/features/*/adapters/**",
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
"@tanstack/**",
],
"feature presentation calls its application API (feature-presentation-does-not-know-outbound-adapters). Bootstrap wires the adapters.",
),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -780,11 +806,14 @@ export default [
{
files: [`src/features/*/adapters/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports([
"**/presentation/**",
"**/bootstrap/**",
"@tanstack/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/presentation/**",
"**/bootstrap/**",
"@tanstack/**",
],
"a feature adapter implements the feature's ports and never imports UI or bootstrap (feature-adapters-do-not-know-presentation).",
),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -823,14 +852,17 @@ export default [
`tests/fixtures/architecture/forbidden/**/*.${sourceExtensions}`,
],
rules: {
"no-restricted-imports": restrictedImports([
"**/adapters/**",
"**/application/ports/out/**",
"@tanstack/**",
"react",
"react-dom",
"**/application/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/adapters/**",
"**/application/ports/out/**",
"@tanstack/**",
"react",
"react-dom",
"**/application/**",
],
"forbidden architecture fixture: this import must be rejected.",
),
"no-restricted-globals": [
"error",
"fetch",
@@ -865,4 +897,50 @@ export default [
],
},
},
{
// 13-06. Vite inlines every loaded VITE_* value into the bundle wherever
// code references the whole `import.meta.env` object, including values no
// code reads. Keyed reads are replaced one by one.
files: [`src/**/*.${sourceExtensions}`],
plugins: {
"build-env": {
rules: {
"no-whole-import-meta-env": {
meta: {
type: "problem",
schema: [],
messages: {
whole:
"Read build variables by key (import.meta.env.VITE_NAME). Referencing import.meta or import.meta.env as a whole bundles every VITE_* value (13-06).",
},
},
create(context: any) {
const isMember = (node: any) =>
node?.type === "MemberExpression" ||
node?.type === "OptionalMemberExpression";
return {
MetaProperty(node: any) {
if (node.meta?.name !== "import") return;
const member = node.parent;
if (!isMember(member) || member.object !== node || member.computed) {
context.report({ node, messageId: "whole" });
return;
}
if (member.property?.name !== "env") return;
const read = member.parent;
if (isMember(read) && read.object === member && !read.computed) {
return;
}
context.report({ node: member, messageId: "whole" });
},
};
},
},
},
},
},
rules: {
"build-env/no-whole-import-meta-env": "error",
},
},
];
+6 -5
View File
@@ -1,6 +1,6 @@
{
"name": "clean-architecture-frontend-template",
"version": "0.1.0",
"version": "0.2.0",
"private": true,
"type": "module",
"packageManager": "pnpm@11.17.0",
@@ -22,7 +22,7 @@
"check:i18n:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts --fixture",
"check:adapter-inventory": "node scripts/check-adapter-inventory.ts",
"check:remediation-ledger": "node scripts/check-remediation-ledger.ts",
"check:release-admission": "node scripts/check-release-admission.ts",
"check:release-admission": "node scripts/generate-product-feature-index.ts && node scripts/check-release-admission.ts",
"check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts --fixture",
"check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:recipes && corepack pnpm check:types:web-worker && corepack pnpm check:types:service-worker",
@@ -72,13 +72,13 @@
"check:test-evidence:fixture": "node scripts/check-test-evidence.ts --source-root tests/fixtures/test-evidence/forbidden --artifact artifacts/quality/test-evidence-fixture.json",
"test:a11y": "node scripts/generate-product-feature-index.ts && playwright test --grep @a11y && node scripts/write-a11y-report.ts",
"review:a11y-manual": "node scripts/generate-product-feature-index.ts && node scripts/verify-a11y-manual.ts",
"test:sample-removal": "node scripts/test-sample-removal.ts",
"test:sample-removal": "node scripts/generate-product-feature-index.ts && node scripts/test-sample-removal.ts",
"test:optional-recipe-removal": "node scripts/test-optional-recipe-removal.ts",
"test:browser-file-storage-removal": "node scripts/test-browser-file-storage-runtime-removal.ts",
"test:realtime-removal": "node scripts/test-realtime-runtime-removal.ts",
"test:reference-feature": "node scripts/run-vitest.ts run tests/features/reference-feature --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/reference-feature.xml --passWithNoTests",
"check:v8-coverage-counter-semantics": "node scripts/check-v8-coverage-counter-semantics.ts",
"test:coverage": "corepack pnpm check:v8-coverage-counter-semantics && node scripts/run-vitest.ts run tests/runtime-schema tests/unit tests/contract tests/component tests/integration tests/features/reference-feature tests/platform --coverage --maxWorkers=4 --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/coverage.xml && node scripts/check-risk-coverage.ts",
"test:coverage": "corepack pnpm check:v8-coverage-counter-semantics && node scripts/run-vitest.ts run tests/runtime-schema tests/unit tests/contract tests/component tests/integration tests/features tests/platform tests/architecture tests/release tests/scripts tests/scale/browser-soak.contract.test.ts --coverage --maxWorkers=4 --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/coverage.xml && node scripts/check-risk-coverage.ts",
"check:coverage:fixture": "node scripts/check-risk-coverage.ts --summary tests/fixtures/coverage/below-threshold.json --artifact artifacts/quality/risk-coverage-fixture.json",
"test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:contract && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature && corepack pnpm test:platform && corepack pnpm check:release-coherence && corepack pnpm test:recipes",
"verify:lockfile": "corepack pnpm install --frozen-lockfile --ignore-scripts",
@@ -103,7 +103,7 @@
"check:optional-recipes:source": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipes.ts",
"check:optional-recipe-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipe-fixtures.ts",
"check:registries": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts",
"check:registries:structure": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --no-baseline",
"update:registry-baseline": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --no-baseline --artifact artifacts/quality/registry-current-snapshot.json && node scripts/update-registry-baseline.ts",
"check:registries:compatibility-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-registry-compatibility-fixtures.ts",
"check:registries:baseline-fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
@@ -120,6 +120,7 @@
"generate:ci-workflow": "node scripts/generate-ci-workflow.ts",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
"check:ci": "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow",
"update:ci-contract-baseline": "node scripts/update-ci-contract-baseline.ts",
"verify:documentation": "node scripts/generate-product-feature-index.ts && node scripts/verify-documentation-readiness.ts",
"build:app-only": "node scripts/generate-product-feature-index.ts && vite build && node scripts/generate-build-manifest.ts",
"generate:contract-set": "node scripts/generate-product-feature-index.ts && node scripts/generate-contract-set.ts",
+1
View File
@@ -2,6 +2,7 @@ import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/e2e",
forbidOnly: true,
outputDir: "./artifacts/tests/e2e/results",
reporter: [
["list"],
+1
View File
@@ -2,6 +2,7 @@ import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/storybook",
forbidOnly: true,
outputDir: "./artifacts/tests/storybook/results",
reporter: [
["list"],

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