fix(storage): 저장소 진단 이벤트에 실패 원인을 싣는다 (05-02)

문제: 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
This commit is contained in:
DongHyeonka
2026-11-01 22:25:41 +09:00
parent e98a980dff
commit 12c23feba9
2 changed files with 23 additions and 3 deletions
@@ -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 {
+20 -3
View File
@@ -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,