# Tasks — extend-crypto-vault-orchestration

## 1. Scaffold

- [ ] 1.1 Add `src/orchestration/` directory; new files `orchestration.ts`, `orchestration.test.ts`, `orchestration.md`, `orchestration.types.ts`, `orchestration.spec-conformance.test.ts`, `index.ts`
- [ ] 1.2 Update `package.json` `exports`: add `./orchestration/orchestration` subpath
- [ ] 1.3 Add `@suaveplan/storage: workspace:^` to dependencies (if not already declared)
- [ ] 1.4 Re-run `bun install`

## 2. Error codes (additive — extend existing registry)

- [ ] 2.1 Add `CRYPTO_VAULT_DECRYPT_FAILED`, `CRYPTO_VAULT_PUBLIC_KEY_SIGNATURE_INVALID`, `CRYPTO_VAULT_STORAGE_KEY_NOT_FOUND`, `CRYPTO_VAULT_INVALID_VERSION` to `src/errors/`
- [ ] 2.2 Update the existing `errors/index.ts` to re-export new codes
- [ ] 2.3 Update `src/errors/errors.test.ts` (or equivalent) to cover new code shapes

## 3. Implementation

- [ ] 3.1 `src/orchestration/orchestration.types.ts` — `RootKeysResult`, `ServerKeysResult`, `CreateRootKeysOptions`, `CreateServerKeysOptions`, `RollServerKeysOptions`, `PackVaultOptions`
- [ ] 3.2 `src/orchestration/orchestration.ts` — 9 exported async functions:
  - `createRootKeys(password, options?)`
  - `createServerKeys(rootKeys, serverPassword, options?)`
  - `rollServerKeys(rootKeys, currentVersion, serverPassword, options?)`
  - `openVault(vaultBytes, password)`
  - `packVault(keychain, password, options?)`
  - `viewPublicKeys(publicKeyBytes, optionalSignKey?)`
  - `saveVaultToStorage(storage, key, vaultBytes)`
  - `savePublicKeysToStorage(storage, key, publicKeyBytes)`
  - `getDataFromStorage(storage, key)`
- [ ] 3.3 `src/orchestration/orchestration.md` — ≥200 words, Purpose / Features / Usage:Basic / Usage:Advanced / API Reference / Implementation Notes
- [ ] 3.4 `src/orchestration/index.ts` — named re-exports only
- [ ] 3.5 Update root `src/index.ts` to re-export the orchestration surface by name

## 4. Tests

- [ ] 4.1 `src/orchestration/orchestration.test.ts` covers every scenario in the spec delta (use `@suaveplan/storage`'s in-memory store for the storage-helper tests; real Argon2id for the KDF)
- [ ] 4.2 `src/orchestration/orchestration.spec-conformance.test.ts` pins (a) every new error code thrown from a production path, (b) `expectTypeOf` on every exported function signature
- [ ] 4.3 `tests/dep-graph.test.ts` (or extend existing) asserts the new subpath export is reachable and `orchestration.ts` has a sibling `.md`
- [ ] 4.4 Every `it(...)` carries `{ timeout: 5000 }` (or 30000 for Argon2id-heavy tests; use the low-iteration test profile from `DEFAULT_ARGON2ID_PARAMS` for unit tests)
- [ ] 4.5 All tests import runner from `@suaveplan/testing/runner`

## 5. Gates

- [ ] 5.1 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-vault` — green
- [ ] 5.2 `bunx turbo test:coverage --filter=@suaveplan/crypto-vault` — 100/100/100/100
- [ ] 5.3 `bun scripts/openspec-conformance.ts @suaveplan/crypto-vault` — exit 0
- [ ] 5.4 `bunx turbo build --filter=@suaveplan/crypto-vault` — green
- [ ] 5.5 `bunx turbo test --filter=...@suaveplan/crypto-vault` — dependent sweep green (foundation package)
- [ ] 5.6 Banned-pattern scan (0 hits, JSDoc-prose `any` ok)
- [ ] 5.7 No `export *` in `orchestration/index.ts`
- [ ] 5.8 No direct `vitest`/`bun:test` imports

## 6. Archive

- [ ] 6.1 Fold `specs/crypto-vault/spec.md` ADDED Requirements into the canonical `openspec/specs/crypto-vault/spec.md` (append; don't replace)
- [ ] 6.2 Move `openspec/changes/extend-crypto-vault-orchestration/` → `openspec/archive/2026-05-17-extend-crypto-vault-orchestration/`
- [ ] 6.3 Refresh `MANIFEST.md`