Files
clean-architecture-frontend…/docs
DongHyeonka e5b7b3e857 fix(storage): partition 삭제가 다른 탭의 진행 중인 put을 기다린다 (0929/05-01)
문제: 손상 때문에 끝나지 못한 LOGOUT·ACCOUNT_DELETION purge의 partition
삭제는 두 단계다. 디렉터리를 origin lease 안에서 지우고, 이어서 journal
row를 lease 밖에서 지운다. origin lease는 put의 BEGIN~FINISH만 막는다.
그래서 다른 탭에서 journal `begin`을 끝낸 put이 두 단계 사이에 BEGIN을
하면 새 디렉터리에 파일을 쓰고, 두 번째 단계가 그 put의 row를 지운다.
put은 다음 journal 단계에서 `CONFLICT`로 실패하지만 파일을 치울 주체가
없다.
- markFilesReady 전에 row가 지워지면: 보상이 manifest·staging을 지우고
  chunk가 남는다.
- commitPut 전에 지워지면: 보상이 없어 manifest·FILES_READY staging
  receipt·chunk가 남는다. staging receipt가 chunk를 GC·sweep에서 지키고
  row가 없어 reconcile도 보지 않으므로 영원히 남는다. 다음 LOGOUT purge는
  `chunkSweep: COMPLETED`를 보고하면서 이 bytes를 남긴다.
- commit 뒤 complete 전에 지워지면: put은 성공하지만 object는 없고
  manifest·chunk가 남는다.
삭제 전체가 put의 FINISH~commit 사이에 들어가는 경우(72edb55가 가정한
경우)는 수정 전에도 put이 `CONFLICT`로 실패하고 bytes가 남지 않았다.

고른 방법: partition 단위 Web Lock
(`<mutationLockName>:partition:<a>:<ns>:<p>`)을 둔다. 모든 put·delete는
`withTransactionLock` 안에서 journal `begin`부터 끝날 때까지 shared로
쥐고, partition 삭제는 디렉터리·journal 두 단계를 exclusive로 쥔 채 한다.
mutation은 삭제 전체보다 앞이거나 뒤에만 놓인다. 진행 중이던 put은 끝난
뒤 삭제가 지우고, 삭제가 lock을 요청한 뒤 온 put은 삭제 뒤에 돈다.
lock 순서는 partition lock → origin lease 하나뿐이라 교착이 없다
(per-transaction lock은 `ifAvailable`이라 기다리지 않는다). 기다리는
동안 purge `signal`을 abort하면 `ABORTED`를 반환한다.

버린 대안:
- commitPut `CONFLICT`면 보상: commitPut 전 경우만 고치고 chunk와
  commit 뒤 경우가 남는다. 또 port가 "CONFLICT = 아무것도 commit 안 됨"을
  약속하지 않아 동봉 구현에 기대는 숨은 결합이 생긴다.
- commit까지 origin lease 쥐기: lease는 worker 안에 있고 journal은 page
  쪽이다. 두 번째 단계(row 삭제)가 lease를 쓰지 않아 commitPut 전 경우가
  그대로다.
- row를 먼저 지우고 디렉터리를 나중에: 그 사이 begin한 put이 디렉터리
  단계 전에 FINISH하면 파일 없는 COMMITTED row가 생긴다. 중간 실패 뒤
  재호출로 이어서 끝나는 성질도 잃는다.
- 디렉터리 → row → 디렉터리: 같은 이유로 파일 없는 commit이 생긴다.

위험·한계:
- 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle
  bound(05-07)까지 삭제를 붙잡는다. 수정 전에도 그 put은 origin lease를
  쥐고 있어 디렉터리 단계가 같은 시간을 기다렸다.
- reconcile은 partition lock을 쥐지 않는다. reconcile은 파일을 새로 쓰지
  않으므로(검증·정리·finalize만) 삭제와 겹쳐도 bytes를 남기지 않는다고
  보았고, 이 경우는 테스트하지 않았다.
- put·delete마다 Web Lock 요청이 하나 늘어난다.
- offline-indexeddb 레시피 gzip 37,327 → 37,423 B(한도 38,500).
- 공개 타입·배럴 변경 없음.

검증:
- RED(수정 전, put 결과 단언을 넣기 전): 새 it.each 5건 중 3건 실패.
  디렉터리를 put BEGIN 전에 지운 경우만 실패했다.
  markFilesReady 앞: chunk 1개 남음. commitPut 앞: staging receipt·chunk·
  manifest 남음. complete 앞: chunk·manifest 남음.
  삭제 전체가 FINISH~commit 사이인 2건은 통과(put CONFLICT, bytes 0).
  "put은 삭제 앞에 끝난다" 단언을 더한 뒤 수정 전 코드: 5건 모두 실패.
- GREEN: 5건 + abort 테스트 1건 통과. 같은 5건 10회 반복 10/10.
- `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
  tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
  tests/recipes` 136건 통과.
- tsc app·test·web-worker·recipes 통과. 바꾼 파일 eslint 통과.
  `check-adapter-inventory` PASS, `check-optional-recipes`(source) PASS,
  `verify-documentation-readiness` PASS_SCOPED.
- 미실행: `check:browser-file-storage-boundaries`·`check:architecture`
  (pnpm 필요), Playwright OPFS spec(webServer가 pnpm).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
2026-11-03 20:22:49 +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 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

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

verify:documentation은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 .md 전부)에 적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. CHANGELOG.md는 지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은 없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은 scripts/verify-documentation-readiness.ts다.

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

파일 읽는 명령
이 파일, architecture/review-ledger.json, architecture/review-evidence.md verify:documentation (FE-GATE-017)
repo 루트의 artifacts/tests/a11y-manual/ 라우트별 기록 verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009, FE-GATE-028)
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만 게이트가 읽는다. reviews/adapters/는 지우지 않는다: INVENTORY의 행과 operations/adapter-remediation-ledger.md가 그 안의 리뷰로 링크한다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다