suaveplan/openspec/archive/2026-04-29-vault/tasks.md

Tasks — vault

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened.

1. Spec authoring

• 1.1 Read MIGRATION.md Section 7 (Vault Orchestration Layer) and Section 8
• 1.2 Read openspec/AGENTS.md Sections 13 and 14
• 1.3 Draft proposal.md from openspec/templates/proposal.md
• 1.4 Draft specs/vault/spec.md from openspec/templates/spec-delta.md
• 1.5 Every requirement carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Scaffold package at packages/vault/vault with package.json, tsconfig.json, vitest.config.ts
• 2.2 Implement Vault class: Vault.open(config), unlock(password, secretKey), lock(), isLocked
• 2.3 Implement vault.items delegation: create, get, update, delete, list, search → db-sqlite
• 2.4 Implement vault.attachments delegation: upload, download, delete → drive
• 2.5 Implement vault.shares delegation: createLink, revokeLink → drive-sharing
• 2.6 Implement vault.sync delegation: pull, push, sync → vault-sync
• 2.7 Implement field encryption: concealed fields encrypted with per-item key from crypto-vault
• 2.8 Implement error module: VaultError, structured error codes
• 2.9 Migrate VaultManager / VaultFactory from @suaveplan/keys into @suaveplan/vault — N/A on genesis. Amended 2026-05-03: @suaveplan/keys was never created on genesis; keypair / Keychain / Authority / low-level vault primitives already live under @suaveplan/crypto/keychain, @suaveplan/crypto/authority, and @suaveplan/crypto/vault. VaultManager / VaultFactory are authored fresh inside @suaveplan/vault consuming those existing surfaces. See proposal ## Why amendment block and ## Migration impact for the revised ownership matrix.
• 2.10 Add OpaqueKeyHandle wrapper for crypto-vault keys
• 2.11 Add rng?: Rng injection to Vault.open and Vault.unlock
• 2.12 Wire subpath exports in package.json for every feature module
• 2.13 Add README.md with quick-start, modules list, and install instruction

3. Tests

• 3.1 Unit tests at src/vault/vault.test.ts covering lifecycle, state transitions, zeroization
• 3.2 Unit tests at src/items/items.test.ts covering CRUD, encryption, history, validation
• 3.3 Unit tests at src/search/search.test.ts covering FTS5 delegation and filter correctness
• 3.4 Unit tests at src/attachments/attachments.test.ts covering upload/download round-trip
• 3.5 Unit tests at src/shares/shares.test.ts covering link creation, revocation, key exclusion
• 3.6 Unit tests at src/sync/sync.test.ts covering pull/push/bidirectional delegation
• 3.7 Spec-conformance tests at src/spec-conformance.test.ts pinning type-level / strict-mode scenarios
• 3.8 Integration tests verifying vault + crypto-vault + db-sqlite + drive end-to-end
• 3.9 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely async)

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 4.2 README links every co-located .md under ## Modules
• 4.3 Update CLAUDE.md package listing if this is a new package
• 4.4 Update @suaveplan/keys sibling docs to remove vault-related references — N/A on genesis (no @suaveplan/keys package exists; see §2.9 amendment).
• 4.5 Update @suaveplan/keys tests to remove VaultManager/VaultFactory coverage — N/A on genesis (see §2.9 amendment).
• 4.6 Add deprecation re-exports in @suaveplan/keys for one minor version — N/A on genesis (see §2.9 amendment).
• 4.7 Update keys sibling .md docs to reflect reduced scope — N/A on genesis (see §2.9 amendment).

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/vault — green (167 tests pass across 16 files)
• 5.3 bunx turbo test:coverage --filter=@suaveplan/vault — 100/100/100/100 (statements/branches/functions/lines)
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/vault — exit 0, 0 errors (2 schemas-at-boundaries warnings on VaultItemSchema and ManifestArgon2idSchema are advisory; both schemas are part of the public surface for downstream consumers)
• 5.5 bunx turbo build --filter=@suaveplan/vault — green

6. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 Zod schemas wired at every declared boundary
• 6.3 Every error code in error-codes.ts thrown by at least one production path
• 6.4 Strict-mode behaviors tested both on and off
• 6.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 6.6 Lifecycle dedup tested where claimed (in-flight Promise, idempotent set/load)
• 6.7 No retroactive tick — every box above reflects work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/vault/spec.md
• 7.2 Move openspec/changes/vault/ → openspec/archive/2026-04-29-vault/
• 7.3 Refresh MANIFEST.md if package set or deps changed