Commit Graph
18 Commits
Author SHA1 Message Date
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 6b7b53fe01 perf(image-cdn): 같은 이미지를 동시에 resolve하면 probe를 한 번만 돌린다 (01-04)
문제: resolve()는 통과한 probe 기록(passedProbes)을 slot을 기다리기
전에만 본다. 같은 asset·preset을 동시에 5번 resolve하면 probe가 5번
돈다. probe마다 preset의 encoded 예산까지 no-store로 내려받고
decode하며, 같은 이미지가 probe slot을 차지해 다른 이미지의 probe가
밀린다.

고른 방법: asset·preset별로 "진행 중인 probe 단계"(slot 대기, probe,
통과 기록)를 promise 하나로 둔다. 뒤에 온 호출은 그 단계가 끝나기를
자기 signal로 기다린 뒤 기록된 통과를 재사용한다. probe 자체를
공유하지 않으므로 호출마다 abort가 독립이다. 앞선 probe가 실패하면
기다린 호출이 직접 probe한다(실패는 재사용하지 않는다는 기존 규칙).
X5(동시 5회, maxConcurrentProbes 2)에서 probe가 1회다.

버린 대안:
- 리뷰가 제안한 slot 획득 뒤 재확인. 넣어 보니 X5에서 probe가 3회로
  완료 기준(2회 이하)을 못 맞춘다. slot은 원시 probe가 끝날 때
  넘겨지는데(TR-RR-07), 통과 기록은 그보다 몇 microtask 뒤에 남는다.
  다음 대기자가 기록 전에 깨어난다.
- 진행 중 probe의 결과를 공유(single-flight). 호출자마다 signal이
  달라 참조 수를 세야 한다.
- slot 해제를 통과 기록 뒤로 미룬다. 해제 지점이 원시 probe 정착과
  wrapper 종료 두 곳으로 갈라진다.

위험·한계:
- 대기 뒤 재사용할 때 만료를 따로 다시 보지 않는다. 통과를 기록한
  호출이 기록 직전에 만료를 봤고, 대기자는 같은 task 안에서 이어서
  실행된다. 시작할 때의 만료 검사(기존)는 그대로다.
- 앞선 probe가 실패하면 기다리던 호출들이 각자 probe한다(slot 수로
  묶임). 실패가 반복되는 이미지는 지금과 같은 수의 probe가 돈다.
- probe 블록을 try/finally로 감싸면서 들여쓰기가 바뀌었다. 로직
  변경은 `git show -w`로 보면 짧다.
- file-transfer 레시피 번들이 55,725 → 55,856 gzip bytes가 되어 예산
  55,800을 넘었다. 다음 백 단위로 올리는 기존 규칙대로 55,900으로
  올렸다.

검증:
- RED(수정 전 코드에 새 테스트): "probes once and lets the other calls
  reuse the pass"가 "expected vi.fn() to be called 1 times, but got 5
  times"로 실패. 재확인 안(버린 대안)에서는 2회 기대에 3회로 실패.
  나머지 새 테스트 2건(앞선 probe 실패 시 대기자가 직접 probe, 대기
  중 abort가 진행 중 probe를 끊지 않음)은 새 분기를 고정한다.
- GREEN: image-cdn 단위 3파일 37건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·json-schema
  단위 20파일 323건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint
  통과. check-optional-recipes(source) file-transfer 55856/55900.

Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
2026-11-01 23:14:47 +09:00
donghyeon-kaandClaude Opus 5.5 49413af045 fix(types): turn on noUnusedLocals and drop the unused declarations (12-12)
VD-01 decision 3 hands unused diagnostics to tsc and turns off ESLint's
no-unused-vars for TS files, but tsconfig.base.json never enabled the
tsc check (D-19). The flag found 46 unused imports, types and helpers
across 22 files; none of them were read, so removing them changes no
behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:32:33 +09:00
DongHyeonkaandClaude Opus 5.5 dde0d2b44e perf(browser-transfer): bound concurrent image probes and reuse a passed probe (01-11)
A PRIMARY_REQUIRED resolve() downloaded and decoded the primary candidate on
every call with no concurrency limit. Probes now wait for one of
maxConcurrentProbes slots (default 4) and a passed probe is reused for the
same asset and preset while the capability is valid.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:44:32 +09:00
DongHyeonkaandClaude Opus 5.5 b3981f9eb7 fix(browser-transfer): record one UPLOAD_PART per part with an attempt bucket (01-10)
The executor and the runtime both recorded UPLOAD_PART, so a part retried once
became one FAILED and two SUCCEEDED records, and no retry bucket existed. PUT
attempts are now PRESIGNED_TRANSFER; the runtime records the part once with
its attempt count as countBucket.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:40:12 +09:00
DongHyeonkaandClaude Opus 5.5 122a3a8b71 perf(browser-transfer): pass optional image-cdn operation inputs directly (R3-2)
The kernel already treats an undefined signal or timeoutMs as absent, so the
conditional spreads around them were dead weight.

