Commit Graph
238 Commits
Author SHA1 Message Date
DongHyeonka fb446e471e Merge branch 'main' into claude/fe-b-docs-korean-645f55
하네스 PR #13(main d1b9c087)을 받는다. 충돌은 README.md와 docs/README.md
둘이다. 이 브랜치가 두 파일을 한국어로 다시 썼고, #13이 영어 판에
AGENTS.md·docs/work/·docs/ledger/를 가리키는 줄과 지워도 되는 표 행을 더했다.
이 브랜치 판을 바탕으로 #13이 더한 것을 한국어로 넣었다.
- README: 최상위 표에 AGENTS.md·.claude/, 문서 지도에 AGENTS.md·docs/work/·
  docs/vision.md·docs/problem-statement.md·docs/ledger/, 지워도 되는 표에서
  CLAUDE.md를 빼고 docs/ledger/estimates.jsonl을 더함, 새 서비스로 시작하기와
  규칙과 기여의 CLAUDE.md 줄을 AGENTS.md 기준으로
- docs/README.md: 1절 「처음 읽을 문서」에 ../AGENTS.md·work/·work/reference/
  링크(#13의 template-contract-documents 시험이 본다), 지도에 work/·ledger/
  행, 폴더 밖 문서에 AGENTS.md·vision.md·problem-statement.md, 2절 살아 있는
  문서 목록
2026-11-11 20:55:11 +09:00
DongHyeonka f117a5af41 docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.

src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).

- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
  본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
  아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
  양식을 가리킨다.

버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).

위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).

검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
2026-11-08 22:57:03 +09:00
DongHyeonka 11530b1adf docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.

위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.

검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
2026-11-08 21:57:47 +09:00
DongHyeonka 5e31faa8af chore(review): 1106 realtime 조치 브랜치를 합친다 2026-11-06 07:02:34 +09:00
DongHyeonka 6f06e7702f fix(realtime): poll execute에 descriptor 타입을 싣고 V3 결과 대응표를 둔다
문제: poll `execute`가 받는 `input.operation`은 `BoundedPollOperation`
(`InstalledHttpContract<unknown, unknown, unknown>`)이다. 권하는 대로
`executor.execute(input.operation, x, …)`를 부르면 `Input`이 `unknown`이
되어 `x`는 아무 값이나 통과하고 `outcome.value`도 `unknown`이다. 입력이
틀리면 런타임 `CONTRACT_VIOLATION`(INPUT_INVALID)으로만 드러난다. 타입을
지키려면 클로저 descriptor를 써야 해서 1103/04-01의 잔여 위험(다른 행을
실행) 쪽이 유리해진다. 또 V3 결과 9종을 poll 결과로 바꾸는 대응표가 없다.
repo의 유일한 V3 조합 예(테스트)는 SUCCESS 외 전부를 retryable
PROVIDER_UNAVAILABLE로 바꿔, 옮기면 401·403·입력 거절도 maxAttempts번
다시 요청된다.

고른 방법: 리뷰 선택지 (b) + (c).
- `createBoundedPollCoordinator`와 `BoundedPollCoordinatorDependencies`에
  `Operation extends BoundedPollOperation = BoundedPollOperation`을 더하고
  `operation`·`input.operation`을 `Operation`으로 둔다. `operation`에서
  추론되므로 실행기 호출이 기능 descriptor의 입력·출력 타입으로 검사된다.
  런타임 코드는 바뀌지 않는다.
- 설계 9.2에 V3 결과 kind마다 poll 결과(kind, retryable, retryAfterMs)를
  적은 표를 두고, 13.1 PROVIDER_UNAVAILABLE 행에서 그 표를 가리킨다.
  9.2 "auth에서 lease 종료", 9.3 "401은 attempt를 끝낸다", 9.4, 13.1과
  맞췄다. `retryAfterMs`는 값이 있을 때만 둔다(빈 칸은 모양 오류).
- 테스트 조합 예를 표대로 바꿨다(`pollAttemptResult`). 503 재시도
  테스트는 같은 결과다(503 PROBLEM → retryable PROVIDER_UNAVAILABLE).
- 테스트: 틀린 입력에 `@ts-expect-error`, 출력을 기능 타입으로 받는 타입
  테스트 1건. 401·403이 요청 1번으로 lease를 끝내는 테스트 2건.
버린 대안:
- (d) 대응 함수를 bootstrap이나 recipe에 두기. realtime 어댑터는
  adapters/http 타입을 import할 수 없고, 레시피 번들과 제거 드릴 범위가
  바뀐다.
- `BoundedPollOperation` 자체를 제네릭으로 바꾸기. application 정책의
  공개 이름이 바뀐다. 제약으로만 두면 기존 이름이 그대로다.

위험·한계:
- 기존 호출은 그대로 컴파일된다. `Value`를 직접 적은 호출은 `Operation`이
  기본값이라 예전처럼 `unknown`이다. 타입을 원하면 둘 다 적거나 추론에
  맡긴다(타입 주석과 9.2에 적음). 그래서 `!`를 붙이지 않았다. 단, 추론에
  맡긴 호출이 descriptor 타입과 다른 입력을 실행기에 넘기고 있었다면 이제
  check:types가 실패한다. 이 커밋이 잡으려는 결함이다.
- 표는 조합 코드가 따를 규칙이고 강제 수단은 없다. 템플릿은 poll
  `execute` 기본 구현을 주지 않는다(리뷰 재검토 조건).
- 409·410의 `CURSOR_EXPIRED` 행은 reset 계약이 있는 기능만 해당한다.
  테스트 계약에는 없어 테스트 예는 그 갈래가 없다.
- CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다.

검증: desktop batch에서 확인.
- corepack pnpm check:types:test
- node scripts/run-vitest.ts run tests/unit/realtime/bounded-poll-coordinator.test.ts
- RED: 부모 커밋의 src에서 check:types:test가 실패한다.
  bounded-poll-coordinator.test.ts의 `@ts-expect-error` 줄이 TS2578(쓰이지
  않은 지시문, 입력이 `unknown`이라 `{ size: 20 }`이 통과), 그 아래
  `pollAttemptResult<…>(outcome)`이 TS2345(`outcome.value`가 `unknown`).
  vitest 테스트는 양쪽에서 통과한다.
- lint, check:architecture, verify:documentation

Refs: 1106/04-02
2026-11-06 05:32:47 +09:00
DongHyeonka 0438c3f248 fix(realtime): 던지는 reconnect attempt·waitClosed의 규칙을 적는다
문제: reconnect coordinator는 `attempt`·`waitClosed`가 던지면
PROVIDER_UNAVAILABLE(CONNECT·RECEIVE, retryable)로 보고 backoff로 다시
시도한다. 05330e3 뒤 poll은 같은 던짐을 PROTOCOL_MISMATCH로 끝낸다. 이
차이는 그 커밋 본문에만 있고 타입 주석과 설계 13.1에는 없다. repo의 SSE
bridge 예(`sseAttempt`)는 `attempt` 안에서 연결을 만든다. 그래서
endpoint 설정 오류가 요청 0번, attempt 3번, PROVIDER_UNAVAILABLE
(EXHAUSTED)로 끝나 서버 장애로 보인다(리뷰 실험 04-R2).

고른 방법: 리뷰 선택지 (c). 동작은 그대로 두고 규칙을 적는다.
- `attempt` 주석: 던짐은 transport 실패로 재시도된다. 설정 검사는
  `attempt` 밖, 조합 코드가 transport를 만들 때 한다. poll과 다른 이유도
  적었다. `waitClosed` 주석: RECEIVE로 같은 규칙.
  `classifyClosed`·`confirmTransportBarrier` 주석: 던짐은
  PROTOCOL_MISMATCH로 끝나고 재시도하지 않는다.
- 설계 13.1 PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행에 같은 규칙을 적었다.
- 테스트 bridge `sseAttempt`는 만들어질 때 연결 설정을 한 번 검사한다.
  연결은 attempt마다 새로 만든다. session `close`가 연결을 끝내므로 한
  연결을 여러 attempt에 쓸 수 없다.
- 규칙을 고정하는 테스트를 더했다. attempt·waitClosed 던짐은 3회 재시도 뒤
  PROVIDER_UNAVAILABLE(EXHAUSTED), classifyClosed 던짐은 1회로
  PROTOCOL_MISMATCH, bridge의 http endpoint는 만들 때 TypeError(fetch 0).
버린 대안:
- (b) reconnect도 던짐을 PROTOCOL_MISMATCH로 끝내기. 연결 실패를 던지는
  라이브러리를 감싼 transport가 첫 실패에서 run을 끝내게 되는 공개 동작
  변경(BREAKING)이다. 리뷰도 지금 동작이 회복에 유리하다고 봤다.
  05330e3이 poll에서 (c)를 버린 이유("결과로 구분한다")는 이번 완료
  기준에 없다.
- 연결 하나를 bridge에서 만들고 attempt마다 read만 하기. 위와 같이
  session `close`가 연결을 닫아 다음 read가 CLOSED가 된다.

위험·한계:
- 동작이 같으므로 조합 코드가 `attempt` 안에서 연결을 만들면 설정 오류는
  여전히 서버 장애로 보인다. 주석과 13.1은 모르고 쓰는 경우만 줄인다.
- 매핑 오류 같은 나머지 던짐도 그대로 재시도되고 원인 예외는 남지 않는다
  (닫힌 관측 어휘).
- CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/realtime-reconnect-coordinator.test.ts
- RED 없음. 동작을 바꾸지 않는 커밋이라 새 테스트는 부모 커밋에서도
  통과한다. 규칙을 고정하는 테스트다.
- check:types, lint, verify:documentation

Refs: 1106/04-01
2026-11-06 05:27:35 +09:00
DongHyeonka 4cef2a2716 fix(cache-storage): 읽히지 않는 active pointer를 activation 옵션으로 덮어쓴다
문제: control cache의 active pointer entry는 있는데 저장된 본문이 다시
쓰기 전까지 계속 읽히지 않으면(blob 손실 등) Cache Storage 관리가 모두
멈춘다. readActivePointer는 이 실패를 UNAVAILABLE/RETRY(또는
NOT_READABLE/REOPEN)로 돌려주고 CORRUPT_DATA로 보지 않는다. activation은
CORRUPT_DATA 밖의 pointer 실패에서 멈추고, cleanup·inspect·조회도 같은
실패에서 멈춘다. pointer를 쓰는 곳은 activation 하나라서 RETRY를
지켜도 돌아오지 않는다. 돌아오는 길은 adapter 밖에서 control cache를
지우는 것뿐이다. 리뷰 실험 02-R1 X3이 이것을 보였다.

고른 방법: activateRelease에 선택 옵션 replaceUnreadablePointer를 둔다.
true면 이전 pointer를 읽지 못한 이유와 상관없이, 손상 pointer와 같은
0929/02-01 경로로 검증된 후보를 rollback 목록 없이 덮어쓴다. 기본값은
지금처럼 멈춤이라 "일시 오류 하나로 rollback 목록을 잃지 않는다"는
보존 조건이 지켜진다. 포트 주석, 설계 문서 8.3절, 운영 문서에 언제
쓰는지와 rollback 목록을 잃는다는 것을 적었다.
버린 대안: (가) 문서에 "control cache를 지우고 다시 activate"만 적기.
제품이 adapter 밖 코드로 소유 cache 이름을 알고 지워야 하고, 그동안
조회가 pointer 없음으로 바뀐다. (다) 연속 N회 실패를 손상으로 보기.
실패 횟수를 저장해야 하고, 긴 일시 오류에서도 rollback 목록을 잃는다.

