chore(review): 1103 release·CI·성능 조치 브랜치를 합친다

Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-07 13-01~13-03 13-05 15-02~15-07

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	docs/operations/performance-evidence.md
#	scripts/lib/hosting-probe.ts
This commit is contained in:
DongHyeonka
2026-11-04 23:10:59 +09:00
45 changed files with 3393 additions and 1732 deletions
+13 -2
View File
@@ -40,8 +40,10 @@ that the host serves that release; while the slot is empty FE-GATE-019 is
Rollback changes the active pointer only after confirming that the prior
immutable release has a coherent HTML/assets/config/API/manifest tuple.
Serve the app over HTTP/2 or later. The entry preloads about 26 initial
JavaScript files in parallel. Over HTTP/1.1 they queue for six connections per
Serve the app over HTTP/2 or later. The entry preloads every initial
JavaScript file in parallel (`initialJsFiles` in
`config/performance/budgets.json` bounds how many; the current count is
`initialJavascript.files` in `config/scale/feature-shape-ceilings.json`). Over HTTP/1.1 they queue for six connections per
host, and the first screen on Fast 3G came about one second later than with the
initial chunks grouped (2026-11-03). Over HTTP/2 the difference was under
100 ms, so the template keeps the chunks split. A product that can only serve
@@ -49,3 +51,12 @@ HTTP/1.1 groups its initial chunks in `vite.config.ts` and measures again
whenever the shell changes ("초기 청크 수와 HTTP/1.1" in
[`performance-evidence.md`](../operations/performance-evidence.md), review
1101/14.4).
Serve JavaScript compressed (gzip, brotli or zstd). The bundle budget counts
gzip bytes; uncompressed, the initial JavaScript is about three times larger.
Both premises are declared in `config/hosting/cache-policy.json`
(`transport.alpnProtocols`, `hashedAsset.contentEncodings`), and the live probe
of FE-GATE-019 fails a host that does not meet them (review 1103/13-02). The
nginx example in
[`release-cache-rollback.md`](../operations/release-cache-rollback.md) turns
both on.
+1
View File
@@ -114,6 +114,7 @@ release admission refused for staging:
- FE-REG-ENV 행의 `required`·`defaultValue`는 zod 필드가 키가 없을 때 하는 것과 같게 적는다. 기본값이 없으면 `defaultValue: null`이다. 같은 테스트가 대조한다.
- `config/runtime/<profile>.json`: 환경별로 기능을 끄고 싶을 때(`FEATURE_OVERRIDES`).
- `src/features/product-capabilities.ts`의 선택 런타임(`PRODUCT_RUNTIME_CAPABILITY_SELECTION`): Service Worker를 켤 때. 아래 "SW 켜기"를 본다.
- `config/ci/product-gates.json`: 배포 job(`deployment`)을 채우거나 제품 전용 merge 검사(`PRODUCT-GATE-NNN`)를 더할 때. 템플릿 파일 `config/ci/gates.json`은 고치지 않는다. 형식은 [`ci-quality-gates.md`](../operations/ci-quality-gates.md)에 있다.
- `package.json`, lockfile, `config/security/dependency-change-evidence.json`: 계약 패키지를 더할 때(B절).
정본 표에 없는 것:
+71 -5
View File
@@ -335,17 +335,60 @@ contract rejects a production gate command that builds or omits the release root
The hosting gate FE-GATE-019 also reads `.release/promoted-release`: it checks
that archive's `dist` and requires the live host to serve a
`release-manifest.json` with the candidate's `buildId` and `releaseId`, so a
host still serving an earlier release fails (1101/13-01). The workflow deploys
host still serving an earlier release fails (1101/13-01). Because a rebuild in
the same run shares those names, the served `config.json` must also equal the
candidate's outside the two emergency switches and the served `index.html` must
name the candidate's entry script (1103/13-01). The workflow deploys
nothing itself. Between `promotion` and `production_gate` sits the `deployment`
job, the project's deployment slot. It is empty by default: it reports
`deployed=false`, FE-GATE-019 does not probe the host and ends `UNVERIFIED`
(exit 3), and the production stage stays open. To fill it, edit the
`deployment` job in `config/ci/gates.json` and run `corepack pnpm
generate:ci-workflow`. The contract allows the steps `checkout`, `setup-node`,
(exit 3), and the production stage stays open. To fill it, set `deployment`
in the product-owned `config/ci/product-gates.json` and run `corepack pnpm
generate:ci-workflow` (1103/12-07):
```json
{
"schemaVersion": 1,
"deployment": {
"script": "deploy:desktop",
"environment": [
{ "name": "DEPLOY_HOST", "value": "${{ vars.DEPLOY_HOST }}" },
{ "name": "DEPLOY_SSH_KEY", "value": "${{ secrets.DEPLOY_SSH_KEY }}" }
]
},
"mergeGates": []
}
```
The template renders the rest of the slot: it downloads the `promoted-release`
transfer, extracts it to `.release/promoted-release` against the candidate
digest, then runs the script, which deploys `.release/promoted-release/dist`.
`environment` takes only `vars.*` and `secrets.*` values. The template ships
this file empty and never changes it, so a template sync does not meet it;
`config/ci/gates.json` stays the template's, and its contract baseline counts
the template contract only. A slot filled in both files is refused.
`mergeGates` adds the product's own checks, such as a contract check against
the paired backend: `{ "id": "PRODUCT-GATE-001", "name": "backend-contract",
"script": "check:backend-contract" }`. Ids are `PRODUCT-GATE-NNN`; the
`FE-GATE-NNN` ids, their commands, artifacts and readiness formula stay the
template's. Each runs as `corepack pnpm <script>` in the `product_merge_gate`
job, on the same condition as `merge_gate`, without browsers and without the
gate log and evidence artifacts of `ci:gate`. Make that job a required check
of the branch where it has to block a merge. `check:ci` refuses a script that
`package.json` does not define and counts these scripts as gated.
The slot as stored in `config/ci/gates.json` still follows the same contract
rules. The contract allows the steps `checkout`, `setup-node`,
`frozen-install`, `download` (the `promoted-release` transfer), `extract`, and
one final `deploy` step whose `script` names a package script. Its variables
may only be the `CANDIDATE_ARCHIVE_SHA256` digest of `immutable_build` and
`vars.*` or `secrets.*` values. The `deploy` step writes `deployed=true` only
`vars.*` or `secrets.*` values. A slot with a deploy script must download only
the `promoted-release` transfer, extract its `release-candidate.tar.gz` and
bind the digest, so the script deploys the promoted candidate rather than a
rebuild (1103/13-01). `secrets.*` values are rendered on the `deploy` step
alone, not on the job, so checkout, setup-node and the download action never
see them (1103/13-05). The `deploy` step writes `deployed=true` only
after the script succeeds. The job owns no gate, so filling it changes neither
gate ownership nor the contract baseline. Browser boot, live API traffic, smoke after a provider
switch, and anything the runbook marks as needing provider verification are
@@ -433,6 +476,18 @@ Repository variables required by higher tiers:
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.
FE-GATE-027 then runs `scan:dependency-advisories` (1103/13-03). It applies
`config/security/vulnerability-policy.json` and its exceptions to the
registry's advisory report for the lockfile (pnpm's audit command with
`--json`) and writes the result to the gate log
and `artifacts/security/dependency-advisories.json`: `PASS`,
`POLICY_VIOLATION` (what the production promotion would refuse, with the
findings) or `UNVERIFIED` (no registry). It never fails the gate, because an
advisory database that changes under unchanged code would break releases;
the signed verdict of the vulnerability provider still decides promotion.
`renovate.json` opens security update PRs once a Renovate runner is attached;
a dependency update re-approves the dependency baseline in the same change
(`update:dependency-baseline`).
- `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
@@ -441,6 +496,17 @@ Repository variables required by higher tiers:
`PROVENANCE_PUBLIC_KEY_PATH`, and `PROVENANCE_KEY_ID` for separately managed
trusted Ed25519 verification material
Advisories at or above the policy's `high` that `scan:dependency-advisories`
reports for this lockfile, checked 2026-11-04 (review 1103/13-03). Check again
by 2026-12-04 or when the update below is made. The development-only ones
(storybook, vite, vitest, undici, brace-expansion, nanoid, source-map-js) were
updated within their declared ranges and are gone.
| Advisory | Package | Fixed in | Why it is not updated yet |
|---|---|---|---|
| GHSA-mrhx-c7xc-m3w5 (high) | `zod` 4.4.3 (production) | 4.6.6 | A direct production upgrade needs a `config/security/dependency-change-evidence.json` entry whose reviewer is not its owner. 4.6.7 also adds about 7 KB gzip of initial JavaScript, over the bundle budget, so the update needs a budget decision as well. The app reads HTTP bodies with a byte limit, which narrows the large-collection input the advisory needs (review estimate) |
| GHSA-qwww-vcr4-c8h2 (high) | `react-router` 7.18.1, through `react-router-dom` (production) | 7.18.2 | Same evidence rule. The advisory concerns RSC mode, which this browser-router SPA does not use (review estimate, not verified). 7.18.5 adds about 470 B of initial JavaScript |
두 provider role은 서로 다른 key ID뿐 아니라 canonical DER-SPKI public-key bytes도
사용해야 한다. 동일 key를 서로 다른 ID로 재등록한 구성도 finalizer가 거절한다.
+60 -21
View File
@@ -3,7 +3,9 @@
Performance evidence is deliberately split by measurement context:
- `bundle.json` records production build output and enforces initial JavaScript
at 200 KiB gzip and every lazy chunk at 120 KiB gzip.
at 200 KiB gzip, the number of initial JavaScript files (`initialJsFiles`),
and every lazy chunk at 120 KiB gzip. A failure names each exceeded limit,
the measured value and the excess (1103/15-03).
- `lab.json` records Chromium/runner/viewport/network/CPU/cache/build context and
enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms.
- `field-web-vitals.json` records consent-filtered, route-ID aggregated,
@@ -12,23 +14,33 @@ Performance evidence is deliberately split by measurement context:
## 번들 예산의 기준선과 여유
리뷰 0925/13-14, 1101/15-02. 예산은 `config/performance/budgets.json`에 있고
`scripts/check-bundle.ts`(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본
화면만으로 초기 JS 예산의 98.9%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를
리뷰 0925/13-14, 1101/15-02, 1103/15-02. 예산은 `config/performance/budgets.json`에
있고 `scripts/check-bundle.ts`(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본
화면만으로 초기 JS 예산의 대부분을 쓴다. 첫 기능을 추가하기 전에 아래 기록을
보고 예산을 정한다.
| 항목 | 값 |
기준선 숫자는 이 문서에 적지 않는다. 손으로 적은 숫자는 두 번 낡았다. 기록은
`config/scale/feature-shape-ceilings.json`의 `initialJavascript` 한 곳이다.
| 칸 | 뜻 |
|---|---|
| 초기 JS 예산 | 204,800 gzip bytes(200 KiB) |
| 템플릿 기준선(2026-11-01, 커밋 `298201f`) | 202,509~202,522 gzip bytes, 16개 파일. local 프로필, `VITE_BUILD_ID`가 `local-build`일 때와 CI 모양(`gitea-<run>-<attempt>`)일 때다. 빌드 ID가 번들에 들어가므로 빌드마다 수십~수백 바이트 다르다 |
| 여유 | 약 2,280 bytes(1.1%) |
| 기능 하나를 더할 때 | 참조 기능 모양 복사본 하나에 약 +650~750 bytes(`298201f` 측정, 상한은 참조 기능과 함께 지워지는 tests/unit/feature-shape-growth.test.ts의 1 KiB). 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다 |
| lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 lazy JS는 17개, 합계 28,204 bytes이고 가장 큰 것은 `use-reference-feature` 8,386 bytes다 |
| `gzipBytes`, `files` | 템플릿 그대로의 초기 JS gzip bytes와 파일 수(entry 포함) |
| `perFeatureGzipBytes` | 있는 context에 참조 기능 모양 기능을 하나 더할 때 느는 초기 JS. 상한 1 KiB |
| `perContextGzipBytes` | 새 context를 하나 더할 때 느는 초기 JS. 상한 512 B |
- `tests/unit/feature-shape-growth.test.ts`(unit, merge 단계)가 매번 빌드해 이
값을 재고, 상한을 넘거나 기록과 다르면(합계 1% 초과, 파일 수 불일치, 기능·
context 비용 10% 초과) 실패한다. 실패 메시지에 잰 값이 나온다.
- 기록을 고칠 때는 `node scripts/scale/measure-feature-shape-growth.ts
--initial-baseline --write`를 돌리고 같은 변경에 넣는다.
- 여유는 예산에서 `gzipBytes`를 뺀 값이다. 그것을 `perFeatureGzipBytes`로 나누면
더 넣을 수 있는 기능 수다. 새 context마다 `perContextGzipBytes`가 더 든다.
- 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다.
lazy chunk 예산은 파일마다 120 KiB(`lazyChunkGzipBytes`)다.
청크 이름으로 크기를 판단하지 않는다. rolldown은 공용 청크에 안에 든 모듈
하나의 이름을 붙인다. 예를 들어 `render-boot-failure` 청크(58.6 KB)의 대부분은
react-dom이고, `design-system` 청크(48.2 KB)에는 react-router가 들어 있다.
아래는 출처별 크기다. sourcemap 빌드에서 minify된 바이트를 원래 모듈에 나눠
하나의 이름을 붙인다. 아래는 2026-11-01(`298201f`)에 잰 출처별 크기다. 지금
빌드와는 조금 다르다. sourcemap 빌드에서 minify된 바이트를 원래 모듈에 나눠
붙이고 묶음마다 따로 gzip했다. 따로 압축하므로 합은 실제 합계와 조금 다르다.
| 출처 | minify bytes | 단독 gzip bytes |
@@ -52,8 +64,7 @@ react-dom이고, `design-system` 청크(48.2 KB)에는 react-router가 들어
(`scripts/lib/classify-vite-bundle.ts`). entry는 앱 그래프의 평가 실패를
보고하려고 그 둘을 dynamic import로 읽을 뿐이고, 첫 화면에 항상 필요하다
(0925/09-03). 그 밖의 dynamic import chunk는 lazy다.
- 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.6 KB gzip)는 예산에 들어가지
않는다.
- 합계는 JavaScript만 센다. CSS(`index-*.css`)는 예산에 들어가지 않는다.
- gzip은 Node `zlib.gzipSync` 기본 수준(6)으로 잰다
(`scripts/lib/release-candidate.ts`). 호스팅이 brotli로 보내면 전송 크기는 더
작다. 예산은 gzip 기준 그대로 둔다.
@@ -102,12 +113,12 @@ the example can never serve as production evidence.
리뷰 1101/14.4. 08-08은 초기 JS 바이트를 줄이는 대신 초기 파일 수를 늘렸다
(`vite.config.ts`의 `moduleSideEffects` 주석). HTTP/1.1에서 브라우저는 한
호스트에 연결을 6개까지만 연다. 파일이 많으면 요청이 줄을 서서 왕복이 는다.
그래서 지금 빌드와 작은 초기 청크를 하나로 묶은 빌드를 쟀다(2026-11-03,
커밋 `ec7435c`).
그래서 그때 빌드와 작은 초기 청크를 하나로 묶은 빌드를 쟀다(2026-11-03,
커밋 `ec7435c`). 아래 두 표의 파일 수와 바이트는 그 커밋의 값이다.
| 빌드 | 초기 JS 파일(entry 포함) | 초기 JS gzip(B) | 첫 화면까지 JS 요청 | Fast 3G 첫 화면 | Fast 4G 첫 화면 |
|---|---:|---:|---:|---:|---:|
| 지금 | 26 | 202,782 | 27 | 5,887 ms | 1,874 ms |
| `ec7435c` | 26 | 202,782 | 27 | 5,887 ms | 1,874 ms |
| (가) 08-08이 나눈 초기 primitive 청크 4개(`field`·`button`·`select`·`page-templates`)를 하나로 | 23 | 201,818 | 24 | 5,426 ms | 1,764 ms |
| (나) 묶을 수 있는 초기 청크 14개를 하나로 | 13 | 198,673 | 14 | 4,930 ms | 1,535 ms |
@@ -116,7 +127,7 @@ the example can never serve as production evidence.
| 빌드 | Fast 3G 첫 화면 | Fast 4G 첫 화면 |
|---|---:|---:|
| 지금 | 4,793 ms | 1,444 ms |
| `ec7435c` | 4,793 ms | 1,444 ms |
| (가) | 4,769 ms | 1,440 ms |
| (나) | 4,708 ms | 1,422 ms |
@@ -128,7 +139,7 @@ the example can never serve as production evidence.
- 매번 새 browser context에서 캐시 없이 `/`를 연다. 첫 화면은 boot 셸이
사라지고 `#main-content h1[data-route-heading]`가 DOM에 들어온 시각이다
(`performance.now()`).
- 세 빌드를 번갈아 7번씩 재고 중앙값을 적었다. 7번의 범위는 지금 5,866~6,077 ms,
- 세 빌드를 번갈아 7번씩 재고 중앙값을 적었다. 7번의 범위는 `ec7435c` 5,866~6,077 ms,
(가) 5,384~5,652 ms, (나) 4,891~5,032 ms다(Fast 3G). loadavg는 HTTP/1.1
측정 때 6~20, HTTP/2 측정 때 3~6이었다. 그래서 두 표끼리는 비교하지 않는다.
- CDP 지연은 요청마다 붙는다. 연결 수립(TCP·TLS) 비용은 따로 재지 않았다.
@@ -154,6 +165,34 @@ the example can never serve as production evidence.
버렸다.
- HTTP/2에서는 (나)도 Fast 3G 85 ms, Fast 4G 22 ms 차이다(위 둘째 표).
그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. HTTP/1.1로만 서빙해야 하는
그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. 초기 파일 수는
`config/performance/budgets.json`의 `initialJsFiles`가 막는다(1103/15-05). 초기
파일을 늘리는 변경은 그 값을 같이 고치고, 이유를 같은 변경에 적는다. HTTP/1.1로만 서빙해야 하는
제품은 (나)처럼 초기 청크를 묶는 그룹을 `vite.config.ts`에 넣는다. 그 목록은
셸을 바꿀 때마다 위 방법으로 다시 잰다.
## build id와 재방문 캐시
리뷰 1103/15-06(1101 O1, 0929/13-03). build id는 부트 실패 화면이 보여 주므로
그 청크에 들어간다. 해시 자산은 1년 `immutable`로 캐시되지만, build id가 든
청크와 그 청크를 import하는 청크는 release마다 이름이 바뀐다. react-dom이 그
청크 안에 있을 때는 코드가 같아도 release마다 초기 JS의 절반을 다시 받았다.
판단: react-dom과 scheduler를 자기 청크(`vite.config.ts`의 `react-dom` 그룹)로
뺀다. 2026-11-04 `VITE_BUILD_ID`만 다른 두 빌드(`gitea-101-1`, `gitea-102-1`)를
비교했다.
| 빌드 | 이름이 바뀐 초기 파일 | 바뀐 초기 JS gzip(B) | 초기 JS gzip(B) | 초기 파일 |
|---|---|---:|---:|---:|
| 분리 전 | `boot`, `index`, `render-boot-failure` | 99,785 (49.4%) | 201,857 | 25 |
| 분리 뒤 | `boot`, `index`, `render-boot-failure` | 44,297 (22.0%) | 201,552 | 25 |
- lazy 파일은 두 경우 모두 0 B 바뀐다.
- 초기 파일 수는 그대로다. react-dom의 작은 진입 모듈(1.3 KB)이 같은 청크로
합쳐졌다.
- `boot`는 build id로 설정 문서를 대조하므로 계속 바뀐다. build id를 JS에 넣지
않고 `release-manifest.json`에서만 읽으면 더 줄지만, 부트 실패 화면이 build
id를 보여 주는 계약을 바꿔야 해서 하지 않았다.
- 부트 실패 화면은 여전히 앱 그래프의 모듈 없이 그려진다(09-03,
`tests/e2e/boot-module-failure.spec.ts`). 이름이 유지되는지는
`tests/unit/build-environment-bundle.test.ts`가 본다.
+27
View File
@@ -85,6 +85,24 @@ evidence for this one (review 1101/13-01). That release is
`<release-root>/dist` with `-- --release-root <extracted archive>` (FE-GATE-019
passes the promoted archive), otherwise the local `dist`.
Those two names come from the CI run, so a release rebuilt in the same run
carries them as well. The served `config.json` must therefore equal the
release's `dist/config.json`, the document release admission (FE-GATE-027)
admitted, in every field except the two emergency switches
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` (FE-RB-001), and the served
`index.html` must name the release's entry script (review 1103/13-01).
The probe also checks the two serving premises the bundle budget and the split
initial chunks rest on (review 1103/13-02): the entry script arrives with a
`Content-Encoding` from `hashedAsset.contentEncodings` (the budget counts gzip
bytes; uncompressed, the initial JavaScript is about three times larger), and
the TLS handshake negotiates a protocol from `transport.alpnProtocols` (`h2`;
over HTTP/1.1 the initial files queue for six connections). A host that cannot
meet them fails FE-GATE-019; a product that has to serve that way changes the
declaration in `config/hosting/cache-policy.json` in the same change that
groups its initial chunks ("초기 청크 수와 HTTP/1.1" in
[`performance-evidence.md`](performance-evidence.md)).
### Example: nginx on a single server
Written by hand for the default base path `/`; nothing in CI runs it. The live
@@ -105,9 +123,18 @@ add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
```nginx
server {
listen 443 ssl;
# nginx 1.25.1 and later; before it, `listen 443 ssl http2;`.
http2 on;
server_name app.example.com;
# ssl_certificate / ssl_certificate_key ...
# The bundle budget counts gzip bytes, and FE-GATE-019 fails an
# uncompressed entry script (cache-policy.json `hashedAsset`). nginx
# compresses only text/html unless gzip_types names the rest.
gzip on;
gzip_vary on;
gzip_types text/javascript application/javascript application/json text/css image/svg+xml;
# The active release directory. Switch it with an atomic symlink rename.
root /srv/frontend/current;