# Tasks — add-drive-range-reads

> Every checkbox MUST reflect work actually done in this change.

## 1. Spec authoring

- [ ] 1.1 Read `openspec/AGENTS.md` §0c, §2b, §6a, §7, §11, §13, §13a, §14
- [ ] 1.2 Read `openspec/archive/2026-05-16-add-drive-uri/proposal.md` deferral note and `add-drive-uri` archived delta
- [ ] 1.3 Read `openspec/specs/drive/spec.md`, `openspec/specs/drive-uri/spec.md`
- [ ] 1.4 Confirm `Drive.createReadStream`, chunks `#reassemble`, mesh `ChunkRequest` shapes in source
- [ ] 1.5 Draft `proposal.md` + `design.md` + `tasks.md` + spec deltas
- [ ] 1.6 Build the numbered Requirement / Scenario implementation checklist (per §0c step 6)
- [ ] 1.7 `openspec validate add-drive-range-reads --strict` exits 0

## 2. `@suaveplan/drive` — range plumbing

- [ ] 2.1 `src/types/drive.types.ts` — add `RangeReadOptions` interface; extend `DriveStorage` with optional `capabilities.nativeRange?: boolean`; extend `DriveStorage.createReadStream?` signature with optional `{ offset, length }` (back-compat preserved)
- [ ] 2.2 `src/error-codes.ts` — add `RANGE_INVALID`, `RANGE_OUT_OF_BOUNDS` to `DRIVE_CODES`
- [ ] 2.3 `src/error-codes.spec-conformance.test.ts` — extend frozen-registry test, every-code-starts-with-`DRIVE.` test
- [ ] 2.4 `src/file-operations/streams.ts` — overload `createReadStream(storage, path, signal?)` AND `createReadStream(storage, path, options: RangeReadOptions)`; runtime `instanceof AbortSignal` discriminator; synchronous validation → `DRIVE.RANGE_INVALID`; slicing transform when `!nativeRange`
- [ ] 2.5 `src/file-operations/streams.md` — update docs (range API, capability flag, sliced vs. native behaviour)
- [ ] 2.6 `src/file-operations/streams.range.test.ts` — boundary table cases: range fully inside one chunk, spans boundary, aligned multi-chunk, tail-to-EOF, zero-length, whole-file, abort mid-stream
- [ ] 2.7 `src/file-operations/streams.range.md` — sibling doc
- [ ] 2.8 `src/drive/drive.ts` — `createReadStream` overload signatures forwarded to `streams.ts` helpers; middleware context carries `range?: { offset, length? }`
- [ ] 2.9 `src/drive/drive.test.ts` — overload-compat (bare signal still works), options form, `DRIVE.RANGE_INVALID` synchronous throw, `DRIVE.RANGE_OUT_OF_BOUNDS` (size-known) synchronous throw

## 3. `@suaveplan/drive-plugin-chunks` — range-aware reassemble

- [ ] 3.1 `src/pipeline/range.ts` — pure function `chunkRangeFor({ offset, length, fileSize, chunkSize })` returning `{ firstChunk, lastChunk, firstSkip, lastKeep }` or `null` for zero-length
- [ ] 3.2 `src/pipeline/range.md`
- [ ] 3.3 `src/pipeline/range.test.ts` — exhaustive table (design § "Worked examples"), fast-check property tests for invariants (`offset + length ≤ fileSize`, slices reassemble to `bytes[offset, end)`)
- [ ] 3.4 `src/error-codes.ts` — add `CHUNKS.RANGE_OUT_OF_BOUNDS`
- [ ] 3.5 `src/error-codes.spec-conformance.test.ts` — extend
- [ ] 3.6 `src/plugin.ts` — refactor `#reassemble` to accept `range?: RangeReadOptions`; sibling `#reassembleAsStream(fileId, range?)`; middleware reads `ctx.range` and forwards; per-iteration `signal.throwIfAborted()`
- [ ] 3.7 `src/plugin.md` — update docs (range path, mesh request optimisation, error code)
- [ ] 3.8 `src/plugin.range.test.ts` — covers buffered read with range + streaming read with range + `RANGE_OUT_OF_BOUNDS` on oversize range + abort mid-range