위험·한계: 옵션을 켜면 일시 오류에서도 rollback 목록을 잃고, 다음
cleanup이 새 활성 release 밖의 owned release cache를 모두 지운다. 그래서
기본값으로 두지 않았다. 일시와 지속을 가르는 판단은 운영자 몫이다.
포트에 선택 칸이 하나 늘었다. 호출부·구현부 모두 호환이라 breaking이
아니다. CHANGELOG [계약] 행은 CHANGELOG 담당에게 남긴다.
1105/02-02의 남은 부분(release marker 본문이 계속 읽히지 않으면 stage가
marker를 다시 쓰지 않는다)은 이 변경으로 풀리지 않는다. marker는 release
cache 안의 entry라 stage 경로를 바꿔야 한다. 범위 밖으로 둔다.
service-worker-pwa 레시피 번들(여유 306 B)에 수십 B가 더해진다.
실제 브라우저에서 pointer 본문 읽기 실패가 지속되는지는 확인하지
못했다(리뷰 5절 미검증과 같다).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
RED(이 커밋의 테스트 + 부모 src): "replaces a pointer whose body stays
unreadable when the activation asks to (1106/02-01)"가 옵션을 준
activation에서 실패한다. 부모는 옵션을 모르므로 UNAVAILABLE/RETRY를
돌려주고 pointer를 다시 쓰지 않는다. 그 앞의 멈춤 단언(X3와 같은
결과)은 부모에서도 통과한다. 일시 오류 테스트 "still stops activation
when the pointer read fails transiently"는 바뀌지 않았고 통과해야 한다.

Refs: 1106/02-01
2026-11-06 05:21:06 +09:00
DongHyeonka 7395c78c3a fix(http): 202 REJECTED 업로드 실패에 응답의 traceId를 싣는다
문제: 짝 백엔드 Fileserver는 검증기가 거절한 업로드를 202 성공
Envelope(state REJECTED)로 답한다. client는 이 답을 FILE_REJECTED
실패로 바꾸는데, readSuccessEnvelope가 meta.traceId를 버려서 실패에
traceId가 없다. 같은 client의 Envelope 실패는 traceId를 싣는다
(1105/01-03). 서버가 정상으로 답해 trace 값이 손에 있는데도, 지원
담당이 이 거절을 서버 로그나 REJECTED 레코드와 잇지 못한다.

고른 방법: readSuccessEnvelope가 readFailureEnvelope처럼 meta.traceId가
있으면 traceId로 함께 돌려준다. Fileserver client는 202 REJECTED
실패에 그 값을 싣는다. V3 실행기는 value와 page만 읽으므로 동작이
같다. 매뉴얼 7절 결과 읽기 줄에 적었다.
버린 대안: fileserver-upload가 successEnvelopeSchema를 직접 파싱하면
Envelope 읽기가 backend-envelope.ts 밖으로 갈라진다. traceId만 읽는
함수를 따로 두면 같은 답을 두 번 파싱한다.
반환 칸이 늘어 readSuccessEnvelope 결과를 toEqual로 보는 테스트 두
곳(tests/runtime-schema/http-schema.test.ts,
tests/unit/a11y-api-answers.test.ts)의 기대값에 traceId를 더했다.
기대를 넓힌 것이 아니라 새 칸의 값까지 고정한 것이다.

위험·한계: 거절 이유는 여전히 없다. 프론트로는 고칠 수 없어
백엔드로 넘긴다.
- 사실(백엔드 45d2a478): FinalizeUploadApplicationUseCase
  #applyNonAcceptVerdict는 REJECT 판정의 code(FILE_TOO_LARGE,
  DIGEST_MALFORMED, 제품 검증기 code 등)를 FileRecordMutation.failure로
  레코드의 lastErrorCode에만 쓴다. FileUploadController#created는
  UploadedFileResponse 7칸(fileId, state, filename, mediaType, size,
  sha256, etag)을 202로 답한다. 이유 칸이 없다.
- 요청: REJECT를 실패 Envelope(422, error.code = 판정 code,
  retryable false)로 답하거나, 202 REJECTED 응답에 판정 code 칸을
  더한다. 앞의 것이면 프론트의 기존 422 경로가 code와 traceId를
  그대로 싣고 NOT_APPLIED로 읽는다. 그때 FILE_REJECTED 분기는 지운다.
- CHANGELOG의 "백엔드로 넘김" 목록에 이 항목을 더하는 일은 CHANGELOG
  담당에게 남긴다.
실제 배포 응답의 성공 meta에 traceId가 있는지는 백엔드 문서
(docs/web/http-contract.md §1 meta 키)와 EnvelopeBodyAdvice 코드로만
확인했다. backend-envelope.ts는 초기 번들에 있어 초기 JS가 수십 B
늘 수 있다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts tests/runtime-schema/http-schema.test.ts tests/unit/a11y-api-answers.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused
file, not as a broken answer"가 traceId "trace-1"이 없어 실패한다.
"reads data, and a dropped data key as null"과 "answers an Envelope
list read with an empty list inside the Envelope"는 결과에 traceId
칸이 없어 실패한다.

Refs: 1106/01-01
2026-11-06 05:18:58 +09:00
DongHyeonka 57c34ea626 chore(review): 1105 realtime·Service Worker 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 7af80859e5 chore(review): 1105 브라우저 파일·캐시·저장소 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 19d10538d6 chore(review): 1105 HTTP 판정·폼 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka c6c37f395b fix(http): 백엔드 rate-limit 503 두 code를 쓰기 전 거절로 읽는다
문제
짝 백엔드 http-contract.md §4는 web 전용 code 넷을 적는다. 그중 503
RATE_LIMIT_UNAVAILABLE(저장소 응답 없음, retryable, Retry-After 있음)과 503
RATE_LIMIT_INCOMPATIBLE(제공자 불일치)이 답 표 사본에도 프론트 판정 표에도
없다. 그래서 이 503은 기능 분류기가 정하고, create:feature가 만든 쓰기의
분류기는 늘 MAYBE_APPLIED다. 아무 일도 일어나지 않은 저장이 결과 불명이 되고,
NEVER 쓰기는 사실과 다른 "변경됨으로 확인"을 눌러야 폼이 풀린다(리뷰 실험 X4:
429는 NOT_APPLIED, 503 둘은 SERVER_FAILURE/MAYBE_APPLIED). pin은 §4를
대조했다고 적었지만 사본에는 REQUEST_TIMEOUT 한 행만 있었다.

고른 방법
백엔드 45d2a478을 읽기만 해서 code마다 판정했다. 두 code는
RateLimitInterceptor.preHandle이 false를 돌려주며 쓰고(Unavailable·
Indeterminate → RATE_LIMIT_UNAVAILABLE, Incompatible →
RATE_LIMIT_INCOMPATIBLE), main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다.
preHandle이 false면 handler를 부르지 않으므로 둘 다 쓰기 전이다. 백엔드는 같은
키 재전송을 요구하지 않는다(멱등성 executor 전). 그래서 답 표 사본에
refusedBeforeWrite: true, sameKeyResend: false로 두 행을 더하고, 프론트 거절 표
REFUSED_BEFORE_WRITE에 status 503과 함께 더했다. pin 테스트의 "답 표대로 읽는다"
규칙이 그대로 NOT_APPLIED를 요구하고 양방향 대조가 두 표를 함께 지킨다. kind는
지금처럼 SERVER_FAILURE(action retry)이고, KEYED도 자동 재전송은 없다(같은 키를
요구하는 답은 503 IDEMPOTENCY_UNAVAILABLE 하나다). pin의 comparedOn을 §4를 다시
대조한 날짜로 올렸다. 계약 문서 4.1·6.1절과 매뉴얼 01·02의 5xx 행 수를 고쳤다.

버린 대안
생성기 분류기가 503을 code별로 보게 한다: 생성 기능에만 고쳐지고 손으로 쓴
Envelope operation은 그대로 남는다. 판정은 백엔드 답 표 한 곳이 정한다는 지금
규칙을 따랐다.

위험·한계
- 추론(실행 확인 안 함): Spring MVC는 비동기 처리(Callable·DeferredResult) 뒤
  ASYNC 재디스패치에서도 interceptor의 preHandle을 다시 부르고, 이 interceptor는
  dispatcher 종류를 보지 않는다. 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이
  쓰기 뒤에도 나올 수 있다. 45d2a478에는 Envelope을 돌려주는 비동기 쓰기
  컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). 계약 6.1절에 적었다.
  백엔드에 넘길 요청: RateLimitInterceptor가 DispatcherType.REQUEST에서만
  평가하게 한다.
- fileserver-upload.ts는 같은 백엔드 답을 자기 표로 따로 판정한다(01 영역).
  여기서는 바꾸지 않았다.
- NOT_APPLIED가 되면서 IDEMPOTENT 쓰기는 이 503에 retryBudget 안에서 자동으로
  다시 보낼 수 있게 됐다(503은 재시도 status다). 쓰기 전 거절이라 중복은 없다.
  RATE_LIMIT_INCOMPATIBLE은 백엔드가 retryable false로 보내지만 실행기는 status로
  판단하므로 같은 답을 한 번 더 받을 수 있다. KEYED·NEVER는 자동 재전송이 없다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/backend-envelope.test.ts
tests/unit/backend-contract-pin.test.ts
tests/integration/http-execution-v3-envelope.test.ts

Refs: 1105/03-02
2026-11-06 02:33:16 +09:00
DongHyeonka 5c0b37e39e fix(contracts)!: 쓰기 뒤에도 나오는 플랫폼 code를 쓰기 전 거절로 적지 못하게 한다
문제
commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사,
중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든
IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤),
DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로
적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가
NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키
없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가
조립을 통과하고 모두 NOT_APPLIED).

고른 방법
6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에
PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그
code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른
경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은
조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은
backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서
6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인
code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외
목록에 적고 선언할 수 있게 둔다.

버린 대안
- 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그
  자리에 통제가 없다.
- 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code
  이름을 강제해 과하다.

위험·한계
- 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한
  실패다.
- 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가
  알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다.
- 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단).
- 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거
  드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는
  돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에
  `tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은
  그대로 돌린다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts
corepack pnpm test:optional-recipe-removal

BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔
플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면
composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의
실패는 결과 불명으로 남는다.

Refs: 1105/03-01
2026-11-06 02:33:16 +09:00
DongHyeonka 8e9fb1fde6 fix(cache-storage): 다시 stage하면 계속 읽히지 않는 캐시 본문을 다시 쓴다
문제: 2026-11-03 02-02 수정 뒤 저장된 본문을 읽지 못하면(`UNAVAILABLE`·
`NOT_READABLE`) 손상이 아니라 "모름"이다. stage 재사용 경로는 "모름"이면
실패를 돌려주고 다시 받지 않는다. 그래서 다시 쓰기 전까지 계속 읽히지 않는
entry(blob 손실 등)는 다시 stage해도 고쳐지지 않는다(리뷰 실험 E-1).
- 새 후보: activate가 `RETRY`를 안내하는데 다시 해도 같다. cleanup으로
  후보를 지운 뒤에야 풀린다.
- rollback 대상: cleanup도 지우지 않아 되돌릴 길이 없다.
- 서비스 중 release: 그 asset 조회가 계속 `UNAVAILABLE`이다.
수정 전 판정에서는 같은 상태가 다시 stage 한 번으로 풀렸다.

고른 방법(리뷰 대안 (나)):
- 판정에 `UNREADABLE`(entry는 있는데 본문 읽기가 실패)을 따로 둔다.
  `UNKNOWN`은 중단(`ABORTED`)과 `cache.match` 자체의 실패만 뜻한다.
- stage 재사용 경로는 `REPAIRABLE`처럼 `UNREADABLE`도 모든 asset을 다시
  받아 같은 cache에 덮어쓴다. 덮어쓰는 것은 digest로 검증한 같은
  바이트이고 cache를 지우지 않으므로 서비스 중인 release를 해치지 않는다
  (STO-RR-04가 막는 것은 삭제다).
- activation은 지금처럼 본문 읽기 실패를 손상으로 보고하지 않고 code를
  그대로 둔다. recovery만 `REHYDRATE`(같은 manifest로 다시 stage)로 바꾼다.
- 조회는 그대로 `UNAVAILABLE`/`RETRY`다.
- `cache.match`가 던지는 경우는 리뷰가 제안한 "중단 제외 UNKNOWN 전부"에서
  뺐다. Cache Storage 자체가 응답하지 않을 때 모든 asset을 다시 받는 것은
  고치는 것이 없고, 2026-11-01 02-03 테스트가 그 경우의 실패 보고를 고정한다.

버린 대안:
- (가) 문서에 "cleanup 뒤 다시 stage"만 적기: rollback 대상은 못 고친다.
- (다) 실패한 entry만 다시 받기: 비용은 가장 작지만 stage 경로를 entry
  단위로 나눠야 한다.

위험·한계:
- 일시적인 본문 읽기 오류에도 다시 stage하면 모든 asset을 다시 받는다
  (수정 전과 같은 비용).
- 실제 브라우저에서 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로
  오는지는 확인하지 못했다. 테스트는 메모리 fake에 오류를 주입한다.
- service-worker-pwa 번들 여유가 342 B다(FE-GATE-012). 늘어난 코드는
  분기 둘이다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
  tests/unit/public-response-cache.test.ts tests/unit/public-response-cache-codec.test.ts
  tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm check:optional-recipes (번들 예산)

Refs: 1105/02-02
2026-11-05 22:22:17 +09:00
DongHyeonka f738348d9d fix(bootstrap): 실패한 scope closer를 label과 함께 진단에 남긴다
문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template
participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는
Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를
`FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단
기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을
읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인
closer를 찾으려면 closer를 하나씩 지워 봐야 한다.

