Merge branch 'fix/maturity-review-2026-09-25' into main

2026-09-25 성숙도 리뷰 전 항목 반영 (v0.2.0).

- 레인 A~M과 검증 후 보완 레인 R·S·T, fix/session-subject-required 포함
- 발견 142건(중복 합쳐 138건) 해결. 01-06은 사용자 결정으로 상한만 반영
- 사용자 몫 U-1~U-5, F-11은 남음
- 상세: docs/reviews/2026-09-25-maturity-review/README.md 10·11절, CHANGELOG.md 0.2.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-28 01:23:31 +09:00
co-authored by Claude Opus 5.5
457 changed files with 27127 additions and 4917 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)
### 알려진 제한
- WebKit이 이 저장소를 검증한 호스트에서 시스템 라이브러리 부족으로 실행되지 않았다. `production-csp`, `old-tab-chunk-recovery`, `boot-module-failure` spec은 chromium·firefox에서만 확인했다.
- 사용자 몫(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
+97 -33
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
@@ -49,45 +45,113 @@ remain opaque to the application and presentation layers.
- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
- missing/invalid external owner: fails closed as `integration-failed`
An external owner implements `readState`, `subscribe`, `beginSignIn`,
`signOut`, `attachCredential`, `recoverSession`, and
`notifyUnauthenticated`. It owns token acquisition and storage.
An external owner implements `readState`, `readSubject`, `subscribe`,
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and
`notifyUnauthenticated`. It owns token acquisition and storage. An owner that
lacks any of these methods is rejected, and the session fails closed as
`integration-failed`.
The owner may also implement `readSubject()`. The server-state cache is cleared
only when the session state or the subject changes, so a token refresh for the
same user keeps cached data. `readSubject()` must return:
`readSubject()` is required. The server-state cache is cleared only when the
session state or the subject changes, so a token refresh for the same user
keeps cached data. `readSubject()` must return:
- an opaque, non-empty string that stays the same for one user across token
refreshes and differs between users, such as a hashed account id
refreshes and differs between users: the OIDC `sub` claim, Supabase
`session.user.id`, or Firebase `user.uid`
- `null` when nobody is signed in
- never an access token, refresh token, or any other credential
Without `readSubject()` (or when it returns `null` or `""` while
authenticated), the runtime cannot tell a refresh from an account switch, so
every notification from an authenticated owner clears server state. This is the
safe default. The `demo` adapter reports one fixed demo user as its subject.
If `readSubject()` returns `null` or `""` while the owner reports
`authenticated`, the runtime cannot tell a refresh from an account switch. It
fails closed: every such notification clears server state, and each one records
the `cache.operation.failed` diagnostic with `operation: SCOPE_FENCE` and
`reason: SUBJECT_MISSING`. Seeing that diagnostic means the owner is not
reporting its subject. The `demo` adapter reports one fixed demo user as its
subject.
Migration: `readSubject()` used to be optional. An owner written for an earlier
release must add it; without it the owner is rejected at startup (the session
becomes `integration-failed`) and a TypeScript owner no longer compiles
against `ExternalSessionOwner`. A code path that implements `AuthSessionPort`
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,406 @@
# 템플릿 성숙도 리뷰 — 전체 종합 (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`에 둔다.
- 브라우저 검증 범위: Playwright spec은 chromium·firefox에서 돌렸다. 검증한 호스트에 WebKit 시스템 라이브러리(libevent, libavif)가 없어 WebKit 결과는 없다. 해당 spec은 `production-csp`, `old-tab-chunk-recovery`, `boot-module-failure` 등이다.
- 로컬에서 확인할 수 없는 것: 13-03의 production 단계 archive 다운로드와 12-01의 CI 실행은 Gitea runner에서 확인해야 한다(U-1).
- 사용자 몫: U-1~U-5, F-11(SBOM의 `scheduler@0.27.0` 분류, 의존성 기준선 재승인).
- 리뷰 범위 밖에서 확인한 것: `check:remediation-ledger`는 `4626b73`에서도 실패한다(2026-09-18 리팩터링 뒤 테스트 마커와 예산 문구가 원장과 어긋남). `config/ci/ungated-scripts.json`에 이유를 적어 두었다.
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"],
+1
View File
@@ -2,6 +2,7 @@ import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/visual",
forbidOnly: true,
snapshotDir: "./tests/visual/__snapshots__",
outputDir: "./artifacts/tests/visual/results",
reporter: [
+10
View File
@@ -1,6 +1,16 @@
# 13-09. pnpm 11 ignores these keys in .npmrc (`pnpm config list` did not show
# them), so an unsupported Node version installed and new dependencies were
# saved with a ^ range. pnpm 11 reads its settings from this file.
engineStrict: true
saveExact: true
allowBuilds:
esbuild: true
msw: true
# 12-07. These exact pins were added on 2026-07-25 (946cf40, f3e105f) while
# they were younger than pnpm's minimum release age. An exclusion covers that
# exact version only, so a later version is checked again. Owner:
# frontend-platform. Revisit: remove an entry when its version is bumped or is
# older than the configured minimum release age.
minimumReleaseAgeExclude:
- '@playwright/test@1.62.0'
- playwright-core@1.62.0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"schemaVersion": 2,
"appVersion": "0.1.0",
"appVersion": "0.2.0",
"buildId": "local-build",
"commitSha": "local",
"configSchemaVersion": "2.0",
@@ -0,0 +1,137 @@
import {
createIndexedDbRuntime,
type IndexedDbRuntimeDependencies,
} from "../../src/adapters/storage/indexeddb/index.ts";
import type { IndexedDbDatasetScope } from "../../src/application/ports/browser-file-storage/index.ts";
import {
createIndexedDbRepositoryProvider,
type IndexedDbRepositoryProvider,
} from "../../src/features/feature-adapter-contribution.ts";
import type {} from "../../src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts";
import type { LocalDraft } from "../../src/features/local-draft-feature/domain/local-draft.ts";
type LocalDraftRuntimeDependencies = IndexedDbRuntimeDependencies<
LocalDraft,
LocalDraft,
never
>;
type LocalDraftRuntime = ReturnType<
typeof createIndexedDbRuntime<LocalDraft, LocalDraft, never>
>;
/**
* 09-05. How a host builds the `indexedDb` feature capability, shown for the
* local-draft sample. IndexedDB is an opt-in reference runtime
* (`offline-indexeddb` in config/recipes/frontend-capability-recipes.json,
* `productionComposition: false`), so `src/bootstrap/runtime-adapters.ts` does
* not build it. A product that installs a feature with `needs: ["indexedDb"]`
* copies this into its composition, replaces the codec, migrations and storage
* policy with its own decisions, and adds `indexedDb` to the feature
* capabilities there; until it does, that object fails the app typecheck and
* `composeFeatureAdapterInputs` names the missing capability.
*
* The scope tokens come from the product's storage registry and the lifecycle
* authority from its composition root; neither is invented here.
*/
export function createLocalDraftIndexedDbCapability(
options: Readonly<{
// The sample keeps drafts across sign-out, so its dataset is origin-shared.
scope: IndexedDbDatasetScope & Readonly<{ accountScope: "ORIGIN_SHARED" }>;
authorizeLifecycle: LocalDraftRuntimeDependencies["authorizeLifecycle"];
/** Defaults to the browser's `indexedDB`; tests pass an in-memory one. */
factory?: IDBFactory;
}>,
): Readonly<{
indexedDb: IndexedDbRepositoryProvider;
/** Opens (and migrates) the database; repository calls fail until it has. */
open(signal?: AbortSignal): ReturnType<LocalDraftRuntime["open"]>;
close(): void;
}> {
const runtime = createIndexedDbRuntime<LocalDraft, LocalDraft, never>({
...(options.factory === undefined ? {} : { factory: options.factory }),
scope: options.scope,
storagePolicy: Object.freeze({
owner: "local-draft-feature",
namespace: "local-draft",
classification: "INTERNAL",
authority: "LOCAL_FIRST",
accountScope: "ORIGIN_SHARED",
retention: Object.freeze({ kind: "EXPLICIT_DELETE" }),
softBudgetBytes: 1_000_000,
hardBudgetBytes: 2_000_000,
evictionPriority: "USER_AUTHORED",
logoutAction: "KEEP_ORIGIN_SHARED",
accountDeletionAction: "KEEP_ORIGIN_SHARED",
pressureAction: "RETAIN",
unavailableFallback: "READ_ONLY",
}),
schemaVersion: 1,
recordStore: "records",
governanceStore: "governance",
retentionStore: "retention",
retentionEligibilityIndex: "by-eligibility",
lifecycleMetadataStores: [],
idempotencyStore: "receipts",
idempotencyExpiryIndex: "by-expiry",
receiptRetentionMs: 60_000,
maxIdempotencyReceipts: 100,
migrations: [
{
id: "local-draft-schema-v1",
fromVersion: 0,
toVersion: 1,
operations: [
{ kind: "CREATE_STORE", name: "governance", keyPath: "bindingKey" },
{
kind: "CREATE_STORE",
name: "retention",
keyPath: "recordKey",
indexes: [{ name: "by-eligibility", keyPath: "eligibleAtEpochMs" }],
},
{ kind: "CREATE_STORE", name: "records", keyPath: "key" },
{
kind: "CREATE_STORE",
name: "receipts",
keyPath: "idempotencyKey",
indexes: [{ name: "by-expiry", keyPath: "expiresAtEpochMs" }],
},
],
},
],
codec: {
currentVersion: 1,
encode: (value) => ({ ok: true, value }),
measureStoredBytes: (value) =>
new TextEncoder().encode(JSON.stringify(value)).byteLength,
decode: (version, value) => {
if (version !== 1 || value === null || typeof value !== "object") {
return { ok: false };
}
const candidate = value as Partial<LocalDraft>;
return typeof candidate.draftId === "string" &&
typeof candidate.title === "string" &&
typeof candidate.body === "string"
? { ok: true, value: candidate as LocalDraft }
: { ok: false };
},
fingerprint: async (value) => {
const bytes = new TextEncoder().encode(
JSON.stringify([value.draftId, value.title, value.body]),
);
const digest = await crypto.subtle.digest("SHA-256", bytes);
return Array.from(new Uint8Array(digest), (byte) =>
byte.toString(16).padStart(2, "0"),
).join("");
},
},
queryPolicy: { plan: () => ({ limit: 1 }) },
authorizeLifecycle: options.authorizeLifecycle,
});
return Object.freeze({
indexedDb: createIndexedDbRepositoryProvider(
Object.freeze({ "local-draft": runtime }),
),
open: (signal?: AbortSignal) => runtime.open(signal),
close: () => runtime.close(),
});
}
+25 -7
View File
@@ -1,8 +1,11 @@
import { spawnSync } from "node:child_process";
import { rm } from "node:fs/promises";
import { rm, writeFile } from "node:fs/promises";
import process from "node:process";
import { SERVICE_WORKER_SCRIPT_PATH } from "../src/contracts/service-worker.ts";
import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtime-capabilities.ts";
import { makeDistFilesPublic } from "./lib/dist-permissions.ts";
import { SELF_UNREGISTERING_SERVICE_WORKER } from "./lib/self-unregistering-service-worker.ts";
/**
* §17.2.2. Deterministic two-pass build.
@@ -16,16 +19,22 @@ import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtim
* 4. materialize dist/config.json from the declared APP_PROFILE
* 5. scan app dist and generate the static asset source
* 6. ACTIVE only: Vite Service Worker build (emptyOutDir = false)
* REMOVE_REGISTRATION only: write the self-unregistering worker (06-03)
* 7. generate Release Manifest V2 and the build manifest
* 8. make every dist file readable by other users (13-02)
*
* Steps 5 and 6 are skipped for `REMOVE_REGISTRATION`, `PURGE_OWNED_RESOURCES`
* and `null`: those modes never run an active worker build.
* `REMOVE_REGISTRATION` still ships a `service-worker.js` so the browser's
* update check can replace a worker that stops the page from booting (D-5).
*
* Step 4 has to follow the Vite build and precede the asset scan. Vite copies
* `public/` verbatim, so without it every build — including a production one —
* ships the local runtime document; and the Service Worker hashes the emitted
* `config.json`, so the profile must be in place before that inventory is
* taken.
* Step 4 has to follow the Vite build. Vite copies `public/` verbatim, so
* without it every build — including a production one — ships the local
* runtime document. The Service Worker asset scan excludes `config.json`
* (`scripts/generate-service-worker-assets.ts`), so the order against step 5
* is not what keeps the profile out of the worker cache (13-15). Step 6 reads
* the release manifest URL from the `dist/config.json` step 4 wrote, and fails
* if its `APP_ENV` is not `APP_PROFILE` (06-10).
*/
const selection = INSTALLED_RUNTIME_CAPABILITIES.serviceWorker;
@@ -60,11 +69,20 @@ if (buildsActiveWorker) {
run("node", ["scripts/generate-service-worker-assets.ts", "dist"]);
// 6. service worker build
run("npx", ["vite", "build", "--config", "vite.service-worker.config.ts"]);
} else if (selection?.mode === "REMOVE_REGISTRATION") {
// 6. self-unregistering worker in place of the active one
await writeFile(
`dist/${SERVICE_WORKER_SCRIPT_PATH}`,
SELF_UNREGISTERING_SERVICE_WORKER,
);
} else {
process.stdout.write(
`service worker mode ${selection?.mode ?? "null"}: skipping worker build\n`,
);
}
// 6. release + build manifest
// 7. release + build manifest
run("node", ["scripts/generate-build-manifest.ts"]);
// 8. publishable permissions: the validated writer creates 0600 files
await makeDistFilesPublic("dist");
+4 -1
View File
@@ -209,7 +209,10 @@ async function main(): Promise<void> {
// probe 대기가 커널 operation으로 옮겨갔다(R3-2).
// 16 → 15: `browser-files/browser-file-picker.ts`의 native input 대기와
// system picker 대기가 커널 operation으로 옮겨갔다(R3-2).
const HAND_ROLLED_ABORT_CEILING = 15;
// 15 → 13: `storage/opfs/opfs-worker-client.ts`가 커널 abort primitive를 쓰고,
// `storage/indexeddb/indexeddb-governance.ts`의 binding 검증이 커널
// 트랜잭션으로 옮겨갔다(05-07, 05-12).
const HAND_ROLLED_ABORT_CEILING = 13;
const handRolledScan = spawnSync(
"git",
["grep", "-l", 'addEventListener("abort"', "--", "src/adapters"],
+130 -51
View File
@@ -6,11 +6,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
import { createRequire } from "node:module";
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type PathRule = Readonly<{ path?: string; pathNot?: string }>;
type ArchitectureRule = Readonly<{
name: string;
comment?: string;
severity?: string;
from?: PathRule;
to?: PathRule & Readonly<{ circular?: boolean }>;
@@ -53,7 +55,6 @@ type GraphFixtureResult = Readonly<{
failures: string[];
}>;
type DependencyResolution = Readonly<{ path?: string; reason: string }>;
type DependencyCruiserReport = Record<string, unknown>;
type TypeScriptOnlyPolicy = Readonly<{
checkedRoots: readonly string[];
exceptionsAllowed: false;
@@ -111,27 +112,15 @@ function runPnpm(arguments_: string[]) {
});
}
// Keep dependency-cruiser's report and checks. The second graph is authoritative
// for TypeScript 7 coverage because dependency-cruiser 18 cannot parse TS 7 yet.
const dependencyCruiser = runPnpm([
"exec",
"depcruise",
"src",
"--config",
".dependency-cruiser.json",
"--output-type",
"json",
]);
// 12-05 (D-11): this graph is the only architecture checker. dependency-cruiser
// 18 cannot parse TypeScript 7, so it cruised zero modules and still passed.
// .dependency-cruiser.json keeps its name and is read here as the rule file.
const sourceGraph = await analyzeSourceGraph(sourceRoot, "src");
const typeScriptOnlyPolicy = await inspectTypeScriptOnlyPolicy();
const graphFixtureResult = await runGraphFixtureChecks();
const dependencyReport = parseDependencyCruiserReport(dependencyCruiser.stdout);
const graphErrors = blockingViolations(sourceGraph);
const dependencyCruiserReportValid = !(
"dependencyCruiserOutput" in dependencyReport
);
dependencyReport.staticImportGraph = {
const staticImportGraph = {
analyzer: "babel-parser-node-resolver",
modules: sourceGraph.modules,
dependencies: sourceGraph.dependencies,
@@ -162,25 +151,11 @@ dependencyReport.staticImportGraph = {
await writeValidatedJsonArtifact({
path: qualityArtifact,
schema: architectureDependencyReportArtifactSchema,
value: dependencyReport,
value: { staticImportGraph },
});
let architectureFailed = false;
if (!dependencyCruiserReportValid) {
architectureFailed = true;
process.stderr.write("dependency-cruiser returned an invalid JSON report\n");
}
if (dependencyCruiser.status !== 0) {
architectureFailed = true;
process.stderr.write(
(dependencyCruiser.error?.message ?? dependencyCruiser.stderr) ||
dependencyCruiser.stdout ||
"dependency-cruiser failed\n",
);
}
for (const failure of sourceGraph.parseFailures) {
architectureFailed = true;
process.stderr.write(
@@ -197,11 +172,16 @@ for (const dependency of sourceGraph.unresolved) {
for (const violation of graphErrors) {
architectureFailed = true;
const cycle = violation.cycle
? ` (cycle group: ${violation.cycle.join(", ")})`
: "";
process.stderr.write(
`Architecture violation [${violation.rule}]: ${violation.source} -> ${violation.target}${cycle}\n`,
formatArchitectureViolation(
violation,
violation.cycle
? []
: sourceGraph.dependencies
.filter(({ source, target }) => source === violation.source && target === violation.target)
.map(({ specifier }) => specifier),
architectureRules.find(({ name }) => name === violation.rule)?.comment,
),
);
}
@@ -443,7 +423,7 @@ async function importSpecifiers(sourceFile: string): Promise<string[]> {
visitSyntaxNode(syntaxTree, specifiers, nonLiteralModuleLoads);
if (nonLiteralModuleLoads.size > 0) {
throw new Error(
`module loading must use string literals: ${[...nonLiteralModuleLoads].join(", ")}`,
`module loading must name one module with a string literal: ${[...nonLiteralModuleLoads].join(", ")}`,
);
}
for (const comment of syntaxTree.comments ?? []) {
@@ -503,6 +483,17 @@ function visitSyntaxNode(
if (!addStringLiteral(arguments_[0], specifiers)) {
nonLiteralModuleLoads.add("require()");
}
} else if (
nodeType === "CallExpression" &&
syntaxNodeType(node.callee) === "MemberExpression" &&
syntaxNodeType(syntaxNodeProperty(node.callee, "object")) === "MetaProperty" &&
/^glob(?:Eager)?$/u.test(
String(syntaxNodeProperty(syntaxNodeProperty(node.callee, "property"), "name")),
)
) {
// 12-06: a glob pulls in every matching module without naming one, so no
// edge rule can see it. Refuse it like a non-literal import().
nonLiteralModuleLoads.add("import.meta.glob()");
} else if (nodeType === "TSExternalModuleReference") {
addStringLiteral(node.expression, specifiers);
} else if (nodeType === "TSImportType") {
@@ -831,6 +822,7 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
cycleGraph,
barrelGraph,
crossBoundaryGraph,
importBoundaryGraph,
] = await Promise.all([
analyzeSourceGraph(allowedRoot, "src"),
analyzeSourceGraph(resolve(fixtureRoot, "unresolved"), "src"),
@@ -838,6 +830,7 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
analyzeSourceGraph(resolve(fixtureRoot, "cycle"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "barrel"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "cross-boundary"), "src"),
analyzeSourceGraph(resolve(fixtureRoot, "import-boundaries"), "src"),
]);
const allowedFiles = new Set(await listFiles(allowedRoot));
const allowedSourceFile = resolve(
@@ -876,6 +869,82 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
target === "src/contexts/admin/value.ts",
),
},
{
name: "feature root re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "feature-and-app-roots-do-not-reach-adapters" &&
source === "src/features/alpha/telemetry.ts" &&
target === "src/adapters/telemetry/index.ts",
),
},
{
name: "context re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "feature-and-app-roots-do-not-reach-adapters" &&
source === "src/contexts/customer/telemetry.ts" &&
target === "src/adapters/telemetry/index.ts",
),
},
{
name: "presentation import of a context is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "presentation-does-not-import-apps-or-contexts" &&
source === "src/presentation/read-context.ts" &&
target === "src/contexts/customer/telemetry.ts",
),
},
// 12-08 / 12-10: these import rules used to be regular expressions in
// check-design-system.ts and realtime-boundaries.ts beside the graph.
{
name: "design-system deep import is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source }) =>
rule === "design-system-is-reached-through-its-index" &&
source === "src/presentation/pages/deep-import.ts",
),
},
{
name: "design-system index and named facades are accepted",
passed: !blockingViolations(importBoundaryGraph).some(({ source }) =>
["src/presentation/pages/public-import.ts", "src/presentation/components/ui/button.ts"].includes(source),
),
},
{
name: "direct icon vendor import is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source, target }) =>
rule === "icon-vendor-is-facade-only" &&
source === "src/presentation/pages/direct-icon.ts" &&
target === "lucide-react",
),
},
// F-7 (13-08): zod must be configured jitless before any schema is built.
{
name: "direct zod import outside src/contracts/zod.ts is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source, target }) =>
rule === "zod-is-reached-through-contracts-zod" &&
source === "src/presentation/pages/direct-zod.ts" &&
target === "zod",
),
},
{
name: "zod through src/contracts/zod.ts is accepted",
passed: !blockingViolations(importBoundaryGraph).some(({ source }) =>
["src/contracts/zod.ts", "src/presentation/pages/wrapped-zod.ts"].includes(source),
),
},
{
name: "unselected realtime runtime composition is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source }) =>
rule === "unselected-realtime-runtime-is-not-composed" &&
source === "src/bootstrap/compose-realtime.ts",
),
},
{
name: "deep adapter import from outside the group is rejected",
passed: blockingViolations(barrelGraph).some(
@@ -885,6 +954,21 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
target === "src/adapters/http/client.ts",
),
},
{
name: "second-level index import from outside the group is rejected",
passed: blockingViolations(barrelGraph).some(
({ rule, source, target }) =>
rule === "adapter-groups-are-reached-through-their-barrel" &&
source === "src/bootstrap/compose-sub-barrel.ts" &&
target === "src/adapters/http/internals/index.ts",
),
},
{
name: "storage runtime sub-barrel import is accepted",
passed: !blockingViolations(barrelGraph).some(
({ source }) => source === "src/bootstrap/compose-storage-sub-barrel.ts",
),
},
{
name: "barrel import from outside the group is accepted",
passed: !blockingViolations(barrelGraph).some(
@@ -954,6 +1038,14 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
reason.includes("import()"),
),
},
{
name: "import.meta.glob module loads are rejected",
passed: unresolvedGraph.parseFailures.some(
({ source, reason }) =>
source === "src/application/glob-value.ts" &&
reason.includes("import.meta.glob"),
),
},
{
name: "non-literal CommonJS imports are rejected",
passed: unresolvedGraph.parseFailures.some(
@@ -1099,6 +1191,7 @@ function parseArchitectureConfig(value: unknown): ArchitectureConfig {
function isArchitectureRule(value: unknown): value is ArchitectureRule {
if (!isRecord(value) || typeof value.name !== "string") return false;
if (value.comment !== undefined && typeof value.comment !== "string") return false;
if (value.severity !== undefined && typeof value.severity !== "string") {
return false;
}
@@ -1124,17 +1217,3 @@ function isPathRule(value: unknown, allowCircular: boolean): value is PathRule {
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value && typeof value === "object" && !Array.isArray(value));
}
function parseDependencyCruiserReport(
output: string,
): DependencyCruiserReport {
try {
const report: unknown = JSON.parse(output);
if (!report || typeof report !== "object" || Array.isArray(report)) {
throw new Error("dependency-cruiser report must be a JSON object");
}
return report as DependencyCruiserReport;
} catch {
return { summary: { errors: 1 }, dependencyCruiserOutput: output };
}
}
+60 -10
View File
@@ -1,4 +1,5 @@
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import {
@@ -7,10 +8,15 @@ import {
type GateResult,
} from "./lib/promotion-readiness.ts";
import {
CANONICAL_GATE_IDS,
loadCiGateContract,
indexCiGateContract,
} from "./contracts/ci-gates.ts";
import { generateCiWorkflow, renderCiWorkflow } from "./generate-ci-workflow.ts";
import {
generateCiWorkflow,
renderCiWorkflow,
workflowGateExecutionFailures,
} from "./generate-ci-workflow.ts";
import {
ciContractReportSchema,
} from "./lib/ci-contract-report.ts";
@@ -18,12 +24,21 @@ import {
validateInstallScriptPolicy,
validatePackageScriptGraph,
} from "./lib/package-script-graph.ts";
import {
gatedTestPaths,
listTestFiles,
parseUngatedTestExclusions,
ungatedTestFailures,
UNGATED_TESTS_PATH,
} from "./lib/ungated-tests.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "./lib/ungated-scripts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const removalFixtureMode = process.argv.includes("--reduced-removal-fixture");
const contract = await loadCiGateContract(process.cwd(), {
mode: removalFixtureMode ? "removal-fixture" : "canonical",
});
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
const [packageDocument, nodeVersion] = await Promise.all([
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
@@ -63,6 +78,43 @@ failures.push(
),
);
// 12-04: every test file runs in a gate, or config/ci/ungated-tests.json says why not.
try {
failures.push(
...ungatedTestFailures({
testFiles: await listTestFiles(process.cwd()),
gatedPaths: gatedTestPaths(
packageScripts,
contract.commands.map(({ script }) => script),
(file) => readFileSync(file, "utf8"),
),
exclusions: parseUngatedTestExclusions(
JSON.parse(await readFile(UNGATED_TESTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04: every verification package script is reached by a gate, or
// config/ci/ungated-scripts.json says why not.
try {
const entryScripts = contract.commands.map(({ script }) => script);
failures.push(
...ungatedScriptFailures({
scripts: packageScripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
const immutable = index.gates.get("FE-GATE-015");
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
if (JSON.stringify(immutableCommands) !== JSON.stringify(["build:release-candidate", "verify:local-evidence"])) {
@@ -76,10 +128,7 @@ if (!architecture?.evidenceArtifactIds.some((id) => index.artifacts.get(id)?.pat
failures.push("FE-GATE-010 must publish the typed CI contract report");
}
const expectedGateIds = Array.from(
{ length: 27 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
const expectedGateIds = CANONICAL_GATE_IDS;
const passingResults: Record<string, GateResult> = Object.fromEntries(
expectedGateIds.map((gateId) => [gateId, "PASS"]),
);
@@ -116,6 +165,7 @@ try {
} catch (error) {
failures.push(`generated workflow is unreadable: ${error instanceof Error ? error.message : String(error)}`);
}
failures.push(...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8")));
const report = ciContractReportSchema.parse({
schemaVersion: 2,
nodeVersion,
@@ -139,4 +189,4 @@ if (failures.length > 0) {
process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write("CI contract: 27 gates, strict v2 graph and generated workflow model PASS\n");
process.stdout.write(`CI contract: ${CANONICAL_GATE_IDS.length} gates, strict v2 graph and generated workflow model PASS\n`);
+55 -26
View File
@@ -1,53 +1,72 @@
import { mkdir, readFile } from "node:fs/promises";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { classifyObjectSchemaChange } from "../src/contracts/compatibility.ts";
import { z } from "zod";
import {
classifyObjectSchemaChange,
type ObjectSchemaShape,
type SchemaChangeClassification,
} from "../src/contracts/compatibility.ts";
import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts";
import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type CompatibilitySchema = Readonly<{
required?: readonly string[];
properties?: Readonly<Record<string, unknown>>;
}>;
type CompatibilityFixture = Readonly<{
before: CompatibilitySchema;
after: CompatibilitySchema;
}>;
// FE-GATE-014 (07-02, 13-10). The committed baseline stands in for the schema
// the previous release's reader accepts; the current schema is exactly what
// the build writes to dist/runtime-config.schema.json.
const BASELINE_PATH = "config/compatibility/runtime-config.schema.baseline.json";
type CompatibilityFixtures = Readonly<{
families: Readonly<
Record<string, Readonly<Record<"additive" | "breaking", CompatibilityFixture>>>
>;
cases: readonly Readonly<{
id: string;
expected: SchemaChangeClassification;
before: ObjectSchemaShape;
after: ObjectSchemaShape;
}>[];
}>;
const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema);
if (process.argv.includes("--update-baseline")) {
await writeFile(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
process.stdout.write(`Updated ${BASELINE_PATH}\n`);
process.exit(0);
}
const fixtures = JSON.parse(
await readFile("config/compatibility/fixtures.json", "utf8"),
) as CompatibilityFixtures;
const results = [];
const results = fixtures.cases.map(({ id, expected, before, after }) => {
const actual = classifyObjectSchemaChange(before, after);
return { id, expected, actual, passed: actual === expected };
});
for (const [family, cases] of Object.entries(fixtures.families)) {
for (const expected of ["additive", "breaking"] as const) {
const fixture = cases[expected];
const actual = classifyObjectSchemaChange(fixture.before, fixture.after);
results.push({ family, expected, actual, passed: actual === expected });
}
}
const baselineClassification = classifyObjectSchemaChange(
JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ObjectSchemaShape,
current as ObjectSchemaShape,
);
const baseline = {
path: BASELINE_PATH,
classification: baselineClassification,
passed: baselineClassification !== "breaking",
};
await mkdir("artifacts/release", { recursive: true });
await writeValidatedJsonArtifact({
path: "artifacts/release/compatibility.json",
schema: compatibilityFixturesArtifactSchema,
value: {
schemaVersion: 1,
schemaVersion: 2,
generatedAt: new Date().toISOString(),
rules: [
"additive changes preserve required fields",
"breaking changes require version bump and migration, discard, fallback, or rollback",
"a change is additive only when it adds a property under a reader that tolerates unknown keys",
"type, enum, nullable, required-set and unmodelled changes are breaking (fail-closed)",
"adding a field at a strict (REJECT_UNKNOWN) boundary is breaking: deploy the reader first",
"config and API major versions must match",
"incompatible persisted cache is discarded by default",
"rollback uses a coherent compatibility tuple",
],
results,
baseline,
},
});
@@ -55,4 +74,14 @@ if (results.some((result) => !result.passed)) {
process.stderr.write("Compatibility fixture classification failed.\n");
process.exit(1);
}
process.stdout.write("Compatibility fixtures: PASS\n");
if (!baseline.passed) {
process.stderr.write(
`Runtime config schema change is breaking for readers of ${BASELINE_PATH}.\n` +
"Follow docs/contracts/compatibility.md (deploy readers first), then run\n" +
"`corepack pnpm verify:compatibility --update-baseline` and commit the baseline.\n",
);
process.exit(1);
}
process.stdout.write(
`Compatibility fixtures: PASS; runtime config schema vs baseline: ${baseline.classification}\n`,
);
+4 -12
View File
@@ -97,22 +97,14 @@ const sources = fixtureMode
: await listSourceFiles("src");
for (const file of sources) {
const source = await readFile(file, "utf8");
const vendorFacade =
file === "src/presentation/design-system/icons/vendors/lucide.tsx";
if (!vendorFacade && /from\s+["']lucide-react["']/.test(source)) {
failures.push(`direct icon vendor import in ${file}`);
}
// Icon vendor and design-system deep imports are graph rules in
// .dependency-cruiser.json (check:architecture), which also sees relative,
// dynamic and type imports (12-08, 12-10).
if (
/from\s+["'](?:react-aria-components|@radix-ui\/[^"']+)["']/.test(source)
) {
failures.push(`direct headless vendor import in ${file}`);
}
if (
!file.includes("src/presentation/design-system/") &&
/presentation\/design-system\/(?!index(?:\.tsx?)?["'])/.test(source)
) {
failures.push(`design-system deep import in ${file}`);
}
if (
!file.includes("src/presentation/design-system/tokens/") &&
/(?:#[0-9a-f]{3,8}\b|oklch\(|rgba?\()/i.test(source)
@@ -151,5 +143,5 @@ if (failures.length > 0) {
process.exit(1);
}
process.stdout.write(
`Design system contract: ${report.checkedTokenCount} tokens and vendor boundaries PASS\n`,
`Design system contract: ${report.checkedTokenCount} tokens and headless vendor boundary PASS\n`,
);
+2
View File
@@ -33,6 +33,7 @@ const telemetryProducerFiles: Readonly<Record<string, string>> = {
"api.request.failed": "src/adapters/http/client.ts",
"ui.render.failed": "src/application/create-application.ts",
"release.mismatch.detected": "src/application/create-application.ts",
"service-worker.start.failed": "src/bootstrap/optional-runtime-host.ts",
"telemetry.delivery.dropped":
"src/adapters/telemetry/best-effort-telemetry.ts",
};
@@ -47,6 +48,7 @@ const diagnosticProducerFiles: Readonly<Record<string, string>> = {
"ui.render.failed": "src/application/create-application.ts",
"release.mismatch.detected": "src/application/create-application.ts",
"telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.ts",
"feature.override.unknown": "src/bootstrap/runtime-adapters.ts",
};
for (const key of DIAGNOSTIC_CONTEXT_ALLOWLIST) {
+43 -5
View File
@@ -52,20 +52,45 @@ if (!fixtureMode) {
}
}
// 08-04. Screen code under these directories must take its words from the
// catalog. `src/presentation/examples` is the component gallery and stays out
// of scope on purpose. Fixture mode runs the same discovery on a fixture tree.
const sourceRoot = fixtureMode ? "tests/fixtures/i18n/forbidden" : ".";
const commonDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
"src/presentation/design-system",
"src/presentation/forms",
"src/presentation/layouts",
"src/presentation/pages",
"src/presentation/routes",
"src/presentation/templates",
];
const sources = fixtureMode
? await listSourceFiles("tests/fixtures/i18n/forbidden")
: (
await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
).flat();
async function featurePresentationDirectories(root: string): Promise<string[]> {
const features = path.join(root, "src/features");
const entries = await readdir(features, { withFileTypes: true }).catch(
() => [],
);
return entries
.filter((entry) => entry.isDirectory())
.map((entry) => path.join("src/features", entry.name, "presentation"));
}
async function existingSourceFiles(directory: string): Promise<string[]> {
return listSourceFiles(directory).catch((error: NodeJS.ErrnoException) => {
if (error.code === "ENOENT") return [];
throw error;
});
}
const sourceDirectories = [
...commonDirectories,
...(await featurePresentationDirectories(sourceRoot)),
].map((directory) => path.join(sourceRoot, directory));
const sources = (
await Promise.all(sourceDirectories.map(existingSourceFiles))
).flat();
for (const file of sources) {
const source = await readFile(file, "utf8");
@@ -98,6 +123,19 @@ await writeValidatedJsonArtifact({
value: report,
});
// Every fixture file must be rejected on its own; one rejected file must not
// hide a directory the discovery above stopped reaching.
const fixtureFiles = fixtureMode ? await listSourceFiles(sourceRoot) : [];
const unrejectedFixtures = fixtureFiles.filter(
(file) => !failures.some((failure) => failure.endsWith(file)),
);
if (fixtureMode && (fixtureFiles.length === 0 || unrejectedFixtures.length > 0)) {
process.stderr.write(
`I18n fixture was not rejected:\n${unrejectedFixtures.join("\n") || "(no fixture files found)"}\n`,
);
process.exit(2);
}
if (failures.length > 0) {
process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
@@ -13,7 +13,6 @@ const forbiddenOutput = `${forbidden.stdout}${forbidden.stderr}`;
const expectedRules = [
"NATIVE_REALTIME_API_OUTSIDE_ADAPTER",
"PRESENTATION_INTERVAL_OWNER",
"UNSELECTED_REALTIME_RUNTIME_COMPOSED",
] as const;
if (
+26 -1
View File
@@ -330,6 +330,27 @@ function projectSnapshotRows(
});
}
/**
* 09-07. `src/features/*\/adapters` names that directory in every feature, so
* adding a feature does not mean adding it to this governance file.
*/
async function expandDirectoryPattern(pattern: string): Promise<string[]> {
const star = pattern.split("/").indexOf("*");
if (star === -1) return [pattern];
const segments = pattern.split("/");
const parent = segments.slice(0, star).join("/");
const rest = segments.slice(star + 1).join("/");
const entries = await readdir(parent, { withFileTypes: true }).catch(() => []);
const expanded = await Promise.all(
entries
.filter((entry) => entry.isDirectory())
.map((entry) =>
expandDirectoryPattern(path.join(parent, entry.name, rest)),
),
);
return expanded.flat();
}
async function filesBelow(directory: string): Promise<string[]> {
try {
const entries = await readdir(directory, { withFileTypes: true });
@@ -548,7 +569,11 @@ for (const specification of governance.registries) {
if (specification.consumerIdentityField) {
const consumerFiles = (
await Promise.all(
(specification.consumerDirectories ?? []).map(filesBelow),
(await Promise.all(
(specification.consumerDirectories ?? []).map(expandDirectoryPattern),
))
.flat()
.map(filesBelow),
)
).flat();
const sourcePath = sourcesByRegistry.get(specification.registryId);
+26
View File
@@ -7,7 +7,9 @@ import {
isDeploymentTarget,
type AdmissionInput,
} from "../src/contracts/deployment-admission.ts";
import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts";
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts";
/**
* §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not
@@ -40,6 +42,17 @@ async function main(): Promise<void> {
process.exitCode = 1;
return;
}
// 13-01: the build profile and the admission target are separate repository
// variables; a profile left on staging must not ship to production.
const profile = process.env["APP_PROFILE"];
if (profile !== undefined && profile !== declared) {
process.stderr.write(
`release admission refused: the artifact was built with APP_PROFILE=${profile} ` +
`but RELEASE_TARGET=${declared}. Set both to the same environment.\n`,
);
process.exitCode = 1;
return;
}
let document: unknown;
try {
@@ -68,6 +81,18 @@ async function main(): Promise<void> {
}
const violations = findAdmissionViolations(declared, config);
// 09-09. Inert by design (a shared document may name another build's
// features), so this warns instead of refusing.
const warnings = unknownProductFeatureOverrides(
COMPILED_PRODUCT_FEATURE_IDS,
"FEATURE_OVERRIDES" in config ? config.FEATURE_OVERRIDES : undefined,
).map((featureId) => ({
field: `FEATURE_OVERRIDES.${featureId}`,
reason: `names no feature this build declares (${COMPILED_PRODUCT_FEATURE_IDS.join(", ") || "none"}); the override does nothing`,
}));
for (const warning of warnings) {
process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`);
}
await mkdir("artifacts/release", { recursive: true });
await writeFile(
RECORD_PATH,
@@ -82,6 +107,7 @@ async function main(): Promise<void> {
releaseId: config.RELEASE_ID ?? null,
status: violations.length === 0 ? "ADMITTED" : "REFUSED",
violations,
warnings,
},
null,
2,
+1 -1
View File
@@ -1,4 +1,4 @@
import { access, readFile } from "node:fs/promises";
import { readFile } from "node:fs/promises";
/**
* GOV-03. Joins the machine-readable remediation dispositions against the prose
@@ -41,7 +41,10 @@ import {
releaseCandidateManifestSchema,
} from "./lib/release-candidate.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
import { linkFixtureNodeModules } from "./lib/fixture-node-modules.ts";
import {
FIXTURE_PNPM_ENVIRONMENT,
linkFixtureNodeModules,
} from "./lib/fixture-node-modules.ts";
const repositoryRoot = process.cwd();
const fixtureRoot = await mkdtemp(path.join(tmpdir(), "provider-exact-five-fixture-"));
@@ -74,6 +77,7 @@ try {
maxBuffer: 32 * 1024 * 1024,
env: {
...process.env,
...FIXTURE_PNPM_ENVIRONMENT,
CI: "true",
VITE_BUILD_ID: "provider-exact-five-fixture",
VITE_COMMIT_SHA: revision,
@@ -249,6 +253,31 @@ try {
},
nowEpochMs: () => now,
} as const;
// 13-04: the same bundle three hours later. Current freshness refuses the
// expired provider evidence; archived freshness accepts it at the recorded
// promotion time, and still refuses a tampered archive.
const threeHoursLater = now + 3 * 60 * 60 * 1_000;
const archivedAfterWindow = await captureRejection(async () => {
await verifyExactPromotionBundle(exactFiles, {
...bundleTrust,
nowEpochMs: () => threeHoursLater,
freshness: "archived",
});
});
const currentAfterWindow = await captureRejection(async () => {
await verifyExactPromotionBundle(exactFiles, {
...bundleTrust,
nowEpochMs: () => threeHoursLater,
});
});
const tamperedArchive = Buffer.from(exactFiles["release-candidate.tar.gz"]);
tamperedArchive[tamperedArchive.length - 1] ^= 0xff;
const archivedTampered = await captureRejection(async () => {
await verifyExactPromotionBundle(
{ ...exactFiles, "release-candidate.tar.gz": tamperedArchive },
{ ...bundleTrust, nowEpochMs: () => threeHoursLater, freshness: "archived" },
);
});
const absentFiles = { ...exactFiles } as Partial<typeof exactFiles>;
delete absentFiles["provider-verification.json"];
const absent = await captureRejection(async () => {
@@ -282,7 +311,8 @@ try {
await captureCiCandidateArchive({ archivePath, expectedSha256: "0".repeat(64) });
});
const passed =
validImmutable && absent.rejected && invalidTar.rejected && wrongDigest.rejected;
validImmutable && absent.rejected && invalidTar.rejected && wrongDigest.rejected &&
!archivedAfterWindow.rejected && currentAfterWindow.rejected && archivedTampered.rejected;
await cleanupFinalizedPromotion({
runnerTempRoot,
stagingRoot: finalized.stagingRoot,
@@ -314,12 +344,24 @@ try {
status: invalidTar.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [invalidTar.failure],
},
archivedAfterWindow: {
status: archivedAfterWindow.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: archivedAfterWindow.rejected ? [archivedAfterWindow.failure] : [],
},
currentAfterWindow: {
status: currentAfterWindow.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [currentAfterWindow.failure],
},
archivedTampered: {
status: archivedTampered.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [archivedTampered.failure],
},
},
externalTreeCanary: {
status: validImmutable ? "PASS" : "FAIL_UNVERIFIED",
failures: validImmutable ? [] : ["external tree canary influenced captured archive"],
},
passingFixtureCount: validImmutable ? 1 : 0,
passingFixtureCount: (validImmutable ? 1 : 0) + (archivedAfterWindow.rejected ? 0 : 1),
status: passed ? "PASS" : "FAIL",
},
});

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