docs(storage): state that a stream can outlive a replaced OPFS generation (05-14)

Orphan GC counts its grace from when a chunk was written, so a read of an
older generation can lose its chunks once a newer put commits. Refreshing
every dropped chunk would rewrite whole objects, so the port now states the
contract instead: the stream ends NOT_FOUND / REHYDRATE and a reopen reads
the new generation. A test pins that outcome.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:59:43 +09:00
co-authored by Claude Opus 5.5
parent 9733ea8eaa
commit e872bfa27d
2 changed files with 59 additions and 0 deletions
@@ -85,6 +85,14 @@ export interface DurableObjectStorePort {
put(
request: PutDurableObjectRequest,
): Promise<BrowserDataResult<DurableObjectDescriptor>>;
/**
* 05-14. `open` checks the manifest; the bytes are read and verified while
* the source streams. A put that replaces the object meanwhile leaves the
* older generation's chunks to orphan GC, whose grace counts from when a
* chunk was written, not from when it lost its last reference. A stream
* that reaches a chunk GC already took ends with `NOT_FOUND` / `REHYDRATE`.
* Nothing is lost: open again to read the generation that replaced it.
*/
open(
request: OpenDurableObjectRequest,
): Promise<BrowserDataResult<OpenedDurableObject>>;