fix(adapters): 지난 리뷰에서 남은 adapter 결함과 시험 빈칸을 고친다

문제(2026-09-29·11-01·11-05 리뷰에서 남음·일부로 이월):
- 계속 읽히지 않는 release marker를 같은 manifest stage가 다시 쓰지 않아
  candidate와 rollback 대상이 다시 활성화되지 않는다(1105/02-02).
- 손상된 chunk 참조 행 하나가 orphan GC를 영구히 멈춘다(0929/05-01 ③).
- 롤백 중(옛 릴리스 탭) 승인된 계정 삭제가 새 릴리스가 올린 DB 앞에서
  실패한다(0929/05-05).
- lifecycle proof 정규식이 IndexedDB 16~128, OPFS 16~512로 갈렸다(05-06).
- canonical JSON 사본 셋과 sameScope 사본 둘(05-07).
- 한 origin의 앱 둘이 DB 이름으로 갈리는 근거가 문서에 없다(05-10).
- Web Storage의 TTL 모양·prototype 키·accessor 거절을 시험이 안 본다
  (1101/05-06).
- part buffer copy factor가 1까지 내려가 메모리 상한 식이 거짓이 된다
  (1101/01-03).
- 업링크 하한 64 KiB/s가 정책과 실행기에 따로 있다(0929/01-03).
- 닫힌 runtime의 abort()가 RESUME을 돌려주고 abort() 표가 없다(01-05).
- 로그인 뒤 돌아갈 주소가 router basename을 빼서 /app/ 배포가 앱 밖으로
  나간다(0929/08-08).

고른 방법:
- marker 읽기 실패(abort 말고)는 entry처럼 같은 stage가 덮어쓴다. 지우지
  않는다. 포트 주석의 "or lookup"을 고치고 운영 문서에 한 줄 적는다.
- 손상 참조 행은 참조로 보고 chunk를 남긴 뒤 수를 센다
  (corruptChunkReferences, DEGRADED 관측). 1101 결정 "손상 행은 건너뛰고
  센다"와 같다.
- 상태가 INCOMPATIBLE(새 schema)일 때 승인된 ACCOUNT_DELETION만 DB 전체를
  지운다. LOGOUT은 새 릴리스에 맡긴다.
- kernel에 canonical-json.ts·opaque-authority-proof.ts를 두고 사본이 그것을
  쓴다(실패 code는 호출자가 정한다). proof는 넓은 쪽(512)을 지킨다.
  sameOpfsScope는 OPFS 그룹 안 한 곳이다. INVENTORY 145.
- 05-10은 접두사 옵션 대신 registry가 주는 authorityToken을 앱 경계로
  정하고 문서와 시험으로 고정한다. 옵션은 지우기·유지보수 경로가 같은
  이름을 다시 계산해야 해서, 한 곳에서 빠지면 지웠다고 보고한 데이터가
  남는다.
- PART_BUFFER_COPIES(4) 하한, DEFAULT_MIN_TRANSFER_BYTES_PER_SECOND 한 값.
- 닫힌 runtime의 abort()는 NONE이고, 포트에 abort() recovery 표를 둔다.
- returnTo는 useHref로 만든 문서 경로이고 포트 주석에 기준을 적는다.
버린 대안: marker를 지우고 다시 받기 — 서빙 중인 release를 지운다
(STO-RR-04).

위험·한계: canonical JSON이 이제 cache·realtime에서도 NaN·Infinity를
거절한다(전에는 null로 썼다). Fileserver client(http 그룹)의 같은
64 KiB/s는 다른 그룹이라 이 상수를 import할 수 없고, 그 파일은 그룹 B
PR①이 고치는 파일이라 여기서 건드리지 않았다.

검증: desktop 결과는 PR 본문.

