# Tasks — `complete-drive-uri`

> Every checkbox MUST reflect work actually done in this change. Walk every `### Requirement` and `#### Scenario` in `specs/drive-uri/spec.md` AND `specs/drive/spec.md` before declaring done (§12a).

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Spec authoring

- [ ] 1.1 Read `openspec/AGENTS.md` §0c, §2b, §2c, §6a, §7, §11, §13, §13a, §14
- [ ] 1.2 Read `openspec/archive/2026-05-16-add-drive-uri/proposal.md`, `_superseded-narrow-deferrals-2026-05-17/{add-drive-uri-writes,add-drive-range-reads}/{proposal,design}.md`
- [ ] 1.3 Read `openspec/specs/drive-uri/spec.md` and `openspec/specs/drive/spec.md`
- [ ] 1.4 Confirm `Drive.{read,write,delete,stat,list,createReadStream,createWriteStream,hydrateFrom,getKeyStatus,getPresence}` surface; `DriveStorage.capabilities` flag pattern; `StreamingStorageExtensions` shape; `MeshDrive.{advertise,unadvertise}` shape; `ChunkRequest` union; `parseUri` query/fragment shape
- [ ] 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 complete-drive-uri --strict` exits 0

## 2. `@suaveplan/drive` — range overload + new codes

- [ ] 2.1 `src/types/drive.types.ts` — add `RangeReadOptions { offset?, length?, signal? }`; extend `DriveStorage` with `capabilities.nativeRange?: boolean` and an extended `createReadStream?(path, options?: { offset?, length?, signal? })` signature
- [ ] 2.2 `src/error-codes.ts` — add `RANGE_INVALID`, `RANGE_OUT_OF_BOUNDS` to `DRIVE_CODES` (registry grows 11 → 13)
- [ ] 2.3 `src/error-codes.spec-conformance.test.ts` — extend frozen-registry and every-code-starts-with-`DRIVE.` checks
- [ ] 2.4 `src/file-operations/streams.range.ts` — pure slicing transform `sliceStream(stream, offset, length)` honouring `signal`
- [ ] 2.5 `src/file-operations/streams.range.md` — sibling doc
- [ ] 2.6 `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`; `nativeRange` → forward `{ offset, length }`; otherwise wrap in `sliceStream`
- [ ] 2.7 `src/file-operations/streams.md` — update docs
- [ ] 2.8 `src/file-operations/streams.range.test.ts` — boundary table: fully inside one chunk, spans boundary, aligned multi-chunk, tail-to-EOF, zero-length, whole-file, abort mid-stream
- [ ] 2.9 `src/drive/drive.ts` — `createReadStream` overload signatures forwarded to `streams.ts`; middleware context carries `range?: { offset, length? }`
- [ ] 2.10 `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-uri` — error registry + types

- [ ] 3.1 `src/error-codes/error-codes.ts` — extend `DRIVE_URI_CODES` to 14 codes: `TEMPLATE_READ_ONLY`, `RANGE_INVALID`, `RANGE_OUT_OF_BOUNDS`, `MESH_PROPAGATION_TIMEOUT`, `STAT_UNAVAILABLE`, `LIST_UNSUPPORTED`, `INVALID_QUERY` added to the existing 7
- [ ] 3.2 `src/error-codes/error-codes.ts` — extend `DriveUriErrorOptions` with `range?: { offset: number; length?: number }`, `fileId?: string`, `key?: string`, `value?: string`
- [ ] 3.3 `src/error-codes/error-codes.md` — describe every code, its call site, and the narrowed role of `WRITE_UNSUPPORTED`
- [ ] 3.4 `src/error-codes/error-codes.test.ts` — exhaustive registry shape (14 codes, every code starts with `DRIVE_URI.`, `Object.isFrozen` holds), `DriveUriError` discriminants all surface, `cause` preserved across re-wraps
- [ ] 3.5 `src/types/plugin-options.types.ts` — add `MeshAdvertiseHook { advertise(fileId, bitset, totalChunks, signal?), unadvertise(fileId, signal?) }`; widen `TemplateProvider.fetchTemplate(templateId, options?: { nonce?, signal? })` (preserve back-compat by making the second arg optional); add `?advertise?: MeshAdvertiseHook` to `DriveMeshUriPluginOptions`
- [ ] 3.6 `src/types/plugin-options.types.md` — update

## 4. `@suaveplan/drive-uri` — query parsing

- [ ] 4.1 `src/query/parse-query.ts` — `parseQuery(query: string | undefined, scheme: string): ParsedQuery` returning `{ signalTimeoutMs?, advertise?, nonce? }`; unknown keys throw `DRIVE_URI.INVALID_QUERY`
- [ ] 4.2 `src/query/parse-query.md` — sibling doc
- [ ] 4.3 `src/query/parse-query.test.ts` — per-scheme allow-list, unknown keys, malformed values (`?advertise=maybe`, `?signal-timeout-ms=-1`), empty/missing query

## 5. `@suaveplan/drive-uri` — events

- [ ] 5.1 `src/events/events.ts` — typed topic constants `DRIVE_URI_TOPICS = { write: "drive_uri:write", delete: "drive_uri:delete", meshAdvertised: "drive_uri:mesh_advertised" } as const`; `emit(events, topic, payload)` no-op when `events` is undefined
- [ ] 5.2 `src/events/events.md` — sibling doc
- [ ] 5.3 `src/events/events.test.ts` — emission against a real `EventBusLike` fixture; no-op when bus absent

## 6. `@suaveplan/drive-uri` — adapter widening

- [ ] 6.1 `src/adapter/drive-storage-like.ts` — widen `get`/`set`/`delete`/`exists`/`stat`/`list` to accept and forward `AbortSignal`; add `getMetadata(key, signal?): Promise<StatResult | undefined>` mapping `Drive.stat → StatResult`; add `createWriteStream(key, body, signal?): Promise<void>` consuming `ReadableStream<Uint8Array>` and piping into `Drive.createWriteStream`; widen `createReadStream` to accept `{ offset?, length?, signal? }`; advertise `capabilities = { nativeRange: true, nativeStreams: true }`
- [ ] 6.2 `src/adapter/drive-storage-like.md` — update for every new method and signature
- [ ] 6.3 `src/adapter/drive-storage-like.test.ts` — `get`/`set`/`delete`/`exists`/`stat`/`list` all propagate `signal`; pre-aborted signal short-circuits; `getMetadata` returns `StatResult` shape; `createWriteStream` round-trips; `createReadStream({ offset, length })` forwards; `clear()` still rejects `WRITE_UNSUPPORTED`; `list` returns the expected re-serialisable keys

## 7. `@suaveplan/drive-uri` — InstrumentedDriveAdapter per-scheme dispatch

- [ ] 7.1 `src/plugins/drive/drive.streams.ts` — replace unconditional `set` rejection with per-scheme dispatch: `drive`/`drive+mesh` → `super.set(key, value, signal)`; `drive+template` → throw `DRIVE_URI.TEMPLATE_READ_ONLY`. Same for `delete` and `createWriteStream`
- [ ] 7.2 `src/plugins/drive/drive.streams.ts` — pre-aborted signal on every op → throw `DRIVE_URI.ABORTED`
- [ ] 7.3 `src/plugins/drive/drive.streams.ts` — range pass-through on `createReadStream`; OTel `drive.uri.range = "{offset}-{end}"` span attribute when present
- [ ] 7.4 `src/plugins/drive/drive.streams.ts` — emit `drive_uri:write` / `drive_uri:delete` events via `events/events.ts` on every success and every failure
- [ ] 7.5 `src/plugins/drive/drive.streams.ts` — narrow `WRITE_UNSUPPORTED` to `DriveStorageLikeAdapter.clear()` only (preserve constant for `clear` call site)
- [ ] 7.6 `src/plugins/drive/drive.streams.md` — update
- [ ] 7.7 `src/plugins/drive/drive.streams.test.ts` — pre-aborted abort short-circuits per op; range round-trip; write-stream round-trip; event emission asserted via real bus fixture

## 8. `@suaveplan/drive-uri` — drive:// plugin

- [ ] 8.1 `src/plugins/drive/drive.ts` — invoke `parseQuery(parts.query, "drive")` and propagate `signal-timeout-ms`; reject `?advertise` and `?nonce` with `DRIVE_URI.INVALID_QUERY`
- [ ] 8.2 `src/plugins/drive/drive.test.ts` — full op matrix: read/write/delete/stat/list/exists; AbortSignal threading; pre-aborted abort; `?signal-timeout-ms` honoured; `?advertise` rejected; `DRIVE_ID_MISMATCH` preserved; `INVALID_URI` for malformed inputs

## 9. `@suaveplan/drive-uri` — drive+mesh:// plugin

- [ ] 9.1 `src/plugins/drive-mesh/drive-mesh.ts` — invoke `parseQuery(parts.query, "drive+mesh")`; honour `?advertise=true|false`; on `true` requires `options.advertise` hook else throws `DRIVE_URI.CAPABILITY_MISSING` (reason: `advertise`) synchronously at `parse`
- [ ] 9.2 `src/plugins/drive-mesh/drive-mesh.ts` — after a successful write under `?advertise=true`, invoke `options.advertise.advertise(fileId, bitset, totalChunks, signal)`; rejection → wrap as `DRIVE_URI.MESH_PROPAGATION_TIMEOUT`; on success emit `drive_uri:mesh_advertised`
- [ ] 9.3 `src/plugins/drive-mesh/drive-mesh.ts` — without `?advertise`, emit `drive_uri.mesh_write_local_only` span event on every successful write
- [ ] 9.4 `src/plugins/drive-mesh/drive-mesh.md` — update for opt-in flow + redaction policy
- [ ] 9.5 `src/plugins/drive-mesh/drive-mesh.test.ts` — default = no advertise (spy asserts zero calls + local-only span event); `?advertise=true` → exactly one advertise call; `MeshAdvertiseHook` rejection → `MESH_PROPAGATION_TIMEOUT`; absence of hook with `?advertise=true` → `CAPABILITY_MISSING`; full op matrix

## 10. `@suaveplan/drive-uri` — drive+template:// plugin

- [ ] 10.1 `src/plugins/drive-template/drive-template.ts` — invoke `parseQuery(parts.query, "drive+template")`; forward `?nonce=…` to `templateProvider.fetchTemplate(templateId, { nonce, signal })`
- [ ] 10.2 `src/plugins/drive-template/drive-template.ts` — `set`/`delete`/`createWriteStream` throw `DRIVE_URI.TEMPLATE_READ_ONLY` synchronously, carrying `{ scheme, path: key, templateId }`
- [ ] 10.3 `src/plugins/drive-template/drive-template.md` — update
- [ ] 10.4 `src/plugins/drive-template/drive-template.test.ts` — full read-side op matrix post-hydrate; nonce forwarding; write/delete/writeStream all reject `TEMPLATE_READ_ONLY`; existing hydration behaviour preserved (memoised, concurrent-share, NOT_AVAILABLE, INVALID)

## 11. `@suaveplan/drive-uri` — OTel

- [ ] 11.1 `src/otel/otel.ts` — add `drive_uri.stream_chunks_fetched` histogram; setter for `drive.uri.range` and `drive.uri.has_advertise` span attributes; extend `redactUri` to also strip the fragment
- [ ] 11.2 `src/otel/otel.md` — update
- [ ] 11.3 `src/otel/otel.test.ts` — every counter/histogram fires per op; range attribute present iff range supplied; advertise attribute on mesh writes; redaction holds for `?` and `#`

