From 985fe4d158cc777cd16a8612e70462498aaea7f8 Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Fri, 31 Jul 2026 18:58:45 +1000
Subject: [PATCH 1/3] fix(ai-persistence): stream artifacts to length-strict
 stores, serve byte ranges
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The cap-enforcing TransformStream wrapper stripped the declared length off
every URL-fetched artifact body, so workerd's `R2Bucket.put` rejected all of
them with `TypeError: Provided readable stream must have a known length`.

- Wrap only when the response does not already bound itself. A trustworthy
  `content-length` is checked against the cap up front and HTTP framing holds
  the origin to it, so those bodies now reach `BlobStore.put` exactly as
  `fetch` produced them — length intact, single-shot into R2, nothing
  buffered. Chunked and content-encoded replies still get the counter.
- Add `BlobPutOptions.expectedLength`, the exact decoded length when the
  origin declared one, for SDKs that want the length as an argument (S3).
  Not forwarded on content-encoded replies, where it measures compressed
  bytes.
- Fix `Number(null) === 0` reading an absent `content-length` as a declared
  length of 0.
- `maxArtifactBytes`: default 100 MiB -> 1 GiB (it bounds transfer, not
  memory), and accept `false` to drop the ceiling entirely.
- Add `BlobStore.get(key, { range })` + `BlobObject.range`, threaded through
  `retrieveBlob`, with `parseRangeHeader` / `resolveBlobRange` helpers. Video
  seeking is built on 206/Content-Range and Safari will not play a source
  that ignores Range.
- Conformance: length-less stream puts (with and without the hint) and ranged
  reads, so a store that only handles byte bodies or ignores ranges fails the
  suite instead of failing on first real use.
- Docs, Cloudflare + media-generation skills, and the ts-react-chat example
  (SQLite store slices with `substr`, serve route answers 206/416) updated to
  match.

Closes #1030
---
 .changeset/persistence-stream-length-hint.md  |  19 +
 docs/persistence/build-your-own-adapter.md    |  80 +++-
 docs/persistence/keep-generated-files.md      | 140 ++++++-
 .../src/lib/sqlite-persistence.ts             |  32 +-
 .../ts-react-chat/src/routes/api.artifacts.ts |  60 ++-
 .../build-cloudflare-artifact-store/SKILL.md  | 220 +++++++++-
 packages/ai-persistence/src/blob-range.ts     |  90 ++++
 packages/ai-persistence/src/index.ts          |   6 +
 packages/ai-persistence/src/memory.ts         |  30 +-
 packages/ai-persistence/src/middleware.ts     |  98 ++++-
 packages/ai-persistence/src/retrieve.ts       |  15 +-
 .../ai-persistence/src/testkit/conformance.ts | 132 ++++++
 packages/ai-persistence/src/types.ts          |  67 ++-
 .../ai-persistence/tests/blob-range.test.ts   |  79 ++++
 .../tests/generation-artifacts.test.ts        | 383 ++++++++++++++++++
 .../skills/ai-core/media-generation/SKILL.md  |   7 +
 16 files changed, 1406 insertions(+), 52 deletions(-)
 create mode 100644 .changeset/persistence-stream-length-hint.md
 create mode 100644 packages/ai-persistence/src/blob-range.ts
 create mode 100644 packages/ai-persistence/tests/blob-range.test.ts

