suaveplan/openspec/archive/2026-05-04-drive-template-drive-surface/tasks.md

Tasks: drive-template-drive-surface

Change ID: drive-template-drive-surface Capability: extends drive capability + cross-cutting consumption of drive-template Target paths: packages/drive/drive/

Every checkbox MUST reflect work actually done in this change.

---

1. Spec

• 1.1 proposal.md drafted with §Why / §What changes / §Out of scope / §Migration impact / §Verification approach
• 1.2 No spec delta file — the additions extend the existing drive capability spec; the canonical openspec/specs/drive/spec.md will fold the additions on archive

2. Implementation — @suaveplan/drive surface additions

• 2.1 src/drive/file-location-index.ts — FileLocationIndex class + FileLocationEntry interface + emptyPresence() helper
• 2.2 src/drive/hydrate-from.ts — Drive.hydrateFrom orchestrator with 8-step validation pipeline, AbortSignal support, mid-iteration rollback via await Promise.resolve() yields
• 2.3 src/drive/get-key-status.ts — Drive.getKeyStatus(path) synchronous three-state lookup
• 2.4 src/drive/get-presence.ts — Drive.getPresence(path) chunk-level progress lookup
• 2.5 Update src/types/drive.types.ts — add KeyStatus / ChunkPresence / HydrateOptions / HydrateResult / HydrateProgressEvent types; extend DriveEntry with optional keyStatus / presence; extend DriveOptions with ourPubkey
• 2.6 Update src/drive/drive.ts — wire hydrateFrom / getKeyStatus / getPresence methods, expose fileLocationIndex getter, accept ourPubkey constructor option
• 2.7 Update src/error-codes.ts — add NOT_FOUND / UNAVAILABLE / ALREADY_HYDRATED / HYDRATE_ABORTED codes
• 2.8 Bus listener registration in hydrateFrom for kind: 'retroactive' files, with validateKeyGrant from @suaveplan/drive-template
• 2.9 Sibling .md for every new implementation file (hydrate-from.md, get-key-status.md, get-presence.md, file-location-index.md)
• 2.10 Update src/index.ts barrel — export new types and surface
• 2.11 Update package.json — add @suaveplan/drive-template runtime dep + @suaveplan/crypto-curve / @suaveplan/crypto-utils dev deps for tests
• 2.12 Update vite.config.ts externals
• 2.13 Cache-eviction loop honoring RetentionPolicy per file — DEFERRED. Needs tighter integration with @suaveplan/drive-plugin-chunks to know per-file chunk inventory; ships in drive-template-retention-loop follow-up.

3. Tests

• 3.1 tests/hydrate-from.test.ts — successful hydration, abort cancellation (pre + mid-iteration with rollback), encrypted-vs-plain counting, preFetch modes, already-hydrated rejection, progress events, NOT_INITIALIZED guard
• 3.2 tests/get-key-status.test.ts — three-state contract + NOT_FOUND
• 3.3 tests/get-presence.test.ts — progress shape contract + NOT_FOUND
• 3.4 tests/retroactive-key-grant.test.ts — valid grant flips lock, defensive branches (unknown fileId / unencrypted / already-unlocked / no-ourPubkey), bad-issuer rejection
• 3.5 tests/file-location-index.test.ts — direct unit tests for the index methods (set / getByPath / getByFileId / deleteByPath / clear / iterate / emptyPresence)
• 3.6 tests/policy-meshallowed-false.test.ts — DEFERRED with the cache-eviction work; no current code path emits cd:request directly from drive proper
• 3.7 tests/policy-cdnallowed-false.test.ts — DEFERRED; needs drive-transport-https integration
• 3.8 tests/policy-autodownload.test.ts — covered by hydrate-from's preFetch:'auto-download-files' test
• 3.9 tests/retention-lru.test.ts — DEFERRED with cache-eviction work
• 3.10 tests/retention-max-age.test.ts — DEFERRED with cache-eviction work
• 3.11 tests/inline-key-unlock.test.ts — covered by retroactive-key-grant; inline (sealed-box) key unwrap lives on @suaveplan/crypto not drive
• 3.12 tests/list-with-presence.test.ts — covered by getKeyStatus / getPresence direct tests; Drive.list enrichment ships with the chunks-plugin integration

4. Pre-archive verification

• 4.1 bunx turbo lint typecheck test --filter=@suaveplan/drive — green (88 tests across 13 files)
• 4.2 bunx turbo test:coverage --filter=@suaveplan/drive — 100/100/100/100
• 4.3 bunx turbo build --filter=@suaveplan/drive — green
• 4.4 bunx turbo lint typecheck test:coverage --filter=@suaveplan/drive-template — green (drive-template's verify catch arms restored with injectable verifyFn per AGENTS.md §7a; verify-catch-arms.test.ts exercises the catch path)
• 4.5 bun run docs:check --filter=@suaveplan/drive — every implementation .ts has a sibling ≥200-word .md (pre-existing stub docs were filled in as part of this change)

5. AGENTS.md additions (cross-cutting)

• 5.1 §2b "NEVER ship stubs, placeholders, or work-in-progress code" added to openspec/AGENTS.md
• 5.2 §7a "Never delete code that serves a purpose to make tests / coverage pass" added to openspec/AGENTS.md
• 5.3 §7's "Tautological tests" bullet strengthened with explicit expect(true).toBe(true) ban + reviewer guidance

6. Archive

• 6.1 Move openspec/changes/drive-template-drive-surface/ → openspec/archive/2026-05-04-drive-template-drive-surface/
• 6.2 Update CLAUDE.md @suaveplan/drive package bullet with new surface
• 6.3 Refresh MANIFEST.md