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
@@ -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초다.