Files
clean-architecture-frontend…/docs
DongHyeonka 68e88b081d fix(opfs): 객체를 못 지운 purge가 완료와 chunk sweep을 보고하지 않는다 (0929/05-02)
문제: OPFS purge는 remove가 CONFLICT·NOT_FOUND면 그 객체를 건너뛴다.
chunk sweep 조건은 "남은 객체가 없다"가 아니라 !moreObjectsAvailable
&& !deadlineReached && !aborted라서, 다른 탭이 같은 객체를 덮어쓰는 동안
ACCOUNT_DELETION purge를 부르면 {removedObjects: 0,
moreObjectsAvailable: false, chunkSweep: "COMPLETED"}를 돌려준다. 객체와
chunk는 남아 있는데 보고는 완료로 읽힌다. port 주석은 sweep이 "once
every object is removed"라고 약속하고 runbook도 COMPLETED를 완료
조건으로 적는다.

고른 방법: 지난 리뷰의 첫 방향. 건너뛸 때 moreObjectsAvailable을 true로
두어 report가 미완료를 드러내고 sweep 조건이 sweep을 막게 한다
(chunkSweep 칸이 빠진다). port 계약은 바꾸지 않고 코드를 기존 주석에
맞춘다. 이 값을 뒤에서 false로 되돌리는 대입이 없다는 근거(다음
페이지로 넘어가는 대입은 그 페이지에 객체가 더 있을 때만 실행되고,
PRESSURE는 sweep하지 않는다)를 코드 주석에 적었다. port의
moreObjectsAvailable 주석과 runbook에 "다시 호출한다"를 더했다.

버린 대안:
- skippedObjects 칸을 report에 더하고 완료 조건을 "skippedObjects === 0
  그리고 COMPLETED"로 고친다: port 추가와 문서 조건 변경이 필요하고
  번들도 더 커진다. offline-indexeddb 예산 여유가 9 B뿐이다.
- 따로 skipped 플래그를 두고 끝에서 합친다: 같은 동작에 바이트가 더 든다.

위험·한계:
- offline-indexeddb 레시피 번들 36,891 -> 36,896 / 36,900 gzip B.
  예산은 올리지 않았지만 여유가 4 B로 줄었다([0929] 05-04).
- 별도로 발견했고 고치지 않은 것: 여러 페이지에 걸친 purge는 마지막
  페이지의 OR 대입이 앞 페이지에서 넘어올 때 넣은 true를 유지해, 다
  지워도 moreObjectsAvailable true를 보고하고 sweep하지 않는다. 보수적
  방향이라 다시 부르면 끝나지만 한 번에 끝나지 않는다. 코드로만
  확인했고 실행하지 않았다. 동작 변경이라 범위 밖.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.

검증:
- RED: opfs-worker-runtime "reports a purge that skipped a changing object
  as unfinished"가 `- "moreObjectsAvailable": true`
  `+ "moreObjectsAvailable": false`로 실패(removedObjects 0, 6번째 칸
  chunkSweep 존재).
- GREEN: 같은 파일 64/64 통과. 두 번째 purge가 removedObjects 1,
  chunkSweep COMPLETED, partition 파일 0개로 끝난다.
- 회귀: opfs-worker-runtime, opfs-byte-store, indexeddb-opfs-journal,
  indexeddb-local-draft 4파일 104/104 통과. tsc app·test·web-worker·
  recipes 통과, eslint 통과, verify-documentation-readiness PASS_SCOPED,
  check-optional-recipes PASS.

Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
..

문서 색인

docs/의 문서를 세 묶음으로 나눈다.

1. 현재 계약   지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계   앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력   리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다

문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는 문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로 확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.

README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.

1. 현재 계약

처음 읽을 입구 문서 6개다.

문서 정하는 것
README.md 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
architecture/optional-adapter-recipes.md 선택 기능(recipe)을 넣고 빼는 절차
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

입구 문서가 가리키는 세부 규칙:

게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md verify:documentation (FE-GATE-017)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)

2. 목표 설계

설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.

3. 작업 이력·리뷰

템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다. 복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의 "Files you can delete after copying" 절에 있다.

경로 내용
superpowers/ 과거 작업 계획과 스펙
reviews/ 리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다