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 });