@ultimat3/storage 29.3.2 → 29.4.0

package/CLAUDE.md

@@ -39,6 +39,7 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 | File | Owns |
 |---|---|
 | `driver.ts` | `StorageDriver` contract (9 methods; `registerAs`/`verifySigned`/`retentionOf` optional), `assertPutOptions`, + bounded `toBytes`/`sha256Base64`/`etagOf` |
+| `range.ts` | `get(key, { range })`: screen + `servedRange` (`errors-range.ts`); s3's one-GET read is `driver-s3-range.ts` |
 | `driver-local.ts` | dev default over `Bun.file`, `.meta/` sidecars, `Bun.Glob` listing |
 | `driver-local-write.ts` | the local WRITE: staged under `.meta/.tmp/`, renamed marker → sidecar → bytes, `X_STORAGE_KEY_CONFLICT` / `X_STORAGE_PUT_FAILED`, the per-key queue |
 | `driver-local-read.ts` | `headObject`: sidecar + pending marker → trusted, re-checked, or untyped |
@@ -274,8 +275,7 @@ Gotchas:
   default header, and `decodeError` keeps a refusal `X_STORAGE_UPLOAD_FAILED` with the disk's
   status. A request with no response at all is the transport's `X_CLIENT_TRANSPORT_FAILED` — it was a
   bare `TypeError` before. This file calls no `fetch`; the XHR above is the one exemption.
-- **Bundle** (`bun build --target=browser --minify`, `uploadFile` only, `As of 2026-09-22`):
-  **17,767 B** on `clientTransport`; the +5.9 kB over 20.2.1 is core's transport graph.
+- **Bundle** (`uploadFile` only, browser, minified, `As of 2026-09-22`): **17,767 B**.
 - `exactOptionalPropertyTypes` is on — declare optional fields as `x?: T | undefined`.
 
 Why each rule above is shaped the way it is: [`docs/history/storage.md`](../../docs/history/storage.md).

package/README.md

@@ -194,6 +194,33 @@ the disk's own size (a HEAD on s3) before a byte is read — and is read with `s
 because an object's size is not the server's to choose: a presigned PUT lands in a bucket
 unmeasured, so a later `get()` of it was heap growth the uploader picked.
 
+## Ranged reads — `get(key, { range: [first, last] })`
+
+```ts
+import { disk } from '@ultimat3/storage';
+
+const page = await disk('debug').get('runs/r1/http.ndjson', { range: [0, 65_535] });
+page.bytes;        // at most 65 536 bytes
+page.range;        // [0, 65_535] — or [0, size - 1] when the object is shorter
+page.object.size;  // the WHOLE object's size, for `Content-Range: bytes 0-65535/<size>`
+```
+
+| Rule | |
+|---|---|
+| Offsets | `first` and `last` are BOTH inclusive — HTTP's `bytes=first-last`, S3's `Range:` |
+| On the wire | s3: ONE signed GET with `Range:` and no HEAD — the bytes, the window and total size (`Content-Range`), the `ETag`, type and date all come from that one response, so a write racing the read (a shrink, a grow, an A → B → A of one length) can never pair one version's bytes with another's description. Asks at most `maxGetBytes`; the provider's 416 is `X_STORAGE_RANGE_UNSATISFIABLE` (its size from a HEAD). local: `Bun.file().slice()` in the key's queue; memory: a slice of its copy |
+| Clamp | a `last` past the end is clamped to `size - 1`, as HTTP clamps it; `read.range` says what was served |
+| Refusal | a `first` at or past the end — an empty object has none — is `X_STORAGE_RANGE_UNSATISFIABLE` (416); its `fix:` is the whole-object range, or the plain `get(key)` for an empty one |
+| Screen | a backwards, negative, fractional or malformed tuple is the caller's defect: core's `X_INVARIANT` |
+| Ceiling | `maxGetBytes` bounds the RANGE, not the object: a 40MB log is refused whole and readable 1MB at a time |
+| Absence | `read.range` is present exactly when a range was asked — a third-party driver that ignored the option answers none |
+
+**A SEALED object cannot be range-read meaningfully.** `seal()` (`@ultimat3/core`) writes one
+`x1` envelope — one AES-256-GCM ciphertext, base64url, whose tag authenticates every byte — so a
+slice of it neither opens nor means anything, and there is no framed or chunked form of the
+envelope to slice along (`As of 2026-10`). Range-read plain objects. To page a sealed log, seal
+each page as its OWN object (`runs/<id>/http/0000`, `…/0001`) and read the page you need whole.
+
 ## Write-once objects (S3 Object Lock)
 
 ```ts
@@ -425,6 +452,7 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_PUT_FAILED` | the disk REFUSED a `put()`/`copy()` — `EACCES`, `ENOSPC`, `EROFS`, a provider's refused PUT |
 | `X_STORAGE_OBJECT_LOCKED` | local, memory: a delete, overwrite or copy onto a key under retention or a legal hold; the cause names the key, the mode and `retainUntil` or the hold, and the bytes are unchanged. Never raised by s3, where the provider keeps the locked version |
 | `X_STORAGE_READ_FAILED` | the disk REFUSED a `get`/`stat`/`exists`/`stream` or the read half of a `copy` — a denied `s3:GetObject`, a throttle, an unreadable file. An **absent** object is still `X_STORAGE_NOT_FOUND`, including one deleted between the existence check and the read |