file-transfer gzip: 54484 -> 54468

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 15:33:13 +09:00
DongHyeonkaandClaude Opus 5.5 874f4012ee perf(browser-transfer): run image-cdn abort wiring on the kernel operation (R3-2)
The capability-verification deadline, the probe wait and runtime close now
use createAbortableOperation/snapshotAbortTimers instead of three local
helpers and a default scheduler wrapper. Results, error codes and the
scheduler TypeError message are unchanged. Hand-rolled abort ratchet 17 -> 16.

file-transfer gzip: 54562 -> 54406

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 15:22:22 +09:00
DongHyeonkaandClaude Opus 5.5 e96f78b8e0 perf(file-transfer): fold duplicated local helpers into one per module (Q-B)
- browser-file-picker: the native and enhanced pickers carried two copies of
  the same selection observation (#finishObservation / #observe); one
  module-level observeSelection replaces both.
- indexeddb-checkpoint-store: read / compareAndSwap / remove /
  removeUnreadable each repeated acquire -> transaction -> get -> onerror;
  withCheckpointRow does that once and hands the row to the operation, still
  inside the same transaction. deleteCheckpointRow shares the delete tail.
- resumable-upload-runtime: the four checkpoint removals that remap to
  UPLOAD_RECONCILE go through removeCheckpoint.
- image-cdn-runtime: the verification deadline reuses
  combineImageRuntimeAbortSignals instead of a second listener loop; the
  verifier-coverage check throws its TypeError from one place; the registry
  id pattern is one constant instead of three inline literals.
- presigned executor / capability provider: reuse checkpoint-schema's
  SHA256_HEX and isSafeUploadReceiptToken instead of equal local patterns.

file-transfer reference runtime: 54754 -> 54562 gzip bytes (budget 54600).
Other reference runtimes unchanged.

Verified: check:architecture, check:types:app, check:types:test, lint,
test:unit, test:component, check:adapter-inventory, build,
check:optional-recipes (file-transfer 54562/54600, offline-indexeddb
35854/36000, realtime 39685/40000, service-worker-pwa 9500/10000),
test:recipes, check:types:recipes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 14:49:19 +09:00
DongHyeonkaandClaude Opus 5.5 834308c29b perf(browser-transfer): remove guards that earlier checks already make unreachable (Q-B)
- image-header-metadata: `=== undefined` / `?? 0` / `?? null` guards on bytes
  and boxes whose index was bounds-checked a few lines earlier (PNG IHDR,
  JPEG marker, WebP VP8X/VP8L, AVIF ftyp/meta/iprp/ipma, ascii,
  readUint24LittleEndian). A differential fuzz of the old and new parser over
  720k valid and mutated PNG/JPEG/WebP/AVIF inputs found no difference.
- incremental-sha256: `?? 0` on in-range Uint32Array reads and `>>> 0` on
  Uint32Array stores, which already reduce modulo 2^32. Checked against
  node:crypto for 0..1 MiB inputs, one-shot and streamed.
- p256 verifier: the alphabet index can't be negative after the base64url
  pattern check, and the decoded signature is already an owned, exactly sized
  buffer, so it is no longer copied again.
- browser-image-probe: once the bitmap matches the header dimensions, which
  are positive and inside the decode budget, the repeated positivity and
  budget checks on the bitmap cannot fail.

file-transfer reference runtime: 54894 -> 54754 gzip bytes. Other reference
runtimes unchanged.

Verified: check:architecture, check:types:app, check:types:test, lint,
test:unit, test:component, check:adapter-inventory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 14:49:19 +09:00
DongHyeonkaandClaude Opus 5.5 6c69df572b perf(file-transfer): use the abort kernel instead of local copies and wrappers (Q-B)
- cancelBody / cancelReader move from presigned/http-common.ts into
  platform/abortable-operation.ts next to compensateLateHandle; the probe's
  own cancelResponseBody/cancelReader copies are dropped and every caller
  imports the kernel pair.
- fetch-json-transport uses the kernel operation directly: the FetchAttempt
  projection only renamed terminal() (ABORT/TIMEOUT/CLOSED), and only the
  CALLER_ABORT case was ever read.
- browser-image-probe uses the kernel operation directly (awaitOwned /
  unanswered helpers replace the ProbeAbortScope object), and the body read
  goes through the same race instead of the hand-written readOrAbort.
- storage-manager-adapter's inspection wait is the kernel race: a caller
  abort ends the wait and a later settlement, including a rejection, is
  consumed, exactly as the hand-written listener did. The hand-rolled abort
  ratchet drops 19 -> 18 for this file.

file-transfer reference runtime: 55154 -> 54894 gzip bytes.
offline-indexeddb: 35951 -> 35854. service-worker-pwa: 9581 -> 9500.
realtime unchanged.

Verified: check:architecture, check:types:app, check:types:test, lint,
test:unit, test:component, check:adapter-inventory (hand-rolled abort
wiring 17/18).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 14:49:19 +09:00
DongHyeonkaandClaude Opus 5.5 09402478d6 perf(file-transfer): share byte-bucket, integer and control-character guards (Q-B)
Identical private copies lived in both file adapters and in five
browser-transfer modules. One copy each now lives next to isValidByteLength
in the browser-file-storage port (outside every reference-runtime source
root, so it adds no namespace export):
- byteBucket (browser-files/file-observer, presigned/http-common) ->
  browserDataByteBucket; both modules re-export it under the old name
- positiveSafeInteger / nonNegativeSafeInteger (checkpoint-schema,
  http-control-plane-adapter, runtime-policy, upload-byte-source,
  image-cdn-policy, browser-image-probe, file-policy's isPositiveSafeInteger)
  -> isPositiveSafeInteger / isNonNegativeSafeInteger
- hasControlCharacters (image-cdn-policy) and
  hasForbiddenHeaderValueCharacter (fetch-json-transport) -> hasControlCharacter

Same predicates, same results for every input.

file-transfer reference runtime: 55306 -> 55154 gzip bytes.
offline-indexeddb: 35957 -> 35951. realtime, service-worker-pwa unchanged.

Verified: check:architecture, check:types:app, check:types:test, lint,
test:unit, test:component, check:adapter-inventory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 14:49:19 +09:00
DongHyeonkaandClaude Opus 5.5 9e387b7ec3 fix(browser-transfer): decode probe images without applying orientation (Q-6.1-8)
The header parser reads pre-rotation dimensions, but the default
createImageBitmap call applied EXIF/irot orientation, so an orientation
5-8 JPEG or a rotated AVIF decoded with width and height swapped and was
rejected. The default bitmap factory now passes
{ imageOrientation: "none" }. An injected createBitmap is unchanged.

Verified: RED test "decodes with the default bitmap factory without
applying orientation" (options were missing) + all gates. Real-browser
decode of a rotated image is not exercised here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:32:37 +09:00
DongHyeonkaandClaude Opus 5.5 818cbd3839 fix(browser-transfer): allow a PRIMARY_REQUIRED probe only with an exact-size fit (Q-6.1-7)
The probe accepts a decode only when it matches the primary candidate's
pixel size exactly. fit inside/outside keep the source ratio, so for any
asset whose ratio differs the preset could only fail with
INTEGRITY_FAILED, and PRIVATE_SIGNED forces the probe. Per D-12 the
registry now rejects PRIMARY_REQUIRED unless fit is cover, contain or
fill; ratio-preserving fits stay allowed on presets without the probe.
README and the architecture doc state the rule.

Verified: RED test "allows a PRIMARY_REQUIRED probe only with an
exact-size fit" (inside/outside were accepted) + all gates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:32:37 +09:00
DongHyeonkaandClaude Opus 5 cc91fc6ae0 fix: settle a shared abort operation by observation, not by drain count
The primitive decided a raced outcome by draining a hard-coded four
microtasks and then asking whether the task had landed. That made the
answer depend on scheduling rather than on what was observed: a caller
abort could fix the terminal owner synchronously and a rejection later in
the same call stack still won the public result, so `race()` disagreed
with `terminal()` and the failure taxonomy a caller received depended on
microtask ordering.

Task settlement and the terminal event now share one settle-once state
machine. Whichever callback actually runs first owns the outcome; a value
that loses is compensated exactly once and a rejection that loses is
absorbed, so neither can surface late.

The three consumers that kept their own copies of these mechanics move
onto it. The Image probe and the Resumable fetch transport attached their
caller listener before installing the timer, so a scheduler that threw
rejected the public `probe()`/`execute()` promise natively and left the
listener on the caller's signal; both now close atomically inside their
own Result vocabulary and start no fetch. `snapshotAbortTimers` binds the
scheduler callables once at construction, so replacing a method after
composition can no longer change how work already in flight is bounded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 01:24:53 +09:00
DongHyeonkaandClaude Opus 5 5a76f95291 fix: bound resumable teardown, image concurrency and delivery leases
TR-RR-06. dispose() now bounds its drain with a cleanupDeadlineMs from policy
and returns the result, so a non-cooperative mutation lock or provider can no
longer make teardown unbounded and an unproved drain is reported as still
CLOSING instead of closed over. The checkpoint store stays open in that case,
because something can still write to it. An abort is admitted physical work
like an upload, so it joins the tracked set rather than being stepped over.

TR-RR-07. The verification slot belongs to the raw verifier, not the wrapper.
Releasing it when the caller's wait expired let an abandoned verification keep
running while a new one was admitted, so repeated aborts produced more
concurrent physical work than the configured cap allows. The slot is now
released only once the raw tasks settle.

TR-RR-04. A presigned byte source owns a fetch reader and a capability lease and
its port requires close(); the delivery consumer never called it. The closeable
subtype is lost in the FileByteSource projection, so a holder keeps it from the
moment the lease exists and the outermost finally closes it exactly once — on
success, validation failure, writer failure and abort alike.

check:adapter-inventory now also fails if the shared abortable-operation
primitive has no production importers. It was safe to add only once the
presigned subsystems actually migrated onto it; a gate that fails CI for a
documented, unfixed defect reports the wrong thing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 17:22:45 +09:00
DongHyeonkaandClaude Opus 5 fb5b449031 fix: apply the recorded private Cache-Control matrix to image probes
TR-RR-09. The documented BT-IMG-02 contract requires a private response to
carry no-store and fail closed when any directive that describes cacheability
accompanies it. The probe checked only that no-store was present and public was
absent, and the suite pinned the contradictory "private, no-store" as a success.
Both now follow the recorded contract: only no-store and syntactically valid
unknown extensions are admitted, and public, private, immutable, max-age,
s-maxage, no-cache, must-revalidate and proxy-revalidate each fail closed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 14:14:41 +09:00
DongHyeonkaandClaude Opus 5 cc4e875c2d fix: bound browser transfer leases and effect reporting
BT-X-01: add the shared abortable-operation utility with golden tests for first
terminal owner, idempotent close, listener and timer cleanup under a throwing
scheduler, observed late rejection and late-handle compensation. It carries no
subsystem result taxonomy.

BT-PRE-01: make the presigned download lease lazy and single-start. open() now
validates, claims and consumes the capability without any network I/O; the
fetch, the transfer deadline and the expiry recheck happen at first stream
consumption. The source gained close(), which discards an unused lease with no
I/O and otherwise cancels the body and releases the scope exactly once.

BT-UP-01: require removeEventListener in the AbortSignal structural guard and
isolate release cleanup so a hostile facade cannot replace a typed terminal
result with a rejection.

BT-UP-03: deleteDatabase cannot be cancelled after dispatch, so a blocked
deadline now returns PENDING with effect UNKNOWN instead of a failure that reads
as NOT_APPLIED. A realm-scoped (factory, databaseName) registry prevents
recreating the partition until the native request settles.

BT-UP-04: reject non-finite and negative upload clocks as a dependency failure
instead of letting them bypass every capability expiry comparison.

BT-IMG-02: replace the naive Cache-Control quote stripping with a quote- and
escape-aware tokenizer, so max-age="60 or 60" is no longer read as 60 and a
comma inside a quoted extension is not a directive boundary.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 00:13:54 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00