From f8587e8b6f4f6a1d562cf16a250bda1037b32799 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:18:41 +0900 Subject: [PATCH] docs(storage): state that revision and generation restart after delete (Q-6.5-8) Decision D-13 keeps the storage schema as is: IndexedDB `remove` deletes the row without a tombstone and an OPFS delete removes the logical object row, so a recreated key starts again at revision 1 / generation 1. The IndexedDB write receipt's `revision` and the durable object descriptor's `generation` now say so in the port comments, and the storage architecture doc says it in the IndexedDB record section and the OPFS journal rules: callers must not treat `(key, revision)` or `(objectId, generation)` as unique across the key's lifetime, and should compare a value they own (or the integrity root digest) when it matters. Documentation only. verify:documentation and all gates pass. Co-Authored-By: Claude Opus 5.5 --- .../architecture/browser-file-and-origin-storage.md | 13 +++++++++++++ .../ports/browser-file-storage/indexeddb-port.ts | 8 ++++++++ .../ports/browser-file-storage/opfs-ports.ts | 7 +++++++ 3 files changed, 28 insertions(+) diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index e3e787b5..1471ed5d 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -525,6 +525,14 @@ recipe의 feature-facing `StoredRecord` view model과 혼동하지 않는다. `writtenAtEpochMs`, synchronization, `measuredBytes`, `eligibleAtEpochMs`는 record envelope에 중복 저장하지 않고 `retentionStore` sidecar에 둔다. +revision은 살아 있는 record 하나 안에서만 순서를 매긴다(D-13). `remove`는 행을 +tombstone 없이 지우므로 같은 key를 다시 만들면 revision이 1부터 다시 시작한다. +그래서 `(key, revision)`은 key의 전체 수명에서 유일하지 않다. 삭제 전에 +revision N을 읽은 writer는 재생성된 record가 N에 도달하면 `expectedRevision: N` +CAS로 그 record를 덮어쓸 수 있다. 이 구분이 필요한 호출자는 revision과 함께 +자기가 소유한 값(server version, payload 안의 ID)을 비교한다. tombstone으로 +번호를 이어 가는 방식은 저장 스키마 변경이라 이 템플릿 범위 밖이다. + - structured clone 성공을 업무 schema 검증으로 간주하지 않는다. - 모든 read는 `unknown`에서 runtime codec으로 envelope와 payload version을 검증한 뒤 domain value로 mapping한다. @@ -771,6 +779,11 @@ CLEANED -> journal 제거 `STORAGE_EVICTED`; reconstructable만 rehydrate한다. - delete는 logical row tombstone을 먼저 commit해 신규 open을 막고 physical bytes를 나중에 정리한다. +- delete가 끝나면 logical row가 없어지므로 같은 object ID의 다음 put은 + generation 1부터 다시 시작한다(D-13). 삭제 전에 기억한 generation이나 + `expectedGeneration`은 다른 객체와 일치할 수 있다. `(objectId, generation)`을 + 객체 수명 전체의 식별자로 쓰지 않고, 필요하면 integrity root digest를 함께 + 비교한다. - operation ID로 replay를 deduplicate한다. `Web Locks`를 쓰면 고정된 origin mutation lock과 AbortSignal/timeout을 사용한다. diff --git a/src/application/ports/browser-file-storage/indexeddb-port.ts b/src/application/ports/browser-file-storage/indexeddb-port.ts index 98ad6eb8..cf71d6f3 100644 --- a/src/application/ports/browser-file-storage/indexeddb-port.ts +++ b/src/application/ports/browser-file-storage/indexeddb-port.ts @@ -68,6 +68,14 @@ export type IndexedDbPage = Readonly<{ export type IndexedDbWriteReceipt = Readonly<{ key: string; + /** + * D-13. A revision orders writes to one live record only. `remove` deletes + * the row without a tombstone, so the next create starts again at 1 and a + * `(key, revision)` pair is not unique across the key's lifetime: a writer + * holding revision N from before a delete can compare-and-swap over the + * recreated record once it reaches N. Pair the revision with a value the + * caller owns (a server version, an id in the payload) when that matters. + */ revision: number; replayed: boolean; }>; diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index 25d1fb72..dbd2f2ac 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -26,6 +26,13 @@ export type OpfsStorageScope = Readonly<{ export type DurableObjectDescriptor = Readonly<{ objectId: string; scope: OpfsStorageScope; + /** + * D-13. A generation orders puts to one live object only. Once `remove` + * commits, the next put starts again at 1, so a generation (or + * `expectedGeneration`) remembered from before the delete can match a + * different object. Do not treat `(objectId, generation)` as unique across + * the object's lifetime; compare the integrity root digest when it matters. + */ generation: number; byteLength: number; mediaType: string;