고른 방법(리뷰 대안 (다)):
- scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나
  남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`·
  `CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질
  때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면
  `scope_participant: <label>`. template participant 실패도 같은 길로
  남는다.
- 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`,
  값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은
  제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다.
- 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로
  넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다
  (`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가
  실패해도 나머지를 부른다"는 그대로다.
- 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서
  바로 드러나야 진단에서 label이 빠지는 일이 없다.

버린 대안:
- (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다.
- (나) wrapper만 제품 label을 기록: template participant 실패는 계속
  조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다.
- label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의
  뜻이 흐려진다.

위험·한계:
- 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다.
  더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다.
- 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은
  부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의
  label)은 모두 맞는다.
- 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09).

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts
  tests/unit/runtime-adapters-product-scope-participants.test.ts
  tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts
- corepack pnpm check:diagnostics
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts

Refs: 1105/02-01
2026-11-05 22:14:54 +09:00
DongHyeonka 8b92f45f5e fix(http): Fileserver 업로드 실패에 Envelope의 traceId를 싣는다
문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고,
V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver
client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를
서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다.

고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면
createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지
않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다.

위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패
(SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를
돌려주지 않아 traceId가 없다. V3도 같다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId
"trace-1"이 없어 모두 실패한다.

Refs: 1105/01-03
2026-11-05 22:12:19 +09:00
DongHyeonka 471b001c40 fix(http): Fileserver 504 TRANSFER_TIMEOUT를 결과 불명으로 읽고 멱등 응답은 V3 표를 쓴다
문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true,
retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시
올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다.
백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가
await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤
TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일
복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에
파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면
같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503
IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와
매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를
MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을
말하지 않는다. pin 대조도 이 표를 보지 않는다.

고른 방법:
- TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로
  MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로
  만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에
  내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE,
  STORAGE_FULL)이다.
- 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE,
  MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로
  판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다.
  503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400
  IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로
  NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔
  MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다.
- pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의
  행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는
  tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을
  옮기면 두 reader가 함께 다시 대조된다.
- Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약
  문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다.
- client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로
  맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절).
버린 대안:
- client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과
  불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일
  업로드에서는 use case가 취소하므로 근거도 없다.
- TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과
  pin 밖 상태가 남는다.

위험·한계:
- 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503
  IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다.
- 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이
  보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이
  시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true,
  retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에
  interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지
  docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을
  되돌린다(재검토 조건).
