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.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.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.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.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.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.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.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/