From 44538819eb88b6ff8ddb0c4c24b8b0e074b8b14b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 19:31:44 +0900 Subject: [PATCH] =?UTF-8?q?fix(adapters):=20=EC=A7=80=EB=82=9C=20=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=EC=97=90=EC=84=9C=20=EB=82=A8=EC=9D=80=20adapter=20?= =?UTF-8?q?=EA=B2=B0=ED=95=A8=EA=B3=BC=20=EC=8B=9C=ED=97=98=20=EB=B9=88?= =?UTF-8?q?=EC=B9=B8=EC=9D=84=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제(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 --- .../browser-file-storage-recovery.md | 6 + .../client-cache-and-storage-recovery.md | 4 + docs/reviews/adapters/INVENTORY.md | 152 +++++++++--------- .../presigned/presigned-transfer-executor.ts | 9 +- .../resumable-upload-runtime.ts | 4 +- .../resumable-upload/runtime-policy.ts | 25 ++- .../cache-storage/public-cache-codec.ts | 23 +-- .../public-response-cache-adapter.ts | 13 +- src/adapters/platform/canonical-json.ts | 31 ++++ .../platform/opaque-authority-proof.ts | 8 + src/adapters/realtime/event-codec.ts | 29 +--- .../storage/indexeddb/indexeddb-runtime.ts | 17 +- .../storage/opfs/indexeddb-opfs-journal.ts | 22 +-- .../storage/opfs/opfs-byte-store-adapter.ts | 30 +++- .../storage/opfs/opfs-prepared-object.ts | 38 ++--- .../storage/opfs/opfs-worker-runtime.ts | 20 +-- src/application/ports/auth-session-port.ts | 6 + .../cache-storage-ports.ts | 7 +- .../ports/browser-file-storage/opfs-ports.ts | 7 + .../browser-transfer/resumable-upload.ts | 16 ++ .../providers/session-provider.tsx | 9 +- .../component/session-sign-in-return.test.tsx | 57 +++++++ tests/unit/canonical-json.test.ts | 32 ++++ tests/unit/indexeddb-runtime.test.ts | 89 ++++++++++ tests/unit/opfs-byte-store.test.ts | 50 ++++++ .../unit/public-response-cache-repair.test.ts | 33 +++- tests/unit/resumable-upload-runtime.test.ts | 31 ++++ tests/unit/storage-registry.test.ts | 69 ++++++++ 28 files changed, 640 insertions(+), 197 deletions(-) create mode 100644 src/adapters/platform/canonical-json.ts create mode 100644 src/adapters/platform/opaque-authority-proof.ts create mode 100644 tests/component/session-sign-in-return.test.tsx create mode 100644 tests/unit/canonical-json.test.ts diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index 9ad98c99..28070113 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -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:..`)과 OPFS journal + (`ca-frontend-opfs-metadata-v1:`) 이름이 그 token에서 나오므로 앱끼리 + DB가 갈린다. 이름 접두사를 바꾸는 조립 옵션은 두지 않는다(0929/05-10). + 계정 삭제·유지보수 경로가 같은 이름을 다시 계산하므로, 옵션을 한 곳에서 + 빠뜨리면 지웠다고 보고한 데이터가 남는다. 4. governance store의 바꿀 수 없는(immutable) scope와 `BrowserStoragePolicy` 전체 binding을 versionchange, post-open, maintenance 모두에서 확인한다. raw token이나 binding 내용을 incident log에 복사하지 않는다. diff --git a/docs/operations/client-cache-and-storage-recovery.md b/docs/operations/client-cache-and-storage-recovery.md index dbb296f9..b0a67c12 100644 --- a/docs/operations/client-cache-and-storage-recovery.md +++ b/docs/operations/client-cache-and-storage-recovery.md @@ -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만 요구하고 실패 시 diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index 0396dcd5..998bcb6f 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -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를 같은 변경에서 갱신한다. 연결된 상세 리뷰는 그 리뷰 때의 기록이라 고치지 않는다. 상세 리뷰에 없는 파일은 그 행의 상세 리뷰 칸에 가장 가까운 묶음을 적는다. diff --git a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts index 03bc3298..8b536138 100644 --- a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts +++ b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts @@ -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, diff --git a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts index da280ebe..7f0c5492 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -239,8 +239,10 @@ export function createResumableUploadRuntime( input: Parameters[0], ): Promise> { 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 ( diff --git a/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts b/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts index 926b444a..d02bf628 100644 --- a/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts +++ b/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts @@ -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 < diff --git a/src/adapters/cache-storage/public-cache-codec.ts b/src/adapters/cache-storage/public-cache-codec.ts index ec6681b5..c18c4c40 100644 --- a/src/adapters/cache-storage/public-cache-codec.ts +++ b/src/adapters/cache-storage/public-cache-codec.ts @@ -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; - 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; diff --git a/src/adapters/cache-storage/public-response-cache-adapter.ts b/src/adapters/cache-storage/public-response-cache-adapter.ts index 43ed3ee5..075cfce4 100644 --- a/src/adapters/cache-storage/public-response-cache-adapter.ts +++ b/src/adapters/cache-storage/public-response-cache-adapter.ts @@ -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 && diff --git a/src/adapters/platform/canonical-json.ts b/src/adapters/platform/canonical-json.ts new file mode 100644 index 00000000..4177488f --- /dev/null +++ b/src/adapters/platform/canonical-json.ts @@ -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>; + return `{${Object.keys(record) + .sort() + .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key], invalid)}`) + .join(",")}}`; + } + return invalid(); +} diff --git a/src/adapters/platform/opaque-authority-proof.ts b/src/adapters/platform/opaque-authority-proof.ts new file mode 100644 index 00000000..e2bf5db9 --- /dev/null +++ b/src/adapters/platform/opaque-authority-proof.ts @@ -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; diff --git a/src/adapters/realtime/event-codec.ts b/src/adapters/realtime/event-codec.ts index 60f6f29e..e4984e1a 100644 --- a/src/adapters/realtime/event-codec.ts +++ b/src/adapters/realtime/event-codec.ts @@ -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>)[key], - )}`, - ) - .join(",")}}`; + }); } diff --git a/src/adapters/storage/indexeddb/indexeddb-runtime.ts b/src/adapters/storage/indexeddb/indexeddb-runtime.ts index 31a2072c..3c98070f 100644 --- a/src/adapters/storage/indexeddb/indexeddb-runtime.ts +++ b/src/adapters/storage/indexeddb/indexeddb-runtime.ts @@ -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( ); } 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( * 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 | 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" ) { diff --git a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts index ea4b49c9..8a902c31 100644 --- a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts +++ b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts @@ -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, ) diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index e150a461..bc9f3818 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -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; diff --git a/src/adapters/storage/opfs/opfs-prepared-object.ts b/src/adapters/storage/opfs/opfs-prepared-object.ts index 5ee2af2b..ca046ba7 100644 --- a/src/adapters/storage/opfs/opfs-prepared-object.ts +++ b/src/adapters/storage/opfs/opfs-prepared-object.ts @@ -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; - 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 + ); } diff --git a/src/adapters/storage/opfs/opfs-worker-runtime.ts b/src/adapters/storage/opfs/opfs-worker-runtime.ts index 48622533..018bf0b2 100644 --- a/src/adapters/storage/opfs/opfs-worker-runtime.ts +++ b/src/adapters/storage/opfs/opfs-worker-runtime.ts @@ -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), ); } diff --git a/src/application/ports/auth-session-port.ts b/src/application/ports/auth-session-port.ts index 324a4e6e..aa674e30 100644 --- a/src/application/ports/auth-session-port.ts +++ b/src/application/ports/auth-session-port.ts @@ -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; signOut(): Promise; /** diff --git a/src/application/ports/browser-file-storage/cache-storage-ports.ts b/src/application/ports/browser-file-storage/cache-storage-ports.ts index ffc9658e..1b0dfa0c 100644 --- a/src/application/ports/browser-file-storage/cache-storage-ports.ts +++ b/src/application/ports/browser-file-storage/cache-storage-ports.ts @@ -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; diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index 48dac066..4f89f6f5 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -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<{ diff --git a/src/application/ports/browser-transfer/resumable-upload.ts b/src/application/ports/browser-transfer/resumable-upload.ts index 46851e50..11acb084 100644 --- a/src/application/ports/browser-transfer/resumable-upload.ts +++ b/src/application/ports/browser-transfer/resumable-upload.ts @@ -128,6 +128,22 @@ export interface ResumableUploadPort { upload( request: ResumableUploadRequest, ): Promise>; + /** + * 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; diff --git a/src/presentation/providers/session-provider.tsx b/src/presentation/providers/session-provider.tsx index d74dd6de..c3808ed1 100644 --- a/src/presentation/providers/session-provider.tsx +++ b/src/presentation/providers/session-provider.tsx @@ -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 { diff --git a/tests/component/session-sign-in-return.test.tsx b/tests/component/session-sign-in-return.test.tsx new file mode 100644 index 00000000..2f18a2eb --- /dev/null +++ b/tests/component/session-sign-in-return.test.tsx @@ -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 ( + + ); +} + +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( + + + + + + + , + ); + + await userEvent.setup().click(screen.getByRole("button", { name: "sign in" })); + + expect(beginSignIn).toHaveBeenCalledWith(expected); + }); +}); diff --git a/tests/unit/canonical-json.test.ts b/tests/unit/canonical-json.test.ts new file mode 100644 index 00000000..9dccea15 --- /dev/null +++ b/tests/unit/canonical-json.test.ts @@ -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"); + }); +}); diff --git a/tests/unit/indexeddb-runtime.test.ts b/tests/unit/indexeddb-runtime.test.ts index 1d3e7588..62d3893b 100644 --- a/tests/unit/indexeddb-runtime.test.ts +++ b/tests/unit/indexeddb-runtime.test.ts @@ -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), + ); + }); +}); diff --git a/tests/unit/opfs-byte-store.test.ts b/tests/unit/opfs-byte-store.test.ts index fb60e1e3..8158099b 100644 --- a/tests/unit/opfs-byte-store.test.ts +++ b/tests/unit/opfs-byte-store.test.ts @@ -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 () => diff --git a/tests/unit/public-response-cache-repair.test.ts b/tests/unit/public-response-cache-repair.test.ts index ee905ddc..0cb91bc9 100644 --- a/tests/unit/public-response-cache-repair.test.ts +++ b/tests/unit/public-response-cache-repair.test.ts @@ -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 diff --git a/tests/unit/resumable-upload-runtime.test.ts b/tests/unit/resumable-upload-runtime.test.ts index e0fcba58..5bfe566c 100644 --- a/tests/unit/resumable-upload-runtime.test.ts +++ b/tests/unit/resumable-upload-runtime.test.ts @@ -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" } }); + }); +}); diff --git a/tests/unit/storage-registry.test.ts b/tests/unit/storage-registry.test.ts index e2661138..a5b33630 100644 --- a/tests/unit/storage-registry.test.ts +++ b/tests/unit/storage-registry.test.ts @@ -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" }); + }); +});