- 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다
  (UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성
  executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다.
- 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md
  추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은
  같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면
  충돌한다. 07-01과 함께 넣는 편이 낫다.
- Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은
  것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503
IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT is an unknown result the client does not offer to
retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as
the V3 Envelope table does"가 실패한다.

Refs: 1105/01-02
2026-11-05 22:11:17 +09:00
DongHyeonka 1c7c614b47 fix(service-worker): 사전 캐시를 Vite assets 폴더의 해시 파일로 제한한다
문제: 사전 캐시 수집기(`collectStaticAssets`)는 dist 전체를 돌고 파일
이름만 해시 정규식으로 본다. `public/` 파일은 이름 그대로 dist 루트에
복사되는데, `apple-touch-icon.png`, `android-chrome-192x192.png`,
`safari-pinned-tab.svg`는 정규식에 걸려 immutable 자산으로 들어간다(리뷰
06-R1). 제품이 같은 이름으로 아이콘을 바꾸고 CDN이 옛 바이트를 주면 새
릴리스 install이 INTEGRITY_MISMATCH로 통째로 거절된다. 이전 릴리스
fallback, 호스팅 정책 `/assets/*`, MIME probe, 레시피 문서는 모두
`assets/`만 가정한다.

고른 방법: 리뷰 06-01의 (a). 계약 모듈에 `BUILD_ASSET_DIRECTORY =
"assets/"` 하나를 두고, 수집기는 그 아래 파일만 받는다. 워커 fallback
(`service-worker-static-assets.ts`)과 probe(`hosting-probe.ts`)도 같은
상수를 읽는다. `build.assetsDir`를 바꿀 때(0925/06-08) 이 상수 한 곳만
고치면 된다. 수집기의 `.vite/` 제외는 새 조건이 덮으므로 지웠다. 레시피
문서에 루트 파일이 빠진다는 문장을 더했다.
버린 대안:
- 정규식을 Vite 해시 형식(8자 고정)으로 좁히기. 우연히 맞는 이름이 남는다.
- 문서만 고치기. 아이콘 문제가 그대로다.

위험·한계: 루트에 해시 이름 파일을 일부러 두는 제품은 그 파일이 사전
캐시에서 빠진다. Vite는 그런 파일을 만들지 않는다. 상수는 vite 설정에서
읽지 않는다. `build.assetsDir`를 바꾸는 제품은 상수도 같이 바꿔야 한다
(0925/06-08은 그대로 남는다).

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/service-worker-web-push-remediation.test.ts tests/unit/service-worker-runtime.test.ts tests/unit/hosting-probe.test.ts tests/unit/service-worker-build-output.test.ts
- RED: "precaches only the assets directory, not public files at the dist
  root"가 옛 수집기에서 루트 아이콘 세 개를 받아 실패한다.

Refs: 1105/06-01
2026-11-05 22:08:50 +09:00
DongHyeonka 23662fb23a fix(storage): 객체를 끝까지 돈 계정 삭제 purge는 늘 partition을 지운다
문제: 승인된 LOGOUT·ACCOUNT_DELETION purge는 객체 목록을 읽고, 하나씩
지우고, 마지막에 journal 행을 한 번 센 뒤 0이면 chunk sweep으로 끝나
`chunkSweep: "COMPLETED"`를 돌려준다. 목록과 세기는 각각 한 순간만 본다.
- 다른 탭이 새 객체를 put하는 중이면 purge의 remove가 그 put이 쥔
  origin lease를 기다린다. partition에 객체가 3개 이상이면 그 put은
  목록 뒤에 commit하고 세기 전에 complete까지 끝난다. 목록에도 행 수에도
  없어 sweep이 그 chunk를 건너뛰고, 계정 삭제 뒤에도 파일이 읽힌다
  (리뷰 실험 Y1b 메모리 20/20, Chromium 6/6). 저장소 테스트는 객체
  0~1개로만 돌아서 이 틈을 놓쳤다.
- FILES_READY에서 멈춘 put의 행이 `logicalKey`를 잃으면 세지 못한다.
  staging receipt가 chunk를 sweep에서 지켜 purge마다 COMPLETED인데
  receipt·chunk·manifest가 남는다(Y2).

고른 방법: 마지막 객체까지 돈 purge는 sweep 대신 늘 partition 삭제로
끝낸다(리뷰 2.1절 (d')). exclusive partition lock이 그때 진행 중인
put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition
행을 지우므로 두 경우를 함께 막는다. 객체 순회는 `removedObjects`·
`releasedBytes` 보고와 예산 단위 진행을 위해 남긴다. 예산이나 다른 탭의
변경(CONFLICT) 때문에 끝까지 돌지 못한 호출은 지금처럼
`moreObjectsAvailable: true`를 돌려주고, 그때만 journal 행을 세서 끝나지
않은 행이 있으면 바로 partition을 지운다(2026-11-03 05-01 그대로).
purge 성공 report는 이제 `partitionDeleted`와 `moreObjectsAvailable`
중 정확히 하나를 가진다(walk 뒤 abort도 more로 보고).

버린 대안:
- (a) sweep 뒤에 다시 세고 committed 객체를 한 번 더 본다: ①만 막고
  ②가 남는다. 다시 볼 때 정책상 남겨야 할 객체를 가려내려면 목록을 끝까지
  다시 읽어야 한다.
- (b)+(a): 둘 다 막지만 판단 조건이 일곱 개가 된다.
- 세기를 아예 없애기: 예산에 걸린 호출의 crash 행 처리가 다음 호출로
  밀린다. 지금 동작을 바꿀 이유가 없어 남겼다.

위험·한계:
- 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(지금까지는 끝나지
  않은 행이 있을 때만). 기다림 상한은 `mutationLockWaitTimeoutMs`
  (1103/05-02)이고 abort로 멈출 수 있다.
- 같은 partition에 LOGOUT 때 남겨야 하는 객체가 섞이면 이 방법은 맞지
  않는다. 지금 정책 검사는 OPAQUE_PARTITION이면 LOGOUT·ACCOUNT_DELETION
  모두 purge만 허용해 그런 객체가 생기지 않는다.
- port의 `chunkSweep`은 아무도 채우지 않는다. 읽는 코드가 깨지지 않게
  타입은 남기고 `@deprecated`로 적었다.
- recipe fake의 purge도 늘 `partitionDeleted`다.
- `logicalKey`를 잃은 행 자체는 여전히 남는다(05-03 설계). 그 bytes는
  이제 남지 않는다.
- Firefox·WebKit에서 Y1은 돌리지 않았다. browser spec은 객체 0·3개
  두 경우로 늘렸다.

검증: desktop batch에서 확인
- 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
- node scripts/run-vitest.ts run tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm test:browser-capabilities tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium

Refs: 1103/05-01
2026-11-05 22:08:19 +09:00
DongHyeonka 6608fef4ba fix(http): Fileserver 202 REJECTED를 파일 거절로 읽고 빈 파일은 보내지 않는다
문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고
READY가 아닌 state를 모두 202로 답한다(FileUploadController#created).
악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다
(FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의
첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일
하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH,
APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는
안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드
문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기
검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다.

고른 방법(리뷰 01-01 최소 개선 방향 (가)):
- schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패
  VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다.
  413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지
  않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입
  FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는
  성공 값으로 나오지 않는다).
- 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트)
  보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는
  이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다.
- 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201
  REJECTED는 여전히 SCHEMA_MISMATCH다.
- MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED·
  REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분).
- 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자
  결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다.
버린 대안:
- REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서
  거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다.
- 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는
  그대로 SCHEMA_MISMATCH다.

위험·한계:
- upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서
  VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로
  바뀐다. CHANGELOG [계약] 한 줄이 필요하다.
- 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서
  LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다.
- 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은
  백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다.
- 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와
  docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제
  업로드 검증(미검증).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file,
not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an
undeclared size that turns out empty"(fetch를 부름)가 실패한다.

Refs: 1105/01-01, 1103/01-01
2026-11-05 22:07:43 +09:00
DongHyeonka 27e3dec5dd fix(realtime): poll execute에 생성 때 검사한 descriptor를 넘긴다
문제: bounded poll은 생성 때 descriptor의 `retryBudget`이 0인지 본다
(1103/04-01). 그런데 `execute` 입력에는 descriptor가 없다. 조합 코드는
실행기에 넘길 descriptor를 스스로 골라야 하고, 같은 경로의 기본 GET
(`retryBudget: 2`)을 넘겨도 막는 것이 없다. 리뷰 04-R1 P5에서 poll 3회가
요청 9회, 실행기 대기 6번이었다. 타입 주석과 설계 9.2가 "같은 객체를
넘긴다"고 적을 뿐이다.

고른 방법: coordinator가 생성 때 검사한 그 객체를 모든 `execute` 호출에
`input.operation`으로 넘긴다. 생성 때 한 번 잡아 두므로 나중에
dependencies 객체가 바뀌어도 검사한 객체가 간다. 조합 코드는 클로저의
descriptor 대신 이것을 실행기에 넘기면 된다. 테스트의 V3 조합도 그렇게
바꿨다. 타입 주석(`bounded-polling.ts`, `bounded-poll-coordinator.ts`)과
설계 9.2를 고쳤다.
버린 대안: coordinator가 실행기를 직접 받아 부르기. 실행기 타입은
`adapters/http`에 있어 realtime 어댑터가 import할 수 없다(adapter 사이
import 금지, kernel 예외 아님). 구조 타입을 새로 두면 결과 매핑까지
coordinator가 정해야 해서 공개 모양이 크게 바뀐다.

위험·한계: 일부만 닫는다. 조합 코드가 `input.operation`을 무시하고 다른
descriptor를 실행기에 넘기면 여전히 attempt마다 요청이 최대 3번이다.
설계 9.2가 이 남은 틈을 적는다. 입력 칸을 더한 것이라 기존 `execute`는
그대로 돈다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "hands every execute call the descriptor it checked at creation"
  (받은 값이 undefined), "sends one request per poll attempt with a poll
  descriptor"(실행기에 undefined가 가서 요청 0개, PROTOCOL_MISMATCH)가
  옛 코드에서 실패한다.

Refs: 1103/04-01
2026-11-05 22:05:31 +09:00
DongHyeonka 05330e30a8 fix(realtime)!: 던지는 poll execute를 서버 장애가 아니라 PROTOCOL_MISMATCH로 끝낸다
문제: bounded poll은 `execute`의 throw를 PROVIDER_UNAVAILABLE/retryable로
바꿔 lease 안에서 다시 부른다(af00067). 설계 9.2가 권하는 조합은
`execute` 안에서 V3 실행기를 부르는 것이고, 실행기는 fetch 거절을 던지지
않고 NETWORK_FAILURE 결과로 돌려준다. 그래서 그 조합에서 throw는 결과
매핑·디코딩 같은 조합 코드 결함이다. 지금은 그 결함이 maxAttempts번의
요청과 ATTEMPT_FINISHED: PROVIDER_UNAVAILABLE, 끝으로
POLL_BUDGET_EXHAUSTED가 되어 서버 장애로 보인다. 원인 예외는 남지 않는다.

고른 방법: 리뷰 04-02의 선택지 (b). throw를 모양이 틀린 결과와 같은
계약 위반으로 본다. coordinator는 이미 `parseAttemptResult`가 거절한
결과를 재시도 없이 PROTOCOL_MISMATCH로 끝낸다. throw도 그 길로 보낸다.
lease 자신의 abort로 생긴 throw는 지금처럼 abort의 이유(ABORTED,
OFFLINE, 예산 소진 등)로 끝난다. `execute` 타입 주석, 설계 9.2와 13.1의
PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행을 같이 고쳤다.
버린 대안:
- (c) 주석과 13.1에만 "throw는 서버 장애로 재시도된다"를 적기. 완료
  기준은 "결과를 보고 조합 결함과 서버 장애를 구분한다"인데, (c)는 읽는
  사람만 알고 결과는 그대로라 구분할 수 없다.
- 관측에 throw 표시 칸을 더하기. 닫힌 관측 어휘를 넓히고, 결과 kind는
  여전히 서버 장애다.

위험·한계:
- 배럴로 공개된 bounded poll의 결과가 바뀐다. repo 안 소비자는 테스트뿐이다.
- `fetch`를 직접 부르는 조합은 네트워크 실패를 결과로 바꾸지 않으면 첫
  거절에서 lease가 끝난다. 설계가 권하지 않는 조합이고, 타입 주석과
  9.2가 "실패도 결과로 돌려준다"를 적는다.
- reconnect coordinator는 던지는 `attempt`를 계속 PROVIDER_UNAVAILABLE로
  재시도한다. 그쪽 attempt는 브라우저 연결 API를 감싸는 자리라 이번
  범위 밖이다.
- CHANGELOG.md 미출시 [계약] 행의 "poll은 던지는 execute도 lease 안에서
  다시 시도한다"는 이 커밋과 맞지 않는다. CHANGELOG는 오케스트레이터가
  고친다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "ends the lease with PROTOCOL_MISMATCH for an async execute that
  rejects"·"... throws before returning"가 옛 코드에서 execute 3회,
  POLL_BUDGET_EXHAUSTED로 실패한다. "keeps ABORTED ..."는 양쪽에서 통과한다
  (보존 조건).

BREAKING CHANGE: createBoundedPollCoordinator의 `execute`가 던지면(abort로
생긴 것 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable: false)로 lease가
끝난다. 전에는 PROVIDER_UNAVAILABLE로 maxAttempts까지 재시도했다.
네트워크 실패를 throw로 내던 `execute`는 그것을 retryable
PROVIDER_UNAVAILABLE 결과로 바꿔 돌려준다.

Refs: 1105/04-02
2026-11-05 22:03:56 +09:00
DongHyeonka 3d3d6527ef fix(http): Fileserver 업로드 client가 browser-file-storage 포트를 import하지 않는다
문제
src/adapters/http/fileserver-upload.ts(1103/01-01)가 입력 타입으로
application/ports/browser-file-storage의 FileByteSource를 import한다.
test:browser-file-storage-removal(FE-GATE-020)은 그 선택 런타임과 포트를
지우고 남은 코드가 import하지 않는지 본다. 그래서 "Removed browser
file/storage runtime is still imported by: src/adapters/http/
fileserver-upload.ts"로 항상 실패한다(리뷰 조치 X2 #7).

고른 방법
- client 안에 같은 모양의 FileserverByteSource(byteLength, stream이
  Result<Uint8Array, { code }>를 낸다)를 두고 배럴로 낸다. client가 쓰는
  것은 이 셋뿐이다. 제품은 FileContentPort.openSource가 준 FileByteSource를
  그대로 넘긴다(구조 타입).
- 버린 대안: 드릴이 이 client도 함께 지우기. http 배럴이 export하므로 배럴도
  고쳐야 하고, 파일 runtime을 쓰지 않는 제품도 업로드 client를 잃는다.

위험·한계
- FileByteSource 모양이 바뀌면 두 타입이 어긋날 수 있다. 통합 테스트가
  FileByteSource 값을 client에 넘기므로 check:types가 그 어긋남을 잡는다.

검증
- check:types(테스트의 FileByteSource → client 호환), lint,
  check:architecture, test:integration 통과. 드릴은 이 커밋 뒤 재실행한다.

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, README.md 14.6 X2 #7
2026-11-05 01:35:37 +09:00
DongHyeonka 20a5b084fd fix(http): Fileserver 422 파일 거절은 입력 거절로, 키 재사용 불일치는 공통 표대로 읽는다
문제
fix/r1103-transfer의 Fileserver 업로드 client는 실패 kind를 공유 Envelope
판정(envelopeFailureReading)에서 받고 413·415만 VALIDATION_REJECTED로
바꾼다. fix/r1103-http(1103/08-05)는 필드 목록 없는 422를
UNKNOWN_CLIENT_FAILURE로 읽게 했다. 두 브랜치를 합치자 Fileserver의
422(digest·서명·검사기 거절, 예: MALWARE_DETECTED)가 입력 거절이 아니게
되어 통합 테스트 2건이 실패한다.

고른 방법
- Fileserver 계약에서 422는 파일 자체의 거절이다(백엔드
  docs/fileserver/http-contract.md 상태 표). 사용자가 파일을 바꿔야 하는
  413·415와 같이 VALIDATION_REJECTED로 둔다.
- 422 IDEMPOTENT_REQUEST_MISMATCH(같은 키, 다른 본문)는 파일 문제가
  아니므로 08-05의 공통 판정(UNKNOWN_CLIENT_FAILURE)을 따른다. 테스트
  기대값도 그렇게 바꿨다.
- 버린 대안: 공통 판정을 422 전체 입력 거절로 되돌리기. 08-05가 고친
  결함(같은 키 불일치를 입력 오류로 보임)이 다시 생긴다.

위험·한계
- 422 code 목록을 파일 거절로 고정하지 않고 "불일치가 아니면 파일 거절"로
  본다. 백엔드가 파일 업로드에 다른 뜻의 422를 더하면 다시 본다.

검증
- test:integration 189건(fileserver-upload 48건 포함), check:types,
  lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, 08-presentation.md 08-05
2026-11-04 22:34:35 +09:00
DongHyeonka 6088f6e533 chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 22:28:57 +09:00
DongHyeonka e20b5bfe3a chore(review): 1103 업로드·전송 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 01-01 01-02 01-03
2026-11-04 21:50:46 +09:00
DongHyeonka 55d0d48424 chore(review): 1103 저장소·파일 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-01~02-05 05-01~05-04

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	src/bootstrap/product-composition-contract.ts
#	src/bootstrap/runtime-adapters.ts
2026-11-04 21:46:20 +09:00
DongHyeonka c17b3a05d6 chore(review): 1103 세션 owner 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-03 09-11

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 21:40:51 +09:00
DongHyeonka 4f78890576 fix(browser-files): 위험 확장자를 safe extension으로 쓰는 다운로드 정책을 거절한다
문제: download 정책 registry는 safeExtension의 형식만 본다. 파일명
금지 목록(.exe, .html, .js 등)은 사용자가 준 이름에만 쓴다
(1101/02-02). 그래서 mediaType application/pdf + safeExtension .exe
정책이 조립되고, invoice.pdf가 invoice.exe로 browser handoff된다
(리뷰 E-7).

고른 방법: snapshotDownload가 금지 목록에 있거나 그것으로 끝나는
(.tar.js) safeExtension을 다른 정책 오류와 같이 TypeError로 거절한다.
목록은 file-policy.ts의 DEFAULT_FORBIDDEN_EXTENSIONS 하나를 쓰고,
isForbiddenDownloadExtension으로 내보낸다. browser-managed capability는
정책과 같은 safeExtension이어야 하므로 그 경로도 함께 막힌다.
버린 대안: media type과 확장자 짝 표를 두는 것. 표를 누가 소유할지
정해야 하고 범위가 크다. 이번에는 하지 않았다.

위험·한계: 이 확장자를 쓰던 다운스트림 정책은 조립 때 실패한다(보안
강화 방향). media type과 확장자가 서로 맞는지는 여전히 보지 않는다
(설계 문서에 적었다). file-transfer 번들 56,068 → 56,100 / 57,800 gzip B.

검증:
- RED: browser-file-policy-registry.test.ts 새 3건(.exe, .HTML, .tar.js)이
  throw 없음으로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 98건 통과.
  check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-02
2026-11-04 21:18:51 +09:00
DongHyeonka f800549315 feat(http): 짝 백엔드 Fileserver의 multipart 한 번 업로드 client를 더한다
문제: 두 템플릿을 짝으로 쓰면 파일 업로드 경로가 없다. 프론트 업로드
레시피는 PRESIGNED_MULTIPART_V1 서버를 가정하는데 짝 백엔드는 그 코드를
지웠고, 짝 백엔드 Fileserver(POST /v1/files)를 부를 프론트 client는 없다.
src 전체에 multipart 요청을 만드는 코드가 없다.

고친 방법(리뷰 D1 (나-1)): src/adapters/http/fileserver-upload.ts에
createFileserverUploadClient를 둔다. 백엔드 bbe944bd 계약 그대로다.
- 입력은 FileContentPort.openSource가 주는 FileByteSource다. 바이트를 한
  번 읽어 multipart 본문(파트 이름 file, RFC 7578, 파일 이름은 HTML 폼
  인코더처럼 escape)을 직접 만든다. File·Blob은 이 adapter에 들어오지
  않는다(eslint browser-data 경계). 선언 크기가 maxFileBytes보다 크면 읽기
  전에 거절하고, 읽는 중에 넘어도 멈춘다. 선언 크기가 있으면 본문 버퍼
  하나에 바로 쓴다.
- 전송 규칙은 레시피와 V3 실행기와 같다. credentials는 인증 프로필이
  정하고, 자격 증명 헤더는 admitCredentialHeaders로 프로필에 맞춰 받는다.
  redirect "error", no-referrer, no-store, 응답 본문 상한, 바이트에 비례한
  deadline 하나, 호출자 abort(커널 createAbortableOperation).
- 성공: 201 READY / 202 그 밖의 state를 Envelope에서 읽는다. 201과 202의
  state가 맞지 않거나 size가 보낸 바이트와 다르면 SCHEMA_MISMATCH,
  APPLIED_CONFIRMED.
- 실패: backend-envelope.ts의 readFailureEnvelope와 envelopeFailureReading을
  그대로 쓴다. 효과 판정은 Fileserver 계약을 따른다. details.ambiguous,
  AMBIGUOUS_COMPLETION, IDEMPOTENT_IN_FLIGHT, IDEMPOTENCY_COMPLETION_UNKNOWN은
  MAYBE_APPLIED. 그 밖의 4xx는 NOT_APPLIED(백엔드 UploadFile use case가
  모호하지 않은 실패에서 업로드를 취소한다). 5xx는 이름 붙인 Fileserver
  code만 NOT_APPLIED이고 나머지는 MAYBE_APPLIED. 보낸 뒤 네트워크 실패·
  시간 초과·abort도 MAYBE_APPLIED. Envelope의 retryable:false와 상한(기본
  30초)을 넘는 Retry-After는 retryable을 false로 만든다(01-02와 같은 규칙).
- Idempotency-Key 헤더를 보낸다. client는 스스로 다시 보내지 않는다.

위치를 http adapter로 고른 이유: Envelope 해석(backend-envelope.ts), 자격
증명 admission(http-contract-bridge.ts), bounded reader를 adapter 안
import로 다시 쓴다. 새 adapter 사이 import 예외가 필요 없다. 바꾼 http
파일은 index.ts의 export 한 묶음뿐이다.
버린 대안:
- backend-envelope.ts를 커널(src/adapters/platform/)로 옮기고 client를
  browser-transfer에 둔다. 다른 작업이 지금 고치는 파일을 옮겨야 하고,
  커널은 제품 중립 primitive 자리인데 백엔드 짝 정책이 들어간다.
  file-transfer 레시피 예산 여유도 1.7KB뿐이고, 이 client는 presigned
  레시피와 무관한데 그 제거 드릴에 함께 지워진다.
- browser-transfer에 Envelope 파서를 하나 더 둔다. 갈라진 사본이다.
- V3 실행기에 multipart 본문을 더한다. 1,900줄짜리 실행기를 다른 작업과
  동시에 크게 고쳐야 한다.
- FormData와 Blob을 쓴다. http adapter는 File·Blob을 쓸 수 없고(eslint),
  기능은 Blob을 갖지 않는다.

조립: 제품이 product-composition.ts에서 client 재료
(FileserverUploadClientDependencies)를 capability로 넘기고, 기능 adapter가
createFileserverUploadClient를 부른다. 그래서 템플릿 boot 번들에는 들지
않는다. 매뉴얼 02 결정표 7절, patterns.md, 두 architecture 문서, 레시피
fallback이 이 경로를 가리킨다. adapter INVENTORY와 상세 리뷰 표에 행을
더했다(번호는 끝에 141로 붙였다).

위험·한계:
- 재개가 없다. 파일 전체를 메모리에 한 번 읽는다(maxFileBytes까지). tus
  client는 없다.
- 짝 백엔드 bbe944bd의 POST /v1/files는 멱등 키를 읽지 않는다
  (NOT_IDEMPOTENT). MAYBE_APPLIED 뒤 같은 키로 다시 보내도 파일이 두 개
  생길 수 있다. 매뉴얼에 적었다.
- 효과 판정 표(NOT_APPLIED_5XX_CODES, MAYBE_APPLIED_CODES)는 백엔드
  bbe944bd 기준이다. 어긋남을 알리는 검사는 없다(12-06과 같은 종류).
- 실제 짝 백엔드를 띄운 업로드는 하지 않았다. 테스트는 계약대로 답하는
  MSW다. 실제 브라우저(Playwright)에서도 돌리지 않았다.
- 템플릿 기본 product-composition.ts가 자격 증명 owner를 노출하지 않으므로,
  템플릿 세션(EXTERNAL_BEARER)으로 올리려면 제품이 자기 credential
  provider를 써야 한다.

검증:
- tests/integration/fileserver-upload.test.ts 48건 통과(201/202 본문,
  Envelope 실패 16종, 409 IDEMPOTENT_IN_FLIGHT + Retry-After 2, 상한 밖
  Retry-After, 보낸 뒤 네트워크 실패 뒤 같은 키 재전송, 시간 초과, abort,
  자격 증명 거절, 크기·입력 거절). multipart 본문은 undici FormData
  파서로 다시 읽어 확인했다.
- 변이 7건(4xx 판정, ambiguous 무시, 상한 무시, credentials 고정, 키 누락,
  201/202 state 검사 제거, Envelope retryable 무시) 모두 실패를 만들었다.
- check:types, lint(바꾼 파일), check:architecture, check:adapter-inventory,
  verify:documentation, check:registries, check:ci 통과
- check:bundle PASS: initial JS 201,921 / 204,800 gzip bytes. 빌드 산출물
  어디에도 client 코드가 없다(dist grep). check:optional-recipes:source PASS
  (file-transfer 56,082 / 57,800)

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
2026-11-04 21:05:23 +09:00
DongHyeonka ba2b4f4c6d feat(contracts): 짝 백엔드 계약 기준점을 기계가 읽는 pin과 답 표로 둔다
문제
짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 5786126c)뿐이고, 이
SHA를 읽는 코드·설정·테스트가 없다. 쓰기 전 거절 표 REFUSED_BEFORE_WRITE와
5xx 판정은 백엔드 http-contract.md §2를 손으로 옮긴 것이다. 리뷰 중 백엔드에
bbe944bd가 들어와 503 IDEMPOTENCY_COMPLETION_UNKNOWN이 새로 생겼는데 프론트의
어떤 검사도 알리지 않았다(README 10.6).

고른 방법 (결정 D6 (1)+(2))
- config/contracts/backend-contract-pin.json: repo, 전체 SHA(bbe944bd), 대조한
  문서와 절(§1·§2·§4), 프론트 쪽 계약 절·판정 파일, 담당.
- config/contracts/backend-idempotency-answers.json: 백엔드 §2 표 여섯 행과
  §4 REQUEST_TIMEOUT을 code·status·쓰기 전 거절·같은 키 재전송 열로 옮겼다.
  백엔드가 문서에 적은 사실만 담는다.
- tests/unit/backend-contract-pin.test.ts: 두 JSON의 모양과 같은 SHA를
  확인하고, 답마다 프론트 판정이 그 두 열에서 나오는 값인지(쓰기 전 거절이면서
  같은 키 재전송이 아니면 NOT_APPLIED, 아니면 MAYBE_APPLIED, 자동 재전송은
  둘 다 참일 때만) 본다. 반대로 프론트 표의 행이 모두 이 답 표나 6.1절
  읽기(VALIDATION_FAILED)로 뒷받침되는지 본다. 그래서 백엔드 표에 행이
  늘거나 status가 바뀐 JSON을 넣으면 실패한다.
- scripts/check-backend-contract-drift.ts(check:backend-contract-drift):
  형제 디렉터리(또는 --backend)의 백엔드 checkout이 pin 뒤에 http-contract.md를
  바꿨는지 알리고 바뀐 표 행을 보인다. CI에는 백엔드가 없어 게이트 밖이다.
  ungated-scripts.json에 이유를 적었다.
- 계약 문서 4.1·6절의 기준 커밋을 bbe944bd와 pin 파일로 옮겼다. 6.1절 표는
  5786126c..bbe944bd 사이 바뀐 백엔드 파일 다섯을 다시 읽었다. 판정은 같고
  줄 번호만 옮겼다(IdempotencyExecutor, GlobalExceptionHandler →
  HttpStatusErrorCodes, FailureCategory, PersistenceExceptionTranslator).

버린 대안
- 백엔드 error-codes.yaml과 문서 다이제스트를 기록: 다이제스트는 바뀐 것만
  알리고 무엇을 고칠지 말하지 않는다.
- 백엔드가 계약 패키지를 발행: 백엔드 빌드에 JS 발행이 생긴다. 지금 규모에는
  pin과 표가 작다.

위험·한계
- 답 표 JSON은 사람이 백엔드 문서에서 옮긴다. 옮기는 실수는 drift 스크립트와
  리뷰가 잡는다. 백엔드 쪽이 같은 JSON을 자기 레지스트리와 대조하는 일은
  백엔드 저장소 몫이다.
- 백엔드 HEAD는 이미 pin 뒤로 갔다(지금 c508b1ba). http-contract.md §2의 500
  IDEMPOTENCY_RECOVERY_REQUIRED 행이 "같은 키 재전송은 안전하다"로 바뀌었다.
  프론트 판정(MAYBE_APPLIED, 자동 재전송 없음, 사용자 재전송은 같은 키)은 그
  문장과도 맞는다. pin은 지시대로 bbe944bd에 두었다.

검증
- 새 테스트 10건 통과. 변이 4종 검출: 답 표에 503 새 code 행 추가, 프론트
  표에서 COMPLETION_UNKNOWN 제거, 프론트 표에 근거 없는 400 BAD_PARAMETER
  추가, 답 표의 RECOVERY_REQUIRED status 변경.
- check:backend-contract-drift: worktree에서 skipped(exit 0), 실제 백엔드
  checkout으로 exit 1과 바뀐 RECOVERY_REQUIRED 행 출력.
- test:unit 178파일 2,645건, check:ci, check:types, eslint,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
2026-11-04 21:03:40 +09:00
DongHyeonka af7d0b1824 fix(browser-transfer): 재조정에서 checkpoint 삭제가 실패해도 resourceId를 준다
문제: complete 응답을 잃은 뒤 다음 upload()가 재조정해 서버 status
QUARANTINED를 찾았을 때, 로컬 checkpoint 삭제가 한 번 실패하면 runtime이
그 실패를 그대로 돌려준다({UNAVAILABLE, UPLOAD_RECONCILE, retryable:true,
RESUME}). 서버에는 자원이 이미 있는데 이 호출은 resourceId를 잃는다. 같은
상황의 complete 경로는 삭제 실패를 무시하고 성공을 준다.

고친 방법: 재조정의 QUARANTINED 분기도 complete 경로와 같이 삭제 결과와
상관없이 {QUARANTINED, resourceId, replayed:true}를 준다. 남은 행은 다음
upload()나 abort()가 같은 자원으로 정리한다. 설계 문서 4.3절의 같은 규칙
줄에 재조정 경우를 더했다.

위험·한계: 삭제가 계속 실패하는 저장소에서는 행이 남는다. 다음 호출마다
status를 한 번 읽고 같은 resourceId를 replayed로 준다. complete 경로와 같은
한계다.

검증:
- 새 테스트: 고치기 전 {ok:false, UNAVAILABLE, UPLOAD_RECONCILE} (리뷰 X4와
  같다), 고친 뒤 {ok:true, QUARANTINED, resource_01, replayed:true}, 행 남음,
  다음 호출이 정리
- 영역 단위 테스트 15파일 276건 통과
- check:types(test), eslint(바꾼 파일) 통과

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 0929/01-02
2026-11-04 20:59:31 +09:00
DongHyeonka 274ae69088 perf(browser-transfer): 이어 올리는 스트림 업로드는 보낼 part만 해시한다
문제: FILE_BYTE_SOURCE로 이어 올리면 runtime이 서버가 이미 받은 part까지
SHA-256으로 다시 검증한다. 검증(verifyUploadPartBytes)이 수락 확인보다
앞에 있기 때문이다. 8 part 중 6개가 수락된 뒤 이어 올리면 part 해시가
16번 돈다. RANGE_READER 경로는 같은 상황에서 10번이다(manifest 8 + 보낼
part 2).

고친 방법: 스트림 경로에서 수락된 part는 검증 전에 건너뛴다. 보내지 않는
part의 바이트는 검증할 필요가 없다. 파일이 checkpoint와 같은지는 그 앞의
manifest 계산이 이미 확인한다(다른 파일이면 STALE_RESULT). part의
offset·길이 확인은 그대로 모든 part에 한다.

위험·한계: 스트림은 여전히 처음부터 끝까지 읽는다. 읽기를 건너뛰는 것은
스트림 모양상 할 수 없다.

검증:
- 새 테스트(8 part 중 6개 수락 뒤 FILE 재개, part 크기 digest 수): 고치기
  전 16, 고친 뒤 10
- 영역 단위 테스트 15파일 275건 통과
- check:types(test), eslint(바꾼 파일) 통과

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 1101/01-02
2026-11-04 20:57:48 +09:00
DongHyeonka f6b74ed496 fix(storage): put idle 상한이 lock 대기 상한보다 짧지 않은 OPFS 정책을 거절한다
문제: putIdleTimeoutMs < mutationLockWaitTimeoutMs는 05-07이 기대는
관계다(멈춘 put이 idle 상한에서 origin lock을 놓아야 줄 선 writer가
대기 상한 전에 돈다). 이 관계가 opfs-policy.ts 주석에만 있고, 정책
검사는 각 값의 범위만 본다. 두 값을 뒤집은 정책은 조용히 통과하고,
멈춘 put 하나가 다른 탭의 모든 쓰기를 BLOCKED로 끝낸다.

고른 방법: assertOpfsRuntimePolicy가 putIdleTimeoutMs >=
mutationLockWaitTimeoutMs를 TypeError로 거절한다. 다른 정책 오류와
같은 자리·같은 방식이다. 기본값(2분 < 10분)과 repo 안의 모든 정책은
이미 관계를 지킨다.

위험·한계: 이 관계를 어긴 정책을 쓰던 다운스트림은 조립 때 실패한다.
의도한 동작이다.

검증:
- RED: opfs-worker-runtime.test.ts 새 2건(같음, 김)이 throw 없음으로 실패.
- GREEN: OPFS 단위 3파일 + tests/recipes + tests/contract 174건 통과.
  check:types, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-09
2026-11-04 20:56:03 +09:00
DongHyeonka 39c1de2e5e feat(diagnostics): 결과 불명 쓰기의 effect와 원인을 진단에 싣는다
문제
실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는
진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는
묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중
409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다.
텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무
거절은 선언 전까지 결과 불명이라 이 구분이 필요하다.

고른 방법
- effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두
  HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를
  쓴다. cardinality는 bounded. projector가 두 sink에 싣는다.
- 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌
  UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중),
  IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED,
  SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409·
  422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용).
- VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던
  "effect_certainty는 필요해지면 더한다" 문장은 지웠다.

버린 대안
- 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이
  먼저다. 닫힌 원인 집합이면 그 결정과 무관하다.
- 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이
  섞인다. 비율은 effect_certainty로 센다.

위험·한계
- Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다.
  응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다.
- 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록
  맞춰야 한다.

검증
- RED: envelope 진단 9행(effect·reason), observability 1건, cardinality
  8건 실패.
- GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다
  effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다.
  tests/unit·integration·component·features·contract·runtime-schema·platform
  282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify
  한도(ENOSPC)로 이 변경과 무관하다.
- check:diagnostics, check:types, lint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05
2026-11-04 20:54:24 +09:00
DongHyeonka 631ce339b9 fix(http): 실패 Envelope의 meta.traceId를 AppFailure.traceId로 싣는다
문제
AppFailure와 createFailure는 traceId를 받는다. 이를 채우던 곳은 V2
client.ts의 Envelope meta.traceId였고, 048f490이 V2를 지운 뒤 src에서
traceId를 넘기는 곳이 없다. 빈 칸을 믿고 만든 화면·진단 코드는 늘
undefined를 받는다. 짝 백엔드는 모든 실패 Envelope의 meta에 W3C trace id를
싣는다(http-contract.md §1).

