suaveplan/openspec/archive/2026-05-16-add-drive-uri/tasks.md

Tasks — add-drive-uri

Every checkbox MUST reflect work actually done in this change.

1. Spec authoring

• 1.1 Read openspec/specs/storage-uri/spec.md (post-archive of add-storage-uri) and confirm UriPlugin is the correct integration point
• 1.2 Read openspec/specs/drive/spec.md, openspec/specs/drive-template/spec.md, openspec/specs/drive-mesh/spec.md, openspec/specs/drive-plugin-chunks/spec.md to confirm the consumed Drive surface
• 1.3 Read openspec/AGENTS.md §0c, §2b, §6a, §7, §11, §13, §14
• 1.4 Read openspec/archive/2026-05-16-add-storage-uri/ end-to-end as the closest precedent
• 1.5 Confirm Drive.read, Drive.createReadStream, Drive.write, Drive.delete, Drive.stat, Drive.hydrateFrom signatures by reading packages/drive/drive/src/drive/drive.ts
• 1.6 Draft proposal.md, design.md, tasks.md, specs/drive-uri/spec.md per openspec/templates/*
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete planned it(...) titles
• 1.8 Build the numbered Requirement/Scenario implementation checklist (per §0c step 6) — 11 requirements, 26 scenarios

2. Scaffolding

• 2.1 Create packages/drive/drive-uri/ mirroring packages/storage/storage-uri/ conventions
• 2.2 Write package.json v0.0.0, "sideEffects": false, subpath exports for every feature module
• 2.3 Wire deps: @suaveplan/error, @suaveplan/storage-uri, @suaveplan/drive, @suaveplan/drive-template, @suaveplan/types, @opentelemetry/api, tslib (all workspace:^ / catalog:)
• 2.4 Wire devDeps: @suaveplan/testing, @suaveplan/storage, @suaveplan/storage-file, @suaveplan/drive-mesh, @suaveplan/drive-plugin-chunks, @vitest/coverage-istanbul, fast-check, typescript, vite, vite-plugin-dts, vitest
• 2.5 Write tsconfig.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts (via createTestConfig)
• 2.6 Write tests/setup/polyfills.ts and README.md skeleton

3. Implementation

• 3.1 src/error-codes/error-codes.ts — defineCodes("DRIVE_URI", ["INVALID_URI", "DRIVE_ID_MISMATCH", "TEMPLATE_NOT_AVAILABLE", "TEMPLATE_INVALID", "WRITE_UNSUPPORTED", "CAPABILITY_MISSING", "ABORTED"] as const), DriveUriError class, uri/scheme/driveId?/swarmId?/templateId?/path? discriminants
• 3.2 src/types/plugin-options.types.ts — DriveUriPluginOptions, DriveMeshUriPluginOptions, DriveTemplateUriPluginOptions, TemplateProvider interfaces (no inline shapes per §11)
• 3.3 src/adapter/drive-storage-like.ts — DriveStorageLikeAdapter translating Drive → StorageLike, with createReadStream passthrough and not-found-to-undefined mapping
• 3.4 src/plugins/drive/drive.ts — driveUriPlugin(options): UriPlugin with parse/build, DRIVE_ID_MISMATCH guard, AbortSignal propagation, WRITE_UNSUPPORTED on set
• 3.5 src/plugins/drive/drive.streams.ts — createReadStream forwarding helper (shared between the three plugins)
• 3.6 src/plugins/drive-mesh/drive-mesh.ts — driveMeshUriPlugin(options): UriPlugin with swarmId capture for instrumentation only
• 3.7 src/plugins/drive-template/drive-template.ts — driveTemplateUriPlugin(options): UriPlugin with construction-time CAPABILITY_MISSING check, per-templateId hydration cache (Map<string, Promise<void>>), TEMPLATE_NOT_AVAILABLE/TEMPLATE_INVALID mapping
• 3.8 src/otel/otel.ts — meter + tracer wiring, recordOp(op, scheme, outcome, ms), recordTemplateHydration(outcome), span attributes with query-string stripping
• 3.9 src/conformance/conformance.ts — re-export of runUriPluginConformance from @suaveplan/storage-uri; package-local fixture sets in tests
• 3.10 src/index.ts — explicit named re-exports per §6a

4. Tests (every it(...) carries { timeout: 5000 }, 30000 for async integration)

• 4.1 src/error-codes/error-codes.test.ts — every code reachable from a real call site, discriminants populated, cause preserved
• 4.2 src/adapter/drive-storage-like.test.ts — get returns undefined on not-found, re-throws other failures, clear rejects with helpful message
• 4.3 src/plugins/drive/drive.test.ts — parse + dispatch + DRIVE_ID_MISMATCH + build round-trip + AbortSignal pre/forward + WRITE_UNSUPPORTED
• 4.4 src/plugins/drive/drive.streams.test.ts — native createReadStream forwarding, mid-stream abort propagation
• 4.5 src/plugins/drive-mesh/drive-mesh.test.ts — dispatch, swarmId span attribute, build round-trip
• 4.6 src/plugins/drive-template/drive-template.test.ts — first-read hydration, concurrent-read single-hydration, second-read skip, TEMPLATE_NOT_AVAILABLE mapping, TEMPLATE_INVALID mapping, CAPABILITY_MISSING (missing provider + non-function fetchTemplate)
• 4.7 src/otel/otel.test.ts — duration histogram, errors_total with code, query-string stripping, template_hydrations_total exactly-once per template
• 4.8 src/conformance/conformance.test.ts — drive / drive+mesh / drive+template plugins pass runUriPluginConformance with planned fixtures
• 4.9 tests/integration/drive-roundtrip.test.ts — real Drive on storage-file: write a file, read it back via resolver.read("drive://...")
• 4.10 tests/integration/template-roundtrip.test.ts — real Drive + chunksPlugin: issue a DriveTemplate, dehydrate, fetch via in-process templateProvider, resolve via drive+template://...
• 4.11 tests/integration/compose-with-storage-uri.test.ts — one StorageUriResolver with fileUriPlugin + driveUriPlugin, resolve both file:/// and drive://
• 4.12 No imports from vitest or bun:test in test files — all via @suaveplan/testing/runner (§7)
• 4.13 No vi.mock / jest.mock; all dependencies are real (CLAUDE.md rule 2)

5. Documentation

• 5.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 5.2 README.md links every module under ## Modules
• 5.3 README documents the composition recipe with storage-uri + drive-uri plugins side-by-side
• 5.4 README documents the TemplateProvider interface and how to author one

6. Gates

• 6.1 bun run check
• 6.2 bunx turbo lint typecheck test --filter=@suaveplan/drive-uri
• 6.3 bunx turbo test:coverage --filter=@suaveplan/drive-uri — 100/100/100/100 Istanbul
• 6.4 bunx turbo build --filter=@suaveplan/drive-uri
• 6.5 bun scripts/lint/check-test-runner-imports.ts (rule 11)
• 6.6 Tier-purity grep — grep -rnE "from ['\"](node:|bun:)" packages/drive/drive-uri/src/ returns empty
• 6.7 Banned-pattern scan returns empty (§2)
• 6.8 Missing-.md scan returns empty (§4)
• 6.9 Non-root export * scan returns empty (§6a)
• 6.10 Bare-version scan returns empty (§1)
• 6.11 Spec-reconciliation gate — every ### Requirement is implemented; every **Verified by:** test name exists verbatim and passes (§13 step 0)

7. Manifest & archival

• 7.1 Add package to MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts
• 7.2 Update STATUS.md (genesis-original — add to "Completed" once shipped)
• 7.3 Update SUMMARY.md with the one-paragraph description
• 7.4 bunx markdownlint-cli2 --fix on touched docs
• 7.5 Fold specs/drive-uri/spec.md into openspec/specs/drive-uri/spec.md
• 7.6 Move openspec/changes/add-drive-uri/ → openspec/archive/<yyyy-mm-dd>-add-drive-uri/