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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:30:26 +09:00
co-authored by Claude Opus 5.5
parent 16abd920a7
commit f8587e8b6f
3 changed files with 28 additions and 0 deletions
@@ -525,6 +525,14 @@ recipe의 feature-facing `StoredRecord<T>` 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을 사용한다.
@@ -68,6 +68,14 @@ export type IndexedDbPage<Value> = 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;
}>;
@@ -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;