고른 방법
- readFailureEnvelope가 error와 함께 meta.traceId를 돌려준다. 값은 이미
  meta 스키마의 id 문법([A-Za-z0-9._:-]{1,128})을 통과한 것이다.
- 실행기가 그 값을 PROBLEM 결과의 SafeResponseMetadata.traceReference에
  싣고, 바인딩이 AppFailure.traceId로 옮긴다. requestId 경로(반사 헤더 →
  보낸 id)는 그대로다.
- 계약 문서 5절의 correlation 문단에 한 줄 더했다.

버린 대안
traceId를 타입에서 지우기(리뷰의 다른 선택지): 다운스트림이 쓰는지 확인이
필요하고, 백엔드가 이미 주는 지원용 id를 버린다.

위험·한계
- Envelope operation의 실패 응답만 채운다. 성공 뒤 매핑 실패, 전송 실패,
  Envelope 없는 operation은 traceId가 없다.
- 텔레메트리에는 싣지 않는다(요청 단위 값).
- 같은 발견의 VD-23 401 문장은 다른 작업 몫이라 건드리지 않았다.

검증
- RED: envelope 통합 1건 실패(404 실패의 traceId 없음).
- GREEN: meta.traceId가 있으면 그 값, 없으면 칸 없음. tests/unit·
  integration·component·features·contract·runtime-schema 253파일 중 252파일
  통과. 남은 1건(provider-guardian-transaction "cleans a linked raw inode")은
  이 기계의 inotify 한도(ENOSPC watch)로 단독 실행에서도 실패하며 이 변경과
  무관하다.
- check:types, lint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-06
2026-11-04 20:49:30 +09:00
DongHyeonka 49a09868ad feat(http): Envelope 목록의 meta.page를 mapSuccess에 넘긴다
문제
짝 백엔드는 페이지 목록의 전체 수·페이지 번호를 meta.page(number·size·
total·sort)에 싣는다(http-contract.md §1). 프론트 Envelope 읽기는 meta에서
id 셋만 남기고 data만 꺼낸다. 그래서 목록 기능은 첫 페이지(기본 20개)만 받고
전체 수를 모른다. 생성된 목록 화면의 "총 N개 항목"은 배열 길이라 페이지
크기를 전체 수처럼 보인다(리뷰 실험 X-G). 우회하려면 responseEnvelope를 빼야
하고, 그러면 Envelope 실패 판정을 함께 잃는다.

고른 방법
- backend-envelope.ts: meta에 page 스키마(정수, number·total 0 이상,
  size 1~100, sort 문자열 또는 null). 범위 밖이면 page만 버리고 응답은 읽는다.
  readSuccessEnvelope가 data와 함께 page를 돌려준다.
- 실행기의 SUCCESS 결과에 선택 칸 page. outputValidator는 지금처럼 data만
  본다.
- 바인딩: mapSuccess(value, context)의 두 번째 인자 FeatureHttpSuccessContext
  { page? }. 한 인자짜리 기존 mapSuccess는 그대로 맞는다.
- 배럴에서 EnvelopePage·FeatureHttpSuccessContext 타입을 낸다.
- 계약 문서 4.1절에 meta.page 경로와 "bulk results는 지원하지 않는다", 7절에
  "짝 백엔드는 offset meta.page"를 적었다.

버린 대안
- outputValidator에 { data, page }를 넘기기: 기존 기능 스키마가 모두 깨진다.
- 기능 스키마가 Envelope 전체를 읽기: 실패 판정을 잃는다.
- page가 범위 밖이면 응답 전체를 거절: meta의 모르는 키는 무시한다는 백엔드
  §1 규칙과 어긋난다.

위험·한계
- 생성기(create-feature.ts)의 목록 화면은 아직 배열 길이를 보인다. 생성기
  담당 작업이 page.total을 쓰도록 이어 받는다.
- bulk는 지원하지 않고 문서로만 알린다.

검증
- RED: envelope 통합 3건 실패(mapSuccess가 page를 받지 못함, 정렬 없는
  page 2건).
- GREEN: 같은 파일 51건 통과. 범위 밖 page 3건(size 500, number -1, total
  1.5)은 page 없이 SUCCESS. tests/unit·integration·component·features·
  contract·runtime-schema 253파일 3,209건 통과.
- check:types, lint, check:architecture, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-02
2026-11-04 20:46:38 +09:00
DongHyeonka fd6b6315c0 fix(storage): 소속 partition이 없는 손상 journal 행을 따로 세고 경보에서 뺀다
문제: partition 삭제는 journal 행을 LOGICAL_KEY_INDEX로 찾는다. 인덱스에는
logicalKey 값이 있는 행만 들어가므로, 그 값까지 깨진 행은 승인된
ACCOUNT_DELETION으로도 지워지지 않는다(X4: partition 파일 0개인데 행은
남음). 그 행은 reconcile마다 corruptTransactions 1, OBJECT_RECONCILE
DEGRADED/CORRUPT_DATA로 남는다. runbook은 "키로 찾으므로 손상 row도
지워진다", "partition이 승인된 purge로 지워질 때만 함께 지워진다"고 적고
수동 삭제를 금지한다. 운영자는 늘 켜진 경보를 받지만 할 수 있는 일이 없고,
그 경보가 진짜 손상을 가린다.

고른 방법(리뷰 (a)+(b)): 소속을 모르는 행은 지울 근거가 없으므로 지우지
않는다. 대신
- journal의 listIncomplete가 손상 행 가운데 이 authority의 partition 키
  범위에 들지 않는 행을 unattributedRows로 따로 센다(0이면 칸 없음).
- reconcile report에 unattributedCorruptTransactions를 싣고(0이면 칸
  없음), DEGRADED 관측은 purge가 지울 수 있는 손상 행이 있을 때만 낸다.
- runbook §0·§7 문장을 코드와 맞추고, 이런 행에 대해 할 일(같은 수면
  없음, 늘면 writer를 찾음, 수동 삭제 금지)을 적었다.
버린 대안: (a)만 — 경보가 계속 켜진다. (c) 소속을 모르는 행 자동 삭제 —
그 행이 가리키던 staging을 추적할 근거가 사라진다(runbook §0 3번).

위험·한계: 공개 타입에 선택 칸 두 개가 는다(OpfsJournalPage
.unattributedRows, OpfsReconciliationReport
.unattributedCorruptTransactions). 직접 만든 journal이 칸을 채우지 않으면
지금처럼 모든 손상 행이 경보에 남는다. 소속 없는 행만 있을 때 관측이
SUCCEEDED가 되므로, 그 수는 report로만 보인다. 이런 행의 staging은 purge의
partition 삭제 조건(countPartitionTransactions)에 잡히지 않는다.
offline-indexeddb 번들 37,555 → 37,705 / 38,500 gzip B.

검증:
- RED: indexeddb-opfs-journal.test.ts 새 테스트가 unattributedRows 없음,
  opfs-worker-runtime.test.ts 새 X4 테스트가 unattributedCorruptTransactions
  없음으로 실패.
- GREEN: 키 있는 손상 행은 removePartition이 지우고 키 없는 행은 남는다.
  키 없는 행만 있으면 관측 SUCCEEDED, 키 있는 손상 행이 더해지면
  DEGRADED:CORRUPT_DATA. OPFS 단위 3파일 + optional-runtime-host +
  tests/recipes + tests/contract 176건 통과. check:types, 바꾼 파일
  eslint, check:optional-recipes:source PASS, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-03
2026-11-04 20:38:17 +09:00
DongHyeonka 1e8b3d049f feat(http): operation이 쓰기 전 업무 거절 code를 선언한다
문제
Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고
나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다.
짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400
<FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를
띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험
X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데
400·409·422는 정할 자리가 없다.

고른 방법 (결정 D2 ①)
- CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[].
  표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code
  목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다.
- 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만,
  code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다
  (409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다).
- 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립
  없이 실행기를 부르는 경로의 fail-close다.
- 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로
  두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다.