## 4. `@suaveplan/drive-mesh` — range → ChunkRequest pivot

- [ ] 4.1 `src/pull/range-request.ts` — `buildRangeRequest({ firstChunk, lastChunk, totalChunks })` returns `ChunkRequest.specific` when `span ≤ 64`, else `ChunkRequest.bitset`
- [ ] 4.2 `src/pull/range-request.md`
- [ ] 4.3 `src/pull/range-request.test.ts` — pivot boundary at exactly 64 chunks; bitset round-trips through `encodeBitset`/`decodeBitset`; specific shape rejects empty span
- [ ] 4.4 `src/parallel-puller.ts` — accept range, build request via `buildRangeRequest`, narrow parallelism domain to in-range chunkIds, propagate `AbortSignal`
- [ ] 4.5 `src/parallel-puller.test.ts` — extend: only in-range chunks pulled; abort cancels in-flight; small-range uses `specific`, large-range uses `bitset`

## 5. `@suaveplan/drive-uri` — range pass-through

- [ ] 5.1 `src/types/plugin-options.types.ts` — extend adapter capabilities (`nativeRange: true`)
- [ ] 5.2 `src/adapter/drive-storage-like.ts` — `createReadStream(key, { offset?, length?, signal? })` forwards to `Drive.createReadStream(key, { offset, length, signal })`
- [ ] 5.3 `src/adapter/drive-storage-like.md` — update
- [ ] 5.4 `src/adapter/drive-storage-like.test.ts` — range forwarded; `nativeRange` capability flag asserted
- [ ] 5.5 `src/plugins/drive/drive.streams.ts` — `InstrumentedDriveAdapter.createReadStream` accepts and forwards range; emits `drive.uri.range` span attribute when present
- [ ] 5.6 `src/plugins/drive/drive.streams.test.ts` — range round-trip via plugin; abort mid-stream; attribute present iff range present
- [ ] 5.7 `src/otel/otel.ts` — `range_chunks_fetched` histogram; `drive.uri.range = "{offset}-{end}"` setter
- [ ] 5.8 `src/otel/otel.test.ts` — histogram increments, attribute set, attribute omitted when no range
- [ ] 5.9 `tests/integration/drive-range-roundtrip.test.ts` — real `Drive` + storage-file: write 200 KiB file, read bytes [60 000, 70 000) via `resolver.read` flow, assert equality

## 6. Pre-archive verification (§13)

- [ ] 6.1 `bunx turbo lint typecheck test --filter=@suaveplan/drive --filter=@suaveplan/drive-plugin-chunks --filter=@suaveplan/drive-mesh --filter=@suaveplan/drive-uri`
- [ ] 6.2 `bunx turbo test:coverage` (100 / 100 / 100 / 100 on every touched package)
- [ ] 6.3 `bunx turbo build`
- [ ] 6.4 Banned-pattern scan; barrel-shape scan; test-runner import scan; missing `.md` scan; README check; bare-version check; subpath export count; security scan
- [ ] 6.5 §13 step 10 dependent sweep: `bunx turbo test --filter=...@suaveplan/drive`
- [ ] 6.6 Walk every `### Requirement` / `#### Scenario` / `**Verified by:**` — confirm every named test exists and the name matches verbatim

## 7. Doc + manifest refresh (§13b)

- [ ] 7.1 Update `packages/drive/drive/README.md`, `packages/drive/drive-plugin-chunks/README.md`, `packages/drive/drive-mesh/README.md`, `packages/drive/drive-uri/README.md`
- [ ] 7.2 `bun scripts/folder-reorg/generate-manifest.ts`
- [ ] 7.3 `bun scripts/generate-missing.ts`
- [ ] 7.4 Update `STATUS.md`, `SUMMARY.md` for the four touched packages
- [ ] 7.5 `bunx markdownlint-cli2 --fix`

## 8. Archival (§14)

- [ ] 8.1 Fold `specs/drive/spec.md` delta into `openspec/specs/drive/spec.md`
- [ ] 8.2 Fold `specs/drive-uri/spec.md` delta into `openspec/specs/drive-uri/spec.md`
- [ ] 8.3 Move `openspec/changes/add-drive-range-reads/` → `openspec/archive/<yyyy-mm-dd>-add-drive-range-reads/`