diff --git a/.changeset/persistence-stream-length-hint.md b/.changeset/persistence-stream-length-hint.md
new file mode 100644
index 000000000..36ea9aea2
--- /dev/null
+++ b/.changeset/persistence-stream-length-hint.md
@@ -0,0 +1,19 @@
+---
+'@tanstack/ai-persistence': minor
+---
+
+Streamed artifact bodies can now be persisted to length-strict blob stores (Cloudflare R2), `maxArtifactBytes` can be turned off for a zero-copy path onto R2, and `BlobStore.get` can serve byte ranges.
+
+**The bug.** URL-fetched artifacts arrived at `BlobStore.put` as a `TransformStream`-wrapped body — the wrapper that enforces `maxArtifactBytes` as the body drains. A transform's readable side carries no declared length, so runtimes that require one for a single-shot upload (workerd's `R2Bucket.put`) rejected every URL-sourced artifact with `TypeError: Provided readable stream must have a known length`. Byte bodies never hit this, which is why the old conformance suite (byte bodies only) and any store that buffers were unaffected.
+
+**The wrapper is now applied only when it is load-bearing.** A trustworthy `content-length` is checked against the cap up front, and HTTP framing holds the origin to it — a body cannot exceed a length it declared — so counting the bytes again adds nothing and costs the declared length. Those responses (the common case for a provider CDN) now reach `BlobStore.put` exactly as `fetch` produced them, length intact, so `R2Bucket.put` single-shots them with nothing buffered. The counter still wraps the two response shapes that genuinely need it: a chunked reply (no declared length at all) and a content-encoded one (whose declared length measures the compressed bytes, so the decoded stream can be a decompression bomb).
+
+**`BlobPutOptions.expectedLength` (additive).** `withGenerationPersistence` now forwards the artifact's exact decoded byte length to `BlobStore.put` when it is known — the `content-length` of an un-encoded artifact response. It is deliberately _not_ forwarded when the response is content-encoded: `fetch` transparently decompresses, so a gzipped reply's `content-length` is the compressed size and the decoded stream can be arbitrarily longer. Stores may use the hint to attach a declared length (e.g. workerd's `FixedLengthStream`) and single-shot the stream, or fall back to multipart when it is absent. Also fixed in the same code: a missing `content-length` header read as a declared length of `0` (`Number(null) === 0`), which kept the early-reject unreachable for chunked replies.
+
+**`BlobStore.get(key, { range })` (additive).** Serving a persisted video means answering HTTP `Range` requests: seeking a `<video>` is built on `206` / `Content-Range`, and Safari refuses to play a source that ignores `Range` entirely. `get` now takes a `BlobGetOptions` with a `range`, returns just that slice, and reports it as `BlobObject.range` while `size` keeps describing the whole object — the numbers a `206` needs. `retrieveBlob(persistence, artifact, { range })` passes it through, and two new helpers cover the fiddly halves: `parseRangeHeader(header, size)` resolves a `Range` header (suffix ranges, clamping, and the `416` case) for a serve route, and `resolveBlobRange(size, range)` does the clamping every byte-storing backend needs. Ranged reads are part of the contract for a store that holds bytes: the `get` signature stays source-compatible (the parameter is optional), so an existing custom store surfaces this as a conformance failure rather than a type error.
+
+**`maxArtifactBytes: false`, and a 1 GiB default** (was 100 MiB). The cap is a drain-time counter, not a buffer — the URL path streams into the blob store and never holds an artifact in memory — so it bounds _transfer_, not memory, and 100 MiB was simply too low for generated video. Passing `false` drops the ceiling and the wrapper on every response, including chunked ones. Keep the cap when `allowInputUrl` lets callers name the URL, or when you want any ceiling at all on what a runaway origin can stream into your bucket (`content-length` is advisory, so uncapped is unbounded).
+
+**Testkit.** `runPersistenceConformance` now exercises `blobs.put` with a length-less `TransformStream`-wrapped body — with and without `expectedLength` — and `blobs.get` with a byte range, so a store that only handles byte bodies or ignores ranges fails the suite instead of failing on first real use. Custom backends should re-run the suite.
+
+**Skill fix.** `ai-persistence/build-cloudflare-artifact-store` no longer claims the body "flows straight through" to `R2Bucket.put`: its R2 `BlobStore.put` recipe now re-declares `expectedLength` via `FixedLengthStream` and falls back to a one-part-at-a-time multipart upload when the length is unknown, and its `get` maps `range` onto R2's own ranged read.
diff --git a/docs/persistence/build-your-own-adapter.md b/docs/persistence/build-your-own-adapter.md
index 49ac8512a..6f8f22456 100644
--- a/docs/persistence/build-your-own-adapter.md
+++ b/docs/persistence/build-your-own-adapter.md
@@ -891,7 +891,7 @@ media.
 
 ```ts
 import { DatabaseSync } from 'node:sqlite'
-import { defineBlobStore } from '@tanstack/ai-persistence'
+import { defineBlobStore, resolveBlobRange } from '@tanstack/ai-persistence'
 import type {
   BlobBody,
   BlobObject,
@@ -942,9 +942,15 @@ function mapBlobRecord(row: Record<string, unknown>): BlobRecord {
   }
 }
 
-function blobObject(record: BlobRecord, bytes: Uint8Array): BlobObject {
+function blobObject(
+  record: BlobRecord,
+  bytes: Uint8Array,
+  range?: { offset: number; length: number },
+): BlobObject {
   return {
     ...record,
+    // `size` keeps describing the whole object; `range` describes these bytes.
+    ...(range ? { range } : {}),
     body: new ReadableStream<Uint8Array>({
       start(controller) {
         controller.enqueue(bytes.slice())
@@ -1005,12 +1011,21 @@ function createBlobStore(db: DatabaseSync) {
           : {}),
       }
     },
-    async get(key) {
+    async get(key, options) {
       const row = selectOne.get(key)
       if (!row) return null
       const bytes =
         row.bytes instanceof Uint8Array ? row.bytes : new Uint8Array()
-      return blobObject(mapBlobRecord(row), bytes)
+      if (!options?.range) return blobObject(mapBlobRecord(row), bytes)
+      // Clamp against the real size, then serve just that slice — a video
+      // seek asks for a few hundred KB of a file you should not re-read whole.
+      // (Push the slice into SQL with `substr(bytes, ?, ?)` for real sizes.)
+      const served = resolveBlobRange(bytes.byteLength, options.range)
+      return blobObject(
+        mapBlobRecord(row),
+        bytes.subarray(served.offset, served.offset + served.length),
+        served,
+      )
     },
     async head(key) {
       const row = selectOne.get(key)
@@ -1468,6 +1483,8 @@ interface BlobObject extends BlobRecord {
   arrayBuffer(): Promise<ArrayBuffer>
   text(): Promise<string>
   body?: ReadableStream<Uint8Array>
+  // The slice served, when a range was requested. Absent on a whole read.
+  range?: { offset: number; length: number }
 }
 
 interface BlobListPage {
@@ -1479,6 +1496,19 @@ interface BlobListPage {
 interface BlobPutOptions {
   contentType?: string
   customMetadata?: Record<string, string>
+  // Exact byte length of `body`, when the producer knows it. Advisory: use it
+  // to pick an upload strategy (single-shot vs multipart), never as a
+  // substitute for counting the bytes you actually store.
+  expectedLength?: number
+}
+
+interface BlobRange {
+  offset: number // from the start of the object; must be inside it
+  length?: number // defaults to "to the end"; clamped when it overshoots
+}
+
+interface BlobGetOptions {
+  range?: BlobRange
 }
 
 interface BlobListOptions {
@@ -1489,7 +1519,7 @@ interface BlobListOptions {
 
 interface BlobStore {
   put(key: string, body: BlobBody, options?: BlobPutOptions): Promise<BlobRecord>
-  get(key: string): Promise<BlobObject | null>
+  get(key: string, options?: BlobGetOptions): Promise<BlobObject | null>
   head(key: string): Promise<BlobRecord | null>
   delete(key: string): Promise<void>
   list(options?: BlobListOptions): Promise<BlobListPage>
@@ -1505,6 +1535,46 @@ Three contracts to hold for `list`:
   paging visits every key exactly once.
 - `limit: 0` yields an empty, untruncated page.
 
+And one for `put`: the body can be a `ReadableStream` with **no declared
+length**. That is how a URL-fetched artifact arrives whenever the origin does
+not declare one it can be held to — a chunked reply, or a compressed one whose
+`content-length` describes the compressed bytes. (When the origin *does* declare
+a usable length, the body reaches you exactly as `fetch` produced it, length
+intact, and `expectedLength` carries the same number.) Your store must drain a
+length-less stream, not require a length up front. Backends that need a declared
+length for a single-shot upload (Cloudflare R2 on workerd is one) can re-attach
+`expectedLength` when it is present and stream through a multipart upload when
+it is not — the `ai-persistence/build-cloudflare-artifact-store` skill ships that
+recipe. The conformance testkit exercises the length-less case, so a store that
+only handles byte bodies fails the suite.
+
+And one for `get`: honour `options.range` by returning **only that slice**.
+`size` keeps reporting the whole object, and the returned `range` reports what
+you actually served — together they are the `206` response a media player's
+seeking depends on. `resolveBlobRange(size, range)` does the clamping (a
+`length` past the end is legal and clamps; an `offset` past the end throws,
+because a serve route should have answered `416` from `record.size` first):
+
+```ts ignore
+import { resolveBlobRange } from '@tanstack/ai-persistence'
+
+async get(key: string, options?: BlobGetOptions) {
+  const row = await selectBlob(key)
+  if (!row) return null
+  if (!options?.range) return blobObject(row, row.body)
+  const served = resolveBlobRange(row.size, options.range)
+  // Slice at the storage layer, not after loading the whole object.
+  const bytes = await selectBlobSlice(key, served.offset, served.length)
+  return blobObject(row, bytes, served)
+}
+```
+
+This is not optional for a store that holds bytes — the conformance testkit
+asserts it. Ignoring `range` and returning the whole file is what makes
+`<video>` seeking (and Safari playback at all) fail, and it silently sends the
+entire artifact for every seek. A reference-only backend that stores no bytes
+skips `blobs` altogether instead.
+
 ## Where to go next
 
 - [Controls](./controls): compose stores from different systems.
diff --git a/docs/persistence/keep-generated-files.md b/docs/persistence/keep-generated-files.md
index 190311128..6323d7241 100644
--- a/docs/persistence/keep-generated-files.md
+++ b/docs/persistence/keep-generated-files.md
@@ -135,6 +135,83 @@ export async function GET(request: Request) {
 }
 ```
 
+### Serve video: honour `Range`
+
+The route above is enough for images. Video is not: seeking a `<video>` is
+built on HTTP range requests, and a source that answers every `Range` with the
+whole file cannot be scrubbed — Safari refuses to play it at all, and every
+other browser downloads the entire clip before it starts. Pass `range` to
+`retrieveBlob` and answer `206`:
+
+```ts group=generation-bytes
+import { parseRangeHeader } from '@tanstack/ai-persistence'
+import type { ArtifactRecord } from '@tanstack/ai-persistence'
+
+// The same route, seek-aware. `parseRangeHeader` resolves the header against
+// the size on the record — including suffix ranges (`bytes=-500` is the LAST
+// 500 bytes) and the unsatisfiable case. `blob.range` then reports the slice
+// actually served, and `artifact.size` the whole file: the two numbers
+// `Content-Range` needs.
+export async function serveArtifactBytes(
+  request: Request,
+  artifact: ArtifactRecord,
+) {
+  const range = parseRangeHeader(request.headers.get('range'), artifact.size)
+  if (range === 'unsatisfiable') {
+    return new Response('range not satisfiable', {
+      status: 416,
+      headers: { 'content-range': `bytes */${artifact.size}` },
+    })
+  }
+
+  const blob = await retrieveBlob(
+    persistence,
+    artifact,
+    range ? { range } : undefined,
+  )
+  if (!blob) return new Response('not found', { status: 404 })
+
+  const body = blob.body ?? (await blob.arrayBuffer())
+  // `accept-ranges` on every response, including the whole-file one: it is how
+  // the player learns it may seek at all.
+  const headers = {
+    'content-type': artifact.mimeType,
+    'accept-ranges': 'bytes',
+  }
+  if (!blob.range) {
+    return new Response(body, {
+      headers: { ...headers, 'content-length': String(artifact.size) },
+    })
+  }
+  const { offset, length } = blob.range
+  return new Response(body, {
+    status: 206,
+    headers: {
+      ...headers,
+      'content-length': String(length),
+      'content-range': `bytes ${offset}-${offset + length - 1}/${artifact.size}`,
+    },
+  })
+}
+```
+
+The client side needs nothing special — that is the point. Given a route that
+answers ranges, the browser drives the rest:
+
+```tsx
+import type { PersistedArtifactRef } from '@tanstack/ai'
+
+export function GeneratedVideo({ artifact }: { artifact: PersistedArtifactRef }) {
+  // `artifact.url` is the app-origin URL `artifactUrl` stamped on the ref.
+  return <video src={artifact.url} controls preload="metadata" />
+}
+```
+
+`preload="metadata"` has the player fetch the header bytes with a range request
+and show the duration and scrubber without pulling the clip down. A store must
+support ranged reads for any of this to work; the
+[conformance testkit](./build-your-own-adapter#blobstore) asserts it.
+
 `memoryPersistence` keeps everything in process memory, which is right for
 development and tests; point `generationRuns` / `artifacts` / `blobs` at a durable backend
 for production. Control what gets captured with `withGenerationPersistence`'s
@@ -204,7 +281,8 @@ Every artifact fetch, input or output, is bounded three ways:
 
 - The scheme must be `http:` or `https:`.
 - It is aborted after `artifactFetchTimeoutMs` (default 30s).
-- It is capped at `maxArtifactBytes` (default 100 MiB) as the body drains.
+- It is capped at `maxArtifactBytes` (default 1 GiB) as the body drains, or not
+  at all when you pass `false` — see [Nothing is buffered](#nothing-is-buffered).
 
 Input fetches add two more: a loopback / private / link-local host block, and a
 refusal to follow redirects, so a `302` cannot hop somewhere the check never
@@ -215,6 +293,66 @@ private address still passes a literal-IP check. Keep `allowInputUrl` narrow,
 and for stronger isolation inject `artifactFetch` to route downloads through an
 egress-restricted proxy that can check the address actually connected to.
 
+## Nothing is buffered
+
+A provider URL is **streamed** into the blob store: the middleware never holds
+the artifact in memory, and `size` on the record is counted as the bytes drain.
+A 2 GB video costs a streaming store (R2, S3, a filesystem) the same memory as
+a 2 KB icon. `memoryPersistence` is the exception, and only because holding the
+bytes in process *is* what it does — it is a dev/test store, not a production
+one.
+
+`maxArtifactBytes` is therefore a bound on **transfer**, not on memory. What it
+buys is a ceiling on what a runaway or hostile origin can make you pull and
+store: `content-length` is advisory, so an origin can declare 1 KB and send
+forever. That is the only reason there is a default at all.
+
+### The body reaches your store untouched when it can
+
+Enforcing the cap during the drain means wrapping the body in a
+`TransformStream` that counts — and a transform's readable side carries **no
+declared length**, which is exactly what workerd's `R2Bucket.put` needs for a
+single-shot upload. So the wrapper is applied only where it is load-bearing:
+
+| The response                                            | What your store gets                        |
+| ------------------------------------------------------- | ------------------------------------------- |
+| declares a `content-length`, no `content-encoding`       | the `fetch` body **untouched**, length intact |
+| chunked — no declared length                             | the counting wrapper                        |
+| `content-encoding: gzip` (declared length is compressed) | the counting wrapper                        |
+
+In the first row nothing is lost by skipping the counter: the declared length
+was already checked against the cap, and HTTP framing holds the origin to it —
+a body cannot exceed a length it declared. That is the common case for a
+provider CDN, so on Cloudflare the default configuration already streams
+straight through:
+
+```ts ignore
+// Inside your BlobStore.put on workerd — nothing buffered, no multipart, no
+// hint needed. (`R2Bucket` comes from @cloudflare/workers-types.)
+const putStraightToR2 = (bucket: R2Bucket, key: string, body: BlobBody) =>
+  bucket.put(key, body)
+```
+
+The other two rows genuinely need the counter — a chunked reply declares
+nothing, and a compressed one can decode to arbitrarily more than it declared
+(a decompression bomb). For those, `BlobPutOptions.expectedLength` is absent
+too, and a length-strict store falls back to a multipart upload that buffers
+one 8 MiB part at a time — flat memory, whatever the artifact's size. The
+`ai-persistence/build-cloudflare-artifact-store` skill ships that recipe.
+
+To drop the ceiling entirely — no counter on any response, no limit on what an
+origin can stream into your bucket — pass `false`:
+
+```ts group=generation-bytes
+const uncappedOptions = withGenerationPersistence(persistence, {
+  maxArtifactBytes: false,
+})
+```
+
+Reach for that when you trust the origins you fetch from and would rather have
+no ceiling than a generous one. Keep the cap when `allowInputUrl` lets callers
+name the URL — there the origin is by definition not one you control.
+
 ## Wire the durable URL through to the client
 
 `artifactUrl` is what makes the stored bytes reachable from the client without
diff --git a/examples/ts-react-chat/src/lib/sqlite-persistence.ts b/examples/ts-react-chat/src/lib/sqlite-persistence.ts
index 2e67be531..b112a2f23 100644
--- a/examples/ts-react-chat/src/lib/sqlite-persistence.ts
+++ b/examples/ts-react-chat/src/lib/sqlite-persistence.ts
@@ -31,6 +31,7 @@ import {
   defineMessageStore,
   defineMetadataStore,
   defineRunStore,
+  resolveBlobRange,
 } from '@tanstack/ai-persistence'
 import type {
   ModelMessage,
@@ -724,9 +725,15 @@ function mapBlobRecord(row: BlobRow): BlobRecord {
   }
 }
 
-function blobObject(record: BlobRecord, bytes: Uint8Array): BlobObject {
+function blobObject(
+  record: BlobRecord,
+  bytes: Uint8Array,
+  range?: { offset: number; length: number },
+): BlobObject {
   return {
     ...record,
+    // `size` keeps describing the whole object; `range` describes these bytes.
+    ...(range ? { range } : {}),
     body: new ReadableStream<Uint8Array>({
       start(controller) {
         controller.enqueue(bytes.slice())
@@ -754,6 +761,9 @@ function createBlobStore(db: DatabaseSync) {
        updated_at = excluded.updated_at`,
   )
   const selectStmt = db.prepare('SELECT * FROM blobs WHERE key = ?')
+  const rangeStmt = db.prepare(
+    'SELECT substr(body, ?, ?) AS body FROM blobs WHERE key = ?',
+  )
   const createdAtStmt = db.prepare('SELECT created_at FROM blobs WHERE key = ?')
   const deleteStmt = db.prepare('DELETE FROM blobs WHERE key = ?')
   // Prefix match via `substr(...) = ?` rather than LIKE: SQLite's LIKE is
@@ -799,10 +809,26 @@ function createBlobStore(db: DatabaseSync) {
       )
       return record
     },
-    get(key) {
+    get(key, options) {
       const row = selectStmt.get(key) as BlobRow | undefined
+      if (!row) return Promise.resolve(null)
+      if (!options?.range) {
+        return Promise.resolve(blobObject(mapBlobRecord(row), row.body))
+      }
+      // Clamp the request to the object the way every byte-storing backend
+      // must — `resolveBlobRange` is the shared implementation, and it throws
+      // on an offset past the end so an unsatisfiable range can't be served as
+      // a 206. A route answers 416 from `record.size` before getting here.
+      const served = resolveBlobRange(row.size, options.range)
+      // Slice in SQLite (1-based, byte-wise over a BLOB) rather than loading
+      // the whole object to hand back a few bytes of it — the difference
+      // between seeking a video and reading it end to end.
+      const sliced = rangeStmt.get(served.offset + 1, served.length, key) as
+        | Pick<BlobRow, 'body'>
+        | undefined
+      if (!sliced) return Promise.resolve(null)
       return Promise.resolve(
-        row ? blobObject(mapBlobRecord(row), row.body) : null,
+        blobObject(mapBlobRecord(row), sliced.body, served),
       )
     },
     head(key) {
diff --git a/examples/ts-react-chat/src/routes/api.artifacts.ts b/examples/ts-react-chat/src/routes/api.artifacts.ts
index b6770c2be..9a92050cd 100644
--- a/examples/ts-react-chat/src/routes/api.artifacts.ts
+++ b/examples/ts-react-chat/src/routes/api.artifacts.ts
@@ -1,5 +1,9 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { retrieveArtifact, retrieveBlob } from '@tanstack/ai-persistence'
+import {
+  parseRangeHeader,
+  retrieveArtifact,
+  retrieveBlob,
+} from '@tanstack/ai-persistence'
 import { generationServerPersistence } from '../lib/generation-server-store'
 
 /**
@@ -33,17 +37,57 @@ export const Route = createFileRoute('/api/artifacts')({
         // comes from the caller, and `ArtifactRecord` carries the `threadId`
         // to check it against. This demo is single-user, so there is no
         // session to check.
-        const blob = await retrieveBlob(persistence, artifact)
+
+        // Video seeking is built on `Range`: the browser asks for a slice and
+        // expects `206` + `Content-Range`, and Safari refuses to play a source
+        // that ignores `Range` outright. `parseRangeHeader` resolves the
+        // header against the known size, so an unsatisfiable range is a `416`
+        // here rather than a bad `206`.
+        const range = parseRangeHeader(
+          request.headers.get('range'),
+          artifact.size,
+        )
+        if (range === 'unsatisfiable') {
+          return new Response('range not satisfiable', {
+            status: 416,
+            headers: { 'content-range': `bytes */${artifact.size}` },
+          })
+        }
+
+        const blob = await retrieveBlob(
+          persistence,
+          artifact,
+          range ? { range } : undefined,
+        )
         if (!blob) return new Response('not found', { status: 404 })
 
-        return new Response(blob.body ?? (await blob.arrayBuffer()), {
+        const cacheHeaders = {
+          'content-type': artifact.mimeType,
+          // Artifact ids are content-addressed by run: the bytes behind an id
+          // never change, so this is safe to cache hard. `private` because a
+          // real deployment serves these per-user.
+          'cache-control': 'private, max-age=31536000, immutable',
+          // Advertised on every response, so a player knows it can seek.
+          'accept-ranges': 'bytes',
+        }
+        const body = blob.body ?? (await blob.arrayBuffer())
+
+        if (blob.range) {
+          const { offset, length } = blob.range
+          return new Response(body, {
+            status: 206,
+            headers: {
+              ...cacheHeaders,
+              'content-length': String(length),
+              'content-range': `bytes ${offset}-${offset + length - 1}/${artifact.size}`,
+            },
+          })
+        }
+
+        return new Response(body, {
           headers: {
-            'content-type': artifact.mimeType,
+            ...cacheHeaders,
             'content-length': String(artifact.size),
-            // Artifact ids are content-addressed by run: the bytes behind an id
-            // never change, so this is safe to cache hard. `private` because a
-            // real deployment serves these per-user.
-            'cache-control': 'private, max-age=31536000, immutable',
           },
         })
       },
diff --git a/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md b/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md
index 236cea847..1e01ab7f6 100644
--- a/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md
+++ b/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md
@@ -35,7 +35,8 @@ interface BlobStore {
     body: BlobBody,
     options?: BlobPutOptions,
   ): Promise<BlobRecord>
-  get(key: string): Promise<BlobObject | null> // metadata + byte accessors
+  // metadata + byte accessors; `options.range` reads one slice (for `206`s)
+  get(key: string, options?: BlobGetOptions): Promise<BlobObject | null>
   head(key: string): Promise<BlobRecord | null> // metadata only
   delete(key: string): Promise<void> // no-op if absent
   list(options?: BlobListOptions): Promise<BlobListPage>
@@ -52,10 +53,43 @@ interface ArtifactStore {
 ```
 
 `BlobBody` is `ReadableStream<Uint8Array> | ArrayBuffer | ArrayBufferView |
-string | Blob` — which is exactly what `R2Bucket.put` accepts, so the body flows
-straight through with no conversion. `BlobPutOptions` is
-`{ contentType?, customMetadata? }`; `BlobListOptions` is
-`{ prefix?, cursor?, limit? }`; `BlobListPage` is
+string | Blob`. The non-stream shapes flow straight into `R2Bucket.put`
+unchanged — but a `ReadableStream` body does **not**, in the general case:
+workerd's `put` requires a stream with a known length (a `Response` body or the
+readable half of a `FixedLengthStream`), and the artifact middleware hands you a
+`TransformStream`-wrapped body whenever it fetched the bytes from a provider
+URL — i.e. essentially every generated artifact. Passing that stream to
+`bucket.put` throws `TypeError: Provided readable stream must have a known
+length`.
+
+**When does that actually happen?** The wrapper only exists to enforce
+`maxArtifactBytes` during the drain, so the middleware applies it only when
+nothing else bounds the transfer:
+
+| Provider response                       | Body handed to `put`              | R2 path             |
+| --------------------------------------- | --------------------------------- | ------------------- |
+| `content-length`, no `content-encoding` | untouched, declared length intact | `bucket.put` direct |
+| chunked (no declared length)            | wrapped, length-less              | multipart           |
+| `content-encoding: gzip`                | wrapped, length-less              | multipart           |
+
+A provider CDN normally sends `content-length`, so the first row is the common
+case and `bucket.put(key, body)` just works. The recipe below is what makes the
+other two rows work: it re-declares the length from
+`BlobPutOptions.expectedLength` when the middleware could vouch for one, and
+otherwise streams through a multipart upload (one 8 MiB part at a time — flat
+memory at any artifact size). Write it once and every response shape is
+covered.
+
+`withGenerationPersistence(persistence, { maxArtifactBytes: false })` drops the
+ceiling and the wrapper altogether, so even a chunked reply arrives untouched.
+It buys nothing extra for R2 (a chunked body has no length to preserve), so
+choose it on its own merits: no limit on what an origin can stream into your
+bucket. Keep the cap when `allowInputUrl` lets callers name the URL.
+
+`BlobPutOptions` is
+`{ contentType?, customMetadata?, expectedLength? }`; `BlobGetOptions` is
+`{ range?: { offset: number, length?: number } }` and maps onto R2's own
+`range`; `BlobListOptions` is `{ prefix?, cursor?, limit? }`; `BlobListPage` is
 `{ objects: BlobRecord[], cursor?, truncated? }`.
 
 ## 1. BlobStore backed by R2
@@ -68,9 +102,78 @@ ms — R2 tracks only the single `uploaded` instant, so map it to both. `get` /
 object plus the mapped metadata.
 
 ```ts ignore
-import { defineBlobStore } from '@tanstack/ai-persistence'
+import { defineBlobStore, resolveBlobRange } from '@tanstack/ai-persistence'
 import type { BlobObject, BlobRecord } from '@tanstack/ai-persistence'
 
+// R2 multipart requires every part but the last to be ≥ 5 MiB. Buffering one
+// part at a time keeps peak memory flat regardless of artifact size.
+const MULTIPART_PART_SIZE = 8 * 1024 * 1024
+
+/** Drain `reader` until `limit` bytes accumulate or the stream ends. */
+async function readUpTo(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  limit: number,
+): Promise<{ bytes: Uint8Array; eof: boolean }> {
+  let bytes = new Uint8Array(0)
+  for (;;) {
+    if (bytes.byteLength >= limit) return { bytes, eof: false }
+    const { value, done } = await reader.read()
+    if (done) return { bytes, eof: true }
+    const merged = new Uint8Array(bytes.byteLength + value.byteLength)
+    merged.set(bytes)
+    merged.set(value, bytes.byteLength)
+    bytes = merged
+  }
+}
+
+/**
+ * `R2Bucket.put` requires a stream with a known length; a pass-through
+ * TransformStream (what the middleware sends for URL-fetched artifacts) has
+ * none. Re-declare the length when `expectedLength` provides it — the
+ * middleware only sets it when it is the exact decoded byte count — and
+ * otherwise stream through a multipart upload, one buffered part at a time.
+ */
+async function putStream(
+  bucket: R2Bucket,
+  key: string,
+  body: ReadableStream<Uint8Array>,
+  options: R2PutOptions,
+  expectedLength: number | undefined,
+): Promise<R2Object | null> {
+  if (expectedLength !== undefined) {
+    return bucket.put(
+      key,
+      body.pipeThrough(new FixedLengthStream(expectedLength)),
+      options,
+    )
+  }
+  const reader = body.getReader()
+  const first = await readUpTo(reader, MULTIPART_PART_SIZE)
+  if (first.eof) {
+    // The whole body fit in one part — a plain put is enough.
+    return bucket.put(key, first.bytes, options)
+  }
+  const upload = await bucket.createMultipartUpload(key, options)
+  try {
+    const parts: Array<R2UploadedPart> = [
+      await upload.uploadPart(1, first.bytes),
+    ]
+    let partNumber = 2
+    for (;;) {
+      const part = await readUpTo(reader, MULTIPART_PART_SIZE)
+      if (part.bytes.byteLength > 0) {
+        parts.push(await upload.uploadPart(partNumber, part.bytes))
+        partNumber += 1
+      }
+      if (part.eof) break
+    }
+    return await upload.complete(parts)
+  } catch (error) {
+    await upload.abort().catch(() => undefined)
+    throw error
+  }
+}
+
 function toRecord(obj: R2Object): BlobRecord {
   const uploaded = obj.uploaded.getTime()
   return {
@@ -89,24 +192,54 @@ function toRecord(obj: R2Object): BlobRecord {
 export function r2BlobStore(bucket: R2Bucket) {
   return defineBlobStore({
     async put(key, body, options) {
-      const obj = await bucket.put(key, body, {
+      const r2Options = {
         ...(options?.contentType
           ? { httpMetadata: { contentType: options.contentType } }
           : {}),
         ...(options?.customMetadata
           ? { customMetadata: options.customMetadata }
           : {}),
-      })
+      }
+      const obj =
+        body instanceof ReadableStream
+          ? await putStream(
+              bucket,
+              key,
+              body,
+              r2Options,
+              options?.expectedLength,
+            )
+          : await bucket.put(key, body, r2Options)
       // R2.put returns null only when an onlyIf precondition fails — not used here.
       if (!obj) throw new Error(`R2 put failed for ${key}`)
       return toRecord(obj)
     },
 
-    async get(key): Promise<BlobObject | null> {
-      const obj = await bucket.get(key)
+    async get(key, options): Promise<BlobObject | null> {
+      // A ranged read is what a serve route turns into `206` — R2 slices in
+      // the bucket, so a seek never streams the whole object. `resolveBlobRange`
+      // clamps a too-long length and throws on an offset past the end (the
+      // route answers `416` from `record.size` before ever calling in). The
+      // extra `head` buys that clamp deterministically — one class-B op
+      // against streaming bytes you did not need to send.
+      const head = options?.range ? await bucket.head(key) : null
+      const served =
+        options?.range && head
+          ? resolveBlobRange(head.size, options.range)
+          : undefined
+      const obj = await bucket.get(
+        key,
+        served
+          ? { range: { offset: served.offset, length: served.length } }
+          : {},
+      )
       if (!obj) return null
       return {
+        // `toRecord(obj)` reports the WHOLE object's size even on a ranged
+        // read — R2's `R2Object.size` is the object, not the slice — which is
+        // exactly the contract, and what `Content-Range`'s total needs.
         ...toRecord(obj),
+        ...(served ? { range: served } : {}),
         body: obj.body,
         arrayBuffer: () => obj.arrayBuffer(),
         text: () => obj.text(),
@@ -147,6 +280,14 @@ Invariants that matter (asserted by the conformance testkit):
 
 - `get` / `head` return `null` for a missing key; `delete` is a silent no-op.
 - `put` **overwrites** an existing key.
+- `put` accepts a `ReadableStream` body with **no declared length** — the
+  middleware streams URL-fetched artifacts as exactly that. This is where the
+  naive "pass the body straight to `bucket.put`" recipe fails at runtime
+  (workerd requires a known length), which is what `putStream` above handles.
+- `get` honours `options.range`: it returns **only** that slice, reports it as
+  `range`, and keeps `size` on the whole object. That is the `206` a video
+  player's seeking depends on, and R2 slices in the bucket so the bytes never
+  cross the Worker.
 - `list` filters by `prefix` literally (R2 prefix is a literal byte prefix — no
   glob), returns keys in ascending order, and pages via the opaque `cursor` when
   `truncated`. R2's own cursor is opaque and satisfies this directly. `limit: 0`
@@ -332,6 +473,10 @@ export default {
       threadId, // the slot recorded on the job + artifacts
       stream: true,
       middleware: [
+        // Nothing is buffered: the artifact streams from the provider CDN
+        // into R2. Add `maxArtifactBytes: false` if you want no ceiling at
+        // all on what an origin can stream into your bucket (the default is
+        // 1 GiB); it is not needed for the streaming itself.
         withGenerationPersistence(generationPersistence(env), { threadId }),
       ],
     })
@@ -348,8 +493,19 @@ A GET route resolves an `artifactId` to its record and its stored bytes.
 key off `artifactBlobKey({ runId, artifactId })` internally, so you never build
 the key yourself.
 
+Honour `Range` requests: `<video>` seeking is built on `206` / `Content-Range`,
+and Safari refuses to play a source that ignores `Range` entirely. Images never
+notice; a few-hundred-MB clip is unwatchable without it. Pass `range` to
+`retrieveBlob` — the store slices in R2 — rather than reaching into the bucket
+binding from the route, which would tie the route to R2 and bypass the store's
+own key resolution.
+
 ```ts ignore
-import { retrieveArtifact, retrieveBlob } from '@tanstack/ai-persistence'
+import {
+  parseRangeHeader,
+  retrieveArtifact,
+  retrieveBlob,
+} from '@tanstack/ai-persistence'
 import { generationPersistence } from './lib/generation-persistence'
 
 export async function GET(request: Request, env: Env) {
@@ -361,13 +517,43 @@ export async function GET(request: Request, env: Env) {
   const record = await retrieveArtifact(persistence, artifactId)
   if (!record) return new Response('Not found', { status: 404 })
 
-  const blob = await retrieveBlob(persistence, record) // pass the record: no 2nd lookup
+  // `parseRangeHeader` resolves the header against the size on the record —
+  // suffix ranges included — so an unsatisfiable range is a 416 here and the
+  // store only ever sees a range it can serve.
+  const range = parseRangeHeader(request.headers.get('range'), record.size)
+  if (range === 'unsatisfiable') {
+    return new Response('Range not satisfiable', {
+      status: 416,
+      headers: { 'content-range': `bytes */${record.size}` },
+    })
+  }
+
+  // Pass the record, not the id: no second metadata lookup.
+  const blob = await retrieveBlob(
+    persistence,
+    record,
+    range ? { range } : undefined,
+  )
   if (!blob?.body) return new Response('Not found', { status: 404 })
 
+  // `accept-ranges` on every response, including the whole-file one: it is how
+  // a player learns it may seek at all.
+  const headers = {
+    'content-type': record.mimeType,
+    'accept-ranges': 'bytes',
+  }
+  if (!blob.range) {
+    return new Response(blob.body, {
+      headers: { ...headers, 'content-length': String(record.size) },
+    })
+  }
+  const { offset, length } = blob.range
   return new Response(blob.body, {
+    status: 206,
     headers: {
-      'content-type': record.mimeType,
-      'content-length': String(record.size),
+      ...headers,
+      'content-length': String(length),
+      'content-range': `bytes ${offset}-${offset + length - 1}/${record.size}`,
     },
   })
 }
@@ -419,6 +605,12 @@ between runs (see **ai-persistence/build-cloudflare-adapter** for the
 
 - `put` then `get` round-trips bytes and metadata; `get`/`head` return `null` for
   a missing key; `delete` is a silent no-op on an absent key.
+- `put` accepts a `ReadableStream` body with no declared length (a
+  `TransformStream`-wrapped stream) and records the real drained size — the
+  shape every URL-fetched artifact arrives in.
+- `get` with a `range` returns just that slice, reports it as `range`, and
+  still reports the whole object's `size` — what a `206` / `Content-Range`
+  response is built from.
 - `put` overwrites an existing key (and its `contentType`/`customMetadata`).
 - `list` filters by `prefix` **literally and case-sensitively**, returns
   ascending keys, pages through the `cursor` when `truncated` without gaps or
diff --git a/packages/ai-persistence/src/blob-range.ts b/packages/ai-persistence/src/blob-range.ts
new file mode 100644
index 000000000..e0014ab27
--- /dev/null
+++ b/packages/ai-persistence/src/blob-range.ts
@@ -0,0 +1,90 @@
+import type { BlobRange } from './types'
+
+/**
+ * Resolve a requested {@link BlobRange} against an object's real size, the way
+ * every byte-storing blob store has to before it slices.
+ *
+ * Clamps `length` to the end of the object and treats an absent `length` as
+ * "to the end", so the result is always the slice actually served — which is
+ * what `BlobObject.range` reports and what a `206` response's `Content-Range`
+ * is built from.
+ *
+ * Throws on an `offset` outside the object: that is a caller error, not a
+ * store error. A serve route knows the size (it is on the artifact record) and
+ * answers `416` from it, so a store only ever sees a satisfiable range unless
+ * something upstream is wrong — and silently returning an empty body there
+ * would serve a `206` that claims bytes it does not carry.
+ *
+ * @example
+ * ```ts
+ * const { offset, length } = resolveBlobRange(bytes.byteLength, range)
+ * const slice = bytes.subarray(offset, offset + length)
+ * ```
+ */
+export function resolveBlobRange(
+  size: number,
+  range: BlobRange,
+): { offset: number; length: number } {
+  const { offset } = range
+  if (!Number.isInteger(offset) || offset < 0 || offset >= size) {
+    throw new RangeError(
+      `Blob range offset ${offset} is outside the object (size ${size}).`,
+    )
+  }
+  const remaining = size - offset
+  if (range.length === undefined) return { offset, length: remaining }
+  if (!Number.isInteger(range.length) || range.length < 0) {
+    throw new RangeError(`Blob range length ${range.length} is not valid.`)
+  }
+  return { offset, length: Math.min(range.length, remaining) }
+}
+
+/**
+ * Resolve an HTTP `Range` header against a known object size, for a route that
+ * serves artifact bytes.
+ *
+ * Returns the {@link BlobRange} to pass to `retrieveBlob` / `BlobStore.get`,
+ * `'unsatisfiable'` when the request names bytes the object does not have — answer
+ * `416`, whose `content-range` is the literal `bytes` `*` then a slash then the
+ * size — or `undefined` when there is no range to honour: an absent header, and
+ * equally the forms this does not implement (multiple ranges, units other than
+ * `bytes`), which a server is always free to answer in full.
+ *
+ * @example
+ * ```ts
+ * const range = parseRangeHeader(request.headers.get('range'), record.size)
+ * if (range === 'unsatisfiable') return new Response(null, { status: 416 })
+ * const blob = await retrieveBlob(
+ *   persistence,
+ *   record,
+ *   range ? { range } : undefined,
+ * )
+ * ```
+ */
+export function parseRangeHeader(
+  header: string | null | undefined,
+  size: number,
+): BlobRange | 'unsatisfiable' | undefined {
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header?.trim() ?? '')
+  if (!match) return undefined
+  const [, rawStart, rawEnd] = match
+  // `bytes=-` names nothing at all.
+  if (rawStart === '' && rawEnd === '') return undefined
+
+  // `bytes=-500` is the LAST 500 bytes, not "from 0 to 500" — the one form
+  // that is easy to read backwards, and reading it backwards serves the wrong
+  // bytes with a 206 that claims they are the right ones.
+  if (rawStart === '') {
+    const suffix = Number(rawEnd)
+    if (suffix === 0) return 'unsatisfiable'
+    return { offset: Math.max(0, size - suffix) }
+  }
+
+  const start = Number(rawStart)
+  if (start >= size) return 'unsatisfiable'
+  if (rawEnd === '') return { offset: start }
+  const end = Number(rawEnd)
+  if (end < start) return 'unsatisfiable'
+  // `end` is inclusive, and past the end of the object it simply clamps.
+  return { offset: start, length: Math.min(end, size - 1) - start + 1 }
+}
diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
index b0f4247b6..f9e8de84f 100644
--- a/packages/ai-persistence/src/index.ts
+++ b/packages/ai-persistence/src/index.ts
@@ -38,6 +38,8 @@ export type {
   BlobObject,
   BlobListPage,
   BlobPutOptions,
+  BlobGetOptions,
+  BlobRange,
   BlobListOptions,
   BlobStore,
   AIPersistence,
@@ -91,6 +93,10 @@ export {
   resolveArtifactBlobKey,
 } from './retrieve'
 
+// Byte-range helpers: parse a `Range` header (routes), clamp a range to an
+// object's real size (store authors)
+export { parseRangeHeader, resolveBlobRange } from './blob-range'
+
 // Reference in-memory implementation
 export { memoryPersistence } from './memory'
 
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
index eef3590b2..f511115e5 100644
--- a/packages/ai-persistence/src/memory.ts
+++ b/packages/ai-persistence/src/memory.ts
@@ -1,11 +1,15 @@
 import { defineAIPersistence } from './types'
+import { resolveBlobRange } from './blob-range'
 import type { ModelMessage } from '@tanstack/ai'
 import type {
   ArtifactRecord,
   ArtifactStore,
   BlobBody,
+  BlobGetOptions,
   BlobListOptions,
   BlobObject,
+  BlobPutOptions,
+  BlobRange,
   BlobRecord,
   BlobStore,
   GenerationRunRecord,
@@ -324,10 +328,21 @@ function blobRecordSnapshot(record: BlobRecord): BlobRecord {
   }
 }
 
-function blobObject(record: BlobRecord, bytes: Uint8Array): BlobObject {
-  const copied = copyBytes(bytes)
+function blobObject(
+  record: BlobRecord,
+  bytes: Uint8Array,
+  range?: BlobRange,
+): BlobObject {
+  // `size` keeps reporting the whole object; only the bytes narrow.
+  const served = range
+    ? resolveBlobRange(bytes.byteLength, range)
+    : { offset: 0, length: bytes.byteLength }
+  const copied = copyBytes(
+    bytes.subarray(served.offset, served.offset + served.length),
+  )
   return {
     ...blobRecordSnapshot(record),
+    ...(range ? { range: served } : {}),
     body: new ReadableStream<Uint8Array>({
       start(controller) {
         controller.enqueue(copyBytes(copied))
@@ -346,10 +361,7 @@ class MemoryBlobStore implements BlobStore {
   async put(
     key: string,
     body: BlobBody,
-    options?: {
-      contentType?: string
-      customMetadata?: Record<string, string>
-    },
+    options?: BlobPutOptions,
   ): Promise<BlobRecord> {
     const bytes = await bytesFromBlobBody(body)
     const existing = this.blobs.get(key)
@@ -373,9 +385,11 @@ class MemoryBlobStore implements BlobStore {
     return blobRecordSnapshot(record)
   }
 
-  get(key: string): Promise<BlobObject | null> {
+  get(key: string, options?: BlobGetOptions): Promise<BlobObject | null> {
     const entry = this.blobs.get(key)
-    return Promise.resolve(entry ? blobObject(entry.record, entry.bytes) : null)
+    return Promise.resolve(
+      entry ? blobObject(entry.record, entry.bytes, options?.range) : null,
+    )
   }
 
   head(key: string): Promise<BlobRecord | null> {
diff --git a/packages/ai-persistence/src/middleware.ts b/packages/ai-persistence/src/middleware.ts
index e0a8af759..d6f346128 100644
--- a/packages/ai-persistence/src/middleware.ts
+++ b/packages/ai-persistence/src/middleware.ts
@@ -126,8 +126,25 @@ export interface ArtifactPersistenceOptions {
   }) => boolean | Promise<boolean>
   /** Abort an artifact fetch after this many ms. Default 30_000. */
   artifactFetchTimeoutMs?: number
-  /** Refuse an artifact body larger than this many bytes. Default 100 MiB. */
-  maxArtifactBytes?: number
+  /**
+   * Refuse an artifact body larger than this many bytes. Default 1 GiB.
+   *
+   * This is a bound on TRANSFER, not on memory: the URL path streams into the
+   * blob store and never buffers, so a 1 GiB artifact costs a streaming store
+   * (R2, S3, filesystem) flat memory. What the cap buys is a ceiling on what a
+   * broken or hostile origin can make you pull and store — `content-length` is
+   * advisory, so without it an artifact fetch is an unbounded transfer billed
+   * to you.
+   *
+   * Pass `false` to remove the ceiling entirely. That also removes the
+   * cap-enforcing `TransformStream` wrapper, so the fetched body reaches your
+   * store exactly as `fetch` produced it — on workerd that means it keeps its
+   * native declared length and `R2Bucket.put` can single-shot it with no hint,
+   * no multipart, and nothing buffered. Do that when you trust the origins you
+   * fetch from (your provider's CDN); keep the cap when `allowInputUrl` lets
+   * callers name the URL.
+   */
+  maxArtifactBytes?: number | false
   /**
    * `fetch` used to download artifact bytes. Defaults to the global. Inject to
    * route downloads through a proxy or an egress-restricted agent — the most
@@ -176,7 +193,15 @@ function generationScope(
 }
 
 const DEFAULT_ARTIFACT_FETCH_TIMEOUT_MS = 30_000
-const DEFAULT_MAX_ARTIFACT_BYTES = 100 * 1024 * 1024
+// 1 GiB, because generated video clips routinely run to a few hundred MB and
+// the old 100 MiB default silently failed them. The cap is a drain-time
+// counter, not a buffer: the URL path streams into the store, so raising it
+// costs a streaming store nothing in memory. It still earns its keep as the
+// only ceiling on what a runaway or hostile origin can make you transfer and
+// store (`content-length` is advisory, and on a compressed reply it measures
+// the compressed body). `maxArtifactBytes: false` removes it — and the wrapper
+// with it, which is the zero-copy path onto workerd + R2.
+const DEFAULT_MAX_ARTIFACT_BYTES = 1024 * 1024 * 1024
 
 export interface GenerationArtifactDescriptor {
   role: PersistedArtifactRole
@@ -758,8 +783,14 @@ function isBlockedInputHost(hostname: string): boolean {
 
 /**
  * Fail the stream once more than `maxBytes` have passed through, so an
- * unexpectedly huge artifact can't fill the blob store. Enforced during the
- * drain because `content-length` is advisory (and absent on chunked replies).
+ * unexpectedly huge artifact can't fill the blob store.
+ *
+ * Only used when the response does NOT already bound itself — a chunked reply,
+ * or a content-encoded one whose declared length describes the compressed
+ * bytes. When `content-length` describes the body the store will drain, HTTP
+ * framing is the bound and wrapping would only cost the caller the declared
+ * length: a `TransformStream`'s readable side carries none, which is what
+ * pushes a length-strict runtime (workerd + R2) onto a multipart upload.
  */
 function capBodySize(
   body: ReadableStream<Uint8Array>,
@@ -797,6 +828,12 @@ async function descriptorBody(
   | {
       body: BlobBody
       size: number
+      /**
+       * Exact byte length of a streamed body, when the origin declared one
+       * that survives decoding — forwarded to `BlobStore.put` as
+       * `BlobPutOptions.expectedLength`. Undefined when unknown.
+       */
+      expectedLength?: number
       mimeType: string
       sourceUrl?: string
     }
@@ -894,8 +931,19 @@ async function descriptorBody(
         `Failed to persist artifact from ${descriptor.url}: HTTP ${response.status}`,
       )
     }
-    const declaredLength = Number(response.headers.get('content-length'))
-    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    // `headers.get` returns null when the header is absent, and
+    // `Number(null) === 0` — parse only a present header, or a chunked reply
+    // would read as a declared length of 0 (harmless, but the early-reject
+    // below would silently never be reachable for it).
+    const contentLength = response.headers.get('content-length')
+    const declaredLength =
+      contentLength === null ? undefined : Number(contentLength)
+    if (
+      maxBytes !== false &&
+      declaredLength !== undefined &&
+      Number.isFinite(declaredLength) &&
+      declaredLength > maxBytes
+    ) {
       throw new Error(
         `Artifact at ${descriptor.url} exceeds maxArtifactBytes (${maxBytes}).`,
       )
@@ -904,20 +952,46 @@ async function descriptorBody(
       descriptor.mimeType ??
       response.headers.get('content-type') ??
       'application/octet-stream'
+    // A declared length is the DECODED body's length only when the response is
+    // not content-encoded: fetch transparently decompresses, so on a gzipped
+    // reply `content-length` measures the compressed bytes and the decoded
+    // stream can be arbitrarily longer. Only trust it when it provably
+    // describes what the store will drain.
+    const encoding = response.headers.get('content-encoding')
+    const decodedLengthIsKnown =
+      declaredLength !== undefined &&
+      Number.isFinite(declaredLength) &&
+      (encoding === null || encoding === 'identity')
+    const expectedLength = decodedLengthIsKnown ? declaredLength : undefined
     // Stream the body straight into the blob store instead of buffering the
     // whole artifact in memory. `size` is left 0 (unknown up front); the store
     // records the actual byte length as it drains the stream. Fall back to
     // buffering only when the response has no body to stream.
     if (response.body) {
       return {
-        body: capBodySize(response.body, maxBytes, descriptor.url),
+        // Wrap ONLY when the response does not already bound itself. A
+        // trustworthy `content-length` was checked against the cap above, and
+        // HTTP framing holds the origin to it — a body cannot exceed a length
+        // it declared — so the counter would add nothing and cost everything:
+        // it is a TransformStream, whose readable side has no declared length,
+        // and that missing length is precisely what breaks `R2Bucket.put`.
+        // Unwrapped, the runtime's own length rides along and R2 single-shots
+        // the stream. What still needs the counter: a chunked reply (no
+        // declared length at all) and a content-encoded one (declared length
+        // measures the compressed bytes, so the decoded stream is a
+        // decompression bomb waiting to happen).
+        body:
+          maxBytes === false || decodedLengthIsKnown
+            ? response.body
+            : capBodySize(response.body, maxBytes, descriptor.url),
         size: 0,
+        expectedLength,
         mimeType,
         sourceUrl: descriptor.url,
       }
     }
     const body = await response.arrayBuffer()
-    if (body.byteLength > maxBytes) {
+    if (maxBytes !== false && body.byteLength > maxBytes) {
       throw new Error(
         `Artifact at ${descriptor.url} exceeds maxArtifactBytes (${maxBytes}).`,
       )
@@ -983,7 +1057,7 @@ async function persistGenerationArtifacts(
     // Deliberately not persisted (an input URL with no `allowInputUrl` opt-in):
     // no blob, no record, no ref — the rest of the run is unaffected.
     if (!resolved) continue
-    const { body, size, mimeType, sourceUrl } = resolved
+    const { body, size, expectedLength, mimeType, sourceUrl } = resolved
     // Resolved before the blob write so `storageKey` can build a path from the
     // final filename (extensions, slugs) rather than guessing at one.
     const name =
@@ -1011,6 +1085,10 @@ async function persistGenerationArtifacts(
       }) ?? artifactBlobKey({ runId, artifactId })
     const stored = await persistence.stores.blobs.put(key, body, {
       contentType: mimeType,
+      // Exact decoded length when the origin declared one — lets a store
+      // single-shot the stream (e.g. R2 via FixedLengthStream) instead of
+      // buffering or going multipart. Absent when unknown.
+      ...(expectedLength !== undefined ? { expectedLength } : {}),
       customMetadata: {
         runId,
         threadId,
diff --git a/packages/ai-persistence/src/retrieve.ts b/packages/ai-persistence/src/retrieve.ts
index 9b5d8faa8..d87c1b683 100644
--- a/packages/ai-persistence/src/retrieve.ts
+++ b/packages/ai-persistence/src/retrieve.ts
@@ -1,4 +1,9 @@
-import type { AIPersistence, ArtifactRecord, BlobObject } from './types'
+import type {
+  AIPersistence,
+  ArtifactRecord,
+  BlobGetOptions,
+  BlobObject,
+} from './types'
 
 /**
  * The DEFAULT blob-store key a generation artifact's bytes are stored under,
@@ -44,10 +49,17 @@ export async function retrieveArtifact(
  * (resolved to its record first) or an already-loaded {@link ArtifactRecord}
  * (no second metadata lookup). Returns `null` when the artifact, its record, or
  * its blob is missing, or the stores are not configured.
+ *
+ * Pass `options.range` to read one slice — how a serve route answers a `Range`
+ * request with `206` + `Content-Range` instead of the whole file, which is what
+ * `<video>` seeking is built on. Resolve the range against `record.size` and
+ * reply `416` yourself when it does not fit; the store is handed satisfiable
+ * ranges only. The returned object's `range` reports the slice actually served.
  */
 export async function retrieveBlob(
   persistence: AIPersistence,
   artifact: string | ArtifactRecord,
+  options?: BlobGetOptions,
 ): Promise<BlobObject | null> {
   const record =
     typeof artifact === 'string'
@@ -57,6 +69,7 @@ export async function retrieveBlob(
 
   const blob = await persistence.stores.blobs?.get(
     resolveArtifactBlobKey(record),
+    options,
   )
   return blob ?? null
 }
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index a14c9abd9..73844d2d2 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -43,6 +43,28 @@ function required<TValue>(
   return value
 }
 
+/** Read a `BlobObject.body` to completion as one contiguous buffer. */
+async function drainStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const chunks: Array<Uint8Array> = []
+  let total = 0
+  const reader = stream.getReader()
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) break
+    chunks.push(value)
+    total += value.byteLength
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
 export interface PersistenceConformanceOptions {
   /**
    * Store keys this backend intentionally does not provide. Any store that is
@@ -723,6 +745,116 @@ export function runPersistenceConformance(
         )
       })
 
+      it('accepts a stream body with no declared length', async () => {
+        const store = resolveStore('blobs')
+        if (!store) return
+
+        // A TransformStream's readable side carries no declared length —
+        // exactly what a fetch-based producer hands the store when the origin
+        // chunks its reply (or its length can't be trusted). Byte bodies take
+        // a different branch in most stores and prove nothing about the
+        // streaming path, so this case is the one that keeps a store honest:
+        // it must drain the stream, not require a length up front.
+        const bytes = new Uint8Array(64 * 1024).map((_, i) => i % 251)
+        const source = required(new Response(bytes).body, 'response body')
+        const lengthless = source.pipeThrough(
+          new TransformStream<Uint8Array, Uint8Array>(),
+        )
+        const put = await store.put('blob/stream', lengthless, {
+          contentType: 'application/octet-stream',
+        })
+        expect(put.size).toBe(bytes.byteLength)
+
+        const object = required(await store.get('blob/stream'), 'blob/stream')
+        expect(new Uint8Array(await object.arrayBuffer())).toEqual(bytes)
+        expect(object.size).toBe(bytes.byteLength)
+      })
+
+      it('accepts expectedLength as an advisory hint for a stream body', async () => {
+        const store = resolveStore('blobs')
+        if (!store) return
+
+        // The real-world combination: a length-less stream PLUS the hint —
+        // which is what the artifact middleware sends when the origin declared
+        // a trustworthy `content-length`. The hint is advisory (a store may
+        // use it to pick an upload strategy); the drained bytes stay the
+        // record of truth, so `size` must still be the count of what arrived.
+        const bytes = new Uint8Array(9 * 1024).map((_, i) => i % 251)
+        const source = required(new Response(bytes).body, 'response body')
+        const lengthless = source.pipeThrough(
+          new TransformStream<Uint8Array, Uint8Array>(),
+        )
+        const put = await store.put('blob/stream-hint', lengthless, {
+          expectedLength: bytes.byteLength,
+        })
+        expect(put.size).toBe(bytes.byteLength)
+
+        const object = required(
+          await store.get('blob/stream-hint'),
+          'blob/stream-hint',
+        )
+        expect(new Uint8Array(await object.arrayBuffer())).toEqual(bytes)
+        expect(object.size).toBe(bytes.byteLength)
+      })
+
+      it('serves a byte range and reports the slice it served', async () => {
+        const store = resolveStore('blobs')
+        if (!store) return
+
+        // Range reads are what a serve route turns into `206` +
+        // `Content-Range` — the shape `<video>` seeking is built on. `size`
+        // keeps reporting the WHOLE object so the route can finish the
+        // `Content-Range` header from the same result.
+        const bytes = new Uint8Array(1024).map((_, i) => i % 251)
+        await store.put('blob/range', bytes)
+
+        const middle = required(
+          await store.get('blob/range', { range: { offset: 100, length: 50 } }),
+          'blob/range',
+        )
+        expect(new Uint8Array(await middle.arrayBuffer())).toEqual(
+          bytes.slice(100, 150),
+        )
+        expect(middle.size).toBe(bytes.byteLength)
+        expect(middle.range).toEqual({ offset: 100, length: 50 })
+
+        // No `length`: from the offset to the end.
+        const tail = required(
+          await store.get('blob/range', { range: { offset: 1000 } }),
+          'blob/range',
+        )
+        expect(new Uint8Array(await tail.arrayBuffer())).toEqual(
+          bytes.slice(1000),
+        )
+        expect(tail.range).toEqual({ offset: 1000, length: 24 })
+
+        // A `length` past the end is clamped, not an error: `bytes=1000-2000`
+        // against a 1 KiB object is a legal request that serves 24 bytes.
+        const clamped = required(
+          await store.get('blob/range', {
+            range: { offset: 1000, length: 1000 },
+          }),
+          'blob/range',
+        )
+        expect(clamped.range).toEqual({ offset: 1000, length: 24 })
+        expect((await clamped.arrayBuffer()).byteLength).toBe(24)
+
+        // The streaming accessor carries the same slice as arrayBuffer().
+        const streamed = required(
+          await store.get('blob/range', { range: { offset: 10, length: 5 } }),
+          'blob/range',
+        )
+        const body = streamed.body
+        if (body) {
+          expect(await drainStream(body)).toEqual(bytes.slice(10, 15))
+        }
+
+        // A whole-object read reports no `range` — a caller that sees one
+        // takes the bytes for a slice and would answer `206` for all of them.
+        const whole = required(await store.get('blob/range'), 'blob/range')
+        expect(whole.range).toBeUndefined()
+      })
+
       it('overwrites an existing key and deletes silently', async () => {
         const store = resolveStore('blobs')
         if (!store) return
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 9f1fc2ea6..9d1827740 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -505,11 +505,42 @@ export interface BlobRecord {
   updatedAt?: number
 }
 
+/**
+ * A byte range to read, in the shape an HTTP `Range` header resolves to.
+ *
+ * `offset` is measured from the start of the object and must be inside it;
+ * `length` defaults to "everything from `offset` to the end" and is clamped to
+ * the end when it overshoots. Suffix ranges (`bytes=-500`) are the caller's to
+ * resolve against the known size — a serve route has the size on the artifact
+ * record, and has to compare against it anyway to answer `416` before reading.
+ */
+export interface BlobRange {
+  offset: number
+  length?: number
+}
+
+/** Options for {@link BlobStore.get}. */
+export interface BlobGetOptions {
+  /**
+   * Read only this slice of the object. `body`, `arrayBuffer()` and `text()`
+   * then cover the slice, `size` still reports the WHOLE object, and `range`
+   * reports the slice actually served — the three numbers a `206` response
+   * needs (`Content-Range: bytes <offset>-<offset+length-1>/<size>`).
+   */
+  range?: BlobRange
+}
+
 /** A stored blob's metadata plus lazy accessors for its bytes. */
 export interface BlobObject extends BlobRecord {
   arrayBuffer: () => Promise<ArrayBuffer>
   text: () => Promise<string>
   body?: ReadableStream<Uint8Array>
+  /**
+   * The slice this object exposes, when a {@link BlobGetOptions.range} was
+   * requested and honoured: `offset` as asked, `length` as actually served
+   * (clamped to the end of the object). Absent on a whole-object read.
+   */
+  range?: { offset: number; length: number }
 }
 
 /**
@@ -527,6 +558,22 @@ export interface BlobListPage {
 export interface BlobPutOptions {
   contentType?: string
   customMetadata?: Record<string, string>
+  /**
+   * The exact byte length of `body`, when the producer knows it up front.
+   *
+   * Advisory, not a contract the store must honor: it exists so a store can
+   * pick an upload strategy knowingly instead of discovering the length by
+   * buffering. Most useful to an SDK that wants the length as a separate
+   * argument rather than reading it off the stream — S3's `PutObject`
+   * (`ContentLength`) is the archetype — and to a runtime that can re-attach
+   * one (workerd's `FixedLengthStream` ahead of `R2Bucket.put`).
+   *
+   * Only ever set when the length is exact — a wrong value is worse than none,
+   * since runtimes that enforce declared lengths fail the write. Absent means
+   * unknown, and a store must accept a length-less stream regardless:
+   * producers hand one over whenever the origin does not declare a length.
+   */
+  expectedLength?: number
 }
 
 export interface BlobListOptions {
@@ -543,8 +590,24 @@ export interface BlobStore {
     body: BlobBody,
     options?: BlobPutOptions,
   ) => Promise<BlobRecord>
-  /** Return the object at `key` (metadata + byte accessors), or `null`. */
-  get: (key: string) => Promise<BlobObject | null>
+  /**
+   * Return the object at `key` (metadata + byte accessors), or `null`.
+   *
+   * RANGE SEMANTICS: with `options.range`, return only that slice — the bytes
+   * a `206` response carries — and report it back as `range`. `size` still
+   * reports the whole object, so the caller can build `Content-Range` without
+   * a second `head`. The reported `length` is what was actually served: a
+   * requested `length` past the end clamps. An `offset` at or past the end is
+   * a caller error, not a store one — the size is on the artifact record, so a
+   * serve route answers `416` before ever asking the store.
+   *
+   * Range support is part of the contract for any store that holds bytes (the
+   * conformance testkit asserts it): serving a whole file where a slice was
+   * asked for is what makes `<video>` seeking, and Safari playback at all,
+   * fail. A reference-only backend that stores no bytes skips `blobs`
+   * entirely rather than half-implementing it.
+   */
+  get: (key: string, options?: BlobGetOptions) => Promise<BlobObject | null>
   /** Return only the metadata for `key`, or `null`. */
   head: (key: string) => Promise<BlobRecord | null>
   /** Remove the object at `key`. A no-op if absent. */
diff --git a/packages/ai-persistence/tests/blob-range.test.ts b/packages/ai-persistence/tests/blob-range.test.ts
new file mode 100644
index 000000000..80ac7b7a3
--- /dev/null
+++ b/packages/ai-persistence/tests/blob-range.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { parseRangeHeader, resolveBlobRange } from '../src/blob-range'
+
+describe('resolveBlobRange', () => {
+  it('resolves a slice and defaults length to the end of the object', () => {
+    expect(resolveBlobRange(1000, { offset: 100, length: 50 })).toEqual({
+      offset: 100,
+      length: 50,
+    })
+    expect(resolveBlobRange(1000, { offset: 900 })).toEqual({
+      offset: 900,
+      length: 100,
+    })
+  })
+
+  it('clamps a length that runs past the end', () => {
+    // `bytes=900-5000` against a 1000-byte object is a legal request that
+    // serves 100 bytes — not an error, and not 4101 bytes of promise.
+    expect(resolveBlobRange(1000, { offset: 900, length: 5000 })).toEqual({
+      offset: 900,
+      length: 100,
+    })
+  })
+
+  it('throws on an offset outside the object', () => {
+    // A store that returned an empty body here would serve a 206 claiming
+    // bytes it does not carry. The route is supposed to have answered 416.
+    expect(() => resolveBlobRange(1000, { offset: 1000 })).toThrow(RangeError)
+    expect(() => resolveBlobRange(1000, { offset: -1 })).toThrow(RangeError)
+    expect(() => resolveBlobRange(0, { offset: 0 })).toThrow(RangeError)
+    expect(() => resolveBlobRange(1000, { offset: 1.5 })).toThrow(RangeError)
+    expect(() => resolveBlobRange(1000, { offset: 0, length: -1 })).toThrow(
+      RangeError,
+    )
+  })
+})
+
+describe('parseRangeHeader', () => {
+  it('parses the three satisfiable forms', () => {
+    expect(parseRangeHeader('bytes=0-499', 1000)).toEqual({
+      offset: 0,
+      length: 500,
+    })
+    expect(parseRangeHeader('bytes=500-', 1000)).toEqual({ offset: 500 })
+    // A suffix range is the LAST n bytes — the form that is easy to read
+    // backwards, and reading it backwards serves the wrong bytes as a 206.
+    expect(parseRangeHeader('bytes=-500', 1000)).toEqual({ offset: 500 })
+    expect(parseRangeHeader('bytes=-5000', 1000)).toEqual({ offset: 0 })
+    expect(parseRangeHeader(' bytes=0-0 ', 1000)).toEqual({
+      offset: 0,
+      length: 1,
+    })
+  })
+
+  it('clamps an end past the last byte', () => {
+    expect(parseRangeHeader('bytes=900-5000', 1000)).toEqual({
+      offset: 900,
+      length: 100,
+    })
+  })
+
+  it('reports unsatisfiable ranges so the route can answer 416', () => {
+    expect(parseRangeHeader('bytes=1000-', 1000)).toBe('unsatisfiable')
+    expect(parseRangeHeader('bytes=1500-1600', 1000)).toBe('unsatisfiable')
+    expect(parseRangeHeader('bytes=500-499', 1000)).toBe('unsatisfiable')
+    expect(parseRangeHeader('bytes=-0', 1000)).toBe('unsatisfiable')
+  })
+
+  it('serves the whole object for an absent or unimplemented header', () => {
+    expect(parseRangeHeader(null, 1000)).toBeUndefined()
+    expect(parseRangeHeader(undefined, 1000)).toBeUndefined()
+    expect(parseRangeHeader('', 1000)).toBeUndefined()
+    expect(parseRangeHeader('bytes=-', 1000)).toBeUndefined()
+    // Multiple ranges and non-`bytes` units are legal to answer in full.
+    expect(parseRangeHeader('bytes=0-99,200-299', 1000)).toBeUndefined()
+    expect(parseRangeHeader('items=0-99', 1000)).toBeUndefined()
+    expect(parseRangeHeader('bytes 0-99', 1000)).toBeUndefined()
+  })
+})
diff --git a/packages/ai-persistence/tests/generation-artifacts.test.ts b/packages/ai-persistence/tests/generation-artifacts.test.ts
index bf5e45b49..1a93f7379 100644
--- a/packages/ai-persistence/tests/generation-artifacts.test.ts
+++ b/packages/ai-persistence/tests/generation-artifacts.test.ts
@@ -16,6 +16,9 @@ import type {
   GenerationArtifactExtractionInput,
   GenerationArtifactNameInput,
   AIPersistence,
+  BlobBody,
+  BlobPutOptions,
+  BlobStore,
 } from '../src'
 import type {
   AudioAdapter,
@@ -910,6 +913,75 @@ describe('artifact URL fetching', () => {
     return vi.fn(async () => new Response(body, { status: 200 }))
   }
 
+  /**
+   * A blob store standing in for workerd + R2: its "bucket" refuses a stream
+   * that carries no declared length, exactly as `R2Bucket.put` does
+   * (`TypeError: Provided readable stream must have a known length`). The store
+   * itself follows the recipe the Cloudflare skill documents — re-declare the
+   * length from `expectedLength` when the producer knows it, otherwise buffer
+   * the stream into parts and upload them — and records which path it took so
+   * a test can pin the hint to an observable effect.
+   */
+  function lengthStrictBlobStore() {
+    const uploads: Array<'single-shot' | 'multipart'> = []
+    // Stand-in for `FixedLengthStream`: the marker workerd checks for.
+    const declared = new WeakSet<ReadableStream<Uint8Array>>()
+    const bucket = memoryPersistence().stores.blobs
+
+    async function bucketPut(
+      key: string,
+      body: BlobBody,
+      options?: BlobPutOptions,
+    ) {
+      if (body instanceof ReadableStream && !declared.has(body)) {
+        throw new TypeError('Provided readable stream must have a known length')
+      }
+      return await bucket.put(key, body, options)
+    }
+
+    const store: BlobStore = {
+      async put(key, body, options) {
+        if (!(body instanceof ReadableStream)) {
+          return await bucketPut(key, body, options)
+        }
+        if (options?.expectedLength !== undefined) {
+          // `FixedLengthStream`: same bytes, now carrying a declared length.
+          const fixed = body.pipeThrough(
+            new TransformStream<Uint8Array, Uint8Array>(),
+          )
+          declared.add(fixed)
+          uploads.push('single-shot')
+          return await bucketPut(key, fixed, options)
+        }
+        // No length to declare: drain the stream into parts instead. Real
+        // multipart uploads them one at a time; buffering here is enough to
+        // prove the store never hands the bucket a length-less stream.
+        const reader = body.getReader()
+        const parts: Array<Uint8Array> = []
+        let total = 0
+        for (;;) {
+          const { value, done } = await reader.read()
+          if (done) break
+          parts.push(value)
+          total += value.byteLength
+        }
+        const bytes = new Uint8Array(total)
+        let offset = 0
+        for (const part of parts) {
+          bytes.set(part, offset)
+          offset += part.byteLength
+        }
+        uploads.push('multipart')
+        return await bucketPut(key, bytes, options)
+      },
+      get: (key, options) => bucket.get(key, options),
+      head: (key) => bucket.head(key),
+      delete: (key) => bucket.delete(key),
+      list: (options) => bucket.list(options),
+    }
+    return { store, uploads }
+  }
+
   /** A prompt referencing media by URL — the caller-controlled input case. */
   function urlPrompt(url: string) {
     return [
@@ -1140,6 +1212,317 @@ describe('artifact URL fetching', () => {
     expect(job?.artifacts).toBeUndefined()
   })
 
+  it('forwards a trustworthy content-length to the blob store as expectedLength', async () => {
+    const persistence = memoryPersistence()
+    const artifactFetch = vi.fn(
+      async () =>
+        new Response('generated-bytes', {
+          status: 200,
+          headers: { 'content-length': '15' },
+        }),
+    )
+    const putSpy = vi.spyOn(persistence.stores.blobs!, 'put')
+
+    await generateImage({
+      adapter: urlImageAdapter('https://cdn.example.com/out.png'),
+      prompt: 'make an image',
+      threadId: 'thread-hint',
+      runId: 'run-hint',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          threadId: 'thread-hint',
+          artifactFetch,
+        }),
+      ],
+    })
+
+    expect(putSpy).toHaveBeenCalled()
+    expect(putSpy.mock.calls[0]?.[2]?.expectedLength).toBe(15)
+  })
+
+  it('omits expectedLength when the origin declares no length', async () => {
+    const persistence = memoryPersistence()
+    // A chunked reply declares no length — and `Number(null) === 0` must not
+    // read that as a declared length of 0.
+    const artifactFetch = vi.fn(
+      async () => new Response('generated-bytes', { status: 200 }),
+    )
+    const putSpy = vi.spyOn(persistence.stores.blobs!, 'put')
+
+    await generateImage({
+      adapter: urlImageAdapter('https://cdn.example.com/out.png'),
+      prompt: 'make an image',
+      threadId: 'thread-no-length',
+      runId: 'run-no-length',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          threadId: 'thread-no-length',
+          artifactFetch,
+        }),
+      ],
+    })
+
+    expect(putSpy).toHaveBeenCalled()
+    expect(putSpy.mock.calls[0]?.[2]?.expectedLength).toBeUndefined()
+  })
+
+  it('omits expectedLength when the response is content-encoded', async () => {
+    const persistence = memoryPersistence()
+    // fetch transparently decompresses: a gzipped reply's content-length is
+    // the COMPRESSED size, so it cannot describe the decoded stream the store
+    // drains. Forwarding it would be worse than no hint.
+    const artifactFetch = vi.fn(
+      async () =>
+        new Response('generated-bytes', {
+          status: 200,
+          headers: { 'content-length': '15', 'content-encoding': 'gzip' },
+        }),
+    )
+    const putSpy = vi.spyOn(persistence.stores.blobs!, 'put')
+
+    await generateImage({
+      adapter: urlImageAdapter('https://cdn.example.com/out.png'),
+      prompt: 'make an image',
+      threadId: 'thread-encoded',
+      runId: 'run-encoded',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          threadId: 'thread-encoded',
+          artifactFetch,
+        }),
+      ],
+    })
+
+    expect(putSpy).toHaveBeenCalled()
+    expect(putSpy.mock.calls[0]?.[2]?.expectedLength).toBeUndefined()
+  })
+
+  it('defaults maxArtifactBytes to 1 GiB', async () => {
+    const persistence = memoryPersistence()
+    // Declared above the old 100 MiB default but below 1 GiB: must persist.
+    // Nothing buffers a byte of it — the cap is a drain-time counter and the
+    // declared length is only read from the header.
+    const artifactFetch = vi.fn(
+      async () =>
+        new Response('ok', {
+          status: 200,
+          headers: { 'content-length': String(150 * 1024 * 1024) },
+        }),
+    )
+    const result = await generateImage({
+      adapter: urlImageAdapter('https://cdn.example.com/big.png'),
+      prompt: 'make an image',
+      threadId: 'thread-default-cap',
+      runId: 'run-default-cap',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          threadId: 'thread-default-cap',
+          artifactFetch,
+        }),
+      ],
+    })
+    expect(result.artifacts?.some((a) => a.role === 'output')).toBe(true)
+
+    // Declared above 1 GiB: the early-reject fires before a byte is read.
+    const tooBigFetch = vi.fn(
+      async () =>
+        new Response('ok', {
+          status: 200,
+          headers: { 'content-length': String(1025 * 1024 * 1024) },
+        }),
+    )
+    await expect(
+      generateImage({
+        adapter: urlImageAdapter('https://cdn.example.com/huge.png'),
+        prompt: 'make an image',
+        threadId: 'thread-default-cap',
+        runId: 'run-too-big',
+        middleware: [
+          withGenerationPersistence(persistence, {
+            threadId: 'thread-default-cap',
+            artifactFetch: tooBigFetch,
+          }),
+        ],
+      }),
+    ).rejects.toThrow(/exceeds maxArtifactBytes/)
+  })
+
+  const wrapCases: Array<{
+    name: string
+    headers: Record<string, string>
+    wrapped: boolean
+  }> = [
+    {
+      name: 'trustworthy content-length: passed through untouched',
+      headers: { 'content-length': '15' },
+      wrapped: false,
+    },
+    {
+      name: 'chunked reply: wrapped, nothing else bounds it',
+      headers: {},
+      wrapped: true,
+    },
+    {
+      name: 'content-encoded: wrapped, the declared length is the compressed size',
+      headers: { 'content-length': '15', 'content-encoding': 'gzip' },
+      wrapped: true,
+    },
+  ]
+
+  it.each(wrapCases)(
+    'caps by wrapping the body only when it has to ($name)',
+    async ({ headers, wrapped }) => {
+      // The wrapper is a TransformStream, and a transform's readable side has no
+      // declared length — the whole of #1030. So it is applied only where it is
+      // load-bearing: when `content-length` describes what the store will drain,
+      // HTTP framing already holds the origin to it and the body goes through
+      // untouched, length intact, ready for a single-shot `R2Bucket.put`.
+      const persistence = memoryPersistence()
+      const response = new Response('generated-bytes', { status: 200, headers })
+      const responseBody = response.body
+      const putSpy = vi.spyOn(persistence.stores.blobs!, 'put')
+
+      const result = await generateImage({
+        adapter: urlImageAdapter('https://cdn.example.com/out.png'),
+        prompt: 'make an image',
+        threadId: 'thread-wrap',
+        runId: 'run-wrap',
+        middleware: [
+          withGenerationPersistence(persistence, {
+            threadId: 'thread-wrap',
+            artifactFetch: vi.fn(async () => response),
+          }),
+        ],
+      })
+
+      const body = putSpy.mock.calls[0]?.[1]
+      if (wrapped) {
+        expect(body).not.toBe(responseBody)
+      } else {
+        expect(body).toBe(responseBody)
+      }
+      // Wrapped or not, the bytes land intact.
+      const ref = result.artifacts?.find((a) => a.role === 'output')
+      await expect(
+        (await retrieveBlob(persistence, ref!.artifactId))?.text(),
+      ).resolves.toBe('generated-bytes')
+    },
+  )
+
+  it('still caps a chunked body during the drain', async () => {
+    const persistence = memoryPersistence()
+    // No declared length, so nothing bounds the transfer but the counter —
+    // this is the case the wrapper exists for.
+    const artifactFetch = vi.fn(
+      async () => new Response('generated-bytes', { status: 200 }),
+    )
+
+    await expect(
+      generateImage({
+        adapter: urlImageAdapter('https://cdn.example.com/out.png'),
+        prompt: 'make an image',
+        threadId: 'thread-drain-cap',
+        runId: 'run-drain-cap',
+        middleware: [
+          withGenerationPersistence(persistence, {
+            threadId: 'thread-drain-cap',
+            artifactFetch,
+            maxArtifactBytes: 4,
+          }),
+        ],
+      }),
+    ).rejects.toThrow(/exceeds maxArtifactBytes/)
+  })
+
+  it('maxArtifactBytes: false hands the store the untouched fetch body', async () => {
+    const persistence = memoryPersistence()
+    // The zero-copy path for workerd + R2: with no cap there is no
+    // TransformStream wrapper, so the store receives the very stream `fetch`
+    // produced — which on workerd still carries its own declared length, so
+    // `R2Bucket.put` single-shots it with no hint and no multipart. Identity,
+    // not equality, is the assertion that pins that down.
+    const response = new Response('generated-bytes', {
+      status: 200,
+      // Far above the 1 GiB default: an uncapped fetch must not consult it.
+      headers: { 'content-length': String(8 * 1024 * 1024 * 1024) },
+    })
+    const responseBody = response.body
+    const artifactFetch = vi.fn(async () => response)
+    const putSpy = vi.spyOn(persistence.stores.blobs!, 'put')
+
+    const result = await generateImage({
+      adapter: urlImageAdapter('https://cdn.example.com/huge.mp4'),
+      prompt: 'make a video',
+      threadId: 'thread-uncapped',
+      runId: 'run-uncapped',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          threadId: 'thread-uncapped',
+          artifactFetch,
+          maxArtifactBytes: false,
+        }),
+      ],
+    })
+
+    expect(putSpy.mock.calls[0]?.[1]).toBe(responseBody)
+    const ref = result.artifacts?.find((a) => a.role === 'output')
+    await expect(
+      (await retrieveBlob(persistence, ref!.artifactId))?.text(),
+    ).resolves.toBe('generated-bytes')
+  })
+
+  it.each([
+    { name: 'declared length: single-shot', contentLength: '15' as const },
+    { name: 'no declared length: multipart', contentLength: undefined },
+  ])(
+    'persists a URL artifact into a length-strict store ($name)',
+    async ({ contentLength }) => {
+      // The #1030 regression, end to end: workerd's `R2Bucket.put` rejects a
+      // stream with no declared length, and the cap-enforcing wrapper strips
+      // the length off every URL-fetched body. `lengthStrictBlobStore` is that
+      // rule in miniature, so this fails the moment the middleware stops
+      // forwarding `expectedLength` — or a store follows the old "pass the
+      // body straight through" recipe.
+      const strict = lengthStrictBlobStore()
+      const persistence = composePersistence(memoryPersistence(), {
+        overrides: { blobs: strict.store },
+      })
+      const artifactFetch = vi.fn(
+        async () =>
+          new Response('generated-bytes', {
+            status: 200,
+            ...(contentLength
+              ? { headers: { 'content-length': contentLength } }
+              : {}),
+          }),
+      )
+
+      const result = await generateImage({
+        adapter: urlImageAdapter('https://cdn.example.com/out.png'),
+        prompt: 'make an image',
+        threadId: 'thread-strict',
+        runId: 'run-strict',
+        middleware: [
+          withGenerationPersistence(persistence, {
+            threadId: 'thread-strict',
+            artifactFetch,
+          }),
+        ],
+      })
+
+      const ref = result.artifacts?.find((a) => a.role === 'output')
+      expect(ref?.size).toBe(15)
+      await expect(
+        (await retrieveBlob(persistence, ref!.artifactId))?.text(),
+      ).resolves.toBe('generated-bytes')
+      // Which upload path the store took follows from the hint, and the hint
+      // follows from the origin declaring a length.
+      expect(strict.uploads).toEqual([
+        contentLength ? 'single-shot' : 'multipart',
+      ])
+    },
+  )
+
   it('fails the run when the provider CDN 404s', async () => {
     const persistence = memoryPersistence()
     const artifactFetch = vi.fn(
diff --git a/packages/ai/skills/ai-core/media-generation/SKILL.md b/packages/ai/skills/ai-core/media-generation/SKILL.md
index 6bc6b86f1..f66b4812e 100644
--- a/packages/ai/skills/ai-core/media-generation/SKILL.md
+++ b/packages/ai/skills/ai-core/media-generation/SKILL.md
@@ -620,6 +620,13 @@ export async function GET(req: Request) {
 }
 ```
 
+That route is enough for images. **Video needs `Range`**: seeking a `<video>`
+is built on `206` / `Content-Range`, and Safari refuses to play a source that
+ignores `Range` at all. Resolve the header against `record.size` (`416` when it
+does not fit), pass `retrieveBlob(persistence, record, { range })`, and answer
+`206` from the returned `blob.range` plus `accept-ranges: bytes`. The full
+route is in the persistence docs under **Serve video: honour `Range`**.
+
 On the client, `persistence` is **boolean only**: `persistence: true` hydrates
 the last generation for the thread on mount, via the connection's
 `hydrateGeneration` handler backed by a `reconstructGeneration` GET route. There

From f8b4ca6ebebf5d94d6d87fa57a2b78ba013a5601 Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Fri, 31 Jul 2026 19:42:40 +1000
Subject: [PATCH 2/3] fix(ai-persistence): ignore an invalid byte-range-spec
 instead of 416ing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RFC 9110 §14.1.1: `bytes=100-50` (last-byte-pos < first-byte-pos) is an
invalid spec, not an unsatisfiable one, so it must be ignored and the whole
representation served. `parseRangeHeader` returned 'unsatisfiable', which
would have failed a request that is supposed to succeed. Checked before
satisfiability so the object's size cannot turn an ignorable spec into a 416.
---
 packages/ai-persistence/src/blob-range.ts     | 19 +++++++++++++------
 .../ai-persistence/tests/blob-range.test.ts   | 12 +++++++++++-
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/packages/ai-persistence/src/blob-range.ts b/packages/ai-persistence/src/blob-range.ts
index e0014ab27..20bad8bfd 100644
--- a/packages/ai-persistence/src/blob-range.ts
+++ b/packages/ai-persistence/src/blob-range.ts
@@ -46,9 +46,11 @@ export function resolveBlobRange(
  * Returns the {@link BlobRange} to pass to `retrieveBlob` / `BlobStore.get`,
  * `'unsatisfiable'` when the request names bytes the object does not have — answer
  * `416`, whose `content-range` is the literal `bytes` `*` then a slash then the
- * size — or `undefined` when there is no range to honour: an absent header, and
- * equally the forms this does not implement (multiple ranges, units other than
- * `bytes`), which a server is always free to answer in full.
+ * size — or `undefined` when there is no range to honour and the whole object
+ * should be served: an absent header, an invalid byte-range-spec (`bytes=100-50`,
+ * which RFC 9110 says to ignore rather than reject), and the forms this does not
+ * implement (multiple ranges, units other than `bytes`), which a server is
+ * always free to answer in full.
  *
  * @example
  * ```ts
@@ -81,10 +83,15 @@ export function parseRangeHeader(
   }
 
   const start = Number(rawStart)
+  const end = rawEnd === '' ? undefined : Number(rawEnd)
+  // `bytes=100-50` is an INVALID byte-range-spec, not an unsatisfiable one
+  // (RFC 9110 §14.1.1). An invalid spec is ignored and the whole
+  // representation is served — answering 416 would fail a request that is
+  // supposed to succeed. Checked before satisfiability so the size cannot turn
+  // an ignorable spec into a 416.
+  if (end !== undefined && end < start) return undefined
   if (start >= size) return 'unsatisfiable'
-  if (rawEnd === '') return { offset: start }
-  const end = Number(rawEnd)
-  if (end < start) return 'unsatisfiable'
+  if (end === undefined) return { offset: start }
   // `end` is inclusive, and past the end of the object it simply clamps.
   return { offset: start, length: Math.min(end, size - 1) - start + 1 }
 }
diff --git a/packages/ai-persistence/tests/blob-range.test.ts b/packages/ai-persistence/tests/blob-range.test.ts
index 80ac7b7a3..996c4e974 100644
--- a/packages/ai-persistence/tests/blob-range.test.ts
+++ b/packages/ai-persistence/tests/blob-range.test.ts
@@ -62,10 +62,20 @@ describe('parseRangeHeader', () => {
   it('reports unsatisfiable ranges so the route can answer 416', () => {
     expect(parseRangeHeader('bytes=1000-', 1000)).toBe('unsatisfiable')
     expect(parseRangeHeader('bytes=1500-1600', 1000)).toBe('unsatisfiable')
-    expect(parseRangeHeader('bytes=500-499', 1000)).toBe('unsatisfiable')
     expect(parseRangeHeader('bytes=-0', 1000)).toBe('unsatisfiable')
   })
 
+  it('ignores an invalid byte-range-spec rather than rejecting it', () => {
+    // RFC 9110 §14.1.1: `last-byte-pos < first-byte-pos` is INVALID, not
+    // unsatisfiable, and an invalid spec is ignored — the request still
+    // succeeds with the whole representation. A 416 here would fail a request
+    // that is supposed to work.
+    expect(parseRangeHeader('bytes=500-499', 1000)).toBeUndefined()
+    // Invalid wins over unsatisfiable: the size must not turn an ignorable
+    // spec into a 416.
+    expect(parseRangeHeader('bytes=5000-499', 1000)).toBeUndefined()
+  })
+
   it('serves the whole object for an absent or unimplemented header', () => {
     expect(parseRangeHeader(null, 1000)).toBeUndefined()
     expect(parseRangeHeader(undefined, 1000)).toBeUndefined()

From 5e3a7476e3b55de80ffa6ccacb9d5aff782dcaf4 Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Fri, 31 Jul 2026 19:50:05 +1000
Subject: [PATCH 3/3] =?UTF-8?q?fix(ai-persistence):=20address=20review=20?=
 =?UTF-8?q?=E2=80=94=20zero-byte=20ranges,=20slice-at-storage,=20R2=20reci?=
 =?UTF-8?q?pe?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `parseRangeHeader`: any range against a zero-byte object is unsatisfiable.
  The suffix branch resolved `bytes=-1` on an empty artifact to `{ offset: 0 }`,
  which then threw a RangeError out of the store instead of answering 416.
- SQLite store (example + docs reference impl): a ranged read ran
  `SELECT *` and then `substr`, so it loaded the whole object AND the slice.
  Metadata now comes from a projection without `body`; `head` too.
- R2 recipe: parts are cut on an exact boundary with the remainder carried,
  since R2 requires equal-sized parts, and chunks are joined once per part
  rather than re-copied per chunk. Single-shot is capped at 5 GiB, multipart
  fails fast at the 10,000-part ceiling.
- R2 ranged get: `head` and `get` are tied together with
  `onlyIf: { etagMatches }`, so an overwrite between them cannot pair one
  version's Content-Range with another's bytes; a ranged head miss returns
  null instead of falling through to a whole-object read.
- Drop the "no limit" claims: `maxArtifactBytes: false` removes the
  application ceiling, not the backend's.
---
 .changeset/persistence-stream-length-hint.md  |   2 +-
 docs/persistence/build-your-own-adapter.md    |  44 +++--
 docs/persistence/keep-generated-files.md      |   6 +-
 .../src/lib/sqlite-persistence.ts             |  49 ++++--
 .../build-cloudflare-artifact-store/SKILL.md  | 158 +++++++++++++-----
 packages/ai-persistence/src/blob-range.ts     |   6 +-
 .../ai-persistence/tests/blob-range.test.ts   |   5 +
 7 files changed, 190 insertions(+), 80 deletions(-)

diff --git a/.changeset/persistence-stream-length-hint.md b/.changeset/persistence-stream-length-hint.md
index 36ea9aea2..4ac22cfb6 100644
--- a/.changeset/persistence-stream-length-hint.md
+++ b/.changeset/persistence-stream-length-hint.md
@@ -2,7 +2,7 @@
 '@tanstack/ai-persistence': minor
 ---
 
-Streamed artifact bodies can now be persisted to length-strict blob stores (Cloudflare R2), `maxArtifactBytes` can be turned off for a zero-copy path onto R2, and `BlobStore.get` can serve byte ranges.
+Streamed artifact bodies can now be persisted to length-strict blob stores (Cloudflare R2), `maxArtifactBytes` can be turned off, and `BlobStore.get` can serve byte ranges.
 
 **The bug.** URL-fetched artifacts arrived at `BlobStore.put` as a `TransformStream`-wrapped body — the wrapper that enforces `maxArtifactBytes` as the body drains. A transform's readable side carries no declared length, so runtimes that require one for a single-shot upload (workerd's `R2Bucket.put`) rejected every URL-sourced artifact with `TypeError: Provided readable stream must have a known length`. Byte bodies never hit this, which is why the old conformance suite (byte bodies only) and any store that buffers were unaffected.
 
diff --git a/docs/persistence/build-your-own-adapter.md b/docs/persistence/build-your-own-adapter.md
index 6f8f22456..c71fbf89a 100644
--- a/docs/persistence/build-your-own-adapter.md
+++ b/docs/persistence/build-your-own-adapter.md
@@ -979,6 +979,16 @@ function createBlobStore(db: DatabaseSync) {
   )
   const selectCreated = db.prepare('SELECT created_at FROM blobs WHERE key = ?')
   const selectOne = db.prepare('SELECT * FROM blobs WHERE key = ?')
+  // Metadata without the bytes, and the bounded slice: a ranged read must not
+  // load the whole object to hand back a piece of it.
+  const selectMeta = db.prepare(
+    `SELECT key, size, etag, content_type, custom_metadata_json,
+            created_at, updated_at
+       FROM blobs WHERE key = ?`,
+  )
+  const selectSlice = db.prepare(
+    'SELECT substr(bytes, ?, ?) AS bytes FROM blobs WHERE key = ?',
+  )
   return defineBlobStore({
     async put(key, body, options) {
       const bytes = await toBytes(body)
@@ -1012,23 +1022,29 @@ function createBlobStore(db: DatabaseSync) {
       }
     },
     async get(key, options) {
-      const row = selectOne.get(key)
-      if (!row) return null
+      if (!options?.range) {
+        const row = selectOne.get(key)
+        if (!row) return null
+        const bytes =
+          row.bytes instanceof Uint8Array ? row.bytes : new Uint8Array()
+        return blobObject(mapBlobRecord(row), bytes)
+      }
+      // Metadata first, WITHOUT the bytes, so the clamp costs no I/O...
+      const meta = selectMeta.get(key)
+      if (!meta) return null
+      const served = resolveBlobRange(Number(meta.size), options.range)
+      // ...then let SQLite cut the slice (`substr` is 1-based and byte-wise
+      // over a BLOB). Reading the row whole and slicing in JS would load the
+      // entire object on every video seek — the cost ranges exist to avoid.
+      const slice = selectSlice.get(served.offset + 1, served.length, key)
+      if (!slice) return null
       const bytes =
-        row.bytes instanceof Uint8Array ? row.bytes : new Uint8Array()
-      if (!options?.range) return blobObject(mapBlobRecord(row), bytes)
-      // Clamp against the real size, then serve just that slice — a video
-      // seek asks for a few hundred KB of a file you should not re-read whole.
-      // (Push the slice into SQL with `substr(bytes, ?, ?)` for real sizes.)
-      const served = resolveBlobRange(bytes.byteLength, options.range)
-      return blobObject(
-        mapBlobRecord(row),
-        bytes.subarray(served.offset, served.offset + served.length),
-        served,
-      )
+        slice.bytes instanceof Uint8Array ? slice.bytes : new Uint8Array()
+      return blobObject(mapBlobRecord(meta), bytes, served)
     },
     async head(key) {
-      const row = selectOne.get(key)
+      // Metadata only: never pull the bytes to answer a question about them.
+      const row = selectMeta.get(key)
       return row ? mapBlobRecord(row) : null
     },
     async delete(key) {
diff --git a/docs/persistence/keep-generated-files.md b/docs/persistence/keep-generated-files.md
index 6323d7241..0f6cd786a 100644
--- a/docs/persistence/keep-generated-files.md
+++ b/docs/persistence/keep-generated-files.md
@@ -350,8 +350,10 @@ const uncappedOptions = withGenerationPersistence(persistence, {
 ```
 
 Reach for that when you trust the origins you fetch from and would rather have
-no ceiling than a generous one. Keep the cap when `allowInputUrl` lets callers
-name the URL — there the origin is by definition not one you control.
+no ceiling than a generous one. Your storage backend's own limits still apply —
+R2, for instance, caps a single-shot upload at 5 GiB and a multipart one at
+10,000 parts. Keep the cap when `allowInputUrl` lets callers name the URL:
+there the origin is by definition not one you control.
 
 ## Wire the durable URL through to the client
 
diff --git a/examples/ts-react-chat/src/lib/sqlite-persistence.ts b/examples/ts-react-chat/src/lib/sqlite-persistence.ts
index b112a2f23..635790d7a 100644
--- a/examples/ts-react-chat/src/lib/sqlite-persistence.ts
+++ b/examples/ts-react-chat/src/lib/sqlite-persistence.ts
@@ -194,9 +194,9 @@ interface ArtifactRow {
   source_url: string | null
   created_at: number
 }
-interface BlobRow {
+/** A `blobs` row without the bytes — what a metadata read selects. */
+interface BlobMetaRow {
   key: string
-  body: Uint8Array
   size: number
   etag: string
   content_type: string | null
@@ -204,6 +204,9 @@ interface BlobRow {
   created_at: number
   updated_at: number
 }
+interface BlobRow extends BlobMetaRow {
+  body: Uint8Array
+}
 
 function parseJson<T>(text: string): T {
   return JSON.parse(text) as T
@@ -707,7 +710,7 @@ async function bytesFromBlobBody(body: BlobBody): Promise<Uint8Array> {
   return bytes
 }
 
-function mapBlobRecord(row: BlobRow): BlobRecord {
+function mapBlobRecord(row: BlobMetaRow): BlobRecord {
   return {
     key: row.key,
     size: row.size,
@@ -761,6 +764,14 @@ function createBlobStore(db: DatabaseSync) {
        updated_at = excluded.updated_at`,
   )
   const selectStmt = db.prepare('SELECT * FROM blobs WHERE key = ?')
+  // Everything EXCEPT `body`. A ranged read needs the metadata to clamp
+  // against, and `SELECT *` would materialize the whole object just to hand
+  // back a slice of it — the cost a range request exists to avoid.
+  const selectMetaStmt = db.prepare(
+    `SELECT key, size, etag, content_type, custom_metadata_json,
+            created_at, updated_at
+       FROM blobs WHERE key = ?`,
+  )
   const rangeStmt = db.prepare(
     'SELECT substr(body, ?, ?) AS body FROM blobs WHERE key = ?',
   )
@@ -810,29 +821,35 @@ function createBlobStore(db: DatabaseSync) {
       return record
     },
     get(key, options) {
-      const row = selectStmt.get(key) as BlobRow | undefined
-      if (!row) return Promise.resolve(null)
       if (!options?.range) {
-        return Promise.resolve(blobObject(mapBlobRecord(row), row.body))
+        const row = selectStmt.get(key) as BlobRow | undefined
+        return Promise.resolve(
+          row ? blobObject(mapBlobRecord(row), row.body) : null,
+        )
       }
-      // Clamp the request to the object the way every byte-storing backend
-      // must — `resolveBlobRange` is the shared implementation, and it throws
-      // on an offset past the end so an unsatisfiable range can't be served as
-      // a 206. A route answers 416 from `record.size` before getting here.
-      const served = resolveBlobRange(row.size, options.range)
-      // Slice in SQLite (1-based, byte-wise over a BLOB) rather than loading
-      // the whole object to hand back a few bytes of it — the difference
-      // between seeking a video and reading it end to end.
+      // Metadata WITHOUT the bytes, then the slice: clamp the request to the
+      // object the way every byte-storing backend must. `resolveBlobRange` is
+      // the shared implementation, and it throws on an offset past the end so
+      // an unsatisfiable range can't be served as a 206 — a route answers 416
+      // from `record.size` before getting here.
+      const meta = selectMetaStmt.get(key) as BlobMetaRow | undefined
+      if (!meta) return Promise.resolve(null)
+      const served = resolveBlobRange(meta.size, options.range)
+      // Slice in SQLite (1-based, byte-wise over a BLOB), so seeking inside a
+      // video reads a few hundred KB and not the whole clip. Reading the row
+      // with `SELECT *` first would have loaded it anyway, which is the whole
+      // cost a range request exists to avoid.
       const sliced = rangeStmt.get(served.offset + 1, served.length, key) as
         | Pick<BlobRow, 'body'>
         | undefined
       if (!sliced) return Promise.resolve(null)
       return Promise.resolve(
-        blobObject(mapBlobRecord(row), sliced.body, served),
+        blobObject(mapBlobRecord(meta), sliced.body, served),
       )
     },
     head(key) {
-      const row = selectStmt.get(key) as BlobRow | undefined
+      // Metadata only: never pull the bytes for a question about the object.
+      const row = selectMetaStmt.get(key) as BlobMetaRow | undefined
       return Promise.resolve(row ? mapBlobRecord(row) : null)
     },
     delete(key) {
diff --git a/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md b/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md
index 1e01ab7f6..9174ad19a 100644
--- a/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md
+++ b/packages/ai-persistence/skills/ai-persistence/build-cloudflare-artifact-store/SKILL.md
@@ -57,10 +57,9 @@ string | Blob`. The non-stream shapes flow straight into `R2Bucket.put`
 unchanged — but a `ReadableStream` body does **not**, in the general case:
 workerd's `put` requires a stream with a known length (a `Response` body or the
 readable half of a `FixedLengthStream`), and the artifact middleware hands you a
-`TransformStream`-wrapped body whenever it fetched the bytes from a provider
-URL — i.e. essentially every generated artifact. Passing that stream to
-`bucket.put` throws `TypeError: Provided readable stream must have a known
-length`.
+`TransformStream`-wrapped body whenever it had to cap a fetched body as it
+drains. Passing that stream to `bucket.put` throws `TypeError: Provided readable
+stream must have a known length`.
 
 **When does that actually happen?** The wrapper only exists to enforce
 `maxArtifactBytes` during the drain, so the middleware applies it only when
@@ -83,8 +82,10 @@ covered.
 `withGenerationPersistence(persistence, { maxArtifactBytes: false })` drops the
 ceiling and the wrapper altogether, so even a chunked reply arrives untouched.
 It buys nothing extra for R2 (a chunked body has no length to preserve), so
-choose it on its own merits: no limit on what an origin can stream into your
-bucket. Keep the cap when `allowInputUrl` lets callers name the URL.
+choose it on its own merits: no _application_ limit on what an origin can
+stream into your bucket. R2's own limits still apply — 5 GiB per single-shot
+put, and 10,000 multipart parts (~80 GiB at the 8 MiB part size below). Keep
+the cap when `allowInputUrl` lets callers name the URL.
 
 `BlobPutOptions` is
 `{ contentType?, customMetadata?, expectedLength? }`; `BlobGetOptions` is
@@ -105,30 +106,64 @@ object plus the mapped metadata.
 import { defineBlobStore, resolveBlobRange } from '@tanstack/ai-persistence'
 import type { BlobObject, BlobRecord } from '@tanstack/ai-persistence'
 
-// R2 multipart requires every part but the last to be ≥ 5 MiB. Buffering one
-// part at a time keeps peak memory flat regardless of artifact size.
+// R2 multipart parts must be ≥ 5 MiB and — except for the last — all exactly
+// the SAME size, so a part reader has to cut on an exact boundary and carry the
+// remainder. 8 MiB × the 10,000-part ceiling puts the multipart path's limit at
+// ~80 GiB; raise this for larger objects, and check R2's current object-size
+// limits before promising more.
 const MULTIPART_PART_SIZE = 8 * 1024 * 1024
 
-/** Drain `reader` until `limit` bytes accumulate or the stream ends. */
-async function readUpTo(
+/**
+ * Cut exactly `limit` bytes off the stream (fewer only at EOF), carrying any
+ * overshoot into the next part.
+ *
+ * `carry` is the leftover from the previous call. Chunks are collected by
+ * reference and copied once per part: growing a `Uint8Array` chunk-by-chunk
+ * instead would re-copy the whole part on every read — quadratic work for a
+ * part built from hundreds of small chunks.
+ */
+async function readPart(
   reader: ReadableStreamDefaultReader<Uint8Array>,
   limit: number,
-): Promise<{ bytes: Uint8Array; eof: boolean }> {
-  let bytes = new Uint8Array(0)
-  for (;;) {
-    if (bytes.byteLength >= limit) return { bytes, eof: false }
+  carry: Uint8Array,
+): Promise<{ bytes: Uint8Array; carry: Uint8Array; eof: boolean }> {
+  const chunks: Array<Uint8Array> = carry.byteLength > 0 ? [carry] : []
+  let total = carry.byteLength
+  let eof = false
+  while (total < limit) {
     const { value, done } = await reader.read()
-    if (done) return { bytes, eof: true }
-    const merged = new Uint8Array(bytes.byteLength + value.byteLength)
-    merged.set(bytes)
-    merged.set(value, bytes.byteLength)
-    bytes = merged
+    if (done) {
+      eof = true
+      break
+    }
+    chunks.push(value)
+    total += value.byteLength
   }
+  const joined = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    joined.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  // Equal-sized parts: hand back exactly `limit` and keep the rest for next
+  // time. At EOF the last part is whatever is left, which R2 allows.
+  if (!eof && total > limit) {
+    return {
+      bytes: joined.subarray(0, limit),
+      carry: joined.subarray(limit),
+      eof,
+    }
+  }
+  return { bytes: joined, carry: new Uint8Array(0), eof }
 }
 
+// R2 takes a single-shot put up to 5 GiB. Above that the upload has to be
+// multipart even when the length is known.
+const MAX_SINGLE_SHOT_BYTES = 5 * 1024 * 1024 * 1024
+
 /**
  * `R2Bucket.put` requires a stream with a known length; a pass-through
- * TransformStream (what the middleware sends for URL-fetched artifacts) has
+ * TransformStream (what the middleware sends when it had to cap the body) has
  * none. Re-declare the length when `expectedLength` provides it — the
  * middleware only sets it when it is the exact decoded byte count — and
  * otherwise stream through a multipart upload, one buffered part at a time.
@@ -140,15 +175,16 @@ async function putStream(
   options: R2PutOptions,
   expectedLength: number | undefined,
 ): Promise<R2Object | null> {
-  if (expectedLength !== undefined) {
+  if (expectedLength !== undefined && expectedLength <= MAX_SINGLE_SHOT_BYTES) {
     return bucket.put(
       key,
       body.pipeThrough(new FixedLengthStream(expectedLength)),
       options,
     )
   }
+  // Unknown length, or too big for one shot: multipart, one part at a time.
   const reader = body.getReader()
-  const first = await readUpTo(reader, MULTIPART_PART_SIZE)
+  const first = await readPart(reader, MULTIPART_PART_SIZE, new Uint8Array(0))
   if (first.eof) {
     // The whole body fit in one part — a plain put is enough.
     return bucket.put(key, first.bytes, options)
@@ -158,10 +194,19 @@ async function putStream(
     const parts: Array<R2UploadedPart> = [
       await upload.uploadPart(1, first.bytes),
     ]
+    let carry = first.carry
     let partNumber = 2
     for (;;) {
-      const part = await readUpTo(reader, MULTIPART_PART_SIZE)
+      const part = await readPart(reader, MULTIPART_PART_SIZE, carry)
+      carry = part.carry
       if (part.bytes.byteLength > 0) {
+        // 10,000 parts is R2's ceiling; failing here beats a confusing error
+        // from `complete` after uploading gigabytes.
+        if (partNumber > 10_000) {
+          throw new Error(
+            `Artifact at ${key} exceeds the multipart part limit — raise MULTIPART_PART_SIZE.`,
+          )
+        }
         parts.push(await upload.uploadPart(partNumber, part.bytes))
         partNumber += 1
       }
@@ -216,34 +261,55 @@ export function r2BlobStore(bucket: R2Bucket) {
     },
 
     async get(key, options): Promise<BlobObject | null> {
+      if (!options?.range) {
+        const whole = await bucket.get(key)
+        if (!whole) return null
+        return {
+          ...toRecord(whole),
+          body: whole.body,
+          arrayBuffer: () => whole.arrayBuffer(),
+          text: () => whole.text(),
+        }
+      }
       // A ranged read is what a serve route turns into `206` — R2 slices in
       // the bucket, so a seek never streams the whole object. `resolveBlobRange`
       // clamps a too-long length and throws on an offset past the end (the
       // route answers `416` from `record.size` before ever calling in). The
-      // extra `head` buys that clamp deterministically — one class-B op
-      // against streaming bytes you did not need to send.
-      const head = options?.range ? await bucket.head(key) : null
-      const served =
-        options?.range && head
-          ? resolveBlobRange(head.size, options.range)
-          : undefined
-      const obj = await bucket.get(
-        key,
-        served
-          ? { range: { offset: served.offset, length: served.length } }
-          : {},
-      )
-      if (!obj) return null
-      return {
-        // `toRecord(obj)` reports the WHOLE object's size even on a ranged
-        // read — R2's `R2Object.size` is the object, not the slice — which is
-        // exactly the contract, and what `Content-Range`'s total needs.
-        ...toRecord(obj),
-        ...(served ? { range: served } : {}),
-        body: obj.body,
-        arrayBuffer: () => obj.arrayBuffer(),
-        text: () => obj.text(),
+      // `head` buys that clamp deterministically — one class-B op against
+      // bytes you did not need to send.
+      //
+      // Retry a bounded number of times: each attempt measures the object and
+      // reads a slice of THAT version, and only an overwrite landing between
+      // the two calls costs another lap.
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const head = await bucket.head(key)
+        // A ranged read of a key that is not there is a miss, not a
+        // whole-object read: falling through to an un-ranged `get` would
+        // answer a `206` carrying the entire file.
+        if (!head) return null
+        const served = resolveBlobRange(head.size, options.range)
+        const obj = await bucket.get(key, {
+          range: { offset: served.offset, length: served.length },
+          // Tie the slice to the version `head` measured. Without this, a
+          // `put` landing between the two calls yields a `Content-Range`
+          // computed from one object and bytes from another.
+          onlyIf: { etagMatches: head.etag },
+        })
+        // No body means the precondition failed — the object changed under us.
+        if (!obj) return null
+        if (!('body' in obj)) continue
+        return {
+          // `toRecord(obj)` reports the WHOLE object's size even on a ranged
+          // read — R2's `R2Object.size` is the object, not the slice — which
+          // is exactly the contract, and what `Content-Range`'s total needs.
+          ...toRecord(obj),
+          range: served,
+          body: obj.body,
+          arrayBuffer: () => obj.arrayBuffer(),
+          text: () => obj.text(),
+        }
       }
+      throw new Error(`R2 object ${key} changed under every ranged read.`)
     },
 
     async head(key) {
diff --git a/packages/ai-persistence/src/blob-range.ts b/packages/ai-persistence/src/blob-range.ts
index 20bad8bfd..82e1ea600 100644
--- a/packages/ai-persistence/src/blob-range.ts
+++ b/packages/ai-persistence/src/blob-range.ts
@@ -78,7 +78,11 @@ export function parseRangeHeader(
   // bytes with a 206 that claims they are the right ones.
   if (rawStart === '') {
     const suffix = Number(rawEnd)
-    if (suffix === 0) return 'unsatisfiable'
+    // A zero-length suffix names no bytes, and NO range is satisfiable against
+    // a zero-byte object — without the size check, `bytes=-1` on an empty
+    // artifact resolves to `{ offset: 0 }` and throws out of the store instead
+    // of answering 416.
+    if (suffix === 0 || size === 0) return 'unsatisfiable'
     return { offset: Math.max(0, size - suffix) }
   }
 
diff --git a/packages/ai-persistence/tests/blob-range.test.ts b/packages/ai-persistence/tests/blob-range.test.ts
index 996c4e974..e88ab8d9d 100644
--- a/packages/ai-persistence/tests/blob-range.test.ts
+++ b/packages/ai-persistence/tests/blob-range.test.ts
@@ -63,6 +63,11 @@ describe('parseRangeHeader', () => {
     expect(parseRangeHeader('bytes=1000-', 1000)).toBe('unsatisfiable')
     expect(parseRangeHeader('bytes=1500-1600', 1000)).toBe('unsatisfiable')
     expect(parseRangeHeader('bytes=-0', 1000)).toBe('unsatisfiable')
+    // No range is satisfiable against a zero-byte object — including the
+    // suffix form, which would otherwise resolve to `{ offset: 0 }` and throw
+    // out of the store instead of answering 416.
+    expect(parseRangeHeader('bytes=-1', 0)).toBe('unsatisfiable')
+    expect(parseRangeHeader('bytes=0-', 0)).toBe('unsatisfiable')
   })
 
   it('ignores an invalid byte-range-spec rather than rejecting it', () => {