suaveplan/openspec/archive/2026-05-18-extend-crypto-vault-orchestration/tasks.md

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