- 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지,
  <FEATURE>_INVALID 예와 거부 문구를 적었다.

버린 대안
- 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도
  나온다.
- 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는
  분류기가 키 보호를 푼다.
- 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로
  중복이 생긴다.
- 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②).

위험·한계
- 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가
  중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드
  코드에서 던지는 곳을 확인한 code만 적으라고 한다.
- 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이
  이어 받는다.
- 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다.

검증
- RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3,
  envelope 통합 3, form-foundation 1).
- GREEN: tests/unit·integration·component·features·contract·runtime-schema
  253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable,
  저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면
  effect-unknown, 저장 꺼짐, fetch 1회.
- 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록
  복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도
  계속 검출.
- check:types, lint, check:registries, check:architecture,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01
2026-11-04 20:38:12 +09:00
DongHyeonka 7b55f0f83d fix(storage): partition lock을 기다리는 put·delete가 자기 abort로 끝난다
문제: withTransactionLock은 partition lock을 signal 없이 요청한다
(withPartitionLock("shared", operation, undefined, run)). put·remove의
request.signal이 거기까지 오지 않고, Web Locks 요청은 signal이 없으면
시간 제한도 없다. mutationLockWaitTimeoutMs는 worker의 origin lease에만
걸린다. 다른 탭의 partition 삭제가 큰 업로드를 기다리는 동안 같은
partition에 put·remove(또는 만료 객체를 지우는 open)를 부르고 취소하면,
삭제가 끝날 때까지 결과가 오지 않는다(X5: abort 뒤 200 ms 동안 대기).
05-01로 정상 purge도 partition 삭제를 쓰게 되어 이 대기가 더 자주 난다.

고른 방법: put·remove가 request.signal을 withTransactionLock에 넘기고,
withPartitionLock은 kernel createAbortableOperation으로 caller signal과
mutationLockWaitTimeoutMs를 묶은 signal로 lock을 요청한다. caller
abort면 ABORTED, 시간이 다 되면 BLOCKED(retryable, RETRY)다. worker의
acquireLease와 같은 값·같은 결과다. lock을 얻으면 바로 close해 타이머를
지운다(얻은 lock에 대한 abort는 Web Locks에서 아무 일도 하지 않는다).
lock 전 abort는 journal begin 전이라 보상할 것이 없다.
버린 대안: signal만 넘기기(리뷰 최소안). 취소는 되지만 "상한 없음"이
남는다. 새 정책 값 추가. 같은 의미의 값이 이미 있다.

위험·한계: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다.
다른 탭 put이 10분(기본값)보다 오래 걸리면 purge가 BLOCKED로 끝나고
호출자가 다시 부른다. 전에는 끝없이 기다렸다. 실제 브라우저에서 abort
경합은 돌리지 않았고 Node Web Locks로만 확인했다. offline-indexeddb
번들 37,521 → 37,555 / 38,500 gzip B.

검증:
- RED: opfs-worker-runtime.test.ts 새 2건. abort한 put이 200 ms 안에
  끝나지 않음(STILL_WAITING), 가짜 시계로 상한을 넘겨도 put이 끝나지
  않아 10초 timeout.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes 151건
  통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source
  PASS, verify:documentation 통과.
- browser: heavy lock 안에서 opfs-runtime·indexeddb-runtime spec 3엔진
  27/27 통과. 첫 실행은 dev server가 실행 중에 페이지를 다시 불러
  5건이 "Execution context was destroyed"로 떨어졌고, 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-02
2026-11-04 20:34:28 +09:00
DongHyeonka 5d0f5ad7f8 docs(realtime): heartbeat를 멈춘 WebSocket이 예산을 새로 받지 못함을 적는다
문제
heartbeatEligible()이 false면 WebSocket 연결은 HEARTBEAT를 보내지
않는다. 그러면 HEARTBEAT_ACK가 없고, 이벤트도 없는 조용한 stream은
유효 신호가 없어 reconnect 예산이 초기화되지 않는다(0929 실험 E7).
훅에 주석이 없어 채택자가 이 결과를 코드 두 곳(heartbeat 송신,
isReconnectAttemptResetEligible)을 같이 읽어야 안다.

고른 방법
- 0929/04-04의 최소 방향대로 훅 옆에 주석을 달고 설계 5.3 예산 문단에
  같은 문장을 더한다. hidden 연결은 닫거나 visible 복귀 때 새 run을
  만들라고 적는다. 동작은 바꾸지 않는다.

위험·한계
- 동작 변경이 없다. 주석이 코드와 어긋나면 잡는 검사는 없다.

검증
- 바꾼 파일 eslint 통과. 주석만 바꿨다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 0929/04-04
2026-11-04 20:31:51 +09:00
DongHyeonka 37615072e9 fix(http): 백엔드가 정한 5xx 결과 불명 답을 분류기와 상관없이 고정한다
문제
Envelope 판정 표가 정하는 5xx는 503 IDEMPOTENCY_UNAVAILABLE 하나다. 짝
백엔드 http-contract.md가 직접 정한 다른 답 셋은 기능의 classifyProblem이
정한다.
- §2 500 IDEMPOTENCY_RECOVERY_REQUIRED: 이전 시도의 효과를 증명할 수 없다.
- §2 503 IDEMPOTENCY_COMPLETION_UNKNOWN(백엔드 bbe944bd): 작업은 돌았고
  결과 기록이 실패했다. 같은 키로 나중에, 새 키 금지.
- §4 503 REQUEST_TIMEOUT: 비동기 요청이 시간을 넘겼고 처리가 계속될 수 있다.
분류기가 5xx를 NOT_APPLIED로 보면 셋 다 SERVER_FAILURE/NOT_APPLIED가 되고,
retryBudget이 있으면 실행기가 다시 보낸다. 폼은 "다시 시도"를 새 키로
연다(리뷰 실험 X-F). 백엔드가 "새 키 금지"라고 한 요청이다.

고른 방법
backend-envelope.ts에 MAYBE_APPLIED_ANSWERS(code → status)를 두고 IU와
같은 줄에 셋을 더했다. status와 code가 함께 맞을 때만 MAYBE_APPLIED다.
MAYBE_APPLIED는 retryHint를 끄므로 자동 재전송이 없고, 코디네이터가 키를
붙들어 결과 불명 화면의 재전송이 같은 키로 나간다. 자동 같은 키 재전송은
지금처럼 KEYED의 503 IU뿐이다.

버린 대안
RECOVERY_REQUIRED에 "재전송 불가" 표시를 실어 화면 버튼을 숨기기(리뷰 최소
개선의 뒷부분): 완료 기준 밖이고 바인딩·코디네이터·화면을 함께 바꾼다.
같은 키 재전송은 백엔드가 다시 실행하지 않고 같은 500이나 재생으로 답한다.
남은 문제로 보고한다.

위험·한계
500 DB_COMPLETION_UNKNOWN(백엔드 error-codes.yaml, http-contract.md 밖)은
넣지 않았다. 계속 분류기가 정한다.

검증
- RED: backend-envelope 단위 3건, envelope 통합 4건(LENIENT 분류기 세 code의
  effect, retryBudget 2에서 fetch 1회·같은 키) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
  3,121건 통과. check:types:app·test, eslint, verify:documentation 통과.
- 매뉴얼 02 4절, 계약 문서 6.1절, descriptor 주석에 네 답을 적었다.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-04
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
2026-11-04 20:31:08 +09:00
DongHyeonka d13a393600 fix(storage): 계정 삭제 purge가 끝나지 않은 put을 보면 partition을 지운다
문제: 손상이 없는 LOGOUT·ACCOUNT_DELETION purge는 commit된 object 행과
참조 없는 chunk만 본다. 같은 partition의 끝나지 않은 journal 행
(PREPARING·FILES_READY)은 보지 않고, sweep은 staging receipt가 가리키는
chunk를 건너뛰면서도 COMPLETED를 돌려준다. 그래서
- 다른 탭이 put 중이면 purge가 "COMPLETED"를 보고한 뒤 그 객체가
  그대로 읽힌다(X1, 실제 Chromium·Firefox에서도 같음).
- commit 직전에 멈춘 put(FILES_READY)은 purge 뒤 다음 reconcile이
  commit해 계정 삭제한 사용자 파일이 객체로 다시 생긴다(X2).
- 업로드 중 멈춘 put(PREPARING)은 chunk가 grace 기간 동안 남고(X2b),
  그 행이 손상됐으면 partition 삭제도 일어나지 않아 영원히 남는다(X3).
손상이 있을 때만 partition 삭제가 진행 중 put까지 기다렸다 지웠다.

고른 방법(리뷰 5.1절 (c)): LOGOUT·ACCOUNT_DELETION이 객체를 다 돈 뒤
그 partition 키를 가진 journal 행 수를 센다. 하나라도 있으면(읽을 수
있든 없든) sweep 대신 이미 있는 partition 삭제로 넘긴다. partition
삭제는 exclusive partition lock으로 진행 중 put·delete가 돌아오기를
기다린 뒤 디렉터리와 그 partition의 행을 모두 지운다(e5b7b3e).
OpfsJournalPort에 countPartitionTransactions(scope)를 더했다.
removePartition이 지우는 같은 LOGICAL_KEY_INDEX 범위를 세므로, 센 행은
삭제가 지운다.
버린 대안: (a) 문서에 "reconcile 먼저" 안내 — X1·X3을 막지 못한다.
(b) report에 수만 추가 — 지울 방법이 없다(X3). (d) 항상 partition
삭제 — 더 단순하지만 끝나지 않은 행이 없을 때의 예산 단위 진행과
removedObjects·releasedBytes 보고를 잃는다.

위험·한계:
- 공개 포트에 필수 메서드가 하나 는다. OpfsJournalPort를 직접 구현한
  쪽은 추가해야 한다([계약]).
- 끝나지 않은 행이 하나라도 있으면 purge가 예산 없는 partition 삭제가
  되고, 다른 탭의 진행 중 put이 끝날 때까지 기다린다. 그 put의 결과도
  지운다(손상 경로와 같은 의미). purge가 행을 센 뒤 시작한 put은
  남는다(point-in-time).
- 기존 테스트 "never sweeps the chunk of a put that runs while the purge
  does"는 X1 동작을 기대값으로 고정하고 있었다. 새 의미로 바꿨다.
  0929/05-02 테스트는 덮어쓰기가 purge의 목록과 remove 사이에 끝나도록
  바꿔 CONFLICT 경로를 계속 본다.
- 소속을 알 수 없는(logicalKey가 깨진) 행은 여기서도 세지 못한다(05-03).
- WebKit은 기본 정책에서 OPFS 지원 판정을 통과하지 못해 browser spec이
  일찍 끝난다. offline-indexeddb 번들 37,423 → 37,521 / 38,500 gzip B.

검증:
- RED: opfs-worker-runtime.test.ts 새 4건(X1, FILES_READY, PREPARING,
  손상 행)이 partitionDeleted 없음으로 실패.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes +
  tests/contract 172건 통과. journal에 countPartitionTransactions 테스트
  1건(손상 행 포함, 다른 partition 제외, 삭제 뒤 0).
- browser: opfs-runtime.spec.ts에 X1 2탭 판을 더했다. heavy lock 안에서
  3엔진 9/9 통과(WebKit은 지원 판정에서 끝남).
- check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-01
2026-11-04 20:29:34 +09:00
DongHyeonka 613c1cfd0c fix(http): 필드 목록이 없는 422를 입력 오류로 읽지 않는다
문제
Envelope 실패 해석이 422를 모두 필드 검증으로 본다
(isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는
"같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가
VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다.
사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는
지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다.

고른 방법
422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만
필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다.
400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원
참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로
NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다.

버린 대안
IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록
없는 다른 422가 계속 입력 오류로 보인다.

위험·한계
422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드
오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다.

검증
- RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH·
  INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구
  없음) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
  3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다
  ("keeps the save off after a 422 the backend may have applied").