Refs: 1105/02-02, 0929/05-01, 0929/05-05, 0929/05-06, 0929/05-07, 0929/05-10, 1101/05-06, 1101/01-03, 0929/01-03, 0929/01-05, 0929/08-08
This commit is contained in:
DongHyeonka
2026-11-13 20:17:04 +09:00
parent ee95573f9b
commit 44538819eb
28 changed files with 640 additions and 197 deletions
@@ -204,6 +204,12 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
token이나 physical DB name에 넣지 않는다.
3. physical DB name이 세 opaque token에서만 파생됐는지, caller
`databaseNameAssertion`이 exact match인지 확인한다.
- 같은 origin에 앱 둘을 두면 앱마다 다른 `authorityToken`을 받는다. IndexedDB
dataset(`ca-idb-v1:<authority>.<namespace>.<partition>`)과 OPFS journal
(`ca-frontend-opfs-metadata-v1:<authority>`) 이름이 그 token에서 나오므로 앱끼리
DB가 갈린다. 이름 접두사를 바꾸는 조립 옵션은 두지 않는다(0929/05-10).
계정 삭제·유지보수 경로가 같은 이름을 다시 계산하므로, 옵션을 한 곳에서
빠뜨리면 지웠다고 보고한 데이터가 남는다.
4. governance store의 바꿀 수 없는(immutable) scope와 `BrowserStoragePolicy` 전체 binding을
versionchange, post-open, maintenance 모두에서 확인한다. raw token이나 binding
내용을 incident log에 복사하지 않는다.
@@ -22,6 +22,10 @@ session/account에 묶인 Query lifecycle, 엄격한 query 정책과 Web Storage
반환하지 않는다.
- 검증 중 abort나 읽기 불가(UNKNOWN)는 stage 성공이 아니며 active pointer를
건드리지 않는다. candidate를 임의로 삭제하지도 않는다.
- candidate의 marker 본문을 읽지 못하면(손상이 아닌 읽기 실패) 같은 manifest의
`stageRelease`가 entry와 marker를 network에서 다시 받아 덮어쓴다. 지우지 않는다.
그 뒤 `activateRelease`가 다시 된다(1105/02-02). abort는 덮어쓰지 않고 실패로
돌려준다.
- `activateRelease`와 `cleanupOwned`는 network I/O가 없다. fetcher 없이도
동작하므로 offline rollback과 quota recovery cleanup이 `UNSUPPORTED`로 막히지
않는다. 두 operation은 Cache Storage와 mutation lock만 요구하고 실패 시
+77 -75
View File
@@ -77,80 +77,82 @@
| 67 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/json-member-scanner.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/retry-after.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 100 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 104 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 107 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 126 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 127 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 128 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 129 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 130 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 134 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/http/fileserver-upload.ts` | [Network/state](./01-network-and-state.md) |
| 142 | `src/adapters/AGENTS.md` | 계층 규칙 문서(코드 아님, 리뷰 대상 아님) |
| 143 | `src/adapters/CLAUDE.md` | 위 문서를 가져오는 한 줄(`@AGENTS.md`) |
| 70 | `src/adapters/platform/canonical-json.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/json-member-scanner.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/opaque-authority-proof.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/platform/retry-after.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 84 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 85 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 100 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 101 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 104 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 107 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 108 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 128 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 129 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 130 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 131 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 134 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/http/fileserver-upload.ts` | [Network/state](./01-network-and-state.md) |
| 144 | `src/adapters/AGENTS.md` | 계층 규칙 문서(코드 아님, 리뷰 대상 아님) |
| 145 | `src/adapters/CLAUDE.md` | 위 문서를 가져오는 한 줄(`@AGENTS.md`) |
합계: **143/143**. 새 adapter 파일이 추가되면 이 ledger를 같은 변경에서 갱신한다. 연결된 상세 리뷰는 그 리뷰 때의 기록이라 고치지 않는다. 상세 리뷰에 없는 파일은 그 행의 상세 리뷰 칸에 가장 가까운 묶음을 적는다.
합계: **145/145**. 새 adapter 파일이 추가되면 이 ledger를 같은 변경에서 갱신한다. 연결된 상세 리뷰는 그 리뷰 때의 기록이라 고치지 않는다. 상세 리뷰에 없는 파일은 그 행의 상세 리뷰 칸에 가장 가까운 묶음을 적는다.
@@ -1,3 +1,4 @@
import { DEFAULT_MIN_TRANSFER_BYTES_PER_SECOND } from "../resumable-upload/runtime-policy.ts";
import type {
PresignedDownloadCapability,
PresignedDownloadByteSource,
@@ -73,7 +74,11 @@ export type PresignedTransferExecutorOptions = Readonly<{
* payload instead of stranding a slow connection.
*/
timeoutMs: number;
/** 01-03. Slowest supported throughput. Default 64 KiB/s (~0.5 Mbit/s). */
/**
* 01-03. Slowest supported throughput. Default
* `DEFAULT_MIN_TRANSFER_BYTES_PER_SECOND`; lower it together with the
* resumable runtime policy's value (0929/01-03).
*/
minTransferBytesPerSecond?: number;
/**
* 01-03. Longest wait for the next download chunk. A stream that stops making
@@ -139,7 +144,7 @@ export function createPresignedTransferExecutor(
);
const timeoutMs = positiveSafeInteger(options.timeoutMs);
const minTransferBytesPerSecond = positiveSafeInteger(
options.minTransferBytesPerSecond ?? 64 * 1024,
options.minTransferBytesPerSecond ?? DEFAULT_MIN_TRANSFER_BYTES_PER_SECOND,
);
const idleTimeoutMs = positiveSafeInteger(
options.idleTimeoutMs ?? timeoutMs,
@@ -239,8 +239,10 @@ export function createResumableUploadRuntime<Capability>(
input: Parameters<ResumableUploadPort["abort"]>[0],
): Promise<BrowserDataResult<UploadAbortOutcome>> {
if (closed) {
// 0929/01-05. A closed runtime takes no call again, so there is
// nothing to resume on it: as `upload()` on a closed runtime.
return browserDataFailure("UNAVAILABLE", "UPLOAD_ABORT", {
recovery: "RESUME",
recovery: "NONE",
});
}
if (
@@ -40,6 +40,26 @@ export type ResumableUploadRuntimePolicy = Readonly<{
const MIB = 1024 * 1024;
const GIB = 1024 * MIB;
/**
* 1101/01-03. How many part-sized buffers the FILE path holds while one part
* is being sent: the source iterator's buffer, the verified copy, the
* executor's snapshot, and the digest copy or the browser's fetch body. The
* memory bound `maxInFlightBytes >= partSizeBytes × maxConcurrency ×
* partBufferCopyFactor` holds only with a factor of at least this, so a
* smaller one is refused rather than taken as a promise the code cannot keep.
*/
export const PART_BUFFER_COPIES = 4;
/**
* 0929/01-03. The slowest uplink supported by default, 64 KiB/s (about
* 0.5 Mbit/s). The runtime's part deadline and the presigned executor's PUT
* deadline both start from it. A product that supports a slower uplink lowers
* `minTransferBytesPerSecond` in this policy and in the executor's options
* together: lowering only the policy leaves the executor ending the PUT at
* the old deadline.
*/
export const DEFAULT_MIN_TRANSFER_BYTES_PER_SECOND = 64 * 1024;
const ABSOLUTE_LIMITS = Object.freeze({
maxPartSizeBytes: 64 * MIB,
maxFileBytes: 100 * GIB,
@@ -75,8 +95,8 @@ const DEFAULT_POLICY: ResumableUploadRuntimePolicy = Object.freeze({
maxSessionLifetimeMs: 24 * 60 * 60_000,
maxClockSkewMs: 60_000,
providerAttemptTimeoutMs: 30_000,
// 64 KiB/s (about 0.5 Mbit/s): a 5 MiB part gets 30 s + 80 s.
minTransferBytesPerSecond: 64 * 1024,
// A 5 MiB part gets 30 s + 80 s.
minTransferBytesPerSecond: DEFAULT_MIN_TRANSFER_BYTES_PER_SECOND,
cleanupDeadlineMs: 10_000,
});
@@ -99,6 +119,7 @@ export function resolveResumableUploadRuntimePolicy(
!positiveSafeInteger(policy.maxInFlightBytes) ||
policy.maxInFlightBytes > ABSOLUTE_LIMITS.maxInFlightBytes ||
!positiveSafeInteger(policy.partBufferCopyFactor) ||
policy.partBufferCopyFactor < PART_BUFFER_COPIES ||
policy.partBufferCopyFactor >
ABSOLUTE_LIMITS.maxPartBufferCopyFactor ||
policy.maxInFlightBytes <
@@ -1,3 +1,4 @@
import { canonicalJson } from "../platform/canonical-json.ts";
import type {
PublicCacheAsset,
PublicCacheHeader,
@@ -635,25 +636,9 @@ export async function sha256Hex(
}
export function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new CacheValidationFailure("CORRUPT_DATA");
return canonicalJson(value, () => {
throw new CacheValidationFailure("CORRUPT_DATA");
});
}
export const SHA256_HEX = /^[a-f0-9]{64}$/u;
@@ -460,12 +460,17 @@ export function createPublicResponseCacheAdapter(
policy,
dependencies.crypto,
);
if (!marker.ok && marker.error.code !== "CORRUPT_DATA") {
// STO-RR-04. A marker that could not be read is unknown, not
// damaged. Treating a transient storage error as proof of
// corruption would delete a healthy active release.
if (!marker.ok && marker.error.code === "ABORTED") {
return rebaseFailure(marker.error, "CACHE_STAGE");
}
// STO-RR-04. A marker that could not be read is unknown, not
// damaged, so nothing is deleted for it. 1105/02-02: it is
// written again below with every entry, as an unreadable entry
// is. A marker that stayed unreadable used to stop this call
// before the write that was its only way back, so the candidate
// (and a rollback target cleanup keeps) never activated again.
// Writing verified bytes over it deletes nothing; a storage that
// is really down fails the writes the same way.
if (
marker.ok &&
marker.value &&
+31
View File
@@ -0,0 +1,31 @@
/**
* 0929/05-07. The canonical JSON text a digest or an identity is taken over:
* object keys sorted, no whitespace, JSON values only. Three adapter groups
* each held a copy (OPFS prepared objects, the public cache manifest, the
* realtime semantic identity), and a copy that changed alone would have
* given the same value two digests.
*
* Kernel code owns the mechanism only: the caller names its own failure
* (`invalid`), thrown for a value JSON cannot carry exactly (`undefined`, a
* function, a symbol, a bigint, or a number that is not finite, which
* `JSON.stringify` would write as `null`).
*/
export function canonicalJson(value: unknown, invalid: () => never): string {
if (value === null || typeof value === "string" || typeof value === "boolean") {
return JSON.stringify(value);
}
if (typeof value === "number") {
return Number.isFinite(value) ? JSON.stringify(value) : invalid();
}
if (Array.isArray(value)) {
return `[${value.map((item: unknown) => canonicalJson(item, invalid)).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Readonly<Record<string, unknown>>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key], invalid)}`)
.join(",")}}`;
}
return invalid();
}
@@ -0,0 +1,8 @@
/**
* 0929/05-06. The shape of the short-lived proof a lifecycle authority hands
* a browser storage runtime (IndexedDB and OPFS purges). The two runtimes
* checked it with their own patterns, 16–128 and 16–512 characters, so one
* proof could pass one runtime and fail the other. This is the one pattern;
* the wider bound is kept so no proof that passed before fails now.
*/
export const OPAQUE_AUTHORITY_PROOF = /^[A-Za-z0-9_-]{16,512}$/u;
+5 -24
View File
@@ -1,3 +1,4 @@
import { canonicalJson } from "../platform/canonical-json.ts";
import {
realtimeFailure,
realtimeSuccess,
@@ -213,7 +214,7 @@ function decodeUnsafe(
eventType,
payloadSnapshot,
);
const semanticFingerprint = hash64(canonicalJson(envelope));
const semanticFingerprint = hash64(canonicalSemanticJson(envelope));
const fingerprintBytes = semanticFingerprint.length;
const dto = Object.freeze({
@@ -411,28 +412,8 @@ function hash64(text: string): string {
);
}
function canonicalJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(canonicalJson).join(",")}]`;
}
if (!value || typeof value !== "object") {
function canonicalSemanticJson(value: unknown): string {
return canonicalJson(value, () => {
throw new TypeError("Realtime semantic identity is invalid.");
}
return `{${Object.keys(value)
.sort()
.map(
(key) =>
`${JSON.stringify(key)}:${canonicalJson(
(value as Readonly<Record<string, unknown>>)[key],
)}`,
)
.join(",")}}`;
});
}
@@ -1,3 +1,4 @@
import { OPAQUE_AUTHORITY_PROOF } from "../../platform/opaque-authority-proof.ts";
import type {
IndexedDbCompareAndSwapInput,
IndexedDbConnectionStatus,
@@ -94,7 +95,6 @@ const MAX_CURSOR_KEY_BYTES = 4_096;
const MAX_RECEIPT_RETENTION_MS = 31 * 24 * 60 * 60 * 1_000;
const MAX_LIFECYCLE_ROWS = 500;
const MAX_LIFECYCLE_DURATION_MS = 30_000;
const OPAQUE_AUTHORITY_PROOF = /^[A-Za-z0-9_-]{16,128}$/u;
const MAX_QUERY_SCANNED_ROWS = 5_000;
const MAX_IDEMPOTENCY_RECEIPTS = 1_000_000;
@@ -2553,7 +2553,7 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
);
} else {
result =
(await deleteUnadmittedDataset(input.signal)) ??
(await deleteUnadmittedDataset(input.signal, input.action)) ??
(await purgePartitionRecords(input, deadline));
}
return observeResult(
@@ -2570,16 +2570,27 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
* purge, and the database name comes from this partition's own tokens, so
* deleting the whole database touches no other partition. Returns `null`
* when a connection is ready for the row-by-row purge.
*
* 0929/05-05. An approved ACCOUNT_DELETION also deletes a database a newer
* release already upgraded (this tab is the older one during a rollback):
* this bundle cannot open it to purge row by row, and the account's data
* must not wait for a reload.
*/
async function deleteUnadmittedDataset(
signal: AbortSignal | undefined,
action: string,
): Promise<BrowserDataResult<IndexedDbLifecycleBatchReceipt> | null> {
if (connection.current()) return null;
const opened = await open(signal);
if (opened.ok) return null;
const newerSchema =
status.kind === "INCOMPATIBLE" &&
action === "ACCOUNT_DELETION" &&
opened.error.code === "UNSUPPORTED";
if (
(opened.error.code !== "POLICY_REJECTED" &&
opened.error.code !== "CORRUPT_DATA") ||
opened.error.code !== "CORRUPT_DATA" &&
!newerSchema) ||
disposed ||
typeof factory?.deleteDatabase !== "function"
) {
@@ -30,7 +30,7 @@ import {
type IndexedDbTransactionContext,
} from "../../platform/indexeddb-transaction.ts";
import { isValidOpfsStorageScope } from "./opfs-policy.ts";
import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts";
import { isPreparedObject, sameOpfsScope, stableJson } from "./opfs-prepared-object.ts";
export type IndexedDbOpfsJournalDependencies = Readonly<{
authorityToken: string;
@@ -272,7 +272,7 @@ export function createIndexedDbOpfsJournal(
}
if (
!isStoredObjectRow(stored) ||
!sameScope(stored.preparedObject.descriptor.scope, scope)
!sameOpfsScope(stored.preparedObject.descriptor.scope, scope)
) {
context.fail(corrupt("INDEXEDDB_READ"));
return;
@@ -522,7 +522,7 @@ export function createIndexedDbOpfsJournal(
if (
row.mutation !== "PUT" ||
row.objectId !== preparedObject.descriptor.objectId ||
!sameScope(row.scope, preparedObject.descriptor.scope) ||
!sameOpfsScope(row.scope, preparedObject.descriptor.scope) ||
row.targetGeneration !==
preparedObject.descriptor.generation ||
row.targetByteLength !==
@@ -792,7 +792,7 @@ export function createIndexedDbOpfsJournal(
// [0929] 05-01. Skipped and counted, as in `listIncomplete`.
if (
isStoredObjectRow(cursor.value) &&
sameScope(
sameOpfsScope(
cursor.value.preparedObject.descriptor.scope,
request.scope,
)
@@ -1425,18 +1425,6 @@ function chunkReferenceKey(
return `${storageScopeKey(scope)}|${digestHex}`;
}
function sameScope(
left: OpfsStorageScope,
right: OpfsStorageScope,
): boolean {
return (
left.namespace === right.namespace &&
left.authorityToken === right.authorityToken &&
left.namespaceToken === right.namespaceToken &&
left.partitionToken === right.partitionToken
);
}
function validScopedObject(
scope: OpfsStorageScope,
objectId: string,
@@ -1563,7 +1551,7 @@ function isStoredJournalRow(
value.phase !== "PREPARING" &&
isPreparedObject(value.preparedObject) &&
value.preparedObject.descriptor.objectId === value.objectId &&
sameScope(
sameOpfsScope(
value.preparedObject.descriptor.scope,
value.scope as OpfsStorageScope,
)
@@ -1,3 +1,4 @@
import { OPAQUE_AUTHORITY_PROOF } from "../../platform/opaque-authority-proof.ts";
import type {
DurableObjectDescriptor,
DurableObjectMaintenancePort,
@@ -604,6 +605,7 @@ export function createOpfsByteStoreAdapter(
transactionBucket: transactionBucket(listed.value.transactions.length),
});
let corruptChunkReferences = 0;
const report: {
inspectedTransactions: number;
committedTransactions: number;
@@ -703,6 +705,7 @@ export function createOpfsByteStoreAdapter(
report.inspectedOrphanChunks = gc.value.inspected;
report.deletedOrphanChunks = gc.value.deleted;
report.orphanGcStatus = gc.value.status;
corruptChunkReferences = gc.value.corruptReferences;
if (gc.value.status === "DEADLINE_REACHED") {
report.deadlineReached = true;
}
@@ -713,7 +716,7 @@ export function createOpfsByteStoreAdapter(
// A skipped corrupt row is observed, not hidden behind a success.
// 2026-11-03 05-03. One no partition owns is reported, not observed:
// nothing clears it, so it would keep the signal on for good.
...(report.corruptTransactions > unattributed
...(report.corruptTransactions > unattributed || corruptChunkReferences > 0
? { outcome: "DEGRADED", failureCode: "CORRUPT_DATA" }
: { outcome: "SUCCEEDED" }),
});
@@ -723,6 +726,7 @@ export function createOpfsByteStoreAdapter(
...(unattributed
? { unattributedCorruptTransactions: unattributed }
: {}),
...(corruptChunkReferences > 0 ? { corruptChunkReferences } : {}),
}),
);
},
@@ -1349,6 +1353,7 @@ export function createOpfsByteStoreAdapter(
Readonly<{
inspected: number;
deleted: number;
corruptReferences: number;
status:
| "COMPLETED"
| "DEADLINE_REACHED"
@@ -1359,6 +1364,7 @@ export function createOpfsByteStoreAdapter(
const olderThanEpochMs = Math.max(0, now() - policy.orphanGracePeriodMs);
let inspected = 0;
let deleted = 0;
let corruptReferences = 0;
// R-5.1. Candidates include committed chunks, so a page can be all
// referenced. The scan pages on by digest cursor until it runs out or the
// deadline stops it.
@@ -1378,6 +1384,7 @@ export function createOpfsByteStoreAdapter(
return browserDataSuccess({
inspected,
deleted,
corruptReferences,
status: "STAGING_STATE_UNREADABLE",
});
}
@@ -1389,6 +1396,7 @@ export function createOpfsByteStoreAdapter(
return browserDataSuccess({
inspected,
deleted,
corruptReferences,
status: "DEADLINE_REACHED",
});
}
@@ -1398,7 +1406,15 @@ export function createOpfsByteStoreAdapter(
digestHex,
);
if (!referenced.ok) {
return rebaseFailure(referenced.error, "OBJECT_RECONCILE");
if (referenced.error.code !== "CORRUPT_DATA") {
return rebaseFailure(referenced.error, "OBJECT_RECONCILE");
}
// 0929/05-01 ③. A reference row that cannot be read is kept as a
// reference: its chunk stays and the rest of the scan goes on. One
// damaged row used to stop every later reconcile and GC for good
// (decision 2026-11-01: damaged rows are skipped and counted).
corruptReferences += 1;
continue;
}
if (referenced.value) continue;
const removal = await dependencies.worker.deleteOrphanChunk(
@@ -1412,6 +1428,7 @@ export function createOpfsByteStoreAdapter(
return browserDataSuccess({
inspected,
deleted,
corruptReferences,
status: "STAGING_STATE_UNREADABLE",
});
}
@@ -1419,12 +1436,18 @@ export function createOpfsByteStoreAdapter(
}
afterDigest = candidates.value.digests.at(-1);
if (!candidates.value.moreAvailable || afterDigest === undefined) {
return browserDataSuccess({ inspected, deleted, status: "COMPLETED" });
return browserDataSuccess({
inspected,
deleted,
corruptReferences,
status: "COMPLETED",
});
}
if (now() >= deadline) {
return browserDataSuccess({
inspected,
deleted,
corruptReferences,
status: "DEADLINE_REACHED",
});
}
@@ -1927,5 +1950,4 @@ function requiresMaintenanceAuthority(
);
}
const OPAQUE_AUTHORITY_PROOF = /^[A-Za-z0-9_-]{16,512}$/u;
const MAX_AUTHORITY_PROOF_LIFETIME_MS = 5 * 60 * 1_000;
@@ -1,3 +1,4 @@
import { canonicalJson } from "../../platform/canonical-json.ts";
import type {
OpfsPreparedObject,
OpfsStorageScope,
@@ -136,28 +137,17 @@ export function isPreparedObject(
* written as something else, so two different values never compare equal.
*/
export function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean"
) {
return JSON.stringify(value);
}
if (typeof value === "number") {
if (!Number.isFinite(value)) {
throw new TypeError("OPFS value is not JSON-safe.");
}
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new TypeError("OPFS value is not JSON-safe.");
return canonicalJson(value, () => {
throw new TypeError("OPFS value is not JSON-safe.");
});
}
/** 0929/05-07. One scope comparison for the journal and the worker runtime. */
export function sameOpfsScope(left: OpfsStorageScope, right: OpfsStorageScope): boolean {
return (
left.namespace === right.namespace &&
left.authorityToken === right.authorityToken &&
left.namespaceToken === right.namespaceToken &&
left.partitionToken === right.partitionToken
);
}
@@ -17,7 +17,7 @@ import {
isWritableObjectId,
type OpfsRuntimePolicy,
} from "./opfs-policy.ts";
import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts";
import { isPreparedObject, sameOpfsScope, stableJson } from "./opfs-prepared-object.ts";
import {
OPFS_WORKER_PROTOCOL_VERSION,
} from "./opfs-worker-protocol.ts";
@@ -1209,7 +1209,7 @@ export function createOpfsWorkerRuntime(
if (
record.phase === "FILES_READY" &&
isPreparedObject(record.preparedObject) &&
sameScope(record.preparedObject.descriptor.scope, scope)
sameOpfsScope(record.preparedObject.descriptor.scope, scope)
) {
const prepared = record.preparedObject;
return {
@@ -1687,18 +1687,6 @@ function scopedTransactionKey(
].join("|");
}
function sameScope(
left: OpfsStorageScope,
right: OpfsStorageScope,
): boolean {
return (
left.namespace === right.namespace &&
left.authorityToken === right.authorityToken &&
left.namespaceToken === right.namespaceToken &&
left.partitionToken === right.partitionToken
);
}
function receiptBelongsToScope(
receipt: unknown,
scope: OpfsStorageScope,
@@ -1717,7 +1705,7 @@ function receiptBelongsToScope(
record.scope &&
typeof record.scope === "object" &&
isValidOpfsStorageScope(record.scope as OpfsStorageScope) &&
sameScope(record.scope as OpfsStorageScope, scope),
sameOpfsScope(record.scope as OpfsStorageScope, scope),
);
}
if (
@@ -1735,7 +1723,7 @@ function receiptBelongsToScope(
preparedScope &&
typeof preparedScope === "object" &&
isValidOpfsStorageScope(preparedScope as OpfsStorageScope) &&
sameScope(preparedScope as OpfsStorageScope, scope),
sameOpfsScope(preparedScope as OpfsStorageScope, scope),
);
}
@@ -35,6 +35,12 @@ export type SessionGateway = Readonly<{
*/
getSubject(): string | null;
subscribe(listener: () => void): () => void;
/**
* 0929/08-08. `returnTo` is where the page asks to come back to after the
* sign-in: a same-origin document path with the router's basename, query
* and hash (`/app/items?x=1#results`), never an absolute URL. An owner that
* accepts it checks it is that before redirecting.
*/
beginSignIn(returnTo?: string): Promise<void>;
signOut(): Promise<void>;
/**
@@ -66,9 +66,10 @@ export type PublicCacheInspection = Readonly<{
/**
* `true` only when every entry was read back and matched the manifest.
* `false` when an entry is missing or no longer matches, and also when it
* could not be read at all (a failed body read or lookup): inspect does
* not tell those apart. Activating the candidate does, and staging the
* same manifest again rewrites either (1105/02-02).
* could not be read at all (a failed body read): inspect does not tell
* those apart. Activating the candidate does, and staging the same
* manifest again rewrites the entries and the marker (1105/02-02). A
* Cache Storage that cannot be asked at all fails that stage too.
*/
verified: boolean;
entryCount: number | null;
@@ -138,6 +138,13 @@ export type OpfsReconciliationReport = Readonly<{
* purge can clear. Present only when there were some.
*/
unattributedCorruptTransactions?: number;
/**
* 0929/05-01 ③. Chunk reference rows orphan GC could not read. Their chunks
* are kept as referenced and the scan goes on, so the bytes stay until an
* operator looks; the run is observed as `DEGRADED`. Present only when
* there were some.
*/
corruptChunkReferences?: number;
}>;
export type OpfsPolicyMaintenanceReport = Readonly<{
@@ -128,6 +128,22 @@ export interface ResumableUploadPort {
upload(
request: ResumableUploadRequest,
): Promise<BrowserDataResult<QuarantinedUpload>>;
/**
* 0929/01-05. A failure's `recovery` names one caller action here too:
*
* | recovery | caller action |
* | ----------- | ---------------------------------------------------------- |
* | `RESUME` | Call `abort()` again later with the same key: the abort did|
* | | not finish (the store, the server or the lock was not |
* | | available). |
* | `RECONCILE` | Call `abort()` again: the server answered a state this |
* | | build does not read, and the next call asks it again. |
* | `NONE` | No action: invalid input, the caller's own abort, or a |
* | | closed runtime. |
*
* A failure passed on from the checkpoint store or the control plane keeps
* that layer's `recovery`, read with the same table.
*/
abort(request: Readonly<{
uploadKey: string;
signal: AbortSignal;
@@ -7,7 +7,7 @@ import {
useSyncExternalStore,
type ReactNode,
} from "react";
import { useLocation } from "react-router-dom";
import { useHref, useLocation } from "react-router-dom";
import type {
ApplicationApi,
@@ -79,6 +79,10 @@ export type SessionAction = "sign-in" | "sign-out" | "recover";
/**
* One session action at a time, with the pending and failed state every
* session button shows. Sign-in returns to the current URL, hash included.
*
* 0929/08-08. `returnTo` is the document path (`useHref`): the router's
* basename is part of it. The router location alone left it out, so an app
* deployed under `/app/` returned to the origin's root after sign-in.
*/
export function useSessionAction(): Readonly<{
pending: boolean;
@@ -86,6 +90,7 @@ export function useSessionAction(): Readonly<{
run(action: SessionAction): void;
}> {
const { pathname, search, hash } = useLocation();
const returnTo = useHref({ pathname, search, hash });
const { beginSignIn, signOut, recover } = useSession();
const [pending, setPending] = useState(false);
const [failed, setFailed] = useState(false);
@@ -96,7 +101,7 @@ export function useSessionAction(): Readonly<{
try {
if (action === "sign-out") await signOut();
else if (action === "recover") await recover();
else await beginSignIn(`${pathname}${search}${hash}`);
else await beginSignIn(returnTo);
} catch {
setFailed(true);
} finally {
@@ -0,0 +1,57 @@
// @vitest-environment jsdom
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { MemoryRouter } from "react-router-dom";
import { describe, expect, it, vi } from "vitest";
import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.ts";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import {
SessionProvider,
useSessionAction,
} from "../../src/presentation/providers/session-provider.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
/**
* 0929/08-08. Sign-in returned to the router location, which leaves out the
* basename: an app served under `/app/` came back to `/fixture/items`, a
* page outside it.
*/
function SignIn() {
const action = useSessionAction();
return (
<button type="button" onClick={() => action.run("sign-in")}>
sign in
</button>
);
}
describe("0929/08-08 sign-in returns to the document path", () => {
it.each([
["/app", "/app/fixture/items?x=1#results"],
[undefined, "/fixture/items?x=1#results"],
] as const)("under basename %s", async (basename, expected) => {
const beginSignIn = vi.fn(async (_returnTo?: string) => {});
render(
<ApplicationProvider
application={createTestApplication({
session: { ...createAnonymousSessionAdapter(), beginSignIn },
})}
>
<MemoryRouter
{...(basename ? { basename } : {})}
initialEntries={[expected]}
>
<SessionProvider>
<SignIn />
</SessionProvider>
</MemoryRouter>
</ApplicationProvider>,
);
await userEvent.setup().click(screen.getByRole("button", { name: "sign in" }));
expect(beginSignIn).toHaveBeenCalledWith(expected);
});
});
+32
View File
@@ -0,0 +1,32 @@
import { describe, expect, it } from "vitest";
import { canonicalJson } from "../../src/adapters/platform/canonical-json.ts";
/**
* 0929/05-07. The one canonical JSON the OPFS objects, the public cache
* manifest and the realtime identity are hashed over. The cache and realtime
* copies wrote a non-finite number as `null`, so two different values had one
* digest; every caller now fails with its own error instead.
*/
const invalid = (): never => {
throw new TypeError("not canonical");
};
describe("0929/05-07 canonical JSON", () => {
it("sorts object keys at every depth and writes no whitespace", () => {
expect(canonicalJson({ b: [2, { d: 1, c: null }], a: "x", e: true }, invalid)).toBe(
'{"a":"x","b":[2,{"c":null,"d":1}],"e":true}',
);
});
it.each([
["NaN", Number.NaN],
["Infinity", Number.POSITIVE_INFINITY],
["undefined", undefined],
["a bigint", 1n],
["a function", () => 1],
["a nested non-finite number", { a: [1, Number.NEGATIVE_INFINITY] }],
])("refuses %s with the caller's own failure", (_label, value) => {
expect(() => canonicalJson(value, invalid)).toThrow("not canonical");
});
});
+89
View File
@@ -1716,3 +1716,92 @@ describe("05-06 an older tab that meets a newer schema", () => {
});
});
});
/**
* 0929/05-05. During a rollback the older release's tab cannot open a
* database a newer release already upgraded (VersionError, `INCOMPATIBLE`).
* An approved account deletion then failed with nothing deleted, and the
* account's data waited for a reload into the newer release.
*/
describe("0929/05-05 an account deletion during a rollback deletes the newer database", () => {
const partitionScope = { ...TEST_SCOPE, accountScope: "OPAQUE_PARTITION" as const };
const partitionPolicy = {
...TEST_STORAGE_POLICY,
accountScope: "OPAQUE_PARTITION" as const,
logoutAction: "PURGE_PARTITION" as const,
accountDeletionAction: "PURGE_PARTITION" as const,
};
const authorizeLifecycle = () => ({ authorized: true as const, proofToken: "authorityproof_001" });
async function upgradedByNewerRelease() {
const memory = new MemoryIndexedDbFactory();
const older = dependencies(memory, {
scope: partitionScope,
storagePolicy: partitionPolicy,
authorizeLifecycle,
});
const newer = createIndexedDbRuntime({
...older,
schemaVersion: 2,
migrations: [
...older.migrations,
{
id: "schema-v2",
fromVersion: 1,
toVersion: 2,
operations: [{ kind: "CREATE_STORE", name: "drafts", keyPath: "key" }],
},
],
});
expect(await newer.open()).toMatchObject({ ok: true });
newer.close();
const rolledBack = createIndexedDbRuntime(older);
expect(await rolledBack.open()).toMatchObject({ ok: false });
expect(rolledBack.getStatus()).toMatchObject({ kind: "INCOMPATIBLE" });
return { memory, rolledBack, deleteDatabase: vi.spyOn(memory.factory, "deleteDatabase") };
}
it("deletes the whole database for an approved ACCOUNT_DELETION", async () => {
const { rolledBack, deleteDatabase } = await upgradedByNewerRelease();
expect(
await rolledBack.enforceLifecycleBatch({
action: "ACCOUNT_DELETION",
maxRows: 100,
maxDurationMs: 1_000,
}),
).toMatchObject({ ok: true, value: { state: "COMPLETE", datasetDeleted: true } });
expect(deleteDatabase).toHaveBeenCalledWith(indexedDbPhysicalDatabaseName(partitionScope));
});
it("leaves a LOGOUT to the newer release", async () => {
const { rolledBack, deleteDatabase } = await upgradedByNewerRelease();
expect(
await rolledBack.enforceLifecycleBatch({ action: "LOGOUT", maxRows: 100, maxDurationMs: 1_000 }),
).toMatchObject({ ok: false });
expect(deleteDatabase).not.toHaveBeenCalled();
});
});
/**
* 0929/05-10. Two apps on one origin are kept apart by their registry-issued
* authority tokens: every physical database name is derived from that token,
* so different tokens can never share a database.
*/
describe("0929/05-10 the authority token is the app's database boundary", () => {
it("gives two apps' authority tokens distinct IndexedDB and OPFS journal names", async () => {
const { opfsJournalDatabaseName } = await import(
"../../src/adapters/storage/opfs/indexeddb-opfs-journal.ts"
);
const otherApp = { ...TEST_SCOPE, authorityToken: `${TEST_SCOPE.authorityToken}x` };
expect(indexedDbPhysicalDatabaseName(otherApp)).not.toBe(
indexedDbPhysicalDatabaseName(TEST_SCOPE),
);
expect(indexedDbPhysicalDatabaseName(TEST_SCOPE)).toContain(TEST_SCOPE.authorityToken);
expect(opfsJournalDatabaseName(otherApp.authorityToken)).not.toBe(
opfsJournalDatabaseName(TEST_SCOPE.authorityToken),
);
});
});
+50
View File
@@ -1317,6 +1317,56 @@ describe("OPFS byte-store coordinator", () => {
});
});
// 0929/05-01 ③. One chunk reference row that cannot be read stopped every
// reconcile at that digest, so orphan GC never reached the chunks after it.
it("keeps a chunk whose reference row is damaged, counts it and sweeps the rest", async () => {
const damaged = "d".repeat(64);
const orphan = "e".repeat(64);
const journal: OpfsJournalPort = {
...createJournal(),
isChunkReferenced: async (_scope, digestHex) =>
digestHex === damaged
? browserDataFailure("CORRUPT_DATA", "INDEXEDDB_READ")
: browserDataSuccess(false),
};
const deleteOrphan = vi.fn(async (_scope: unknown, _digestHex: string) =>
browserDataSuccess({ deleted: true, skippedUnsafe: false }),
);
const observations: unknown[] = [];
const adapter = createOpfsByteStoreAdapter({
journal,
worker: createWorker({
listOrphanCandidates: vi.fn(async () =>
browserDataSuccess({
safeToSweep: true,
digests: [damaged, orphan],
moreAvailable: false,
}),
),
deleteOrphanChunk: deleteOrphan,
}),
scope,
storagePolicy,
now: () => 100_000,
observer: (event) => observations.push(event),
});
expect(await adapter.maintenance.reconcile()).toMatchObject({
ok: true,
value: {
inspectedOrphanChunks: 2,
deletedOrphanChunks: 1,
corruptChunkReferences: 1,
orphanGcStatus: "COMPLETED",
},
});
expect(deleteOrphan).toHaveBeenCalledOnce();
expect(deleteOrphan.mock.calls[0]?.[1]).toBe(orphan);
expect(observations).toContainEqual(
expect.objectContaining({ operation: "OBJECT_RECONCILE", outcome: "DEGRADED" }),
);
});
it("runs bounded orphan GC and fails closed when staging is unreadable", async () => {
const digestHex = "c".repeat(64);
const listOrphans = vi.fn(async () =>
@@ -133,7 +133,9 @@ describe("public response cache repair is failure-atomic", () => {
const restaged = await release.adapter.admin.stageRelease(release.manifest);
expect(markerReads).toBeGreaterThan(0);
expect(restaged.ok).toBe(false);
// 1105/02-02. An unreadable marker is rewritten with the entries, over the
// serving candidate, never by deleting it first.
expect(restaged.ok).toBe(true);
expect(release.cacheStorage.caches.has(release.cacheName)).toBe(true);
cache.match = realMatch;
expect(
@@ -509,6 +511,35 @@ describe("a cached body that stays unreadable until it is written again (1105/02
},
);
// 1105/02-02. The release marker too: a candidate whose marker body stays
// unreadable could neither be activated nor staged again, because the
// stage stopped at the unreadable marker before the write that would
// replace it.
it.each([
["a TypeError", () => new TypeError("blob missing")],
["a NotReadableError", () => new DOMException("unreadable", "NotReadableError")],
] as const)(
"repairs a staged candidate whose marker fails with %s by staging it again",
async (_label, error) => {
const world = await deployments();
expect(await world.stage("r1")).toEqual({ ok: true, fetched: 2 });
expect(await world.activate("r1")).toMatchObject({ ok: true });
expect(await world.stage("r2")).toEqual({ ok: true, fetched: 2 });
const marker = world.unreadableUntilRewritten(
"r2",
"https://assets.example.test/.well-known/ca-public-cache-v1/candidate",
error,
);
expect(await world.activate("r2")).toMatchObject({ ok: false });
expect(await world.stage("r2")).toEqual({ ok: true, fetched: 2 });
expect(marker.unreadable).toBe(false);
expect(await world.activate("r2")).toMatchObject({ ok: true });
// The release that served before the repair still did.
expect(await world.lookup(world.assets[0]!.absoluteUrl)).toMatchObject({ ok: true });
},
);
// 1105/02-04. Which stored-entry failures count as damage decides what an
// activation reports; the stage fast path writes every one of them again.
// Each row is one code of the damage list or one body read failure outside
@@ -113,6 +113,15 @@ describe("production resumable upload runtime", () => {
).toThrow(TypeError);
});
// 1101/01-03. The factor is the number of part buffers the code holds, not
// a setting: a factor of 1 let the bound admit four times the concurrency
// the memory budget can carry.
it.each([1, 3])("refuses a part buffer copy factor of %i", (partBufferCopyFactor) => {
expect(() =>
resolveResumableUploadRuntimePolicy({ partBufferCopyFactor }),
).toThrow(TypeError);
});
// R-1.3. The default memory budget (20 MiB / (5 MiB × 4)) runs one worker,
// but createSession asked the server for 3.
it("requests the concurrency the default policy can actually run", async () => {
@@ -1150,3 +1159,25 @@ describe("production resumable upload runtime", () => {
}
});
});
describe("0929/01-05 abort() on a closed runtime", () => {
it("names no caller action, as upload() on a closed runtime", async () => {
const harness = createControlHarness();
const runtime = createResumableUploadRuntime({
controlPlane: harness.control,
partExecutor: executorFor(harness),
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy(),
now: () => 1_000,
random: () => 0,
sleep: async () => {},
});
await runtime.dispose();
expect(
await runtime.abort({ uploadKey: "upload_key_01", signal: activeSignal }),
).toMatchObject({ ok: false, error: { operation: "UPLOAD_ABORT", recovery: "NONE" } });
});
});
+69
View File
@@ -1,6 +1,10 @@
import { describe, expect, it, vi } from "vitest";
import { createBrowserStorageAdapter } from "../../src/adapters/storage/browser-storage-adapter.ts";
import {
decodeBrowserStorageEnvelope,
encodeBrowserStorageEnvelope,
} from "../../src/adapters/storage/browser-storage-codec.ts";
import {
STORAGE_REGISTRY,
buildPhysicalKey,
@@ -665,3 +669,68 @@ describe("storage registry", () => {
);
});
});
/**
* 1101/05-06. Three guards of the Web Storage path were reached by no test:
* the stored record's expiry has to match the key's TTL shape (W2), and the
* codec refuses prototype keys (W5) and accessors (W6). The template's own
* keys hold strings without a numeric TTL, so a product's object codec or
* numeric TTL key is the first to reach them.
*/
describe("1101/05-06 Web Storage guards a downstream key reaches", () => {
const keyWith = (ttl: number | null) =>
defineStorageKey({
logicalName: "SHAPED_PREFERENCE",
scope: "preference",
name: "shaped",
backend: "localStorage",
classification: "public-preference",
schemaVersion: 1,
valueCodec: "opaque-string-v1",
ttl,
migration: "discard",
quotaFallback: "memory",
});
it.each([
["a TTL key whose record has no expiry", 10, null],
["a key without TTL whose record has one", null, 500],
] as const)("discards %s (W2)", (_label, ttl, expiresAt) => {
const key = keyWith(ttl);
const { storage, removeItem } = createStorage({
initial: { [key.physicalKey]: serializedEnvelope("private-value", { expiresAt }) },
});
const adapter = createBrowserStorageAdapter({
localStorage: storage,
now: () => 100,
resolveDefinition: definitionResolver({ SHAPED_PREFERENCE: key }),
});
expect(adapter.read("SHAPED_PREFERENCE")).toEqual({ ok: true, value: undefined });
expect(removeItem).toHaveBeenCalledWith(key.physicalKey);
});
it.each(["__proto__", "constructor", "prototype"])(
"refuses a record key %s in both directions (W5)",
(forbidden) => {
const raw = `{"schemaVersion":1,"expiresAt":null,"value":{${JSON.stringify(forbidden)}:1}}`;
expect(decodeBrowserStorageEnvelope(raw, 4_096)).toEqual({
ok: false,
reason: "MALFORMED_RECORD",
});
const value = JSON.parse(`{${JSON.stringify(forbidden)}:1}`) as unknown;
expect(
encodeBrowserStorageEnvelope({ schemaVersion: 1, expiresAt: null, value }, 4_096),
).toEqual({ ok: false, reason: "INVALID_VALUE" });
},
);
it("refuses an accessor instead of writing what it returns (W6)", () => {
const value = {};
Object.defineProperty(value, "label", { enumerable: true, get: () => "computed" });
expect(
encodeBrowserStorageEnvelope({ schemaVersion: 1, expiresAt: null, value }, 4_096),
).toEqual({ ok: false, reason: "INVALID_VALUE" });
});
});