+| `X_STORAGE_RANGE_UNSATISFIABLE` | `get(key, { range })` whose first byte is at or past the object's size — the 416 |
 | `X_STORAGE_KEY_CONFLICT` | local and memory disks (never s3): the key's path is another key's directory, or the reverse (`a` and `a/b`) |
 | `X_NOT_IMPLEMENTED` | `serverSideEncryption` on any driver |
 | `X_ENV_MISSING` | core's: S3 credential env vars, or a `localDriver` built outside development where neither `signingSecret` nor `STORAGE_SIGNING_SECRET` holds a secret other than the published `DEV_SIGNING_SECRET` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "29.3.2",
+  "version": "29.4.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.2"
+    "@ultimat3/core": "29.4.0"
   }
 }

package/src/driver-local-read.ts

@@ -61,6 +61,19 @@ export async function readObjectBytes(
     .then((buffer) => new Uint8Array(buffer), refusedRead(root, key, disk));
 }
 
+/** `readObjectBytes` for the inclusive window `[first, last]` — `Bun.file().slice()`, one read. */
+export async function readObjectRange(
+  root: string,
+  key: string,
+  disk: string,
+  [first, last]: readonly [number, number],
+): Promise<Uint8Array> {
+  return Bun.file(`${root}/${key}`)
+    .slice(first, last + 1)
+    .arrayBuffer()
+    .then((buffer) => new Uint8Array(buffer), refusedRead(root, key, disk));
+}
+
 /** `etagOf`, streamed: a copy or a `stat()` must settle a doubt without buffering the object. */
 export async function etagOfFile(root: string, key: string, disk = 'local'): Promise<string> {
   const hasher = new Bun.CryptoHasher('sha256');

package/src/driver-local.ts

@@ -31,7 +31,13 @@ import {
   sha256Base64,
   toBytes,
 } from './driver';
-import { etagOfFile, headObject, readObjectBytes, readSidecar } from './driver-local-read';
+import {
+  etagOfFile,
+  headObject,
+  readObjectBytes,
+  readObjectRange,
+  readSidecar,
+} from './driver-local-read';
 import { lockOfSidecar, type Sidecar, sidecarLock } from './driver-local-sidecar';
 import {
   commitObject,
@@ -50,6 +56,7 @@ import {
   requestedLock,
 } from './object-lock';
 import { assertSafeKey, META_DIR } from './path';
+import { assertGetOptions, type GetOptions, servedRange } from './range';
 import type { SignedUrlVerification } from './signed-url';
 import { buildSignedUrl, signedUrlBaseFor, verifySignedUrl } from './signed-url';
 import { resolveSigningSecret } from './signing-secret';
@@ -256,13 +263,25 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       return entry && { ...entry, contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE };
     },
 
-    async get(key: string): Promise<StorageRead> {
+    async get(key: string, getOptions?: GetOptions): Promise<StorageRead> {
       const safe = assertSafeKey(key);
+      assertGetOptions(DRIVER_NAME, getOptions);
+      const range = getOptions?.range;
       // Queued behind this key's writers: an object is two files, and a read between a put()'s
       // renames is a pair in doubt this process has no need to meet.
       return oneAtATime(safe, async () => {
         const file = Bun.file(filePath(safe));
         if (!(await file.exists())) throw objectNotFound(registered, safe);
+        if (range !== undefined) {
+          const served = servedRange(DRIVER_NAME, safe, range, file.size, maxGetBytes);
+          const bytes = await readObjectRange(root, safe, registered, served);
+          // A doubt is settled by streaming the WHOLE file through the hash, never by buffering it:
+          // the range is the only part of this object the read may hold.
+          const entry = await headObject(root, safe, () => etagOfFile(root, safe, registered));
+          if (entry === undefined) throw objectNotFound(registered, safe);
+          const object = { ...entry, contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE };
+          return { object, bytes, range: served };
+        }
         if (file.size > maxGetBytes) throw getTooLarge(DRIVER_NAME, safe, file.size, maxGetBytes);
         const bytes = await readObjectBytes(root, safe, registered);
         // Settled against the bytes this read ALREADY holds: hashed only for a sidecar-less object

package/src/driver-memory.ts

@@ -42,6 +42,7 @@ import {
   requestedLock,
 } from './object-lock';
 import { assertSafeKey } from './path';
+import { assertGetOptions, type GetOptions, servedRange } from './range';
 import type { SignedUrlVerification } from './signed-url';
 import { buildSignedUrl, signedUrlBaseFor, verifySignedUrl } from './signed-url';
 import { resolveSigningSecret } from './signing-secret';
@@ -190,9 +191,16 @@ export function memoryStorageDriver(options: MemoryStorageDriverOptions = {}): M
       return hit && snapshot(hit.object);
     },
 
-    async get(key: string): Promise<StorageRead> {
+    async get(key: string, getOptions?: GetOptions): Promise<StorageRead> {
       const safe = assertSafeKey(key);
+      assertGetOptions(DRIVER_NAME, getOptions);
       const hit = found(safe);
+      const range = getOptions?.range;
+      if (range !== undefined) {
+        const served = servedRange(DRIVER_NAME, safe, range, hit.bytes.byteLength, maxGetBytes);
+        const bytes = hit.bytes.slice(served[0], served[1] + 1);
+        return { object: snapshot(hit.object), bytes, range: served };
+      }
       // The local disk's refusal, so a suite on this disk meets the ceiling production has.
       if (hit.bytes.byteLength > maxGetBytes) {
         throw getTooLarge(DRIVER_NAME, safe, hit.bytes.byteLength, maxGetBytes);

package/src/driver-s3-range.ts

@@ -0,0 +1,99 @@
+// Single responsibility: the s3 disk's ranged read — ONE signed GET whose `Range:` answer carries
+// the bytes AND what they are (`Content-Range`'s window and total size, `ETag`, type, date), so the
+// slice and its description come from one response about one version. A HEAD beside it could not
+// promise that: a write between the two, or an A → B → A overwrite of one length, slips past both.
+
+import type { StorageObject, StorageRead } from './driver';
+import { DEFAULT_CONTENT_TYPE } from './driver';
+import { type S3Refusal, type S3WireOptions, sendSigned } from './driver-s3-signed';
+import { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
+import type { ByteRange } from './range';
+
+/** What the driver lends this read: its coded refusals and its own HEAD for a 416's size. */
+export interface S3RangeDeps {
+  readonly driver: string;
+  readonly maxGetBytes: number;
+  /** A refusal the provider gave (403, 503, a wrong region, a 404) as the disk's coded error. */
+  readonly refused: (key: string, refusal: S3Refusal) => never;
+  /** The disk's HEAD — asked only after a 416, for the size the refusal names. */
+  readonly sizeOf: (key: string) => Promise<number>;
+  /** A response the read cannot use: no `Content-Range`, or one that is not the window asked. */
+  readonly unreadable: (key: string, why: string) => never;
+}
+
+const CONTENT_RANGE = /^bytes (\d+)-(\d+)\/(\d+)$/;
+
+/**
+ * The window asked, CAPPED at `maxGetBytes` before it is sent: the ceiling bounds the range, and the
+ * object's size is not known until the answer — so at most the ceiling crosses the wire, and an
+ * answer that shows the object went on past the cap is refused before its body is read.
+ */
+const errorMessage = (thrown: unknown): string =>
+  thrown instanceof Error ? thrown.message : String(thrown);
+
+export async function readS3Range(
+  wire: S3WireOptions,
+  key: string,
+  range: ByteRange,
+  deps: S3RangeDeps,
+): Promise<StorageRead> {
+  const [first, last] = range;
+  const capped = Math.min(last, first + deps.maxGetBytes - 1);
+  const result = await sendSigned(wire, {
+    method: 'GET',
+    key,
+    headers: { range: `bytes=${first}-${capped}` },
+  });
+  if (!result.ok) {
+    if (result.refusal.statusCode !== 416) return deps.refused(key, result.refusal);
+    // A first byte at or past the end — of the object as it is NOW, which the HEAD names.
+    throw rangeUnsatisfiable(deps.driver, key, range, await deps.sizeOf(key));
+  }
+  const { response } = result;
+  const window = CONTENT_RANGE.exec(response.headers.get('content-range') ?? '');
+  if (response.status !== 206 || window === null) {
+    await response.body?.cancel().catch(() => undefined);
+    return deps.unreadable(key, `the ranged GET answered ${response.status} with no byte range`);
+  }
+  const served: ByteRange = [Number(window[1]), Number(window[2])];
+  const size = Number(window[3]);
+  if (served[0] !== first || served[1] > capped) {
+    await response.body?.cancel().catch(() => undefined);
+    return deps.unreadable(
+      key,
+      `asked bytes ${first}-${capped}, answered ${served[0]}-${served[1]}`,
+    );
+  }
+  // Cut by the CAP, not by the end of the object: the range asked is over the ceiling.
+  if (last > capped && size - 1 > capped) {
+    await response.body?.cancel().catch(() => undefined);
+    throw rangeTooLarge(deps.driver, key, [first, Math.min(last, size - 1)], deps.maxGetBytes);
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = new Uint8Array(await response.arrayBuffer());
+  } catch (thrown) {
+    // The headers came, the body broke (a reset connection): the disk's coded read failure.
+    return deps.unreadable(key, `the ranged body broke mid-read: ${errorMessage(thrown)}`);
+  }
+  if (bytes.byteLength !== served[1] - served[0] + 1) {
+    return deps.unreadable(
+      key,
+      `Content-Range promised ${served[1] - served[0] + 1}B, the body held ${bytes.byteLength}B`,
+    );
+  }
+  return { object: objectOf(key, size, response.headers), bytes, range: served };
+}
+
+/** The WHOLE object, as the same response describes it — never a second request's view. */
+function objectOf(key: string, size: number, headers: Headers): StorageObject {
+  const modified = new Date(headers.get('last-modified') ?? '');
+  return {
+    key,
+    size,
+    contentType: headers.get('content-type') ?? DEFAULT_CONTENT_TYPE,
+    etag: headers.get('etag') ?? '',
+    // Omitted when the provider sent none, never epoch 0 — `StorageListEntry.lastModified`.
+    ...(Number.isFinite(modified.getTime()) ? { lastModified: modified } : {}),
+  };
+}

package/src/driver-s3-signed.ts

@@ -1,5 +1,5 @@
 // Single responsibility: the s3 disk's SIGNED requests — the ones `Bun.S3Client` has no option for
-// (`x-amz-meta-*`, `Cache-Control`, `x-amz-object-lock-*`, `?retention`, `?legal-hold`) — built,
+// (`x-amz-meta-*`, `Cache-Control`, object lock, a ranged GET read off its own `Content-Range`) — built,
 // signed through core's one SigV4 signer and sent with `fetch`. The endpoint, the addressing style,
 // the region and the credentials are read from the SAME `S3DriverOptions` the Bun client is built
 // from, so the two transports of one disk cannot point at two buckets.

package/src/driver-s3.ts

@@ -34,6 +34,7 @@ import {
 import { isAbsentObject } from './driver-s3-absent';
 import { buildClient, type S3ClientLike, type S3ListResultLike } from './driver-s3-client';
 import { needsSignedPut, readObjectLock, signedPut } from './driver-s3-lock';
+import { readS3Range } from './driver-s3-range';
 import { regionMismatch } from './driver-s3-region';
 import type { S3FetchLike } from './driver-s3-signed';
 import {
@@ -48,6 +49,7 @@ import {
 } from './errors';
 import { assertObjectLockOptions, type ObjectLock } from './object-lock';
 import { assertSafeKey } from './path';
+import { assertGetOptions, type GetOptions } from './range';
 import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
@@ -261,8 +263,30 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       return (await present(safe)) ? statObject(safe) : undefined;
     },
 
-    async get(key: string): Promise<StorageRead> {
+    async get(key: string, getOptions?: GetOptions): Promise<StorageRead> {
       const safe = assertSafeKey(key);
+      assertGetOptions(DRIVER_NAME, getOptions);
+      const range = getOptions?.range;
+      // ONE signed GET, bytes and description from the same response (`driver-s3-range.ts`).
+      if (range !== undefined) {
+        return readS3Range(options, safe, range, {
+          driver: DRIVER_NAME,
+          maxGetBytes,
+          refused: (key, refusal) => refusedRead(key)(refusal),
+          sizeOf: async (key) => {
+            if (!(await present(key))) throw objectNotFound(diskName, key);
+            return (await statObject(key)).size;
+          },
+          unreadable: (key, why) => {
+            throw readFailed(
+              DRIVER_NAME,
+              key,
+              why,
+              `aws s3api get-object --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")} --key ${renderFixShellArg(key, "'<key>'")} --range bytes=0-0 /dev/null   # what the provider answers a ranged GET`,
+            );
+          },
+        });
+      }
       const file = conn().file(safe);
       if (!(await present(safe))) throw objectNotFound(diskName, safe);
       // The HEAD comes FIRST, and it is the whole point: a client PUT straight into the bucket is

package/src/driver.ts

@@ -7,6 +7,7 @@ import type { Clock, Page } from '@ultimat3/core';
 import { assert } from '@ultimat3/core';
 import { putTooLarge } from './errors';
 import type { ObjectLock, ObjectLockOptions } from './object-lock';
+import type { ByteRange, GetOptions } from './range';
 import type { SignedUrlVerification } from './signed-url';
 
 export type StorageBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
@@ -81,8 +82,15 @@ export interface ListOptions {
 }
 
 export interface StorageRead {
+  /** The WHOLE object's description — `size` is the object's, never the range's. */
   readonly object: StorageObject;
   readonly bytes: Uint8Array;
+  /**
+   * The bytes served, both inclusive, after the clamp — present exactly when `range` was asked.
+   * A third-party driver that ignored the option answers none, and that absence is how a caller
+   * tells a slice from the whole object rather than trusting `bytes.byteLength`.
+   */
+  readonly range?: ByteRange | undefined;
 }
 
 export type SignedUrlMethod = 'GET' | 'PUT';
@@ -134,9 +142,11 @@ export interface StorageDriver {
   stat(key: string): Promise<StorageObject | undefined>;
   /**
    * The whole object, BUFFERED — so bounded: an object over the driver's `maxGetBytes` is
-   * `X_STORAGE_TOO_LARGE`, exactly as `put()` refuses a body over `maxPutBytes`. Past it, `stream()`.
+   * `X_STORAGE_TOO_LARGE`, exactly as `put()` refuses a body over `maxPutBytes`. Past it, `stream()`
+   * — or `{ range: [first, last] }`, which reads only those bytes (inclusive) and is bounded by
+   * the range's length: s3 sends `Range:`, the local disk slices the file, memory slices its copy.
    */
-  get(key: string): Promise<StorageRead>;
+  get(key: string, options?: GetOptions): Promise<StorageRead>;
   /** Bytes without buffering — the only safe path for anything over a few MB. */
   stream(key: string): Promise<ReadableStream<Uint8Array>>;
   /**

package/src/errors-range.ts

@@ -0,0 +1,47 @@
+// The two refusals of a ranged `get(key, { range })`: a first byte past the end (HTTP's 416) and a
+// window over the disk's get ceiling. Their codes are registered with the rest of the package's in
+// `errors.ts`; each `fix:` is the call to make next, with the numbers this object allows.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+const keyArg = (key: string): string => renderFixLiteral(key, "'<key>'");
+
+/**
+ * A first byte at or past the end. The last byte is CLAMPED (`range.ts`), so only the first can
+ * miss; an empty object has no first byte at all, so its fix is the plain read.
+ */
+export const rangeUnsatisfiable = (
+  disk: string,
+  key: string,
+  range: readonly [number, number],
+  size: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_RANGE_UNSATISFIABLE',
+    cause: `get() asked "${key}" for bytes ${range[0]}-${range[1]}, and the object on the ${disk} disk is ${size}B — its first byte is past the end`,
+    fix:
+      size === 0
+        ? `await disk.get(${keyArg(key)})   # the object is empty: no range has a first byte`
+        : `await disk.get(${keyArg(key)}, { range: [0, ${size - 1}] })   # the whole ${size}B object; any first byte below ${size}`,
+    meta: { disk, key, first: range[0], last: range[1], size },
+  });
+
+/**
+ * A window over `maxGetBytes` — the ceiling bounds the RANGE, so the repair is a smaller window
+ * from the same first byte, or a higher ceiling on the disk.
+ */
+export const rangeTooLarge = (
+  disk: string,
+  key: string,
+  range: readonly [number, number],
+  maxBytes: number,
+): StorageError => {
+  const bytes = range[1] - range[0] + 1;
+  return new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `the range asked of "${key}" is ${bytes}B against the ${disk} disk's get ceiling of ${maxBytes}B, and get() buffers the range`,
+    fix: `await disk.get(${keyArg(key)}, { range: [${range[0]}, ${range[0] + maxBytes - 1}] })   # one window within the ceiling; or raise maxGetBytes to ${bytes} on the disk`,
+    meta: { disk, key, bytes, maxBytes, first: range[0], last: range[1] },
+  });
+};

package/src/errors.ts

@@ -32,6 +32,7 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_OBJECT_LOCKED',
   'X_STORAGE_KEY_UNSHARED',
   'X_STORAGE_ALREADY_PROMOTED',
+  'X_STORAGE_RANGE_UNSATISFIABLE',
 ] as const;
 
 /**
@@ -74,6 +75,7 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_OBJECT_LOCKED: 'the object is under retention or a legal hold',
   X_STORAGE_KEY_UNSHARED: 'object key is outside every tenant and every shared prefix',
   X_STORAGE_ALREADY_PROMOTED: 'the upload was already promoted onto its row',
+  X_STORAGE_RANGE_UNSATISFIABLE: 'the requested byte range starts past the end of the object',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -193,7 +195,7 @@ export const getTooLarge = (
     code: 'X_STORAGE_TOO_LARGE',
     cause: `"${key}" is ${bytes}B against the ${disk} disk's get ceiling of ${maxBytes}B, and get() buffers the whole object`,
     fix:
-      `read it with disk.stream(key) instead of get(), or raise the ceiling: ` +
+      `await disk.stream(${renderFixLiteral(key, "'<key>'")})   # unbuffered; or a window with get(key, { range }), or raise the ceiling: ` +
       (disk === 's3'
         ? `s3Driver({ bucket, maxGetBytes: ${bytes} })`
         : disk === 'memory'

package/src/index.ts

@@ -97,6 +97,7 @@ export {
   xmlBodyUnreadable,
 } from './errors';
 export { alreadyPromoted, quarantined } from './errors-promote';
+export { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
 export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
 export { grantUpload } from './grant';
 export type {
@@ -144,6 +145,12 @@ export {
   orgPrefix,
   scopedKey,
 } from './path';
+/**
+ * `get(key, { range })`. A third-party driver screens and clamps through these two, or it is a
+ * fourth answer to what a range means.
+ */
+export type { ByteRange, GetOptions } from './range';
+export { assertGetOptions, servedRange } from './range';
 export type {
   SignedUrlConstraints,
   SignedUrlFailure,

package/src/range.ts

@@ -0,0 +1,71 @@
+// Single responsibility: what `get(key, { range })` may ask for and what it is answered with — the
+// screen of the tuple for every disk, and for memory and local the clamp, the 416 and the ceiling
+// (which bounds the BYTES ASKED FOR, not the object). s3 learns the size from its one GET's answer
+// and applies the same three rules there (`driver-s3-range.ts`), with the same refusals.
+
+import { assert } from '@ultimat3/core';
+import { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
+
+/**
+ * The first and the last byte, BOTH INCLUSIVE — HTTP's `Range: bytes=first-last` and S3's, so a
+ * route copies a parsed header straight in and a `Content-Range` is read straight back out.
+ * `[0, 99]` is the first hundred bytes; `[0, 0]` is one.
+ */
+export type ByteRange = readonly [first: number, last: number];
+
+export interface GetOptions {
+  /**
+   * Read only these bytes. The last byte is clamped to the object (`[0, 1e12]` on a 10-byte object
+   * answers `[0, 9]`), as HTTP clamps it; a first byte at or past the end is
+   * `X_STORAGE_RANGE_UNSATISFIABLE`, which is a 416. `maxGetBytes` bounds the RANGE'S length, so a
+   * page of a large object is readable where `get()` of the whole would be refused.
+   *
+   * Meaningless on a SEALED object: `seal()`'s `x1` envelope is one AES-GCM ciphertext whose tag
+   * authenticates every byte, so a slice of it neither opens nor means anything. Range-read plain
+   * objects; page a sealed one by sealing each page as its own object.
+   */
+  readonly range?: ByteRange | undefined;
+}
+
+const isOffset = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/**
+ * The tuple's SHAPE, before the disk is asked anything: two whole, non-negative offsets in order.
+ * Core's `assert` (`X_INVARIANT`), because a backwards or fractional range is the calling code's
+ * defect — no object makes it valid — while a first byte past the end depends on the object and
+ * is the coded, caller-facing refusal below.
+ */
+export function assertGetOptions(driver: string, options: GetOptions | undefined): void {
+  const range = options?.range;
+  if (range === undefined) return;
+  const [first, last] = Array.isArray(range) ? range : [];
+  assert(
+    Array.isArray(range) && range.length === 2 && isOffset(first) && isOffset(last),
+    `get() on the ${driver} disk was given a range that is not two whole, non-negative byte offsets`,
+    'get(key, { range: [first, last] }) — inclusive offsets: [0, 99] reads the first 100 bytes',
+  );
+  assert(
+    first <= last,
+    `get() on the ${driver} disk was given the range [${first}, ${last}], whose first byte is past its last`,
+    `get(key, { range: [${last}, ${first}] }) — first before last, both inclusive`,
+  );
+}
+
+/**
+ * The range a disk SERVES for an object of `size` bytes — clamped, refused, or over the ceiling.
+ * Called with the object's own measured size, before a byte is read, by every driver.
+ */
+export function servedRange(
+  disk: string,
+  key: string,
+  range: ByteRange,
+  size: number,
+  maxGetBytes: number,
+): ByteRange {
+  const [first, wanted] = range;
+  if (first >= size) throw rangeUnsatisfiable(disk, key, range, size);
+  const last = Math.min(wanted, size - 1);
+  if (last - first + 1 > maxGetBytes) throw rangeTooLarge(disk, key, [first, last], maxGetBytes);
+  return [first, last];
+}