## 12. `@suaveplan/drive-uri` — conformance

- [ ] 12.1 `src/conformance/conformance.test.ts` — re-run `runUriPluginConformance` with full **read/write/delete/stat/list/exists/range** matrices for all three plugins. Fixtures: 3 valid URIs + 6 invalid + build round-trip + range round-trip per scheme; `drive`/`drive+mesh` pass full cycle; `drive+template` rejects writes with `TEMPLATE_READ_ONLY`

## 13. Integration tests (no mocks per CLAUDE.md rule 2)

- [ ] 13.1 `tests/integration/drive-roundtrip-write.test.ts` — real local-storage `Drive`; `resolver.write` then `resolver.read`; assert equality
- [ ] 13.2 `tests/integration/drive-mesh-roundtrip-write.test.ts` — mesh-configured `Drive` with a real advertise hook implementation; default = no advertise; `?advertise=true` → exactly one advertise observed
- [ ] 13.3 `tests/integration/template-write-rejection.test.ts` — wired template-backed `Drive`; `resolver.write` and `resolver.remove` both reject `TEMPLATE_READ_ONLY`
- [ ] 13.4 `tests/integration/drive-range-roundtrip.test.ts` — write 200 KiB file via local Drive; `resolver.open("drive://…", { offset: 60_000, length: 10_000, signal })` returns exactly bytes [60 000, 70 000)
- [ ] 13.5 `tests/integration/drive-stat-list-exists.test.ts` — full read-side matrix on a real Drive: `resolver.stat` → `StatResult`, `resolver.exists` → boolean, `resolver.list` → URIs that round-trip through `resolver.read`

