docs: 문서 체계 후속으로 VD 보완 표시와 낡은 서술을 고친다 #20
@@ -251,7 +251,7 @@
|
||||
},
|
||||
{
|
||||
"name": "adapters-do-not-know-other-concrete-adapters",
|
||||
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
|
||||
"comment": "docs/architecture/layers.md, section \"adapter kernel\": a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
|
||||
"severity": "error",
|
||||
"from": {
|
||||
"path": "^src/adapters/([^/]+)/"
|
||||
|
||||
+5
-1
@@ -43,7 +43,7 @@
|
||||
|
||||
## 미출시 — `48c7695b` → 정리 단계
|
||||
|
||||
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`), 4단계에 남은 R2·R5 검사(브랜치 `chore/layout-rules-r2-r5`, `3f64c689`부터 브랜치 끝까지)를 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
|
||||
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`), 4단계에 남은 R2·R5 검사(브랜치 `chore/layout-rules-r2-r5`, `3f64c689`부터 브랜치 끝까지), 문서 체계 후속(브랜치 `claude/fe-b-docs-followup`, `8acf07c2`부터 브랜치 끝까지)을 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
|
||||
|
||||
### 먼저 할 일 (BREAKING)
|
||||
|
||||
@@ -123,6 +123,10 @@
|
||||
- 문서 검사는 라우트별 수동 접근성 기록(`docs/accessibility/route-reviews/`)을 문서로 보지 않는다. 정해진 영어 키 형식의 게이트 입력이다 (`e9e98b8a`).
|
||||
- `SPEC.md`의 공통 완료 기준은 하네스 범위가 `docs/work/improve.md` 5절로 옮겼다. 이 범위가 먼저 만든 사본 `docs/manual/reference/done-criteria.md`는 지웠다(`ee5e19f4`에서 만들고 뒤 커밋에서 지움).
|
||||
- 설정 파일의 설명 칸(recipe 카탈로그, runbook 등록, 규모 상한, 짝 백엔드 pin의 `fact`, secret scan 허용 이유)을 한국어로 옮겼다. 키와 값의 모양은 그대로다 (`309631e4`).
|
||||
- 결정 뒤 본문을 제자리에서 고친 VD-09·11·13의 상태를 「채택(보완)」으로 올리고, 맨 아래 「보완」 절에 고친 날짜와 커밋을 적었다. 본문은 그대로다 (`8acf07c2`).
|
||||
- 번역할 때 남겨 둔 낡은 서술 일곱 곳을 코드·설정에 맞췄다: 계약 파일 수는 `src/contracts/`를 가리키고, Local Draft는 테스트 fixture라고 쓰고, 초기 JS 파일 수의 기준은 feature가 없는 빌드다. `.dependency-cruiser.json` 주석은 절 이름을 쓰고, runbook 문서 제목은 `runbooks.json` title과 같다. zod advisory 행의 잰 버전을 밝히고, runbook record 고정 경로 문단의 두 문장을 제자리로 옮겼다 (`374af986`).
|
||||
- `drill:runbook`의 복구 확인 항목 이름이 `runbooks.json`의 `recoveryEvidence`와 같다. `record.json`의 `assertion` 값이 한국어가 되고, `tests/unit/runbook-drill.test.ts`가 이름과 순서를 대조한다. 자기 `recoveryEvidence`를 고쳤으면 drill 이름도 같이 고친다 (`6571d8cb`).
|
||||
- `config/ci/ungated-scripts.json`의 `reason`을 한국어로 옮겼다 (`b824195c`).
|
||||
|
||||
### 알려진 제한
|
||||
|
||||
|
||||
@@ -3,75 +3,75 @@
|
||||
"entries": [
|
||||
{
|
||||
"script": "check:backend-contract-drift",
|
||||
"reason": "1103/12-06, 1105/07-01. Compares the paired backend checkout (--backend, or beside the main checkout) with config/contracts/backend-contract-pin.json: the copied table excerpt and the answer table against the pinned document, and the document between the pin and the backend's HEAD. CI checks out this repository alone, so a gate has no backend to read; with no checkout the script exits 2 (not compared), never 0. The gated half is tests/unit/backend-contract-pin.test.ts (test:unit), which holds the Envelope table to the answer table and the answer table to the excerpt. Run this after pulling the backend and before moving the pin (docs/manual/01-add-a-feature.md)."
|
||||
"reason": "1103/12-06, 1105/07-01. 짝 백엔드 checkout(--backend, 없으면 메인 checkout 옆)을 config/contracts/backend-contract-pin.json과 비교한다. 옮겨 둔 표 발췌와 답 표를 pin한 문서와 대조하고, pin과 백엔드 HEAD 사이에 문서가 바뀌었는지 본다. CI는 이 repo만 checkout하므로 게이트에는 읽을 백엔드가 없다. checkout이 없으면 이 script는 0이 아니라 2(비교하지 못함)로 끝난다. 게이트가 도는 쪽은 tests/unit/backend-contract-pin.test.ts(test:unit)이고, Envelope 표를 답 표에, 답 표를 발췌에 맞춰 본다. 백엔드를 pull한 뒤와 pin을 옮기기 전에 돌린다(docs/manual/01-add-a-feature.md)."
|
||||
},
|
||||
{
|
||||
"script": "check:feature-index",
|
||||
"reason": "Local check that the generated indexes (src/.generated/, not committed) are current, and the first step of verify:extreme-scale (scripts/verify-extreme-scale.ts), itself a local run. A gate gains nothing from it: every gate script regenerates the indexes first (generate-product-feature-index.ts)."
|
||||
"reason": "커밋하지 않는 생성 색인(src/.generated/)이 최신인지 보는 로컬 검사이고, 그 자체가 로컬 실행인 verify:extreme-scale(scripts/verify-extreme-scale.ts)의 첫 단계다. 게이트에 넣어도 얻는 것이 없다. 모든 게이트 script가 먼저 색인을 다시 만든다(generate-product-feature-index.ts)."
|
||||
},
|
||||
{
|
||||
"script": "check:http-scenario-evidence",
|
||||
"reason": "Run by scripts/run-http-scenario-evidence.ts, which is test:http-scenario-evidence in FE-GATE-007; that runner calls it by name after the scenario catalog."
|
||||
"reason": "scripts/run-http-scenario-evidence.ts가 돌린다. 이 runner는 FE-GATE-007의 test:http-scenario-evidence이고, scenario catalog 다음에 이 script를 이름으로 부른다."
|
||||
},
|
||||
{
|
||||
"script": "check:http-scenario-evidence:fixture",
|
||||
"reason": "Negative fixture run by scripts/run-http-scenario-evidence.ts (test:http-scenario-evidence, FE-GATE-007), which requires it to fail with TEST-EVIDENCE-EXECUTION-ID-MISSING."
|
||||
"reason": "scripts/run-http-scenario-evidence.ts(test:http-scenario-evidence, FE-GATE-007)가 돌리는 음성 fixture다. 그 runner는 이 script가 TEST-EVIDENCE-EXECUTION-ID-MISSING으로 실패해야 통과로 본다."
|
||||
},
|
||||
{
|
||||
"script": "check:remediation-ledger",
|
||||
"reason": "Checks the prose ledger of the 2026-08-14 adapter re-review (docs/operations/adapter-remediation-ledger.md) against test-file markers and the file-transfer bundle budget. It is a history record run by hand, not a current contract: it fails when a product removes the optional file-transfer recipe or when a test split moves a marked test to another file, and neither should block a merge. Run it after moving those tests or changing that budget, and point the ledger rows at the new files."
|
||||
"reason": "2026-08-14 adapter 재검토의 문장 원장(docs/operations/adapter-remediation-ledger.md)을 테스트 파일 표식과 file-transfer 번들 예산에 대조한다. 지금 계약이 아니라 손으로 돌리는 이력 기록이다. 제품이 선택 recipe인 file-transfer를 지우거나 테스트를 나누다 표식이 있는 테스트가 다른 파일로 옮겨 가면 실패하는데, 둘 다 merge를 막을 일이 아니다. 그런 테스트를 옮기거나 그 예산을 바꾼 뒤에 돌리고, 원장 행이 새 파일을 가리키게 고친다."
|
||||
},
|
||||
{
|
||||
"script": "check:scale:baseline",
|
||||
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
|
||||
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
|
||||
},
|
||||
{
|
||||
"script": "check:scale:main",
|
||||
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
|
||||
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
|
||||
},
|
||||
{
|
||||
"script": "check:scale:nightly",
|
||||
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
|
||||
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
|
||||
},
|
||||
{
|
||||
"script": "check:scale:release",
|
||||
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
|
||||
"reason": "CI 밖의 scale 단계다(scripts/scale/run-scale-profile.ts). baseline-regression을 포함하는데, 이 검사는 config/scale/benchmark-baseline.json을 기록한 CPU 모델에서만 시간을 비교하고 다른 곳에서는 incomplete로 보고한다(리뷰 11-03). 그 기계에서 돌린다. CPU와 상관없는 pr 단계는 FE-GATE-005에서 돈다."
|
||||
},
|
||||
{
|
||||
"script": "check:test-evidence",
|
||||
"reason": "Local all-in-one run. CI splits it: check:test-evidence:browser (--skip-scenario-executions) in FE-GATE-008 after the browser suites, and the scenario part through test:http-scenario-evidence in FE-GATE-007."
|
||||
"reason": "한 번에 모두 보는 로컬 실행이다. CI는 이것을 나눈다. FE-GATE-008이 브라우저 suite 뒤에 check:test-evidence:browser(--skip-scenario-executions)를 돌리고, scenario 부분은 FE-GATE-007의 test:http-scenario-evidence가 맡는다."
|
||||
},
|
||||
{
|
||||
"script": "check:test-evidence:source",
|
||||
"reason": "--source-only is a subset of check:test-evidence:browser (FE-GATE-008), for a quick local run without browser results."
|
||||
"reason": "--source-only는 check:test-evidence:browser(FE-GATE-008)의 일부다. 브라우저 결과 없이 로컬에서 빨리 돌릴 때 쓴다."
|
||||
},
|
||||
{
|
||||
"script": "drill:runbooks",
|
||||
"reason": "Local shortcut for all five drills. CI runs each drill as its own production gate (FE-GATE-021 to FE-GATE-025) through drill:runbook."
|
||||
"reason": "다섯 drill을 한 번에 돌리는 로컬 단축 명령이다. CI는 drill마다 drill:runbook으로 따로 production 게이트(FE-GATE-021~FE-GATE-025)를 돌린다."
|
||||
},
|
||||
{
|
||||
"script": "test:all",
|
||||
"reason": "Local aggregate of suites the gates run one by one (FE-GATE-004 to FE-GATE-007). The removal checks in FE-GATE-020 run it inside their fixtures through scripts/lib/removal-fixture.ts, not through the package script graph."
|
||||
"reason": "게이트가 하나씩 돌리는 suite(FE-GATE-004~FE-GATE-007)를 묶은 로컬 명령이다. FE-GATE-020의 제거 검사는 package script 그래프가 아니라 scripts/lib/removal-fixture.ts를 거쳐 자기 fixture 안에서 이것을 돌린다."
|
||||
},
|
||||
{
|
||||
"script": "test:e2e:dev",
|
||||
"reason": "Runs tests/e2e against the Vite dev server (playwright.dev.config.ts) for local debugging. FE-GATE-008 runs the same specs against the production build (test:e2e)."
|
||||
"reason": "로컬 디버깅용으로 tests/e2e를 Vite 개발 서버(playwright.dev.config.ts)에 돌린다. FE-GATE-008은 같은 spec을 production 빌드에 돌린다(test:e2e)."
|
||||
},
|
||||
{
|
||||
"script": "test:extreme-scale:focused",
|
||||
"reason": "Part of verify:extreme-scale. All its paths run in FE-GATE-005 except tests/scale/global-local-independence.test.ts, which belongs to the main scale tier (see config/ci/ungated-tests.json)."
|
||||
"reason": "verify:extreme-scale의 일부다. 경로는 모두 FE-GATE-005에서 돈다. 예외는 main scale 단계에 속하는 tests/scale/global-local-independence.test.ts다(config/ci/ungated-tests.json 참고)."
|
||||
},
|
||||
{
|
||||
"script": "test:visual:update",
|
||||
"reason": "Rewrites the visual snapshots; it is an update command, not a check. FE-GATE-008 runs test:visual."
|
||||
"reason": "visual snapshot을 다시 쓰는 갱신 명령이지 검사가 아니다. FE-GATE-008은 test:visual을 돌린다."
|
||||
},
|
||||
{
|
||||
"script": "verify:extreme-scale",
|
||||
"reason": "Local aggregate of 24 scripts (scripts/verify-extreme-scale.ts). Its CPU-independent parts run in gates; the main, nightly and release scale tiers need the baseline CPU (see check:scale:main)."
|
||||
"reason": "package script 여러 개를 차례로 돌리는 로컬 묶음이다. 목록은 scripts/verify-extreme-scale.ts의 EXTREME_SCALE_GATES다. CPU와 상관없는 부분은 게이트에서 돌고, main·nightly·release scale 단계는 기준 CPU가 필요하다(check:scale:main 참고)."
|
||||
},
|
||||
{
|
||||
"script": "verify:promotion",
|
||||
"reason": "Re-verifies a promotion bundle archived by an earlier run (13-04, --archived) with provider trust keys and EXPECTED_PROMOTION_* inputs of that run. In CI the promotion job verifies the same bundle through scripts/stage-verified-promotion.ts before it uploads it."
|
||||
"reason": "앞선 run이 보관한 promotion bundle(13-04, --archived)을 그 run의 provider 신뢰 key와 EXPECTED_PROMOTION_* 입력으로 다시 검증한다. CI에서는 promotion job이 같은 bundle을 올리기 전에 scripts/stage-verified-promotion.ts로 검증한다."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: lockfile 전체에서 의존성 목록·라이선스·SBOM·출처 증명을 만들고, 외부 취약점 보고와 서명된 증거가 없으면 승격(promotion)을 실패로 둔다는 결정이다.
|
||||
- 현재 정본: `docs/security/supply-chain.md`
|
||||
@@ -120,3 +120,10 @@ attestation transparency/retention과 비밀 관리를 결정해야 한다.
|
||||
`FAIL_UNVERIFIED`로 돌아간다. local inventory, lock integrity, license, SBOM,
|
||||
secret, reproducibility와 actual diff gate는 유지한다. scanner 장애를 이유로
|
||||
promotion을 PASS로 변경하지 않는다.
|
||||
|
||||
## 보완
|
||||
|
||||
> 머리 블록은 2026-11-08에, 이 절은 2026-11-12에 더했다. 아래 고침은 기록 규칙(2026-11-08)이 생기기 전에 본문을 제자리에서 고친 것이다. 그래서 위 본문은 결정한 때의 원문이 아니라 마지막 고침 뒤의 내용이다. 처음 커밋한 본문은 `git show 8b4f875c:docs/architecture/decisions/VD-09-supply-chain-evidence.md`로 본다.
|
||||
|
||||
- 2026-07-30 (`6c52cdb9`): 「실행 경계와 증적」 절의 generator·coherence·secret scan·reproducibility 스크립트 경로를 `.mjs`에서 `.ts`로 바꿨다.
|
||||
- 2026-08-02 (`92e5cace`): 결정 6~11번, 「실행 경계와 증적」 도식, 「검증」 절, 「Rollback」 절을 고쳤다. 외부 provider 입력을 `immutable_build` archive 하나와 provider job 둘, Ed25519 서명 검증으로 바꿨고, 결정 항목이 10개에서 11개가 됐다.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-27
|
||||
- 요약: File·Blob·파일 선택기·IndexedDB·OPFS·Cache Storage를 기존 `StoragePort`와 섞지 않는 별도 경계로 두고, reference runtime은 제품에 조립하지 않은 채 둔다는 결정이다.
|
||||
- 현재 정본: `src/adapters/browser-files/`, `src/adapters/storage/`, `config/recipes/frontend-capability-recipes.json`
|
||||
@@ -277,3 +277,9 @@ test, build와 optional catalog가 유지되는지 검증한다.
|
||||
|
||||
schema downgrade, blanket `deleteDatabase()`, `caches.keys()` 전체 삭제와 사용자
|
||||
filename 기반 OPFS 삭제는 rollback 수단으로 금지한다.
|
||||
|
||||
## 보완
|
||||
|
||||
> 머리 블록은 2026-11-08에, 이 절은 2026-11-12에 더했다. 아래 고침은 기록 규칙(2026-11-08)이 생기기 전에 본문을 제자리에서 고친 것이다. 그래서 위 본문은 결정한 때의 원문이 아니라 마지막 고침 뒤의 내용이다. 처음 커밋한 본문은 `git show 6c52cdb9:docs/architecture/decisions/VD-11-browser-file-and-origin-storage.md`로 본다.
|
||||
|
||||
- 2026-09-18 (`ec7f20e2`): 「계약과 증적」 절 끝의 문단 하나를 두 문단으로 바꿨다. engine마다 14개, 모두 42개라는 browser source suite case 수와 WebKit native library 부재 서술을 지우고, `verify:browser-capability-evidence`가 Chromium artifact에서 기준 testcase 묶음을 잡고 Firefox·WebKit이 같은 묶음을 실패 없이 돌렸는지 검사한다는 규칙과, engine별 capability 차이를 skip 이유로 쓰지 않는다는 규칙을 넣었다.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: server state cache, Web Storage, IndexedDB 영속화, 탭 간 무효화를 한 추상으로 합치지 않고 scope와 영속화 경계를 따로 정한다는 결정이다.
|
||||
- 현재 정본: `src/adapters/query-cache/`, `src/adapters/cross-context-invalidation/`, `src/contracts/storage-keys.ts`
|
||||
@@ -889,3 +889,9 @@ source, deterministic test, native evidence와 composition inventory로 증명
|
||||
|
||||
이 비용은 cache hit, durable restore, cross-tab hint와 server truth를 하나의
|
||||
“cached” 상태로 잘못 합치지 않기 위한 의도적인 비용이다.
|
||||
|
||||
## 보완
|
||||
|
||||
> 머리 블록은 2026-11-08에, 이 절은 2026-11-12에 더했다. 아래 고침은 기록 규칙(2026-11-08)이 생기기 전에 본문을 제자리에서 고친 것이다. 그래서 위 본문은 결정한 때의 원문이 아니라 마지막 고침 뒤의 내용이다. 처음 커밋한 본문은 `git show 6c52cdb9:docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md`로 본다.
|
||||
|
||||
- 2026-11-06 (`02a761f0`): 2절 상태 표의 registered Web Storage 행과 7절 한도 표 아래 문단에서 `COLOR_SCHEME`·`CHUNK_RELOAD_GUARD` 두 key 이름을 지우고, 행 목록의 정본이 `src/contracts/storage-keys.ts`의 `STORAGE_REGISTRY`라고 가리키게 했다.
|
||||
|
||||
@@ -111,14 +111,15 @@ Local Draft 소비자가 아직 `src/features/` 아래 있을 때 잰 값(09-12)
|
||||
- 내구성, 스케줄링, 관측
|
||||
|
||||
이 복잡함은 feature가 아니라 조립·플랫폼 경계에 둔다.
|
||||
Local Draft 세로 slice는 이제 두 번째 구체 소비자다.
|
||||
Local Draft 세로 slice는 이 repository port를 feature 모양으로 쓰는 구체 소비자다.
|
||||
다만 제품 feature가 아니라 테스트 fixture(`tests/fixtures/indexeddb-consumer`)다.
|
||||
이 소비자는 안정된 연결 지점(seam)이 타입이 있는 repository provider와,
|
||||
feature가 소유한 repository 식별자라는 것을 확인한다.
|
||||
dataset 범위, 보존, 마이그레이션, codec, 수명 주기 권한 설정을 만능
|
||||
`create...Repository<T>` factory 하나로 안전하게 합칠 수 있다는 것은 보여 주지 **않는다**.
|
||||
|
||||
그래서 편의 프로필은 IndexedDB를 쓰는 다른 제품 feature가 같은 인프라 정책을 되풀이한 뒤에만 들인다.
|
||||
두 feature가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
|
||||
그래서 편의 프로필은 IndexedDB를 쓰는 제품 feature가 생기고, 그 feature들이 같은 인프라 정책을 되풀이한 뒤에만 들인다.
|
||||
여러 소비자가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.
|
||||
|
||||
## 소비자 품질 검토 체크리스트
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ bootstrap, presentation, application 모듈을 import하지 못하게 막는다.
|
||||
|
||||
## 감사 결과
|
||||
|
||||
2026년 9월 아키텍처 리뷰를 계기로 계약 파일 39개 전체의 import 그래프를 감사했다.
|
||||
2026년 9월 아키텍처 리뷰를 계기로 그때 `src/contracts`에 있던 계약 파일 전체의 import 그래프를 감사했다. 지금 파일 목록은 `src/contracts/`가 정본이다.
|
||||
|
||||
### capability 소유 계약을 옮김
|
||||
|
||||
@@ -112,4 +112,4 @@ runtime에 설치됐다는 사실을 message 소유로 보지 않는다.
|
||||
- 같은 정의가 필요한 빌드·release·runtime wire 기준이 없다.
|
||||
- 정의를 그 owner로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다.
|
||||
|
||||
39라는 숫자를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
|
||||
계약 파일 수를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
|
||||
|
||||
@@ -44,7 +44,7 @@ rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음
|
||||
미리 불러온다(preload). 몇 개까지 허용할지는 `config/performance/budgets.json`의
|
||||
`initialJsFiles`가 정한다. 지금 개수는
|
||||
`config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`이고, 이
|
||||
값은 예시 feature를 기준으로 한다. HTTP/1.1에서는 host마다 연결이 여섯 개라
|
||||
값은 feature가 없는 지금 템플릿 빌드에서 잰 것이다. HTTP/1.1에서는 host마다 연결이 여섯 개라
|
||||
파일이 줄을 선다. 그래서 Fast 3G에서 첫 화면이 초기 chunk를 묶었을 때보다 약
|
||||
1초 늦게 떴다(2026-11-03). HTTP/2에서는 차이가 100 ms 미만이었다. 그래서
|
||||
템플릿은 chunk를 나눈 채로 둔다. HTTP/1.1로만 서빙할 수 있는 제품은
|
||||
|
||||
@@ -333,7 +333,9 @@ release 증거는 다음 release 승격까지, drill 증거는 다음 production
|
||||
증거는 집계까지 보관한다.
|
||||
|
||||
runbook job은 고정 경로 `artifacts/runbooks/<runbook-id>/record.json`에 쓴다. 바뀌는
|
||||
release identity는 record 안에 저장한다.
|
||||
release identity는 record 안에 저장한다. 그래서 게이트 증거를 찾는 일이 `RELEASE_ID`의
|
||||
slash나 그 밖의 provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자
|
||||
자기 run 범위에 남는다.
|
||||
|
||||
runbook drill(`drill:runbook`, FE-GATE-021..025)은 판정마다 `PASS`, `FAIL`,
|
||||
`UNVERIFIED` 중 하나로 기록한다(`scripts/drill-runbook.ts`, record schema는
|
||||
@@ -411,9 +413,7 @@ drill은 `FAIL`(exit 1)이다. 그렇지 않고 `UNVERIFIED`가 하나라도 있
|
||||
production 단계는 닫히지 않는다. 의도한 결과다. 로컬 drill은 승격한 release를 rollback할
|
||||
수 있다는 것을 보여 줄 수 없다. FE-GATE-016(`rollback-drill`)은 FE-GATE-025와 같은
|
||||
FE-RB-005 drill을 돌렸으므로 폐기했다(`scripts/contracts/ci-gates.ts`의
|
||||
`RETIRED_GATE_IDS`). 이렇게 하면 게이트 증거를 찾는 일이 `RELEASE_ID`의 slash나 그 밖의
|
||||
provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자 자기 run 범위에
|
||||
남는다.
|
||||
`RETIRED_GATE_IDS`).
|
||||
|
||||
브라우저를 쓰는 merge 게이트는 버전을 고정한 Chromium, Firefox, WebKit 엔진을 설치해
|
||||
실행한다. 그래서 route 동작, reflow, 기본 dialog 동작, theme 유지, 자동 접근성 검사는
|
||||
@@ -522,7 +522,7 @@ nanoid, source-map-js)은 선언한 범위 안에서 업데이트해서 없어
|
||||
|
||||
| Advisory | 패키지 | 고친 버전 | 아직 업데이트하지 않은 이유 |
|
||||
|---|---|---|---|
|
||||
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 4.6.7은 초기 JavaScript를 gzip으로 약 7 KB 늘려 번들 예산을 넘는다. 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
|
||||
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 고친 버전 이상으로 올리면 초기 JavaScript가 gzip으로 약 7 KB 늘어 번들 예산을 넘는다(2026-11-04에 4.6.7로 잰 값). 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
|
||||
| GHSA-qwww-vcr4-c8h2 (high) | `react-router`, `react-router-dom`을 거쳐 들어옴(production. 지금 버전은 `pnpm-lock.yaml`) | 7.18.2 | 같은 evidence 규칙을 따른다. 이 advisory는 RSC 모드에 관한 것이다. browser router를 쓰는 이 SPA는 RSC 모드를 쓰지 않는다(리뷰 추정, 확인하지 않음). 7.18.5는 초기 JavaScript를 약 470 B 늘린다 |
|
||||
|
||||
두 provider role은 서로 다른 key ID뿐 아니라 canonical DER-SPKI public-key bytes도
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# FE-RB-001 — 부트 설정 실패
|
||||
# FE-RB-001 — boot 설정 실패
|
||||
|
||||
`BOOT_CONFIG_FAILURE`가 나고, 한 번만 허용된 재요청(refetch)도 실패하면 이
|
||||
runbook을 시작한다. 제품 route를 mount하지 않고 안전한 지원 화면(support
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# FE-RB-002 — chunk 또는 배포 불일치
|
||||
# FE-RB-002 — chunk·manifest·배포 불일치
|
||||
|
||||
`CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, `DEPLOY_MISMATCH` 중 하나가
|
||||
나면 시작한다. 저장하지 않은 상태(dirty state)를 잃을 수 있으면 경고한다.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# FE-RB-003 — 백엔드 API 품질 저하
|
||||
# FE-RB-003 — 백엔드 API 저하
|
||||
|
||||
다음 중 하나면 시작한다. 더 재시도하지 않는(terminal) 네트워크·시간 초과·5xx
|
||||
실패가 최근 5분 이동 구간(rolling)의 기준치를 넘는다. 또는 `SCHEMA_MISMATCH`가
|
||||
|
||||
+24
-20
@@ -32,6 +32,10 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
// it on the local build. What needs a browser boot, live traffic or the hosting
|
||||
// provider is UNVERIFIED, and so is every drill whose runbook needs provider
|
||||
// verification: a local drill never claims the release can be recovered.
|
||||
//
|
||||
// Each recovery assertion is named after one of the runbook's recoveryEvidence
|
||||
// items in config/runbooks/runbooks.json, word for word and in its order
|
||||
// (tests/unit/runbook-drill.test.ts), so the record names what the runbook lists.
|
||||
|
||||
type RecoveryAssertion = Readonly<{
|
||||
assertion: string;
|
||||
@@ -181,14 +185,14 @@ async function drillBoot(): Promise<DrillResult> {
|
||||
triggerAsserted: verdict(!invalid.success),
|
||||
containmentAsserted: verdict(!invalid.success),
|
||||
recoveryAssertions: [
|
||||
notObserved("clean-session boot", "a browser boot of the promoted release"),
|
||||
notObserved("product root mount", "a browser boot of the promoted release"),
|
||||
notObserved("깨끗한 세션에서 boot", "a browser boot of the promoted release"),
|
||||
notObserved("제품 root mount", "a browser boot of the promoted release"),
|
||||
assertion(
|
||||
"config validation",
|
||||
"config 검증",
|
||||
"invalid fixture rejected, valid fixture accepted",
|
||||
verdict(!invalid.success && recovered.success),
|
||||
),
|
||||
notObserved("no repeated boot error", "boot telemetry from the promoted release"),
|
||||
notObserved("boot 오류 반복 없음", "boot telemetry from the promoted release"),
|
||||
],
|
||||
// The runbook's negative fixture injects a mount failure after a valid
|
||||
// config; that needs a mounted app, which a Node drill does not have.
|
||||
@@ -233,13 +237,13 @@ async function drillChunkMismatch(context: DrillContext): Promise<DrillResult> {
|
||||
),
|
||||
recoveryAssertions: [
|
||||
assertion(
|
||||
"entry and lazy assets reachable",
|
||||
"entry asset과 lazy asset에 접근 가능",
|
||||
"every Vite manifest file exists in the local dist",
|
||||
verdict(await builtAssetsPresent(context.root)),
|
||||
),
|
||||
assertion("release tuple coherent", "build/config/manifest tuple", verdict(coherence.compatible)),
|
||||
assertion("second reload blocked", "reload guard decision", verdict(second.action === "support")),
|
||||
notObserved("critical route smoke", "a browser smoke against the hosted release"),
|
||||
assertion("release tuple 일치", "build/config/manifest tuple", verdict(coherence.compatible)),
|
||||
assertion("두 번째 reload 차단", "reload guard decision", verdict(second.action === "support")),
|
||||
notObserved("핵심 route smoke 시험", "a browser smoke against the hosted release"),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: verdict(second.action !== "reload-once"),
|
||||
providerVerificationRequired: true,
|
||||
@@ -338,11 +342,11 @@ async function drillApiDegradation(): Promise<DrillResult> {
|
||||
triggerAsserted: "UNVERIFIED",
|
||||
containmentAsserted: verdict(!unkeyedRetry && safeRetry),
|
||||
recoveryAssertions: [
|
||||
notObserved("terminal failure rate at baseline", "API failure telemetry from the promoted release"),
|
||||
assertion("no retry amplification", "unkeyed retry policy", verdict(!unkeyedRetry)),
|
||||
notObserved("critical read/write smoke", "a read and a write against the live API"),
|
||||
notObserved("최종(terminal) 실패율이 기준선 수준", "API failure telemetry from the promoted release"),
|
||||
assertion("재시도 증폭 없음", "unkeyed retry policy", verdict(!unkeyedRetry)),
|
||||
notObserved("핵심 읽기/쓰기 smoke 시험", "a read and a write against the live API"),
|
||||
assertion(
|
||||
"schema fixtures",
|
||||
"스키마 fixture",
|
||||
"schema mismatch is not retryable",
|
||||
verdict(!schemaRetry),
|
||||
),
|
||||
@@ -384,10 +388,10 @@ async function drillTelemetry(): Promise<DrillResult> {
|
||||
triggerAsserted: verdict(adapter.droppedCount() === 1),
|
||||
containmentAsserted: verdict(adapter.pendingCount() === 0),
|
||||
recoveryAssertions: [
|
||||
assertion("product flow unaffected", "adapter flush resolves despite the sink failure", verdict(flushResolved)),
|
||||
assertion("delivery self-check", "sink failure counted", verdict(adapter.droppedCount() === 1)),
|
||||
assertion("queue drained within bound", "pending queue count", verdict(adapter.pendingCount() === 0)),
|
||||
assertion("forbidden attributes absent", "default-deny projection", verdict(redacted)),
|
||||
assertion("제품 흐름 영향 없음", "adapter flush resolves despite the sink failure", verdict(flushResolved)),
|
||||
assertion("전송 자체 점검", "sink failure counted", verdict(adapter.droppedCount() === 1)),
|
||||
assertion("queue가 상한 안에서 비워짐", "pending queue count", verdict(adapter.pendingCount() === 0)),
|
||||
assertion("금지 속성 없음", "default-deny projection", verdict(redacted)),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: verdict(redacted),
|
||||
providerVerificationRequired: true,
|
||||
@@ -421,14 +425,14 @@ async function drillRollback(context: DrillContext): Promise<DrillResult> {
|
||||
triggerAsserted: "UNVERIFIED",
|
||||
containmentAsserted: verdict(coherent.compatible && assetsPresent),
|
||||
recoveryAssertions: [
|
||||
assertion("compatibility gate", "typed version comparison", verdict(coherent.compatible)),
|
||||
assertion("호환성 gate", "typed version comparison", verdict(coherent.compatible)),
|
||||
assertion(
|
||||
"release coherence gate",
|
||||
"release 일관성 gate",
|
||||
"build/config/manifest tuple and every Vite manifest file in the local dist",
|
||||
verdict(coherent.compatible && assetsPresent),
|
||||
),
|
||||
notObserved("critical smoke", "a browser smoke after the provider switches to the prior release"),
|
||||
assertion("release ID in timeline", "drill record releaseId", verdict(Boolean(release.releaseId))),
|
||||
notObserved("핵심 smoke 시험", "a browser smoke after the provider switches to the prior release"),
|
||||
assertion("장애 타임라인에 release ID 기록", "drill record releaseId", verdict(Boolean(release.releaseId))),
|
||||
],
|
||||
negativeFixtureFailedAsExpected: verdict(!mixed.compatible),
|
||||
providerVerificationRequired: true,
|
||||
|
||||
@@ -103,6 +103,19 @@ describe("runbook drill verdicts", () => {
|
||||
expect(record.recoveryAssertions.some(({ result }) => result === "FAIL")).toBe(false);
|
||||
});
|
||||
|
||||
// A drill's recovery assertions are the runbook's recoveryEvidence items, named
|
||||
// as config/runbooks/runbooks.json names them and in its order, so the record
|
||||
// and the UNVERIFIED line name the same checks the runbook lists.
|
||||
it.each(RUNBOOK_IDS)("%s names its recovery assertions after the runbook's recoveryEvidence", async (runbookId) => {
|
||||
const document = JSON.parse(await readFile("config/runbooks/runbooks.json", "utf8")) as {
|
||||
runbooks: Record<string, { recoveryEvidence: string[] }>;
|
||||
};
|
||||
const record = await runRunbookDrill(runbookId, { releaseRoot: await builtDist(), contractPackages });
|
||||
expect(record.recoveryAssertions.map(({ assertion }) => assertion)).toEqual(
|
||||
document.runbooks[runbookId]?.recoveryEvidence,
|
||||
);
|
||||
});
|
||||
|
||||
it.each(["FE-RB-002", "FE-RB-005"] as const)(
|
||||
"%s fails when the build lost its JavaScript assets",
|
||||
async (runbookId) => {
|
||||
|
||||
Reference in New Issue
Block a user