chore: sync the frontend template from ebea300 to af3d8e6

Carries 359 template commits, tag v0.2.0 plus one documentation commit: the
generator-built feature index with its app, bounded-context and feature
declarations, the src/platform kernel and scale tooling, the 2026-09-24 src
review fixes, and the 2026-09-25 maturity review round with its CHANGELOG
[보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them
merged with product changes; 127 are not carried.

Product identity is unchanged: name, version 0.1.0, routes, design and the
TechLog domain.

Three decisions worth naming. TechLog stays composed directly, as the last
two syncs recorded; its directory carries a NOT_INSTALLED marker that says so,
and every installed-* composer takes the template's projection with TechLog
added on top. The reference sample is no longer installed: the template now
installs a feature only through feature-module.ts and context-routes.ts,
which load the screens this product deleted, so its three operations, six
schemas and one topic leave the registries, recorded as registry change
evidence. And AppRouter mounts the platform and TechLog routes only; the
template's bounded-context route gateway waits for a generator-installed
feature.

Required fixes: readSubject on the BFF session owner (without it every HTTP
Studio session would close as integration-failed), zod through the facade in
nine TechLog files, noUnusedLocals, and public/config.json written out to
match the local profile. Derived baselines were recomputed after reproducing
both sides' values: CI contract 101 commands / 106 references / 141
artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime
config schema baseline equals the schema at 8210d48.

Verified here: types, lint, architecture, adapter inventory, CI contract,
i18n, design system, diagnostics, browser security, dev release manifest,
TechLog contract and build pass; 220 component, 155 integration, 15
contract, 418 TechLog, 43 reference-feature, 18 recipe and 46
release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at
8210d48 first and unchanged: check:registries (byte-identical),
test:runtime-schema, verify:documentation. Brought by the template and
escalated rather than suppressed: check:request-fanout on TechLog's cursor
pagination, check:remediation-ledger (fails upstream too), the shared-chunk
hash test, and the registry-dependent sample removal and second-feature
tests. Playwright suites were not run.

Full record, the five open questions and the follow-ups in
docs/operations/template-sync-2026-09-29.md.

(cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
This commit is contained in:
DongHyeonka
2026-11-12 08:28:54 +09:00
parent 585c62431a
commit c80320dfc7
738 changed files with 55027 additions and 13567 deletions
+71
View File
@@ -0,0 +1,71 @@
# 문서 색인
`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`. 이 저장소가 받은 템플릿 변경은 [`operations/template-sync-*.md`](operations/)에 동기화마다 적는다
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
| `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`만 게이트가 읽는다 |
+6
View File
@@ -18,6 +18,12 @@ fields, pending verdicts, and mismatched release IDs. The scope is:
`TECH_LOG_STUDIO_NOT_FOUND`, `TECH_LOG_STUDIO_PUBLICATIONS`,
`TECH_LOG_STUDIO_PUBLICATION_PREVIEW`, `TECH_LOG_TOPIC`.
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. The
template carried the same rule for its own example screens; the route set is
@@ -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
@@ -2604,7 +2607,7 @@ export const DEFAULT_REALTIME_RECONNECT_POLICY = Object.freeze({
- remaining episode budget 초과 hint: reconnect 종료;
- attempts/exhausted: `DEGRADED`, explicit recovery action;
- automatic new episode cooldown: 300,000ms;
- valid event/heartbeat 또는 60s stable open 후 attempt counter reset;
- valid event/heartbeat를 받고 60s stable open도 지난 뒤에만 attempt counter reset;
- offline state에서는 timer 대신 `online` signal을 기다림.
### 14.4 error classification
@@ -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 정책을 사용한다.
@@ -525,6 +540,14 @@ recipe의 feature-facing `StoredRecord<T>` view model과 혼동하지 않는다.
`writtenAtEpochMs`, synchronization, `measuredBytes`, `eligibleAtEpochMs`는 record
envelope에 중복 저장하지 않고 `retentionStore` sidecar에 둔다.
revision은 살아 있는 record 하나 안에서만 순서를 매긴다(D-13). `remove`는 행을
tombstone 없이 지우므로 같은 key를 다시 만들면 revision이 1부터 다시 시작한다.
그래서 `(key, revision)`은 key의 전체 수명에서 유일하지 않다. 삭제 전에
revision N을 읽은 writer는 재생성된 record가 N에 도달하면 `expectedRevision: N`
CAS로 그 record를 덮어쓸 수 있다. 이 구분이 필요한 호출자는 revision과 함께
자기가 소유한 값(server version, payload 안의 ID)을 비교한다. tombstone으로
번호를 이어 가는 방식은 저장 스키마 변경이라 이 템플릿 범위 밖이다.
- structured clone 성공을 업무 schema 검증으로 간주하지 않는다.
- 모든 read는 `unknown`에서 runtime codec으로 envelope와 payload version을
검증한 뒤 domain value로 mapping한다.
@@ -751,8 +774,10 @@ CLEANED -> journal 제거
- journal row와 budget reservation은 physical cleanup effect가
`CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash,
malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를
그대로 남기고 `OBJECT_RECONCILE`로 반환한다.
malformed response, worker cleanup 실패는 성공이 아니며 `PREPARING`/`FILES_READY`를
그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면
`QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다
(Q-6.5-9). journal rollback이 실패해도 같다.
- coordinator가 `abortPreparedPut()` 하나만 소유한다. worker client는 prepare 실패
시 별도의 fire-and-forget abort를 발행하지 않는다. 중복 보상은 아직 남아 있어야
할 journal row를 조기에 지우는 경로였다.
@@ -771,6 +796,11 @@ CLEANED -> journal 제거
`STORAGE_EVICTED`; reconstructable만 rehydrate한다.
- delete는 logical row tombstone을 먼저 commit해 신규 open을 막고 physical bytes를
나중에 정리한다.
- delete가 끝나면 logical row가 없어지므로 같은 object ID의 다음 put은
generation 1부터 다시 시작한다(D-13). 삭제 전에 기억한 generation이나
`expectedGeneration`은 다른 객체와 일치할 수 있다. `(objectId, generation)`을
객체 수명 전체의 식별자로 쓰지 않고, 필요하면 integrity root digest를 함께
비교한다.
- operation ID로 replay를 deduplicate한다.
`Web Locks`를 쓰면 고정된 origin mutation lock과 AbortSignal/timeout을 사용한다.
@@ -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에 노출하지 않는다.
@@ -360,7 +437,10 @@ resume through upload()
정한 `schemaVersion: 2`가 필요하다. 기존 schema에 필드를 몰래 추가하지 않는다.
현재 checkpoint store도 single-key `read/CAS/remove`와 account partition 전체
삭제만 제공한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
삭제만 제공한다. 예외로 읽을 수 없는 행(손상, 또는 이 빌드가 모르는
`schemaVersion`)은 명시적 `abort()`가 `removeUnreadable`로 지우고 `ORPHANED`로
보고한다. 그 행에서는 session을 알 수 없으므로 server session은 만료에 맡긴다.
`upload()`는 같은 행에서 계속 `CORRUPT_DATA`로 fail-closed한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
checkpoint를 retention 기준으로 자동 발견·정리하지 못한다. 향후 admin lifecycle은
다음을 제공한다.
@@ -397,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`다.
@@ -545,6 +630,9 @@ DOM, persisted state, telemetry 또는 query cache에 장기 보관하지 않는
private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NONE`으로
낮출 수 없다. probe는 `credentials: omit`, redirect 금지, exact response URL과
`Cache-Control: no-store`를 실제 response에서 확인한다.
probe는 decode 크기가 primary 후보의 pixel 크기와 정확히 같아야 통과하므로
`PRIMARY_REQUIRED` preset의 `fit`은 `cover`/`contain`/`fill`만 허용한다(D-12).
원본 비율을 유지하는 `inside`/`outside`는 probe를 쓰지 않는 preset에서만 쓴다.
실제 `<img crossorigin="anonymous">`는 same-origin일 때 cookie를 보낼 수
있으므로 registry는 CDN origin이 composition의 application origin과 같으면
생성 단계에서 거절한다. private CDN 응답은 cookie나 ambient authorization에
@@ -559,6 +647,14 @@ private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NON
- 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`도
@@ -624,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
@@ -618,7 +618,8 @@ stream + epoch별 `lastAppliedSequence`를 기준으로 처리한다.
| `sequence == lastApplied + 1` | 순차 적용 |
| `sequence > lastApplied + 1` | gap; delta 적용 중지, `RESYNC_REQUIRED` |
| unknown `streamEpoch` | old/new epoch를 섞지 않고 registered snapshot 또는 session rebuild |
| dedupe/queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
| dedupe window 가득 참 | 가장 오래된 항목부터 제거(FIFO)하고 계속 적용. 창에서 밀려난 재전송은 `sequence <= lastApplied`로 drop |
| queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
| captured old runtime generation | late callback safe drop + aggregate diagnostic |
| current connection의 `scopeBinding` mismatch | effect/sequence/cursor 0, freshness `UNKNOWN`, close + session revalidation + registered recovery |
@@ -763,21 +764,39 @@ effectiveDelay = max(localDelay, validServerNotBefore)
bound로 취급한다. `effectiveDelay`가 implementation max delay나 남은 elapsed
budget을 넘으면 낮춰 clamp하지 않고 reconnect/poll을 종료해
`DEGRADED`/`STALE`로 전환한다.
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. stable-open
window 또는 valid heartbeat/event 뒤에만 reset한다.
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. valid
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로 전환한다.
@@ -801,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 |
@@ -844,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을 늘릴 수 없다.
@@ -873,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을 하나로 만드는 기능은
@@ -1004,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,
@@ -1148,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 | 아니오 |
@@ -1279,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
@@ -1298,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했다”고 주장하지
@@ -1411,6 +1478,20 @@ Service Worker는 언제든 종료될 수 있다. in-memory cursor, queue, auth
timer를 authority로 사용하지 않는다. `waitUntil`도 무제한 lifetime을 보장하지
않으므로 large fetch, retry loop, data migration을 넣지 않는다.
**조용한 drop은 설계 의도다(D-14).** 검증에 실패한 push(EXPIRED,
RELEASE_MISMATCH, association mismatch, fence 읽기 실패, handler deadline 초과,
malformed/unknown)는 알림을 띄우지 않고 끝난다. 계정 정보가 없는 generic
알림으로 대신 띄우지 않는 이유는 logout·계정 전환 뒤에 도착한 push가 어떤
형태로든 사용자에게 보이면 안 되기 때문이다. 대가는 두 가지다.
- Chrome은 `userVisibleOnly` push가 알림 없이 끝나면 "This site has been updated
in the background" 같은 기본 알림을 대신 띄울 수 있다.
- Safari(WebKit)는 알림 없는 push가 반복되면 구독을 취소할 수 있다.
그래서 drop은 드물어야 한다. backend는 ACTIVE association에만 보내고, 짧은
server TTL을 쓰고, release를 바꾼 직후에는 이전 release epoch로 보내지 않는다.
drop은 `web_push_hint_processed`의 `FAILED` + reason으로 관측한다.
### 8.5 Notification content와 click
- title/body/icon/action은 closed notification registry가 만든다.
@@ -1438,8 +1519,17 @@ type NotificationClickDataV1 = Readonly<{
worker가 종료·재시작된 뒤에도 click을 처리할 수 있도록 이 bounded, non-sensitive
envelope만 `NotificationOptions.data`에 넣는다. click handler는 codec/size/expiry,
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch는
route를 열지 않고 notification을 닫는다. 이미 표시된 notification은 logout 뒤
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch
(만료, fence·release 불일치, fence 읽기 실패, 모르는 route)는 notification을 닫고
요청한 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`는 루트 창의
확실성), 브라우저가 창 열기를 거절한 native 실패나 deadline/abort 뒤에는 루트를
다시 시도하지 않는다. 이미 표시된 notification은 logout 뒤
OS notification center에 남을 수 있으므로 copy는 항상 account-neutral하고
민감하지 않아야 하며, `getNotifications()` cleanup 성공을 privacy 보장으로
과장하지 않는다.
@@ -1709,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이어야 한다.
@@ -1828,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 |
@@ -1883,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를 만들지 않는다.
@@ -1919,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
+103 -25
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,31 +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`.
`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: 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
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
@@ -31,6 +31,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
`allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이
`TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지
않기 위한 cross-field invariant다.
- `allowedResponseHeaderNames`에 `content-type`이 없는 policy도 composition에서
`TypeError`로 실패한다. activation이 저장된 `content-type`을 다시 검증하기
때문이다.
- `Vary: Accept-Encoding`은 policy 없이 항상 허용한다. `Accept-Encoding`은
script가 만든 Request에 들어가지 않는 금지 헤더라 저장과 조회 요청 모두 이
값이 없다. nginx `gzip_vary`와 대부분의 CDN이 이 헤더를 붙인다.
## 1. 변경할 수 없는 복구 원칙
@@ -54,7 +60,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
2. `cache.operation.failed`와 `storage.operation.failed`의 allowlisted
operation/outcome/reason만으로 범위를 좁힌다.
3. runtime status가 `ACTIVE_BROADCAST`, `ACTIVE_STORAGE_FALLBACK`,
`DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지 확인한다.
`DEGRADED_STORAGE_FALLBACK`, `DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지
확인한다. `DEGRADED_STORAGE_FALLBACK`은 BroadcastChannel open에 실패한 tab이다.
다른 tab이 broadcast로만 보낸 event를 받지 못한다.
4. 현재 tab의 mutation 성공 후 local namespace가 stale 처리되는지 확인한다.
5. 다른 tab의 오래된 화면이 단순 stale 표시인지, 실제 server authorization
우회인지 분리한다. authorization 우회는 cache incident가 아니라 P1 security
@@ -70,7 +78,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
- `BROADCAST_PUBLISH_FAILED`
- `STORAGE_LISTENER_FAILED`
- `STORAGE_PUBLISH_FAILED`
- runtime status `DEGRADED_LOCAL_ONLY`
- `INVALID_CACHE_EPOCH`, `SECURE_RANDOM_UNAVAILABLE`(OPEN FAILED): runtime을
만들지 못해 이 tab은 cross-tab 무효화 없이 `DEGRADED_LOCAL_ONLY`로 동작한다
- runtime status `DEGRADED_STORAGE_FALLBACK` 또는 `DEGRADED_LOCAL_ONLY`
### 확인
+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
+84 -7
View File
@@ -12,21 +12,98 @@ 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`
- HTML: `no-cache`
- runtime config and release manifest: `no-store`
- public source maps: disabled
- service worker/offline cache: disabled
- service worker/offline cache: disabled, unless the static selection in
`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`).
+537
View File
@@ -0,0 +1,537 @@
# Template sync — `ebea300` → `af3d8e6`
Record of how the frontend template's 359 pending commits (tag `v0.2.0` plus
one documentation commit) were transplanted into this product, and of every
decision taken where the two trees disagreed.
## Starting state
| | |
| --- | --- |
| template pin before | `ebea300` (`template.lock.json`) |
| template pin after | `af3d8e6` (tree `bbcb6dd`) |
| template commits carried | 359 (`ebea300..af3d8e6`) |
| template delta | 824 files: 371 added, 439 modified, 8 renamed, 6 deleted; +68,835 / −13,207 |
| this product's divergence since the last sync | 182 files (`afde2b1..8210d48`) |
| files touched by both since `ebea300` | 90 |
| template paths applied verbatim | 606 |
| template paths applied with product changes | 85 |
| template paths not carried | 127 (listed below) |
Rollback ref created before touching anything:
```
backup/main-before-template-af3d8e6 → 8210d48
```
The histories share no commit, so this is again a patch transplant. It was
done as a three-way merge against an explicit base:
`git merge-recursive ebea300 -- HEAD template/main`, which left 67 conflicts
in the working tree (49 content, 17 modify/delete, 1 rename/delete).
### Pre-transplant baseline
Captured in a clean worktree at `8210d48`, so a pre-existing failure could not
be mistaken for a transplant regression.
| Gate | Result at `8210d48` |
| --- | --- |
| `check:types`, `lint`, `check:architecture`, `check:adapter-inventory`, `check:ci`, `check:i18n`, `check:remediation-ledger`, `check:design-system`, `check:diagnostics`, `check:browser-security`, `check:dev-release-manifest`, `check:tech-log-contract`, `build` | pass |
| `check:registries` | fail — 5 structure errors (three TechLog schema ids unregistered), 6 breaking changes without evidence |
| `test:unit` | 1792 passed (140 files) |
| `test:component` | 154 passed |
| `test:integration` | 102 passed |
| `test:contract` | 7 passed |
| `test:runtime-schema` | 44 passed / 1 failed (`release-manifest.test.ts` expects Studio contract 3.0.0; it is 3.1.0) |
| `test:tech-log` | 417 passed |
| `test:reference-feature` | 19 passed |
| `test:recipes` | 17 passed |
| `test:coverage` | 2535 passed / 1 failed (the runtime-schema test above), so the risk-coverage check is never reached |
| `verify:documentation` | `FAIL_UNVERIFIED`: `routeScopeDocumented: false` |
| `test:sample-removal` | fails: `typecheck`, `registry-structure`, `unit-integration`, `coverage` |
## What the template brought
| Group | Substance |
| --- | --- |
| Domain-scalable structure (`e59994a`) | Features are declared by `src/features/<id>/feature-module.ts`, owned by a bounded context (`src/contexts/<id>/context-module.ts`) inside a deployable app (`src/apps/<id>/app-module.ts`). `scripts/generate-product-feature-index.ts` writes `src/.generated/` from those declarations, and every composer (`installed-*`) is a projection of the generated index. New `src/platform/` kernel (cardinality, errors, telemetry pipeline, traffic, resilience, release coherence) and the scale tooling under `scripts/scale/` |
| 2026-09-24 src review (`4626b73`) | HTTP 408/425/503 handling, abort kernel reuse, SSE parsing, demo subject |
| 2026-09-25 maturity review (`f1002fd`) | The 0.2.0 CHANGELOG rows: correlation ids, idempotency-key reuse on unknown-effect resend, 422 field issues, `readSubject` required, `VITE_*` only through `ENV_REGISTRY`, zod only through `src/contracts/zod.ts`, generator-applied `VITE_PRODUCT_FEATURES`, `feature-module.ts` or `NOT_INSTALLED` per feature directory, CI contract baseline file, every test file gated or listed, FE-GATE-028 for the signed manual accessibility review, runtime-config schema baseline, `noUnusedLocals`, boot error shell for module-evaluation failures, and a long list of adapter fixes |
| Other | WebKit wording fix for the old-tab chunk spec, deferred-decision records |
## What was deliberately not carried
| Path | Why |
| --- | --- |
| `artifacts/phase5/**` (4), `artifacts/quality/extreme-scale-gates/**` (24), `artifacts/scale/**` (35) | Logs of the template's own runs. `scripts/scale/run-scale-profile.ts` and `scripts/verify-extreme-scale.ts` *write* them; `verify-extreme-scale` reads only `summary.json`, `browser-soak.json` and `baseline-comparison.json`, which are regenerated and gitignored. Nothing reads the committed `.log` files. |
| `CLAUDE.md`, `SPEC.md`, `tasks/**` | The template repository's own review instructions and the task tracking of its 2026-09-25 fix round (branch states, lanes). False here. `tests/unit/deletable-history-documents.test.ts` confirms no code reads them. |
| `CHANGELOG.md` | The template's release notes (`version 0.2.0`). This product's version is its own; the README and `docs/README.md` now point at the template repository's changelog instead. |
| `docs/reviews/2026-09-2{3,4,5}-*` (28 files), `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` | Reviews of the template repository at its own commits, with its own file:line findings, and the guide those reviews follow. Only `CHANGELOG.md` linked to them. |
| `src/features/reference-feature/{feature-module,context-routes}.ts` and `…/presentation/**` (9 paths) | Installing the sample now requires its screens, which this product deleted (see the reference-feature decision below). |
| `src/presentation/{pages/home-page,pages/not-found-page,examples/auth-example-page,examples/platform-overview-page}.tsx` | Deleted by this product's UI migration; the template modified them. The deletions stand. |
| `tests/e2e/reference-{form,route,save}.spec.ts`, `tests/features/reference-feature/{reference-page,reference-production-vertical,feature-module,installed-context-routing}.test.tsx?`, `tests/visual/platform.visual.spec.ts` and its three PNGs | Assert the deleted sample screens, the uninstalled sample's descriptor or the template's own pages. |
| `tests/component/app-shell.test.tsx` | Drives the template `AppShell` through `AppRouter`. This product never mounts `AppShell`. |
| `tests/component/context-route-gateway.test.tsx`, `tests/component/route-status-surfaces.test.tsx` | Drive the template's bounded-context route gateway and its example pages, which this product's router does not mount (see the router decision below). |
Template tests that asserted a platform behaviour on deleted template screens
were ported onto TechLog routes instead of being dropped — see "Template tests
ported onto TechLog".
## Conflicts and how each was decided
The rule is the one the previous two syncs wrote down: **keep the template's
mechanism, keep the product's content, and never invent a third state that
neither branch would accept.**
### The generated feature index — `src/features/*/NOT_INSTALLED`
The substantive change of this sync. The template no longer lists features by
hand anywhere: the generator scans `src/features/<id>/`, and a directory must
either declare itself with `feature-module.ts` (and `context-routes.ts` for its
screens) or carry a `NOT_INSTALLED` marker, or the first build step fails.
Every `installed-*` composer is now a projection of the generated index.
This product has three feature directories:
- `local-draft-feature` — the template itself now marks it `NOT_INSTALLED`.
Previous follow-up 5 ("carried but not installed") is settled upstream.
- `tech-log` — this product's domain. The previous two syncs recorded that
TechLog is composed directly rather than as a selectable feature, and that
decision stands. Its routes are served by the product's grouped
PUBLIC/STUDIO router, not by a bounded-context route module, so a
`feature-module.ts` would be a second, unused description of it. It carries
a `NOT_INSTALLED` marker whose text says exactly that: the generator must
leave the directory alone; TechLog is composed by the composition root.
- `reference-feature` — the template's removable sample. See the next section.
With no generator-installed feature, `src/.generated/` declares none, the
deployable app is the template's `template-app` declaration with no populated
context, and `COMPILED_PRODUCT_FEATURE_IDS` is empty.
### `reference-feature` is no longer installed
Until now the sample stayed half-installed: its operations, schemas, adapter
input, contract contribution and messages were composed, and its routes were
filtered out because this product deleted its screens. The template's new
mechanism has no such state. A feature is installed by `feature-module.ts`,
whose `context-routes.ts` imports the page components, and whose contract's
routes enter the route registry. Recreating the half-installed state would need
a product-only `context-routes.ts` with no routes and the old route filter back
in `installed-feature-contracts.ts` — a third state neither side has.
So the directory carries `NOT_INSTALLED`, with the reason. Its code and its own
tests stay (they compile and pass), so reinstalling it or deleting it outright
remain open, and the next sync merges cleanly. What changes at runtime: the
three `REFERENCE_RESOURCE` operations, their six schemas and the one
invalidation topic leave the registries and the bundle. Nothing in this
product called them. The removal is recorded as 13 evidence entries in
`config/contracts/registry-change-evidence.json` (owner `tech-log-frontend`),
the same way the product recorded removing the template's routes, and
`FEATURE_OVERRIDES.reference-feature` is dropped from the four runtime
profiles and `public/config.json` — what the template's own removal procedure
does, and what keeps boot from reporting an override for an undeclared
feature (09-09). Whether to delete the directory is an open question below.
### Composers — `src/features/installed-*.ts(x)`
All five take the template's version, then add TechLog directly:
- `installed-feature-adapters.ts` — the template's module projection and its
`activeFeatureIds` parameter (Q-6.9-5, the kill switch now withholds a
switched-off feature's input). TechLog's input is composed on top and stays
total; neither the index nor `activeFeatureIds` governs it.
- `installed-contract-contributions.ts` — the descriptors' contributions, then
TechLog's three.
- `installed-feature-contracts.ts` — `composeUniqueRecord` over platform,
TechLog and installed routes (a duplicate route id now throws). The
previous sync's route filter and its ownership filter are gone: with the
sample uninstalled no registered route lacks a component.
- `installed-feature-messages.ts` — `composeInstalledMessageCatalogs` over the
installed modules plus TechLog's catalogs, so a key defined twice for one
locale throws for TechLog too. The type is keyed by TechLog's locales.
- `installed-feature-runtimes.tsx` — `composeUniqueRecord` over platform,
TechLog and installed runtime descriptors. The previous sync kept an object
spread because the template's `Object.assign` widened the catalogs to
`any`; `composeUniqueRecord` keeps them typed, so that reason is gone.
### Router — `src/presentation/routes/app-router.tsx`
Taken from the template: the shared `LoadingSurface` and `StatusPage` for the
loading, failure, invalid-address, disabled-feature and integration-failed
surfaces; the support reference `build:incident` on route failures (08-07);
route lifecycle (title, telemetry) for every answer a route gives, with the
title effect split from the navigation effect; no scroll-to-top on back and
forward (08-08); a query on a route without search is kept in the URL (D-16,
here expressed as `searchSchema === null`); `useSessionAction`; the keyed
`ChunkRecoveryBoundary` with `buildId` and `onUnrecovered`; and the router
created in the effect that disposes it, below `PreferenceProviders`.
Kept from the product: the grouped PUBLIC/STUDIO layouts, the registered
not-found descriptor, the sign-in card with its return address, and no route
focus on `#main-content` (removed in `6c2780b` for UI parity; the shells own
focus).
Not carried: the template's bounded-context route gateway
(`ContextRouteGateway`). It mounts generator-installed features' routes, and
none is installed here. `AppRouter` now mounts `MOUNTED_ROUTE_REGISTRY` —
platform plus TechLog — rather than the whole installed registry, which is
also what keeps the app typecheck green when a generator feature is installed
(`tests/unit/two-feature-install-typecheck.test.ts`). The day one is installed,
`tests/component/product-feature-switch.test.tsx` ("registers no route that
cannot be mounted") fails until the gateway is wired in. Follow-up.
### Boot — `src/bootstrap/main.tsx`, `create-runtime-composition.ts`, `runtime-adapters.ts`
`main.tsx` is the template's entry that imports `boot.tsx` dynamically
(09-03), with this product's font and TechLog stylesheet imports kept in the
entry. The composition keeps the BFF session-owner installation and takes the
template's telemetry hand-off to the optional host (06-05). The feature
capabilities object carries both the template's `telemetry` and TechLog's
source switches and CSRF provider.
### Design system and forms
- `Pagination` (`primitives/navigation.tsx`) — the template's version (landmark
context for `CollectionPage`, links that keep the other search parameters,
modified clicks left to the browser, a single hidden page shown instead of an
ellipsis) with this product's options added back: `pageControl: "button"`,
`pageAccessibleLabel`, `className`, `around`, and the `ol.ui-pagination__pages`
list the Studio stylesheet and tests target. The product's "show every page
when there are few" rule is replaced by the template's window with `around`
neighbours; `StudioPagination` keeps `around={2}` and its tests pass
unchanged.
- `Dialog` (`primitives/core.tsx`) — the template's "restore focus only if the
dialog still owns it" guard on this product's synchronous restore.
- `StatusPage` — the template's `surface` prop beside this product's
`className`, `headingNode` and `visualPolicy`; `children` renders once, under
the actions, as upstream.
- `application-query.ts` — the template's idempotency-key reuse on resend
(03-01) written against this product's lazily acquired `submissionChannel`.
- `feature-http-binding.ts` — both the product's `detail` and the template's
422 `validationIssues` pass through.
- `platform-route-codecs.ts` — the template's non-strict `none` codec (D-16)
with this product's non-empty splat.
### Messages — `src/presentation/i18n/catalog.ts`
Both sides wrote copy for the 22 failure kinds that had none (07-01). This
product's copy is kept; the template's boot keys come in through
`BOOT_MESSAGES` (09-03). The template's `home.*` keys belong to its home page,
which this product deleted, so they and their parameter entry are not carried.
### Build and CI
- `vite.config.ts` — the template's declared-`VITE_*` check (13-06) and
config-under-base check (13-07); one `manualChunks` under `rolldownOptions`
that splits the template's preload helper first (09-03) and then this
product's named TechLog route chunks, plus this product's Studio
`modulePreload` filter.
- `scripts/build-frontend.ts` — the template's self-unregistering worker and
dist permissions steps around this product's serving-boundary step.
- `scripts/check-i18n.ts` — the template's discovery of every feature's
`presentation/`, with TechLog's held to this product's behavioural-literal
policy instead of the whole-file Korean rule.
- `scripts/check-design-system.ts` — deep-import and icon checks moved to the
import graph upstream; this product's palette rule is kept.
- `scripts/generate-ci-workflow.ts` and the workflow — pushes to `main` only,
as this product already had (the template also lists `develop`).
- `config/ci/gates.json` — merged per id. The template moved the signed manual
accessibility review out of FE-GATE-009 into release gate FE-GATE-028
(08-06); this product's per-route evidence moved with it, and the template's
five records for its own routes stay deleted. `scripts/contracts/ci-gates.ts`
now pins that one-record-per-mounted-route rule on FE-GATE-028.
- `scripts/test-performance.ts` — the template's median-of-runs measurement
(11-07). Its named interaction is a click on a navigation link to the target
heading; this product had measured the landing heading without a click, which
that clock cannot express, so the interaction is now landing → Explore
(`TECH_LOG_EXPLORE`). Not run here (Playwright). Open question below.
- `scripts/test-sample-removal.ts` — the template's `--feature=<id>` version.
It locates a `NOT_INSTALLED` directory directly, and this product's two
extra owned paths (`studio-csrf-composition.test.ts`, and now the sample's
bounded context) and two excluded tests are kept.
- `package.json` — the template's scripts with the generator prefix; this
product's name, version and scripts. The generator prefix is also added to
`check:dev-release-manifest`, `generate:dev-release-manifest`,
`check:tech-log-contract` and `generate:tech-log-contract`, which reach the
generated index (`tests/unit/product-index-entrypoints.test.ts`).
### Documents
`README.md` takes the template's runtime-configuration, support-scope,
documentation, CI and "Updating a copied project" sections, edited where they
would be false here: the support scope names TechLog's shells instead of the
example routes and lists the reference sample as not installed; the deletable
history table drops `SPEC.md`, `tasks/` and `CLAUDE.md`; the workflow runs on
`main`; and the origin record is `template.lock.json`, which already says
more than the suggested one-line `.template-origin`. `docs/README.md` (the
template's document index) is carried with its links to the uncarried files
removed. `docs/accessibility/manual-checklist.md` keeps this product's route
list and takes the FE-GATE-028 paragraph; the template's description of its own
accessibility spec is not carried, because this product's spec differs.
### Derived baselines — recomputed, not chosen
Each was recomputed with the template's own command or function, after first
reproducing both sides' committed value from their own input.
| Value | This product | The template | Merged |
| --- | --- | --- | --- |
| CI contract (`config/ci/contract-baseline.json`, `update:ci-contract-baseline`) | 27 / 94 / 106 / 141 / 5, `629e5898…` | 27 / 98 / 103 / 109 / 5, `630e8012…` | **27 gates / 101 commands / 106 references / 141 artifacts / 5 stages, `c9adcf85701156097262d8f88203fe42f8be003033e1b6c296a0062e56f10324`** |
| evidence artifact references (`ci-workflow-generation.test.ts`) | 120 | 87 | **119** |
| registry baseline approval digest (`registrySnapshotDigest`) | `428479ac…` | `83d11f84…` | **`2dc6c3a36a5e06c5b4736a0e2bc556d74437f061e6adb71c4e4fb96293170def`** |
| runtime-config schema baseline (`check-compatibility.ts --update-baseline`) | — | template's schema | **this product's schema, byte-identical to the one at `8210d48`** |
The CI contract's hard-coded counts moved upstream into the baseline file
(14-02), so `scripts/contracts/ci-gates.ts` no longer carries them. The
registry baseline is a per-registry, per-row three-way merge of both approved
snapshots; its new approval takes no row from the current tree, so this
product's six pending TechLog route changes stay unapproved. The runtime-config
baseline stands for "the schema the previous release's reader accepts"; the
previous release is `8210d48`, and the schema did not change.
### Template tests ported onto TechLog
Where a template test pinned a platform behaviour on a screen this product
deleted, the test was moved onto a TechLog route rather than dropped:
| Test | Upstream subject | Here |
| --- | --- | --- |
| `tests/component/router.test.tsx` | D-16 query on `/examples/ui`; route lifecycle on fixture-feature surfaces | `/projects?utm_source=mail`; the sign-in gate on `/studio` |
| `tests/component/chunk-recovery-boundary.test.tsx` (2 cases) | states example page | Explore page; sibling move to Topics |
| `tests/component/render-boundary.test.tsx` | states example page | Explore page |
| `tests/component/locale-platform.test.tsx` | the app shell's language selector | the file's own locale harness |
| `tests/component/runtime-application.test.tsx` | shell language selector and session button | stored preference; the Studio sign-in gate |
| `tests/e2e/old-tab-chunk-recovery.spec.ts` | platform and UI example pages | Explore and Topics (not run here) |
| `tests/component/product-feature-switch.test.tsx` | — | the owner is a fixture id and the feature port reports it active or off, since no feature is generator-installed |
Template tests whose invariant is "every feature comes from the generated
index" now also account for TechLog composed directly
(`installed-feature-messages`, `route-runtime`, `product-feature-selection-build`).
Tests that hard-coded template copy or template route ids now use this
product's (`form-foundation`, `manual-a11y-evidence`, `ci-workflow-generation`,
`feature-override-diagnostics`).
## Fixes the transplant required
### `readSubject` on the TechLog session owner — `bff-session-owner.ts`
The template now closes an external session owner without `readSubject` as
`integration-failed` (c6300e9). The HTTP Studio's only owner is
`createBffSessionOwner`, which had none — so every Studio session in
production would have closed. It now has one. `getStudioSession` returns a
display name and roles but no identifier that is stable for one user and
distinct between users, so the owner reports `null`: the runtime then treats a
change of state as a possible user switch and clears server state, recording
`SUBJECT_MISSING`. The owner only notifies when the probed state changes, so
that is one fence per sign-in. `tests/features/tech-log/bff-session-owner.test.ts`
pins that the owner is complete. A real subject needs the backend (open
question below).
### zod through `src/contracts/zod.ts` (F-7)
Nine TechLog files imported `zod` directly; the architecture gate now refuses
that. They import `z` from the facade, which sets `jitless` before any schema
is built, so the production CSP sees no eval probe.
### `noUnusedLocals` (12-12)
The flag found 22 unused imports and locals in TechLog source, one unused
helper in `scripts/generate-nginx-config.ts`, and nine in tests (eight under
`tests/features/tech-log`). All were removed except three compile-time
assertions in `tests/features/tech-log/feature-input.test.ts` and
`studio-contract.test.ts`, which are exported instead: removing them would
remove the check.
### Runtime profiles and `public/config.json`
The template requires `public/config.json` to equal the local profile plus
`BUILD_ID` and `RELEASE_ID` (F-5). It lacked this product's two
`TECH_LOG_*_SOURCE` keys, whose defaults it relied on; they are now written
out, with the same values. `FEATURE_OVERRIDES.reference-feature` left every
profile with the sample (above). `public/release-manifest.json` keeps this
product's `appVersion` 0.1.0; the merge had taken the template's 0.2.0.
### Scripts that reach the generated index
`tests/unit/product-index-entrypoints.test.ts` requires every script that
imports `src/.generated/` to run the generator first. This product's
`check:dev-release-manifest`, `generate:dev-release-manifest`,
`check:tech-log-contract` and `generate:tech-log-contract` do, and are
prefixed. `scripts/lib/manual-a11y-evidence.ts` did too, through the CI
contract parser, which would have forced a prefix on `check:ci` — and the
template requires `check:ci` to be its exact canonical command. The manual
accessibility scope is now read from the platform and TechLog route
registries directly: the set `AppRouter` mounts.
### `verify:tech-log-source-parity` is listed as ungated
Every verification script must run in a gate or be listed with a reason
(12-04). This one needs the original TechLog source served on another port,
which no CI runner has; it is listed in `config/ci/ungated-scripts.json`.
### Idempotency-key reuse (03-01) in two TechLog tests
`studio-save-navigation` and `studio-publication-flow` asserted that a retry
after a 503 uses a new key. The template now resends a write whose outcome is
unknown with its original key, so the backend can apply it once; the TechLog
contracts already declare `IDEMPOTENCY_REPLAY`. The two assertions now expect
the original key. The backend guarantee is an open question below.
### Chunk failures are recorded (08-07)
An unrecovered chunk failure is now recorded as `ui.render.failed` with the
incident id its support reference shows. `public-discovery-screens.test.tsx`
asserted that nothing was recorded for a failed not-found chunk; it now
asserts the one record, under `NOT_FOUND`. Its render helper also waits out
data loading only, since the route's own loading surface is now the shared
`LoadingSurface`.
### Release fixtures carry this build's contract set
`tests/release/fixtures/R10`/`R11` stand for releases of this repository.
Upstream the compiled contract set is empty and the fixtures write
`__EMPTY_SET_DIGEST__`; here it holds TechLog's three packages, so
`tests/release/release-fixture.ts` substitutes the set this build compiles.
### The sample's own composition test installs the sample
`tests/features/reference-feature/reference-runtime-composition.test.ts`
exercises the production graph with a real feature. With the sample
uninstalled it installs it for itself through the generated index, the way the
template's platform tests install their test-only feature.
## Gates on the transplanted tree
Run on the working tree after `corepack pnpm install` (no lockfile change).
Another agent was running gates on the same machine; every failure that
looked timing-sensitive was re-run alone (see below).
| Gate | `8210d48` | After the sync | |
| --- | --- | --- | --- |
| `check:types` | pass | pass (6 projects, `noUnusedLocals` on) | |
| `lint` | pass | pass, `--max-warnings=0` | |
| `check:architecture` | 507 modules, 14 fixtures | 565 modules, 2059 dependencies, 28 graph fixtures, TechLog route source of truth | pass |
| `check:adapter-inventory` | 133 files, 21/21 ratchet | 145 files, 22 abort-primitive importers, 13/13 ratchet | pass |
| `check:ci` | pass | 27 gates, baseline file, workflow bytes | pass |
| `check:registries` | fail | fail, **byte-identical output** | pre-existing |
| `check:i18n` | 460 keys | 455 keys (template's home-page copy not carried) | pass |
| `check:remediation-ledger` | pass | fail (budget statement) | template, escalated |
| `check:design-system` | 48 tokens | 48 tokens | pass |
| `check:diagnostics` | 8 / 5 | 9 diagnostics / 6 telemetry producers | pass |
| `check:browser-security` | pass | pass | |
| `check:dev-release-manifest` | pass | pass | |
| `check:request-fanout` | — (new) | fail: `collect-catalog.ts:30` | template, escalated |
| `check:tech-log-contract` | pass | pass | |
| `build` | pass | pass | |
| `test:unit` | 1792 | 2381 passed / 2 failed (174 files) | template, escalated |
| `test:component` | 154 | 220 passed | pass |
| `test:integration` | 102 | 155 passed | pass |
| `test:contract` | 7 | 15 passed | pass |
| `test:runtime-schema` | 44 / 1 failed | 60 / 1 failed, same test and assertion | pre-existing |
| `test:tech-log` | 417 | 418 passed | pass |
| `test:reference-feature` | 19 | 43 passed | pass |
| `test:recipes` | 17 | 18 passed | pass |
| `test:platform` | — (new) | 247 passed / 1 failed (request fan-out) | template, escalated |
| `check:release-coherence` | — (new) | 46 passed | pass |
| `test:coverage` | 1 failed | 3599 passed / 4 failed: the runtime-schema test and the three escalated tests; risk-coverage not reached on either side | pre-existing + escalated |
| `verify:documentation` | `FAIL_UNVERIFIED` | `FAIL_UNVERIFIED`, same cause; the template's new README variable check passes | pre-existing |
| `test:sample-removal` | fail (4 checks) | fail earlier, at the registry re-baseline | pre-existing cause, escalated |
`tests/component/boot-unexpected-failure.test.tsx` failed once in a full run
while the other agent's gates were running (its boot graph did not settle
inside the default one-second wait) and passed four times alone and in the
final full run; it is load-sensitive, not introduced.
Not run: Playwright e2e, visual and lab-performance
(`test:e2e`, `test:visual`, `test:a11y`, `test:performance`), so the ported
`old-tab-chunk-recovery.spec.ts` and the new lab interaction are unverified.
No visual snapshot was touched: the three template PNGs belong to the
platform spec this product deleted.
## Failures this sync did not cause, and did not fix
Each was reproduced at `8210d48` in the baseline worktree first.
| Gate | State |
| --- | --- |
| `check:registries` | Same five structure errors and six unevidenced TechLog route changes; output byte-identical. |
| `test:runtime-schema` | `release-manifest.test.ts` expects the vendored Studio contract at 3.0.0; it is 3.1.0. |
| `verify:documentation` | `routeScopeDocumented: false`, as recorded by the previous sync. |
| `test:coverage` | Fails on the runtime-schema test on both sides, so `check-risk-coverage` never runs; after the sync it also carries the escalated failures below. |
## Failures the template brought, escalated rather than fixed
Each fails because of something the template introduced, and each was left
failing rather than made green by weakening a check.
| Gate / test | Cause | Why not fixed here |
| --- | --- | --- |
| `check:request-fanout` (FE-GATE-010), and `tests/architecture/request-fanout.test.ts` in `test:platform` and `test:coverage` (FE-GATE-005) | The template's new N+1 source gate flags `gateway.getCatalog()` inside the loop at `src/features/tech-log/application/collect-catalog.ts:30`. That loop is cursor pagination — one request per page of 100, bounded at 50 pages, each needing the previous page's cursor — not one request per row. | The gate's own escape is a `// fanout-reviewed: <reason>` comment on the call's line: a reviewed suppression. Adding one is a reviewer's call, not a merge's. Open question 1. |
| `tests/unit/build-environment-bundle.test.ts` ("keeps the values the app reads and nothing else") | 09-03 expects the shared application chunk to keep its hash when only `VITE_BUILD_ID` changes. This product's `manualChunks` (named TechLog route chunks) leaves one shared chunk that also holds the build-id reader, so every chunk changes hash on every build. That was already true before the sync — then the whole app was one entry chunk. The test now names the product's shared chunk (`render-boot-failure-*`; upstream it is `design-system-*`) and fails on the property itself. | Needs a chunking change in `vite.config.ts` that keeps the route chunk names the build manifest requires; one attempt (isolating the boot-failure module) did not separate the shared code. Follow-up. |
| `tests/unit/second-api-feature-registries.test.ts` | Adds a feature to a copy of the tree and expects `check:registries` to pass there. It inherits this product's registry defect (previous follow-up 2). | Fixing that defect registers TechLog schema ids and approves six TechLog route changes: product work. |
| `test:sample-removal` (FE-GATE-020) | The template's removal now re-baselines the registries in the fixture with `update:registry-baseline`, which runs `check:registries --no-baseline` and stops on the same registry defect. The script throws there, before its other checks run. At `8210d48` it failed later, on four named checks, for the same root cause. | Same as above. |
| `check:remediation-ledger` | The ledger does not state the file-transfer budget the template later ratcheted to 55,700 bytes. Reproduced on an unmodified export of the template at `af3d8e6`, which fails it with four findings (this product's evidence-path fixes from the previous sync remove three). The template moved the script to `config/ci/ungated-scripts.json` with that reason; no gate runs it on either side. | Editing a history record to state a later number is the template's call, and it declined. |
## Follow-ups
The previous sync left five. Their state now:
1. **TechLog's HTTP gateways address operations by id through a shim.**
Closed before this sync, by `aaa384c` (`tech-log-http-binding.ts` builds
every gateway on `createFeatureHttpBinding`; the composition-root shim is
gone). This sync did not change it.
2. **The schema registry defect keeps gates red.** Still open, and it now
blocks more: besides `check:registries`, it stops `test:sample-removal`
earlier and fails the template's new `second-api-feature-registries` test.
`check:registries` output is byte-identical to `8210d48`.
3. **`tests/mocks` is feature-owned but TechLog imports it.** Unchanged. It
cannot be re-checked until `test:sample-removal` gets past the registry step.
4. **`check:i18n` cannot tell a comment from a literal.** Closed before this
sync, by `aaa384c` (TechLog presentation is held to a behavioural-literal
policy). This sync kept that policy while taking the template's per-feature
discovery; `check:i18n` passes.
5. **`local-draft-feature` carried but not installed.** Settled upstream: the
template marks it `NOT_INSTALLED` itself.
New:
6. **TechLog is not a generator-installed feature.** It carries a
`NOT_INSTALLED` marker because it is composed directly. The template's shape
for it would be `feature-module.ts` in a bounded context whose route module
serves TechLog's routes — which means moving the grouped PUBLIC/STUDIO router
onto context route modules. Its own change.
7. **The bounded-context route gateway is not mounted.** `AppRouter` mounts
platform and TechLog routes only. The day a generator-installed feature
arrives (the sample reinstalled, or TechLog moved per item 6), the
template's `ContextRouteGateway` has to be wired into a layout group, and
the template tests not carried for that reason
(`context-route-gateway`, `route-status-surfaces`, `app-shell`) come back.
8. **Shared chunk hash changes with every build.** See the
`build-environment-bundle` row above.
9. **`template-app` is the deployable app's id.** The generator requires one
app declaration; the template's (`src/apps/template-app/`) is carried as is.
Renaming it is cosmetic and touches no behaviour.
10. **Lab performance measures landing → Explore.** Not run here; the budget
(200 ms named interaction) has not been checked against it.
## Open questions for the product owner
1. **Cursor pagination and the N+1 gate.** Approve
`// fanout-reviewed: cursor pagination, one request per 100-row page, at most 50 pages`
on `src/features/tech-log/application/collect-catalog.ts:30`, or give the
Studio catalog a bulk read. Until then FE-GATE-010 and FE-GATE-005 are red.
2. **Delete `src/features/reference-feature`?** It is now uninstalled, with its
code and tests kept so the next sync merges cleanly and its own tests keep
running. Deleting it is what the template's removal gate proves possible;
reinstalling it means bringing its screens back.
3. **Studio session subject.** `getStudioSession` has no stable user
identifier, so the BFF owner reports none and every sign-in clears server
state once. A `subject` (for example the OIDC `sub`) in the session response
would let a token refresh keep the cache. Backend contract change.
4. **Same-key resend.** The client now resends a write whose outcome is
unknown with its original idempotency key (template 03-01). The TechLog
Studio and management contracts declare `IDEMPOTENCY_REPLAY`; confirm the
backend applies a repeated key once and returns the first result.
5. **Lab performance interaction.** The template's lab gate times a click on a
navigation link to the target heading. This product now uses landing →
Explore. Confirm that is the interaction to budget, or name another.
@@ -16,7 +16,7 @@ No Critical issue was found. Five High findings are implementation blockers or n
4. N-04: telemetry dispose only removes pagehide; queued callbacks, future emit calls, and in-flight delivery survive runtime teardown.
5. N-05: the conditional-validator key codec is delimiter-ambiguous and lets two valid bindings overwrite each other. It is not composed into HTTP yet, so this is a rollout blocker rather than a current request-path incident.
The current reference feature uses V3. The older createHttpClient path remains exported and is still the documented rollback/compatibility seam, so its replay and cancellation defects cannot be dismissed as dead code.
The current reference feature uses V3. The older createHttpClient path remains exported and is still the documented rollback/compatibility seam, so its replay and cancellation defects cannot be dismissed as dead code. (2026-09-24, Q-6.3-11: the comments no longer call it a rollback seam; V2 and V3 use different wire shapes, so a rollback also needs a V2-envelope server.)
## 2. Method, severity, and confidence
@@ -60,16 +60,19 @@ All 24 files below were read in full.
| src/adapters/diagnostics/bounded-diagnostics.ts | Bounded in-memory diagnostics projection/sink and safe pre-mount boot evidence | DiagnosticsPort; contracts/diagnostics.ts and telemetry.ts; bootstrap | Preserve fail-isolated projection and cloning. Harden non-finite capacity. V3 producer fix belongs primarily in bootstrap. |
| src/adapters/http/bounded-body-reader.ts | Declared-length and streamed byte ceilings, stream cancellation/release isolation, forbidden-body probing, strict UTF-8/JSON decode | V3 executor; bounded-body-reader tests | Keep as the single bounded response primitive. It already contains the cleanup behavior missing from bounded-json.ts. |
| src/adapters/http/bounded-json.ts | Legacy response stream reader and JSON decoder | legacy client.ts | Replace internals with bounded-body-reader delegation, then remove with V2 retirement. Current cancel/release failures can reject. |
| src/adapters/http/client.ts | Legacy/V2 operation lookup, profiles, auth recovery, retries, total deadline, response validation/mapping, diagnostics and telemetry | legacy contracts and ports; runtime-adapters createRuntimeHttpClient | Compatibility-only but exported. Fix empty keyed replay, cooperative auth cancellation, and common body-reader use before relying on it for rollback. Deprecate after callers are migrated. |
| src/adapters/http/client.ts | Legacy/V2 operation lookup, profiles, auth recovery, retries, total deadline, response validation/mapping, diagnostics and telemetry | legacy contracts and ports; runtime-adapters createRuntimeHttpClient | Compatibility-only but exported. Fix empty keyed replay, cooperative auth cancellation, and common body-reader use before relying on it for rollback. Not a drop-in rollback for V3: V2 validates the `{success,data,meta}` envelope and V3 the bare DTO, so a rollback needs the four slots and a V2-envelope server (Q-6.3-11). 401 recovery is a single replay outside the retry budget. Deprecate after callers are migrated. |
| src/adapters/http/http-contract-bridge.ts | V3 request projection, URL/body bounds, credential patch type, final request invariant | external-contract-runtime.ts; V3 executor | Preserve descriptor-owned request projection. Change credential authority: patch cannot own credentials or transport headers; final invariant must compare exact resolved profile. |
| src/adapters/http/http-effect-certainty.ts | Converts physical-attempt state and problem descriptors into mutation certainty/UI projection | V3 executor; contracts | Preserve explicit certainty vocabulary. Add a monotonic logical-execution certainty join used across retries. |
| src/adapters/http/http-execution-v3.ts | Descriptor-driven V3 lifetime: validation, projection, credentials, deadline, retry, fetch, response admission, effect verdict and observation | external contracts, scope, mutation intent, bridge, bounded reader, certainty, retry policy | Main correction site for N-01, N-02, N-03 and cooperative cancellation. Keep one retry authority and closed result union. |
| src/adapters/http/request-builder.ts | Legacy path/query construction and origin/base-prefix checks | legacy client; ApiOperation | Keep while V2 remains. Do not reuse it to weaken V3 descriptor projection. |
| src/adapters/http/resource-mapper.ts | Thin legacy operation-payload mapper delegation | boundary-mapper; legacy client | No standalone defect. Remove only with V2, not as part of the correctness patch. |
| src/adapters/http/retry-policy.ts | Legacy retry decision/backoff plus parseRetryAfter reused by V3 | legacy client and V3 executor | Keep deterministic parse/backoff seam. V2 must additionally prove a valid key before keyed replay. |
| src/adapters/http/retry-policy.ts | Legacy retry decision/backoff plus parseRetryAfter reused by V3; parsing delegates to kernel platform/retry-after.ts (Q-6.4-8) | legacy client and V3 executor; platform/retry-after.ts | Keep deterministic parse/backoff seam. V2 must additionally prove a valid key before keyed replay. |
| src/adapters/http/platform-error-mapping.ts | Maps feature-less V3 transport outcomes (cancel, timeout, network, response-invalid) to the platform AppError envelope; feature-owned outcomes return null | http-execution-v3.ts outcomes; platform/errors; feature HTTP binding | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row). |
| src/adapters/http/schema-registry.ts | Legacy Zod envelope/request/payload validation and clone | legacy client/tests | No standalone defect. Remains V2-only and should not be merged with installed external validators. |
| src/adapters/platform/browser-lifecycle.ts | Single owner of visibility/network/focus/page/beforeunload listeners and lifecycle snapshots | optional-runtime-host.ts | Preserve centralized listener ownership and idempotent dispose. Clarify or redesign dirty-source attachment semantics; selection item O-02. |
| src/adapters/platform/browser-mutation-intent-factory.ts | Secure intent/idempotency UUIDs plus monotonic creation time, normalized by defineMutationIntent | MutationIntentFactory port; bootstrap | Keep. Share one idempotency-key validator so external inputs and generated values have identical bounds. |
| src/adapters/platform/json-member-scanner.ts | Non-recursive duplicate-member and structure-budget scan before `JSON.parse`; moved from realtime in 2nd round (Q-6.4-8) | realtime event codec and WS protocol; web-push hint codec | Keep. Single scanner; web-push now checks every depth, not only top-level keys. |
| src/adapters/platform/retry-after.ts | Strict Retry-After parser: delta-seconds or IMF-fixdate, no guessed delays (Q-6.4-8) | realtime reconnect policy / SSE; http retry-policy.ts | Keep. Rejects blank, decimal and exponent values the old http copy accepted. |
| src/adapters/platform/system-clock.ts | Wall clock and abortable sleep with listener/timer cleanup | ClockPort; legacy HTTP | Keep. Existing unit test covers abort cleanup behavior. |
| src/adapters/query-cache/conditional-validator-store.ts | In-memory ETag CAS sidecar keyed by scope, definition, identity, representation and cache revision | bootstrap scope reset; future conditional HTTP/query join | Fix tuple codec before composition. Preserve validator grammar, generation/revision checks and bounded capacity. |
| src/adapters/query-cache/cursor-pagination-runtime.ts | Bounded cursor chain, page/snapshot/loop/item/byte validation | cursor pagination contract; currently available but not composed | Add post-await abort admission or an abort race. Current pre-await-only check can admit a late page. |
@@ -77,6 +80,8 @@ All 24 files below were read in full.
| src/adapters/query-cache/tanstack-cache-coordinator.ts | Maps registry topics to query namespace invalidation, coalesces remote hints, defers under mutation leases, resets/disposes | TanStack Query, invalidation contracts, cross-context runtime | Keep invalidate-only remote authority, generation guard, reset serialization and bounded registry validation. Add teardown characterization if dispose becomes async. |
| src/adapters/query-cache/tanstack-query-cache.ts | Creates QueryClient defaults and QueryCachePort read/write/invalidate adapter with diagnostics | TanStack Query, QueryCachePort, errors/diagnostics | Keep retry disabled and clone-on-write. Clone-on-read is an optional port-semantics decision, not a confirmed production defect. |
| src/adapters/telemetry/best-effort-telemetry.ts | Allowlisted bounded oldest-drop telemetry queue, scheduled/pagehide flush, sink isolation and evidence | TelemetryPort, telemetry/diagnostic contracts, bootstrap | Add terminal lifecycle state, joined flush promise and in-flight abort; ensure runtime composition disposes it. |
| src/adapters/telemetry/feature-telemetry.ts | Feature TelemetryPort adapter over the platform telemetry pipeline; fetch transport to the collector endpoint | platform/telemetry pipeline; TelemetryPort; bootstrap | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row); shares the collector with best-effort-telemetry (review 6.9-4). |
| src/adapters/telemetry/telemetry-collector.ts | The one collector transport behind both telemetry ports: shared send-rate window, `credentials: "omit"`, `cache: "no-store"`, per-request deadline through the kernel abort primitive, one `pagehide` fan-out | platform/telemetry send rate; adapters/platform abort and capacity kernel; bootstrap | Keep. Added 2026-09-24 for review 6.9-4 / 6.3-10: a hung collector no longer stalls later flushes, and the two ports no longer send 20+20 per minute. |
## 4. Traced boundary inventory
@@ -6,9 +6,9 @@
- 방식: 코드 리뷰만 수행했다. 이 문서 외 구현 파일은 수정하지 않았다.
- 결론: **Critical 0, High 4, Medium 3**이다. R-01~R-06은 코드상 확정된 lifecycle/immutability/resource 문제이고, R-07은 문서에도 미완료라고 명시된 production promotion blocker다. 두 runtime 모두 현재 `AVAILABLE_NOT_COMPOSED`이므로 production traffic 사고로 과장하지 않는다.
## 1. 21/21 파일 inventory와 책임
## 1. 20/20 파일 inventory와 책임
아래 경로는 모두 저장소 루트 기준 full path이며, 범위의 구현 파일 21개를 모두 읽었다.
아래 경로는 모두 저장소 루트 기준 full path이며, 범위의 구현 파일 21개를 모두 읽었다. 2차 라운드(Q-6.4-8)에서 `json-member-scanner.ts`는 kernel `src/adapters/platform/`로 옮겨 [Network/state](./01-network-and-state.md) 표에서 다룬다.
| # | full path | 책임 | 주요 의존성 / downstream | 판정 |
|---:|---|---|---|---|
@@ -16,23 +16,22 @@
| 2 | `src/adapters/browser-rpc/index.ts` | Browser RPC public adapter export surface | runtime, transport, unavailable adapter | 새 lease/install type export 필요 |
| 3 | `src/adapters/browser-rpc/transport.ts` | provider-neutral unary/stream transport result와 runtime identity 계약 | `src/contracts/browser-rpc.ts` | R-01, R-07 |
| 4 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | 선택되지 않은 runtime의 명시적 fail-closed Null Object | `transport.ts` | 유지; 새 stream lease shape만 맞춤 |
| 5 | `src/adapters/realtime/event-codec.ts` | raw JSON byte/shape/registry/schema 검증, immutable DTO와 semantic fingerprint 생성 | realtime contracts, schema registry, JSON scanner, result codec | 유지 |
| 5 | `src/adapters/realtime/event-codec.ts` | raw JSON byte/shape/registry/schema 검증, immutable DTO와 semantic fingerprint 생성 | realtime contracts, schema registry, kernel JSON scanner, result codec | 유지 |
| 6 | `src/adapters/realtime/event-consumer.ts` | SSE/WS cursor 규칙을 codec 결과와 결합하고 common stream coordinator outcome으로 투영 | realtime ports/contracts, event codec, stream coordinator | 유지 |
| 7 | `src/adapters/realtime/index.ts` | common realtime adapter public export surface | codec, consumer, reconnect, handoff, stream, sub-index | R-02/R-03 lifecycle type export 필요 |
| 8 | `src/adapters/realtime/json-member-scanner.ts` | `JSON.parse` 전 duplicate member와 structure budget을 비재귀적으로 검사 | 독립 utility | 유지 |
| 9 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | LIVE/POLL 단일 effect writer, generation fence, quiescence/checkpoint, probe buffer와 전환 | `ClockPort`, realtime result/ports | R-03 |
| 10 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | visible/online finite lease, single-flight poll, retry hint, response/apply deadline, non-cooperative task drain | bounded polling policy, `ClockPort`, realtime result | 유지 |
| 11 | `src/adapters/realtime/polling/index.ts` | polling public exports | bounded poll coordinator | 유지 |
| 12 | `src/adapters/realtime/reconnect-coordinator.ts` | 단일 reconnect owner, online gate, retry budget, session close authority, exact recovery proof, post-abort DRAINING | reconnect policy, `ClockPort`, realtime ports/result | 유지 |
| 13 | `src/adapters/realtime/reconnect-policy.ts` | immutable reconnect policy, full jitter, elapsed budget, Retry-After 계산/검증 | 독립 policy | 유지 |
| 14 | `src/adapters/realtime/result.ts` | hostile/mutable collaborator result를 exact own-data snapshot으로 canonicalize | realtime ports/contracts | 유지; R-04의 기준 패턴 |
| 15 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | fixed same-origin fetch-stream SSE, response/media/open gate, read/event deadline, cursor rule, bounded reader cancel | `ClockPort`, event authority/result, parser, reconnect policy | 유지; R-02 common drain과 함께 검증 |
| 16 | `src/adapters/realtime/sse/index.ts` | SSE public exports | fetch connection, parser | 유지 |
| 17 | `src/adapters/realtime/sse/sse-parser.ts` | strict incremental UTF-8 SSE parser, BOM/line ending/id/retry/event buffer ceiling | realtime contracts/result | 유지 |
| 18 | `src/adapters/realtime/stream-coordinator.ts` | per-stream sequential effect, dedupe/order, recovery, checkpoint/barrier, scope generation fence | event authority port, realtime contracts, mapper registry, codec/result | R-02 |
| 19 | `src/adapters/realtime/websocket/index.ts` | WebSocket connection/protocol public exports | connection, protocol | 유지 |
| 20 | `src/adapters/realtime/websocket/websocket-connection.ts` | 한 physical WS의 handshake/subscription/tombstone/FIFO/heartbeat/apply gate/recovery close | `ClockPort`, realtime contracts/result, WS protocol | 유지; R-02 upstream timeout과 함께 검증 |
| 21 | `src/adapters/realtime/websocket/websocket-protocol.ts` | exact closed JSON frame decode/encode, duplicate key/structure/sequence/frame byte 검증 | realtime contracts, JSON scanner | R-05 |
| 8 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | LIVE/POLL 단일 effect writer, generation fence, quiescence/checkpoint, probe buffer와 전환 | `ClockPort`, realtime result/ports | R-03 |
| 9 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | visible/online finite lease, single-flight poll, retry hint, response/apply deadline, non-cooperative task drain | bounded polling policy, `ClockPort`, realtime result | 유지 |
| 10 | `src/adapters/realtime/polling/index.ts` | polling public exports | bounded poll coordinator | 유지 |
| 11 | `src/adapters/realtime/reconnect-coordinator.ts` | 단일 reconnect owner, online gate, retry budget, session close authority, exact recovery proof, post-abort DRAINING | reconnect policy, `ClockPort`, realtime ports/result | 유지 |
| 12 | `src/adapters/realtime/reconnect-policy.ts` | immutable reconnect policy, full jitter, elapsed budget; Retry-After 파서는 kernel `platform/retry-after.ts`를 re-export | kernel retry-after | 유지 |
| 13 | `src/adapters/realtime/result.ts` | hostile/mutable collaborator result를 exact own-data snapshot으로 canonicalize | realtime ports/contracts | 유지; R-04의 기준 패턴 |
| 14 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | fixed same-origin fetch-stream SSE, response/media/open gate, read/event deadline, cursor rule, bounded reader cancel | `ClockPort`, event authority/result, parser, reconnect policy | 유지; R-02 common drain과 함께 검증 |
| 15 | `src/adapters/realtime/sse/index.ts` | SSE public exports | fetch connection, parser | 유지 |
| 16 | `src/adapters/realtime/sse/sse-parser.ts` | strict incremental UTF-8 SSE parser, BOM/line ending/id/retry/event buffer ceiling | realtime contracts/result | 유지 |
| 17 | `src/adapters/realtime/stream-coordinator.ts` | per-stream sequential effect, dedupe/order, recovery, checkpoint/barrier, scope generation fence | event authority port, realtime contracts, mapper registry, codec/result | R-02 |
| 18 | `src/adapters/realtime/websocket/index.ts` | WebSocket connection/protocol public exports | connection, protocol | 유지 |
| 19 | `src/adapters/realtime/websocket/websocket-connection.ts` | 한 physical WS의 handshake/subscription/tombstone/FIFO/heartbeat/apply gate/recovery close | `ClockPort`, realtime contracts/result, WS protocol | 유지; R-02 upstream timeout과 함께 검증 |
| 20 | `src/adapters/realtime/websocket/websocket-protocol.ts` | exact closed JSON frame decode/encode, duplicate key/structure/sequence/frame byte 검증 | realtime contracts, kernel JSON scanner | R-05 |
## 2. 추적한 contracts, ports, bootstrap, tests, docs
@@ -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`
@@ -43,6 +43,7 @@
| `src/adapters/browser-files/browser-file-vault.ts` | transient native File/handle 보관, opaque ref, inspection receipt, bounded range/source | file port/shared/result/policy registry. File이 application 경계를 넘지 않고 receipt가 exact file/profile에 묶이는 설계가 좋다. |
| `src/adapters/browser-files/create-browser-file-runtime.ts` | vault/picker/preview/download를 선택적으로 조립하고 일괄 dispose | 위 adapters 및 application contracts. optional capability를 제품 선택 없이 bootstrap에 암묵 조립하지 않는 점을 유지. preview 조립 전 GAP-01 gate 필요. |
| `src/adapters/browser-files/download-delivery-adapter.ts` | browser handoff, foreground save stream, bounded object URL download, integrity/progress/cancellation | file/authorized-download ports, policy registry, object URL lease, Result. STO-02와 STO-08; stream close truth/backpressure는 유지. |
| `src/adapters/browser-files/download-input-validation.ts` | download 요청 snapshot, policy/limit/activation 검증, presigned·browser-managed capability 검증, canonical handoff target 해석 | file/authorized-download ports, policy registry, `file-policy.ts`, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/browser-files/file-observer.ts` | file-safe observation DTO를 공통 browser observation으로 변환 | shared port/result. raw filename/ref 비노출 유지. |
| `src/adapters/browser-files/file-policy.ts` | policy input validation, MIME/extension/signature/hard byte caps, immutable resolved policy | file/shared contracts. closed allowlist 및 absolute ceiling을 유지. |
| `src/adapters/browser-files/index.ts` | browser-file public exports | 위 모듈. native implementation detail export 확장을 피한다. |
@@ -53,7 +54,9 @@
| 파일 | 책임 | 주요 의존성 / 리뷰 결과 |
| --- | --- | --- |
| `src/adapters/cache-storage/index.ts` | public cache policy/adapter barrel | optional public static cache만 export; private/range cache로 일반화하지 않는다. |
| `src/adapters/cache-storage/public-cache-codec.ts` | manifest 정규화·canonical digest 입력, marker/active pointer 검증, bounded control JSON 읽기, owned cache 이름, 검증 실패 → Result 매핑 | cache ports/result/policy. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-cache-policy.ts` | same-origin/public-only release 정책, URL/header/query/size/retention hard limits | cache ports/shared. STO-03 policy cross-field invariant 누락. 기본 policy에는 `vary`가 있어 기본-path 테스트는 통과한다. |
| `src/adapters/cache-storage/public-cache-response-validation.ts` | network/cached response 수용 검증: status, cache directive, Content-Type, Vary, bounded body, digest | `public-cache-codec.ts`, policy, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-response-cache-adapter.ts` | manifest canonicalization/digest, anonymous fetch, bounded body 검증, candidate marker-last staging, explicit activation, exact lookup/reverify, owned cleanup/inspect | cache ports/result/policy, CacheStorage/fetch/Crypto/Web Lock snapshot. STO-03~05 및 GAP-02. private/auth/opaque/206 거절과 current+previous 보존은 유지. |
### 1.4 `storage` root / IndexedDB
@@ -63,10 +66,10 @@
| `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 거절 유지. |
| `src/adapters/storage/indexeddb/indexeddb-records.ts` | runtime·maintenance·dataset binding이 함께 쓰는 저장 행 타입, 검증기, record 바이트 측정, `countBucket`/`failureOf` | IndexedDB port/shared/types. Q-6.5-7: 복사본 3벌을 하나로 합쳤다. 실패 코드는 호출부가 정한다(runtime `INVALID_INPUT`, maintenance `MIGRATION_FAILED`). budget의 `hardBudgetBytes` 상한은 binding 검증에서만 본다. |
| `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | generic repository open/read/query/CAS/delete, idempotency, retention, lifecycle purge, connection lifecycle | indexeddb ports/types/governance/failure/migrations. transaction `complete` truth, versionchange close, shared open/abort isolation, exact budgets 유지. lifecycle proof는 현재 문서 계약(형식 검증 후 폐기)과 일치하므로 결함으로 분류하지 않았다. |
| `src/adapters/storage/indexeddb/indexeddb-types.ts` | adapter-local codec/query/schema/dependency contracts | application indexeddb/shared ports. `isOldWriterDrainConfirmed()` boolean은 provider가 전체 window를 보장한다는 문서 전제; lease형으로 강화 권고. |
@@ -79,6 +82,7 @@
| `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | logical object/journal/budget/chunk refcount의 IDB authority; begin/files-ready/commit/rollback/reconcile pages | OPFS ports, IDB failure, policy. journal+object+budget CAS atomicity가 좋다. STO-01 수정에서 incomplete row를 cleanup 확인 전 삭제하지 않아야 한다. |
| `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | logical journal과 physical worker를 saga로 조정, put/open/remove, reconcile/policy maintenance | OPFS/shared ports, journal, worker gateway, policy. STO-01의 journal/physical compensation ordering 결함 위치. |
| `src/adapters/storage/opfs/opfs-policy.ts` | root/lock/chunk/object/RPC/reconcile/GC hard limits 및 scope validation | shared/opfs ports. opaque physical path와 absolute caps 유지. |
| `src/adapters/storage/opfs/opfs-prepared-object.ts` | page·journal·worker가 함께 쓰는 prepared-object 검증기 하나 | OPFS/shared ports, opfs-policy scope 검증. R-5.5: 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증하고 현재 정책값은 새 쓰기에만 적용. |
| `src/adapters/storage/opfs/opfs-worker-client.ts` | request correlation/timeout/abort/transferable chunking, worker gateway, streamed reads | protocol/policy/shared Result. STO-01의 untracked abort cleanup 및 STO-07의 shallow response parse. |
| `src/adapters/storage/opfs/opfs-worker-protocol.ts` | page↔DedicatedWorker request/response union 및 gateway contract | OPFS/shared ports. STO-07; protocol version/kind/effect certainty 추가 필요. |
| `src/adapters/storage/opfs/opfs-worker-runtime.ts` | DedicatedWorker OPFS physical layout, lock lease, immutable chunk, manifest/staging receipt, abort/finalize/remove/GC | protocol/policy/OPFS ports/Web Lock/Crypto. STO-01의 generation-only cleanup과 lease release 순서. sync handle `finally close` 등은 유지. |
+4 -1
View File
@@ -35,6 +35,7 @@
| --- | --- | --- | --- |
| `browser-transfer/index.ts` | 하위 capability export | KEEP | public export 증가는 각 capability 계획에서만 수행 |
| `presigned/index.ts` | presigned public surface | KEEP | `BT-PRE-04`에서 vault issuer 노출만 축소 검토 |
| `presigned/http-common.ts` | executor·provider 공용 HTTP 메커니즘(abort scope, status 표, Content-Length 파싱, body 취소) | KEEP | Q-6.1-9. 두 벌이던 사본을 합쳤다. status 표는 여기 한 벌만 둔다 |
| `presigned/incremental-sha256.ts` | streaming SHA-256 | KEEP | WebCrypto `digest()`로 바꾸면 전체 buffering이 되므로 교체 금지 |
| `presigned/presigned-capability-http-provider.ts` | BFF capability 발급, strict decode | CONTRACT_GAP | `BT-PRE-02`, `BT-PRE-03`, `BT-X-01` |
| `presigned/presigned-capability-vault.ts` | identity capability 보관/폐기 | REFACTOR | `BT-PRE-04` |
@@ -45,8 +46,10 @@
| `resumable-upload/index.ts` | resumable public surface | KEEP | facade 호환 유지 |
| `resumable-upload/indexeddb-checkpoint-store.ts` | scope-bound CAS store/admin | VERIFIED_DEFECT | `BT-UP-03` |
| `resumable-upload/presigned-upload-part-executor.ts` | multipart와 presigned bridge | VERIFIED_DEFECT | `BT-UP-04` |
| `resumable-upload/resumable-upload-runtime.ts` | session state/retry/part scheduling/commit | REFACTOR | `BT-UP-05`, `BT-UP-06` |
| `resumable-upload/resumable-upload-runtime.ts` | session state/retry/part scheduling/commit | REFACTOR | `BT-UP-05`, `BT-UP-06`. Q-6.1-10에서 검증·snapshot 래퍼를 분리 |
| `resumable-upload/runtime-dependencies.ts` | runtime 주입 의존성 검증과 메서드 snapshot, clock/random guard | KEEP | Q-6.1-10. runtime 파일에서 분리, 동작 불변 |
| `resumable-upload/runtime-policy.ts` | hard bound snapshot | KEEP | 값 변경은 contract migration으로만 수행 |
| `resumable-upload/upload-response-validation.ts` | session/status/part capability/receipt strict decoder | KEEP | Q-6.1-10. runtime 파일에서 분리, 동작 불변 |
| `resumable-upload/upload-byte-source.ts` | stream/range source snapshot과 hashing | KEEP/REFACTOR | runtime에서 source preparation Strategy로 주입 |
| `resumable-upload/upload-cancellation-channel.ts` | best-effort cross-context cancel hint | KEEP | backend/CAS가 authority라는 주석과 동작 유지 |
| `resumable-upload/upload-mutation-lock.ts` | Web Lock exclusive mutation | PLANNED_GAP | `BT-UP-07` |
@@ -30,6 +30,7 @@ Web Push는 현재 `AVAILABLE_NOT_COMPOSED`이고 제품 선택도 `NOT_SELECTED
| `service-worker-protocol.ts` | page-worker strict message codec/nonce | CONTRACT_GAP | `SW-06`, `SW-10` |
| `service-worker-removal.ts` | exact registration/cache ownership cleanup | VERIFIED_DEFECT | `SW-03` |
| `service-worker-static-assets.ts` | static manifest/install/cache policy | KEEP/REFACTOR | `SW-01`, `SW-05`, `SW-09` |
| `web-push/codec-primitives.ts` | 공유 검증 primitive(base64url decode, opaque id, authority, exact record) | KEEP | Q-6.6-12에서 4개 파일의 복사본을 합침. 복사본이 다르던 곳은 더 엄격한 쪽을 유지 |
| `web-push/index.ts` | public exports | KEEP | product selection 전 surface 확대 금지 |
| `web-push/notification-registry.ts` | closed copy/route registry | KEEP | arbitrary copy/URL 허용 금지 |
| `web-push/push-association-fence-store.ts` | durable authority state machine | VERIFIED_DEFECT | `WP-01`, `WP-02` |
+136 -124
View File
@@ -18,131 +18,143 @@
| 8 | `src/adapters/browser-files/browser-file-vault.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 9 | `src/adapters/browser-files/create-browser-file-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 10 | `src/adapters/browser-files/download-delivery-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 11 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 16 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 44 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 45 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 46 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 47 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 48 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 49 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 50 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 51 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 52 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 80 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 81 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 82 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 83 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 97 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 98 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 99 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 100 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 104 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 105 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 106 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 107 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 122 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 123 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 124 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 125 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 126 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 127 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 128 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 129 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 130 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 11 | `src/adapters/browser-files/download-input-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 16 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/http-common.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 44 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 45 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 46 | `src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts` | [Browser transfer](./04-browser-transfer.md) |
| 47 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 48 | `src/adapters/cache-storage/public-cache-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 49 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 50 | `src/adapters/cache-storage/public-cache-response-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 51 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 52 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/platform/json-member-scanner.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/platform/retry-after.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 84 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 85 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 86 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 87 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 88 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 100 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 101 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 102 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 103 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 104 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 107 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 108 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 109 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 110 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 111 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 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-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) |
합계: **133/133**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **145/145**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
## Feature-scoped adapter 리뷰 (`src/adapters/**` 밖)
+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
+5 -3
View File
@@ -57,7 +57,9 @@ RP-07 구현 이후 이 기반은 저장소 내부 디자인 시스템 플랫폼
3. 앱 셸, 예제와 reference feature는 public design-system barrel을 소비한다.
4. 문자 glyph는 semantic Lucide facade로 교체됐다.
5. token은 세 CSS 파일로 분리됐고 `theme.css`는 layout/component styling만
소유한다.
소유한다. `theme.css`는 import 순서만 정하는 진입점이고, 실제 규칙은
`styles/theme/` 아래 파일(base, shell, primitives, templates, pages,
responsive)에 같은 순서로 있다.
6. runtime gallery는 있지만 격리된 story, interaction story, 시각 회귀 기준선이
없다.
7. 사용자 문구가 한국어 literal로 고정되어 locale과 RTL 계약이 없다.
@@ -304,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