- check:types:app·test, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05
2026-11-04 20:27:53 +09:00
DongHyeonka a145f30b48 fix(web-push): dot segment가 든 registry path를 생성 때 거절한다
문제
registry path는 router base path를 뺀 앱 경로이고, 정상 클릭은
`${appBasePath}${path}`를 URL로 풀어 연다. registry 검사는 `/` 시작,
`//`·`\`·`#` 금지, 같은 origin만 본다. URL parser는 `..`와 `%2e%2e`를
dot segment로 풀기 때문에 scope `/app/`에서 `/../admin`과
`/%2e%2e/admin`이 모두 `https://app.example.test/admin`을 연다(리뷰
실험 ⑤). 검사를 통과한 경로가 앱 밖을 연다.

고른 방법
- safePath가 `new URL(path, base)`의 pathname + search가 입력과 같을 때만
  받는다. `..`·`.`·`%2e%2e`(대소문자 무관)는 parser가 바꾸므로 거절된다.
  query는 그대로 남는다.
- 버린 대안: 클릭 때 target.pathname이 앱 루트 아래인지 보기. 잘못된
  registry가 클릭할 때에야 드러난다. registry는 제품 코드라 생성 시점에
  throw하는 쪽이 이르고 작다(리뷰 5.3 (a)).

위험·한계
- 정규화되지 않은 경로(인코딩 안 된 비ASCII 문자, 빈 query `?`)도
  거절된다. registry를 쓰는 제품 코드는 아직 없다.
- registry가 서버가 내려주는 런타임 데이터가 되면 클릭 때 검사도 함께
  둬야 한다(리뷰 재검토 조건).

검증
- 새 테스트를 옛 코드에 돌림: 5건 실패(RED). 새 코드: web-push 단위
  6파일 76건 통과.
- 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-02
2026-11-04 20:24:14 +09:00
DongHyeonka d7c6cb4fd2 fix(auth): 세션 복구가 no-session이면 로그인 버튼을 보인다
문제: useSessionAction이 recover()의 결과를 버린다. owner가
"no-session"을 돌려주고 상태를 recovery-pending으로 두면 보호 라우트와
셸은 계속 "세션 복구" 버튼만 보이고, 로그인으로 갈 길이 없다. owner가
지켜야 할 상태 전이도 어디에도 적혀 있지 않아 owner 작성자가 화면
코드를 읽고 추론해야 했다.

고른 방법: 두 가지를 함께 한다.
- SessionState·SessionGateway.recover·ExternalSessionOwner에 전이
  계약을 적는다. restored면 authenticated, no-session이면
  unauthenticated(또는 integration-failed), reject면 상태 유지.
- SessionProvider가 recover()의 답을 쓴다. no-session을 받았는데
  owner가 아직 recovery-pending이면, owner가 다음에 알릴 때까지 화면에
  unauthenticated로 보인다. 그래서 라우트 문과 셸 모두 로그인 버튼을
  보인다.
버린 대안: 어댑터가 전이를 검사해 throw. 그러면 화면은 "작업 실패"만
보이고 여전히 로그인 버튼이 없다. 어댑터가 상태를 덮어쓰는 것은 구독
알림을 새로 만들어야 해서 scope fence와 얽힌다.

위험·한계: 계약을 어기는 owner의 상태를 화면에서만 바로잡는다.
application·scope fence는 owner의 상태를 그대로 본다.

검증: tests/component/session-recovery.test.tsx 4건(수정 전 2건 실패
확인), router·app-shell·route-status-surfaces·auth-session-adapter
테스트 통과, check:types, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-11
2026-11-04 20:23:22 +09:00
DongHyeonka af000673ef fix(realtime)!: 서버에 닿지 않은 SSE·poll 실패를 PROVIDER_UNAVAILABLE로 낸다
문제
브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이
transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은
execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로
낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고
예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE
행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로
화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인",
WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를
기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양).

고른 방법
- 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader
  거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로
  바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다.
- poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는
  execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다.
  executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다.
- 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다.
- 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만
  조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이
  없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3).

위험·한계
- 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo
  안 소비자는 테스트뿐이다.
- 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시
  불린다. 상한은 maxAttempts·maxElapsed 그대로다.
- 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로
  보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다
  (before/after 테스트 그대로 통과).

검증
- 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime
  단위 241건 통과.
- check:types 통과, 바꾼 파일 eslint 통과.

BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute
거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은
던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던
조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04
2026-11-04 20:23:21 +09:00
DongHyeonka c695898aee fix(browser-transfer): 상한보다 긴 Retry-After는 앱에도 retryable:false로 준다
문제: part 단계(BFF 발급, object store PUT)가 상한(maxRetryAfterMs, 기본
30초)보다 긴 Retry-After로 429·503을 받으면 runtime은 기다리지 않고
멈춘다. 그런데 앱에 주는 실패는 retryable:true다. 포트 표대로면 "자동
재시도해도 된다"는 뜻이라, 서버가 45초 기다리라고 한 요청을 앱이 바로
다시 보낸다. 같은 429에 control plane 전송은 retryable:false를 준다.
control plane도 전송 상한이 정책 상한보다 크면 retryable:true가 된다.

고친 방법: provider 실패를 앱 실패로 바꾸는 한 곳(stripProviderFailure)이
정책 상한을 받아, 지우는 retryAfterMs가 상한을 넘었으면 retryable을
false로 만든다. control plane 전송이 이미 쓰는 규칙이다. 한 곳에서 하므로
두 단계와 두 factory 상한 조합이 모두 같은 답을 낸다. 포트 주석과 설계
문서(presigned-transfer-and-image-cdn.md 7절)에 같은 규칙을 적었다.

버린 대안: 현상 유지 + 포트 주의 한 줄은 앱이 기다릴 값을 모르므로 지킬
수 없다. 앱 실패에 retryAfterMs를 싣는 안은 공유 타입 BrowserDataFailure를
바꿔 다른 포트까지 퍼진다. 상한 밖 값도 기다리는 안은 한 호출이 끝없이
늘어지지 않는다는 상한의 목적을 깬다(리뷰 5절 D2).

위험·한계: upload()·abort()의 실패 값이 바뀐다. 상한 밖 Retry-After는
RESUME에 retryable:false가 되어, 자동 재시도하던 다운스트림은 사람이
누르는 재시도로 넘어간다. 상한 안 대기, PUT 403 재발급, 발급 401/403
NONE은 바뀌지 않는다(기존 테스트 그대로 통과). 헤더 없는 part 단계 429가
backoff로 재시도하는 차이는 이 변경 범위 밖이다.

검증:
- 고치기 전: 새 단언 5건 실패(part 단계 4건, 전송 상한 60초 조합 1건)
- 고친 뒤: 영역 단위 테스트 15파일 274건 통과
- check:types, eslint(바꾼 파일) 통과

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-02
2026-11-04 20:21:39 +09:00
DongHyeonka a65df74046 fix(realtime)!: bounded poll을 V3 descriptor에 묶어 실행기 재시도를 막는다
문제
BoundedPollOperationContract는 지운 V2 행의 어휘(contractVersion: 2,
protocol, semantics, replayPolicy, retry, transportMaxAttempts,
authRecoveryCount, maxCumulativeSleepMs, serverStream)로 된 자기 선언이다.
assertBoundedPollOperation은 리터럴만 보고 실제로 실행할 descriptor와
대조하지 않는다. 조합 코드가 execute를 V3 실행기와 기본 GET
descriptor(retryBudget 2)로 만들면 503마다 실행기가 두 번 더 보낸다.
poll 3회가 요청 9회가 되고, poll 관측에는 1건씩만 보인다(리뷰 실험 P).

고른 방법
- coordinator의 operation을 V3 descriptor(InstalledHttpContract)로 바꾼다.
  실행기는 재시도 상한을 그 descriptor의 frontend.retryBudget에서 읽는다
  (http-execution-v3.ts retryCeiling). 그래서 생성 때
  retryBudget === 0을 요구하면 실행기 옵션 없이 poll 한 attempt가 요청
  한 번이 된다. 실행기(src/adapters/http)는 고치지 않았다.
- 검사: operationId 일치, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT,
  retryBudget 0, responseByteLimit 1..8 MiB. execute에 넘기는
  maxResponseBytes는 min(policy.maxResponseBytes, responseByteLimit)이다.
- V2 리터럴 필드는 모두 지운다. command descriptor·요청 본문은 조립
  (composeContractContributions)이 GET·HEAD에서 이미 거절한다.
- 버린 대안: (a) ApiOperationRow + HttpExecutionPolicy 두 인자. 행에는
  retryBudget이 없고, 실행기가 실제로 받는 것은 descriptor 하나라 같은
  객체를 넘기는 쪽이 어긋날 틈이 작다. (b) 실행기에 호출별 재시도 끄기
  옵션 추가. 다른 에이전트가 고치는 http 영역을 건드리고, descriptor가
  재시도를 허용한다는 사실은 그대로 남는다. (c) 문서에만 적기. 검출이
  없다.

위험·한계
- 공개 타입이 바뀐다. repo 안 소비자는 테스트뿐이다.
- 조합 코드가 coordinator에 넘긴 descriptor와 다른 객체를 실행기에
  넘기면 막지 못한다. 타입 주석과 설계 9.2에 "같은 객체를 넘긴다"고
  적었다. 조립된 행은 동결돼 있어 검사 뒤 값이 바뀌지 않는다.
- 기능의 기본 GET(retryBudget 2)은 poll에 쓸 수 없다. poll 전용
  operation을 따로 등록해야 한다.

검증
- 새 테스트를 옛 코드에 돌림: 21건 실패(RED). 새 코드: 32건 통과.
- 실험 P를 테스트로 옮김: 기본 descriptor는 생성 때 TypeError,
  retryBudget 0 descriptor + maxRetryAttempts 2 실행기 + 503 서버에서
  poll 3회 = 요청 3회.
- 변이 5건(retryBudget·method·retrySemantics·operationId·응답 상한 검사
  삭제) 모두 검출.
- check:types 통과, 바꾼 파일 eslint 통과.

BREAKING CHANGE: BoundedPollOperationContract를 지운다.
createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의
둘째 인자는 V3 descriptor(BoundedPollOperation = InstalledHttpContract)다.
조립된 행(composeContractContributions(...).httpByOperationId.get(id))을
넘기고, frontend.retryBudget을 0으로 둔 poll 전용 operation을 등록한다.
execute 안에서는 같은 descriptor를 실행기에 넘긴다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-01
2026-11-04 20:21:39 +09:00
DongHyeonka 60b721fd1c fix(browser-files): inspect 중에 놓은 ref에는 receipt를 발급하지 않는다
문제: vault inspect()는 이전 receipt를 무효화한 뒤 파일을 읽으며 두 번
await한다. 그 뒤 #disposed는 다시 보지만 ref가 아직 있는지는 보지 않고
receipt를 발급한다. 그 사이 release(ref)가 record와 receipt를 지우면,
inspect는 사라진 ref에 ok와 receipt를 돌려주고 receipt 기록이 놓은 File을
runtime dispose까지 붙잡는다(activeReferenceCount 0,
activeVerificationCount 1). 지금은 resolveVerifiedFile의 records.has 검사가
preview를 막지만, 그 검사를 지운 변이(L11)를 잡는 테스트가 없었다.

고른 방법: #disposed 재확인 바로 뒤에서 record가 없으면
NOT_FOUND/RESELECT로 끝낸다. resolveFile이 ref를 못 찾을 때와 같은
결과라 호출자가 이미 처리하는 분기다. 리뷰의 최소 개선 방향 그대로다.

위험·한계: 같은 ref에 inspect 두 개가 겹치면 receipt가 둘 생기는 것은
이 변경 범위 밖이다(두 receipt 모두 release·dispose가 지운다). 이 수정
뒤에는 놓은 ref에 receipt가 남는 경로가 없어서, L11 검사는 다시 두 번째
방어선이 된다. 새 테스트는 이 커밋의 검사를 지우면 실패한다.
file-transfer 번들 56,053 → 56,068 / 57,800 gzip B.

검증:
- RED: browser-file-content.test.ts 새 테스트가 inspect ok(기대
  NOT_FOUND)로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 85건 통과.
  check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-04
2026-11-04 20:17:50 +09:00