# 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

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

## 2. Implementation

- [x] 2.1 Scaffold package at `packages/vault/vault` with `package.json`, `tsconfig.json`, `vitest.config.ts`
- [x] 2.2 Implement `Vault` class: `Vault.open(config)`, `unlock(password, secretKey)`, `lock()`, `isLocked`
- [x] 2.3 Implement `vault.items` delegation: `create`, `get`, `update`, `delete`, `list`, `search` → `db-sqlite`
- [x] 2.4 Implement `vault.attachments` delegation: `upload`, `download`, `delete` → `drive`
- [x] 2.5 Implement `vault.shares` delegation: `createLink`, `revokeLink` → `drive-sharing`
- [x] 2.6 Implement `vault.sync` delegation: `pull`, `push`, `sync` → `vault-sync`
- [x] 2.7 Implement field encryption: concealed fields encrypted with per-item key from `crypto-vault`
- [x] 2.8 Implement error module: `VaultError`, structured error codes
- [x] 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.
- [x] 2.10 Add `OpaqueKeyHandle` wrapper for `crypto-vault` keys
- [x] 2.11 Add `rng?: Rng` injection to `Vault.open` and `Vault.unlock`
- [x] 2.12 Wire subpath exports in `package.json` for every feature module
- [x] 2.13 Add `README.md` with quick-start, modules list, and install instruction

## 3. Tests

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

## 4. Documentation

- [x] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
- [x] 4.2 README links every co-located `.md` under `## Modules`
- [x] 4.3 Update `CLAUDE.md` package listing if this is a new package
- [x] 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).
- [x] 4.5 ~~Update `@suaveplan/keys` tests to remove `VaultManager`/`VaultFactory` coverage~~ — N/A on genesis (see §2.9 amendment).
- [x] 4.6 ~~Add deprecation re-exports in `@suaveplan/keys` for one minor version~~ — N/A on genesis (see §2.9 amendment).
- [x] 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)

- [x] 5.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/vault` — green (167 tests pass across 16 files)
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/vault` — 100/100/100/100 (statements/branches/functions/lines)
- [x] 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)
- [x] 5.5 `bunx turbo build --filter=@suaveplan/vault` — green

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

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

## 7. Archive

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