## 14. Migration audit

- [ ] 14.1 `grep -rln "DRIVE_URI.WRITE_UNSUPPORTED" packages/ | grep -v "/dist/\|/coverage/\|/drive-uri/"` — every hit reviewed; non-matching consumers re-routed onto `TEMPLATE_READ_ONLY` / `RANGE_*` / `MESH_PROPAGATION_TIMEOUT` where appropriate
- [ ] 14.2 Update `README.md` Features + Modules sections to reflect full surface

## 15. Pre-publish gate (§13)

- [ ] 15.1 Spec reconciliation — walk every `### Requirement` and `#### Scenario` in `specs/drive-uri/spec.md` AND `specs/drive/spec.md`; confirm every `**Verified by:**` test name exists verbatim
- [ ] 15.2 `bunx turbo lint typecheck test --filter=@suaveplan/drive --filter=@suaveplan/drive-uri` — green
- [ ] 15.3 `bunx turbo test:coverage --filter=@suaveplan/drive --filter=@suaveplan/drive-uri` — 100/100/100/100 on touched modules
- [ ] 15.4 `bunx turbo build --filter=@suaveplan/drive --filter=@suaveplan/drive-uri` — green
- [ ] 15.5 Banned-pattern, barrel, test-runner-import, missing-`.md`, README, bare-version, subpath-export, security scans — all clean
- [ ] 15.6 Dependent sweep: `bunx turbo test --filter=...@suaveplan/drive` — green

## 16. Root-doc refresh (§13b)

- [ ] 16.1 `bun scripts/folder-reorg/generate-manifest.ts` — refresh `MANIFEST.md`
- [ ] 16.2 `bun scripts/generate-missing.ts` — refresh `MISSING.yml`
- [ ] 16.3 Update `STATUS.md` / `SUMMARY.md` paragraphs for `drive-uri` and `drive` to reflect full surface
- [ ] 16.4 `bunx markdownlint-cli2 --fix` over touched docs

## 17. Archival (§14)

- [ ] 17.1 Fold `specs/drive-uri/spec.md` delta into `openspec/specs/drive-uri/spec.md`
- [ ] 17.2 Fold `specs/drive/spec.md` delta into `openspec/specs/drive/spec.md`
- [ ] 17.3 Move `openspec/changes/complete-drive-uri/` → `openspec/archive/<yyyy-mm-dd>-complete-drive-uri/`
- [ ] 17.4 Delete `openspec/changes/_superseded-narrow-deferrals-2026-05-17/` (research already folded into this change's archive)