From e98a980dfff2b4cb4595f1efa626ac28d9925d6a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 21:59:07 +0900 Subject: [PATCH] =?UTF-8?q?fix(storage):=20pulse=20=ED=82=A4=EB=A5=BC=20?= =?UTF-8?q?=EC=99=B8=EB=B6=80=20=EC=86=8C=EC=9C=A0=EB=A1=9C=20=EC=A0=81?= =?UTF-8?q?=EC=96=B4=20StoragePort=EA=B0=80=20=EA=B1=B0=EC=A0=88=ED=95=9C?= =?UTF-8?q?=EB=8B=A4=20(05-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage, valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context 어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서 StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고 물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다. 고른 방법: StorageBackend에 "external"을 더하고 pulse 행을 backend external, valueCodec none으로 바꾼다. getStorageDefinition이 external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지 않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에 codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키 문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다. registry-governance의 backend 허용값에 external을 더하고, breaking 필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline 재승인 대신 기존 08-13·F-6과 같은 evidence 방식). 버린 대안: - 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다. - cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의 newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다. 위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend 유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은 분기를 더해야 한다. check:registries 결과는 compatibility=breaking (evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이 없어 실제 동작 변화는 없다. 검증: - RED: storage-registry "refuses the externally owned pulse key..."가 "expected { ok: true, value: undefined } to match object { ok: false }" 로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function] to throw an error"로 실패. - GREEN: 같은 파일 23/23 통과. - 회귀: storage-registry, registry-governance, cross-tab-invalidation, contract-registry-lookup, browser-security, runtime-adapters, release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과, eslint 통과, check-registries PASS, verify-documentation-readiness PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행. Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md --- .../contracts/registry-change-evidence.json | 16 ++++++ config/contracts/registry-governance.json | 3 +- docs/architecture/client-cache-and-storage.md | 4 +- docs/contracts/compatibility.md | 2 +- src/contracts/storage-keys.ts | 23 +++++++-- tests/unit/storage-registry.test.ts | 49 +++++++++++++++++++ 6 files changed, 91 insertions(+), 6 deletions(-) diff --git a/config/contracts/registry-change-evidence.json b/config/contracts/registry-change-evidence.json index 3c90d861..10de93e0 100644 --- a/config/contracts/registry-change-evidence.json +++ b/config/contracts/registry-change-evidence.json @@ -120,6 +120,22 @@ "compatibilityWindow": "None for bookmarked sample detail URLs: an old /examples/reference-resources/ URL no longer matches the detail route; new and status keep opening the form and status screens.", "rollback": "Restore the previous path in src/features/reference-feature/contracts/reference-feature-contract.ts and the link in reference-resource-page.tsx, then drop this entry.", "owner": "frontend-platform" + }, + { + "changeId": "FE-REG-STORAGE:CACHE_INVALIDATION_PULSE:backend:field-changed", + "versionBump": "05-01 (maturity review 2026-11-01): the pulse row moves from backend localStorage to the new external backend. The cross-context invalidation adapter owns the value format, so getStorageDefinition refuses the key and StoragePort can no longer delete the raw pulse as a corrupt envelope.", + "migration": "None. Nothing reads or writes this key through StoragePort. The cross-context adapter keeps writing raw wire JSON to the unchanged physical key ca-frontend:cache-invalidation:v1:pulse.", + "compatibilityWindow": "No storage or wire format changes: deployed tabs keep exchanging the same raw pulse on the same key. Only StoragePort read/write/remove on CACHE_INVALIDATION_PULSE now fail instead of discarding or overwriting the pulse.", + "rollback": "Restore backend localStorage and valueCodec opaque-string-v1 on CACHE_INVALIDATION_PULSE in src/contracts/storage-keys.ts, drop the external backend checks there and in registry-governance.json, then drop this entry and its valueCodec sibling.", + "owner": "frontend-platform" + }, + { + "changeId": "FE-REG-STORAGE:CACHE_INVALIDATION_PULSE:valueCodec:field-changed", + "versionBump": "05-01 (maturity review 2026-11-01): the pulse row drops valueCodec opaque-string-v1 for none. The stored value was never an opaque-string envelope; it is raw cross-context wire JSON.", + "migration": "None. Nothing reads or writes this key through StoragePort. The cross-context adapter keeps writing raw wire JSON to the unchanged physical key ca-frontend:cache-invalidation:v1:pulse.", + "compatibilityWindow": "No storage or wire format changes: deployed tabs keep exchanging the same raw pulse on the same key.", + "rollback": "Revert together with FE-REG-STORAGE:CACHE_INVALIDATION_PULSE:backend:field-changed.", + "owner": "frontend-platform" } ] } diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index 47619f22..24f4404a 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.json @@ -307,7 +307,8 @@ "sessionStorage", "localStorage", "disabled", - "forbidden" + "forbidden", + "external" ], "classification": [ "public-preference", diff --git a/docs/architecture/client-cache-and-storage.md b/docs/architecture/client-cache-and-storage.md index a71033be..afa249fd 100644 --- a/docs/architecture/client-cache-and-storage.md +++ b/docs/architecture/client-cache-and-storage.md @@ -80,8 +80,10 @@ delivery/cleanup을 검증한다. 다만 production QueryClient/coordinator까 account transition, bfcache/StrictMode lifecycle E2E는 없고, 현재 보존 artifact도 Chromium/Firefox만 통과해 WebKit을 포함한 promotion evidence는 충족하지 않는다. localStorage fallback physical key는 storage registry의 -`CACHE_INVALIDATION_PULSE` 항목에서 온다(`src/contracts/storage-keys.ts:102`, +`CACHE_INVALIDATION_PULSE` 항목에서 온다(`src/contracts/storage-keys.ts:112`, `src/adapters/cross-context-invalidation/browser-cross-context-host.ts:36-37`). +값은 envelope 없는 wire JSON이라 이 항목은 `backend: "external"`이다. +registry는 이름만 갖고, StoragePort는 이 key를 거절한다(05-01). host facade는 native `StorageEvent.storageArea`를 캡처한 `localStorage` 객체와 동일성으로 비교하고(`browser-cross-context-host.ts:286-296`), core는 `EXPECTED_LOCAL_STORAGE`로 표시된 pulse만 받는다 diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index 46ec1b18..8191cb93 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -28,7 +28,7 @@ reader that accepts it must ship before any writer sends it. | HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` | | Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` | | Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` | -| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:138-140` | +| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:148-150` | `CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids vary per build because each downstream project installs its own features, and diff --git a/src/contracts/storage-keys.ts b/src/contracts/storage-keys.ts index 0537041c..dd374e49 100644 --- a/src/contracts/storage-keys.ts +++ b/src/contracts/storage-keys.ts @@ -5,7 +5,12 @@ export type StorageBackend = | "sessionStorage" | "localStorage" | "disabled" - | "forbidden"; + | "forbidden" + /** + * Another adapter owns the value format and writes the physical key itself. + * The registry only owns the name, so StoragePort refuses the key. + */ + | "external"; export type StorageValueCodec = | "color-scheme-v1" @@ -99,14 +104,19 @@ export const STORAGE_REGISTRY = Object.freeze({ migration: "discard", quotaFallback: "feature-disable", }), + /** + * 05-01. The cross-context invalidation adapter writes raw wire JSON to this + * localStorage key with no envelope. Only the physical key name lives here. + * The key string is a channel between deployed tabs and must not change. + */ CACHE_INVALIDATION_PULSE: defineStorageKey({ logicalName: "CACHE_INVALIDATION_PULSE", scope: "cache-invalidation", name: "pulse", - backend: "localStorage", + backend: "external", classification: "opaque-cache", schemaVersion: 1, - valueCodec: "opaque-string-v1", + valueCodec: "none", ttl: null, migration: "discard", quotaFallback: "no-persist", @@ -145,6 +155,10 @@ export function defineStorageKey( if (definition.valueCodec !== "none") { throw new Error("Sensitive client storage codec is forbidden"); } + } else if (definition.backend === "external") { + if (definition.valueCodec !== "none") { + throw new Error("Externally owned storage keys have no StoragePort codec"); + } } else if (definition.valueCodec === "none") { throw new Error("Persisted storage keys require a value codec"); } @@ -179,6 +193,9 @@ export function getStorageDefinition(logicalName: string): StorageDefinition { if (definition.classification === "sensitive-forbidden") { throw new Error(`Forbidden storage key: ${logicalName}`); } + if (definition.backend === "external") { + throw new Error(`Externally owned storage key: ${logicalName}`); + } return definition; } diff --git a/tests/unit/storage-registry.test.ts b/tests/unit/storage-registry.test.ts index 2942d532..33f980db 100644 --- a/tests/unit/storage-registry.test.ts +++ b/tests/unit/storage-registry.test.ts @@ -164,6 +164,55 @@ describe("storage registry", () => { ).toThrow("Unsupported client storage migration policy"); }); + // 05-01. The cross-context adapter writes raw wire JSON to this physical + // key. StoragePort must refuse the key instead of discarding that value as + // a corrupt envelope or overwriting it with one. + it("refuses the externally owned pulse key without touching its value", () => { + const pulse = STORAGE_REGISTRY.CACHE_INVALIDATION_PULSE; + const rawPulse = JSON.stringify({ protocolVersion: 1, topic: "t" }); + const { storage, values, setItem, removeItem } = createStorage({ + initial: { [pulse.physicalKey]: rawPulse }, + }); + const adapter = createBrowserStorageAdapter({ localStorage: storage }); + + expect(adapter.read("CACHE_INVALIDATION_PULSE")).toMatchObject({ + ok: false, + error: { code: "CACHE_INVALIDATION_PULSE_READ_UNAVAILABLE" }, + }); + expect(adapter.write("CACHE_INVALIDATION_PULSE", "hello")).toMatchObject({ + ok: false, + }); + expect(adapter.remove("CACHE_INVALIDATION_PULSE")).toMatchObject({ + ok: false, + }); + expect(setItem).not.toHaveBeenCalled(); + expect(removeItem).not.toHaveBeenCalled(); + expect(values.get(pulse.physicalKey)).toBe(rawPulse); + + expect(pulse.physicalKey).toBe("ca-frontend:cache-invalidation:v1:pulse"); + expect(pulse).toMatchObject({ backend: "external", valueCodec: "none" }); + expect(() => getStorageDefinition("CACHE_INVALIDATION_PULSE")).toThrow( + "Externally owned storage key: CACHE_INVALIDATION_PULSE", + ); + }); + + it("rejects a value codec on an externally owned key", () => { + expect(() => + defineStorageKey({ + logicalName: "EXTERNAL_WITH_CODEC", + scope: "cache", + name: "external-with-codec", + backend: "external", + classification: "opaque-cache", + schemaVersion: 1, + valueCodec: "opaque-string-v1", + ttl: null, + migration: "discard", + quotaFallback: "no-persist", + }), + ).toThrow("Externally owned storage keys have no StoragePort codec"); + }); + it("round-trips public preferences through the adapter", () => { const { storage: localStorage } = createStorage(); const adapter = createBrowserStorageAdapter({ localStorage });