From 12c23feba980ee7bb1c7f9f4264407d71ff84d3b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:01:00 +0900 Subject: [PATCH] =?UTF-8?q?fix(storage):=20=EC=A0=80=EC=9E=A5=EC=86=8C=20?= =?UTF-8?q?=EC=A7=84=EB=8B=A8=20=EC=9D=B4=EB=B2=A4=ED=8A=B8=EC=97=90=20?= =?UTF-8?q?=EC=8B=A4=ED=8C=A8=20=EC=9B=90=EC=9D=B8=EC=9D=84=20=EC=8B=A3?= =?UTF-8?q?=EB=8A=94=EB=8B=A4=20(05-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: Web Storage 어댑터의 실패 원인은 QUOTA_EXCEEDED, SIZE_LIMIT_EXCEEDED, UNAVAILABLE, VALUE_REJECTED 넷이다. 진단 이벤트 storage.operation.failed는 error_kind에 quota면 STORAGE_QUOTA_EXCEEDED, 나머지는 모두 STORAGE_UNAVAILABLE을 넣고 원인을 버린다. 그래서 운영자는 "브라우저 저장소를 못 쓴다"와 "저장된 값이 깨져서 버렸다"를 같은 이벤트로 본다. 호출자에게 주는 실패 code에는 원인이 이미 들어 있다. 고른 방법: recordStorageFailure의 context에 reason: cause를 더한다. reason은 진단 계약의 허용 칸(taxonomy)이고 원인 값은 어댑터의 닫힌 유니온이라 cardinality가 늘지 않는다. projectDiagnosticRecord에 넣어 칸이 그대로 남는 것을 확인했다. 버린 대안: error_kind를 원인별로 나누는 것. error_kind는 createFailure의 error kind taxonomy와 맞춰져 있어, 값을 늘리면 그 taxonomy를 바꿔야 한다. 이미 있는 reason 칸에 싣는 쪽이 추가만으로 끝난다. 위험·한계: 진단 이벤트에 칸이 하나 는다(추가만). 수집기가 reason을 바깥으로 내보내는지는 영역 03 소관이라 보지 않았다. 검증: - RED: storage-registry의 quota, discard 3종(malformed, invalid envelope, oversized), oversize write 테스트 5개가 실패. 예: "expected vi.fn() to be called with arguments" 차이 `- "reason": "VALUE_REJECTED"`. - GREEN: 같은 파일 23/23 통과. - 회귀: storage-registry, runtime-adapters, diagnostics, release-mismatch-recovery 4파일 68/68 통과. tsc app·test 통과, eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md --- .../storage/browser-storage-adapter.ts | 3 +++ tests/unit/storage-registry.test.ts | 23 ++++++++++++++++--- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/src/adapters/storage/browser-storage-adapter.ts b/src/adapters/storage/browser-storage-adapter.ts index 8c240fb5..9f009636 100644 --- a/src/adapters/storage/browser-storage-adapter.ts +++ b/src/adapters/storage/browser-storage-adapter.ts @@ -377,6 +377,9 @@ function recordStorageFailure( cause === "QUOTA_EXCEEDED" ? "STORAGE_QUOTA_EXCEEDED" : "STORAGE_UNAVAILABLE", + // 05-02. error_kind folds three causes into STORAGE_UNAVAILABLE; the + // cause tells a corrupt or oversized value apart from no storage. + reason: cause, }, }); } catch { diff --git a/tests/unit/storage-registry.test.ts b/tests/unit/storage-registry.test.ts index 33f980db..7259492e 100644 --- a/tests/unit/storage-registry.test.ts +++ b/tests/unit/storage-registry.test.ts @@ -269,6 +269,7 @@ describe("storage registry", () => { context: { operation: "write:COLOR_SCHEME", error_kind: "STORAGE_QUOTA_EXCEEDED", + reason: "QUOTA_EXCEEDED", }, }); expect(JSON.stringify(record.mock.calls)).not.toContain("dark"); @@ -307,7 +308,7 @@ describe("storage registry", () => { }); it.each([ - ["malformed JSON", "{private malformed value"], + ["malformed JSON", "{private malformed value", "VALUE_REJECTED"], [ "invalid envelope", JSON.stringify({ @@ -316,11 +317,12 @@ describe("storage registry", () => { value: "dark", unexpected: "private", }), + "VALUE_REJECTED", ], - ["oversized record", "x".repeat(512)], + ["oversized record", "x".repeat(512), "SIZE_LIMIT_EXCEEDED"], ])( "removes a %s once and suppresses it when native cleanup fails", - (_label, raw) => { + (_label, raw, reason) => { const physicalKey = STORAGE_REGISTRY.COLOR_SCHEME.physicalKey; const { storage, getItem, removeItem } = createStorage({ initial: { [physicalKey]: raw }, @@ -343,6 +345,16 @@ describe("storage registry", () => { }); expect(getItem).toHaveBeenCalledOnce(); expect(removeItem).toHaveBeenCalledOnce(); + // 05-02. A discarded value must not read as "storage unavailable". + expect(record).toHaveBeenCalledWith({ + level: "warn", + eventId: "storage.operation.failed", + context: { + operation: "discard:COLOR_SCHEME", + error_kind: "STORAGE_UNAVAILABLE", + reason, + }, + }); expect(JSON.stringify(record.mock.calls)).not.toMatch( /private|malformed|unexpected/, ); @@ -549,6 +561,11 @@ describe("storage registry", () => { code: "CHUNK_RELOAD_GUARD_WRITE_SIZE_LIMIT_EXCEEDED", }, }); + expect(record).toHaveBeenCalledWith( + expect.objectContaining({ + context: expect.objectContaining({ reason: "SIZE_LIMIT_EXCEEDED" }), + }), + ); expect(setItem).not.toHaveBeenCalled(); expect(JSON.stringify({ result, calls: record.mock.calls })).not.toContain( secret,