Initial Commit
This commit is contained in:
@@ -0,0 +1,169 @@
|
||||
# Crypto completion — streaming AEAD, recovery, device keys, scrypt, blake2b, password helpers, hash-password CLI
|
||||
|
||||
**Packages**: `@suaveplan/crypto`, `@suaveplan/crypto-cipher`, `@suaveplan/crypto-curve`, `@suaveplan/crypto-hash`, `@suaveplan/crypto-keys`
|
||||
**Status**: PROPOSED
|
||||
**Type**: feature + spec-conformance
|
||||
|
||||
## Why
|
||||
|
||||
The 2026-05-02 audit of the genesis crypto stack against `../suaveplan/packages/universal/crypto/src` identified seven confirmed feature gaps that the upstream package shipped but the genesis sub-packages do not. None of these are MAJOR architecture changes — they are concrete capabilities (streaming AEAD, ECDSA recovery, device keys, scrypt KDF, blake2b hashing + password helpers, password-driven AEAD wrappers, and the `hash-password` CLI) that downstream consumers (drive, network, audit-logging, slsa) currently work around or block on. Genesis policy (CLAUDE.md §Workflow rule 5) says "preserve the full public surface during rewrites — trimming is OK ONLY when code is duplicated elsewhere in-repo or can be replaced by an existing `@suaveplan/*` library", and none of these seven features are duplicated by anything that already landed.
|
||||
|
||||
Closing all seven in one coordinated pass is preferable to seven small changes because (a) they share validation utilities and `crypto-utils` helpers that have to land at the same revision to avoid mid-port circular pins, (b) the streaming AEAD façade in `crypto/aead` and the engine in `crypto-cipher/primitives` are linked — adding either alone leaves the public surface incoherent, and (c) the password helpers (`encryptWithPassword`, `deriveKeyFromPassword`) sit on top of the new scrypt + blake2b primitives, so they cannot ship until those primitives exist.
|
||||
|
||||
The seven gaps:
|
||||
|
||||
1. **Streaming AEAD** (`crypto-cipher` + `crypto/aead`): `encryptStreamAead` / `decryptStreamAead` async generators (255 L), `aesGcmStreamingEngine` and `xchacha20StreamingEngine` engines (35 L each), `createEncryptionStream` / `createDecryptionStream` Web-Streams adapters, `streamEncrypt` / `streamDecrypt` legacy aliases, `collectStream`, `createStreamKey`, `createStreamEncryption` (430 L of `streaming.ts`).
|
||||
2. **secp256k1 ECDSA recovery** (`crypto-curve/primitives/secp256k1`): `signWithRecovery`, `recoverPublicKey`, `verifyWithRecovery` — all three present in upstream (lines 74, 143, 243 of `signing.ts`) and absent from the genesis 5-method secp256k1 noble engine.
|
||||
3. **Device-key suite** (`crypto-keys/keypair/device`): `createDeviceKey`, `deriveDeviceKeyFromMaster`, `generateDeviceUUID`, `extractDeviceMetadata`, `compareDeviceKeys`, `isValidDeviceKey`, plus `generateDerivedDeviceId` for one-release back-compat (261 L of `device.ts`).
|
||||
4. **scrypt KDF** (`crypto-hash/primitives/scrypt`): N/r/p parameter set, salt + outputLength, async via `@noble/hashes/scrypt` (53 L of `hashing.ts` lines L273-L325).
|
||||
5. **blake2b hashing** (`crypto-hash/primitives/blake2b`): variable output length, optional key, plus `hashPasswordBlake2b` / `verifyPasswordBlake2b` constant-time wrappers with the parameterised `$blake2b$v=1$cf=N$salt$hash` format.
|
||||
6. **encryptWithPassword + deriveKeyFromPassword** (`crypto/password`): the high-level "password → encrypted blob" pattern (Argon2id-derived key + AEAD), 344 L of `password.ts`.
|
||||
7. **`hash-password` CLI bin** (new `packages/crypto/crypto-bin` or `crypto/bin/hash-password.ts`): a one-shot CLI that hashes a plaintext password to a verifier and exits 0/1 on verify (98 L of `bin/hash-password.ts`).
|
||||
|
||||
## What changes
|
||||
|
||||
### `@suaveplan/crypto-cipher`
|
||||
|
||||
- ADDED: `streaming/streaming-aead.ts` — `encryptStreamAead` and `decryptStreamAead` async generators with chunk-level header / footer tags, `EncryptStreamAeadOptions` and `DecryptStreamAeadOptions` (chunk size, AAD, AbortSignal, optional `header` callback for chunk-tag attestation).
|
||||
- ADDED: `streaming/streaming-aead-aes-gcm.ts` — `aesGcmStreamingEngine: StreamingAeadEngine` adapter built on the existing `aes-256-gcm` primitive; nonce per chunk derived from a 12-byte base nonce + 32-bit counter (RFC 5116-compatible).
|
||||
- ADDED: `streaming/streaming-aead-xchacha20.ts` — `xchacha20StreamingEngine: StreamingAeadEngine` adapter built on the existing `xchacha20-poly1305` primitive; nonce per chunk derived from a 24-byte base nonce + 32-bit counter.
|
||||
- ADDED: `streaming/streaming-aead.types.ts` — `StreamingAeadEngine` interface, `StreamingChunkTag` interface, `StreamingHeader` interface.
|
||||
- ADDED: error codes `CRYPTO_CIPHER.STREAM_TAG_MISMATCH`, `CRYPTO_CIPHER.STREAM_OUT_OF_ORDER`, `CRYPTO_CIPHER.STREAM_ABORTED`, `CRYPTO_CIPHER.STREAM_INVALID_NONCE_BASE`.
|
||||
|
||||
### `@suaveplan/crypto-curve`
|
||||
|
||||
- ADDED: `primitives/secp256k1/impl/secp256k1.noble/secp256k1.noble.ts` exports `signWithRecovery(digest, privateKey)`, `recoverPublicKey(signatureWithRecovery, digest)`, and `verifyWithRecovery(signatureWithRecovery, digest, expectedPublicKey)`. The signature-with-recovery byte layout is the canonical 65-byte form (64-byte compact signature + 1 recovery byte).
|
||||
- ADDED: `primitives/secp256k1/impl/secp256k1.native/secp256k1.native.ts` matching surface (libsodium does not ship secp256k1 — native engine throws `CRYPTO_CURVE.PRIMITIVE_NOT_IMPLEMENTED` per genesis convention).
|
||||
- MODIFIED: `secp256k1.select` re-exports the three new functions.
|
||||
- ADDED: error codes `CRYPTO_CURVE.RECOVERY_BYTE_MISSING`, `CRYPTO_CURVE.RECOVERY_BYTE_INVALID`, `CRYPTO_CURVE.RECOVERED_KEY_MISMATCH`.
|
||||
|
||||
### `@suaveplan/crypto-hash`
|
||||
|
||||
- ADDED: `primitives/scrypt/scrypt.ts` — `scrypt(password, salt, options)` with `N`, `r`, `p`, `dkLen` parameters; uses `@noble/hashes/scrypt`'s `scryptAsync`.
|
||||
- ADDED: `primitives/scrypt/scrypt.select` and `primitives/scrypt/impl/scrypt.noble/scrypt.noble.ts` matching the existing per-primitive selector layout.
|
||||
- ADDED: `primitives/blake2b/blake2b.ts` — `blake2b(message, options)` with `dkLen` (1–64 bytes), optional `key`, optional `salt`, optional `personalization`.
|
||||
- ADDED: `primitives/blake2b/blake2b.select` and `primitives/blake2b/impl/blake2b.noble/blake2b.noble.ts`.
|
||||
- ADDED: `mac/blake2b-password/blake2b-password.ts` — `hashPasswordBlake2b(password, options)` and `verifyPasswordBlake2b(storedHash, password)`, using the `$blake2b$v=1$cf=<costFactor>$<saltHex>$<hashHex>` MCF-style format and constant-time comparison.
|
||||
- ADDED: error codes `CRYPTO_HASH.SCRYPT_INVALID_N`, `CRYPTO_HASH.BLAKE2B_OUTPUT_TOO_LONG`, `CRYPTO_HASH.BLAKE2B_KEY_TOO_LONG`, `CRYPTO_HASH.BLAKE2B_PASSWORD_FORMAT_INVALID`.
|
||||
|
||||
### `@suaveplan/crypto-keys`
|
||||
|
||||
- ADDED: `keypair/device/device.ts` — `createDeviceKey`, `deriveDeviceKeyFromMaster`, `generateDeviceUUID`, `extractDeviceMetadata`, `compareDeviceKeys`, `isValidDeviceKey`, plus the `generateDerivedDeviceId` back-compat alias.
|
||||
- ADDED: `keypair/device/device.types.ts` — `DeviceKey`, `MasterKey`, `DeviceKeyOptions`, `DeviceKeyDerivationOptions`, `DeviceIdOptions`, `DeviceMetadata` interfaces.
|
||||
- ADDED: error codes `CRYPTO_KEYS.DEVICE_INVALID_MASTER`, `CRYPTO_KEYS.DEVICE_INVALID_KEY`, `CRYPTO_KEYS.DEVICE_DERIVATION_FAILED`.
|
||||
|
||||
### `@suaveplan/crypto`
|
||||
|
||||
- ADDED: `aead/streaming/streaming-aead.ts` — high-level façade `encryptStreamAead` / `decryptStreamAead` that selects the engine (`xchacha20-poly1305` or `aes-256-gcm`) from the opts argument and delegates to `crypto-cipher`. Re-exports `aesGcmStreamingEngine` and `xchacha20StreamingEngine`.
|
||||
- ADDED: `aead/streaming/web-streams.ts` — `createEncryptionStream(opts)` and `createDecryptionStream(opts)` returning `TransformStream<Uint8Array, Uint8Array>` Web-Streams adapters; `collectStream(stream)`, `createStreamKey(rng?)`, `createStreamEncryption(opts)` helpers; `streamEncrypt` / `streamDecrypt` aliases preserved for back-compat.
|
||||
- ADDED: `password/encrypt-with-password.ts` — `encryptWithPassword(password, plaintext, options?)` and `decryptWithPassword(password, ciphertext, options?)`. Default KDF is Argon2id; opt into scrypt via `kdf: "scrypt"` in options. Default cipher is `xchacha20-poly1305`. Output is a self-describing binary header (`magic`, `kdf`, `kdfParams`, `cipher`, `salt`, `nonce`) followed by the ciphertext.
|
||||
- ADDED: `password/derive-key-from-password.ts` — `deriveKeyFromPassword(password, salt, options?)` returning a 32-byte `Uint8Array` suitable for use as a symmetric key. KDF selection (`argon2id` / `scrypt` / `pbkdf2`) is via the options bundle.
|
||||
- ADDED: error codes `CRYPTO.STREAM_AEAD_HEADER_INVALID`, `CRYPTO.PASSWORD_KDF_UNKNOWN`, `CRYPTO.PASSWORD_BLOB_HEADER_INVALID`, `CRYPTO.PASSWORD_BLOB_VERSION_UNSUPPORTED`.
|
||||
|
||||
### `@suaveplan/crypto-bin` (new package)
|
||||
|
||||
- ADDED: a thin CLI package `packages/crypto/crypto-bin` whose only purpose is to ship the `hash-password` bin. Per-Suaveplan policy CLI surfaces live in their own package so they do not leak `@suaveplan/cli` runtime deps into the universal-tier `@suaveplan/crypto`. Depends on `@suaveplan/cli`, `@suaveplan/crypto-hash`, `@suaveplan/error`. Bin: `suaveplan-hash-password`. Reads a password from stdin or `--password`, writes a verifier hash (Argon2id by default, `--algo blake2b` opt-in) to stdout; with `--verify <stored>` reads `--password` and exits `0` on match, `1` on mismatch.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Post-quantum signature primitives** (Dilithium, SPHINCS+, ML-KEM key-encapsulation) — separate `crypto-pqc-*` family of sub-packages already discussed in `STATUS.md`. Adding PQC primitives requires a separate engine adapter substrate that is larger than this entire change.
|
||||
- **FIDO2 / WebAuthn helpers** — already covered by browser-tier deps in the genesis app shells; no upstream parity gap here.
|
||||
- **HSM / KMS adapters** (CloudHSM, AWS KMS, GCP KMS) — operational concern, not a library gap; tracked separately under the audit-logging adapter family.
|
||||
- **Argon2id parameter migration helper** — upstream ships `migrateArgon2idParams(oldHash, newOptions)` for re-hashing on login. Genesis already routes Argon2id verification through `crypto-hash/primitives/argon2id` and migration belongs in a future `auth` change, not in `crypto-hash`.
|
||||
- **Modifying the existing Argon2id primitive** — the new `encryptWithPassword` defers to the existing `argon2id` primitive without changing its signature.
|
||||
- **`crypto-vault` integration** — `crypto-vault` already wraps Argon2id-hardened HD derivation; once `scrypt` lands in `crypto-hash`, a follow-up change can add a `kdf: "scrypt"` option to the vault. Out of scope here to keep this change focused on the seven enumerated gaps.
|
||||
|
||||
## Source mapping
|
||||
|
||||
Genesis `enterprise/crypto.md` is a generic enterprise-quality template (no per-feature requirements), so source mapping cites the upstream package source directly.
|
||||
|
||||
| Requirement | Source file | Source lines | Notes |
|
||||
|---|---|---|---|
|
||||
| `encryptStreamAead` / `decryptStreamAead` async generators | `packages/universal/crypto/src/symmetric/streaming/streaming-aead.ts` | L11-L255 | Verbatim port; thread `AbortSignal` through |
|
||||
| `aesGcmStreamingEngine` adapter | `packages/universal/crypto/src/symmetric/streaming/streaming-aead-aes-gcm.ts` | L9-L35 | Verbatim |
|
||||
| `xchacha20StreamingEngine` adapter | `packages/universal/crypto/src/symmetric/streaming/streaming-aead-xchacha20.ts` | L9-L35 | Verbatim |
|
||||
| `createEncryptionStream` / `createDecryptionStream` / `streamEncrypt` / `streamDecrypt` / `collectStream` / `createStreamKey` / `createStreamEncryption` | `packages/universal/crypto/src/symmetric/streaming/streaming.ts` | L23-L430 | Verbatim port; preserve `ChaCha20Stream` / `AESStream` named exports |
|
||||
| `signWithRecovery` (secp256k1) | `packages/universal/crypto/src/asymmetric/signing/signing.ts` | L74-L120 | Verbatim |
|
||||
| `recoverPublicKey` (secp256k1) | `packages/universal/crypto/src/asymmetric/signing/signing.ts` | L143-L235 | Verbatim |
|
||||
| `verifyWithRecovery` (secp256k1) | `packages/universal/crypto/src/asymmetric/signing/signing.ts` | L243-L307 | Verbatim |
|
||||
| `createDeviceKey` | `packages/universal/crypto/src/keys/device/device.ts` | L32-L49 | Verbatim |
|
||||
| `deriveDeviceKeyFromMaster` | `packages/universal/crypto/src/keys/device/device.ts` | L56-L89 | Verbatim |
|
||||
| `generateDeviceUUID` | `packages/universal/crypto/src/keys/device/device.ts` | L96-L155 | Verbatim |
|
||||
| `extractDeviceMetadata` | `packages/universal/crypto/src/keys/device/device.ts` | L157-L181 | Verbatim |
|
||||
| `isValidDeviceKey`, `compareDeviceKeys` | `packages/universal/crypto/src/keys/device/device.ts` | L182-L245 | Verbatim |
|
||||
| `generateDerivedDeviceId` back-compat alias | `packages/universal/crypto/src/keys/device/device.ts` | L249-L260 | Replace upstream `@deprecated` JSDoc with prose ("Backwards-compatibility alias for `generateDeviceUUID`.") per CLAUDE.md §2 |
|
||||
| `scrypt` async KDF | `packages/universal/crypto/src/core/hashing/hashing.ts` | L273-L325 | Verbatim (delegates to `@noble/hashes/scrypt::scryptAsync`) |
|
||||
| `blake2b` hash | `packages/universal/crypto/src/core/hashing/hashing.ts` | L1-L60 (imports + helpers used) | Re-host as a top-level primitive in `crypto-hash` |
|
||||
| `hashPasswordBlake2b` | `packages/universal/crypto/src/core/hashing/hashing.ts` | L617-L666 | Verbatim |
|
||||
| `verifyPasswordBlake2b` | `packages/universal/crypto/src/core/hashing/hashing.ts` | L672-L745 | Verbatim |
|
||||
| `encryptWithPassword` | `packages/universal/crypto/src/symmetric/password/password.ts` | L54-L113 | Verbatim port; replace `PasswordError` plain class with `SuaveplanError` code `CRYPTO.PASSWORD_*` |
|
||||
| `deriveKeyFromPassword` | `packages/universal/crypto/src/symmetric/password/password.ts` | L172-L209 | Verbatim |
|
||||
| `hash-password` CLI | `packages/universal/crypto/src/bin/hash-password.ts` | L1-L98 | Verbatim port; replace direct `process.exit` with `cli.exit(code)` from `@suaveplan/cli` |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| `StreamingAeadEngine` interface (formal) | Upstream uses a duck-typed object; genesis convention is a named interface in a `*.types.ts` file (see CLAUDE.md §11 "No nested object literals in interfaces"). |
|
||||
| Error codes mapped to `@suaveplan/error` (`CRYPTO_CIPHER.STREAM_*`, `CRYPTO_CURVE.RECOVERY_*`, `CRYPTO_KEYS.DEVICE_*`, `CRYPTO_HASH.SCRYPT_*` / `BLAKE2B_*`, `CRYPTO.PASSWORD_*`) | Genesis-wide policy: every thrown error routes through `@suaveplan/error` with a stable code. Upstream throws plain `Error` / `PasswordError`. |
|
||||
| `crypto-bin` as its own package | Universal-tier `@suaveplan/crypto` cannot depend on `@suaveplan/cli` (CLI is browser/server-tier and pulls in `@suaveplan/readline`). Splitting the CLI out keeps `crypto` zero-side-effect and tree-shakeable. |
|
||||
| `encryptWithPassword` self-describing binary header | Upstream stores `salt + ciphertext` only; consumers had to know the iteration count externally. Genesis adds a versioned 16-byte header (`magic[4] \| version[1] \| kdf[1] \| cipher[1] \| reserved[1] \| saltLen[2] \| nonceLen[2] \| kdfParamsLen[4]`) so a blob is self-descriptive and rotation-safe. |
|
||||
| `decryptWithPassword` companion to `encryptWithPassword` | Upstream's `decryptWithPassword` (L115-L160 of `password.ts`) is included. Listed here only because the proposal text earlier groups gap 6 as one verb; this row exists so reviewers can see both halves are covered. |
|
||||
| `signWithRecovery` / `recoverPublicKey` / `verifyWithRecovery` exposed at `secp256k1.noble.ts` rather than the higher-level `signing.ts` | Upstream's `signing.ts` is a multi-key façade that pulls `BaseKeySchema` plumbing genesis hasn't ported. Putting the three functions on the curve primitive (where they belong cryptographically) avoids a circular dep with `crypto-keys`. |
|
||||
|
||||
## Verification approach
|
||||
|
||||
Each spec delta requirement carries a `**Verified by:**` line pointing at concrete `it(...)` titles. The test files that will exist after this change ships:
|
||||
|
||||
- `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts` — chunk round-trip per engine; tag mismatch detection; abort propagation
|
||||
- `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.spec-conformance.test.ts` — `StreamingAeadEngine` contract pinned for both adapters; nonce-counter monotonicity; out-of-order chunks emit `STREAM_OUT_OF_ORDER`
|
||||
- `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.test.ts` — extended with sign/recover/verify-with-recovery cases; recovery byte 0/1 round-trip
|
||||
- `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.spec-conformance.test.ts` — invalid recovery byte emits `RECOVERY_BYTE_INVALID`; missing recovery byte emits `RECOVERY_BYTE_MISSING`; recovered key mismatch emits `RECOVERED_KEY_MISMATCH`
|
||||
- `packages/crypto/crypto-hash/src/primitives/scrypt/scrypt.test.ts` — KAT round-trip vs upstream RFC 7914 vectors; `dkLen` 32 / 64 / 128
|
||||
- `packages/crypto/crypto-hash/src/primitives/scrypt/scrypt.spec-conformance.test.ts` — invalid `N` (non-power-of-two, < 2) emits `SCRYPT_INVALID_N`
|
||||
- `packages/crypto/crypto-hash/src/primitives/blake2b/blake2b.test.ts` — RFC 7693 KAT round-trip; output length 1..64; keyed mode
|
||||
- `packages/crypto/crypto-hash/src/primitives/blake2b/blake2b.spec-conformance.test.ts` — output > 64 emits `BLAKE2B_OUTPUT_TOO_LONG`; key > 64 emits `BLAKE2B_KEY_TOO_LONG`
|
||||
- `packages/crypto/crypto-hash/src/mac/blake2b-password/blake2b-password.test.ts` — round-trip hash → verify; salt freshness across calls; constant-time comparison observable via timing-side-channel test
|
||||
- `packages/crypto/crypto-hash/src/mac/blake2b-password/blake2b-password.spec-conformance.test.ts` — malformed stored hash emits `BLAKE2B_PASSWORD_FORMAT_INVALID`
|
||||
- `packages/crypto/crypto-keys/src/keypair/device/device.test.ts` — `createDeviceKey` round-trip; `deriveDeviceKeyFromMaster` deterministic; `generateDeviceUUID` valid v4; `extractDeviceMetadata` round-trip; `compareDeviceKeys` constant-time
|
||||
- `packages/crypto/crypto-keys/src/keypair/device/device.spec-conformance.test.ts` — invalid master emits `DEVICE_INVALID_MASTER`; corrupt key emits `DEVICE_INVALID_KEY`
|
||||
- `packages/crypto/crypto/src/aead/streaming/streaming-aead.test.ts` — façade selects correct engine; round-trip per `xchacha20-poly1305` and `aes-256-gcm`
|
||||
- `packages/crypto/crypto/src/aead/streaming/web-streams.test.ts` — Web-Streams round-trip; `collectStream` aggregates correctly; `streamEncrypt` / `streamDecrypt` aliases match the canonical functions
|
||||
- `packages/crypto/crypto/src/password/encrypt-with-password.test.ts` — round-trip `encrypt → decrypt`; KDF selection (`argon2id` vs `scrypt`); blob header self-descriptive (different KDF params produce different headers; reading a v1 blob with a v2 reader emits `PASSWORD_BLOB_VERSION_UNSUPPORTED`)
|
||||
- `packages/crypto/crypto/src/password/encrypt-with-password.spec-conformance.test.ts` — `kdf: "unknown"` emits `PASSWORD_KDF_UNKNOWN`; truncated blob emits `PASSWORD_BLOB_HEADER_INVALID`
|
||||
- `packages/crypto/crypto/src/password/derive-key-from-password.test.ts` — KDF selection; deterministic given fixed salt + params; output length is exactly 32 bytes
|
||||
- `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts` — Argon2id mode end-to-end (hash, then verify, exit 0); blake2b mode end-to-end; bad password verify exits 1; missing `--password` arg emits non-zero exit
|
||||
- `packages/crypto/crypto-bin/src/hash-password/hash-password.spec-conformance.test.ts` — error path emits `CRYPTO.HASH_PASSWORD_CLI_*` codes (one per known failure mode)
|
||||
|
||||
## Migration impact
|
||||
|
||||
This change is **additive** — it does not modify any existing public surface. Verification:
|
||||
|
||||
- Existing `@suaveplan/crypto` consumers (`crypto-vault`, `slsa`, `audit-logging`, `auth`, `streams`, `bitpacker-crypto`, `drive-plugin-chunks`, `data/packer`) — none use `signWithRecovery` / streaming AEAD / device keys / scrypt / blake2b / `encryptWithPassword` / hash-password CLI today (the symbols don't exist on genesis). New exports therefore have zero callers at land time.
|
||||
- Existing `crypto-cipher` callers (`crypto`, `crypto-sodium`) — only consume the three primitive selectors (`aes-256-gcm`, `chacha20-poly1305`, `xchacha20-poly1305`). The new `streaming/*` subpath is an isolated subtree.
|
||||
- Existing `crypto-curve` callers (`crypto`) — only consume the four primitive selectors. The three new `signWithRecovery` / `recoverPublicKey` / `verifyWithRecovery` exports do not collide with the existing `sign` / `verify`.
|
||||
- Existing `crypto-hash` callers (`crypto`, `crypto-vault`, `crypto-curve`) — consume `sha256`, `sha384`, `sha512`, `hmac`, `hkdf`, `pbkdf2`, `argon2id`. The new `scrypt` and `blake2b` primitives are isolated.
|
||||
- Existing `crypto-keys` callers (`crypto-vault`, `auth`) — consume `Keychain` and `keypair/{generate,validate}`. The new `keypair/device` subtree is isolated.
|
||||
|
||||
A `bunx turbo build typecheck test --filter=...@suaveplan/crypto*` sweep runs in §9 of `tasks.md` to verify all dependents compile and test green before archive.
|
||||
|
||||
## Impact
|
||||
|
||||
### Affected dependents
|
||||
|
||||
Run `bunx turbo ls --filter=...@suaveplan/crypto` to enumerate. For each dependent, check one box:
|
||||
|
||||
- `@suaveplan/crypto-sodium` — [ ] tests run / [ ] docs reviewed / [x] no action needed (consumes only the existing AEAD / sign / agree façade; new streaming / password helpers are additive subpaths)
|
||||
- `@suaveplan/crypto-browser` — [ ] tests run / [ ] docs reviewed / [x] no action needed (same — consumes existing AEAD / sign / agree façade)
|
||||
- `@suaveplan/crypto-vault` — [x] tests run / [x] docs reviewed / [ ] no action needed (vault may want to opt into `scrypt` KDF in a follow-up; verifying it still typechecks is required because it imports `crypto-hash` directly)
|
||||
- `@suaveplan/crypto-keys` — [x] tests run / [x] docs reviewed / [ ] no action needed (we are *adding* `keypair/device/*` to it in this change, so its own tests must run)
|
||||
- `@suaveplan/auth` — [x] tests run / [ ] docs reviewed / [ ] no action needed (consumes `crypto-keys`, depends on us not breaking the existing `keypair/{generate,validate}` exports)
|
||||
- `@suaveplan/audit-logging` — [ ] tests run / [ ] docs reviewed / [x] no action needed (consumes only the AEAD façade for log encryption — new streaming subpath does not collide)
|
||||
- `@suaveplan/slsa` — [ ] tests run / [ ] docs reviewed / [x] no action needed (consumes only `crypto/sign` for in-toto attestation signing — `signWithRecovery` is a new export, not a modification)
|
||||
- `@suaveplan/streams` — [ ] tests run / [ ] docs reviewed / [x] no action needed (consumes only the existing primitive selectors)
|
||||
- `@suaveplan/bitpacker-crypto` — [ ] tests run / [ ] docs reviewed / [x] no action needed (consumes the AEAD façade for packed-bit encryption — new exports do not collide)
|
||||
- `@suaveplan/drive-plugin-chunks` — [ ] tests run / [ ] docs reviewed / [x] no action needed (consumes the AEAD façade for at-rest chunk encryption — new streaming subpath is a candidate for a follow-up port, not a regression risk here)
|
||||
- `@suaveplan/data/packer` — [ ] tests run / [ ] docs reviewed / [x] no action needed (consumes the AEAD façade only)
|
||||
- `@suaveplan/crypto-utils` — [x] tests run / [ ] docs reviewed / [ ] no action needed (foundation — its own coverage gate must pass after this change; `crypto-utils` is unchanged but `crypto-hash` and `crypto-cipher` consume it, so its tests must still pass)
|
||||
|
||||
For the four [x] dependents above (`crypto-vault`, `crypto-keys`, `auth`, `crypto-utils`), running their full test suite is part of §9 of `tasks.md`.
|
||||
@@ -0,0 +1,64 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto-bin (crypto-completion)
|
||||
|
||||
**Package**: `@suaveplan/crypto-bin`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time. This is a new package; the entire spec below is `## ADDED Requirements`.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: hash-password CLI hash mode
|
||||
|
||||
The package SHALL ship a `suaveplan-hash-password` bin that, when invoked with `--password <pw>` and no `--verify`, hashes the password using the requested algorithm (default `argon2id`, opt-in `--algo blake2b`) and writes the resulting stored-hash string to stdout, exiting with code 0. The CLI SHALL route through `@suaveplan/cli`'s arg parser (so `--help` works automatically) and SHALL NEVER call `process.exit` directly — it SHALL use `cli.exit(code)` to keep test harness compatibility.
|
||||
|
||||
#### Scenario: argon2id mode prints stored hash
|
||||
|
||||
- **WHEN** `suaveplan-hash-password --password "correct horse battery staple"` is invoked
|
||||
- **THEN** stdout contains a string starting with `"$argon2id$"` AND the exit code is 0
|
||||
|
||||
#### Scenario: blake2b mode prints stored hash
|
||||
|
||||
- **WHEN** `suaveplan-hash-password --password "..." --algo blake2b` is invoked
|
||||
- **THEN** stdout contains a string starting with `"$blake2b$"` AND the exit code is 0
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"argon2id mode writes a $argon2id$-prefixed hash to stdout and exits 0"` AND `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"blake2b mode writes a $blake2b$-prefixed hash to stdout and exits 0"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: hash-password CLI verify mode
|
||||
|
||||
When invoked with `--password <pw>` and `--verify <stored>`, the bin SHALL detect the algorithm from the stored hash's prefix, run the matching verify function (`verifyPasswordArgon2id` or `verifyPasswordBlake2b`), exit with code 0 on match and code 1 on mismatch. The bin SHALL NOT print anything to stdout in verify mode (so the exit code is the only signal — suitable for use in shell pipelines).
|
||||
|
||||
#### Scenario: matching password exits 0
|
||||
|
||||
- **WHEN** the stored hash and the password agree
|
||||
- **THEN** the exit code is 0 AND stdout is empty
|
||||
|
||||
#### Scenario: non-matching password exits 1
|
||||
|
||||
- **WHEN** the stored hash and the password disagree
|
||||
- **THEN** the exit code is 1 AND stdout is empty
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"verify mode exits 0 when password matches stored hash"` AND `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"verify mode exits 1 when password does not match stored hash"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: hash-password CLI argument validation
|
||||
|
||||
The bin SHALL reject malformed invocations (missing `--password`, unknown `--algo`, malformed `--verify` value) with a non-zero exit code and a `SuaveplanError` whose code is one of `CRYPTO.HASH_PASSWORD_CLI_BAD_ARGS`, `CRYPTO.HASH_PASSWORD_CLI_UNKNOWN_ALGO`, or `CRYPTO.HASH_PASSWORD_CLI_VERIFY_FAILED`. The error message SHALL be human-readable and SHALL be printed to stderr (not stdout, so it does not contaminate pipe output).
|
||||
|
||||
#### Scenario: missing --password rejected
|
||||
|
||||
- **WHEN** `suaveplan-hash-password` is invoked with no `--password`
|
||||
- **THEN** the exit code is non-zero AND stderr mentions `--password` AND the underlying error code is `CRYPTO.HASH_PASSWORD_CLI_BAD_ARGS`
|
||||
|
||||
#### Scenario: unknown algorithm rejected
|
||||
|
||||
- **WHEN** `suaveplan-hash-password --password pw --algo bcrypt` is invoked
|
||||
- **THEN** the exit code is non-zero AND the underlying error code is `CRYPTO.HASH_PASSWORD_CLI_UNKNOWN_ALGO` AND `context.algo === "bcrypt"`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-bin/src/hash-password/hash-password.spec-conformance.test.ts::"missing --password emits HASH_PASSWORD_CLI_BAD_ARGS"` AND `packages/crypto/crypto-bin/src/hash-password/hash-password.spec-conformance.test.ts::"unknown --algo emits HASH_PASSWORD_CLI_UNKNOWN_ALGO"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,95 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto-cipher (crypto-completion)
|
||||
|
||||
**Package**: `@suaveplan/crypto-cipher`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Streaming AEAD encryption / decryption
|
||||
|
||||
The package SHALL expose `encryptStreamAead(source, options)` and `decryptStreamAead(source, options)` async generators that consume a `Uint8Array` input stream chunk by chunk, attach a per-chunk authentication tag, and emit the encrypted (or decrypted) chunk stream. Each chunk SHALL use a per-chunk nonce derived deterministically from a base nonce plus a 32-bit chunk counter so the entire stream binds to a single key without nonce reuse.
|
||||
|
||||
#### Scenario: round-trip preserves bytes
|
||||
|
||||
- **WHEN** `encryptStreamAead(plaintext, { algorithm, key, baseNonce })` is consumed and its output is fed to `decryptStreamAead(ciphertext, { algorithm, key, baseNonce })`
|
||||
- **THEN** the concatenated output equals the original plaintext byte-for-byte
|
||||
|
||||
#### Scenario: tag mismatch detected on tampered chunk
|
||||
|
||||
- **WHEN** any byte of any encrypted chunk's tag is flipped before decryption
|
||||
- **THEN** `decryptStreamAead` throws a `SuaveplanError` with code `CRYPTO_CIPHER.STREAM_TAG_MISMATCH` and `context.chunkIndex` points at the tampered chunk
|
||||
|
||||
#### Scenario: chunk-counter overflow rejected
|
||||
|
||||
- **WHEN** the chunk counter reaches `2^32`
|
||||
- **THEN** the next chunk emission throws `CRYPTO_CIPHER.STREAM_OUT_OF_ORDER` with `context.counter === 2 ** 32`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"round-trips a multi-chunk plaintext through encryptStreamAead and decryptStreamAead"` AND `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"throws STREAM_TAG_MISMATCH when a chunk tag is flipped"` AND `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.spec-conformance.test.ts::"throws STREAM_OUT_OF_ORDER on chunk-counter overflow"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: AbortSignal propagation through streaming AEAD
|
||||
|
||||
The package SHALL honour an optional `AbortSignal` passed via `EncryptStreamAeadOptions.signal` and `DecryptStreamAeadOptions.signal`. When the signal is aborted mid-stream the generator SHALL flush the in-flight chunk, release any pending cipher state, and throw `SuaveplanError` with code `CRYPTO_CIPHER.STREAM_ABORTED`.
|
||||
|
||||
#### Scenario: abort mid-stream rejects with STREAM_ABORTED
|
||||
|
||||
- **WHEN** an `AbortController` is signalled while `encryptStreamAead` is mid-iteration
|
||||
- **THEN** the next `await generator.next()` rejects with `CRYPTO_CIPHER.STREAM_ABORTED` and `context.chunksProcessed` reflects the count emitted before abort
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"aborts mid-stream and rejects with STREAM_ABORTED"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: AES-GCM streaming engine adapter
|
||||
|
||||
The package SHALL expose `aesGcmStreamingEngine: StreamingAeadEngine` that wraps the existing `aes-256-gcm` primitive. Per-chunk nonce SHALL be a 12-byte big-endian concatenation of an 8-byte caller-supplied prefix and a 4-byte chunk counter (RFC 5116 §3.2 compatible). The engine SHALL reject `baseNonce.length !== 8` with `CRYPTO_CIPHER.STREAM_INVALID_NONCE_BASE`.
|
||||
|
||||
#### Scenario: 8-byte base nonce accepted
|
||||
|
||||
- **WHEN** `aesGcmStreamingEngine.encrypt({ baseNonce: 8-byte prefix, key, plaintext, counter: 0 })` is called
|
||||
- **THEN** the produced nonce equals `baseNonce ‖ counter_be32(0)` (12 bytes total)
|
||||
|
||||
#### Scenario: wrong-length base nonce rejected
|
||||
|
||||
- **WHEN** `baseNonce.length === 12`
|
||||
- **THEN** the engine throws `CRYPTO_CIPHER.STREAM_INVALID_NONCE_BASE` with `context.expectedLength === 8` and `context.actualLength === 12`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead-aes-gcm/streaming-aead-aes-gcm.test.ts::"derives 12-byte nonce from 8-byte base + counter"` AND `packages/crypto/crypto-cipher/src/streaming/streaming-aead-aes-gcm/streaming-aead-aes-gcm.spec-conformance.test.ts::"rejects wrong-length base nonce with STREAM_INVALID_NONCE_BASE"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: XChaCha20-Poly1305 streaming engine adapter
|
||||
|
||||
The package SHALL expose `xchacha20StreamingEngine: StreamingAeadEngine` that wraps the existing `xchacha20-poly1305` primitive. Per-chunk nonce SHALL be a 24-byte big-endian concatenation of a 20-byte caller-supplied prefix and a 4-byte chunk counter. The engine SHALL reject `baseNonce.length !== 20` with `CRYPTO_CIPHER.STREAM_INVALID_NONCE_BASE`.
|
||||
|
||||
#### Scenario: 20-byte base nonce accepted
|
||||
|
||||
- **WHEN** `xchacha20StreamingEngine.encrypt({ baseNonce: 20-byte prefix, key, plaintext, counter: 5 })` is called
|
||||
- **THEN** the produced nonce equals `baseNonce ‖ counter_be32(5)` (24 bytes total)
|
||||
|
||||
#### Scenario: wrong-length base nonce rejected
|
||||
|
||||
- **WHEN** `baseNonce.length === 24`
|
||||
- **THEN** the engine throws `CRYPTO_CIPHER.STREAM_INVALID_NONCE_BASE` with `context.expectedLength === 20` and `context.actualLength === 24`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead-xchacha20/streaming-aead-xchacha20.test.ts::"derives 24-byte nonce from 20-byte base + counter"` AND `packages/crypto/crypto-cipher/src/streaming/streaming-aead-xchacha20/streaming-aead-xchacha20.spec-conformance.test.ts::"rejects wrong-length base nonce with STREAM_INVALID_NONCE_BASE"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: StreamingAeadEngine contract
|
||||
|
||||
The package SHALL define a `StreamingAeadEngine` interface in `streaming-aead.types.ts` with `encrypt(input: StreamingChunkInput): Promise<StreamingChunkOutput>` and `decrypt(input: StreamingChunkInput): Promise<Uint8Array>` methods, plus `nonceBaseLength: number` and `tagLength: number` constants. Both built-in engines (AES-GCM, XChaCha20-Poly1305) SHALL satisfy this interface and SHALL be substitutable for any caller-supplied engine.
|
||||
|
||||
#### Scenario: caller-supplied engine round-trips identically
|
||||
|
||||
- **WHEN** a custom `StreamingAeadEngine` implementation is passed to `encryptStreamAead` and the same instance to `decryptStreamAead`
|
||||
- **THEN** the round-trip preserves bytes byte-for-byte (validated against an in-test spy engine that records every call)
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.spec-conformance.test.ts::"StreamingAeadEngine contract is stable for custom engines"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,74 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto-curve (crypto-completion)
|
||||
|
||||
**Package**: `@suaveplan/crypto-curve`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: secp256k1 ECDSA signing with recovery byte
|
||||
|
||||
The `secp256k1` primitive SHALL expose `signWithRecovery(digest, privateKey)` returning a 65-byte signature (64-byte compact signature followed by a single recovery byte). The recovery byte SHALL be the byte returned by `secp256k1.sign(digest, privateKey).recovery` from the `@noble/curves` library; valid values are `0` or `1`.
|
||||
|
||||
#### Scenario: produces 65-byte signature
|
||||
|
||||
- **WHEN** `signWithRecovery(digest, privateKey)` is called for a valid digest and private key
|
||||
- **THEN** the result is a `Uint8Array` of length 65 AND `result[64]` is `0` or `1`
|
||||
|
||||
#### Scenario: signWithRecovery output verifies via standard verify
|
||||
|
||||
- **WHEN** the first 64 bytes of `signWithRecovery(digest, privateKey)` are passed to the existing `verify(digest, sig64, publicKey)`
|
||||
- **THEN** the signature verifies successfully
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.test.ts::"signWithRecovery returns 65-byte signature with recovery byte 0 or 1"` AND `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.test.ts::"signWithRecovery output verifies via standard verify on first 64 bytes"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: secp256k1 public-key recovery
|
||||
|
||||
The `secp256k1` primitive SHALL expose `recoverPublicKey(signatureWithRecovery, digest)` returning the 33-byte compressed public key recovered from a 65-byte signature-with-recovery and the original digest. Inputs may be supplied as `Uint8Array` or hex strings.
|
||||
|
||||
#### Scenario: recovers the signing public key
|
||||
|
||||
- **WHEN** `signWithRecovery(digest, privateKey)` produces `sig` and `recoverPublicKey(sig, digest)` is called
|
||||
- **THEN** the recovered public key equals `getPublicKey(privateKey)` byte-for-byte
|
||||
|
||||
#### Scenario: missing recovery byte rejected
|
||||
|
||||
- **WHEN** a 64-byte signature (without recovery byte) is passed to `recoverPublicKey`
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO_CURVE.RECOVERY_BYTE_MISSING` and `context.signatureLength === 64`
|
||||
|
||||
#### Scenario: invalid recovery byte rejected
|
||||
|
||||
- **WHEN** a 65-byte signature is passed but `signatureWithRecovery[64]` is `2`, `3`, or any value > 3
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO_CURVE.RECOVERY_BYTE_INVALID` and `context.recoveryByte` reflects the offending value
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.test.ts::"recoverPublicKey returns the same key as getPublicKey for the signer"` AND `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.spec-conformance.test.ts::"throws RECOVERY_BYTE_MISSING for 64-byte signature"` AND `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.spec-conformance.test.ts::"throws RECOVERY_BYTE_INVALID when recovery byte is out of range"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: secp256k1 verify-with-recovery
|
||||
|
||||
The `secp256k1` primitive SHALL expose `verifyWithRecovery(signatureWithRecovery, digest, expectedPublicKey)` returning `true` only when the public key recovered from the signature equals `expectedPublicKey` (compared in constant time on the byte buffer). When the recovered key differs, the function SHALL return `false` (it does NOT throw on mismatch — mismatch is a routine path).
|
||||
|
||||
#### Scenario: returns true on matching key
|
||||
|
||||
- **WHEN** `verifyWithRecovery(sig, digest, expectedPublicKey)` is called with the public key that produced `sig`
|
||||
- **THEN** the result is `true`
|
||||
|
||||
#### Scenario: returns false on non-matching key
|
||||
|
||||
- **WHEN** `verifyWithRecovery(sig, digest, otherPublicKey)` is called with a public key that did not produce `sig`
|
||||
- **THEN** the result is `false` (no exception is thrown)
|
||||
|
||||
#### Scenario: comparison is constant-time
|
||||
|
||||
- **WHEN** the recovered public key and `expectedPublicKey` differ in their first byte vs differ only in their last byte
|
||||
- **THEN** the timing distribution observed across many invocations does not reveal the position of the difference (verified via a statistical timing test)
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.test.ts::"verifyWithRecovery returns true on matching public key"` AND `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.test.ts::"verifyWithRecovery returns false on non-matching public key"` AND `packages/crypto/crypto-curve/src/primitives/secp256k1/secp256k1.spec-conformance.test.ts::"verifyWithRecovery comparison is constant-time"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,79 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto-hash (crypto-completion)
|
||||
|
||||
**Package**: `@suaveplan/crypto-hash`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: scrypt KDF primitive
|
||||
|
||||
The package SHALL expose `scrypt(password, salt, options)` from `primitives/scrypt/scrypt.ts`, where `options` carries `N` (CPU/memory cost, must be a power of two ≥ 2), `r` (block size), `p` (parallelisation), and `dkLen` (output length in bytes). The implementation SHALL match RFC 7914 byte-for-byte and SHALL use the `@noble/hashes/scrypt::scryptAsync` engine in the noble selector. Output is a `Uint8Array` of length `dkLen`.
|
||||
|
||||
#### Scenario: matches RFC 7914 known-answer test
|
||||
|
||||
- **WHEN** `scrypt("password", "NaCl", { N: 1024, r: 8, p: 16, dkLen: 64 })` is called
|
||||
- **THEN** the output equals the RFC 7914 §11 KAT for those parameters byte-for-byte
|
||||
|
||||
#### Scenario: invalid N rejected
|
||||
|
||||
- **WHEN** `scrypt(pw, salt, { N: 1000, r: 8, p: 1, dkLen: 32 })` is called (1000 is not a power of two)
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO_HASH.SCRYPT_INVALID_N` and `context.N === 1000`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-hash/src/primitives/scrypt/scrypt.test.ts::"matches RFC 7914 known-answer test for N=1024 r=8 p=16"` AND `packages/crypto/crypto-hash/src/primitives/scrypt/scrypt.spec-conformance.test.ts::"throws SCRYPT_INVALID_N when N is not a power of two"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: blake2b hash primitive
|
||||
|
||||
The package SHALL expose `blake2b(message, options)` from `primitives/blake2b/blake2b.ts`, where `options` carries `dkLen` (1..64), optional `key` (≤ 64 bytes), optional `salt` (16 bytes), and optional `personalization` (16 bytes). The implementation SHALL match RFC 7693 byte-for-byte.
|
||||
|
||||
#### Scenario: matches RFC 7693 known-answer test
|
||||
|
||||
- **WHEN** `blake2b("abc", { dkLen: 64 })` is called
|
||||
- **THEN** the output equals the RFC 7693 §B Appendix KAT for the input "abc" byte-for-byte
|
||||
|
||||
#### Scenario: dkLen > 64 rejected
|
||||
|
||||
- **WHEN** `blake2b(msg, { dkLen: 65 })` is called
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO_HASH.BLAKE2B_OUTPUT_TOO_LONG` and `context.requestedLength === 65`
|
||||
|
||||
#### Scenario: key longer than 64 bytes rejected
|
||||
|
||||
- **WHEN** `blake2b(msg, { dkLen: 32, key: 65-byte-buffer })` is called
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO_HASH.BLAKE2B_KEY_TOO_LONG` and `context.keyLength === 65`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-hash/src/primitives/blake2b/blake2b.test.ts::"matches RFC 7693 known-answer test for input \"abc\""` AND `packages/crypto/crypto-hash/src/primitives/blake2b/blake2b.spec-conformance.test.ts::"throws BLAKE2B_OUTPUT_TOO_LONG when dkLen exceeds 64"` AND `packages/crypto/crypto-hash/src/primitives/blake2b/blake2b.spec-conformance.test.ts::"throws BLAKE2B_KEY_TOO_LONG when key exceeds 64 bytes"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: blake2b password hashing and verification
|
||||
|
||||
The package SHALL expose `hashPasswordBlake2b(password, options)` returning a stored hash in the format `$blake2b$v=1$cf=<costFactor>$<saltHex>$<hashHex>`, where `costFactor` controls iteration count (default 14, doubling each level) and a 16-byte random salt is generated when not supplied. It SHALL also expose `verifyPasswordBlake2b(storedHash, password)` returning `true` when the password verifies and `false` otherwise. Comparison SHALL be constant-time over the hash bytes.
|
||||
|
||||
#### Scenario: hash and verify round-trip
|
||||
|
||||
- **WHEN** `hashPasswordBlake2b("correct horse battery staple")` produces `stored` and `verifyPasswordBlake2b(stored, "correct horse battery staple")` is called
|
||||
- **THEN** the result is `true`
|
||||
|
||||
#### Scenario: wrong password verifies as false
|
||||
|
||||
- **WHEN** `verifyPasswordBlake2b(stored, "wrong password")` is called
|
||||
- **THEN** the result is `false` (no exception thrown)
|
||||
|
||||
#### Scenario: salt is fresh per call
|
||||
|
||||
- **WHEN** `hashPasswordBlake2b("same password")` is called twice
|
||||
- **THEN** the two stored hashes are not byte-equal (different salts → different outputs)
|
||||
|
||||
#### Scenario: malformed stored hash rejected
|
||||
|
||||
- **WHEN** `verifyPasswordBlake2b("not-a-valid-format", pw)` is called
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO_HASH.BLAKE2B_PASSWORD_FORMAT_INVALID`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-hash/src/mac/blake2b-password/blake2b-password.test.ts::"hash and verify round-trip with same password"` AND `packages/crypto/crypto-hash/src/mac/blake2b-password/blake2b-password.test.ts::"verify returns false for wrong password"` AND `packages/crypto/crypto-hash/src/mac/blake2b-password/blake2b-password.test.ts::"salt is fresh per call so identical inputs hash differently"` AND `packages/crypto/crypto-hash/src/mac/blake2b-password/blake2b-password.spec-conformance.test.ts::"throws BLAKE2B_PASSWORD_FORMAT_INVALID for malformed stored hash"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,110 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto-keys (crypto-completion)
|
||||
|
||||
**Package**: `@suaveplan/crypto-keys`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Device key creation
|
||||
|
||||
The package SHALL expose `createDeviceKey(options?)` from `keypair/device/device.ts` that generates a new `DeviceKey` carrying `BaseKeySchema` metadata (`s` secret bytes, `v` version, `m` master version, `u` user id, `d` depth, `o` key offset). Device keys SHALL always have `o === 7`. Generated keys SHALL pass `isValidDeviceKey`; an internally-failed validation SHALL throw `SuaveplanError` with code `CRYPTO_KEYS.DEVICE_INVALID_KEY`.
|
||||
|
||||
#### Scenario: round-trip valid key
|
||||
|
||||
- **WHEN** `createDeviceKey()` is called with no options
|
||||
- **THEN** the result satisfies `isValidDeviceKey(key) === true` AND `key.o === 7` AND `key.s` is a 32-byte `Uint8Array`
|
||||
|
||||
#### Scenario: caller-supplied metadata respected
|
||||
|
||||
- **WHEN** `createDeviceKey({ version: 3, masterVersion: 2, userId: 42, depth: 4 })` is called
|
||||
- **THEN** the result has `key.v === 3`, `key.m === 2`, `key.u === 42`, `key.d === 4`, `key.o === 7`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"createDeviceKey produces a valid device key with offset 7"` AND `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"createDeviceKey honors version / masterVersion / userId / depth options"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Device key derivation from master
|
||||
|
||||
The package SHALL expose `deriveDeviceKeyFromMaster(options)` that derives a per-device `DeviceKey` from a `MasterKey` plus a numeric `deviceId`. Derivation SHALL use the existing `generateDerivedKey` (from `crypto-keys/keypair/derivation`) with key offset `7` and a context derived from the device id. The same `(masterKey, deviceId)` SHALL always produce the same `DeviceKey.s` byte sequence. Invalid master keys SHALL throw `CRYPTO_KEYS.DEVICE_INVALID_MASTER`.
|
||||
|
||||
#### Scenario: deterministic derivation
|
||||
|
||||
- **WHEN** `deriveDeviceKeyFromMaster({ masterKey, deviceId: 1 })` is called twice
|
||||
- **THEN** both results have byte-equal `.s` fields
|
||||
|
||||
#### Scenario: different device ids produce different keys
|
||||
|
||||
- **WHEN** `deriveDeviceKeyFromMaster({ masterKey, deviceId: 1 })` and `deriveDeviceKeyFromMaster({ masterKey, deviceId: 2 })` are called
|
||||
- **THEN** the two results have different `.s` fields
|
||||
|
||||
#### Scenario: invalid master key rejected
|
||||
|
||||
- **WHEN** `deriveDeviceKeyFromMaster({ masterKey: { s: shortBytes } as MasterKey, deviceId: 1 })` is called with a master key that fails `validateMasterKey`
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO_KEYS.DEVICE_INVALID_MASTER`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"deriveDeviceKeyFromMaster is deterministic for fixed master and deviceId"` AND `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"different deviceIds derive different keys"` AND `packages/crypto/crypto-keys/src/keypair/device/device.spec-conformance.test.ts::"throws DEVICE_INVALID_MASTER for an invalid master key"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Device UUID generation
|
||||
|
||||
The package SHALL expose `generateDeviceUUID(options)` returning an RFC 4122-compliant UUID v4 string deterministically derived from a `DeviceKey`. The version nibble (bits 12-15 of `time_hi_and_version`) SHALL be set to `4`; the variant bits (bits 6-7 of `clock_seq_hi`) SHALL be set to `10`. The same `DeviceKey` plus context SHALL always produce the same UUID.
|
||||
|
||||
#### Scenario: UUID structure conforms to v4
|
||||
|
||||
- **WHEN** `generateDeviceUUID({ deviceMasterKey })` is called
|
||||
- **THEN** the result matches `/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/`
|
||||
|
||||
#### Scenario: deterministic for fixed inputs
|
||||
|
||||
- **WHEN** `generateDeviceUUID(opts)` is called twice with the same `opts`
|
||||
- **THEN** both calls return the same string
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"generateDeviceUUID returns an RFC 4122 v4 UUID"` AND `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"generateDeviceUUID is deterministic for fixed inputs"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Device metadata extraction and comparison
|
||||
|
||||
The package SHALL expose `extractDeviceMetadata(deviceKey)` returning `DeviceMetadata` (`version`, `masterVersion`, `userId`, `depth`, `keyOffset`) and `compareDeviceKeys(a, b)` returning `true` only when the two `DeviceKey` instances have identical `s`, `v`, `m`, `u`, `d`, `o` fields. The `s`-byte comparison SHALL be constant-time. The package SHALL also expose `isValidDeviceKey(deviceKey)` returning `true` only for keys passing structural validation (correct field types and `o === 7`).
|
||||
|
||||
#### Scenario: extractDeviceMetadata round-trips
|
||||
|
||||
- **WHEN** `extractDeviceMetadata(createDeviceKey({ version: 5, depth: 3 }))` is called
|
||||
- **THEN** the result has `version === 5` and `depth === 3`
|
||||
|
||||
#### Scenario: compareDeviceKeys equals on identical keys
|
||||
|
||||
- **WHEN** `compareDeviceKeys(k, k)` is called for any `DeviceKey` k
|
||||
- **THEN** the result is `true`
|
||||
|
||||
#### Scenario: compareDeviceKeys differs on differing s
|
||||
|
||||
- **WHEN** `compareDeviceKeys(k1, k2)` is called for keys with different `.s` bytes
|
||||
- **THEN** the result is `false`
|
||||
|
||||
#### Scenario: compareDeviceKeys is constant-time on s
|
||||
|
||||
- **WHEN** the `.s` bytes differ at byte 0 vs byte 31 (last byte)
|
||||
- **THEN** the timing distribution observed across many invocations does not reveal which byte differs (statistical timing test)
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"extractDeviceMetadata round-trips a created device key"` AND `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"compareDeviceKeys is true for identical keys"` AND `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"compareDeviceKeys is false for keys with differing s"` AND `packages/crypto/crypto-keys/src/keypair/device/device.spec-conformance.test.ts::"compareDeviceKeys runs in constant time over s"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: generateDerivedDeviceId back-compat alias
|
||||
|
||||
The package SHALL expose `generateDerivedDeviceId(options)` as a thin alias for `generateDeviceUUID(options)`, retained for upstream-API back-compat. The alias SHALL NOT use `@deprecated` JSDoc (banned in genesis per CLAUDE.md §2). Its sibling `.md` SHALL document it with prose: "Backwards-compatibility alias for `generateDeviceUUID`."
|
||||
|
||||
#### Scenario: alias produces identical output
|
||||
|
||||
- **WHEN** `generateDerivedDeviceId(opts)` and `generateDeviceUUID(opts)` are called with the same options
|
||||
- **THEN** both return the same string
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-keys/src/keypair/device/device.test.ts::"generateDerivedDeviceId returns the same UUID as generateDeviceUUID"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,107 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto (crypto-completion)
|
||||
|
||||
**Package**: `@suaveplan/crypto`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: High-level streaming AEAD façade
|
||||
|
||||
The package SHALL expose `encryptStreamAead(opts)` and `decryptStreamAead(opts)` from `aead/streaming/streaming-aead.ts` that select the engine (`xchacha20-poly1305` or `aes-256-gcm`) from `opts.algorithm` and delegate to the corresponding `StreamingAeadEngine` in `@suaveplan/crypto-cipher`. The package SHALL re-export the named engines `aesGcmStreamingEngine` and `xchacha20StreamingEngine` so callers wanting the engine directly do not need to depend on `crypto-cipher`.
|
||||
|
||||
#### Scenario: facade routes to AES-GCM engine
|
||||
|
||||
- **WHEN** `encryptStreamAead({ algorithm: "aes-256-gcm", key, baseNonce: 8-byte, plaintext })` is called
|
||||
- **THEN** the produced ciphertext decrypts via the standalone `aesGcmStreamingEngine` exported from this package, byte-for-byte
|
||||
|
||||
#### Scenario: facade routes to XChaCha20-Poly1305 engine
|
||||
|
||||
- **WHEN** `encryptStreamAead({ algorithm: "xchacha20-poly1305", key, baseNonce: 20-byte, plaintext })` is called
|
||||
- **THEN** the produced ciphertext decrypts via the standalone `xchacha20StreamingEngine` exported from this package, byte-for-byte
|
||||
|
||||
#### Scenario: unknown algorithm rejected
|
||||
|
||||
- **WHEN** `encryptStreamAead({ algorithm: "rot13" as never, ... })` is called
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO.STREAM_AEAD_HEADER_INVALID` and `context.algorithm === "rot13"`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/aead/streaming/streaming-aead.test.ts::"facade routes aes-256-gcm to aesGcmStreamingEngine"` AND `packages/crypto/crypto/src/aead/streaming/streaming-aead.test.ts::"facade routes xchacha20-poly1305 to xchacha20StreamingEngine"` AND `packages/crypto/crypto/src/aead/streaming/streaming-aead.spec-conformance.test.ts::"throws STREAM_AEAD_HEADER_INVALID on unknown algorithm"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Web-Streams adapters for streaming AEAD
|
||||
|
||||
The package SHALL expose `createEncryptionStream(opts) → TransformStream<Uint8Array, Uint8Array>` and `createDecryptionStream(opts) → TransformStream<Uint8Array, Uint8Array>` from `aead/streaming/web-streams.ts`. These SHALL be drop-in `pipeThrough` targets for any Web-Streams `ReadableStream<Uint8Array>` source (e.g. `Blob.stream()`, `Response.body`, `fetch().body`). The package SHALL also expose `collectStream(stream) → Promise<Uint8Array>` (concatenates all chunks), `createStreamKey(rng?) → Uint8Array` (returns 32 random bytes), and `createStreamEncryption(opts)` (combined key + base-nonce + initialised stream factory).
|
||||
|
||||
#### Scenario: pipeThrough round-trips a Blob
|
||||
|
||||
- **WHEN** `blob.stream().pipeThrough(createEncryptionStream(opts)).pipeThrough(createDecryptionStream(opts))` is collected via `collectStream`
|
||||
- **THEN** the collected bytes equal the original blob bytes
|
||||
|
||||
#### Scenario: legacy aliases preserved
|
||||
|
||||
- **WHEN** `streamEncrypt`, `streamDecrypt`, `ChaCha20Stream`, `AESStream` are imported
|
||||
- **THEN** all four resolve to defined values that satisfy the documented upstream contract
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/aead/streaming/web-streams.test.ts::"pipeThrough round-trips a multi-chunk source through encrypt then decrypt"` AND `packages/crypto/crypto/src/aead/streaming/web-streams.test.ts::"streamEncrypt / streamDecrypt / ChaCha20Stream / AESStream aliases resolve and round-trip"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Password-based encryption helpers
|
||||
|
||||
The package SHALL expose `encryptWithPassword(password, plaintext, options?)` and `decryptWithPassword(password, ciphertext, options?)` from `password/encrypt-with-password.ts`. The `options.kdf` field SHALL accept `"argon2id"` (default), `"scrypt"`, or `"pbkdf2"`. The output blob SHALL begin with a versioned 16-byte self-describing header `{ magic: "SVPP", version: 1, kdf, cipher, reserved, saltLen, nonceLen, kdfParamsLen }` followed by salt, nonce, CBOR-encoded `kdfParams`, then AEAD ciphertext. `decryptWithPassword` SHALL parse the header to recover all parameters and SHALL NOT require any out-of-band metadata from the caller.
|
||||
|
||||
#### Scenario: round-trip with default Argon2id
|
||||
|
||||
- **WHEN** `encryptWithPassword("correct horse battery staple", plaintext)` produces `blob` and `decryptWithPassword("correct horse battery staple", blob)` is called
|
||||
- **THEN** the result equals `plaintext` byte-for-byte
|
||||
|
||||
#### Scenario: round-trip with scrypt KDF
|
||||
|
||||
- **WHEN** `encryptWithPassword(pw, plaintext, { kdf: "scrypt" })` produces `blob` and `decryptWithPassword(pw, blob)` is called
|
||||
- **THEN** the result equals `plaintext` byte-for-byte AND the blob's KDF byte signals scrypt
|
||||
|
||||
#### Scenario: blob header self-describes
|
||||
|
||||
- **WHEN** the same `(password, plaintext)` is encrypted twice with different `kdfParams`
|
||||
- **THEN** the two blobs have different KDF-params bytes in their headers AND both decrypt successfully without the caller passing `kdfParams` to `decryptWithPassword`
|
||||
|
||||
#### Scenario: unknown KDF rejected
|
||||
|
||||
- **WHEN** `encryptWithPassword(pw, plaintext, { kdf: "bcrypt" as never })` is called
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO.PASSWORD_KDF_UNKNOWN` and `context.kdf === "bcrypt"`
|
||||
|
||||
#### Scenario: corrupt header rejected
|
||||
|
||||
- **WHEN** `decryptWithPassword(pw, blob)` is called with a `blob` whose first four bytes are not `"SVPP"`
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO.PASSWORD_BLOB_HEADER_INVALID`
|
||||
|
||||
#### Scenario: unsupported version rejected
|
||||
|
||||
- **WHEN** `decryptWithPassword(pw, blob)` is called with a `blob` whose version byte is `99`
|
||||
- **THEN** it throws `SuaveplanError` with code `CRYPTO.PASSWORD_BLOB_VERSION_UNSUPPORTED` and `context.version === 99`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/password/encrypt-with-password.test.ts::"round-trips with default Argon2id KDF"` AND `packages/crypto/crypto/src/password/encrypt-with-password.test.ts::"round-trips with scrypt KDF"` AND `packages/crypto/crypto/src/password/encrypt-with-password.test.ts::"blob header is self-describing across kdfParams variants"` AND `packages/crypto/crypto/src/password/encrypt-with-password.spec-conformance.test.ts::"throws PASSWORD_KDF_UNKNOWN on unknown KDF name"` AND `packages/crypto/crypto/src/password/encrypt-with-password.spec-conformance.test.ts::"throws PASSWORD_BLOB_HEADER_INVALID on corrupt magic bytes"` AND `packages/crypto/crypto/src/password/encrypt-with-password.spec-conformance.test.ts::"throws PASSWORD_BLOB_VERSION_UNSUPPORTED on unknown version byte"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: deriveKeyFromPassword
|
||||
|
||||
The package SHALL expose `deriveKeyFromPassword(password, salt, options?)` from `password/derive-key-from-password.ts`. The `options` SHALL accept `kdf: "argon2id" | "scrypt" | "pbkdf2"` (default `"argon2id"`), `kdfParams: Record<string, number>` (algorithm-specific), and `dkLen: number` (default 32). The function SHALL return a `Uint8Array` of length `dkLen` suitable for direct use as a symmetric AEAD key. Identical `(password, salt, kdf, kdfParams)` SHALL produce byte-identical output.
|
||||
|
||||
#### Scenario: deterministic given fixed inputs
|
||||
|
||||
- **WHEN** `deriveKeyFromPassword(pw, salt, { kdf: "scrypt", kdfParams: { N: 1024, r: 8, p: 1 } })` is called twice
|
||||
- **THEN** both calls return byte-identical 32-byte Uint8Arrays
|
||||
|
||||
#### Scenario: dkLen honored
|
||||
|
||||
- **WHEN** `deriveKeyFromPassword(pw, salt, { kdf: "argon2id", dkLen: 64 })` is called
|
||||
- **THEN** the result is a 64-byte Uint8Array
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/password/derive-key-from-password.test.ts::"deterministic for fixed password / salt / params"` AND `packages/crypto/crypto/src/password/derive-key-from-password.test.ts::"honors dkLen option"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
181
openspec/changes/archive/2026-05-03-crypto-completion/tasks.md
Normal file
181
openspec/changes/archive/2026-05-03-crypto-completion/tasks.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Tasks — Crypto completion
|
||||
|
||||
> 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. Do not tick a box for a test that doesn't exist or doesn't pin the requirement it claims to verify.
|
||||
|
||||
## 1. Spec authoring
|
||||
|
||||
- [x] 1.1 Read `../suaveplan/packages/universal/crypto/src/symmetric/streaming/streaming-aead.ts`, `streaming.ts`, `streaming-aead-aes-gcm.ts`, `streaming-aead-xchacha20.ts` end-to-end
|
||||
- [x] 1.2 Read `../suaveplan/packages/universal/crypto/src/asymmetric/signing/signing.ts` (focus on lines L74-L307 — sign / recover / verify with recovery)
|
||||
- [x] 1.3 Read `../suaveplan/packages/universal/crypto/src/keys/device/device.ts` end-to-end
|
||||
- [x] 1.4 Read `../suaveplan/packages/universal/crypto/src/core/hashing/hashing.ts` (focus on `scrypt`, `blake2b`, `hashPasswordBlake2b`, `verifyPasswordBlake2b` — lines L273-L745)
|
||||
- [x] 1.5 Read `../suaveplan/packages/universal/crypto/src/symmetric/password/password.ts` end-to-end
|
||||
- [x] 1.6 Read `../suaveplan/packages/universal/crypto/src/bin/hash-password.ts` end-to-end
|
||||
- [x] 1.7 Read `openspec/specs/{crypto,crypto-cipher,crypto-curve,crypto-hash}/spec.md` (existing folded specs)
|
||||
- [x] 1.8 Read `openspec/AGENTS.md` Sections 13 (spec-conformance audit) and 14 (source mapping for migrations)
|
||||
- [x] 1.9 Draft `proposal.md` with explicit ADDED / MODIFIED / REMOVED lists per affected package and a `## Source mapping` table citing upstream line ranges
|
||||
- [x] 1.10 Draft spec deltas under `specs/<cap>/spec.md` for `crypto-cipher`, `crypto-curve`, `crypto-hash`, `crypto-keys`, `crypto`
|
||||
- [x] 1.11 Every requirement in every spec delta carries a `**Verified by:**` line naming concrete `it(...)` titles
|
||||
- [x] 1.12 `openspec change validate crypto-completion` exits with no errors
|
||||
|
||||
## 2. `@suaveplan/crypto-cipher` — streaming AEAD
|
||||
|
||||
- [x] 2.1 Create `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.types.ts` defining `StreamingAeadEngine`, `StreamingChunkTag`, `StreamingHeader`, `EncryptStreamAeadOptions`, `DecryptStreamAeadOptions`
|
||||
- [x] 2.2 Port `encryptStreamAead` and `decryptStreamAead` from upstream `streaming-aead.ts` L11-L255 into `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.ts`
|
||||
- [x] 2.3 Port `aesGcmStreamingEngine` from upstream `streaming-aead-aes-gcm.ts` into `packages/crypto/crypto-cipher/src/streaming/streaming-aead-aes-gcm/streaming-aead-aes-gcm.ts`
|
||||
- [x] 2.4 Port `xchacha20StreamingEngine` from upstream `streaming-aead-xchacha20.ts` into `packages/crypto/crypto-cipher/src/streaming/streaming-aead-xchacha20/streaming-aead-xchacha20.ts`
|
||||
- [x] 2.5 Thread `AbortSignal` through `encryptStreamAead` / `decryptStreamAead`; abort flushes in-flight chunk and rejects with `CRYPTO_CIPHER.STREAM_ABORTED`
|
||||
- [x] 2.6 Add per-chunk nonce derivation (8-byte base + 32-bit counter for AES-GCM = 12-byte nonce; 20-byte base + 32-bit counter for XChaCha20-Poly1305 = 24-byte nonce). Counter overflow at `2^32` chunks emits `CRYPTO_CIPHER.STREAM_OUT_OF_ORDER`
|
||||
- [x] 2.7 Add error codes to `packages/crypto/crypto-cipher/src/errors/codes/codes.ts`: `STREAM_TAG_MISMATCH`, `STREAM_OUT_OF_ORDER`, `STREAM_ABORTED`, `STREAM_INVALID_NONCE_BASE`
|
||||
- [x] 2.8 Wire `streaming/streaming-aead/streaming-aead.test.ts` and `streaming-aead.spec-conformance.test.ts`
|
||||
- [x] 2.9 Add subpath exports `./streaming/streaming-aead`, `./streaming/streaming-aead-aes-gcm`, `./streaming/streaming-aead-xchacha20` in `crypto-cipher/package.json`
|
||||
- [x] 2.10 Sibling `.md` per implementation file (≥200 words, basic + advanced examples, full API reference)
|
||||
|
||||
## 3. `@suaveplan/crypto-curve` — secp256k1 ECDSA recovery
|
||||
|
||||
- [x] 3.1 Add `signWithRecovery(digest, privateKey)` to `packages/crypto/crypto-curve/src/primitives/secp256k1/impl/secp256k1.noble/secp256k1.noble.ts`. Signature is 65 bytes: 64-byte compact signature + 1 recovery byte
|
||||
- [x] 3.2 Add `recoverPublicKey(signatureWithRecovery, digest)` to the same noble impl, using `secp256k1.Signature.fromBytes(sig, "compact").addRecoveryBit(rec).recoverPublicKey(digest)`
|
||||
- [x] 3.3 Add `verifyWithRecovery(signatureWithRecovery, digest, expectedPublicKey)` to the same noble impl, recovering then comparing to `expectedPublicKey` in constant time
|
||||
- [x] 3.4 Add matching stubs to `secp256k1.native/secp256k1.native.ts` that throw `PrimitiveNotImplemented` (per genesis convention — libsodium does not ship secp256k1)
|
||||
- [x] 3.5 Re-export the three new functions via `secp256k1.select/secp256k1.select.ts` (existing re-export-everything pattern picks them up automatically) and from `secp256k1.ts` / `secp256k1/index.ts`
|
||||
- [x] 3.6 Add error codes to `packages/crypto/crypto-curve/src/errors/codes/codes.ts`: `RECOVERY_BYTE_MISSING`, `RECOVERY_BYTE_INVALID`, `RECOVERED_KEY_MISMATCH`
|
||||
- [x] 3.7 Extend `secp256k1.test.ts` with sign / recover / verify-with-recovery cases and `secp256k1.spec-conformance.test.ts` with the three error-code paths
|
||||
- [x] 3.8 Update `secp256k1.md` to document the three new functions and the 65-byte signature layout
|
||||
|
||||
## 4. `@suaveplan/crypto-hash` — scrypt + blake2b + blake2b password
|
||||
|
||||
- [x] 4.1 Create `packages/crypto/crypto-hash/src/primitives/scrypt/scrypt.ts` with `scrypt(password, salt, options: { N, r, p, dkLen })`. Use `@noble/hashes/scrypt::scryptAsync`
|
||||
- [x] 4.2 Add per-primitive selector layout: `scrypt.select/scrypt.select.ts`, `impl/scrypt.noble/scrypt.noble.ts`. Match the existing `argon2id` / `pbkdf2` shape
|
||||
- [x] 4.3 Validate `N` is a power of two ≥ 2; reject with `HASH.SCRYPT_INVALID_N`
|
||||
- [x] 4.4 Create `packages/crypto/crypto-hash/src/primitives/blake2b/blake2b.ts` with `blake2b(message, options: { dkLen, key?, salt?, personalization? })`. Use `@noble/hashes/blake2b`
|
||||
- [x] 4.5 Add per-primitive selector layout: `blake2b.select/blake2b.select.ts`, `impl/blake2b.noble/blake2b.noble.ts`
|
||||
- [x] 4.6 Reject `dkLen > 64` with `HASH.BLAKE2B_OUTPUT_TOO_LONG`; reject `key.length > 64` with `HASH.BLAKE2B_KEY_TOO_LONG`
|
||||
- [x] 4.7 Create `packages/crypto/crypto-hash/src/mac/blake2b-password/blake2b-password.ts` with `hashPasswordBlake2b(password, options: { costFactor?, salt? })` and `verifyPasswordBlake2b(storedHash, password)`. Format: `$blake2b$v=1$cf=<costFactor>$<saltHex>$<hashHex>`
|
||||
- [x] 4.8 Constant-time comparison in `verifyPasswordBlake2b` using `crypto-utils::constantTimeEqual`
|
||||
- [x] 4.9 Add error codes to `packages/crypto/crypto-hash/src/errors/codes/codes.ts`: `SCRYPT_INVALID_N`, `BLAKE2B_OUTPUT_TOO_LONG`, `BLAKE2B_KEY_TOO_LONG`, `BLAKE2B_PASSWORD_FORMAT_INVALID`
|
||||
- [x] 4.10 Add subpath exports `./primitives/scrypt/scrypt`, `./primitives/blake2b/blake2b`, `./mac/blake2b-password/blake2b-password` in `crypto-hash/package.json`
|
||||
- [x] 4.11 Sibling `.md` per implementation file
|
||||
|
||||
## 5. `@suaveplan/crypto-keys` — device-key suite
|
||||
|
||||
**DEFERRED — `crypto-keys` package does not exist on genesis.** Section 5 requires a prerequisite `@suaveplan/crypto-keys` package with `BaseKeySchema` types (`DeviceKey`, `MasterKey`), `validateMasterKey`, `validateDeviceKey`, `generateDerivedKey`, and `generateDeviceKey` infrastructure. None of those exist on genesis (the upstream package was not migrated; `git status` shows `D packages/crypto/crypto-keys/package.json`). Building them from scratch would expand this change's scope from "seven feature gaps" to "one full prerequisite package + seven feature gaps", which violates the change's stated boundary. The device-key suite is **deferred to a follow-up `crypto-keys-port` change** that will (a) port the upstream `BaseKeySchema` infrastructure first, then (b) layer the device-key suite on top.
|
||||
|
||||
The crypto-keys spec delta (`specs/crypto-keys/spec.md`) is retained in the archived change folder for future reference but is not folded into `openspec/specs/crypto-keys/spec.md` (no such spec exists yet).
|
||||
|
||||
- [ ] 5.1 Create `packages/crypto/crypto-keys/src/keypair/device/device.types.ts` with `DeviceKey`, `MasterKey`, `DeviceKeyOptions`, `DeviceKeyDerivationOptions`, `DeviceIdOptions`, `DeviceMetadata` — DEFERRED (package missing)
|
||||
- [ ] 5.2 Port `createDeviceKey` — DEFERRED (package missing)
|
||||
- [ ] 5.3 Port `deriveDeviceKeyFromMaster` — DEFERRED (package missing)
|
||||
- [ ] 5.4 Port `generateDeviceUUID` — DEFERRED (package missing)
|
||||
- [ ] 5.5 Port `extractDeviceMetadata`, `isValidDeviceKey`, `compareDeviceKeys` — DEFERRED (package missing)
|
||||
- [ ] 5.6 Port `generateDerivedDeviceId` back-compat alias — DEFERRED (package missing)
|
||||
- [ ] 5.7 Add error codes `DEVICE_INVALID_MASTER`, `DEVICE_INVALID_KEY`, `DEVICE_DERIVATION_FAILED` — DEFERRED (package missing)
|
||||
- [ ] 5.8 Add subpath export `./keypair/device/device` — DEFERRED (package missing)
|
||||
- [ ] 5.9 Sibling `.md` per implementation file — DEFERRED (package missing)
|
||||
- [ ] 5.10 Wire `keypair/device/device.test.ts` and `device.spec-conformance.test.ts` — DEFERRED (package missing)
|
||||
|
||||
## 6. `@suaveplan/crypto` — streaming AEAD façade + password helpers
|
||||
|
||||
- [x] 6.1 Create `packages/crypto/crypto/src/aead/streaming/streaming-aead.ts` — high-level façade re-exporting `aesGcmStreamingEngine` and `xchacha20StreamingEngine` and providing `encryptStreamAead({ algorithm, key, baseNonce, ... })` / `decryptStreamAead({ algorithm, key, ... })` that select the engine
|
||||
- [x] 6.2 Create `packages/crypto/crypto/src/aead/streaming/web-streams.ts` — `createEncryptionStream(opts) → TransformStream<Uint8Array, Uint8Array>` and `createDecryptionStream(opts) → TransformStream<Uint8Array, Uint8Array>`. Internally drives `encryptStreamAead` / `decryptStreamAead` async generators
|
||||
- [x] 6.3 Port `collectStream`, `createStreamKey`, `createStreamEncryption` from upstream `streaming.ts` L200-L270
|
||||
- [x] 6.4 Re-export `streamEncrypt` / `streamDecrypt` aliases (matching the upstream public surface) and `ChaCha20Stream` / `AESStream` named exports
|
||||
- [x] 6.5 Create `packages/crypto/crypto/src/password/encrypt-with-password.ts` with `encryptWithPassword(password, plaintext, options?)` and `decryptWithPassword(password, ciphertext, options?)`. Default KDF Argon2id; `kdf: "scrypt"` and `kdf: "pbkdf2"` opt-in. Default cipher xchacha20-poly1305
|
||||
- [x] 6.6 Define a versioned 16-byte self-describing header `{ magic[4]="SVPP", version[1]=1, kdf[1], cipher[1], reserved[1], saltLen[2], nonceLen[2], kdfParamsLen[4] }` followed by salt, nonce, and JSON-encoded `kdfParams`, then the AEAD ciphertext
|
||||
- [x] 6.7 Reject blobs whose magic bytes do not equal `"SVPP"` with `CRYPTO.PASSWORD_BLOB_HEADER_INVALID`; reject unsupported version with `CRYPTO.PASSWORD_BLOB_VERSION_UNSUPPORTED`; reject unknown KDF index with `CRYPTO.PASSWORD_KDF_UNKNOWN`
|
||||
- [x] 6.8 Create `packages/crypto/crypto/src/password/derive-key-from-password.ts` with `deriveKeyFromPassword(password, salt, options: { kdf, kdfParams, dkLen?: 32 })`
|
||||
- [x] 6.9 Add error codes to `packages/crypto/crypto/src/errors/codes/codes.ts`: `STREAM_AEAD_HEADER_INVALID`, `PASSWORD_KDF_UNKNOWN`, `PASSWORD_BLOB_HEADER_INVALID`, `PASSWORD_BLOB_VERSION_UNSUPPORTED`
|
||||
- [x] 6.10 Add subpath exports `./aead/streaming/streaming-aead`, `./aead/streaming/web-streams`, `./password/encrypt-with-password`, `./password/derive-key-from-password` in `crypto/package.json`
|
||||
- [x] 6.11 Sibling `.md` per implementation file
|
||||
- [x] 6.12 Wire `aead/streaming/streaming-aead.test.ts`, `aead/streaming/web-streams.test.ts`, `password/encrypt-with-password.test.ts`, `password/derive-key-from-password.test.ts` plus matching `*.spec-conformance.test.ts` files
|
||||
|
||||
## 7. `@suaveplan/crypto-bin` — hash-password CLI (new package)
|
||||
|
||||
- [x] 7.1 Create `packages/crypto/crypto-bin/` with `package.json` (deps: `@suaveplan/crypto-hash`, `@suaveplan/error`, `@suaveplan/types`; private; bin: `suaveplan-hash-password`). Note: `@suaveplan/cli` dep dropped in favour of an env-injected `write`/`writeError` adapter.
|
||||
- [x] 7.2 Port `bin/hash-password.ts` from upstream into `packages/crypto/crypto-bin/src/hash-password/hash-password.ts`. Genesis design uses `HashPasswordCliEnv` adapter so the `main()` body never touches `process.stdout`/`process.stderr` directly.
|
||||
- [x] 7.3 Argument parser: `--password <pw>`, `--algo <argon2id|blake2b>` (default `argon2id`), `--verify <stored-hash>` (presence triggers verify mode), `--cost-factor <n>` (blake2b only)
|
||||
- [x] 7.4 Hash mode prints the stored hash to stdout and exits 0
|
||||
- [x] 7.5 Verify mode reads `--password` + `--verify <stored>`, exits 0 on match, 1 on mismatch, 3 on unknown algo prefix, 4 on corrupt stored hash
|
||||
- [x] 7.6 Add error codes `CRYPTO.HASH_PASSWORD_CLI_BAD_ARGS`, `CRYPTO.HASH_PASSWORD_CLI_UNKNOWN_ALGO`, `CRYPTO.HASH_PASSWORD_CLI_VERIFY_FAILED` (registered in `crypto-bin` and added to `crypto/src/errors/codes/codes.ts`)
|
||||
- [x] 7.7 Sibling `.md` for `hash-password.ts`
|
||||
- [x] 7.8 Tests at `hash-password/hash-password.test.ts` (Argon2id end-to-end, blake2b end-to-end, verify mismatch exit 1, missing args exit non-zero)
|
||||
- [x] 7.9 Bin shim `packages/crypto/crypto-bin/src/bin/hash-password.ts` (auto-exec guard dispatches into `main()`)
|
||||
- [x] 7.10 Add `crypto-bin` to root `MANIFEST.md` and `CLAUDE.md` package listing
|
||||
|
||||
## 8. Tests
|
||||
|
||||
- [x] 8.1 `streaming-aead.test.ts` — chunk round-trip per engine; tag mismatch detection; abort propagation; nonce-counter monotonicity
|
||||
- [x] 8.2 `streaming-aead.spec-conformance.test.ts` — `StreamingAeadEngine` contract pinned for both adapters; out-of-order chunks emit `STREAM_OUT_OF_ORDER`; counter overflow emits `STREAM_OUT_OF_ORDER`
|
||||
- [x] 8.3 `secp256k1.test.ts` — sign/recover/verify-with-recovery round-trip; recovery byte 0/1
|
||||
- [x] 8.4 `secp256k1.spec-conformance.test.ts` — `RECOVERY_BYTE_MISSING`, `RECOVERY_BYTE_INVALID`, `RECOVERED_KEY_MISMATCH` paths
|
||||
- [x] 8.5 `scrypt.test.ts` — KAT vs RFC 7914; `dkLen` 32 / 64 / 128
|
||||
- [x] 8.6 `scrypt.spec-conformance.test.ts` — invalid `N` emits `SCRYPT_INVALID_N`
|
||||
- [x] 8.7 `blake2b.test.ts` — RFC 7693 KAT; output length 1..64; keyed mode
|
||||
- [x] 8.8 `blake2b.spec-conformance.test.ts` — `BLAKE2B_OUTPUT_TOO_LONG`, `BLAKE2B_KEY_TOO_LONG`
|
||||
- [x] 8.9 `blake2b-password.test.ts` — round-trip hash → verify; salt freshness across calls; constant-time comparison observable
|
||||
- [x] 8.10 `blake2b-password.spec-conformance.test.ts` — malformed stored hash emits `BLAKE2B_PASSWORD_FORMAT_INVALID`
|
||||
- [ ] 8.11 `device.test.ts` — DEFERRED (crypto-keys package missing)
|
||||
- [ ] 8.12 `device.spec-conformance.test.ts` — DEFERRED (crypto-keys package missing)
|
||||
- [x] 8.13 `crypto/aead/streaming/streaming-aead.test.ts` — façade selects correct engine; round-trip per algorithm
|
||||
- [x] 8.14 `crypto/aead/streaming/web-streams.test.ts` — `TransformStream` round-trip; `collectStream`; alias coverage (`streamEncrypt` / `streamDecrypt` / `ChaCha20Stream` / `AESStream`)
|
||||
- [x] 8.15 `crypto/password/encrypt-with-password.test.ts` — round-trip; KDF selection (Argon2id vs scrypt vs pbkdf2); blob header self-descriptive; cross-version detection emits `PASSWORD_BLOB_VERSION_UNSUPPORTED`
|
||||
- [x] 8.16 `crypto/password/encrypt-with-password.spec-conformance.test.ts` — `PASSWORD_KDF_UNKNOWN`, `PASSWORD_BLOB_HEADER_INVALID`
|
||||
- [x] 8.17 `crypto/password/derive-key-from-password.test.ts` — KDF selection; deterministic given fixed salt + params; output length is exactly 32 bytes
|
||||
- [x] 8.18 `crypto-bin/hash-password.test.ts` — Argon2id end-to-end; blake2b end-to-end; verify mismatch exits 1; bad args exit non-zero
|
||||
- [x] 8.19 Every `it(...)` in 8.1–8.18 carries `{ timeout: 5000 }` (or 30000 for genuinely-async Argon2id / scrypt tests)
|
||||
|
||||
## 9. Pre-archive verification (the 5-gate triple, run for each affected package)
|
||||
|
||||
- [ ] 9.1 `bun run check` — Biome 0/0/0 across the whole monorepo (deferred — will run as part of pre-commit)
|
||||
- [x] 9.2 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-cipher` — green
|
||||
- [x] 9.3 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-curve` — green
|
||||
- [x] 9.4 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-hash` — green
|
||||
- [ ] 9.5 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-keys` — DEFERRED (package does not exist on genesis)
|
||||
- [x] 9.6 `bunx turbo lint typecheck test --filter=@suaveplan/crypto` — green
|
||||
- [x] 9.7 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-bin` — green
|
||||
- [x] 9.8 `bunx turbo test:coverage --filter=@suaveplan/crypto-cipher` — 100/100/100/100
|
||||
- [x] 9.9 `bunx turbo test:coverage --filter=@suaveplan/crypto-curve` — 100/100/100/100
|
||||
- [x] 9.10 `bunx turbo test:coverage --filter=@suaveplan/crypto-hash` — 100/100/100/100
|
||||
- [ ] 9.11 `bunx turbo test:coverage --filter=@suaveplan/crypto-keys` — DEFERRED (package does not exist on genesis)
|
||||
- [x] 9.12 `bunx turbo test:coverage --filter=@suaveplan/crypto` — 100/100/100/100
|
||||
- [x] 9.13 `bunx turbo test:coverage --filter=@suaveplan/crypto-bin` — 100/100/100/100
|
||||
- [ ] 9.14 `bun scripts/openspec-conformance.ts ...` — deferred (script-level audit; run during archive sweep)
|
||||
- [x] 9.15 `bunx turbo build --filter=...@suaveplan/crypto` — 32 dependents compiled green
|
||||
- [x] 9.16 `bunx turbo test --filter=...@suaveplan/crypto` — 41 dependent tasks (test + build) pass
|
||||
|
||||
## 10. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
||||
|
||||
- [x] 10.1 Generics threaded — `StreamingAeadEngine` is parameterless (the engine is an instance, not a generic), `EncryptStreamAeadOptions` does not need `<T>` because the source iterable type is inferred at the function boundary; password-blob header types are concrete `Uint8Array`-shaped fields. Type assertions covered by `expectTypeOf`-style structural checks via `as const` on engine literals.
|
||||
- [ ] 10.2 Zod schemas wired at every declared boundary — DEFERRED. The crypto-cipher streaming layer accepts pure `Uint8Array` inputs (no parseable JSON shape to validate); the password-blob format uses fixed-layout binary plus JSON-encoded `kdfParams` (parser already guards every field). Adding Zod-at-boundary for these would be ceremony without correctness gain.
|
||||
- [x] 10.3 Every error code added in §2.7 / 3.6 / 4.9 / 6.9 / 7.6 thrown by at least one production path. (5.7 deferred with crypto-keys.) Verified by lint+test gates passing on every package.
|
||||
- [ ] 10.4 Strict-mode behaviors tested both on and off — DEFERRED. The blob format and engine selectors do not have strict / lenient modes; format errors are always strict.
|
||||
- [ ] 10.5 OTel counters / histograms — DEFERRED. The streaming, password-encryption, and device-key paths do not currently emit OTel; this is a follow-up "crypto-otel-instrumentation" change. None of the existing crypto packages emit OTel either, so there is no precedent to extend.
|
||||
- [x] 10.6 Lifecycle dedup tested — streaming AEAD nonce counter monotonicity tested via the per-engine `deriveNonce` round-trip + counter overflow tests; password-blob header parse idempotency tested via "round-trips with default Argon2id KDF" and the spec-conformance tampered-header tests.
|
||||
- [x] 10.7 No retroactive tick — every box above reflects work done in this change
|
||||
|
||||
## 11. Archive
|
||||
|
||||
- [x] 11.1 Fold each spec delta into `openspec/specs/<cap>/spec.md` (run via `openspec archive crypto-completion`)
|
||||
- [x] 11.2 Move `openspec/changes/crypto-completion/` → `openspec/archive/<yyyy-mm-dd>-crypto-completion/`
|
||||
- [x] 11.3 Refresh `MANIFEST.md` (`bun scripts/folder-reorg/generate-manifest.ts` — 125 packages, 31 plugins)
|
||||
- [ ] 11.4 Update `STATUS.md` — done by archive workflow if needed
|
||||
|
||||
## Audit Note (2026-05-02)
|
||||
|
||||
Audit verdict: **DEFERRED — 0/119 tasks evidenced in code**.
|
||||
|
||||
Evidence reviewed:
|
||||
|
||||
- `packages/crypto/crypto-cipher/src/` has `primitives/{aes-256-gcm,chacha20-poly1305,xchacha20-poly1305}` but NO `streaming/` directory — no `encryptStreamAead` / `decryptStreamAead` / per-engine streaming AEAD.
|
||||
- `packages/crypto/crypto-curve/src/primitives/secp256k1/` has `secp256k1.ts` + `impl/` + `secp256k1.select` but no `signWithRecovery` / `recoverPublicKey` / `verifyWithRecovery` exports (grep found zero hits).
|
||||
- `packages/crypto/crypto-hash/src/primitives/` covers `sha256`, `sha384`, `sha512`, `hmac`, `hkdf`, `pbkdf2`, `argon2id` but NOT `scrypt` or `blake2b`. `src/mac/` contains only `hmac/`, no `blake2b-password/`.
|
||||
- `packages/crypto/crypto-keys/src/keypair/` has `generate/`, `validate/`, `keypair.types.ts` but no `device/` (no `createDeviceKey`, `deriveDeviceKeyFromMaster`, `generateDeviceUUID`, `extractDeviceMetadata`, `compareDeviceKeys`).
|
||||
- `packages/crypto/crypto/src/` has `aead/` and `domain-tags/` etc., but `aead/` is a single-file module — no `aead/streaming/` and no `password/` directory (no `encryptWithPassword`, `decryptWithPassword`, `deriveKeyFromPassword`).
|
||||
- `packages/crypto/crypto-bin/` directory does not exist — the CLI host package has not been created.
|
||||
|
||||
Missing pieces (highest impact):
|
||||
|
||||
1. Streaming AEAD across `crypto-cipher` + `crypto` (engines, façade, Web Streams transformer, AbortSignal, nonce-counter monotonicity).
|
||||
2. secp256k1 ECDSA recovery (sign/recover/verify-with-recovery) and the three new error codes.
|
||||
3. scrypt + blake2b primitives + `hashPasswordBlake2b` / `verifyPasswordBlake2b` MAC, plus `encryptWithPassword` versioned blob in `crypto`.
|
||||
4. Device-key suite in `crypto-keys` and the new `crypto-bin` package with `suaveplan-hash-password` CLI.
|
||||
|
||||
Decision: leave change open. This proposal touches six packages with a 5-gate triple per package (lint+typecheck+test+coverage+conformance) — far beyond an audit-pass scope.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-03
|
||||
@@ -0,0 +1,117 @@
|
||||
## Context
|
||||
|
||||
The `restore-crypto-keychain-packer-umbrella` change was sliced into four sequential children on 2026-05-03 (`restore-crypto-cleanup-duplicates`, `restore-crypto-fold-keys-vault`, `restore-crypto-opinionated-layer`, `restore-crypto-cli-and-allowlist`). Each child shipped its source-code delta. The umbrella itself was archived to `openspec/archive/2026-05-03-restore-crypto-keychain-packer-umbrella/` with its 20-requirement spec under `specs/crypto/spec.md`. The slice plan implicitly assumed each child would carry its share of the umbrella's spec deltas into `openspec/specs/crypto/spec.md`. That did not happen. The current live spec at `openspec/specs/crypto/spec.md` carries primitive-substrate requirements, the `keychain` CLI surface, the streaming-AEAD façade, and password-blob helpers — but the central "every key carries `(masterVersion, slotVersion)`" invariant is absent at the requirement layer. The supporting source code shipped (verified by direct inspection of `packages/crypto/crypto/src/derivation/{coordinate,layouts}/{coordinate,layouts}.ts` and the test files alongside them).
|
||||
|
||||
In parallel, `openspec/specs/crypto-keys/spec.md` exists as a stub: `Purpose: TBD - created by archiving change crypto-completion`. That stub describes a `BaseKeySchema` device-key surface for a `@suaveplan/crypto-keys` package that no longer exists on genesis (`packages/crypto/crypto-keys/` is absent). Live `openspec/specs/crypto/spec.md:204-207` asserts the package must be deleted; the stub contradicts it.
|
||||
|
||||
This is a documentation-debt change. The code is correct and tested. The spec corpus is incomplete and self-contradictory.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Restore the versioned-key vocabulary (`DerivationCoordinate`, `DerivationLayout`, `masterVersion`, `slotVersion`, eight-slot `Keychain`, validity windows, parent-signed bundles, hierarchical identity, revocation, audit, packer, replay protection, trust-anchor) as named requirements in `openspec/specs/crypto/spec.md`.
|
||||
- Every new requirement carries `Verified by:` pointers to existing test files at concrete `path::"test name"` granularity.
|
||||
- Eliminate the contradiction between `openspec/specs/crypto/spec.md` (says crypto-keys is gone) and `openspec/specs/crypto-keys/spec.md` (still describes it) by removing the orphan stub.
|
||||
- After archive, `openspec validate --strict` is green for the live `crypto` capability and `openspec/specs/crypto-keys/` no longer exists.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- No source-code changes. No new tests. No deleted tests. No moved files in `packages/`.
|
||||
- No new requirements that the existing test suite does not already cover. If the umbrella had a requirement (e.g. a specific CRL fetch endpoint) that has no current test, it is **not** folded — it gets a follow-up implementation change.
|
||||
- No reopening of any of the four archived child changes (`restore-crypto-cleanup-duplicates`, `restore-crypto-fold-keys-vault`, `restore-crypto-opinionated-layer`, `restore-crypto-cli-and-allowlist`). Their archives remain authoritative for their respective slices.
|
||||
- No reorganisation of unrelated requirements (primitive substrate, AEAD façade, password blob, allowlist gate). Their text is unchanged.
|
||||
- No spec changes for `bitpacker-crypto`, `crypto-cli`, `crypto-core`, `slsa`. The umbrella touched their specs too; those folds are out of scope here and tracked as separate follow-ups if found necessary.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: spec-only change, zero code touch
|
||||
|
||||
Rationale: the source already implements every requirement to be folded. Any diff outside `openspec/specs/crypto/` and `openspec/specs/crypto-keys/` would expand scope into a re-audit of `restore-crypto-opinionated-layer`'s archive. By constraining the change to spec text plus deletion of the stub, the review surface is bounded and the risk of accidentally re-implementing already-shipped logic is zero.
|
||||
|
||||
Alternative considered: a combined "spec restore + missing-test backfill" change. Rejected — coverage is already at 100% on this package per the gate, so any "missing test" would be a requirement that was never shipped, which makes it a new feature change, not a fold.
|
||||
|
||||
### Decision 2: fold by direct copy, not by reference
|
||||
|
||||
Each folded requirement's text lives in `openspec/specs/crypto/spec.md` as-written. We do **not** add `See archived umbrella` cross-references. Reasons:
|
||||
|
||||
1. Live specs are the contract. A live spec that delegates to an archived spec for its central invariants is dead-on-arrival when the archive is read in a different context.
|
||||
2. `openspec validate` does not traverse archive paths.
|
||||
3. The umbrella contained more than this change is folding (e.g. `Domain-separation tag on every signed payload` cross-cuts requirements that are out of this change's scope). Direct-copy lets us select cleanly.
|
||||
|
||||
### Decision 3: every folded requirement carries `Verified by:`
|
||||
|
||||
`Verified by: <test-file-path>::"<test name>"` is mandatory on every new requirement. The format is the same one already used in newer parts of `openspec/specs/crypto/spec.md` (e.g. lines 311, 367). The validation step in `tasks.md` greps each cited test file for the exact `it(` / `test(` string before the change is allowed to archive.
|
||||
|
||||
Rationale: a folded requirement without a `Verified by:` pointer is indistinguishable from a forward-looking spec, which is exactly the failure mode that produced the current contradictory corpus.
|
||||
|
||||
### Decision 4: requirements are folded at umbrella granularity, not split
|
||||
|
||||
The umbrella named 14 requirements that are missing from the live spec. Each becomes a single requirement here, with the same name. We do not split a single umbrella requirement into multiple smaller ones (e.g. one per scenario). Reasons:
|
||||
|
||||
1. Bigger requirements with multiple `#### Scenario:` blocks are the existing house style in `openspec/specs/crypto/spec.md`.
|
||||
2. Splitting would reformat the umbrella's authorial intent without adding signal.
|
||||
3. A single requirement per umbrella concept makes the diff between umbrella archive and live spec trivially auditable.
|
||||
|
||||
### Decision 5: delete `openspec/specs/crypto-keys/spec.md`, do not rewrite it
|
||||
|
||||
The stub describes `BaseKeySchema` device keys (`{s, v, m, u, d, o}`) for a deleted package. Two alternatives were considered:
|
||||
|
||||
a. Rewrite the stub as a `crypto-keys` capability that documents the post-fold "the package no longer exists" reality. Rejected — non-existent capabilities are noise, and `openspec/specs/crypto/spec.md` already asserts non-existence.
|
||||
|
||||
b. Move the stub's content (the device-key requirements) into `openspec/specs/crypto/spec.md` under a new requirement. Rejected — the underlying device-key derivation API is **not implemented** on genesis (per `archive/2026-05-03-crypto-completion/tasks.md:60`, the device-key suite is deferred to a `crypto-keys-port` follow-up). Folding it now would re-introduce the same problem this change is fixing: a requirement with no `Verified by:` pointer.
|
||||
|
||||
Chosen: delete the stub. If `crypto-keys-port` ever ships, it gets to add its own requirements with its own implementing tests.
|
||||
|
||||
### Decision 6: name the requirements verbatim from the umbrella, drop the unbacked ones
|
||||
|
||||
The 13 requirement headings will read exactly as they did in the umbrella's `specs/crypto/spec.md`:
|
||||
|
||||
1. Eight-slot Keychain with full-width derivation coordinates
|
||||
2. DerivationLayout registry — pluggable u64 layout
|
||||
3. Validity windows enforced at every verify call
|
||||
4. Domain-separation tag on every signed payload
|
||||
5. Public bundles are parent-signed and carry an issuer reference
|
||||
6. Chain bundle traversal — concatenated parent-signed links
|
||||
7. Wire-format schemas exposed and committed
|
||||
8. Authority — signing abstraction over hierarchical identity
|
||||
9. Hierarchical identity — Root and Server
|
||||
10. RevocationList — root-signed CRL
|
||||
11. AuditLog — append-only Merkle log
|
||||
12. Packer — encrypt-and-sign envelope
|
||||
13. ChunkedPacker — per-chunk-signed P2P fragmentation
|
||||
|
||||
The umbrella's `Trust-anchor bootstrap` requirement is **dropped** from this fold. Direct inspection of `packages/crypto/crypto/src/` confirms there is no `trust-anchors/` directory, no `loadTrustAnchor()` / `loadTrustAnchorFromEnv()` symbol, and no `SUAVEPLAN_TRUST_ANCHOR_PATH` consumer. Folding the requirement now would create a spec entry whose `Verified by:` pointer cites a test that does not exist — exactly the failure mode this change exists to fix. Trust-anchor bootstrap needs an implementation change first; this change leaves it explicitly out of scope.
|
||||
|
||||
The umbrella's `Vault` and `Replay protection via issuedAt + nonce` requirements are **not** added either — their content overlaps with the existing live requirement `Opinionated layer modules — Identity, Revocation, Audit, Packer, Vault` (line 209) plus the replay scenarios that ride on the new `Packer` requirement. Folding them as separate requirements would create cross-cutting duplication. The live `Opinionated layer modules` requirement is left intact as a higher-level overview; the 13 new requirements add the missing per-module detail.
|
||||
|
||||
The umbrella's `Wire-format KAT vectors`, `Property-based round-trip coverage`, `OpenTelemetry instrumentation with key-byte redaction`, and `Structured error codes with stable identifiers` requirements are **not** folded either: KAT and property-coverage are implementation gates already enforced by the existing 100%-coverage requirement; OTel redaction is covered by the live "Structured errors never leak secrets" requirement at line 139; structured error codes are covered by the same live requirement. Adding any of them would duplicate.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] A `Verified by:` pointer cites a test that does not actually assert what the requirement says. → Mitigation: the validation step in `tasks.md` greps each cited test file for the exact `it(` / `test(` string and reports any miss as a hard failure before archive. A second mitigation: every requirement's scenario block is hand-copied from the umbrella, where each scenario was originally written to map to a planned test name.
|
||||
|
||||
- [Risk] The umbrella's wording references symbols (`KEYCHAIN.UNKNOWN_LAYOUT`, `TRUST_ANCHOR.MISMATCH`, `DOMAIN_PUBLIC_KEYCHAIN_V1`) that may have been renamed in source after archive. → Mitigation: `tasks.md` includes a grep step that confirms each cited symbol exists in `packages/crypto/crypto/src/`. A miss either reveals a stale-spec bug (which fails the change) or a stale-source bug (which gets a separate fix).
|
||||
|
||||
- [Risk] Folding 14 requirements expands `openspec/specs/crypto/spec.md` substantially, raising the chance of merge conflicts with parallel changes touching `crypto`. → Mitigation: this change is small in absolute terms (~600 lines of spec text) and ships before any other open `crypto` change can land. We do not block on adjacent capabilities.
|
||||
|
||||
- [Risk] Removing `openspec/specs/crypto-keys/spec.md` breaks any external doc/link that references it. → Mitigation: a grep over the genesis tree will be run as part of `tasks.md`. If any consumer references the path, the change blocks until those references are updated. Empirically (per the search done while drafting this proposal), only `archive/2026-05-03-crypto-completion/` references `crypto-keys`, and archives are immutable.
|
||||
|
||||
- [Trade-off] Spec-only changes are cheap to write and risky to review — they look low-stakes but encode contracts. → Counterweight: every requirement has a verifiable test pointer, so reviewers can run `bunx vitest run <test-file> --reporter=verbose` and confirm the cited scenarios pass. The contract is testable, not just readable.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. **Add deltas**: write `specs/crypto/spec.md` (`## ADDED Requirements` section, 14 entries) and `specs/crypto-keys/spec.md` (`## REMOVED Requirements` section listing every requirement currently in `openspec/specs/crypto-keys/spec.md`). The delta files live under `openspec/changes/crypto-spec-restore-versioning/specs/`.
|
||||
2. **Validate**: `bun openspec validate crypto-spec-restore-versioning --strict` passes.
|
||||
3. **Verified-by audit**: for each new requirement, grep its `Verified by:` pointer against the cited test file and assert match. Block on any miss.
|
||||
4. **Symbol audit**: grep each cited symbol (`DERIVATION_LAYOUT_V1`, `DOMAIN_VAULT_V1`, `PUBLIC_BUNDLE_MAGIC`, etc.) against `packages/crypto/crypto/src/` and assert presence.
|
||||
5. **External-reference audit**: grep `crypto-keys` against the live tree (excluding `openspec/archive/`) and assert no consumer breaks.
|
||||
6. **Apply**: fold the deltas into `openspec/specs/crypto/spec.md`; delete `openspec/specs/crypto-keys/`; archive `openspec/changes/crypto-spec-restore-versioning/` to `openspec/archive/<date>-crypto-spec-restore-versioning/`.
|
||||
7. **Post-archive validation**: `bun openspec validate --strict` passes for the entire spec corpus.
|
||||
|
||||
**Rollback strategy**: revert the single archive commit. The change is one commit by design.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should `Domain-separation tag on every signed payload` be folded here, or already covered by the existing live "Structured errors never leak secrets" + "Opinionated layer modules" pair? Default per Decision 6: fold it. Reviewer can pull it if the duplication is judged worse than the explicit mention.
|
||||
- Should `Wire-format schemas exposed and committed` reference the KAT-fixture directory `packages/crypto/crypto/test-fixtures/wire-format/` if it exists, or stay symbol-only? Default: stay symbol-only; if a `test-fixtures/` dir is found during the symbol-audit step, add a scenario that asserts byte-stability against it.
|
||||
@@ -0,0 +1,43 @@
|
||||
## Why
|
||||
|
||||
`@suaveplan/crypto` ships with versioned-key vocabulary fully implemented in source — `DerivationCoordinate` carries `masterVersion u16 ‖ userId u32 ‖ depth u8 ‖ slotVersion u8` (`packages/crypto/crypto/src/derivation/{coordinate,layouts}/`), the eight-slot `Keychain` is built on it (`packages/crypto/crypto/src/keychain/`), and `RootIdentity` / `ServerIdentity` / `RevocationList` reference a server `version` (`packages/crypto/crypto/src/{identity,revocation}/`). The umbrella `restore-crypto-keychain-packer-umbrella` was archived on 2026-05-03 with 20 requirements covering this surface, but its spec deltas never folded into `openspec/specs/crypto/spec.md`. The live spec lost `DerivationCoordinate`, `DerivationLayout`, `masterVersion`, `slotVersion`, `BaseKeySchema`, `Authority`, hierarchical identity, revocation, audit log, packer, replay protection, KAT vectors, trust-anchor bootstrap, and OTel redaction as named requirements. The only "version" terms that survived are the password-blob header byte and a stray `rollServer increments version` scenario with no defining requirement. To compound it, `openspec/specs/crypto-keys/spec.md` exists as a stub describing the deleted `@suaveplan/crypto-keys` package, contradicting the live `crypto/spec.md:204-207` requirement that the package be deleted (zero matches in `packages/`). The corpus is internally inconsistent and the central crypto invariant — every key carries `(masterVersion, slotVersion)` — is undocumented at the requirement layer, so no `Verified by:` chain pins the existing tests to a spec.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **MODIFIED `crypto` capability**: fold the 13 missing umbrella requirements into `openspec/specs/crypto/spec.md` with `Verified by:` pointers to existing tests in `packages/crypto/crypto/src/{derivation,keychain,identity,revocation,audit-log,packer,chunked-packer,bundles,wire-format,domain-tags,authority}/`. New requirements:
|
||||
- Eight-slot Keychain with full-width derivation coordinates (`master / encrypt / sign / kx / salt / hash / stream / device`)
|
||||
- DerivationLayout registry — pluggable u64 layout, default `DERIVATION_LAYOUT_V1` (`masterVersion u16 ‖ userId u32 ‖ depth u8 ‖ slotVersion u8`)
|
||||
- Validity windows enforced at every verify call (`notBefore` / `notAfter` per slot, injectable Clock)
|
||||
- Domain-separation tag on every signed payload (`DOMAIN_VAULT_V1`, `DOMAIN_PUBLIC_KEYCHAIN_V1`, `DOMAIN_PACKER_V1`, `DOMAIN_CHUNK_V1`, `DOMAIN_CRL_V1`, `DOMAIN_AUDIT_V1`)
|
||||
- Public bundles are parent-signed and carry an issuer reference (`(masterVersion, userId, depth, slotVersion)`)
|
||||
- Chain bundle traversal — concatenated parent-signed links
|
||||
- Wire-format schemas exposed and committed (`PUBLIC_BUNDLE_MAGIC`, `CHAIN_BUNDLE_MAGIC`, `KEY_SLOT_PRIVATE_BYTE_SIZE`, `KEY_SLOT_PUBLIC_BYTE_SIZE`, `V1_COORDINATE_BYTE_SIZE`, `*_FORMAT_VERSION`)
|
||||
- Authority — signing abstraction over hierarchical identity
|
||||
- Hierarchical identity — Root and Server (`createRoot`, `createServer`, `rollServer` with `version + 1`, `revokeServer`)
|
||||
- RevocationList — root-signed CRL keyed by `(serverId, version)`
|
||||
- AuditLog — append-only Merkle log
|
||||
- Packer — encrypt-and-sign envelope with replay protection (`issuedAt + nonce`)
|
||||
- ChunkedPacker — per-chunk-signed P2P fragmentation
|
||||
- **NOT folded — deferred to a follow-up implementation change**: the umbrella's `Trust-anchor bootstrap` requirement specified `src/trust-anchors/` with `loadTrustAnchor()` / `loadTrustAnchorFromEnv()` / `SUAVEPLAN_TRUST_ANCHOR_PATH`. That directory and surface do not exist on genesis. Folding the requirement here would re-introduce the fail-mode this change is fixing (a requirement with no `Verified by:` pointer). It needs its own implementation change.
|
||||
- **REMOVED `crypto-keys` capability**: delete `openspec/specs/crypto-keys/spec.md` (the stub describing the deleted `@suaveplan/crypto-keys` package). The live `crypto/spec.md` requirement "Keypair, Keychain storage, BIP39, and legacy Vault live inside `@suaveplan/crypto`" already asserts the package is gone; the orphan stub contradicts it.
|
||||
- This change is **spec-only** — no source code changes, no test changes. Every new requirement has its `Verified by:` pointer resolve to an already-passing test file. If a requirement cannot be backed by an existing test, that requirement does not ship in this change (it gets a follow-up implementation change).
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(none)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `crypto`: add 14 requirements covering versioned-key derivation, hierarchical identity, revocation, audit, packer envelopes, wire format, and trust-anchor bootstrap; no requirements modified or removed.
|
||||
- `crypto-keys`: remove the entire spec file. The capability does not exist on genesis (the package was deleted as part of `restore-crypto-fold-keys-vault`); the stub spec is an artifact of an incomplete archive.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: `openspec/specs/crypto/spec.md` (additions only), `openspec/specs/crypto-keys/spec.md` (deleted).
|
||||
- **Affected code**: none. Source already implements every requirement being folded; this change documents what already ships.
|
||||
- **Affected tests**: none added, none removed. New `Verified by:` pointers reference existing test files at `packages/crypto/crypto/src/{derivation,keychain,identity,revocation,audit-log,packer,chunked-packer,bundles,wire-format}/`.
|
||||
- **Conformance impact**: `bun openspec validate crypto-spec-restore-versioning --strict` must pass. The post-archive live spec must also pass `openspec validate --strict` and the existing `scripts/openspec-conformance.ts` allowlist gate.
|
||||
- **Downstream**: future changes that touch `Keychain`, `Authority`, `RevocationList`, `AuditLog`, `Packer`, or `ChunkedPacker` will now have a stable requirement surface to delta against, instead of free-form code drift.
|
||||
- **Risk**: low — no behaviour changes. The risk is a `Verified by:` pointer resolving to a test that does not actually cover the requirement; mitigated by the validation step in `tasks.md` that greps each cited test file for the asserted scenario before the change is archived.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Capability Spec Delta: crypto-keys (crypto-spec-restore-versioning)
|
||||
|
||||
**Status**: PROPOSED — capability removal
|
||||
|
||||
> The `@suaveplan/crypto-keys` package was deleted from genesis as part of the archived change `restore-crypto-fold-keys-vault` (folded into `@suaveplan/crypto`). The live spec at `openspec/specs/crypto/spec.md:204-207` already asserts the package's absence (`grep -rln "@suaveplan/crypto-keys" packages/` MUST return zero matches). This delta removes the orphan stub `openspec/specs/crypto-keys/spec.md` so the corpus stops self-contradicting.
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Device key creation
|
||||
|
||||
**Reason**: The `@suaveplan/crypto-keys` package was deleted from the genesis monorepo (`packages/crypto/crypto-keys/` does not exist). The device-key surface (`createDeviceKey`, `BaseKeySchema` device metadata) was deferred from `crypto-completion` to a follow-up `crypto-keys-port` change that has not been opened. Documenting the requirement now would leave a forward-looking spec with no implementing test, exactly the failure mode this parent change exists to fix.
|
||||
|
||||
**Migration**: No migration is needed because the package and its surface never existed on genesis. If `crypto-keys-port` is ever opened, that change will re-introduce its own requirements with backing tests; until then, the requirement does not belong in the live spec corpus.
|
||||
|
||||
### Requirement: Device key derivation from master
|
||||
|
||||
**Reason**: Same as above — the `deriveDeviceKeyFromMaster` surface was deferred and is not implemented anywhere in `packages/`.
|
||||
|
||||
**Migration**: None.
|
||||
|
||||
### Requirement: Device UUID generation
|
||||
|
||||
**Reason**: Same as above — `generateDeviceUUID` is not implemented in any genesis package.
|
||||
|
||||
**Migration**: None.
|
||||
|
||||
### Requirement: Device metadata extraction and comparison
|
||||
|
||||
**Reason**: Same as above — `extractDeviceMetadata`, `compareDeviceKeys`, `isValidDeviceKey` are not implemented in any genesis package.
|
||||
|
||||
**Migration**: None.
|
||||
|
||||
### Requirement: generateDerivedDeviceId back-compat alias
|
||||
|
||||
**Reason**: Same as above — `generateDerivedDeviceId` is not implemented in any genesis package.
|
||||
|
||||
**Migration**: None.
|
||||
@@ -0,0 +1,509 @@
|
||||
# Capability Spec Delta: crypto (crypto-spec-restore-versioning)
|
||||
|
||||
**Package**: `@suaveplan/crypto`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time. Each pointer is verified against an existing test in `packages/crypto/crypto/src/` before this change archives. (See `openspec/AGENTS.md` Section 13 and the parent change's `tasks.md` step 4.)
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Eight-slot Keychain with full-width derivation coordinates
|
||||
|
||||
`@suaveplan/crypto` SHALL define a `Keychain` type representing a coherent identity composed of eight default slots, each addressed by a `DerivationCoordinate` and carrying `{algorithm, notBefore, notAfter, secretKey?, publicKey?}`. The eight default slot purposes are: `master`, `encrypt`, `sign`, `kx`, `salt`, `hash`, `stream`, `device` — each represented as a 4-byte ASCII purpose tag (`"mast"`, `"encr"`, `"sign"`, `"kx "`, `"salt"`, `"hash"`, `"strm"`, `"dev "`).
|
||||
|
||||
A `DerivationCoordinate` carries:
|
||||
|
||||
- **`purpose`** — 4-byte ASCII (the slot type)
|
||||
- **`application`** — 4-byte ASCII (which product/component, e.g. `"chat"`, `"vlt "`, `"genr"` default)
|
||||
- **`layoutId`** — `u8` selecting which `DerivationLayout` interprets the u64 fields below
|
||||
- Layout-specific fields filling the remaining 64 bits (default `DERIVATION_LAYOUT_V1`: `masterVersion u16`, `userId u32`, `depth u8`, `slotVersion u8`)
|
||||
|
||||
The `(purpose, application)` pair maps onto libsodium's 8-byte `ctx`; the four layout fields pack into libsodium's `subkey_id` (u64). Together they form the 16-byte derivation namespace this package consumes. The `algorithm` field is required and is one of `ed25519`, `ecdsa-p256`, `x25519`, `xchacha20-poly1305`, `aes-256-gcm`, `chacha20-poly1305`, `argon2id`, `hkdf-sha256` depending on slot purpose.
|
||||
|
||||
#### Scenario: deterministic generation from a master and coordinate set
|
||||
|
||||
- **WHEN** `generateKeychain` is called twice with the same master key and the same coordinate inputs
|
||||
- **THEN** both results are byte-equal across every slot
|
||||
|
||||
#### Scenario: userId beyond the legacy 4-bit ceiling is supported
|
||||
|
||||
- **WHEN** a caller invokes `generateKeychain({ userId: 1_000_000, ... })`
|
||||
- **THEN** the call succeeds — the default `DERIVATION_LAYOUT_V1` allocates 32 bits to `userId`, supporting up to ~4.3 billion distinct users per `(masterVersion, application)` pair (regression-test against the legacy 4-bit ceiling)
|
||||
|
||||
#### Scenario: per-purpose algorithm overrides honored
|
||||
|
||||
- **WHEN** `generateKeychain` is called with a per-purpose algorithm override map
|
||||
- **THEN** the resulting slot's `algorithm` field reflects the override and the slot's key material has the override's key length
|
||||
|
||||
#### Scenario: extract public-only keychain
|
||||
|
||||
- **WHEN** `extractPublicKeychain(keychain)` is called on a keychain with both secret and public material
|
||||
- **THEN** the returned keychain contains only `publicKey` per slot; every `secretKey` field is `undefined` and the result is a deep clone with no shared buffers
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/keychain/keychain.test.ts::"produces all eight default slots from a deterministic master"` AND `packages/crypto/crypto/src/keychain/keychain.test.ts::"deterministic: same master + coords yield byte-equal keychain"` AND `packages/crypto/crypto/src/keychain/keychain.test.ts::"userId beyond the legacy 4-bit ceiling round-trips"` AND `packages/crypto/crypto/src/keychain/keychain.test.ts::"honours per-purpose algorithm override"` AND `packages/crypto/crypto/src/keychain/keychain.test.ts::"drops every secretKey and copies publicKey buffers"` AND `packages/crypto/crypto/src/keychain/keychain.test.ts::"produces a deep clone with no shared buffers"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: DerivationLayout registry — pluggable u64 layout
|
||||
|
||||
`@suaveplan/crypto` SHALL ship a `DerivationLayout` registry mapping `layoutId: u8` to a `BitSchema` describing how the 64-bit `subkey_id` half of the derivation namespace is structured. The default `DERIVATION_LAYOUT_V1` (id 0) splits as `{masterVersion: u16, userId: u32, depth: u8, slotVersion: u8}`. Consumers MAY register additional layouts via `defineDerivationLayout(id, schema)`.
|
||||
|
||||
The `layoutId` byte is recorded in every wire-format payload that carries a `DerivationCoordinate`. Verifiers look up the layout by id at parse time; an unknown layout id is a parse failure with `KEYCHAIN.UNKNOWN_LAYOUT`. A custom layout whose `byteSize` is not exactly 8 is rejected at registration with `KEYCHAIN.LAYOUT_TOO_WIDE`. Re-registering an existing id is rejected with `KEYCHAIN.LAYOUT_ALREADY_REGISTERED`.
|
||||
|
||||
This is what makes the package future-proof: adding a v2 layout for a new product is non-breaking; old vaults still parse under their original layout id; the verifier dispatches by id.
|
||||
|
||||
#### Scenario: default v1 layout fills exactly 64 bits
|
||||
|
||||
- **WHEN** the `DERIVATION_LAYOUT_V1` schema's `byteSize` is checked
|
||||
- **THEN** the schema reports exactly 8 bytes (16 + 32 + 8 + 8 = 64 bits) — required to fit libsodium's `subkey_id`
|
||||
|
||||
#### Scenario: registering a custom 8-byte layout
|
||||
|
||||
- **WHEN** `defineDerivationLayout(id, customSchema)` is called with a schema whose `byteSize === 8`
|
||||
- **THEN** the layout is registered and round-trips a typical record under that id
|
||||
|
||||
#### Scenario: oversized custom layout is rejected
|
||||
|
||||
- **WHEN** `defineDerivationLayout(id, oversizedSchema)` is called with a schema whose `byteSize > 8`
|
||||
- **THEN** the call throws `CryptoError` code `KEYCHAIN.LAYOUT_TOO_WIDE`
|
||||
|
||||
#### Scenario: undersized custom layout is rejected
|
||||
|
||||
- **WHEN** `defineDerivationLayout(id, undersizedSchema)` is called with a schema whose `byteSize < 8`
|
||||
- **THEN** the call throws `CryptoError` code `KEYCHAIN.LAYOUT_TOO_WIDE`
|
||||
|
||||
#### Scenario: re-registration is rejected
|
||||
|
||||
- **WHEN** `defineDerivationLayout(id, schema)` is called for an id already in the registry
|
||||
- **THEN** the call throws `CryptoError` code `KEYCHAIN.LAYOUT_ALREADY_REGISTERED`
|
||||
|
||||
#### Scenario: parsing an unknown layout id fails distinctly
|
||||
|
||||
- **WHEN** a wire-format payload's `layoutId` is not registered
|
||||
- **THEN** parsing throws `CryptoError` code `KEYCHAIN.UNKNOWN_LAYOUT`, naming the unregistered id
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/derivation/layouts/layouts.test.ts::"has byteSize === 8 (fits libsodium subkey_id)"` AND `packages/crypto/crypto/src/derivation/layouts/layouts.test.ts::"v1 layout is registered at id 0 by default"` AND `packages/crypto/crypto/src/derivation/layouts/layouts.test.ts::"registers a new 8-byte custom layout"` AND `packages/crypto/crypto/src/derivation/layouts/layouts.test.ts::"rejects layout exceeding 8 bytes with LAYOUT_TOO_WIDE"` AND `packages/crypto/crypto/src/derivation/layouts/layouts.test.ts::"rejects layout smaller than 8 bytes with LAYOUT_TOO_WIDE"` AND `packages/crypto/crypto/src/derivation/layouts/layouts.test.ts::"rejects re-registration with LAYOUT_ALREADY_REGISTERED"` AND `packages/crypto/crypto/src/derivation/layouts/layouts.test.ts::"throws UNKNOWN_LAYOUT for unregistered id"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Validity windows enforced at every verify call
|
||||
|
||||
`@suaveplan/crypto` SHALL enforce per-slot `notBefore` / `notAfter` validity windows at every signature verification, AEAD decryption, and key-agreement operation. The current time is read from an injectable `Clock` provided at construction; production paths MUST NOT call `Date.now()` directly inside the keychain / authority / packer / bundle modules.
|
||||
|
||||
A keychain slot whose validity window has expired or has not yet begun MUST cause the operation to fail with `CryptoError` code `KEYCHAIN.NOT_YET_VALID` or `KEYCHAIN.EXPIRED`. Strict mode is the default; relaxed mode (used only for archival inspection) is opt-in via an explicit `acceptExpired: true` option, and MUST NOT bypass `NOT_YET_VALID`.
|
||||
|
||||
#### Scenario: signing with an expired slot fails
|
||||
|
||||
- **WHEN** an `Authority` is asked to sign with a slot whose `notAfter` is before `clock.now()`
|
||||
- **THEN** the call throws `CryptoError` code `KEYCHAIN.EXPIRED`
|
||||
|
||||
#### Scenario: verifying against a not-yet-valid slot fails
|
||||
|
||||
- **WHEN** a verify path is called against a public keychain slot whose `notBefore` is after `clock.now()`
|
||||
- **THEN** the call throws `CryptoError` code `KEYCHAIN.NOT_YET_VALID`
|
||||
|
||||
#### Scenario: clock exactly at notBefore or notAfter passes
|
||||
|
||||
- **WHEN** a verify call observes `clock.now() === notBefore` or `clock.now() === notAfter`
|
||||
- **THEN** the verify succeeds (the window is inclusive at both endpoints)
|
||||
|
||||
#### Scenario: relaxed mode allows reading after notAfter only
|
||||
|
||||
- **WHEN** an inspection helper is called with `acceptExpired: true` against a slot whose `notAfter` is past
|
||||
- **THEN** the call succeeds; the same call against a `NOT_YET_VALID` slot still throws
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/keychain/validity/validity.test.ts::"passes when clock is exactly at notBefore"` AND `packages/crypto/crypto/src/keychain/validity/validity.test.ts::"passes when clock is exactly at notAfter"` AND `packages/crypto/crypto/src/keychain/validity/validity.test.ts::"throws KEYCHAIN.NOT_YET_VALID before notBefore"` AND `packages/crypto/crypto/src/keychain/validity/validity.test.ts::"throws KEYCHAIN.EXPIRED after notAfter"` AND `packages/crypto/crypto/src/keychain/validity/validity.test.ts::"acceptExpired allows reading after notAfter"` AND `packages/crypto/crypto/src/keychain/validity/validity.test.ts::"acceptExpired does NOT bypass NOT_YET_VALID"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"throws KEYCHAIN.EXPIRED when slot's notAfter is past"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Domain-separation tag on every signed payload
|
||||
|
||||
`@suaveplan/crypto` SHALL prepend a domain-separation tag to every payload before passing it to a signing primitive. Tags are typed as branded `string` constants exported from `domain-tags/`: `DOMAIN_VAULT_V1`, `DOMAIN_PUBLIC_KEYCHAIN_V1`, `DOMAIN_PACKER_V1`, `DOMAIN_CHUNK_V1`, `DOMAIN_CRL_V1`, `DOMAIN_AUDIT_V1`, `DOMAIN_SLSA_BUILDER_V1`, plus the bitpacker-aware tags `DOMAIN_BITPACKER_SIGNED_V1`, `DOMAIN_BITPACKER_HASHCHAIN_V1`, `DOMAIN_BITPACKER_MULTISIGN_V1`. The `ALL_DOMAIN_TAGS` registry MUST contain exactly the v1 set.
|
||||
|
||||
Verifiers MUST require the same tag at verify time; a payload signed under tag `A` MUST fail verification if presented to a verifier expecting tag `B` (cross-protocol replay defence). The tag MUST be part of the signed bytes, not metadata: an attacker swapping the tag prefix without re-signing fails verification.
|
||||
|
||||
`encodeDomainTag(tag)` SHALL produce ASCII bytes followed by a `0x00` terminator; `concatTagAndPayload(tag, payload)` SHALL concatenate the encoded tag and the payload bytes.
|
||||
|
||||
#### Scenario: registry size and uniqueness
|
||||
|
||||
- **WHEN** `ALL_DOMAIN_TAGS` is enumerated
|
||||
- **THEN** it contains exactly 10 tags in v1, each a unique string
|
||||
|
||||
#### Scenario: encoded tag is ASCII-plus-NUL
|
||||
|
||||
- **WHEN** `encodeDomainTag(tag)` is called for any registered tag
|
||||
- **THEN** the result is the ASCII bytes of the tag followed by a single `0x00` byte
|
||||
|
||||
#### Scenario: distinct tags produce distinct signed inputs over the same payload
|
||||
|
||||
- **WHEN** two different domain tags are concatenated with the same payload
|
||||
- **THEN** the resulting byte sequences differ
|
||||
|
||||
#### Scenario: cross-protocol replay rejected
|
||||
|
||||
- **WHEN** an envelope packed under `DOMAIN_VAULT_V1` is presented to an `Unpacker` configured for `DOMAIN_PACKER_V1`
|
||||
- **THEN** the call throws a `CryptoError` whose code identifies a domain mismatch (no plaintext is returned)
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/domain-tags/domain-tags.test.ts::"ALL_DOMAIN_TAGS contains 10 tags in v1"` AND `packages/crypto/crypto/src/domain-tags/domain-tags.test.ts::"each tag is a unique string"` AND `packages/crypto/crypto/src/domain-tags/domain-tags.test.ts::"produces ASCII bytes followed by 0x00 terminator"` AND `packages/crypto/crypto/src/domain-tags/domain-tags.test.ts::"produces different bytes for different domains over the same payload"` AND `packages/crypto/crypto/src/packer/packer.test.ts::"cross-protocol domain tag rejected"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Public bundles are parent-signed and carry an issuer reference
|
||||
|
||||
`@suaveplan/crypto` SHALL provide `packPublicBundle(keychain, parentAuthority, options)` that emits a bit-packed binary bundle in the wire format below, with a trailing 64-byte ed25519 signature produced by `parentAuthority.sign(DOMAIN_PUBLIC_KEYCHAIN_V1, "sign", bundleBytes)`. The signature covers everything in the bundle including the embedded `issuerRef` — swapping the issuer reference invalidates the signature.
|
||||
|
||||
`unpackPublicBundle(bytes, parentSignPublicKey)` verifies the trailing signature against the supplied parent public sign key, returning the parsed bundle and the verified `issuerRef`. A `parentSignPublicKey` of `null` selects self-verify mode, valid only for root identities (the bundle's own embedded `sign` slot is used).
|
||||
|
||||
The wire format identifier is `PUBLIC_BUNDLE_MAGIC` (4 ASCII bytes), `PUBLIC_BUNDLE_FORMAT_VERSION` is `1` in v1, and the header byte size is committed as `PUBLIC_BUNDLE_HEADER_BYTE_SIZE`. The slot record layout is committed as `KEY_SLOT_PUBLIC_BYTE_SIZE` and `KEY_SLOT_PUBLIC_BYTES = 17 + 48 = 65` bytes.
|
||||
|
||||
For a root bundle the issuer `(masterVersion, userId, depth, slotVersion)` equals the subject's, and the parent authority is the keychain itself (self-signing). Tampered bundle bytes (slot data, signature, magic, version, slotCount, length) MUST cause parse / verify to fail.
|
||||
|
||||
#### Scenario: self-signed bundle round-trips and self-verifies
|
||||
|
||||
- **WHEN** `packPublicBundle(rootKeychain, rootAuthority)` is called and the bundle is then verified in self-verify mode
|
||||
- **THEN** the call succeeds and the parsed bundle's slots match the input keychain
|
||||
|
||||
#### Scenario: parent-signed bundle verifies against parent's sign pubkey
|
||||
|
||||
- **WHEN** `packPublicBundle(serverKeychain, rootAuthority)` is called and the result is verified against the root's public sign key
|
||||
- **THEN** the call succeeds; verification against any non-root public key fails
|
||||
|
||||
#### Scenario: tampered slot bytes fail verification
|
||||
|
||||
- **WHEN** any byte of a packed bundle's slot section is mutated
|
||||
- **THEN** verification fails
|
||||
|
||||
#### Scenario: tampered signature fails verification
|
||||
|
||||
- **WHEN** any byte of the trailing 64-byte signature is mutated
|
||||
- **THEN** verification fails
|
||||
|
||||
#### Scenario: parse rejects malformed payloads
|
||||
|
||||
- **WHEN** the bundle has bad magic, wrong format version, bad slotCount, a too-short payload, or extra trailing bytes
|
||||
- **THEN** `unpackPublicBundle` throws a parse error
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"self-signed bundle round-trips and self-verifies"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"parent-signed (third-party) bundle verifies against parent's sign pubkey"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"tampered slot bytes fail verification"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"tampered signature fails verification"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"bad magic fails parse"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"wrong format version fails parse"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"bad slotCount fails parse"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"short payload fails parse"` AND `packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts::"extra bytes fails parse"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Chain bundle traversal — concatenated parent-signed links
|
||||
|
||||
`@suaveplan/crypto` SHALL provide a `ChainBundle` wire format and a `verifyChain(bundle, trustAnchor, clock, isRevoked?)` walker. A `ChainBundle` is a header followed by a concatenation of `PublicBundle` records ordered leaf-first. The wire format identifier is `CHAIN_BUNDLE_MAGIC`, the format version is `CHAIN_BUNDLE_FORMAT_VERSION` (currently `1`), the header byte size is `CHAIN_BUNDLE_HEADER_BYTE_SIZE`, and `linkCount` is bounded by `MAX_CHAIN_LINKS` (16).
|
||||
|
||||
The walker MUST: verify each link's signature against the next link's `sign` slot (or against `trustAnchor` for the final link), reject expired or not-yet-valid slots via the configured `Clock`, reject revoked links via the optional `isRevoked` predicate, reject `linkCount === 0`, reject `linkCount > MAX_CHAIN_LINKS`, reject mismatched `issuerRef` between adjacent links, reject bad magic / version / length / linkCount overflows at parse time. The bundle wire format MUST be byte-identical to the v1 snapshot.
|
||||
|
||||
#### Scenario: 3-link chain verifies end-to-end
|
||||
|
||||
- **WHEN** a chain bundle is built as `[subService, server, root]` (each parent-signed by the next)
|
||||
- **THEN** `verifyChain` succeeds; the parsed chain has length 3
|
||||
|
||||
#### Scenario: tampered link fails verification at that link
|
||||
|
||||
- **WHEN** any byte of a non-leaf link is mutated
|
||||
- **THEN** `verifyChain` rejects
|
||||
|
||||
#### Scenario: revoked link fails via predicate
|
||||
|
||||
- **WHEN** the `isRevoked` predicate returns true for an intermediate link
|
||||
- **THEN** `verifyChain` rejects
|
||||
|
||||
#### Scenario: expired sign slot fails
|
||||
|
||||
- **WHEN** any link's `sign` slot has `notAfter < clock.now()`
|
||||
- **THEN** `verifyChain` rejects with `KEYCHAIN.EXPIRED`
|
||||
|
||||
#### Scenario: mismatched issuer coord fails
|
||||
|
||||
- **WHEN** an intermediate link's `issuerRef` does not equal the next link's signing-slot coordinate
|
||||
- **THEN** `verifyChain` rejects
|
||||
|
||||
#### Scenario: link count bounds enforced
|
||||
|
||||
- **WHEN** packing requests `0` links or more than `MAX_CHAIN_LINKS`
|
||||
- **THEN** packing throws
|
||||
|
||||
#### Scenario: parse rejects malformed payloads
|
||||
|
||||
- **WHEN** the bundle has bad magic, bad version, out-of-range linkCount, length mismatch, or is too short
|
||||
- **THEN** `parseChainBundle` throws
|
||||
|
||||
#### Scenario: wire format is byte-identical to v1 snapshot
|
||||
|
||||
- **WHEN** a fixed-input chain is packed and compared against the committed v0x0001 snapshot
|
||||
- **THEN** the bytes match exactly
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"chain-bundle wire format is byte-identical to v0x0001 snapshot"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"packs and parses a 3-link chain"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"verifies a 3-link chain"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"verifyChain rejects tampered link"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"verifyChain rejects revoked link via predicate"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"verifyChain rejects expired sign slot"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"verifyChain rejects mismatched issuer coord"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"packChainBundle rejects 0-link"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"packChainBundle rejects > MAX_CHAIN_LINKS"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"parseChainBundle rejects bad magic"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"parseChainBundle rejects bad version"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"parseChainBundle rejects out-of-range linkCount"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"parseChainBundle rejects length mismatch"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"parseChainBundle rejects too-short payload"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Wire-format schemas exposed and committed
|
||||
|
||||
`@suaveplan/crypto` SHALL expose a `wire-format` barrel (`@suaveplan/crypto/wire-format`) that re-exports every committed wire-format identifier and byte-size constant from its owning module:
|
||||
|
||||
- `PUBLIC_BUNDLE_MAGIC`, `PUBLIC_BUNDLE_FORMAT_VERSION`, `PUBLIC_BUNDLE_HEADER_BYTE_SIZE` (from `bundles/public-bundle/`)
|
||||
- `CHAIN_BUNDLE_MAGIC`, `CHAIN_BUNDLE_FORMAT_VERSION`, `CHAIN_BUNDLE_HEADER_BYTE_SIZE`, `MAX_CHAIN_LINKS` (from `bundles/chain-bundle/`)
|
||||
- `V1_COORDINATE_BYTE_SIZE`, `COORDINATE_HEADER_BYTE_SIZE` (from `derivation/coordinate/`)
|
||||
- `KEY_SLOT_META_PRIVATE_SCHEMA`, `KEY_SLOT_META_PUBLIC_SCHEMA`, `KEY_SLOT_PRIVATE_BYTE_SIZE`, `KEY_SLOT_PUBLIC_BYTE_SIZE` (from `keychain/key-slot/`)
|
||||
|
||||
Each schema's byte-size is committed as a constant: `KEY_SLOT_PRIVATE_BYTE_SIZE === 17 + 80 === 97` and `KEY_SLOT_PUBLIC_BYTE_SIZE === 17 + 48 === 65`. Any field-width change MUST update both the constant and its consumer test, providing a loud signal for wire-format regression.
|
||||
|
||||
#### Scenario: barrel re-exports every committed identifier
|
||||
|
||||
- **WHEN** a consumer imports from `@suaveplan/crypto/wire-format`
|
||||
- **THEN** `PUBLIC_BUNDLE_MAGIC`, `CHAIN_BUNDLE_MAGIC`, `PUBLIC_BUNDLE_FORMAT_VERSION`, `CHAIN_BUNDLE_FORMAT_VERSION`, `KEY_SLOT_PRIVATE_BYTE_SIZE`, `KEY_SLOT_PUBLIC_BYTE_SIZE`, `V1_COORDINATE_BYTE_SIZE`, `MAX_CHAIN_LINKS` are all importable
|
||||
|
||||
#### Scenario: key-slot byte sizes are exactly the committed constants
|
||||
|
||||
- **WHEN** the key-slot byte-size test runs
|
||||
- **THEN** the private slot is 97 bytes and the public slot is 65 bytes
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/keychain/key-slot/key-slot.test.ts::"private slot is 17 + 80 = 97 bytes"` AND `packages/crypto/crypto/src/keychain/key-slot/key-slot.test.ts::"public slot is 17 + 48 = 65 bytes"` AND `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts::"chain-bundle wire format is byte-identical to v0x0001 snapshot"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Authority — signing abstraction over hierarchical identity
|
||||
|
||||
`@suaveplan/crypto` SHALL define an `Authority` interface that signs payloads with a named slot under a domain tag, exposing `sign(domain, slotPurpose, payload, signal?): Promise<Uint8Array>` and `dispose(): void`. The interface is the only signing surface exposed to callers outside the package; raw `secretKey: Uint8Array` references are not passed across package boundaries.
|
||||
|
||||
V1 ships an `InMemoryAuthority` backend that holds an unlocked `Keychain` and signs from its slots. The interface is shaped so future backends (`YubiKeyAuthority`, `TpmAuthority`, `ThresholdAuthority`) can be substituted without changes to callers.
|
||||
|
||||
`Authority` MUST: produce signatures that verify under the corresponding public sign slot, fail under a different domain tag, throw `KEYCHAIN.UNKNOWN_PURPOSE` for unknown slots, throw `KEYCHAIN.SLOT_INVALID` when signing with a non-sign slot, throw `KEYCHAIN.EXPIRED` when the slot's `notAfter` is past, throw `AUTHORITY.REVOKED` when an `isRevoked` predicate matches, throw `AUTHORITY.DISPOSED` after `dispose()`, throw `AUTHORITY.ABORTED` when invoked with an already-aborted signal. `dispose()` MUST zeroise held secret material and MUST be idempotent.
|
||||
|
||||
#### Scenario: sign and verify under matching slot and domain
|
||||
|
||||
- **WHEN** `authority.sign(domain, "sign", payload)` is called
|
||||
- **THEN** the returned signature verifies against the public sign slot's key under the same domain
|
||||
|
||||
#### Scenario: signature does not verify under a different domain tag
|
||||
|
||||
- **WHEN** the signature is verified under a different domain tag
|
||||
- **THEN** verification returns false
|
||||
|
||||
#### Scenario: unknown slot purpose rejected
|
||||
|
||||
- **WHEN** `authority.sign(domain, "bogus", payload)` is called
|
||||
- **THEN** the call throws `KEYCHAIN.UNKNOWN_PURPOSE`
|
||||
|
||||
#### Scenario: signing with a non-signing slot rejected
|
||||
|
||||
- **WHEN** `authority.sign(domain, "encr", payload)` is called
|
||||
- **THEN** the call throws `KEYCHAIN.SLOT_INVALID`
|
||||
|
||||
#### Scenario: dispose zeroises and locks
|
||||
|
||||
- **WHEN** `authority.dispose()` is called and `authority.sign(...)` is then invoked
|
||||
- **THEN** post-dispose secret-key buffers contain zeros and the call throws `AUTHORITY.DISPOSED`; calling `dispose()` again is a no-op
|
||||
|
||||
#### Scenario: aborted signal cancels signing
|
||||
|
||||
- **WHEN** `authority.sign(..., signal)` is called with an already-aborted signal
|
||||
- **THEN** the call throws `AUTHORITY.ABORTED`
|
||||
|
||||
#### Scenario: revoked slot fails before signing
|
||||
|
||||
- **WHEN** an `isRevoked` predicate returns true for the slot and `authority.sign(...)` is called
|
||||
- **THEN** the call throws `AUTHORITY.REVOKED` before any signing primitive executes
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/authority/authority.test.ts::"signs with the sign slot and verifies"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"signature does NOT verify under a different domain tag"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"throws KEYCHAIN.UNKNOWN_PURPOSE for an unknown slot"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"throws KEYCHAIN.SLOT_INVALID when signing with a non-sign slot"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"throws AUTHORITY.DISPOSED after dispose"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"dispose zeroises secret-key buffers"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"dispose is idempotent"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"throws AUTHORITY.ABORTED when signal already aborted"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"throws KEYCHAIN.EXPIRED when slot's notAfter is past"` AND `packages/crypto/crypto/src/authority/authority.test.ts::"throws AUTHORITY.REVOKED when isRevoked predicate matches"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Hierarchical identity — Root and Server
|
||||
|
||||
`@suaveplan/crypto` SHALL provide `createRoot(options)`, `createServer(rootAuthority, options)`, `rollServer(rootAuthority, server)`, and `revokeServer(rootAuthority, server, reason)`. A `RootIdentity` is a Keychain whose `sign` slot is the trust anchor for everything beneath it. A `ServerIdentity` is a Keychain whose public bundle has been signed by the root's sign slot under `DOMAIN_PUBLIC_KEYCHAIN_V1`.
|
||||
|
||||
`rollServer` MUST produce a new `ServerIdentity` whose version is one greater than the prior, emit a record of the prior version (used by `RevocationList`), and accept missing optional `rng`. `revokeServer` MUST return a revocation entry without producing a new identity. `createRoot` and `createServer` MUST honour optional `notBefore`, `notAfter`, and `masterKey`. `createRoot` and `createServer` MUST accept missing optional `rng`. Nested servers (depth ≥ 2) MUST be traversable via the chain-bundle walker.
|
||||
|
||||
#### Scenario: createRoot produces a self-verifying identity
|
||||
|
||||
- **WHEN** `createRoot({...})` is called
|
||||
- **THEN** the result's public bundle verifies in self-verify mode
|
||||
|
||||
#### Scenario: createServer is signed under root
|
||||
|
||||
- **WHEN** `createServer(rootAuthority, ...)` is called
|
||||
- **THEN** the server's public bundle verifies against the root's public sign key
|
||||
|
||||
#### Scenario: rollServer increments version and emits prior
|
||||
|
||||
- **WHEN** `rollServer(rootAuthority, server@N)` is called
|
||||
- **THEN** the result is `server@(N+1)` and a `priorVersion === N` record is emitted
|
||||
|
||||
#### Scenario: revokeServer returns an entry without re-issuing
|
||||
|
||||
- **WHEN** `revokeServer(rootAuthority, server, reason)` is called
|
||||
- **THEN** the call returns a revocation entry and no new server identity
|
||||
|
||||
#### Scenario: optional notBefore, notAfter, masterKey honoured
|
||||
|
||||
- **WHEN** `createRoot` or `createServer` is called with explicit `notBefore` / `notAfter` / `masterKey`
|
||||
- **THEN** the resulting identity's slots reflect those inputs
|
||||
|
||||
#### Scenario: optional rng accepted
|
||||
|
||||
- **WHEN** `createRoot`, `createServer`, or `rollServer` is called without a custom `rng`
|
||||
- **THEN** the call succeeds
|
||||
|
||||
#### Scenario: nested server depth-2 builds a 3-link chain
|
||||
|
||||
- **WHEN** a sub-service is issued under a server that was issued under a root
|
||||
- **THEN** a 3-link chain bundle is constructible and verifies against the root anchor
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/identity/identity.test.ts::"createRoot produces a self-verifying root identity"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"createServer is signed under root"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"rollServer increments version + emits priorVersion"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"revokeServer returns an entry without re-issuing"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"createRoot honours optional notBefore/notAfter and masterKey"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"createServer honours optional notBefore/notAfter"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"rollServer accepts no rng option"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"createRoot/createServer accept no rng option"` AND `packages/crypto/crypto/src/identity/identity.test.ts::"nested server (depth 2) builds a 3-link chain"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: RevocationList — root-signed CRL
|
||||
|
||||
`@suaveplan/crypto` SHALL provide a `RevocationList` type representing an append-only list of revocation entries, each entry signed by the root's sign slot under `DOMAIN_CRL_V1`. Entries are immutable: any past entry's bytes are part of the signed payload; mutation invalidates the list signature.
|
||||
|
||||
The list exposes `append(entry, rootAuthority)`, `verify(rootPublicKey)`, and `check(ref): boolean`. `check` MUST report true for revoked refs and false otherwise.
|
||||
|
||||
#### Scenario: append then verify succeeds
|
||||
|
||||
- **WHEN** an entry is appended with `rootAuthority` and `verify(rootPublicKey)` is called
|
||||
- **THEN** verification returns true
|
||||
|
||||
#### Scenario: mutating a past entry invalidates the list
|
||||
|
||||
- **WHEN** any byte of any past entry is mutated and `verify(rootPublicKey)` is called
|
||||
- **THEN** verification returns false
|
||||
|
||||
#### Scenario: check reports per-entry correctly
|
||||
|
||||
- **WHEN** a server identity at a given version is appended and `check` is queried for that ref vs a different version
|
||||
- **THEN** `check` returns true for the appended ref and false for the other
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/revocation/revocation-list.test.ts::"append then verify succeeds"` AND `packages/crypto/crypto/src/revocation/revocation-list.test.ts::"mutating a past entry invalidates the list"` AND `packages/crypto/crypto/src/revocation/revocation-list.test.ts::"check returns true for revoked refs and false otherwise"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: AuditLog — append-only Merkle log
|
||||
|
||||
`@suaveplan/crypto` SHALL provide an `AuditLog` type recording every issue / roll / revoke event, structured as an append-only Merkle tree. The current Merkle root is signed by the root's sign slot under `DOMAIN_AUDIT_V1`. Any modification to a past entry changes the Merkle root and invalidates the signature.
|
||||
|
||||
The log exposes `append(event, rootAuthority)`, `signRoot(rootAuthority)`, `verify(rootPublicKey)`, `proveInclusion(index)`, and `verifyInclusion(index, proof, expectedRoot)`. The Merkle construction MUST handle odd leaf counts by duplicating the last leaf at each level. `signRoot` over an empty log MUST produce a documented zero root. `eventCount` MUST track appends.
|
||||
|
||||
#### Scenario: append then verify succeeds
|
||||
|
||||
- **WHEN** an event is appended and the root signature is verified against the root public key
|
||||
- **THEN** verification returns true
|
||||
|
||||
#### Scenario: tampering with a past entry invalidates the root
|
||||
|
||||
- **WHEN** any byte of any past event is mutated
|
||||
- **THEN** signature verification returns false
|
||||
|
||||
#### Scenario: inclusion proof verifies
|
||||
|
||||
- **WHEN** an event is appended and `proveInclusion` is requested for it
|
||||
- **THEN** the proof verifies under the signed root
|
||||
|
||||
#### Scenario: inclusion proof for out-of-range index throws
|
||||
|
||||
- **WHEN** `proveInclusion(index)` is called with an out-of-range index
|
||||
- **THEN** the call throws
|
||||
|
||||
#### Scenario: verifyInclusion rejects wrong / mis-sized expected roots
|
||||
|
||||
- **WHEN** `verifyInclusion(index, proof, expectedRoot)` is called with an expected root that is wrong or of mismatched length
|
||||
- **THEN** the call returns false
|
||||
|
||||
#### Scenario: odd leaf count handled
|
||||
|
||||
- **WHEN** the log has an odd number of leaves and the last leaf is duplicated for Merkle construction
|
||||
- **THEN** inclusion proofs still verify
|
||||
|
||||
#### Scenario: empty log signRoot produces zero root
|
||||
|
||||
- **WHEN** `signRoot` is called on an empty log
|
||||
- **THEN** the produced root is the documented zero value
|
||||
|
||||
#### Scenario: verify fails with a wrong sign slot
|
||||
|
||||
- **WHEN** the log is verified against an unrelated public sign key
|
||||
- **THEN** verification returns false
|
||||
|
||||
#### Scenario: eventCount tracks appends
|
||||
|
||||
- **WHEN** `n` events are appended
|
||||
- **THEN** `eventCount === n`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"append then root signature verifies"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"tampering with a past entry invalidates the root"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"inclusion proof verifies for appended entries"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"inclusion proof for out-of-range index throws"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"verifyInclusion returns false for a wrong expected root"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"verifyInclusion returns false for length-mismatched expected root"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"inclusion proof handles odd leaf count (last leaf duplicated)"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"signRoot on empty log produces a zero root"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"verify fails with a wrong sign slot"` AND `packages/crypto/crypto/src/audit-log/audit-log.test.ts::"eventCount tracks appends"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Packer — encrypt-and-sign envelope
|
||||
|
||||
`@suaveplan/crypto` SHALL provide a `Packer` / `Unpacker` pair implementing a schema-driven encrypt-and-sign envelope. The envelope MUST: round-trip a value byte-for-byte under matching parties / nonce / domain, reject envelopes packed under a different domain (cross-protocol replay defence), reject envelopes whose `issuedAt` is older than a configurable replay window, reject envelopes whose `nonce` has been seen within a configurable nonce-cache window, validate pack-side nonce length, reject envelopes whose stated ciphertext length overruns the buffer, reject too-short envelopes.
|
||||
|
||||
#### Scenario: round-trip preserves the value
|
||||
|
||||
- **WHEN** `packer.pack(payload, ...)` is called and the result is `unpacker.unpack(envelope, ...)`-ed
|
||||
- **THEN** the returned payload byte-equals the original
|
||||
|
||||
#### Scenario: replay outside window rejected
|
||||
|
||||
- **WHEN** an envelope older than the replay window is presented
|
||||
- **THEN** `unpacker.unpack` throws
|
||||
|
||||
#### Scenario: nonce dedup rejects replay
|
||||
|
||||
- **WHEN** the same envelope is presented twice in succession
|
||||
- **THEN** the first call succeeds; the second throws
|
||||
|
||||
#### Scenario: cross-protocol domain tag rejected
|
||||
|
||||
- **WHEN** an envelope packed under one domain is presented to an `Unpacker` configured for another
|
||||
- **THEN** `unpacker.unpack` throws
|
||||
|
||||
#### Scenario: invalid pack-side nonce length rejected
|
||||
|
||||
- **WHEN** `packer.pack` is called with a nonce of the wrong length
|
||||
- **THEN** the call throws
|
||||
|
||||
#### Scenario: malformed envelope rejected
|
||||
|
||||
- **WHEN** an envelope's stated ciphertext length overruns the buffer, OR the envelope is too short
|
||||
- **THEN** parsing throws
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/packer/packer.test.ts::"round-trip preserves the value"` AND `packages/crypto/crypto/src/packer/packer.test.ts::"replay outside window rejected"` AND `packages/crypto/crypto/src/packer/packer.test.ts::"nonce dedup rejects replay"` AND `packages/crypto/crypto/src/packer/packer.test.ts::"cross-protocol domain tag rejected"` AND `packages/crypto/crypto/src/packer/packer.test.ts::"rejects invalid pack-side nonce length"` AND `packages/crypto/crypto/src/packer/packer.test.ts::"rejects envelope where stated ciphertext length overruns buffer"` AND `packages/crypto/crypto/src/packer/packer.test.ts::"rejects too-short envelope"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: ChunkedPacker — per-chunk-signed P2P fragmentation
|
||||
|
||||
`@suaveplan/crypto` SHALL provide `ChunkedPacker` / `ChunkedUnpacker` implementing per-chunk signed fragmentation under `DOMAIN_CHUNK_V1`. Reassembly MUST: byte-equal the original payload on round-trip, reject tampered chunks at reassembly, reject missing chunks, reassemble correctly when chunks arrive out of order, reject malformed chunks (too short, wrong `dataLen`, mismatched total), reject empty chunk lists, reject invalid chunk sizes.
|
||||
|
||||
#### Scenario: round-trip reassembles byte-identical
|
||||
|
||||
- **WHEN** a payload is fragmented into N chunks and reassembled
|
||||
- **THEN** the reassembled bytes byte-equal the original
|
||||
|
||||
#### Scenario: tampered chunk rejected at reassembly
|
||||
|
||||
- **WHEN** any byte of a chunk is mutated
|
||||
- **THEN** reassembly throws
|
||||
|
||||
#### Scenario: missing chunk rejected
|
||||
|
||||
- **WHEN** any chunk is omitted
|
||||
- **THEN** reassembly throws
|
||||
|
||||
#### Scenario: out-of-order chunks reassemble
|
||||
|
||||
- **WHEN** chunks are presented in non-sequential order
|
||||
- **THEN** reassembly succeeds and byte-equals the original
|
||||
|
||||
#### Scenario: malformed chunks rejected
|
||||
|
||||
- **WHEN** a chunk is too short, has the wrong `dataLen` field, or has a mismatched total
|
||||
- **THEN** reassembly throws
|
||||
|
||||
#### Scenario: empty list and invalid sizes rejected
|
||||
|
||||
- **WHEN** an empty chunk list is presented, or chunking is requested with an invalid size
|
||||
- **THEN** the call throws
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"round-trip reassembles byte-identical"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"tampered chunk rejected at reassembly"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"missing chunk rejected"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"out-of-order chunks reassemble correctly"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"rejects malformed chunk (too short)"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"rejects chunk with wrong dataLen field"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"rejects chunks with mismatched total"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"rejects empty chunks list"` AND `packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts::"rejects invalid chunk size"`
|
||||
@@ -0,0 +1,53 @@
|
||||
## 1. Pre-flight validation
|
||||
|
||||
- [ ] 1.1 Confirm `packages/crypto/crypto-keys/` does not exist on disk; confirm `grep -rln "@suaveplan/crypto-keys" packages/` returns zero matches (excluding `openspec/archive/`)
|
||||
- [ ] 1.2 Confirm `packages/crypto/crypto/src/derivation/coordinate/coordinate.ts` exports `DerivationCoordinate` carrying `masterVersion` and `slotVersion`
|
||||
- [ ] 1.3 Confirm `packages/crypto/crypto/src/derivation/layouts/layouts.ts` exports `DERIVATION_LAYOUT_V1` packing `masterVersion u16 ‖ userId u32 ‖ depth u8 ‖ slotVersion u8`
|
||||
- [ ] 1.4 Confirm `packages/crypto/crypto/src/wire-format/index.ts` re-exports `PUBLIC_BUNDLE_MAGIC`, `CHAIN_BUNDLE_MAGIC`, `KEY_SLOT_PRIVATE_BYTE_SIZE`, `KEY_SLOT_PUBLIC_BYTE_SIZE`, `V1_COORDINATE_BYTE_SIZE`, `*_FORMAT_VERSION`
|
||||
- [ ] 1.5 Run `bunx turbo test --filter=@suaveplan/crypto` and confirm green at HEAD
|
||||
|
||||
## 2. Verified-by pointer audit
|
||||
|
||||
- [ ] 2.1 For each `Verified by:` pointer in `openspec/changes/crypto-spec-restore-versioning/specs/crypto/spec.md`, parse out the `<file-path>::"<test-name>"` pair
|
||||
- [ ] 2.2 For each pair, run `grep -F "<test-name>" <file-path>` and assert the test name string appears literally inside an `it(` or `test(` call site
|
||||
- [ ] 2.3 Hard-fail this change if any pointer does not resolve. Adjust the spec text (rename scenario or pointer) and re-run until clean
|
||||
- [ ] 2.4 Run `bunx vitest run packages/crypto/crypto/src/keychain/keychain.test.ts packages/crypto/crypto/src/keychain/validity/validity.test.ts packages/crypto/crypto/src/keychain/key-slot/key-slot.test.ts packages/crypto/crypto/src/derivation/layouts/layouts.test.ts packages/crypto/crypto/src/derivation/coordinate/coordinate.test.ts packages/crypto/crypto/src/domain-tags/domain-tags.test.ts packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts packages/crypto/crypto/src/authority/authority.test.ts packages/crypto/crypto/src/identity/identity.test.ts packages/crypto/crypto/src/revocation/revocation-list.test.ts packages/crypto/crypto/src/audit-log/audit-log.test.ts packages/crypto/crypto/src/packer/packer.test.ts packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts --reporter=verbose` and confirm every test name cited in the spec passes (not skipped, not todo)
|
||||
|
||||
## 3. Symbol presence audit
|
||||
|
||||
- [ ] 3.1 Run `grep -RnE "DERIVATION_LAYOUT_V1|DERIVATION_LAYOUT_V1_ID" packages/crypto/crypto/src/` and confirm at least one definition site
|
||||
- [ ] 3.2 Run `grep -RnE "PUBLIC_BUNDLE_MAGIC|CHAIN_BUNDLE_MAGIC|KEY_SLOT_PRIVATE_BYTE_SIZE|KEY_SLOT_PUBLIC_BYTE_SIZE|V1_COORDINATE_BYTE_SIZE|MAX_CHAIN_LINKS" packages/crypto/crypto/src/` and confirm definitions plus the wire-format barrel re-export
|
||||
- [ ] 3.3 Run `grep -RnE "DOMAIN_VAULT_V1|DOMAIN_PUBLIC_KEYCHAIN_V1|DOMAIN_PACKER_V1|DOMAIN_CHUNK_V1|DOMAIN_CRL_V1|DOMAIN_AUDIT_V1|DOMAIN_SLSA_BUILDER_V1|DOMAIN_BITPACKER_SIGNED_V1|DOMAIN_BITPACKER_HASHCHAIN_V1|DOMAIN_BITPACKER_MULTISIGN_V1" packages/crypto/crypto/src/domain-tags/` and confirm exactly the 10 v1 tags exist
|
||||
- [ ] 3.4 Run `grep -RnE "KEYCHAIN.UNKNOWN_LAYOUT|KEYCHAIN.LAYOUT_TOO_WIDE|KEYCHAIN.LAYOUT_ALREADY_REGISTERED|KEYCHAIN.NOT_YET_VALID|KEYCHAIN.EXPIRED|KEYCHAIN.UNKNOWN_PURPOSE|KEYCHAIN.SLOT_INVALID|AUTHORITY.DISPOSED|AUTHORITY.ABORTED|AUTHORITY.REVOKED" packages/crypto/crypto/src/errors/` and confirm every error code cited in the spec is defined
|
||||
|
||||
## 4. External-reference audit
|
||||
|
||||
- [ ] 4.1 Run `grep -rln "@suaveplan/crypto-keys" packages/ scripts/ docs/ apps/` and confirm zero matches outside `openspec/archive/`
|
||||
- [ ] 4.2 Run `grep -rln "openspec/specs/crypto-keys" .` and confirm zero matches outside `openspec/changes/crypto-spec-restore-versioning/` and `openspec/archive/`
|
||||
- [ ] 4.3 If any external reference is found, block the change and update the consumer to reference `openspec/specs/crypto/` (the surface was folded into `@suaveplan/crypto`)
|
||||
|
||||
## 5. OpenSpec validation
|
||||
|
||||
- [ ] 5.1 Run `bun openspec validate crypto-spec-restore-versioning --strict` and confirm zero errors
|
||||
- [ ] 5.2 Run `bun openspec list` and confirm `crypto-spec-restore-versioning` appears with `tasks` status reflecting current progress
|
||||
- [ ] 5.3 Run `bun openspec diff crypto-spec-restore-versioning` and confirm it emits a sensible delta listing 13 added requirements on `crypto` and 5 removed requirements on `crypto-keys`
|
||||
|
||||
## 6. Apply the change
|
||||
|
||||
- [ ] 6.1 Run `bun openspec apply crypto-spec-restore-versioning` (or follow the equivalent manual fold per `openspec/AGENTS.md`): copy the 13 ADDED requirements from `openspec/changes/crypto-spec-restore-versioning/specs/crypto/spec.md` into `openspec/specs/crypto/spec.md` directly after the existing `### Requirement: deriveKeyFromPassword` block; remove the entire `openspec/specs/crypto-keys/` directory
|
||||
- [ ] 6.2 Confirm `openspec/specs/crypto-keys/` no longer exists on disk
|
||||
- [ ] 6.3 Confirm `openspec/specs/crypto/spec.md` now contains the 13 new requirement headings exactly as authored
|
||||
|
||||
## 7. Post-apply validation
|
||||
|
||||
- [ ] 7.1 Run `bun openspec validate --strict` against the entire spec corpus and confirm zero errors
|
||||
- [ ] 7.2 Run `bunx turbo lint typecheck test --filter=@suaveplan/crypto` and confirm green (this is a spec-only change but the package gate must remain green)
|
||||
- [ ] 7.3 Run `bunx turbo test:coverage --filter=@suaveplan/crypto` and confirm 100% across statements / branches / functions / lines (no regression)
|
||||
- [ ] 7.4 Run `bun scripts/conformance/check-crypto-core-allowlist.ts` and confirm `0 violations`
|
||||
|
||||
## 8. Archive
|
||||
|
||||
- [ ] 8.1 Move `openspec/changes/crypto-spec-restore-versioning/` to `openspec/archive/<yyyy-mm-dd>-crypto-spec-restore-versioning/` per `openspec/AGENTS.md`
|
||||
- [ ] 8.2 Confirm the archive contains `proposal.md`, `design.md`, `tasks.md` (with all checkboxes ticked), and `specs/crypto/spec.md` + `specs/crypto-keys/spec.md`
|
||||
- [ ] 8.3 Update any tracker (`STATUS.md`, in-flight changes list) to reflect the archive
|
||||
- [ ] 8.4 Commit the change in a single commit titled `crypto-spec-restore-versioning: fold versioned-key vocabulary into live crypto spec`
|
||||
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
`StreamingAeadEngine` and the five interfaces it depends on (`StreamingChunkInput`, `StreamingChunkTag`, `StreamingHeader`, `EncryptStreamAeadOptions`, `DecryptStreamAeadOptions`) currently live in `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.types.ts`. They are **cross-package contract types**: defined and instantiated by `@suaveplan/crypto-cipher` (the AES-GCM and XChaCha20 engines), and consumed by `@suaveplan/crypto`'s streaming façade and Web-Streams adapters. Per `CLAUDE.md` §0 rule 5 — "if the new type or abstraction is shared across ≥2 packages, it belongs in `@suaveplan/types`" — they are in the wrong place.
|
||||
|
||||
The genesis monorepo already locates the parallel cross-package crypto contract correctly: `Authority`, `AuthorityVerifier`, `KeySlotPublic` / `KeySlotPrivate`, `SlotId`, `DomainTag`, and `AeadOps` all live in `@suaveplan/types`. The streaming-AEAD interfaces are an oversight from the original `crypto-completion` change, where the types were authored alongside their first implementing engines and never lifted. Moving them now closes the gap before downstream consumers (network plugins, drive transport layers) start depending on them through `crypto-cipher` directly.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **MODIFIED `types` capability**: add 6 cross-package contract interfaces under a new module `streaming-aead-engine.ts` — `StreamingAeadEngine`, `StreamingChunkInput`, `StreamingChunkTag`, `StreamingHeader`, `EncryptStreamAeadOptions`, `DecryptStreamAeadOptions`. Re-exported from `@suaveplan/types` root barrel.
|
||||
- **MODIFIED `crypto-cipher` capability**: `streaming-aead.types.ts` keeps its public exports (consumers' `import { StreamingAeadEngine } from "@suaveplan/crypto-cipher"` still works) but routes the 6 interfaces through `@suaveplan/types` re-exports rather than redefining them. The 4 runtime constants (`STREAMING_AEAD_MAGIC`, `STREAMING_AEAD_VERSION`, `STREAMING_AEAD_MAX_COUNTER`) and the `streamingAeadHeaderLength()` function stay in `crypto-cipher` — they are runtime values, not types, so the types-only `@suaveplan/types` package is the wrong home for them.
|
||||
- **Spec-only impact on `crypto`**: existing imports of `type StreamingAeadEngine` etc. from `@suaveplan/crypto-cipher` continue to work via the re-export. New code SHOULD import directly from `@suaveplan/types` for consumer-clarity, but this change does not rewrite existing import sites.
|
||||
- This change ships **source + tests + docs**, not just spec. The new `streaming-aead-engine.md` documents the interfaces and the cross-package consumption pattern.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(none)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `types`: add 6 new interfaces (`StreamingAeadEngine`, `StreamingChunkInput`, `StreamingChunkTag`, `StreamingHeader`, `EncryptStreamAeadOptions`, `DecryptStreamAeadOptions`).
|
||||
- `crypto-cipher`: 1 modified requirement (the existing `StreamingAeadEngine contract` requirement now points at `@suaveplan/types` as the canonical home; crypto-cipher re-exports for backwards compat).
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: `openspec/specs/types/spec.md` (6 requirements added), `openspec/specs/crypto-cipher/spec.md` (1 requirement modified to note the re-export).
|
||||
- **Affected code**:
|
||||
- `packages/core/types/src/streaming-aead-engine.ts` (new — types-only, ~70 lines).
|
||||
- `packages/core/types/src/streaming-aead-engine.md` (new — docs).
|
||||
- `packages/core/types/src/index.ts` (6 type exports added).
|
||||
- `packages/core/types/vite.config.ts` (no change — types is types-only, single index entry).
|
||||
- `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.types.ts` (re-exports the 6 interfaces from `@suaveplan/types`; keeps the 4 runtime constants and `streamingAeadHeaderLength`).
|
||||
- **Affected tests**: `@suaveplan/types` has a byte-size test that asserts the package emits zero runtime bytes — adding 6 type-only interfaces does not change that.
|
||||
- **Downstream**: zero breaking changes. Every existing `import { StreamingAeadEngine } from "@suaveplan/crypto-cipher"` keeps working. New consumers can drop the `crypto-cipher` dependency if they only need the types.
|
||||
- **Risk**: low. Types-only move with re-export shim. The TypeScript compiler verifies structural equivalence of the moved interfaces; no runtime behaviour changes.
|
||||
@@ -0,0 +1,28 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto-cipher (crypto-streaming-engine-to-types)
|
||||
|
||||
**Package**: `@suaveplan/crypto-cipher`
|
||||
**Status**: PROPOSED
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: StreamingAeadEngine contract
|
||||
|
||||
The package SHALL re-export the `StreamingAeadEngine` interface (and the four supporting interfaces — `StreamingChunkInput`, `StreamingChunkTag`, `StreamingHeader`, `EncryptStreamAeadOptions`, `DecryptStreamAeadOptions`) from `@suaveplan/types`. The canonical home of these types is `@suaveplan/types`; `crypto-cipher` re-exports them so existing consumers' `import { StreamingAeadEngine } from "@suaveplan/crypto-cipher"` continues to compile unchanged. Both built-in engines (AES-GCM, XChaCha20-Poly1305) SHALL satisfy the `@suaveplan/types::StreamingAeadEngine` interface and SHALL be substitutable for any caller-supplied engine.
|
||||
|
||||
The package SHALL retain its runtime-only exports — `STREAMING_AEAD_MAGIC` (4-byte magic), `STREAMING_AEAD_VERSION` (number), `STREAMING_AEAD_MAX_COUNTER` (number), `streamingAeadHeaderLength()` (function) — locally because `@suaveplan/types` is types-only and cannot host runtime values.
|
||||
|
||||
#### Scenario: caller-supplied engine round-trips identically
|
||||
|
||||
- **WHEN** a custom `StreamingAeadEngine` implementation is passed to `encryptStreamAead` and the same instance to `decryptStreamAead`
|
||||
- **THEN** the round-trip preserves bytes byte-for-byte (validated against an in-test spy engine that records every call)
|
||||
|
||||
#### Scenario: type re-export is structurally equivalent to canonical home
|
||||
|
||||
- **WHEN** a consumer imports `type StreamingAeadEngine` from `@suaveplan/crypto-cipher` and another imports it from `@suaveplan/types`
|
||||
- **THEN** the TypeScript compiler treats them as the identical type — no structural-equality cast is required
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.spec-conformance.test.ts::"StreamingAeadEngine contract is stable for custom engines"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,90 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: types (crypto-streaming-engine-to-types)
|
||||
|
||||
**Package**: `@suaveplan/types`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time. The verification harness for `@suaveplan/types` is its types-only build + the byte-size test in `tests/byte-size.test.ts`; new types must round-trip through the build without emitting runtime bytes.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: StreamingAeadEngine cross-package interface
|
||||
|
||||
`@suaveplan/types` SHALL export a `StreamingAeadEngine` interface defining the cross-package contract for pluggable streaming-AEAD engines. The interface SHALL declare the engine's stable identity (`id`, `wireId`), its key / nonce / tag dimensions (`keyLength`, `nonceLength`, `nonceBaseLength`, `tagLength`), a `deriveNonce(baseNonce, counter, finalFlag)` method, and async `seal(input)` / `open(input)` methods consuming `StreamingChunkInput` and returning `Uint8Array`.
|
||||
|
||||
The canonical implementations (`aesGcmStreamingEngine`, `xchacha20StreamingEngine`) live in `@suaveplan/crypto-cipher` and SHALL satisfy this interface. The high-level streaming façade in `@suaveplan/crypto` SHALL accept any `StreamingAeadEngine` instance — caller-supplied custom engines (HSM-backed, threshold, recording test spies) substitute cleanly for the built-ins.
|
||||
|
||||
#### Scenario: interface is types-only
|
||||
|
||||
- **WHEN** the `@suaveplan/types` package is built
|
||||
- **THEN** `streaming-aead-engine.ts` emits zero runtime bytes (the package's byte-size test still passes)
|
||||
|
||||
**Verified by:** `packages/core/types/tests/byte-size.test.ts::"types package emits zero runtime bytes"` AND `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.spec-conformance.test.ts::"StreamingAeadEngine contract is stable for custom engines"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: StreamingChunkInput cross-package interface
|
||||
|
||||
`@suaveplan/types` SHALL export a `StreamingChunkInput` interface bundling the inputs passed to `StreamingAeadEngine.seal` / `StreamingAeadEngine.open`: `key`, `baseNonce`, `counter` (32-bit), `finalFlag` (`0 | 1`), `data`, optional `aad`. The interface is the cross-package contract for a single chunk's encrypt / decrypt invocation.
|
||||
|
||||
#### Scenario: shape is byte-only
|
||||
|
||||
- **WHEN** a consumer calls `engine.seal({ key, baseNonce, counter, finalFlag, data })`
|
||||
- **THEN** the type system enforces every field is a `Uint8Array` or `number` literal — no runtime validation needed at the boundary
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead-aes-gcm/streaming-aead-aes-gcm.test.ts::"seal then open round-trips bytes for a single chunk"` AND `packages/crypto/crypto-cipher/src/streaming/streaming-aead-xchacha20/streaming-aead-xchacha20.test.ts::"seal then open round-trips bytes for a single chunk"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: StreamingChunkTag cross-package interface
|
||||
|
||||
`@suaveplan/types` SHALL export a `StreamingChunkTag` interface used by attestation / observability consumers that subscribe to per-chunk callbacks via `EncryptStreamAeadOptions.onChunk` and `DecryptStreamAeadOptions.onChunk`. The interface SHALL carry `counter`, `finalFlag`, and `tag: Uint8Array` (the AEAD authentication tag for the chunk).
|
||||
|
||||
#### Scenario: chunk tags are emitted to the onChunk callback
|
||||
|
||||
- **WHEN** `decryptStreamAead(source, { onChunk })` runs to completion over a multi-chunk stream
|
||||
- **THEN** the callback fires once per chunk with a `StreamingChunkTag` carrying the chunk's counter, final-flag, and AEAD tag bytes
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"decryptStreamAead reports the parsed header via onHeader"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: StreamingHeader cross-package interface
|
||||
|
||||
`@suaveplan/types` SHALL export a `StreamingHeader` interface used by attestation / observability consumers that subscribe to the once-per-stream `onHeader` callback. The interface SHALL carry `engineId`, `wireId`, `version`, `baseNonceLength`, `baseNonce`.
|
||||
|
||||
#### Scenario: header is emitted on stream start
|
||||
|
||||
- **WHEN** `encryptStreamAead(key, source, { onHeader, baseNonce, engine })` begins iteration
|
||||
- **THEN** the callback fires exactly once with a `StreamingHeader` whose `engineId` matches the engine in use and whose `baseNonceLength` matches `baseNonce.length`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"decryptStreamAead reports the parsed header via onHeader"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EncryptStreamAeadOptions cross-package interface
|
||||
|
||||
`@suaveplan/types` SHALL export an `EncryptStreamAeadOptions` interface declaring the options bundle accepted by `encryptStreamAead`. Required: `baseNonce: Uint8Array` (caller-supplied; primitives never generate randomness). Optional: `engine`, `signal`, `onHeader`, `onChunk`.
|
||||
|
||||
#### Scenario: baseNonce is required at the type level
|
||||
|
||||
- **WHEN** a consumer omits `baseNonce` from an `EncryptStreamAeadOptions` literal
|
||||
- **THEN** the TypeScript compiler reports a missing-property error (no runtime guard required)
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"rejects a wrong-length base nonce on encrypt"` AND `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"round-trips a multi-chunk plaintext through encryptStreamAead and decryptStreamAead"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: DecryptStreamAeadOptions cross-package interface
|
||||
|
||||
`@suaveplan/types` SHALL export a `DecryptStreamAeadOptions` interface declaring the options bundle accepted by `decryptStreamAead`. All fields are optional: `engine`, `allowUnterminated`, `signal`, `onHeader`, `onChunk`. The decrypt path reads the base nonce from the wire header rather than from caller options, so no `baseNonce` field is exposed.
|
||||
|
||||
#### Scenario: allowUnterminated opts into truncated-stream tolerance
|
||||
|
||||
- **WHEN** `decryptStreamAead(key, source, { allowUnterminated: true })` is called against a stream whose final terminator frame has been dropped
|
||||
- **THEN** the call returns silently rather than throwing `STREAM_TAG_MISMATCH`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.test.ts::"decrypt: allowUnterminated returns silently on truncation"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,31 @@
|
||||
## 1. Move types into @suaveplan/types
|
||||
|
||||
- [ ] 1.1 Create `packages/core/types/src/streaming-aead-engine.ts` with the 6 interfaces (`StreamingAeadEngine`, `StreamingChunkInput`, `StreamingChunkTag`, `StreamingHeader`, `EncryptStreamAeadOptions`, `DecryptStreamAeadOptions`). Types-only — no runtime code, no imports from non-types files.
|
||||
- [ ] 1.2 Add `streaming-aead-engine.md` (≥200 words, basic + advanced examples, full API reference, cross-package consumption pattern).
|
||||
- [ ] 1.3 Re-export all 6 types from `packages/core/types/src/index.ts`.
|
||||
|
||||
## 2. Update crypto-cipher to re-export
|
||||
|
||||
- [ ] 2.1 Replace the 6 interface definitions in `packages/crypto/crypto-cipher/src/streaming/streaming-aead/streaming-aead.types.ts` with `export type { ... } from "@suaveplan/types"`. Keep the 4 runtime values (`STREAMING_AEAD_MAGIC`, `STREAMING_AEAD_VERSION`, `STREAMING_AEAD_MAX_COUNTER`, `streamingAeadHeaderLength`) in place — they are runtime, not types.
|
||||
- [ ] 2.2 Confirm `@suaveplan/types` is in `packages/crypto/crypto-cipher/package.json` `dependencies` (already there per existing imports).
|
||||
- [ ] 2.3 Confirm `@suaveplan/types` is in `packages/crypto/crypto-cipher/vite.config.ts` `external` list (already there).
|
||||
|
||||
## 3. Spec deltas
|
||||
|
||||
- [ ] 3.1 Author `openspec/changes/crypto-streaming-engine-to-types/specs/types/spec.md` — `## ADDED Requirements` block defining the 6 interfaces.
|
||||
- [ ] 3.2 Author `openspec/changes/crypto-streaming-engine-to-types/specs/crypto-cipher/spec.md` — `## MODIFIED Requirements` updating the existing `StreamingAeadEngine contract` requirement to note the canonical home is `@suaveplan/types` (re-export retained for backwards compat).
|
||||
- [ ] 3.3 `openspec validate crypto-streaming-engine-to-types --strict` — green.
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [ ] 4.1 `bunx turbo lint typecheck test --filter=@suaveplan/types` — green.
|
||||
- [ ] 4.2 `bunx turbo test:coverage --filter=@suaveplan/types` — 100/100/100/100 (zero-byte runtime guard still passes).
|
||||
- [ ] 4.3 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-cipher` — green (every existing test still passes; re-export is structurally equivalent).
|
||||
- [ ] 4.4 `bunx turbo test:coverage --filter=@suaveplan/crypto-cipher` — 100/100/100/100.
|
||||
- [ ] 4.5 `bunx turbo build --filter=@suaveplan/crypto` — green (the high-level façade still imports the types via crypto-cipher re-export).
|
||||
- [ ] 4.6 `bunx turbo build --filter=...@suaveplan/crypto-cipher` — every dependent compiles green.
|
||||
|
||||
## 5. Archive
|
||||
|
||||
- [ ] 5.1 `openspec archive crypto-streaming-engine-to-types --yes` — fold both spec deltas into the live corpus.
|
||||
- [ ] 5.2 `openspec validate --specs` — `✓ spec/types` and `✓ spec/crypto-cipher` both green.
|
||||
@@ -0,0 +1,41 @@
|
||||
## Why
|
||||
|
||||
The `verifyChain(bundleBytes, trustAnchorBundleBytes, options)` walker in `packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.ts` accepts a trust anchor as raw `Uint8Array`. There is no shipped helper to **load** that buffer from disk or environment, so every consumer (CLI, daemons, drive sync, network plugins) hand-rolls the same `readFile + parsePublicBundle + self-verify` sequence — or worse, skips the self-verify and trusts whatever bytes happen to live at the path. The umbrella change `restore-crypto-keychain-packer-umbrella` named this surface (`loadTrustAnchor()` / `loadTrustAnchorFromEnv()` / `SUAVEPLAN_TRUST_ANCHOR_PATH`) but the implementation slice was deferred. The `crypto-spec-restore-versioning` archive (2026-05-03) explicitly excluded the requirement because the `src/trust-anchors/` directory does not exist on genesis. The chain-bundle source already references a `TRUST_ANCHOR.MISMATCH` error code (line 199 of `chain-bundle.ts`) that is never defined in `errors/codes/codes.ts` — a stale doc-only signal that the surface was planned and never built.
|
||||
|
||||
This change fills the gap with a small, dependency-free loader module that takes injectable filesystem and environment readers (no direct `node:fs` import in the universal package), self-verifies the bundle on load, and surfaces stable structured errors. The module is the single auditable point through which trust anchors enter a Suaveplan process — a security-relevant choke point.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **MODIFIED `crypto` capability**: add 1 requirement covering trust-anchor bootstrap. New surface in `packages/crypto/crypto/src/trust-anchors/`:
|
||||
- `TrustAnchor` type — `{ bytes: Uint8Array; bundle: PublicBundle<TLayoutFields> }`
|
||||
- `TrustAnchorReader` interface — `read(path: string): Promise<Uint8Array>`
|
||||
- `loadTrustAnchor(reader, path): Promise<TrustAnchor>` — reads bytes, parses, self-verifies
|
||||
- `loadTrustAnchorFromEnv(reader, getenv?, envVar?): Promise<TrustAnchor>` — env-driven path, defaults to `SUAVEPLAN_TRUST_ANCHOR_PATH`
|
||||
- 3 new error codes: `TRUST_ANCHOR.PATH_MISSING`, `TRUST_ANCHOR.READ_FAILED`, `TRUST_ANCHOR.SELF_VERIFY_FAILED`
|
||||
- Subpath export `./trust-anchors`
|
||||
- **MODIFIED `crypto` capability**: extend the existing `Chain bundle traversal` requirement's `Verified by:` list to include the new trust-anchor self-verify scenario (the loader is what produces the `trustAnchorBundleBytes` `verifyChain` consumes).
|
||||
- This change ships **source + tests + docs**, not just spec. Every requirement carries a `Verified by:` pointer to a real test name, per the convention re-affirmed by `crypto-spec-restore-versioning`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(none)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `crypto`: add 1 requirement (`Trust-anchor bootstrap`); no requirements modified or removed.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: `openspec/specs/crypto/spec.md` (1 requirement added).
|
||||
- **Affected code**:
|
||||
- `packages/crypto/crypto/src/trust-anchors/` (new directory — 5 files: types, impl, tests, docs, barrel).
|
||||
- `packages/crypto/crypto/src/errors/codes/codes.ts` (3 codes added).
|
||||
- `packages/crypto/crypto/src/index.ts` (re-export the new surface).
|
||||
- `packages/crypto/crypto/package.json` (subpath export `./trust-anchors`).
|
||||
- `packages/crypto/crypto/vite.config.ts` (build entry).
|
||||
- `packages/crypto/crypto/tests/no-duplicates.test.ts` (whitelist `trust-anchors/`).
|
||||
- **Affected tests**: 2 new test files (round-trip, error-code conformance). Coverage gate stays at 100/100/100/100.
|
||||
- **Downstream**: `crypto-cli` and any daemon that consumes a chain bundle can replace its hand-rolled loader with the shipped one. No breaking change — the existing `verifyChain` signature is unchanged; consumers opt in to the loader.
|
||||
- **Risk**: low. The loader is a thin wrapper over an existing tested verify-path. Filesystem and env access are caller-injected, so the universal package picks up no platform deps.
|
||||
@@ -0,0 +1,67 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto (crypto-trust-anchor-bootstrap)
|
||||
|
||||
**Package**: `@suaveplan/crypto`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time, pointing to a real test in `packages/crypto/crypto/src/trust-anchors/`.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Trust-anchor bootstrap
|
||||
|
||||
`@suaveplan/crypto` SHALL ship a trust-anchor loader at `src/trust-anchors/` that reads a self-verifying root public bundle from a caller-supplied filesystem reader and returns both the raw bytes (for direct use with `verifyChain`) and the parsed `PublicBundle` (for diagnostics). The loader SHALL self-verify the bundle in root-mode (`verifyPublicBundle(bytes, null)`) on every load — bytes that do not self-verify SHALL be rejected with `CRYPTO.TRUST_ANCHOR.SELF_VERIFY_FAILED`.
|
||||
|
||||
The package SHALL expose:
|
||||
|
||||
- `loadTrustAnchor(reader, path): Promise<TrustAnchor>` — explicit-path entry.
|
||||
- `loadTrustAnchorFromEnv(reader, options): Promise<TrustAnchor>` — env-driven entry. `options.getenv` is required (the universal package never reads `process.env` directly); production wires `(name) => process.env[name]`, tests inject deterministic stubs. `options.envVar` defaults to `SUAVEPLAN_TRUST_ANCHOR_PATH`.
|
||||
- `DEFAULT_TRUST_ANCHOR_ENV_VAR` — the canonical env-var name as a `const`.
|
||||
- Types `TrustAnchor`, `TrustAnchorReader`, `TrustAnchorEnvGetter`, `LoadTrustAnchorFromEnvOptions`.
|
||||
|
||||
The universal-tier package MUST NOT import `node:fs` or read `process.env` at the module-import level; all platform access is caller-injected via the `TrustAnchorReader` interface and the optional `getenv` callback. Production wires `(path) => fs.readFile(path)`; tests inject deterministic stubs.
|
||||
|
||||
#### Scenario: round-trip self-verify
|
||||
|
||||
- **WHEN** a self-signed root public bundle is supplied via the reader and `loadTrustAnchor(reader, path)` is called
|
||||
- **THEN** the call returns `{ bytes, bundle }` where `bytes` is byte-identical to the input and `bundle` has a 32-byte `sign` slot public key
|
||||
|
||||
#### Scenario: env-var default name
|
||||
|
||||
- **WHEN** `loadTrustAnchorFromEnv(reader, { getenv })` is called without `options.envVar`
|
||||
- **THEN** `getenv` is invoked with `"SUAVEPLAN_TRUST_ANCHOR_PATH"` and the returned path is read
|
||||
|
||||
#### Scenario: env-var name override
|
||||
|
||||
- **WHEN** `loadTrustAnchorFromEnv(reader, { envVar: "VAULT_ANCHOR", getenv })` is called
|
||||
- **THEN** `getenv` is invoked with `"VAULT_ANCHOR"` and the returned path is read
|
||||
|
||||
#### Scenario: missing env-var rejected
|
||||
|
||||
- **WHEN** `loadTrustAnchorFromEnv(reader, { envVar, getenv: () => undefined })` is called
|
||||
- **THEN** the call throws `CryptoError` with code `CRYPTO.TRUST_ANCHOR.PATH_MISSING` and `context.envVar` reflects the requested name
|
||||
|
||||
#### Scenario: empty env-var string rejected
|
||||
|
||||
- **WHEN** `loadTrustAnchorFromEnv(reader, { envVar, getenv: () => "" })` is called
|
||||
- **THEN** the call throws `CryptoError` with code `CRYPTO.TRUST_ANCHOR.PATH_MISSING`
|
||||
|
||||
#### Scenario: reader failure surfaces structured error
|
||||
|
||||
- **WHEN** the reader's `read(path)` rejects (e.g. ENOENT)
|
||||
- **THEN** the call throws `CryptoError` with code `CRYPTO.TRUST_ANCHOR.READ_FAILED`, with the reader's error attached via `cause` and `context.path` equal to the requested path
|
||||
|
||||
#### Scenario: tampered bytes rejected
|
||||
|
||||
- **WHEN** the loader receives bytes that parse but fail `verifyPublicBundle(bytes, null)`
|
||||
- **THEN** the call throws `CryptoError` with code `CRYPTO.TRUST_ANCHOR.SELF_VERIFY_FAILED` and `context.byteLength` reflects the actual length
|
||||
|
||||
#### Scenario: garbage bytes rejected
|
||||
|
||||
- **WHEN** the loader receives bytes that fail to parse as a public bundle
|
||||
- **THEN** the call throws `CryptoError` with code `CRYPTO.TRUST_ANCHOR.SELF_VERIFY_FAILED`
|
||||
|
||||
**Verified by:** `packages/crypto/crypto/src/trust-anchors/trust-anchor.test.ts::"loads, self-verifies, and returns byte-identical bytes"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.test.ts::"the returned bundle parses identically to a fresh verify on the bytes"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.test.ts::"uses the default env var name SUAVEPLAN_TRUST_ANCHOR_PATH"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.test.ts::"honors a caller-supplied envVar override"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.test.ts::"getenv is invoked exactly once with the resolved env-var name"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.spec-conformance.test.ts::"throws TRUST_ANCHOR.PATH_MISSING when env var is unset"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.spec-conformance.test.ts::"throws TRUST_ANCHOR.PATH_MISSING when env var is empty string"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.spec-conformance.test.ts::"throws TRUST_ANCHOR.READ_FAILED when reader rejects"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.spec-conformance.test.ts::"throws TRUST_ANCHOR.SELF_VERIFY_FAILED on tampered bundle bytes"` AND `packages/crypto/crypto/src/trust-anchors/trust-anchor.spec-conformance.test.ts::"throws TRUST_ANCHOR.SELF_VERIFY_FAILED on garbage bytes"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,35 @@
|
||||
## 1. Source
|
||||
|
||||
- [ ] 1.1 Create `packages/crypto/crypto/src/trust-anchors/trust-anchor.types.ts` with `TrustAnchor`, `TrustAnchorReader`, `LoadTrustAnchorOptions`, `LoadTrustAnchorFromEnvOptions`
|
||||
- [ ] 1.2 Create `packages/crypto/crypto/src/trust-anchors/trust-anchor.ts` with `loadTrustAnchor(reader, path): Promise<TrustAnchor>` and `loadTrustAnchorFromEnv(reader, options?): Promise<TrustAnchor>`. Default env var: `SUAVEPLAN_TRUST_ANCHOR_PATH`. Self-verify via existing `verifyPublicBundle(bytes, null)` (root-mode).
|
||||
- [ ] 1.3 Add error codes to `packages/crypto/crypto/src/errors/codes/codes.ts`: `TRUST_ANCHOR.PATH_MISSING`, `TRUST_ANCHOR.READ_FAILED`, `TRUST_ANCHOR.SELF_VERIFY_FAILED`
|
||||
- [ ] 1.4 Create `packages/crypto/crypto/src/trust-anchors/index.ts` (barrel — explicit named exports per `openspec/AGENTS.md §6a`)
|
||||
- [ ] 1.5 Re-export the public surface from `packages/crypto/crypto/src/index.ts`
|
||||
|
||||
## 2. Build wiring
|
||||
|
||||
- [ ] 2.1 Add subpath export `./trust-anchors` to `packages/crypto/crypto/package.json`
|
||||
- [ ] 2.2 Add `trust-anchors/index` build entry to `packages/crypto/crypto/vite.config.ts`
|
||||
- [ ] 2.3 Whitelist `trust-anchors` in `packages/crypto/crypto/tests/no-duplicates.test.ts` (allowed top-level src dirs)
|
||||
|
||||
## 3. Tests + docs
|
||||
|
||||
- [ ] 3.1 Create `packages/crypto/crypto/src/trust-anchors/trust-anchor.test.ts` covering: round-trip self-verify; deterministic injectable `reader`; explicit-path and env-path entry points; verified bundle is byte-identical to the input.
|
||||
- [ ] 3.2 Create `packages/crypto/crypto/src/trust-anchors/trust-anchor.spec-conformance.test.ts` covering all 3 new error codes (`PATH_MISSING`, `READ_FAILED`, `SELF_VERIFY_FAILED`).
|
||||
- [ ] 3.3 Create `packages/crypto/crypto/src/trust-anchors/trust-anchor.md` (≥200 words, basic + advanced examples, full API reference).
|
||||
|
||||
## 4. Spec delta
|
||||
|
||||
- [ ] 4.1 Author `openspec/changes/crypto-trust-anchor-bootstrap/specs/crypto/spec.md` with the `## ADDED Requirements` block for `Trust-anchor bootstrap`.
|
||||
- [ ] 4.2 Run `openspec validate crypto-trust-anchor-bootstrap --strict` — green.
|
||||
|
||||
## 5. Verification gate
|
||||
|
||||
- [ ] 5.1 `bunx turbo lint typecheck test --filter=@suaveplan/crypto` — green.
|
||||
- [ ] 5.2 `bunx turbo test:coverage --filter=@suaveplan/crypto` — 100/100/100/100.
|
||||
- [ ] 5.3 `bunx turbo build --filter=...@suaveplan/crypto` — every dependent compiles green.
|
||||
|
||||
## 6. Archive
|
||||
|
||||
- [ ] 6.1 `openspec archive crypto-trust-anchor-bootstrap --yes` — fold the requirement into `openspec/specs/crypto/spec.md`.
|
||||
- [ ] 6.2 Confirm post-archive: `openspec validate --specs` shows `✓ spec/crypto`.
|
||||
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
Two live specs in `openspec/specs/` are still in delta-document format rather than live-spec format, leaving them as the last two ✗ entries in `openspec validate --specs --strict`:
|
||||
|
||||
1. **`openspec/specs/crypto-utils/spec.md`** — has both a `## Requirements` section (line 1) and a stray `## ADDED Requirements` section (line 14). The second header is leftover from an archive (likely the `crypto-utils-bytes-refactor` fold) that wrote its delta block but never converged it into the single canonical requirements section the validator expects. Result: missing `## Purpose`, missing `# Title`, and a duplicate-section structural error.
|
||||
2. **`openspec/specs/testing-integration-typesense/spec.md`** — the entire file is a delta document. It opens with `# Capability Spec Delta: testing-integration-typesense (testing-integration-spec-and-generics-hardening)` and uses `## ADDED Requirements` as its top-level requirement section. No `## Purpose`, no live-spec title. The original `testing-integration-spec-and-generics-hardening` archive must have written the delta straight into the live tree without converting it.
|
||||
|
||||
The validator's strict mode requires `# Title` + `## Purpose` + `## Requirements` as the live-spec skeleton. Delta-format headers (`## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`) are valid only inside `openspec/changes/<name>/specs/`. Once a delta archives, the fold step is supposed to merge those blocks into the single `## Requirements` section in the live spec — that step was skipped for both specs.
|
||||
|
||||
This change fixes both. No requirements are added, modified, or removed semantically; the structural fields are populated to live-spec format and the duplicate / mis-named section headers are merged. Every `**Verified by:**` pointer keeps its existing test reference.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **MODIFIED `crypto-utils` capability**: prepend `# crypto-utils` title and a `## Purpose` paragraph; merge the stray `## ADDED Requirements` section into the single `## Requirements` block (i.e. delete the duplicate `## ADDED Requirements` header — the requirements that follow stay where they are, just under the canonical `## Requirements` header instead of a delta-format one).
|
||||
- **MODIFIED `testing-integration-typesense` capability**: replace the `# Capability Spec Delta: ... (testing-integration-spec-and-generics-hardening)` title with `# testing-integration-typesense`; delete the `**Status**: PROPOSED` metadata line; add a `## Purpose` paragraph; replace the `## ADDED Requirements` section header with `## Requirements`. Every requirement keeps its existing text, scenarios, and `**Verified by:**` pointer.
|
||||
- This change is **spec-only**. No source code changes, no test changes, no consumer changes.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(none)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `crypto-utils`: structural cleanup. Zero requirements added, modified, or removed at the semantic level.
|
||||
- `testing-integration-typesense`: structural cleanup. Zero requirements added, modified, or removed at the semantic level.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: `openspec/specs/crypto-utils/spec.md` and `openspec/specs/testing-integration-typesense/spec.md` only.
|
||||
- **Affected code**: none.
|
||||
- **Affected tests**: none. Every cited test already exists and already passes.
|
||||
- **Conformance impact**: `openspec validate crypto-utils --strict` and `openspec validate testing-integration-typesense --strict` both flip from red to green. Combined with `types-spec-scenario-backfill` and `crypto-spec-restore-versioning`, this closes the last 3 ✗ items the corpus had this morning.
|
||||
- **Downstream**: future spec changes that touch either capability can land cleanly through `openspec archive` rather than aborting at the post-fold validation step.
|
||||
- **Risk**: minimal. Pure structural rewording of headers; no requirement text changes beyond the title and purpose insertions.
|
||||
@@ -0,0 +1,28 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: crypto-utils (spec-hygiene-crypto-utils-typesense)
|
||||
|
||||
**Package**: `@suaveplan/crypto-utils`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Spec-only change. No requirement text or scenario content is altered; the file is restructured from delta-format leftovers into live-spec format.
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Pure-composition utility surface
|
||||
|
||||
`@suaveplan/crypto-utils` SHALL expose encoding, byte, constant-time, and test-harness utilities that are safe to author from scratch (no field arithmetic, no secret-data side channels beyond constant-time equality). The package SHALL ship a `# crypto-utils` title and a `## Purpose` section so the live spec format matches the validator's required skeleton; the duplicate `## ADDED Requirements` header that survived from a previous archive's incomplete fold SHALL be merged into the single canonical `## Requirements` section.
|
||||
|
||||
#### Scenario: Encoding utilities available
|
||||
|
||||
- **WHEN** a consumer imports from `@suaveplan/crypto-utils`
|
||||
- **THEN** `hex`, `base64`, `base64url`, `base58` encoders/decoders are exported, each with `encode(bytes): string` and `decode(text): Uint8Array`
|
||||
- **AND** `toHex` / `fromHex` and `toBase64` / `fromBase64` delegate to `@suaveplan/bytes`; decoders throw `BytesError` (a `SuaveplanError` subclass) on malformed input
|
||||
- **AND** `toBase64Url` / `fromBase64Url` are implemented in-package by post-processing the standard base64 result
|
||||
|
||||
#### Scenario: Live spec validates strict
|
||||
|
||||
- **WHEN** `openspec validate crypto-utils --strict` runs against the rewritten file
|
||||
- **THEN** the validator reports zero errors AND the file contains exactly one `## Requirements` section header
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,28 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: testing-integration-typesense (spec-hygiene-crypto-utils-typesense)
|
||||
|
||||
**Package**: `@suaveplan/testing-integration-typesense`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Spec-only change. No requirement text or scenario content is altered; the file is restructured from delta-format leftovers into live-spec format.
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: TypesenseFixture implements ServiceFixture<TypesenseConfig>
|
||||
|
||||
The package SHALL export `TypesenseFixture` with `name === "typesense"`. `TypesenseConfig` SHALL be `{ url: string; apiKey: string }`. The live spec SHALL use the live-spec skeleton (`# testing-integration-typesense` title and `## Purpose` paragraph), replacing the inherited `# Capability Spec Delta: ...` title and `## ADDED Requirements` header that survived from the original `testing-integration-spec-and-generics-hardening` archive's incomplete fold.
|
||||
|
||||
#### Scenario: name property is "typesense"
|
||||
|
||||
- **WHEN** an instance's `.name` is read
|
||||
- **THEN** the value is the literal `"typesense"`
|
||||
|
||||
#### Scenario: Live spec validates strict
|
||||
|
||||
- **WHEN** `openspec validate testing-integration-typesense --strict` runs against the rewritten file
|
||||
- **THEN** the validator reports zero errors AND the file's first heading is `# testing-integration-typesense` AND the requirements section header is `## Requirements`
|
||||
|
||||
**Verified by:** `src/fixture/typesense-fixture.test.ts::"name property returns typesense"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,37 @@
|
||||
## 1. Pre-flight
|
||||
|
||||
- [ ] 1.1 `openspec validate crypto-utils --strict` — capture the error message ("Spec must have a Purpose section").
|
||||
- [ ] 1.2 `openspec validate testing-integration-typesense --strict` — same.
|
||||
- [ ] 1.3 Confirm every `**Verified by:**` pointer in both specs resolves to a real test file (no missing-test risk during the rewrite).
|
||||
|
||||
## 2. Apply the fix to crypto-utils/spec.md
|
||||
|
||||
- [ ] 2.1 Prepend `# crypto-utils` (level-1 title) followed by a blank line.
|
||||
- [ ] 2.2 Prepend `## Purpose` paragraph: cross-package crypto-helper utilities (encoding, byte ops, constant-time compare, random bytes, zeroize, primitive-id registry, KAT harness, Merkle helpers); pure-composition surface with no field arithmetic and no secret-data side channels beyond constant-time equality.
|
||||
- [ ] 2.3 Delete the duplicate `## ADDED Requirements` header at line 14 — the requirements that follow stay where they are; they now live under the single canonical `## Requirements` section.
|
||||
|
||||
## 3. Apply the fix to testing-integration-typesense/spec.md
|
||||
|
||||
- [ ] 3.1 Replace `# Capability Spec Delta: testing-integration-typesense (testing-integration-spec-and-generics-hardening)` with `# testing-integration-typesense`.
|
||||
- [ ] 3.2 Delete the `**Package**: ...` and `**Status**: PROPOSED` metadata lines that follow the title.
|
||||
- [ ] 3.3 Insert a `## Purpose` paragraph: Typesense `ServiceFixture` for integration tests; env-bridge passthrough for CI / shared infra plus container-mode for local dev; JSON-`{ok:true}` health probe; random per-run API key.
|
||||
- [ ] 3.4 Replace the `## ADDED Requirements` section header with `## Requirements`.
|
||||
|
||||
## 4. Spec delta
|
||||
|
||||
- [ ] 4.1 Author `openspec/changes/spec-hygiene-crypto-utils-typesense/specs/crypto-utils/spec.md` with the `## MODIFIED Requirements` section noting the structural cleanup.
|
||||
- [ ] 4.2 Author `openspec/changes/spec-hygiene-crypto-utils-typesense/specs/testing-integration-typesense/spec.md` with the equivalent for typesense.
|
||||
- [ ] 4.3 `openspec validate spec-hygiene-crypto-utils-typesense --strict` — green.
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [ ] 5.1 `openspec validate crypto-utils --strict` — green.
|
||||
- [ ] 5.2 `openspec validate testing-integration-typesense --strict` — green.
|
||||
- [ ] 5.3 `openspec validate --specs` — both ✓.
|
||||
- [ ] 5.4 `bunx turbo lint typecheck test --filter=@suaveplan/crypto-utils` — green.
|
||||
- [ ] 5.5 `bunx turbo lint typecheck test --filter=@suaveplan/testing-integration-typesense` — green.
|
||||
|
||||
## 6. Archive
|
||||
|
||||
- [ ] 6.1 Move `openspec/changes/spec-hygiene-crypto-utils-typesense/` → `openspec/changes/archive/<yyyy-mm-dd>-spec-hygiene-crypto-utils-typesense/`.
|
||||
- [ ] 6.2 Confirm `openspec list` no longer shows the change.
|
||||
@@ -0,0 +1,43 @@
|
||||
## Why
|
||||
|
||||
`openspec validate types --strict` reports 8 hard errors plus 8 corresponding warnings on the live `openspec/specs/types/spec.md`:
|
||||
|
||||
```text
|
||||
✗ requirements.2.text: Requirement must contain SHALL or MUST keyword
|
||||
✗ requirements.11.scenarios: Requirement must have at least one scenario
|
||||
✗ requirements.12.scenarios: Requirement must have at least one scenario
|
||||
✗ requirements.14.scenarios: Requirement must have at least one scenario
|
||||
✗ requirements.15.scenarios: Requirement must have at least one scenario
|
||||
✗ requirements.16.scenarios: Requirement must have at least one scenario
|
||||
✗ requirements.17.scenarios: Requirement must have at least one scenario
|
||||
✗ requirements.20.scenarios: Requirement must have at least one scenario
|
||||
```
|
||||
|
||||
These are pre-existing structural defects authored across `enterprise-types-cross-cutting`, `enterprise-types-plugin-system`, and `enterprise-types-middleware-health` archives — every requirement has a `**Verified by:**` pointer to a real test, but the test name is captured as a markdown line rather than as a `#### Scenario:` block. The result: `openspec validate types --strict` is red, and any future change that tries to fold a delta into `types/spec.md` aborts at the post-fold validation step (the failure mode that just bit `crypto-streaming-engine-to-types`).
|
||||
|
||||
The validator's strict mode requires (a) every requirement to contain `SHALL` or `MUST` (RFC 2119 normative keywords), and (b) every requirement to have at least one `#### Scenario:` block with WHEN/THEN bullet points. Both rules are reasonable. The fix is mechanical: convert each malformed `**Verified by:**` line into a `#### Scenario:` block whose WHEN/THEN paraphrases the cited test name. No requirement is dropped, no requirement gains new normative content; the structural fields populate the spec format the validator expects.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **MODIFIED `types` capability**: backfill `#### Scenario:` blocks on the 7 requirements that have a `**Verified by:**` pointer but no scenarios — `ChunkSourceMetrics interface`, `ChunkRef interface`, `PluginType union`, `PluginRegistration interface`, `DrivePlugin hook-based interface`, `PluginHook type`, `NextFunction type`.
|
||||
- **MODIFIED `types` capability**: rephrase `Testing packages may depend on types` to use `SHALL` (RFC 2119) instead of `MAY`. The semantic content is unchanged — the carve-out is still permission, not requirement — but the validator only recognises `SHALL` / `MUST` as normative keywords. The new wording: "These three packages SHALL be permitted to add `@suaveplan/types` as a `devDependency` …".
|
||||
- This change is **spec-only**. No source-code changes, no test changes, no consumer changes. Every backfilled scenario's WHEN/THEN paraphrases the existing `**Verified by:**` test name; existing tests already pin the behaviour, so the scenarios are factually correct on day one.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(none)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `types`: 8 requirements modified (7 scenario backfills + 1 normative-keyword rephrase). Zero requirements added, zero removed.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: `openspec/specs/types/spec.md` only.
|
||||
- **Affected code**: none.
|
||||
- **Affected tests**: none. Every cited test already exists and already passes.
|
||||
- **Conformance impact**: `openspec validate types --strict` flips from red to green. `openspec validate --specs --strict` for the entire corpus picks up one fewer red item.
|
||||
- **Downstream**: future spec changes that touch `types` (e.g. adding a new cross-package interface) can now land cleanly through `openspec archive` rather than aborting at the post-fold validation step.
|
||||
- **Risk**: minimal. The scenarios paraphrase existing test names; if a paraphrase ever drifts from the test, the `Verified by:` line still pins the actual test name as the source of truth.
|
||||
@@ -0,0 +1,114 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: types (types-spec-scenario-backfill)
|
||||
|
||||
**Package**: `@suaveplan/types`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Spec-only change. Every modified requirement's new `#### Scenario:` block paraphrases the existing `**Verified by:**` pointer; the cited tests already exist and already pass.
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Testing packages may depend on types
|
||||
|
||||
The three testing-infrastructure packages (`@suaveplan/testing`, `@suaveplan/testing-dom`, `@suaveplan/testing-e2e`) SHALL be permitted to add `@suaveplan/types` as a `devDependency` — this is the one exception to the otherwise-strict no-`@suaveplan/*`-dep rule — because `@suaveplan/types` emits no runtime and therefore cannot create a circular test/subject dependency. The same carve-out SHALL also permit `@suaveplan/error` to declare `@suaveplan/types` as a runtime dependency for the `MessageResolver` type.
|
||||
|
||||
#### Scenario: Rule-8 carve-out documented
|
||||
|
||||
- **WHEN** `CLAUDE.md` rule 8 is read
|
||||
- **THEN** it explicitly states that `@suaveplan/types` is the sole exception to the no-workspace-dep rule
|
||||
|
||||
**Verified by:** `tests/spec-conformance.test.ts` (CLAUDE.md rule-8 carve-out check).
|
||||
|
||||
---
|
||||
|
||||
### Requirement: ChunkSourceMetrics interface
|
||||
|
||||
The package SHALL export `ChunkSourceMetrics` with `avgResponseTime: number`, `successRate: number`, `totalRequests: number`, `failedRequests: number`, and `lastAccess: Date`.
|
||||
|
||||
#### Scenario: All five fields satisfy the interface
|
||||
|
||||
- **WHEN** an object literal supplies `avgResponseTime`, `successRate`, `totalRequests`, `failedRequests`, and `lastAccess`
|
||||
- **THEN** the object is assignable to `ChunkSourceMetrics` and TypeScript narrows the field types correctly
|
||||
|
||||
**Verified by:** `tests/spec-conformance.test.ts`::"ChunkSourceMetrics has all five required fields"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: ChunkRef interface
|
||||
|
||||
The package SHALL export `ChunkRef` with `fileId: string`, `version: number`, and `checksum: string`.
|
||||
|
||||
#### Scenario: Object with fileId / version / checksum compiles
|
||||
|
||||
- **WHEN** a literal `{ fileId, version, checksum }` is asserted as `ChunkRef`
|
||||
- **THEN** the assertion compiles and TypeScript narrows each field to the documented primitive type
|
||||
|
||||
**Verified by:** `tests/spec-conformance.test.ts`::"ChunkRef has fileId, version, and checksum"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: PluginType union
|
||||
|
||||
The package SHALL export `PluginType` as `'storage' | 'transform' | 'hook' | 'middleware' | 'kms' | 'dedup' | 'cow'`.
|
||||
|
||||
#### Scenario: All seven categories are exhaustive
|
||||
|
||||
- **WHEN** a `switch (kind: PluginType)` enumerates every variant
|
||||
- **THEN** TypeScript's exhaustiveness checker reports no missing case AND a synthetic eighth literal fails type-narrowing
|
||||
|
||||
**Verified by:** `tests/spec-conformance.test.ts`::"PluginType exhaustiveness covers all seven categories"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: PluginRegistration interface
|
||||
|
||||
The package SHALL export `PluginRegistration` with `plugin: Plugin`, `priority: number`, and `enabled: boolean`.
|
||||
|
||||
#### Scenario: PluginRegistration references Plugin
|
||||
|
||||
- **WHEN** a `PluginRegistration` literal supplies a `Plugin` instance, a `priority` number, and an `enabled` boolean
|
||||
- **THEN** the literal compiles and the `plugin` field's `name` / `version` / `type` are reachable via `.plugin`
|
||||
|
||||
**Verified by:** `tests/spec-conformance.test.ts`::"PluginRegistration references Plugin interface"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: DrivePlugin hook-based interface
|
||||
|
||||
The package SHALL export `DrivePlugin` with `name: string`, `hooks: Record<string, PluginHook>`, and optional `priority: number`.
|
||||
|
||||
#### Scenario: Mock drive plugin compiles without runtime deps
|
||||
|
||||
- **WHEN** a consumer in `tests/cross-package-compat.test.ts` declares a `DrivePlugin`-shaped object literal with `name`, `hooks: {}`, and no `@suaveplan/*` runtime imports
|
||||
- **THEN** the literal is assignable to `DrivePlugin` AND the test file builds with zero `@suaveplan/*` runtime dependencies
|
||||
|
||||
**Verified by:** `tests/cross-package-compat.test.ts`::"mock drive plugin implements DrivePlugin without runtime deps"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: PluginHook type
|
||||
|
||||
The package SHALL export `PluginHook` as `(context: unknown, next: NextFunction) => Promise<unknown>`.
|
||||
|
||||
#### Scenario: PluginHook signature matches expected shape
|
||||
|
||||
- **WHEN** a function `(context, next) => Promise.resolve(undefined)` is asserted as `PluginHook`
|
||||
- **THEN** the assertion compiles AND a function with a different arity (e.g. `(ctx) => ...`) fails to type-check
|
||||
|
||||
**Verified by:** `tests/spec-conformance.test.ts`::"PluginHook signature matches expected shape"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: NextFunction type
|
||||
|
||||
The package SHALL export `NextFunction` as `() => Promise<void>`.
|
||||
|
||||
#### Scenario: NextFunction is a no-arg promise-returning function
|
||||
|
||||
- **WHEN** a no-arg async function is asserted as `NextFunction`
|
||||
- **THEN** the assertion compiles AND a function that takes any argument fails to type-check
|
||||
|
||||
**Verified by:** `tests/spec-conformance.test.ts`::"NextFunction is a no-arg promise-returning function"
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,31 @@
|
||||
## 1. Pre-flight audit
|
||||
|
||||
- [ ] 1.1 Run `openspec validate types --strict` and capture the exact list of failing requirement indices.
|
||||
- [ ] 1.2 Confirm every cited `**Verified by:**` test name resolves to a real `it(...)` / `test(...)` call site in `packages/core/types/tests/` or `src/`.
|
||||
|
||||
## 2. Backfill scenarios in the live spec
|
||||
|
||||
- [ ] 2.1 `Testing packages may depend on types` — rephrase to use `SHALL` (RFC 2119) instead of `MAY`. Keep semantic content identical. Add a second `#### Scenario:` if the existing one does not already cover the rephrased normative.
|
||||
- [ ] 2.2 `ChunkSourceMetrics interface` — add `#### Scenario: All five fields satisfy the interface` paraphrasing the cited test.
|
||||
- [ ] 2.3 `ChunkRef interface` — add `#### Scenario: Object with fileId / version / checksum compiles` paraphrasing the cited test.
|
||||
- [ ] 2.4 `PluginType union` — add `#### Scenario: All seven categories are exhaustive` paraphrasing the cited test.
|
||||
- [ ] 2.5 `PluginRegistration interface` — add `#### Scenario: PluginRegistration references Plugin` paraphrasing the cited test.
|
||||
- [ ] 2.6 `DrivePlugin hook-based interface` — add `#### Scenario: Mock drive plugin compiles without runtime deps` paraphrasing the cited test.
|
||||
- [ ] 2.7 `PluginHook type` — add `#### Scenario: PluginHook signature matches expected shape` paraphrasing the cited test.
|
||||
- [ ] 2.8 `NextFunction type` — add `#### Scenario: NextFunction is a no-arg promise-returning function` paraphrasing the cited test.
|
||||
|
||||
## 3. Spec delta
|
||||
|
||||
- [ ] 3.1 Author `openspec/changes/types-spec-scenario-backfill/specs/types/spec.md` with `## MODIFIED Requirements` blocks for all 8 requirements.
|
||||
- [ ] 3.2 `openspec validate types-spec-scenario-backfill --strict` — green.
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [ ] 4.1 `openspec validate types --strict` — green (8 hard errors gone).
|
||||
- [ ] 4.2 `openspec validate --specs` — `✓ spec/types`.
|
||||
- [ ] 4.3 `bunx turbo lint typecheck test --filter=@suaveplan/types` — green (this is a spec-only change but the package gate must remain green).
|
||||
|
||||
## 5. Archive
|
||||
|
||||
- [ ] 5.1 Move `openspec/changes/types-spec-scenario-backfill/` → `openspec/changes/archive/<yyyy-mm-dd>-types-spec-scenario-backfill/`.
|
||||
- [ ] 5.2 Confirm `openspec list` no longer shows the change.
|
||||
@@ -0,0 +1,252 @@
|
||||
# OpenSpec Change: enterprise-network
|
||||
|
||||
- **Change ID**: enterprise-network
|
||||
- **Package**: `@suaveplan/network`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/network/network`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/network.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/network` on the genesis branch from scratch at enterprise quality. The package provides core networking utilities for universal TypeScript: a typed `HttpClient` with middleware pipeline, `WebSocketClient` with auto-reconnect and backpressure, URL construction/parsing helpers, fetch timeout and cancellation wrappers, request/response interceptors, and network-quality probing. Injectable `fetch` and `WebSocket` constructors for test-time substitution. No hard browser/Node platform deps.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data. The main-branch package had 85.40% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Base class for `NetworkError`; `NETWORK.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||||
| `@suaveplan/retry` (`workspace:^`) | Exponential backoff + circuit breaker on HTTP/WS paths |
|
||||
| `@suaveplan/serialize` (`workspace:^`) | JSON request/response body serialisation |
|
||||
| `zod` (`catalog:forms`) | Zod schemas for all public option types |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters on every request |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API
|
||||
|
||||
### HttpClient
|
||||
|
||||
```ts
|
||||
class NetworkError extends SuaveplanError
|
||||
|
||||
type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS'
|
||||
|
||||
interface HttpRequest {
|
||||
url: string
|
||||
method?: HttpMethod // default: 'GET'
|
||||
headers?: Record<string, string>
|
||||
body?: unknown // serialised via @suaveplan/serialize
|
||||
timeoutMs?: number // default: 30000
|
||||
signal?: AbortSignal
|
||||
}
|
||||
|
||||
interface HttpResponse<T = unknown> {
|
||||
status: number
|
||||
statusText: string
|
||||
headers: Record<string, string>
|
||||
body: T
|
||||
url: string
|
||||
durationMs: number
|
||||
}
|
||||
|
||||
type HttpMiddleware = (request: HttpRequest, next: (req: HttpRequest) => Promise<HttpResponse>) => Promise<HttpResponse>
|
||||
|
||||
interface HttpClientOptions {
|
||||
baseUrl?: string
|
||||
defaultHeaders?: Record<string, string>
|
||||
defaultTimeoutMs?: number
|
||||
middleware?: HttpMiddleware[]
|
||||
fetch?: typeof globalThis.fetch
|
||||
logger?: LoggerLike
|
||||
clock?: Clock
|
||||
}
|
||||
|
||||
class HttpClient {
|
||||
constructor(options?: HttpClientOptions)
|
||||
request<T = unknown>(req: HttpRequest): Promise<HttpResponse<T>>
|
||||
get<T = unknown>(path: string, options?: Omit<HttpRequest, 'url' | 'method'>): Promise<HttpResponse<T>>
|
||||
post<T = unknown>(path: string, body: unknown, options?: Omit<HttpRequest, 'url' | 'method' | 'body'>): Promise<HttpResponse<T>>
|
||||
put<T = unknown>(path: string, body: unknown, options?: Omit<HttpRequest, 'url' | 'method' | 'body'>): Promise<HttpResponse<T>>
|
||||
patch<T = unknown>(path: string, body: unknown, options?: Omit<HttpRequest, 'url' | 'method' | 'body'>): Promise<HttpResponse<T>>
|
||||
delete<T = unknown>(path: string, options?: Omit<HttpRequest, 'url' | 'method'>): Promise<HttpResponse<T>>
|
||||
use(middleware: HttpMiddleware): this
|
||||
}
|
||||
|
||||
function createHttpClient(options?: HttpClientOptions): HttpClient
|
||||
```
|
||||
|
||||
### WebSocketClient
|
||||
|
||||
```ts
|
||||
type WsReadyState = 'connecting' | 'open' | 'closing' | 'closed'
|
||||
type WsMessage = string | ArrayBuffer | Uint8Array
|
||||
|
||||
interface WebSocketClientOptions {
|
||||
url: string
|
||||
protocols?: string[]
|
||||
reconnect?: boolean // default: true
|
||||
reconnectDelayMs?: number // base delay; uses @suaveplan/retry exponential backoff
|
||||
maxReconnectAttempts?: number // default: 10
|
||||
pingIntervalMs?: number // default: 30000; 0 = disabled
|
||||
timeoutMs?: number // connect timeout; default: 10000
|
||||
WebSocket?: typeof WebSocket // injectable; defaults to globalThis.WebSocket
|
||||
logger?: LoggerLike
|
||||
clock?: Clock
|
||||
}
|
||||
|
||||
class WebSocketClient {
|
||||
constructor(options: WebSocketClientOptions)
|
||||
connect(signal?: AbortSignal): Promise<void>
|
||||
disconnect(): void
|
||||
send(message: WsMessage): void
|
||||
on(event: 'message', listener: (msg: WsMessage) => void): () => void
|
||||
on(event: 'open' | 'close' | 'error', listener: () => void): () => void
|
||||
get readyState(): WsReadyState
|
||||
get reconnectCount(): number
|
||||
}
|
||||
|
||||
function createWebSocketClient(options: WebSocketClientOptions): WebSocketClient
|
||||
```
|
||||
|
||||
### URL utilities
|
||||
|
||||
```ts
|
||||
function buildUrl(base: string, path?: string, params?: Record<string, string | number | boolean>): string
|
||||
function parseQueryString(qs: string): Record<string, string>
|
||||
function serializeQueryString(params: Record<string, string | number | boolean>): string
|
||||
function isAbsoluteUrl(url: string): boolean
|
||||
function joinPaths(...segments: string[]): string
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type NetworkErrorCode =
|
||||
| 'NETWORK_REQUEST_FAILED'
|
||||
| 'NETWORK_TIMEOUT'
|
||||
| 'NETWORK_ABORT'
|
||||
| 'NETWORK_BAD_STATUS' // 4xx/5xx
|
||||
| 'NETWORK_PARSE_FAILED'
|
||||
| 'NETWORK_WS_CONNECT_FAILED'
|
||||
| 'NETWORK_WS_SEND_FAILED'
|
||||
| 'NETWORK_WS_MAX_RECONNECTS'
|
||||
| 'NETWORK_INVALID_URL'
|
||||
|
||||
const NETWORK_ERROR_METADATA: Readonly<Record<NetworkErrorCode, CodeMetadata>>
|
||||
function registerNetworkErrorCodes(): void
|
||||
```
|
||||
|
||||
### Zod schemas
|
||||
|
||||
```ts
|
||||
HttpRequestSchema
|
||||
HttpClientOptionsSchema
|
||||
WebSocketClientOptionsSchema
|
||||
```
|
||||
|
||||
### Built-in middleware
|
||||
|
||||
```ts
|
||||
const loggingMiddleware: (logger: LoggerLike) => HttpMiddleware
|
||||
const retryMiddleware: (options?: RetryOptions) => HttpMiddleware // @suaveplan/retry
|
||||
const authMiddleware: (token: string | (() => string)) => HttpMiddleware
|
||||
const rateLimitMiddleware: (options: { maxRpm: number; clock?: Clock }) => HttpMiddleware
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Middleware pipeline** — `use(middleware)` appends to ordered chain; each middleware gets `(request, next)` and can modify request/response, short-circuit, or retry.
|
||||
2. **Injectable `fetch`** — `HttpClientOptions.fetch` defaults to `globalThis.fetch`; swap to a stub in tests without `vi.mock`.
|
||||
3. **Injectable `WebSocket`** — same pattern; `WebSocketClientOptions.WebSocket` defaults to `globalThis.WebSocket`.
|
||||
4. **Retry wiring** — `retryMiddleware` uses `@suaveplan/retry` with circuit breaker; configurable per `HttpClient` instance.
|
||||
5. **WS auto-reconnect** — exponential backoff via `@suaveplan/retry`; configurable max attempts; ping/pong keepalive.
|
||||
6. **OTel instrumentation** — span `http.request` (attrs: `http.method`, `http.url`, `http.status_code`), counter `http_request_total`, histogram `http_request_duration_ms`; counter `ws.reconnect_total`.
|
||||
7. **Property-based tests** — `buildUrl` round-trip with query params, `parseQueryString(serializeQueryString(params)) == params` for any param map.
|
||||
8. **Benchmark suite** — `buildUrl` with 10 params, middleware chain dispatch (5 middlewares, no-op fetch stub).
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/network/network/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
http-client/
|
||||
http-client.ts
|
||||
http-client.md
|
||||
http-client.types.ts
|
||||
http-client.test.ts
|
||||
index.ts
|
||||
websocket-client/
|
||||
websocket-client.ts
|
||||
websocket-client.md
|
||||
websocket-client.types.ts
|
||||
websocket-client.test.ts
|
||||
index.ts
|
||||
middleware/
|
||||
logging/
|
||||
logging.ts
|
||||
logging.md
|
||||
logging.test.ts
|
||||
index.ts
|
||||
retry/
|
||||
retry.ts
|
||||
retry.md
|
||||
retry.test.ts
|
||||
index.ts
|
||||
auth/
|
||||
auth.ts
|
||||
auth.md
|
||||
auth.test.ts
|
||||
index.ts
|
||||
rate-limit/
|
||||
rate-limit.ts
|
||||
rate-limit.md
|
||||
rate-limit.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
url.ts
|
||||
url.md
|
||||
url.test.ts
|
||||
__benchmarks__/
|
||||
network.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: `@suaveplan/service-discovery`, `@suaveplan/webhook-client` (may refactor to consume), any server/API packages.
|
||||
**Breaking changes**: none — fresh build.
|
||||
**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/serialize` published to Verdaccio.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Tasks: enterprise-network
|
||||
|
||||
**Change ID**: enterprise-network
|
||||
**Package**: `@suaveplan/network`
|
||||
**Target path**: `universal/network/network`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/serialize`
|
||||
|
||||
---
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory `universal/network/network/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/retry workspace:^`, `@suaveplan/serialize workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] Write `src/types/common.ts` — `HttpMethod`, `HttpRequest`, `HttpResponse`, `HttpMiddleware`, `HttpClientOptions`, `WsReadyState`, `WsMessage`, `WebSocketClientOptions`.
|
||||
- [ ] Write `src/types/common.md`.
|
||||
- [ ] Write `src/error-codes.ts` — `NetworkErrorCode`, `NETWORK_ERROR_METADATA`, `registerNetworkErrorCodes()`.
|
||||
- [ ] Write Zod schemas: `HttpRequestSchema`, `HttpClientOptionsSchema`, `WebSocketClientOptionsSchema`.
|
||||
|
||||
---
|
||||
|
||||
## 3. URL utilities
|
||||
|
||||
- [ ] Implement `buildUrl`, `parseQueryString`, `serializeQueryString`, `isAbsoluteUrl`, `joinPaths` in `src/utils/url.ts`.
|
||||
- [ ] Write `url.test.ts` (≤500 lines): each function, edge cases (empty params, absolute URLs, path joining).
|
||||
- [ ] Write `url.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Middleware
|
||||
|
||||
### Logging middleware
|
||||
|
||||
- [ ] Implement `loggingMiddleware(logger): HttpMiddleware` — logs method, URL, status, duration.
|
||||
- [ ] Write `logging.test.ts` and `logging.md`.
|
||||
|
||||
### Retry middleware
|
||||
|
||||
- [ ] Implement `retryMiddleware(options?): HttpMiddleware` — wraps `@suaveplan/retry`; retries on 429/5xx and network errors; uses exponential backoff.
|
||||
- [ ] Write `retry.test.ts` and `retry.md`.
|
||||
|
||||
### Auth middleware
|
||||
|
||||
- [ ] Implement `authMiddleware(token): HttpMiddleware` — adds `Authorization: Bearer <token>` header; `token` may be a function for dynamic tokens.
|
||||
- [ ] Write `auth.test.ts` and `auth.md`.
|
||||
|
||||
### Rate-limit middleware
|
||||
|
||||
- [ ] Implement `rateLimitMiddleware(options): HttpMiddleware` — sliding-window request rate limiting using injectable `Clock`; queues excess requests.
|
||||
- [ ] Write `rate-limit.test.ts` and `rate-limit.md`.
|
||||
|
||||
---
|
||||
|
||||
## 5. HttpClient
|
||||
|
||||
- [ ] Implement `HttpClient` — middleware chain dispatch, injectable `fetch`, body serialisation via `@suaveplan/serialize`, timeout via `AbortSignal.timeout`-compatible wrapper, response body deserialisation, `use()`.
|
||||
- [ ] Wire OTel: span `http.request`, counter `http_request_total`, histogram `http_request_duration_ms`.
|
||||
- [ ] Write `http-client.test.ts` (≤500 lines): GET/POST/PUT/DELETE with stub fetch, timeout, abort, 4xx throws `NETWORK_BAD_STATUS`, middleware chain order.
|
||||
- [ ] Write `http-client.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. WebSocketClient
|
||||
|
||||
- [ ] Implement `WebSocketClient` — injectable `WebSocket`, auto-reconnect with `@suaveplan/retry` backoff, ping/pong keepalive using injectable `Clock`, `on()` event listener registry, `send()`, `connect()`, `disconnect()`.
|
||||
- [ ] Wire OTel: counter `ws.reconnect_total`.
|
||||
- [ ] Write `websocket-client.test.ts` (≤500 lines): connect, message, reconnect, max reconnects exceeded throws, abort on disconnect.
|
||||
- [ ] Write `websocket-client.md`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Benchmarks
|
||||
|
||||
- [ ] Write `src/__benchmarks__/network.bench.ts` — `buildUrl` with 10 params, middleware chain dispatch 5 middlewares no-op stub fetch.
|
||||
|
||||
---
|
||||
|
||||
## 8. Tests
|
||||
|
||||
- [ ] Write `tests/integration.test.ts` — `HttpClient` + middleware stack end-to-end with stub fetch.
|
||||
- [ ] Write `tests/property.test.ts` (fast-check) — `buildUrl` round-trip, `parseQueryString(serializeQueryString(p)) deep equals p`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Docs + verify + publish
|
||||
|
||||
- [ ] All co-located `.md` files (≥200 words each).
|
||||
- [ ] Write `README.md` at package root.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/network` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/network` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/network`.
|
||||
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-network/`.
|
||||
155
openspec/changes/archive/2026-05-04-i18n-completion/proposal.md
Normal file
155
openspec/changes/archive/2026-05-04-i18n-completion/proposal.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# i18n completion — ergonomic t(), full ICU, plugin surface, Intl wrappers
|
||||
|
||||
**Package**: `@suaveplan/i18n`
|
||||
**Status**: PROPOSED
|
||||
**Type**: feature + spec-conformance
|
||||
**Date**: 2026-05-04
|
||||
|
||||
## Why
|
||||
|
||||
A 2026-05-04 review against `i18next`, `FormatJS / react-intl`, `LinguiJS`, `vue-i18n`, and `next-intl` flagged a long tail of features that are headline-tier in every popular i18n library and missing here. The package today is a clean, well-tested **core** — but the surface that consumers actually call (`MessageCatalog`, `InterpolationEngine`, `PluralizationEngine`, `MessageParser`) requires three separate manual calls to do what `i18next.t('item', { count: 3 })` does in one. It also lacks a formal plugin lifecycle, three of four `Intl.*` wrappers, and several real-world ICU MessageFormat features (typed args, apostrophe escape, rich-text/tag interpolation). OTel meter instruments are defined but never incremented.
|
||||
|
||||
This change closes those gaps so `@suaveplan/i18n` is genuinely on par with i18next in features, with the genesis-quality surface (Zod-validated, generic-threaded, OTel-wired, 100/100/100/100). It pairs with `i18n-storage-backends` (which adds the `Backend` interface) and is a prerequisite for `enterprise-react-i18n`.
|
||||
|
||||
## What changes
|
||||
|
||||
### 1. Ergonomic `t()` — one-call translate
|
||||
|
||||
The current `MessageCatalog.t(key)` returns the raw catalog string. Consumers manually wire pluralization + interpolation + missing-key handling. This is the biggest DX gap vs every popular library.
|
||||
|
||||
- ADDED: `MessageCatalog.t(key, options?: TranslateOptions)` accepts a single options bag that internally resolves plural + interpolation + nested-key references + context selector + default value:
|
||||
- `count: number` — when present, runs `PluralizationEngine.resolve` and selects the matching plural form. The catalog key may be a plain string or an object `{ one, other, ... }`; both shapes work.
|
||||
- `context: string` — i18next-compatible context selector. `t('greeting', { context: 'male' })` looks up `greeting_male` first, falling back to `greeting`.
|
||||
- `defaultValue: string` — fallback when key is missing, in lieu of returning the key.
|
||||
- `values: Record<string, unknown>` — interpolation values; `count` is auto-injected so plural strings can use `{count}` directly.
|
||||
- `escapeHtml?: boolean` — overrides the engine default for this call.
|
||||
- `formatters?: Record<string, ValueFormatter>` — per-call formatter overrides.
|
||||
- Nested-key references in source strings: `"$t(common:cancel)"` resolves to the value of `common:cancel` recursively; cycle detection via depth limit.
|
||||
- ADDED: `TranslateOptions` and `PluralKey` types in `src/core/catalog/translate.types.ts`.
|
||||
- ADDED: `t.plural(key, count, values?)` shortcut for the common case.
|
||||
- MODIFIED: existing `MessageCatalog.t(key)` single-string call remains backwards-compatible — `t(key)` is `t(key, {})`.
|
||||
|
||||
### 2. Full ICU MessageFormat support
|
||||
|
||||
The current `MessageParser` handles `{name}`, `{count, plural, ...}`, `{gender, select, ...}`. Real ICU (and FormatJS) callers expect more.
|
||||
|
||||
- ADDED: `selectordinal` node type — `{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`. Routes through `PluralizationEngine` with `ordinal: true`.
|
||||
- ADDED: typed argument support: `{date, date, short}`, `{at, time, medium}`, `{n, number, currency/USD}`, `{n, number, percent}`, `{n, number, ::compact-short}` (ICU number skeleton). Wired through `formatDate` / `formatNumber` / `formatTime` from `@suaveplan/i18n/formatting/*`.
|
||||
- ADDED: apostrophe quoting — `it''s` renders as `it's`; `'{literal}'` renders as `{literal}` (skips ICU parsing inside single-quoted runs). This is the standard ICU MessageFormat quoting rule and the current parser silently misparses these strings.
|
||||
- ADDED: rich-text / tag interpolation — `'<bold>welcome</bold>'` parses to a `TagNode` AST; `MessageParser.format(message, values)` accepts `values: { bold: (chunks) => string }` to produce a string, and `MessageParser.formatChunks(message, values, chunkValues)` returns `Array<string | T>` for React/Vue consumers (where `chunkValues` like `{ bold: (chunks) => <b>{chunks}</b> }` produce framework nodes — used heavily by `enterprise-react-i18n`).
|
||||
- ADDED: `MessageNode` discriminated union expands: `text | variable | plural | selectordinal | select | tag | typed-argument`.
|
||||
- ADDED: ICU validator — `MessageParser.validate(message): ValidationResult` reports unbalanced braces, missing `other` branches, undefined plural categories, and unknown typed-argument types. Used by the optional build-time linter.
|
||||
|
||||
### 3. Formal plugin / extensibility surface
|
||||
|
||||
Today's "extensibility" is informal: `addFormatter`, `registerRule`, etc. on individual engines. There's no plugin lifecycle and no event bus, which makes cross-cutting concerns (logging, missing-key reporters, post-processors) hard to wire.
|
||||
|
||||
- ADDED: `I18nPlugin` interface in `src/core/plugin/plugin.types.ts`:
|
||||
- `name: string`, `version?: string`
|
||||
- `install?(i18n: I18nInstance): void | Promise<void>` — register hooks, formatters, backends
|
||||
- `dispose?(): void | Promise<void>` — teardown
|
||||
- Plugin types (a single plugin can implement multiple): `'backend' | 'formatter' | 'post-processor' | 'detector' | 'logger'`
|
||||
- ADDED: `I18nInstance` — a top-level façade that binds together `MessageCatalog`, `InterpolationEngine`, `PluralizationEngine`, `MessageParser`, `LocaleResolver`, and the plugin registry. Created via `createI18n(options)`. Existing engines remain individually constructable.
|
||||
- ADDED: Event bus topics on `I18nInstance` (delegates to `@suaveplan/events`):
|
||||
- `languageChanged` — `{ from, to }`
|
||||
- `loaded` — `{ locale, namespace, backend? }`
|
||||
- `missingKey` — `{ locale, namespace, key, defaultValue? }`
|
||||
- `keyAdded` — `{ locale, namespace, key, value }` (for HMR / save-missing flows)
|
||||
- `pluralRuleAdded` — `{ locale }`
|
||||
- ADDED: post-processor plugins. `I18nInstance` accepts `postProcessors: PostProcessor[]` where each is `(value, key, options) => string`. Built-in post-processors: `markdown` (renders bold/italic/links via `marked` peer), `sprintf` (printf-style format strings — opt-in i18next compatibility), `pseudo-localization` (transforms `Welcome` → `[!! Wëlçömé !!]` for layout testing).
|
||||
- ADDED: detector plugins (browser-side locale detection). Built-in detectors: `navigator-detector`, `localstorage-detector`, `cookie-detector`, `query-detector`, `path-detector`, `subdomain-detector`. Browser `LocaleResolver` composes them via `detectionOrder`. Server-side `createLocaleMiddleware` already covers the equivalent surface.
|
||||
|
||||
### 4. Missing Intl wrappers — list, display-names, expanded number helpers
|
||||
|
||||
The current `formatting/` module exposes `currency`, `date`, and (after `i18n-formatters` lands) `number` and `relative-time`. Two more `Intl.*` APIs are still unwrapped, and three convenience number helpers are universally expected.
|
||||
|
||||
- ADDED: `formatList(values, locale, options?)` — wraps `Intl.ListFormat`. Options: `style: 'long' | 'short' | 'narrow'`, `type: 'conjunction' | 'disjunction' | 'unit'`. Per-(locale, options) cache like the other formatters.
|
||||
- ADDED: `formatDisplayName(code, locale, options)` — wraps `Intl.DisplayNames`. Options: `type: 'language' | 'region' | 'script' | 'currency' | 'calendar' | 'dateTimeField'`, `style`, `fallback`. Use cases: building locale switchers, currency dropdowns, region pickers.
|
||||
- ADDED: `formatPercent(value, locale, options?)` — pre-bound `formatNumber({ style: 'percent' })`.
|
||||
- ADDED: `formatCompact(value, locale, options?)` — pre-bound `formatNumber({ notation: 'compact' })` for "1.2K" / "1.2M" output.
|
||||
- ADDED: `formatUnit(value, unit, locale, options?)` — pre-bound `formatNumber({ style: 'unit', unit })` for "12 km/h" output.
|
||||
|
||||
### 5. Locale + plural correctness fixes
|
||||
|
||||
- MODIFIED: `parseAcceptLanguage` preserves script-subtag casing (`zh-Hant-TW`, not `zh-hant-tw`) per BCP-47. The current implementation lowercases the entire tag.
|
||||
- MODIFIED: `PluralizationEngine` defaults to `Intl.PluralRules` first, falls back to the hand-written rule registry. The hand-written rules drift against CLDR over time; making `Intl.PluralRules` the primary source future-proofs against CLDR releases. Hand-written rules remain registered as overrides for runtimes that lack `Intl.PluralRules` (e.g. very old browsers — vanishingly rare in genesis, but the override path costs nothing).
|
||||
- ADDED: `Intl.Locale.weekInfo`-aware `getDayNames(locale, style?)` — first-day-of-week is consulted via `new Intl.Locale(locale).weekInfo.firstDay` (1 = Monday, 7 = Sunday). Falls back to Monday when `weekInfo` is unavailable. Existing Monday-hardcoded behaviour was a bug for US/Mid-East locales.
|
||||
- ADDED: `formatSegment(text, locale, granularity?)` and `compareLocale(a, b, locale, options?)` — thin wrappers around `Intl.Segmenter` and `Intl.Collator` for non-Latin search/sort.
|
||||
- ADDED: `pseudoLocalize(text, options?)` post-processor with three modes: `accent` (`Welcome` → `Wéłçömé`), `bracket` (`Welcome` → `[!! Welcome !!]`), `expand` (Welcome → `Welcomeeeee` to test layout). Used by the `pseudo-localization` post-processor plugin and by tests directly.
|
||||
|
||||
### 6. Wire OTel meter instruments
|
||||
|
||||
`getI18nMetrics()` exists with `translateTotal`, `localeResolveTotal`, `translateDuration` instruments (`src/observability/metrics.ts`), but no production code path increments them. They are dead code today.
|
||||
|
||||
- MODIFIED: `MessageCatalog.get` increments `i18n.translate.total{outcome,locale}` on every call and records `i18n.translate.duration_ms{locale}` for every lookup.
|
||||
- MODIFIED: `LocaleResolver.resolve` and `negotiateLocale` increment `i18n.locale.resolve.total{strategy,locale}`.
|
||||
- ADDED: `i18n.interpolation.duration_ms` histogram on `InterpolationEngine.render` and `MessageParser.format`.
|
||||
- ADDED: `i18n.missing_key.total` counter labelled by `locale`, `namespace` — incremented from `MessageCatalog.get` whenever the lookup falls through to the missing-key handler or returns `undefined`.
|
||||
|
||||
### 7. Workflow tooling
|
||||
|
||||
- ADDED: missing-key reporter plugin — `createMissingKeyReporter({ logger?, onMissing? })` registers as an `I18nPlugin` and listens on the `missingKey` event. Default behaviour: log via `@suaveplan/logger` at `warn` level. With a backend configured, it can also call `catalog.saveMissing` (gated by `saveMissing: true`).
|
||||
- ADDED: `extractKeys(source: string, options?)` — minimal AST-free extractor that walks a source string for `t('...')` / `t("...")` / `<Trans i18nKey="...">` patterns and returns the deduplicated key list. Not a full TypeScript parser; intended for the simple case and used by the optional `extract-i18n` CLI in `i18n-tooling` (separate change).
|
||||
- ADDED: pseudo-localization post-processor (covered by §5) wired so consumers can flip `i18n.use(pseudoLocalizationPlugin())` in test environments.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Full TypeScript-AST key extractor** — separate `i18n-tooling` change once the runtime surface stabilises.
|
||||
- **PO / XLIFF / Android XML / iOS .strings round-trip** — the `MultiFileFsBackend` (in `i18n-storage-backends`) already supports PO read via the `gettext-parser` peer; full bidirectional XLIFF / Android XML tooling is a separate change.
|
||||
- **Lingui/FBT-style hash-based stable IDs** — separate change. Requires build-time tooling and a different runtime contract.
|
||||
- **React/Vue/Solid bindings** — covered by `enterprise-react-i18n` (and equivalents for other frameworks as they land).
|
||||
- **Build-time message compilation (FormatJS-style)** — separate change once we have a Vite plugin scoped.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change is **genesis-original** in spirit: it lifts feature parity from i18next + FormatJS rather than from `../suaveplan/enterprise/i18n.md`. Every requirement below has a feature-parity citation in the table.
|
||||
|
||||
### Feature-parity table
|
||||
|
||||
| Requirement | Reference | Notes |
|
||||
|---|---|---|
|
||||
| Ergonomic `t({ count, context, defaultValue, values, ... })` | i18next `t()` | Single most-used i18n API; matching shape is critical for consumer ergonomics. |
|
||||
| Nested-key references `$t(...)` | i18next nesting | Cycle detection via depth limit (default 4). |
|
||||
| `selectordinal` node | ICU MessageFormat | Already supported by `PluralizationEngine.resolve(..., { ordinal: true })`; missing only in the parser. |
|
||||
| Typed arguments (`{x, number, currency/USD}`) | ICU MessageFormat / FormatJS | Routes through existing formatters. |
|
||||
| Apostrophe quoting | ICU MessageFormat spec | Current parser silently misparses these — it's a bug, not a feature. |
|
||||
| Tag/rich-text interpolation | i18next `<Trans>`, FormatJS `<FormattedMessage>` | Required by `enterprise-react-i18n`. |
|
||||
| `I18nPlugin` interface + lifecycle | i18next plugin model | Genesis already uses this pattern in `@suaveplan/network`, `@suaveplan/drive`. |
|
||||
| Event bus topics | i18next emit | Reuses `@suaveplan/events`. |
|
||||
| Pseudo-localization | i18next-pseudo, FormatJS pseudo | Standard layout-testing tool. |
|
||||
| `formatList`, `formatDisplayName` | `Intl.ListFormat`, `Intl.DisplayNames` | Universally expected. |
|
||||
| `formatCompact`, `formatPercent`, `formatUnit` | Intl helpers | Convenience over `formatNumber`. |
|
||||
| `Intl.Locale.weekInfo` for first-day-of-week | MDN, Chromium 99+, Node 22+ | Current Monday hardcode is a bug. |
|
||||
| `Intl.PluralRules` first | CLDR drift hardening | Hand-written rules become overrides, not source of truth. |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| OTel `i18n.translate.total` etc. wiring | `i18n-spec-conformance` declared the instruments; this change actually increments them. AGENTS.md §13 row 4. |
|
||||
| `extractKeys(source)` runtime helper | Enables a downstream CLI without locking the runtime to a specific TS-AST library. |
|
||||
| `formatSegment` / `compareLocale` | Required for non-Latin search/sort in our search packages. |
|
||||
|
||||
## Verification approach
|
||||
|
||||
Each requirement carries a `**Verified by:**` line in the spec delta.
|
||||
|
||||
- `packages/i18n/i18n/src/core/catalog/translate.test.ts` — ergonomic `t()` with count, context, defaultValue, nested refs
|
||||
- `packages/i18n/i18n/src/parser/message/message.test.ts` (extended) — selectordinal, typed args, apostrophe escape, tag nodes
|
||||
- `packages/i18n/i18n/src/parser/message/message-validate.test.ts` — `MessageParser.validate` happy/sad paths
|
||||
- `packages/i18n/i18n/src/core/plugin/plugin.test.ts` — `I18nPlugin` lifecycle, event bus topics, post-processor / detector composition
|
||||
- `packages/i18n/i18n/src/formatting/list/list.test.ts`, `display-name/display-name.test.ts`, `number/number-helpers.test.ts`
|
||||
- `packages/i18n/i18n/src/locale/segment/segment.test.ts`, `collator/collator.test.ts`
|
||||
- `packages/i18n/i18n/src/observability/metrics.spec-conformance.test.ts` — every instrument records a sample under in-memory `MeterProvider`
|
||||
|
||||
## Migration impact
|
||||
|
||||
- `MessageCatalog.t(key)` (single-arg) — backwards-compatible. Existing call sites continue to work.
|
||||
- `MessageCatalog.t(key, options)` (new) — additive.
|
||||
- `parseAcceptLanguage` casing fix — observable change for consumers that string-compared the result. No genesis consumers depend on the lowercased tag (verified by grep).
|
||||
- `PluralizationEngine` defaulting to `Intl.PluralRules` — observable for locales where the hand-written rule disagreed with CLDR. Tests pinning `Intl.PluralRules` output are added; the override registry path remains available for explicit overrides.
|
||||
- `MessageParser` apostrophe handling — observable bug fix: `it''s` formerly rendered as `it''s` and now renders as `it's`. No genesis consumers depend on the broken behaviour (verified by grep).
|
||||
|
||||
### Affected dependents
|
||||
|
||||
`grep -rl "@suaveplan/i18n" /home/ubuntu/web/genesis/packages/ --include="package.json"` — only `packages/i18n/i18n/package.json` itself. New consumer (`@suaveplan/react-i18n`) lands via its own change.
|
||||
@@ -0,0 +1,417 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: i18n (i18n-completion)
|
||||
|
||||
**Package**: `@suaveplan/i18n`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time. (See `openspec/AGENTS.md` Section 13.)
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Ergonomic translate options bag
|
||||
|
||||
`MessageCatalog.t(key, options?: TranslateOptions)` SHALL accept an optional second argument that bundles the most common translation concerns into a single call. `options` SHALL support `count: number`, `context: string`, `defaultValue: string`, `values: Record<string, unknown>`, `escapeHtml?: boolean`, and `formatters?: Record<string, ValueFormatter>`. When `count` is present, the catalog SHALL invoke `PluralizationEngine.resolve` and select the matching plural branch; when `context` is present, the catalog SHALL look up `${key}_${context}` first, falling back to `key`. The `count` value SHALL be auto-injected into `options.values` so plural strings can use `{count}` directly.
|
||||
|
||||
#### Scenario: count selects plural branch
|
||||
|
||||
- **GIVEN** catalog `{ en: { item: { one: '{count} item', other: '{count} items' } } }`
|
||||
- **WHEN** `t('item', { count: 3 })` is called
|
||||
- **THEN** the result equals `'3 items'`
|
||||
|
||||
#### Scenario: context selector falls back to base key
|
||||
|
||||
- **GIVEN** catalog `{ en: { greeting: 'Hi', greeting_male: 'Hello sir' } }`
|
||||
- **WHEN** `t('greeting', { context: 'female' })` is called
|
||||
- **THEN** the result equals `'Hi'` (greeting_female absent → falls back to base)
|
||||
|
||||
#### Scenario: defaultValue used on miss
|
||||
|
||||
- **GIVEN** catalog without key `'foo'`
|
||||
- **WHEN** `t('foo', { defaultValue: 'Bar' })` is called
|
||||
- **THEN** the result equals `'Bar'`
|
||||
|
||||
#### Scenario: values interpolated alongside count
|
||||
|
||||
- **GIVEN** catalog `{ en: { item: { one: '{name} has {count} item', other: '{name} has {count} items' } } }`
|
||||
- **WHEN** `t('item', { count: 2, values: { name: 'Alice' } })` is called
|
||||
- **THEN** the result equals `'Alice has 2 items'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/catalog/translate.test.ts::"count selects plural branch"` AND `packages/i18n/i18n/src/core/catalog/translate.test.ts::"context selector falls back to base key"` AND `packages/i18n/i18n/src/core/catalog/translate.test.ts::"defaultValue used on miss"` AND `packages/i18n/i18n/src/core/catalog/translate.test.ts::"values interpolated alongside count"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Nested-key references in source strings
|
||||
|
||||
When a source string contains `$t(other.key)` or `$t(ns:other.key)`, the catalog SHALL recursively resolve the referenced key and substitute its value in place. Cycles SHALL be detected via a maximum nesting depth of 4 (configurable via `nestingDepth` option). Exceeding the depth SHALL throw `I18nError(I18N.NESTING_DEPTH_EXCEEDED)` with `context.path` listing the chain.
|
||||
|
||||
#### Scenario: nested reference resolves
|
||||
|
||||
- **GIVEN** catalog `{ en: { common: { cancel: 'Cancel' }, dialog: { close: 'Close — $t(common:cancel)' } } }`
|
||||
- **WHEN** `t('dialog:close')` is called
|
||||
- **THEN** the result equals `'Close — Cancel'`
|
||||
|
||||
#### Scenario: cycle throws NESTING_DEPTH_EXCEEDED
|
||||
|
||||
- **GIVEN** catalog `{ en: { a: '$t(b)', b: '$t(a)' } }`
|
||||
- **WHEN** `t('a')` is called
|
||||
- **THEN** it throws `I18nError(I18N.NESTING_DEPTH_EXCEEDED)` with `context.path` containing `['a', 'b', 'a', 'b', 'a']`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/catalog/translate.test.ts::"nested reference resolves"` AND `packages/i18n/i18n/src/core/catalog/translate.test.ts::"cycle throws NESTING_DEPTH_EXCEEDED"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: ICU selectordinal node
|
||||
|
||||
`MessageParser` SHALL recognise `{var, selectordinal, one {…} two {…} few {…} other {…}}` as a node type distinct from `plural`. At render time, the renderer SHALL invoke the supplied `pluralSelect(count, 'ordinal')` callback (or `PluralizationEngine.getCategory(count, locale, true)` when wired through `MessageCatalog.t`).
|
||||
|
||||
#### Scenario: selectordinal selects 'few' for English '3'
|
||||
|
||||
- **GIVEN** message `'{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} place'`
|
||||
- **WHEN** parsed and rendered with `{ place: 3 }` under `en` locale
|
||||
- **THEN** the result equals `'3rd place'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/parser/message/message.test.ts::"selectordinal selects 'few' for English '3'"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: ICU typed-argument support
|
||||
|
||||
`MessageParser` SHALL recognise typed-argument forms `{name, type[, style]}` where `type` is one of `date`, `time`, `number`. At render time, the renderer SHALL route through the canonical `formatDate` / `formatTime` / `formatNumber` helpers from `@suaveplan/i18n/formatting/*`, threading the active locale. Style strings SHALL accept the standard ICU subset:
|
||||
|
||||
- `date`: `short`, `medium`, `long`, `full`
|
||||
- `time`: `short`, `medium`, `long`, `full`
|
||||
- `number`: `decimal`, `percent`, `currency/<ISO 4217 code>`, `compact`, `scientific`, `engineering`
|
||||
|
||||
#### Scenario: typed currency argument formats per locale
|
||||
|
||||
- **GIVEN** message `'{amount, number, currency/USD}'`
|
||||
- **WHEN** parsed and rendered with `{ amount: 1234.5 }` under `en-US` locale
|
||||
- **THEN** the result equals `'$1,234.50'`
|
||||
|
||||
#### Scenario: typed date argument formats per style
|
||||
|
||||
- **GIVEN** message `'{at, date, medium}'`
|
||||
- **WHEN** parsed and rendered with `{ at: new Date(Date.UTC(2026, 4, 4)) }` under `en-GB` locale
|
||||
- **THEN** the result equals `'4 May 2026'`
|
||||
|
||||
#### Scenario: unknown type rejects at parse time
|
||||
|
||||
- **GIVEN** message `'{x, magic, foo}'`
|
||||
- **WHEN** parsed
|
||||
- **THEN** `MessageParser.validate(message)` returns an error with code `'UNKNOWN_ARG_TYPE'` and `field === 'magic'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/parser/message/message.test.ts::"typed currency argument formats per locale"` AND `packages/i18n/i18n/src/parser/message/message.test.ts::"typed date argument formats per style"` AND `packages/i18n/i18n/src/parser/message/message-validate.test.ts::"unknown type rejects at validate"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: ICU apostrophe quoting
|
||||
|
||||
`MessageParser` SHALL implement the ICU MessageFormat apostrophe quoting rule:
|
||||
|
||||
- A standalone apostrophe followed by a `{`, `}`, or another apostrophe begins a quoted run; the quoted run ends at the next single apostrophe.
|
||||
- Two consecutive apostrophes (`''`) render as a single literal apostrophe.
|
||||
- Apostrophes outside this rule render literally.
|
||||
|
||||
#### Scenario: doubled apostrophe renders as single
|
||||
|
||||
- **GIVEN** message `"it''s here"`
|
||||
- **WHEN** parsed and rendered with `{}` values
|
||||
- **THEN** the result equals `"it's here"`
|
||||
|
||||
#### Scenario: quoted run preserves braces
|
||||
|
||||
- **GIVEN** message `"'{literal}' is {actual}"`
|
||||
- **WHEN** parsed and rendered with `{ actual: 'X' }`
|
||||
- **THEN** the result equals `'{literal} is X'`
|
||||
|
||||
#### Scenario: standalone apostrophe is literal
|
||||
|
||||
- **GIVEN** message `"don't"`
|
||||
- **WHEN** parsed and rendered
|
||||
- **THEN** the result equals `"don't"`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/parser/message/message.test.ts::"doubled apostrophe renders as single"` AND `packages/i18n/i18n/src/parser/message/message.test.ts::"quoted run preserves braces"` AND `packages/i18n/i18n/src/parser/message/message.test.ts::"standalone apostrophe is literal"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Rich-text / tag interpolation
|
||||
|
||||
`MessageParser` SHALL recognise XML-style open/close tag pairs (`<tag>...</tag>`) inside source messages and emit a `TagNode` with `name: string` and `children: MessageNode[]`. `MessageParser.format(message, values)` SHALL accept a value `name: (chunks: string) => string` to render the tag content inline. `MessageParser.formatChunks<T>(message, values, chunkValues)` SHALL return `Array<string | T>` for framework consumers, where `chunkValues[name]: (chunks: T[]) => T` (e.g. `{ bold: (chunks) => <b>{chunks}</b> }`).
|
||||
|
||||
#### Scenario: tag formats inline as string
|
||||
|
||||
- **GIVEN** message `'Hello <bold>world</bold>!'`
|
||||
- **WHEN** `format(message, { bold: (chunks) =>`**${chunks}**`})`
|
||||
- **THEN** the result equals `'Hello **world**!'`
|
||||
|
||||
#### Scenario: nested tag formats correctly
|
||||
|
||||
- **GIVEN** message `'<a>read <b>more</b> here</a>'`
|
||||
- **WHEN** `format(message, { a: (c) =>`[${c}]`, b: (c) => `*${c}*`})`
|
||||
- **THEN** the result equals `'[read *more* here]'`
|
||||
|
||||
#### Scenario: formatChunks returns mixed string + framework-node array
|
||||
|
||||
- **GIVEN** message `'Hello <bold>world</bold>!'`
|
||||
- **WHEN** `formatChunks(message, {}, { bold: (c) => ({ tag: 'b', children: c }) })`
|
||||
- **THEN** the result deep-equals `['Hello ', { tag: 'b', children: ['world'] }, '!']`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/parser/message/message.test.ts::"tag formats inline as string"` AND `packages/i18n/i18n/src/parser/message/message.test.ts::"nested tag formats correctly"` AND `packages/i18n/i18n/src/parser/message/message.test.ts::"formatChunks returns mixed array"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: I18nInstance facade and plugin lifecycle
|
||||
|
||||
The package SHALL expose `createI18n(options) → I18nInstance` that composes `MessageCatalog`, `InterpolationEngine`, `PluralizationEngine`, `MessageParser`, `LocaleResolver`, and a plugin registry. `I18nInstance.use(plugin: I18nPlugin)` SHALL register the plugin (calling `install(i18n)` synchronously or awaiting it when async). `I18nInstance.dispose()` SHALL call `dispose()` on every registered plugin in reverse-registration order.
|
||||
|
||||
#### Scenario: plugin install runs once on registration
|
||||
|
||||
- **GIVEN** an `I18nInstance` and a plugin whose `install` increments a counter
|
||||
- **WHEN** `i18n.use(plugin)` is called once
|
||||
- **THEN** the counter is 1 (not 0, not 2)
|
||||
|
||||
#### Scenario: dispose runs in reverse order
|
||||
|
||||
- **GIVEN** plugins A, B, C registered in that order, each pushing their name into a shared array on `dispose`
|
||||
- **WHEN** `i18n.dispose()` is called
|
||||
- **THEN** the shared array equals `['C', 'B', 'A']`
|
||||
|
||||
#### Scenario: duplicate plugin names rejected
|
||||
|
||||
- **GIVEN** an `I18nInstance` with a plugin named `'http-backend'` already registered
|
||||
- **WHEN** another plugin with the same name is registered
|
||||
- **THEN** it throws `I18nError(I18N.PLUGIN_ALREADY_INSTALLED)` with `context.name === 'http-backend'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/plugin/plugin.test.ts::"install runs once"` AND `packages/i18n/i18n/src/core/plugin/plugin.test.ts::"dispose runs in reverse order"` AND `packages/i18n/i18n/src/core/plugin/plugin.test.ts::"duplicate plugin name rejected"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Event bus topics
|
||||
|
||||
`I18nInstance` SHALL emit five canonical event topics via an internal `@suaveplan/events` bus exposed as `i18n.events`:
|
||||
|
||||
- `languageChanged` — `{ from: string; to: string }` — emitted by `i18n.changeLanguage(locale)`
|
||||
- `loaded` — `{ locale: string; namespace: string; backend?: string }` — emitted on every catalog `set` / `mergeMessages` / backend read
|
||||
- `missingKey` — `{ locale: string; namespace: string; key: string; defaultValue?: string }` — emitted on every miss before `MissingKeyHandler` is invoked
|
||||
- `keyAdded` — `{ locale: string; namespace: string; key: string; value: string }` — emitted on `saveMissing` / HMR / backend write-through
|
||||
- `pluralRuleAdded` — `{ locale: string }` — emitted by `PluralizationEngine.registerRule`
|
||||
|
||||
#### Scenario: changeLanguage emits languageChanged
|
||||
|
||||
- **WHEN** `i18n.changeLanguage('fr')` is called from an `en` locale
|
||||
- **THEN** the bus emits `languageChanged` with `{ from: 'en', to: 'fr' }` exactly once
|
||||
|
||||
#### Scenario: missing key emits missingKey before handler
|
||||
|
||||
- **WHEN** `t('absent.key')` is called and a `MissingKeyHandler` is registered
|
||||
- **THEN** the bus emits `missingKey` with the lookup payload AND the handler is invoked AFTER the emission
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/plugin/events.test.ts::"changeLanguage emits languageChanged"` AND `packages/i18n/i18n/src/core/plugin/events.test.ts::"missingKey emitted before handler"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: List, display-name, and number-helper formatters
|
||||
|
||||
The package SHALL expose:
|
||||
|
||||
- `formatList(values: string[], locale: string, options?: ListFormatOptions)` wrapping `Intl.ListFormat` with cached instance per `(locale, options-hash)`
|
||||
- `formatDisplayName(code: string, locale: string, options: DisplayNameOptions)` wrapping `Intl.DisplayNames`
|
||||
- `formatPercent(value: number, locale: string, options?)` — pre-bound `formatNumber({ style: 'percent' })`
|
||||
- `formatCompact(value: number, locale: string, options?)` — pre-bound `formatNumber({ notation: 'compact' })`
|
||||
- `formatUnit(value: number, unit: string, locale: string, options?)` — pre-bound `formatNumber({ style: 'unit', unit })`
|
||||
|
||||
Each function SHALL emit a sample on the relevant `i18n.format.<name>.duration_ms` histogram.
|
||||
|
||||
#### Scenario: list conjunction joins with locale-specific connector
|
||||
|
||||
- **WHEN** `formatList(['apples', 'oranges', 'bananas'], 'en-US', { type: 'conjunction' })` is called
|
||||
- **THEN** the result equals `'apples, oranges, and bananas'`
|
||||
|
||||
#### Scenario: display-name returns localised region name
|
||||
|
||||
- **WHEN** `formatDisplayName('GB', 'en-US', { type: 'region' })` is called
|
||||
- **THEN** the result equals `'United Kingdom'`
|
||||
|
||||
#### Scenario: compact notation for thousands
|
||||
|
||||
- **WHEN** `formatCompact(1234, 'en-US')` is called
|
||||
- **THEN** the result equals `'1.2K'`
|
||||
|
||||
#### Scenario: unit formatting
|
||||
|
||||
- **WHEN** `formatUnit(12, 'kilometer-per-hour', 'en-US')` is called
|
||||
- **THEN** the result equals `'12 km/h'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/list/list.test.ts::"list conjunction joins"` AND `packages/i18n/i18n/src/formatting/display-name/display-name.test.ts::"region name localised"` AND `packages/i18n/i18n/src/formatting/number/number-helpers.test.ts::"compact notation for thousands"` AND `packages/i18n/i18n/src/formatting/number/number-helpers.test.ts::"unit formatting"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Pluralization engine prefers Intl.PluralRules
|
||||
|
||||
`PluralizationEngine.getRule(locale)` SHALL select rules in this order: (1) explicitly registered override rule, (2) `Intl.PluralRules(locale)` when supported by the runtime, (3) hand-written rule registry, (4) `defaultPluralRule`. The hand-written rules SHALL remain registered and SHALL be used when `Intl.PluralRules` is unavailable. This decouples the package from CLDR drift.
|
||||
|
||||
#### Scenario: registered override wins over Intl
|
||||
|
||||
- **GIVEN** a custom rule registered for `en` that always returns `'few'`
|
||||
- **WHEN** `getRule('en')(5)` is called
|
||||
- **THEN** the result equals `'few'` (override wins, Intl skipped)
|
||||
|
||||
#### Scenario: Intl.PluralRules used when no override
|
||||
|
||||
- **GIVEN** no override registered for `pl`
|
||||
- **WHEN** `getCategory(2, 'pl')` is called on a runtime where `Intl.PluralRules` is supported
|
||||
- **THEN** the result equals `Intl.PluralRules('pl').select(2)` (i.e. `'few'`)
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/pluralization/pluralization.test.ts::"override wins over Intl"` AND `packages/i18n/i18n/src/core/pluralization/pluralization.test.ts::"Intl used when no override"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Locale-aware first-day-of-week
|
||||
|
||||
`getDayNames(locale, style?)` SHALL consult `new Intl.Locale(locale).weekInfo.firstDay` (1 = Monday, 7 = Sunday) to determine the array's starting weekday. When `weekInfo` is unavailable on the runtime (older Node, older browsers), the function SHALL fall back to Monday-start (`firstDay: 1`).
|
||||
|
||||
#### Scenario: en-US starts on Sunday
|
||||
|
||||
- **WHEN** `getDayNames('en-US', 'short')` is called on a runtime where `weekInfo` is available
|
||||
- **THEN** the first element equals `'Sun'`
|
||||
|
||||
#### Scenario: en-GB starts on Monday
|
||||
|
||||
- **WHEN** `getDayNames('en-GB', 'short')` is called
|
||||
- **THEN** the first element equals `'Mon'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/date/date.test.ts::"en-US starts on Sunday"` AND `packages/i18n/i18n/src/formatting/date/date.test.ts::"en-GB starts on Monday"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Accept-Language preserves script casing
|
||||
|
||||
`parseAcceptLanguage(header)` SHALL preserve the BCP-47 case convention of script subtags: language → lowercase, script → title-case, region → uppercase. The current implementation lowercases the entire tag and is a bug.
|
||||
|
||||
#### Scenario: zh-Hant-TW round-trips with original casing
|
||||
|
||||
- **WHEN** `parseAcceptLanguage('zh-Hant-TW;q=0.9')` is called
|
||||
- **THEN** the first entry's `code` equals `'zh-Hant-TW'` (script title-case, region upper-case, language lower-case)
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/locale/negotiation/negotiation.test.ts::"zh-Hant-TW round-trips with original casing"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Pseudo-localization post-processor
|
||||
|
||||
The package SHALL expose `pseudoLocalize(text, options?)` and a corresponding `pseudoLocalizationPlugin(options?)` that registers as a post-processor. Three modes SHALL be supported via `mode: 'accent' | 'bracket' | 'expand'`:
|
||||
|
||||
- `accent` (default): replaces ASCII letters with diacritic equivalents (`Welcome` → `Wéłçömé`)
|
||||
- `bracket`: surrounds the string with `[!! ... !!]` markers
|
||||
- `expand`: pads the string by ~30% with extra characters to test layout overflow
|
||||
|
||||
#### Scenario: accent mode produces diacritic equivalents
|
||||
|
||||
- **WHEN** `pseudoLocalize('Welcome', { mode: 'accent' })` is called
|
||||
- **THEN** the result is non-empty AND every original ASCII letter is replaced with a non-ASCII counterpart
|
||||
|
||||
#### Scenario: bracket mode surrounds the string
|
||||
|
||||
- **WHEN** `pseudoLocalize('Welcome', { mode: 'bracket' })` is called
|
||||
- **THEN** the result equals `'[!! Welcome !!]'`
|
||||
|
||||
#### Scenario: post-processor plugin transforms t() output
|
||||
|
||||
- **GIVEN** an `I18nInstance` with `pseudoLocalizationPlugin({ mode: 'bracket' })` registered
|
||||
- **WHEN** `t('greeting')` returns `'Welcome'` from the catalog
|
||||
- **THEN** the final return value equals `'[!! Welcome !!]'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/post-processors/pseudo-localize.test.ts::"accent mode produces diacritic equivalents"` AND `packages/i18n/i18n/src/post-processors/pseudo-localize.test.ts::"bracket mode surrounds string"` AND `packages/i18n/i18n/src/post-processors/pseudo-localize.test.ts::"plugin transforms t() output"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Segmenter and collator wrappers
|
||||
|
||||
The package SHALL expose `formatSegment(text, locale, granularity?)` returning an array of `{ segment: string; index: number; isWordLike?: boolean }` via `Intl.Segmenter`, and `compareLocale(a, b, locale, options?)` wrapping `Intl.Collator` with cached instance per `(locale, options-hash)`.
|
||||
|
||||
#### Scenario: word segmentation in Japanese
|
||||
|
||||
- **WHEN** `formatSegment('東京は晴れです', 'ja-JP', 'word')` is called on a runtime with `Intl.Segmenter`
|
||||
- **THEN** the result has at least one segment with `isWordLike: true` and `segment === '東京'`
|
||||
|
||||
#### Scenario: collator sorts case-insensitively
|
||||
|
||||
- **WHEN** `['B', 'a', 'C'].sort((a, b) => compareLocale(a, b, 'en-US', { sensitivity: 'base' }))`
|
||||
- **THEN** the result equals `['a', 'B', 'C']`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/locale/segment/segment.test.ts::"word segmentation in Japanese"` AND `packages/i18n/i18n/src/locale/collator/collator.test.ts::"sorts case-insensitively"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: OTel meter instruments wired into production paths
|
||||
|
||||
Every existing instrument declared in `src/observability/metrics.ts` (`i18n.translate.total`, `i18n.translate.duration_ms`, `i18n.locale.resolve.total`) SHALL be incremented / observed from the relevant production code paths. Two additional instruments SHALL be added:
|
||||
|
||||
- Histogram `i18n.interpolation.duration_ms` — emitted from `InterpolationEngine.render` and `MessageParser.format`
|
||||
- Counter `i18n.missing_key.total` — labels: `locale`, `namespace`; incremented from `MessageCatalog.get` whenever the lookup falls through to the missing-key handler or returns `undefined`
|
||||
|
||||
#### Scenario: get records translate.total{outcome=hit}
|
||||
|
||||
- **WHEN** `MessageCatalog.get('present.key')` resolves a value with the in-memory `MeterProvider` registered
|
||||
- **THEN** exactly one sample is recorded under `i18n.translate.total` with attribute `outcome: 'hit'` AND one sample under `i18n.translate.duration_ms`
|
||||
|
||||
#### Scenario: locale resolve records strategy
|
||||
|
||||
- **WHEN** `LocaleResolver.resolve('fr-FR')` returns via `'language'` strategy
|
||||
- **THEN** `i18n.locale.resolve.total` records a sample with attribute `strategy: 'language'`
|
||||
|
||||
#### Scenario: missing key increments counter
|
||||
|
||||
- **WHEN** `MessageCatalog.get('absent.key')` returns `undefined`
|
||||
- **THEN** `i18n.missing_key.total` records a sample with `{ locale: 'en', namespace: '' }`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/observability/metrics.spec-conformance.test.ts::"translate.total records hit"` AND `packages/i18n/i18n/src/observability/metrics.spec-conformance.test.ts::"locale.resolve.total records strategy"` AND `packages/i18n/i18n/src/observability/metrics.spec-conformance.test.ts::"missing_key.total increments on miss"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Missing-key reporter plugin
|
||||
|
||||
The package SHALL expose `createMissingKeyReporter(options?)` returning an `I18nPlugin` that subscribes to the `missingKey` event. By default it logs at `warn` via `@suaveplan/logger`. When `options.onMissing` is supplied, the plugin SHALL invoke it with the event payload. When the catalog is configured with `saveMissing: true` and a backend that implements `save`, the reporter MAY (opt-in via `persistMissing: true`) call `catalog.saveMissing(locale, key, defaultValue)`.
|
||||
|
||||
#### Scenario: missing key logs warn by default
|
||||
|
||||
- **GIVEN** a logger spy and `i18n.use(createMissingKeyReporter({ logger }))`
|
||||
- **WHEN** `t('absent.key')` is called
|
||||
- **THEN** the logger received exactly one `warn` call mentioning `'absent.key'`
|
||||
|
||||
#### Scenario: persistMissing routes to backend
|
||||
|
||||
- **GIVEN** `saveMissing: true`, a `MemoryBackend`, and `createMissingKeyReporter({ persistMissing: true })`
|
||||
- **WHEN** `t('new.key', { defaultValue: 'New' })` is called for a missing key
|
||||
- **THEN** the backend's `save` was called once with the merged record containing `'new.key': 'New'`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/post-processors/missing-key-reporter.test.ts::"warn logged by default"` AND `packages/i18n/i18n/src/post-processors/missing-key-reporter.test.ts::"persistMissing routes to backend"`
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### I18N-05 — Pluralization engine contract
|
||||
|
||||
`PluralizationEngine` MUST:
|
||||
|
||||
- Maintain a `PluralRuleRegistry` that callers can write to via `registerRule(locale, rule)`. Built-in hand-written rules for Arabic, Chinese, English, French, German, Polish, Russian, Spanish, Welsh, and `defaultPluralRule` SHALL remain registered as overrides.
|
||||
- `.getRule(locale)` selects in this order: (1) explicit override registered via `registerRule`, (2) `Intl.PluralRules(locale)` when the runtime supports it, (3) the hand-written rule registry, (4) `defaultPluralRule`.
|
||||
- `.resolve(count, locale, messages, opts?)` MUST call the resolved rule, fall back to the base-language rule (strip region), then fall back to `defaultPluralRule`; return `PluralResolveResult { category: PluralCategory; value: string }`.
|
||||
- `PluralCategory` MUST be `'zero' | 'one' | 'two' | 'few' | 'many' | 'other'`.
|
||||
- In strict mode, throw `I18nError(I18N.PLURAL_RULE_NOT_FOUND)` when no rule exists for the locale and its base language and `Intl.PluralRules` is unavailable.
|
||||
|
||||
#### Scenario: Intl.PluralRules used when no override
|
||||
|
||||
- **GIVEN** no override registered for `'pl'`
|
||||
- **WHEN** `getCategory(2, 'pl')` is called
|
||||
- **THEN** the result equals `Intl.PluralRules('pl').select(2)` (`'few'`)
|
||||
|
||||
#### Scenario: hand-written rule used when Intl unavailable
|
||||
|
||||
- **GIVEN** a stubbed runtime where `Intl.PluralRules` throws on construction
|
||||
- **WHEN** `getCategory(2, 'pl')` is called
|
||||
- **THEN** the result is computed by the registered `polishPlural` function
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/pluralization/pluralization.test.ts::"Intl used when no override"` AND `packages/i18n/i18n/src/core/pluralization/pluralization.test.ts::"hand-written used when Intl unavailable"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
176
openspec/changes/archive/2026-05-04-i18n-completion/tasks.md
Normal file
176
openspec/changes/archive/2026-05-04-i18n-completion/tasks.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# Tasks — i18n completion (ergonomic t, full ICU, plugin surface, Intl wrappers)
|
||||
|
||||
> Every checkbox MUST reflect work actually done in this change. Do not retroactively tick.
|
||||
|
||||
## Sequencing
|
||||
|
||||
This change SHOULD land **after** `i18n-storage-backends` (the `Backend` interface is referenced by `createMissingKeyReporter` and the `loaded` event topic). It can land before or after `i18n-formatters` — the `formatList` / `formatDisplayName` / number-helper additions here are independent of `formatNumber` / `formatRelativeTime`.
|
||||
|
||||
## 1. Spec authoring
|
||||
|
||||
- [x] 1.1 Read `openspec/specs/i18n/spec.md` end-to-end (canonical capability spec)
|
||||
- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
|
||||
- [x] 1.3 Confirm the in-flight `i18n-storage-backends` + `i18n-formatters` + `i18n-spec-conformance` proposals do not conflict with this delta (especially the `MessageCatalog` constructor surface and OTel meter naming)
|
||||
- [x] 1.4 `openspec change validate i18n-completion` exits with no errors
|
||||
|
||||
## 2. Ergonomic t() and TranslateOptions
|
||||
|
||||
- [x] 2.1 Define `TranslateOptions` and `PluralKey` in `packages/i18n/i18n/src/core/catalog/translate.types.ts`
|
||||
- [x] 2.2 Implement `MessageCatalog.t(key, options?)` accepting the options bag (≤300 lines after refactor)
|
||||
- [x] 2.3 Implement `count` → `PluralizationEngine.resolve` → branch selection with `count` auto-injected into `values`
|
||||
- [x] 2.4 Implement `context` → `${key}_${context}` lookup with fallback to base
|
||||
- [x] 2.5 Implement `defaultValue` fallback on miss
|
||||
- [x] 2.6 Implement nested-key references `$t(other.key)` / `$t(ns:key)` with depth limit (default 4) and cycle detection
|
||||
- [x] 2.7 Add `I18N.NESTING_DEPTH_EXCEEDED` error code via `defineCodes`
|
||||
- [x] 2.8 `t.plural(key, count, values?)` shortcut helper
|
||||
- [x] 2.9 `translate.test.ts` — count, context, defaultValue, nested refs (success + cycle), shortcut helper
|
||||
- [x] 2.10 Sibling `translate.md`
|
||||
|
||||
## 3. ICU MessageFormat — selectordinal
|
||||
|
||||
- [x] 3.1 Add `SelectOrdinalNode` to `MessageNode` discriminated union
|
||||
- [x] 3.2 Implement `parsePluralChoices(...)` branching for `selectordinal` (separate path so `plural` and `selectordinal` carry distinct `type` discriminants)
|
||||
- [x] 3.3 Render path calls `pluralSelect(count, 'ordinal')` (or, when wired through `MessageCatalog.t`, `PluralizationEngine.getCategory(count, locale, true)`)
|
||||
- [x] 3.4 `message.test.ts` — selectordinal selects `'few'` for English `3`, `'one'` for `1`, `'two'` for `2`
|
||||
|
||||
## 4. ICU MessageFormat — typed arguments
|
||||
|
||||
- [x] 4.1 Implement `parseTypedArg(message, start, name)` for `{name, date|time|number, style?}` shapes
|
||||
- [x] 4.2 Add `TypedArgumentNode` to `MessageNode` discriminated union with `type: 'date' | 'time' | 'number'` and `style: string`
|
||||
- [x] 4.3 Render path calls `formatDate` / `formatTime` / `formatNumber` from `@suaveplan/i18n/formatting/*`
|
||||
- [x] 4.4 Number style parsing: `decimal`, `percent`, `currency/<ISO>`, `compact`, `scientific`, `engineering`
|
||||
- [x] 4.5 Date/time style parsing: `short`, `medium`, `long`, `full`
|
||||
- [x] 4.6 `message.test.ts` — typed currency, typed date, typed percent, typed compact
|
||||
- [x] 4.7 `MessageParser.validate(message)` rejects unknown `type` values
|
||||
|
||||
## 5. ICU MessageFormat — apostrophe quoting
|
||||
|
||||
- [x] 5.1 Pre-process the source message in `parseIcu` to handle the three apostrophe rules
|
||||
- [x] 5.2 `''` → single literal `'`
|
||||
- [x] 5.3 `'<followed by`{`,`}`, or another`'`>...'` → quoted run, content is literal until matching `'`
|
||||
- [x] 5.4 Standalone `'` (any other context) → literal apostrophe
|
||||
- [x] 5.5 `message.test.ts` — `it''s here`, `'{literal}' is X`, `don't`
|
||||
|
||||
## 6. ICU MessageFormat — tag interpolation
|
||||
|
||||
- [x] 6.1 Add `TagNode { type: 'tag'; name: string; children: MessageNode[] }` to `MessageNode`
|
||||
- [x] 6.2 `parseIcu` recognises `<name>...</name>` pairs; nested tags supported
|
||||
- [x] 6.3 Implement `MessageParser.format(message, values)` where a value `name: (chunks: string) => string` renders the tag inline
|
||||
- [x] 6.4 Implement `MessageParser.formatChunks<T>(message, values, chunkValues)` returning `Array<string | T>` — the React-friendly path
|
||||
- [x] 6.5 `extractVariables` skips tag names (they're not interpolation variables)
|
||||
- [x] 6.6 `message.test.ts` — inline string tag, nested tags, formatChunks mixed array
|
||||
- [x] 6.7 Update `message.md` with the rich-text section and a React example referencing `@suaveplan/react-i18n`
|
||||
|
||||
## 7. MessageParser.validate
|
||||
|
||||
- [x] 7.1 Implement `validate(message): ValidationResult` returning `{ ok: true } | { ok: false; errors: ValidationError[] }`
|
||||
- [x] 7.2 Detect: unbalanced braces, unbalanced apostrophe quoted runs, missing `other` branch in `plural` / `select` / `selectordinal`, unknown typed-argument type, unknown plural categories
|
||||
- [x] 7.3 `message-validate.test.ts` — happy path + each error case
|
||||
|
||||
## 8. I18nInstance facade and plugin lifecycle
|
||||
|
||||
- [x] 8.1 Define `I18nPlugin`, `I18nInstance`, `PluginRegistry` in `src/core/plugin/plugin.types.ts`
|
||||
- [x] 8.2 Implement `createI18n(options) → I18nInstance` composing existing engines + plugin registry
|
||||
- [x] 8.3 `i18n.use(plugin)` — sync + async install; reject duplicate names with `I18N.PLUGIN_ALREADY_INSTALLED`
|
||||
- [x] 8.4 `i18n.dispose()` — reverse-order plugin disposal
|
||||
- [x] 8.5 `i18n.changeLanguage(locale)` — emits `languageChanged`
|
||||
- [x] 8.6 Add `I18N.PLUGIN_ALREADY_INSTALLED` error code via `defineCodes`
|
||||
- [x] 8.7 `plugin.test.ts` — install once, dispose order, duplicate rejection
|
||||
- [x] 8.8 Sibling `plugin.md` walks through the plugin contract with three example plugins
|
||||
|
||||
## 9. Event bus topics
|
||||
|
||||
- [x] 9.1 Wire `@suaveplan/events` instance as `i18n.events`
|
||||
- [x] 9.2 Emit `languageChanged` from `changeLanguage`
|
||||
- [x] 9.3 Emit `loaded` from `MessageCatalog.set` / `mergeMessages` and from backend reads
|
||||
- [x] 9.4 Emit `missingKey` from `MessageCatalog.get` BEFORE invoking `MissingKeyHandler`
|
||||
- [x] 9.5 Emit `keyAdded` from `saveMissing` and HMR paths
|
||||
- [x] 9.6 Emit `pluralRuleAdded` from `PluralizationEngine.registerRule`
|
||||
- [x] 9.7 `events.test.ts` — every topic emits with the documented payload shape
|
||||
|
||||
## 10. List + display-name + number-helper formatters
|
||||
|
||||
- [x] 10.1 Implement `formatList(values, locale, options?)` at `src/formatting/list/list.ts` with cache + Zod options + OTel histogram
|
||||
- [x] 10.2 Implement `formatDisplayName(code, locale, options)` at `src/formatting/display-name/display-name.ts`
|
||||
- [x] 10.3 Implement `formatPercent`, `formatCompact`, `formatUnit` at `src/formatting/number/number-helpers.ts` — pre-bound `formatNumber` calls
|
||||
- [x] 10.4 `list.test.ts`, `display-name.test.ts`, `number-helpers.test.ts` — happy paths + Intl rejection mapping
|
||||
- [x] 10.5 Sibling `.md` for each
|
||||
- [x] 10.6 Subpath exports `./formatting/list` and `./formatting/display-name` in `package.json`
|
||||
|
||||
## 11. Pluralization Intl-first refactor
|
||||
|
||||
- [x] 11.1 Refactor `PluralizationEngine.getRule` to prefer override → `Intl.PluralRules` → hand-written → default
|
||||
- [x] 11.2 Hand-written rules remain registered (they're now overrides for runtimes lacking `Intl.PluralRules`)
|
||||
- [x] 11.3 `pluralization.test.ts` — override wins, Intl used when no override, hand-written used when Intl missing (stub `Intl.PluralRules` throw)
|
||||
|
||||
## 12. Locale-aware first-day-of-week
|
||||
|
||||
- [x] 12.1 Refactor `getDayNames(locale, style?)` to use `new Intl.Locale(locale).weekInfo.firstDay` when available
|
||||
- [x] 12.2 Fall back to Monday-start when `weekInfo` is undefined or throws
|
||||
- [x] 12.3 `date.test.ts` — `en-US` → Sunday, `en-GB` → Monday, fallback path
|
||||
|
||||
## 13. Accept-Language script casing
|
||||
|
||||
- [x] 13.1 Refactor `parseAcceptLanguage` to preserve script title-case + region upper-case + language lower-case
|
||||
- [x] 13.2 `negotiation.test.ts` — `zh-Hant-TW` round-trips with original casing; `EN-US;q=0.9` parses to `en-US`
|
||||
|
||||
## 14. Pseudo-localization
|
||||
|
||||
- [x] 14.1 Implement `pseudoLocalize(text, options?)` at `src/post-processors/pseudo-localize.ts` with three modes
|
||||
- [x] 14.2 Implement `pseudoLocalizationPlugin(options?)` returning an `I18nPlugin` that registers as a post-processor
|
||||
- [x] 14.3 `pseudo-localize.test.ts` — accent, bracket, expand modes; plugin transforms `t()` output
|
||||
|
||||
## 15. Segmenter and collator wrappers
|
||||
|
||||
- [x] 15.1 Implement `formatSegment(text, locale, granularity?)` at `src/locale/segment/segment.ts`
|
||||
- [x] 15.2 Implement `compareLocale(a, b, locale, options?)` at `src/locale/collator/collator.ts` with cache
|
||||
- [x] 15.3 `segment.test.ts`, `collator.test.ts` — non-Latin scripts (Japanese word segmentation, Arabic case-insensitive sort)
|
||||
|
||||
## 16. OTel instrumentation wiring
|
||||
|
||||
- [x] 16.1 Wire `i18n.translate.total{outcome,locale}` increment in `MessageCatalog.get`
|
||||
- [x] 16.2 Wire `i18n.translate.duration_ms{locale}` histogram in `MessageCatalog.get`
|
||||
- [x] 16.3 Wire `i18n.locale.resolve.total{strategy,locale}` increment in `LocaleResolver.resolve` and `negotiateLocale`
|
||||
- [x] 16.4 Add `i18n.interpolation.duration_ms` histogram and emit from `InterpolationEngine.render` and `MessageParser.format`
|
||||
- [x] 16.5 Add `i18n.missing_key.total{locale,namespace}` counter; increment from `MessageCatalog.get` on miss before handler invocation
|
||||
- [x] 16.6 `metrics.spec-conformance.test.ts` — every instrument records a sample under in-memory `MeterProvider`; assert exact attributes
|
||||
|
||||
## 17. Missing-key reporter plugin
|
||||
|
||||
- [x] 17.1 Implement `createMissingKeyReporter(options?)` returning an `I18nPlugin`
|
||||
- [x] 17.2 Default behaviour: log `warn` via `@suaveplan/logger` (peer; no-op when absent)
|
||||
- [x] 17.3 `onMissing(payload)` callback option
|
||||
- [x] 17.4 `persistMissing: true` opt-in routing to `catalog.saveMissing` (requires `i18n-storage-backends` `Backend` with `save`)
|
||||
- [x] 17.5 `missing-key-reporter.test.ts` — warn-by-default, callback, persistMissing path
|
||||
|
||||
## 18. Wiring and exports
|
||||
|
||||
- [x] 18.1 Add `@suaveplan/events workspace:^` and `@suaveplan/logger workspace:^` (peer-optional for the reporter) to `package.json`
|
||||
- [x] 18.2 Update `src/index.ts` to export `createI18n`, `I18nInstance`, `I18nPlugin`, `pseudoLocalize`, `formatList`, `formatDisplayName`, `formatPercent`, `formatCompact`, `formatUnit`, `formatSegment`, `compareLocale`, `createMissingKeyReporter`, `pseudoLocalizationPlugin`
|
||||
- [x] 18.3 Add subpath exports for `./post-processors`, `./formatting/list`, `./formatting/display-name`, `./formatting/number/number-helpers`, `./locale/segment`, `./locale/collator`, `./plugin`
|
||||
- [x] 18.4 Update root `README.md` `## Quick Start` with an `I18nInstance` + plugin example
|
||||
- [x] 18.5 Update `## Modules` table with every new co-located `.md`
|
||||
|
||||
## 19. Pre-archive verification (the 5-gate triple)
|
||||
|
||||
- [x] 19.1 `bun run check` — Biome 0/0/0 across the monorepo
|
||||
- [x] 19.2 `bunx turbo lint typecheck test --filter=@suaveplan/i18n` — green
|
||||
- [x] 19.3 `bunx turbo test:coverage --filter=@suaveplan/i18n` — 100/100/100/100
|
||||
- [x] 19.4 `bun scripts/openspec-conformance.ts @suaveplan/i18n` — exit 0
|
||||
- [x] 19.5 `bunx turbo build --filter=@suaveplan/i18n` — green
|
||||
|
||||
## 20. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
||||
|
||||
- [x] 20.1 Generics threaded; `expectTypeOf` assertions on `TranslateOptions['count']` narrowing, `MessageNode` discriminant
|
||||
- [x] 20.2 Zod schemas wired at every public boundary (`TranslateOptionsSchema`, `ListFormatOptionsSchema`, `DisplayNameOptionsSchema`, `PseudoLocalizeOptionsSchema`)
|
||||
- [x] 20.3 New error codes (`NESTING_DEPTH_EXCEEDED`, `PLUGIN_ALREADY_INSTALLED`) thrown from at least one production path
|
||||
- [x] 20.4 Strict-mode tested: cycle in nested refs, plugin duplicate, ICU validate failure
|
||||
- [x] 20.5 OTel histograms / counters emitted from production paths and asserted with a real in-memory `MeterProvider`
|
||||
- [x] 20.6 Lifecycle dedup: `changeLanguage` to same locale is a no-op (no event); plugin install / dispose idempotent
|
||||
- [x] 20.7 No retroactive tick — every box reflects work done in this change
|
||||
|
||||
## 21. Archive
|
||||
|
||||
- [x] 21.1 Fold spec delta into `openspec/specs/i18n/spec.md`
|
||||
- [x] 21.2 Move `openspec/changes/i18n-completion/` → `openspec/archive/<yyyy-mm-dd>-i18n-completion/`
|
||||
- [x] 21.3 Refresh `MANIFEST.md` if dep set changed (`@suaveplan/events`, optional `@suaveplan/logger`)
|
||||
@@ -0,0 +1,72 @@
|
||||
# i18n number and relative-time formatters
|
||||
|
||||
**Package**: `@suaveplan/i18n`
|
||||
**Status**: PROPOSED
|
||||
**Type**: feature + spec-conformance
|
||||
|
||||
## Why
|
||||
|
||||
`@suaveplan/i18n` currently exports only the `currency` and `date` modules from `src/formatting/index.ts` (`packages/i18n/i18n/src/formatting/index.ts` L1-L2). The upstream package ships two additional formatters — `NumberFormatter` and `RelativeTimeFormatter` — that wrap `Intl.NumberFormat` / `Intl.RelativeTimeFormat` with consistent option handling, locale validation, and structured error reporting. Without them, downstream consumers (drive UI, network admin pages, suppression dashboards) re-implement the same `Intl` wiring with subtle differences in fraction-digit clamping, currency-display defaults, and unit selection. Both legacy modules already exist at upstream parity (`packages/universal/i18n/src/formatting/number/number.ts` 119 L; `packages/universal/i18n/src/formatting/relative-time/relative-time.ts` 130 L) and pass the genesis quality bar — porting them closes the parity gap before consumers fork.
|
||||
|
||||
## What changes
|
||||
|
||||
### `@suaveplan/i18n`
|
||||
|
||||
- ADDED: `NumberFormatter` class — `format(value, locale, options?)` with `style: 'decimal' | 'percent' | 'currency'`, `currency`, `currencyDisplay`, `minimumFractionDigits`, `maximumFractionDigits`, `useGrouping`, `notation`, `signDisplay`. Validates options through a Zod schema; throws `I18nError` with code `I18N.INVALID_FORMATTER_OPTIONS` on rejection. Caches the underlying `Intl.NumberFormat` per (locale, options-hash) pair to amortise construction cost.
|
||||
- ADDED: `formatNumber(value, locale, options?)` standalone helper — pure-function wrapper around `NumberFormatter` for one-off calls.
|
||||
- ADDED: `RelativeTimeFormatter` class — `format(deltaMs, locale, options?)` with auto-unit selection (seconds → minutes → hours → days → weeks → months → years), `numeric: 'always' | 'auto'`, `style: 'long' | 'short' | 'narrow'`. Auto-selects the largest unit whose absolute value ≥ 1; threshold table mirrors upstream `relative-time.ts` L40-L96.
|
||||
- ADDED: `formatRelativeTime(deltaMs, locale, options?)` standalone helper.
|
||||
- ADDED: `NumberFormatterOptions`, `NumberFormatterStyle`, `NumberFormatterCacheKey`, `RelativeTimeFormatterOptions`, `RelativeTimeUnit`, `RelativeTimeUnitSelection` types.
|
||||
- ADDED: `NumberFormatterOptionsSchema` and `RelativeTimeFormatterOptionsSchema` Zod schemas.
|
||||
- ADDED: `I18N.INVALID_FORMATTER_OPTIONS` and `I18N.UNSUPPORTED_LOCALE` error codes registered via `defineCodes`.
|
||||
- MODIFIED: `src/formatting/index.ts` — re-exports the two new modules alongside `currency` and `date`.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **List formatting** (`Intl.ListFormat`) — separate change once `number` and `relative-time` ship and prove the formatter-cache pattern.
|
||||
- **Display-name formatting** (`Intl.DisplayNames`) — separate change; depends on locale-data plumbing not yet wired in genesis.
|
||||
- **Plural-rule integration into `RelativeTimeFormatter`** — `Intl.RelativeTimeFormat` already pluralises internally; manual integration with `@suaveplan/i18n` plural rules is unnecessary and adds risk of double-pluralisation.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/i18n.md` and the upstream package source.
|
||||
|
||||
| Requirement | Source file | Source lines | Notes |
|
||||
|---|---|---|---|
|
||||
| `NumberFormatter` class | `packages/universal/i18n/src/formatting/number/number.ts` | L1-L119 | Verbatim port; thread `I18nError` through |
|
||||
| `formatNumber` helper | `packages/universal/i18n/src/formatting/number/number.ts` | L101-L119 | Verbatim |
|
||||
| `NumberFormatterOptions`, `NumberFormatterStyle` types | `packages/universal/i18n/src/formatting/number/number.types.ts` | L1-L17 | Verbatim |
|
||||
| `RelativeTimeFormatter` class | `packages/universal/i18n/src/formatting/relative-time/relative-time.ts` | L1-L130 | Verbatim port; thresholds at L40-L96 |
|
||||
| `formatRelativeTime` helper | `packages/universal/i18n/src/formatting/relative-time/relative-time.ts` | L110-L130 | Verbatim |
|
||||
| `RelativeTimeFormatterOptions`, `RelativeTimeUnit` types | `packages/universal/i18n/src/formatting/relative-time/relative-time.types.ts` | L1-L23 | Verbatim |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| `NumberFormatterOptionsSchema` / `RelativeTimeFormatterOptionsSchema` Zod schemas | AGENTS.md §13 row 2 ("Zod schemas wired at every declared boundary"). Upstream uses runtime `typeof` guards. |
|
||||
| `I18N.INVALID_FORMATTER_OPTIONS` / `I18N.UNSUPPORTED_LOCALE` error codes | AGENTS.md §13 row 3 ("every error code thrown by at least one production path"). Upstream throws plain `Error`. |
|
||||
| Per-(locale, options) `Intl.NumberFormat` / `Intl.RelativeTimeFormat` cache | Performance. Constructing `Intl.*` is ~50× slower than calling `format()`; without a cache the pattern goes quadratic on dashboards rendering hundreds of values. Not in upstream. |
|
||||
|
||||
## Verification approach
|
||||
|
||||
Each requirement carries a `**Verified by:**` line in the spec delta.
|
||||
|
||||
- `packages/i18n/i18n/src/formatting/number/number.test.ts` — covers `Decimal/percent/currency formatting`, `Fraction-digit clamping`, `Cache reuse`
|
||||
- `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts` — pins Zod schema rejection, error-code emission, and `expectTypeOf` assertions on `NumberFormatterStyle`
|
||||
- `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts` — covers `Auto-unit selection`, `Style and numeric overrides`, `Negative deltas`
|
||||
- `packages/i18n/i18n/src/formatting/relative-time/relative-time.spec-conformance.test.ts` — pins Zod schema rejection, unsupported-locale fallback, and OTel histogram emission
|
||||
|
||||
## Impact
|
||||
|
||||
### Affected dependents
|
||||
|
||||
Run `bunx turbo ls --filter=...@suaveplan/i18n` to enumerate. Genesis grep result:
|
||||
|
||||
- No dependents (verified by `grep -rl "@suaveplan/i18n" /home/ubuntu/web/genesis/packages/ --include="package.json"` → only `packages/i18n/i18n/package.json` itself).
|
||||
|
||||
Pure additive change — existing `formatting/currency` and `formatting/date` re-exports unchanged.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only. Callers that already import `formatCurrency` / `formatDate` from `@suaveplan/i18n/formatting` are unaffected. New consumers can import `formatNumber` / `formatRelativeTime` from the same root or from the per-feature subpaths `@suaveplan/i18n/formatting/number/number` and `@suaveplan/i18n/formatting/relative-time/relative-time`.
|
||||
@@ -0,0 +1,143 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: i18n (i18n-formatters)
|
||||
|
||||
**Package**: `@suaveplan/i18n`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time. (See `openspec/AGENTS.md` Section 13.)
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Number formatting with style and currency support
|
||||
|
||||
The package SHALL expose a `NumberFormatter` class and a `formatNumber(value, locale, options?)` standalone helper that wrap `Intl.NumberFormat`. The formatter SHALL support `style: 'decimal' | 'percent' | 'currency'`, `currency` (ISO 4217 code), `currencyDisplay` (`'symbol' | 'code' | 'name' | 'narrowSymbol'`), `minimumFractionDigits`, `maximumFractionDigits`, `useGrouping`, `notation` (`'standard' | 'scientific' | 'engineering' | 'compact'`), and `signDisplay`. Options SHALL be validated through `NumberFormatterOptionsSchema` at construction.
|
||||
|
||||
#### Scenario: decimal style produces a grouped number
|
||||
|
||||
- **WHEN** `formatNumber(1234567.89, 'en-US', { style: 'decimal', maximumFractionDigits: 2 })` is called
|
||||
- **THEN** the result equals `"1,234,567.89"`
|
||||
|
||||
#### Scenario: currency style honours `currencyDisplay`
|
||||
|
||||
- **WHEN** `formatNumber(42, 'en-GB', { style: 'currency', currency: 'GBP', currencyDisplay: 'code' })` is called
|
||||
- **THEN** the result contains the substring `"GBP"` (not the `£` glyph)
|
||||
|
||||
#### Scenario: percent style multiplies by 100
|
||||
|
||||
- **WHEN** `formatNumber(0.255, 'en-US', { style: 'percent', maximumFractionDigits: 1 })` is called
|
||||
- **THEN** the result equals `"25.5%"`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/number/number.test.ts::"formats decimals with grouping in en-US"` AND `packages/i18n/i18n/src/formatting/number/number.test.ts::"formats currency with currencyDisplay code"` AND `packages/i18n/i18n/src/formatting/number/number.test.ts::"formats percent by multiplying by 100"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: NumberFormatter validates options via Zod
|
||||
|
||||
The package SHALL validate every `NumberFormatterOptions` object through `NumberFormatterOptionsSchema` (Zod). Unknown styles, negative fraction digits, fraction-digit inversions (`min > max`), and unsupported locale strings SHALL be rejected with `I18nError`.
|
||||
|
||||
#### Scenario: unknown style rejected
|
||||
|
||||
- **WHEN** `new NumberFormatter({ style: 'magic' } as never)` is constructed
|
||||
- **THEN** it throws `I18nError` with code `I18N.INVALID_FORMATTER_OPTIONS` and `context.field === "style"`
|
||||
|
||||
#### Scenario: unsupported locale surfaces structured error
|
||||
|
||||
- **WHEN** `formatNumber(1, 'xx-INVALID-LOCALE-1234', {})` is called
|
||||
- **THEN** it throws `I18nError` with code `I18N.UNSUPPORTED_LOCALE` (the underlying `Intl.NumberFormat` `RangeError` is mapped, not propagated)
|
||||
|
||||
#### Scenario: fraction-digit inversion rejected
|
||||
|
||||
- **WHEN** options carry `{ minimumFractionDigits: 4, maximumFractionDigits: 2 }`
|
||||
- **THEN** Zod rejection produces `I18N.INVALID_FORMATTER_OPTIONS` with `context.field === "fractionDigits"`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts::"rejects unknown style with INVALID_FORMATTER_OPTIONS"` AND `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts::"maps Intl RangeError to UNSUPPORTED_LOCALE"` AND `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts::"rejects fraction-digit inversion"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: NumberFormatter caches `Intl.NumberFormat` instances
|
||||
|
||||
The package SHALL cache the underlying `Intl.NumberFormat` keyed by (locale, canonicalised options hash). Repeat calls with the same key SHALL reuse the cached instance and emit the OTel counter `i18n.format.cache_hit` with attribute `formatter="number"`.
|
||||
|
||||
#### Scenario: cache reused on identical key
|
||||
|
||||
- **WHEN** `formatNumber(1, 'en-US', { style: 'decimal' })` is called twice
|
||||
- **THEN** the second call increments `i18n.format.cache_hit` by exactly 1
|
||||
|
||||
#### Scenario: distinct options produce distinct cache entries
|
||||
|
||||
- **WHEN** the same locale is called with `{ style: 'decimal' }` then `{ style: 'percent' }`
|
||||
- **THEN** both calls miss the cache; `i18n.format.cache_hit` does not increment
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts::"reuses cached Intl.NumberFormat on identical key"` AND `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts::"does not reuse cache across distinct options"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Relative-time formatting with auto-unit selection
|
||||
|
||||
The package SHALL expose a `RelativeTimeFormatter` class and a `formatRelativeTime(deltaMs, locale, options?)` helper that wrap `Intl.RelativeTimeFormat`. When `options.unit` is omitted, the formatter SHALL auto-select the largest unit whose absolute value is ≥ 1 from the ordered set `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `years`. Threshold boundaries match upstream `relative-time.ts` L40-L96 (60s, 60m, 24h, 7d, 4.345w, 12mo).
|
||||
|
||||
#### Scenario: 30 seconds selects "seconds" unit
|
||||
|
||||
- **WHEN** `formatRelativeTime(30_000, 'en-US')` is called
|
||||
- **THEN** the result contains `"second"` (e.g. `"in 30 seconds"`) AND not `"minute"`
|
||||
|
||||
#### Scenario: 90 seconds rolls over to "minutes" unit
|
||||
|
||||
- **WHEN** `formatRelativeTime(90_000, 'en-US')` is called
|
||||
- **THEN** the selected unit is `"minutes"` and the value is `2` (rounded)
|
||||
|
||||
#### Scenario: negative delta produces past-tense phrasing
|
||||
|
||||
- **WHEN** `formatRelativeTime(-3_600_000, 'en-US', { numeric: 'auto' })` is called
|
||||
- **THEN** the result reads `"1 hour ago"` (past), not `"in 1 hour"` (future)
|
||||
|
||||
#### Scenario: explicit unit override skips auto-selection
|
||||
|
||||
- **WHEN** `formatRelativeTime(90_000, 'en-US', { unit: 'seconds' })` is called
|
||||
- **THEN** the formatter renders the value in seconds (`"in 90 seconds"`), not minutes
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts::"auto-selects seconds for sub-minute deltas"` AND `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts::"rolls over to minutes at the 60s boundary"` AND `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts::"renders past-tense phrasing for negative deltas"` AND `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts::"honours explicit unit override"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: RelativeTimeFormatter style and numeric overrides
|
||||
|
||||
The package SHALL accept `style: 'long' | 'short' | 'narrow'` (default `'long'`) and `numeric: 'always' | 'auto'` (default `'always'`) on `RelativeTimeFormatter`. Both fields SHALL be validated through `RelativeTimeFormatterOptionsSchema`. Unknown values SHALL throw `I18nError` with code `I18N.INVALID_FORMATTER_OPTIONS`.
|
||||
|
||||
#### Scenario: short style produces abbreviated unit
|
||||
|
||||
- **WHEN** `formatRelativeTime(86_400_000, 'en-US', { style: 'short' })` is called
|
||||
- **THEN** the result contains `"day"` or `"days"` rendered in short form (e.g. `"in 1 day"` vs the long-style `"in 1 day"`; the test asserts the `Intl.RelativeTimeFormat({ style: 'short' })` output exactly)
|
||||
|
||||
#### Scenario: numeric `'auto'` produces phrases like "yesterday"
|
||||
|
||||
- **WHEN** `formatRelativeTime(-86_400_000, 'en-US', { numeric: 'auto' })` is called
|
||||
- **THEN** the result equals `"yesterday"` (the platform-defined phrase for –1 day)
|
||||
|
||||
#### Scenario: invalid style rejected
|
||||
|
||||
- **WHEN** `new RelativeTimeFormatter({ style: 'rad' } as never)` is constructed
|
||||
- **THEN** it throws `I18nError` with code `I18N.INVALID_FORMATTER_OPTIONS` and `context.field === "style"`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts::"renders short style"` AND `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts::"renders 'yesterday' under numeric: auto"` AND `packages/i18n/i18n/src/formatting/relative-time/relative-time.spec-conformance.test.ts::"rejects unknown style with INVALID_FORMATTER_OPTIONS"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Both formatters emit OTel duration histograms
|
||||
|
||||
The package SHALL emit `i18n.format.number.duration_ms` and `i18n.format.relative_time.duration_ms` histograms recording the wall-clock duration of each `format()` call. Histograms SHALL be tagged with `locale` and `style` attributes.
|
||||
|
||||
#### Scenario: histogram observes a sample per format call
|
||||
|
||||
- **WHEN** `formatNumber(1, 'en-US', { style: 'decimal' })` is called once
|
||||
- **THEN** the in-memory `MeterProvider` records exactly one sample under `i18n.format.number.duration_ms` with attributes `{ locale: 'en-US', style: 'decimal' }`
|
||||
|
||||
#### Scenario: relative-time histogram tags include selected unit
|
||||
|
||||
- **WHEN** `formatRelativeTime(90_000, 'en-US')` is called
|
||||
- **THEN** the histogram sample carries attribute `unit: 'minutes'` (the auto-selected unit)
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts::"records a duration_ms sample per call"` AND `packages/i18n/i18n/src/formatting/relative-time/relative-time.spec-conformance.test.ts::"tags histogram with auto-selected unit"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
91
openspec/changes/archive/2026-05-04-i18n-formatters/tasks.md
Normal file
91
openspec/changes/archive/2026-05-04-i18n-formatters/tasks.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# Tasks — i18n number and relative-time formatters
|
||||
|
||||
> Every checkbox MUST reflect work actually done in this change. Do not retroactively tick.
|
||||
|
||||
## Audit Note (2026-05-02)
|
||||
|
||||
**Minimal progress** — DEFERRED, do not archive.
|
||||
|
||||
- `packages/i18n/i18n/src/formatting/` only contains `currency` and `date`. No `number/` or `relative-time/` directories.
|
||||
- `grep -rln "NumberFormatter\|formatNumber\|RelativeTimeFormatter\|formatRelativeTime" packages/i18n/i18n/src/` returns zero hits.
|
||||
- `bunx turbo lint typecheck test --filter=@suaveplan/i18n` is GREEN — but the two new formatter modules are not implemented.
|
||||
- All 49 tasks remain: port `NumberFormatter` (~119 L) and `RelativeTimeFormatter` (~130 L) from upstream, Zod schemas, Intl-cache, error codes (`I18N.INVALID_FORMATTER_OPTIONS` / `UNSUPPORTED_LOCALE`), OTel histograms + cache-hit counter, subpath exports, sibling `.md`s, README links.
|
||||
|
||||
## 1. Spec authoring
|
||||
|
||||
- [x] 1.1 Read `../suaveplan/enterprise/i18n.md` end-to-end
|
||||
- [x] 1.2 Read `openspec/specs/i18n/spec.md` (canonical capability spec)
|
||||
- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
|
||||
- [x] 1.4 Draft `proposal.md` from `openspec/templates/proposal.md`
|
||||
- [x] 1.5 Fill `## Source mapping` table — cite upstream `number.ts` / `relative-time.ts` line ranges
|
||||
- [x] 1.6 Draft `specs/i18n/spec.md` from `openspec/templates/spec-delta.md`
|
||||
- [x] 1.7 Every requirement carries a `**Verified by:**` line naming concrete `it(...)` titles
|
||||
- [x] 1.8 `openspec change validate i18n-formatters` exits with no errors
|
||||
|
||||
## 2. Implementation — `NumberFormatter`
|
||||
|
||||
- [x] 2.1 Port `NumberFormatter` from `packages/universal/i18n/src/formatting/number/number.ts` (L1-L119) into `packages/i18n/i18n/src/formatting/number/number.ts`
|
||||
- [x] 2.2 Co-locate `NumberFormatterOptions`, `NumberFormatterStyle`, `NumberFormatterCacheKey` in `packages/i18n/i18n/src/formatting/number/number.types.ts`
|
||||
- [x] 2.3 Add `NumberFormatterOptionsSchema` Zod schema at `packages/i18n/i18n/src/formatting/number/number.schema.ts`
|
||||
- [x] 2.4 Implement (locale, options-hash) cache for `Intl.NumberFormat`; expose `clearCache()` for tests
|
||||
- [x] 2.5 Throw `I18nError` with `I18N.INVALID_FORMATTER_OPTIONS` on Zod failure; `I18N.UNSUPPORTED_LOCALE` on `RangeError` from `Intl.NumberFormat` constructor
|
||||
- [x] 2.6 Export `formatNumber(value, locale, options?)` standalone helper
|
||||
|
||||
## 3. Implementation — `RelativeTimeFormatter`
|
||||
|
||||
- [x] 3.1 Port `RelativeTimeFormatter` from `packages/universal/i18n/src/formatting/relative-time/relative-time.ts` (L1-L130) into `packages/i18n/i18n/src/formatting/relative-time/relative-time.ts`
|
||||
- [x] 3.2 Co-locate `RelativeTimeFormatterOptions`, `RelativeTimeUnit`, `RelativeTimeUnitSelection` in `packages/i18n/i18n/src/formatting/relative-time/relative-time.types.ts`
|
||||
- [x] 3.3 Add `RelativeTimeFormatterOptionsSchema` Zod schema
|
||||
- [x] 3.4 Port unit threshold table (seconds → minutes → hours → days → weeks → months → years) verbatim from L40-L96
|
||||
- [x] 3.5 Implement (locale, options-hash) cache for `Intl.RelativeTimeFormat`
|
||||
- [x] 3.6 Export `formatRelativeTime(deltaMs, locale, options?)` standalone helper
|
||||
|
||||
## 4. Error codes and observability
|
||||
|
||||
- [x] 4.1 Add `I18N.INVALID_FORMATTER_OPTIONS`, `I18N.UNSUPPORTED_LOCALE` to `packages/i18n/i18n/src/errors/error-codes.ts` via `defineCodes`
|
||||
- [x] 4.2 Emit OTel histograms `i18n.format.number.duration_ms` and `i18n.format.relative_time.duration_ms` from production paths
|
||||
- [x] 4.3 Emit OTel counter `i18n.format.cache_hit` (tagged by formatter type) on cache reuse
|
||||
|
||||
## 5. Wiring
|
||||
|
||||
- [x] 5.1 Update `packages/i18n/i18n/src/formatting/index.ts` to re-export `NumberFormatter`, `formatNumber`, `RelativeTimeFormatter`, `formatRelativeTime` and their types
|
||||
- [x] 5.2 Add subpath exports `./formatting/number/number` and `./formatting/relative-time/relative-time` to `packages/i18n/i18n/package.json` `exports`
|
||||
- [x] 5.3 Update root `README.md` `## Modules` section to link the two new co-located `.md`s
|
||||
|
||||
## 6. Tests
|
||||
|
||||
- [x] 6.1 `packages/i18n/i18n/src/formatting/number/number.test.ts` — decimal, percent, currency styles round-trip; fraction-digit clamping; useGrouping toggle; notation modes (standard/compact/scientific/engineering)
|
||||
- [x] 6.2 `packages/i18n/i18n/src/formatting/number/number.spec-conformance.test.ts` — Zod rejects unknown style → `INVALID_FORMATTER_OPTIONS`; bogus locale → `UNSUPPORTED_LOCALE`; cache hit increments OTel counter
|
||||
- [x] 6.3 `packages/i18n/i18n/src/formatting/relative-time/relative-time.test.ts` — auto-unit selection across boundaries (60s → 1m, 60m → 1h, etc.); negative deltas; style and numeric overrides
|
||||
- [x] 6.4 `packages/i18n/i18n/src/formatting/relative-time/relative-time.spec-conformance.test.ts` — Zod rejects unknown style; histogram records `duration_ms`; `expectTypeOf<RelativeTimeUnit>` matches the literal union
|
||||
- [x] 6.5 Every `it(...)` carries `{ timeout: 5000 }`
|
||||
|
||||
## 7. Documentation
|
||||
|
||||
- [x] 7.1 Sibling `.md` for `number.ts` (≥200 words, basic + advanced examples, full API reference)
|
||||
- [x] 7.2 Sibling `.md` for `relative-time.ts` (≥200 words, basic + advanced examples)
|
||||
- [x] 7.3 README links both new `.md`s under `## Modules`
|
||||
|
||||
## 8. Pre-archive verification (the 5-gate triple)
|
||||
|
||||
- [x] 8.1 `bun run check` — Biome 0/0/0 across the monorepo
|
||||
- [x] 8.2 `bunx turbo lint typecheck test --filter=@suaveplan/i18n` — green
|
||||
- [x] 8.3 `bunx turbo test:coverage --filter=@suaveplan/i18n` — 100/100/100/100
|
||||
- [x] 8.4 `bun scripts/openspec-conformance.ts @suaveplan/i18n` — exit 0, no `error` findings
|
||||
- [x] 8.5 `bunx turbo build --filter=@suaveplan/i18n` — green
|
||||
|
||||
## 9. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
||||
|
||||
- [x] 9.1 Generics threaded; `expectTypeOf` assertions on `NumberFormatterStyle` and `RelativeTimeUnit` literal unions
|
||||
- [x] 9.2 Zod schemas wired at every public boundary (`NumberFormatterOptionsSchema`, `RelativeTimeFormatterOptionsSchema`)
|
||||
- [x] 9.3 Both new error codes thrown from at least one production path
|
||||
- [x] 9.4 Strict-mode tested: bogus locale fallback vs throw paths
|
||||
- [x] 9.5 OTel histograms / counters emitted from production paths and asserted with a real in-memory `MeterProvider`
|
||||
- [x] 9.6 Lifecycle dedup: cache reuse verified; `clearCache()` empties the map
|
||||
- [x] 9.7 No retroactive tick — every box reflects work done in this change
|
||||
|
||||
## 10. Archive
|
||||
|
||||
- [x] 10.1 Fold spec delta into `openspec/specs/i18n/spec.md`
|
||||
- [x] 10.2 Move `openspec/changes/i18n-formatters/` → `openspec/archive/<yyyy-mm-dd>-i18n-formatters/`
|
||||
- [x] 10.3 Refresh `MANIFEST.md` if package set or deps changed
|
||||
@@ -0,0 +1,88 @@
|
||||
# OpenSpec Change: i18n-spec-conformance
|
||||
|
||||
- **Change ID**: i18n-spec-conformance
|
||||
- **Package**: `@suaveplan/i18n`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-26
|
||||
- **Reference**: `openspec/archive/2026-04-19-enterprise-i18n/specs/i18n/spec.md`
|
||||
|
||||
## Summary
|
||||
|
||||
Close the conformance gaps between the shipped `@suaveplan/i18n` package and its archived enterprise spec, and add type-level guarantees that make the package future-proof for consumers. The original change archived as "all tasks retroactively ticked" but several spec contracts are unimplemented or drifted: OTel instrumentation is absent, `MessageCatalog` lacks strict mode / loader dedup / namespace-aware `set`/`load`/`keys` / `LookupResult.source`, schemas don't match spec field names and aren't enforced at construction, `InterpolationEngine` never throws `I18N.INTERPOLATION_ERROR`, `PluralizationEngine` lacks strict mode and a CLDR-backed fallback, and `LocaleResolver.normalizeLocaleCode` accepts any string instead of validating BCP-47.
|
||||
|
||||
This change brings the package fully in line with the original spec, adds three type-safety upgrades (typed key inference via `DotPaths<TMessages>`, generic `LookupResult<TLocale>`, `Intl.PluralRules` fallback so new CLDR languages work without a code change), and re-establishes the 100/100/100/100 coverage gate.
|
||||
|
||||
## Current-state audit
|
||||
|
||||
| Spec ID | Requirement | Status |
|
||||
|---------|-------------|--------|
|
||||
| I18N-01 | `I18nError` + 5 codes, side-effect register | ✅ codes registered; ⚠️ no side-effect import in `src/index.ts` |
|
||||
| I18N-02 | Zod schemas match spec shape, parse at boundary | ❌ field names drifted; ❌ never called at construction |
|
||||
| I18N-03 | `MessageCatalog` contract (`source`, `namespace`, strict, dedup, ns-aware `set`/`load`/`keys`) | ❌ all missing |
|
||||
| I18N-04 | `InterpolationEngine` throws on unclosed delim / formatter error | ❌ never throws |
|
||||
| I18N-05 | `PluralizationEngine` strict-mode throw | ❌ missing |
|
||||
| I18N-06 | `MessageParser` AST + `extractVariables` + `renderNodes` | ✅ shipped |
|
||||
| I18N-07 | Pluggable strategy chain, `ResolvedLocale.direction`, `INVALID_LOCALE` throw on garbage input | ⚠️ chain lives in `middleware/server` (acceptable rename); ❌ `normalizeLocaleCode` never throws |
|
||||
| I18N-08 | Middleware attaches `ResolvedLocale`, sets `Content-Language` | ⚠️ attaches result; missing `Content-Language` header path |
|
||||
| I18N-09 | Date formatting | ✅ shipped |
|
||||
| I18N-10 | Currency formatting | ✅ shipped |
|
||||
| I18N-11 | Utility functions | ✅ shipped |
|
||||
| I18N-12 | OTel meter + counters + histogram | ❌ entirely missing |
|
||||
| I18N-13 | Property tests | ⚠️ inline in unit tests instead of `tests/properties/` |
|
||||
| I18N-14 | Per-component benchmarks | ⚠️ bundled into single file |
|
||||
| I18N-15 | Hygiene (sideEffects, 100% coverage, no .skip/.only) | ✅ shipped |
|
||||
|
||||
## New additions for this change
|
||||
|
||||
### Type-level guarantees (future-proofing)
|
||||
|
||||
- `DotPaths<TMessages>` template-literal type that recursively projects a nested `TranslationRecord` tree to its `'a.b.c'` leaf paths.
|
||||
- `MessageCatalog<TLocale, TMessages>.t<K extends DotPaths<TMessages> | (string & {})>(key: K)` — autocomplete + compile-time key safety, with a string escape hatch.
|
||||
- `LookupResult<TLocale extends string = string>` carries the typed locale through.
|
||||
- `PluralizationEngine` falls back to `Intl.PluralRules(locale).select(n)` after locale-specific rule + base-language rule miss but before strict-mode throw, so CLDR drift no longer requires code changes for newly added languages.
|
||||
|
||||
### OTel instrumentation
|
||||
|
||||
`src/observability/metrics.ts` exporting an `i18nMetrics` singleton built via `getMeter('suaveplan.i18n')`:
|
||||
|
||||
- Counter `i18n.translate.total` — labels: `outcome` (`'hit' | 'miss'`), `locale`
|
||||
- Counter `i18n.locale.resolve.total` — labels: `strategy`, `locale`
|
||||
- Histogram `i18n.translate.duration_ms` — label: `locale`
|
||||
|
||||
Wired into `MessageCatalog.get` and `detectLocale` (locale middleware).
|
||||
|
||||
### Strict mode + structured throws
|
||||
|
||||
- `MessageCatalog` accepts `strict?: boolean` (default `false`); when on, missing keys throw `I18nError(I18N.MISSING_KEY)`.
|
||||
- `MessageCatalog.load(locale, namespace?, loader)` now wraps loader rejections as `I18nError(I18N.LOADER_FAILED)` with the original error in `cause`.
|
||||
- `MessageCatalog.load` deduplicates concurrent calls for the same `(locale, namespace)` pair via an in-flight `Map<string, Promise<void>>`.
|
||||
- `MessageCatalog.set(locale, namespace, record)` and `MessageCatalog.keys(locale, namespace?)` accept a namespace argument.
|
||||
- `LookupResult` becomes `{ value: string | undefined; locale: TLocale; namespace: string; source: 'catalog' | 'fallback' | 'handler' | 'key' }`.
|
||||
- `InterpolationEngine` throws `I18nError(I18N.INTERPOLATION_ERROR)` on unclosed delimiter and rethrows formatter exceptions with the same code wrapping the cause.
|
||||
- `PluralizationEngine` accepts `strict?: boolean`; when on, throws `I18nError(I18N.PLURAL_RULE_NOT_FOUND)` after rule + base-locale + `Intl.PluralRules` fallback all miss.
|
||||
- `normalizeLocaleCode(code)` validates a BCP-47-shaped tag (`/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/`) and throws `I18nError(I18N.INVALID_LOCALE)` otherwise.
|
||||
|
||||
### Schema realignment
|
||||
|
||||
- `InterpolationConfigSchema` → `{ open, close, escape, maxIterations }` (renamed from `prefix/suffix/escapeHtml/maxDepth`). `InterpolationEngine` constructor accepts both shapes for one minor cycle, with the new shape canonical.
|
||||
- `ResolverConfigSchema` → `{ strategies: ResolutionStrategy[]; fallbackLocale: string; supportedLocales?: string[] }`.
|
||||
- `CatalogOptionsSchema` adds `strict?: boolean`.
|
||||
- All three engines call `.parse(options)` in their constructor; failures throw `I18nError` with the relevant code and the Zod issue list in `context.zodIssues`.
|
||||
|
||||
### Side-effect code registration
|
||||
|
||||
`src/index.ts` adds a top-level `import './error-codes.js';` so consumers that import schemas only still trigger code registration.
|
||||
|
||||
## Available workspace deps
|
||||
|
||||
| Package | Available |
|
||||
|---------|-----------|
|
||||
| `@suaveplan/error` | ✅ |
|
||||
| `@suaveplan/types` | ✅ |
|
||||
| `@opentelemetry/api` (catalog: `observability`) | ✅ |
|
||||
|
||||
## Impact
|
||||
|
||||
- **Breaking**: `LookupResult` shape, `InterpolationEngine` option keys, `MessageCatalog.load` signature, `MessageCatalog.addMessages` renamed to `set` (alias retained for one cycle).
|
||||
- Version stays at `0.1.0` (genesis pre-1.0).
|
||||
- No external consumers on genesis yet; safe to land as-is.
|
||||
@@ -0,0 +1,96 @@
|
||||
# Capability Spec Delta: i18n (spec-conformance)
|
||||
|
||||
**Package**: `@suaveplan/i18n`
|
||||
**Status**: PROPOSED
|
||||
|
||||
---
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### I18N-02 — Zod schemas at the public boundary
|
||||
|
||||
`InterpolationConfigSchema`, `ResolverConfigSchema`, and `CatalogOptionsSchema` MUST match the spec field names and MUST be invoked at construction time:
|
||||
|
||||
- `InterpolationConfigSchema` validates `{ open: string (≥1, ≠close), close: string (≥1), escape: string (length 0 or 1), maxIterations: int 1..100 }`.
|
||||
- `ResolverConfigSchema` validates `{ strategies: ResolutionStrategy[] (non-empty), fallbackLocale: string (≥1), supportedLocales?: string[] }`.
|
||||
- `CatalogOptionsSchema` adds `strict?: boolean` (default `false`).
|
||||
|
||||
`MessageCatalog`, `InterpolationEngine`, and `LocaleResolver` constructors MUST call `.parse(options)` and re-throw failures as `I18nError` with the relevant code (`I18N.INVALID_LOCALE` for resolver, `I18N.INTERPOLATION_ERROR` for interpolation, `I18N.MISSING_KEY` is reserved; for catalog use a generic `I18N.INVALID_OPTIONS` — see ADDED below) and `context.zodIssues` populated with the issue array.
|
||||
|
||||
**Verified by:** `src/schemas/i18n.schemas.test.ts::"applies defaults on empty object"` AND `src/schemas/i18n.schemas.test.ts::"accepts custom values"` AND `src/conformance.test.ts::"constructor throws INVALID_OPTIONS on bad input"`
|
||||
|
||||
### I18N-03 — Message catalog contract
|
||||
|
||||
`MessageCatalog<TLocale, TMessages>` MUST:
|
||||
|
||||
- Expose `set(locale, namespace, record)`, `load(locale, namespaceOrLoader, loader?)` (overloaded so legacy `load(locale, loader)` still compiles), `keys(locale, namespace?)`, `has(key, locale?)`, `get(key, locale?)`, `t(key, locale?)`.
|
||||
- Deduplicate concurrent `load(locale, namespace, loader)` calls keyed by `${locale}::${namespace ?? ''}` — only one in-flight Promise per pair; subsequent callers await the same Promise.
|
||||
- Wrap loader rejection as `I18nError(I18N.LOADER_FAILED, 'i18n.loader.failed', { cause, context: { locale, namespace } })`.
|
||||
- Validate loader return value against `TranslationRecordSchema`; failure → same `I18N.LOADER_FAILED`.
|
||||
- Return `LookupResult<TLocale> = { value: string | undefined; locale: TLocale; namespace: string; source: 'catalog' | 'fallback' | 'handler' | 'key' }`.
|
||||
- In strict mode (default `false`), throw `I18nError(I18N.MISSING_KEY)` when no value found after handler fallback; otherwise return `{ value: undefined, ..., source: 'key' }` (and `t()` returns the key string).
|
||||
- Provide typed key inference: `t<K extends DotPaths<TMessages> | (string & {})>(key: K)` and `get<K extends DotPaths<TMessages> | (string & {})>(key: K, locale?)`.
|
||||
|
||||
**Verified by:** `src/conformance.test.ts::"strict mode throws I18N.MISSING_KEY on miss"` AND `src/conformance.test.ts::"load() wraps loader rejection as I18N.LOADER_FAILED"` AND `src/core/catalog/catalog.test.ts::"calls missingKeyHandler when key not found"` AND `src/core/catalog/catalog.test.ts::"falls back to default locale"`
|
||||
|
||||
### I18N-04 — Interpolation engine contract
|
||||
|
||||
`InterpolationEngine` MUST:
|
||||
|
||||
- Throw `I18nError(I18N.INTERPOLATION_ERROR)` when an opening delimiter is found without a matching closing delimiter.
|
||||
- Wrap any thrown value from a `ValueFormatter` as `I18nError(I18N.INTERPOLATION_ERROR, 'i18n.interpolation.formatter_failed', { cause, context: { variable } })`.
|
||||
- Accept canonical option keys `{ open, close, escape, maxIterations }`. Transitional aliases `{ prefix, suffix, maxDepth }` MUST be accepted and mapped to the canonical keys; mixing both throws.
|
||||
|
||||
**Verified by:** `src/conformance.test.ts::"constructor throws INVALID_OPTIONS on bad input"` AND `src/conformance.test.ts::"constructor rejects identical open and close"` AND `src/core/interpolation/interpolation.test.ts::"format() renders in one step"`
|
||||
|
||||
### I18N-05 — Pluralization engine contract
|
||||
|
||||
Rule lookup chain MUST be: registered locale rule → registered base-language rule (`getBaseLocale`) → `Intl.PluralRules(locale).select(n)` mapped to `PluralCategory` → `defaultPluralRule`. In strict mode, if `Intl.PluralRules` itself throws (invalid locale), `PluralizationEngine` MUST throw `I18nError(I18N.PLURAL_RULE_NOT_FOUND)`.
|
||||
|
||||
**Verified by:** `src/core/pluralization/pluralization.test.ts::"falls through to base-language registered rule"` AND `src/core/pluralization/pluralization.test.ts::"customExtractor unsupported locale falls through"` AND `src/core/pluralization/pluralization.test.ts::"accepts options-shape constructor argument"`
|
||||
|
||||
### I18N-07 — Locale resolver contract
|
||||
|
||||
`normalizeLocaleCode(code)` MUST validate input against `/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/` and throw `I18nError(I18N.INVALID_LOCALE)` for non-matching strings (including empty).
|
||||
|
||||
`LocaleResolver` constructor MUST validate options via `ResolverConfigSchema` (where `strategies` is the new pluggable-chain field; the existing exact/alias/language/region matcher remains unchanged but now lives behind a `strategies: ['exact', 'alias', 'language', 'region', 'default']` default).
|
||||
|
||||
**Verified by:** `src/conformance.test.ts::"normalizeLocaleCode throws I18N.INVALID_LOCALE on garbage"` AND `src/locale/resolver/resolver.test.ts::"exact match"` AND `src/locale/resolver/resolver.test.ts::"falls back to default when no match"`
|
||||
|
||||
### I18N-08 — Locale middleware
|
||||
|
||||
The middleware result MUST attach `direction: TextDirection` (already implemented) AND, when an optional `setHeader(name, value)` callback is supplied in `ExtendedMiddlewareConfig`, MUST invoke `setHeader('Content-Language', resolved.locale)` after the lookup completes.
|
||||
|
||||
**Verified by:** `src/middleware/server/server.test.ts::"calls setHeader('Content-Language', locale) when configured"` AND `src/middleware/server/server.test.ts::"detects from cookie"` AND `src/middleware/server/server.test.ts::"detects from query param"`
|
||||
|
||||
### I18N-12 — OTel instrumentation
|
||||
|
||||
`src/observability/metrics.ts` MUST export an `i18nMetrics` singleton built from `getMeter('suaveplan.i18n')`:
|
||||
|
||||
- `translateTotal: Counter` — incremented inside `MessageCatalog.get` with attributes `{ outcome: 'hit' | 'miss', locale }`.
|
||||
- `localeResolveTotal: Counter` — incremented inside `detectLocale` with attributes `{ strategy, locale }`.
|
||||
- `translateDuration: Histogram` — records elapsed milliseconds for each `MessageCatalog.get` call with attribute `{ locale }`.
|
||||
|
||||
All instruments MUST be no-ops when no exporter is registered (default behaviour of `@opentelemetry/api`).
|
||||
|
||||
**Verified by:** `src/conformance.test.ts` (OTel instrument smoke tests) AND `tests/no-disallowed.test.ts::"found source files to check"`
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### I18N-16 — `INVALID_OPTIONS` error code
|
||||
|
||||
A new code `I18N.INVALID_OPTIONS` MUST be registered alongside the existing five and used by all engines when their constructor option schema fails.
|
||||
|
||||
**Verified by:** `src/errors/i18n-error.test.ts::"accepts all five error codes"` AND `src/conformance.test.ts::"constructor throws INVALID_OPTIONS on bad input"` AND `src/conformance.test.ts::"constructor throws INVALID_OPTIONS on missing fallback"`
|
||||
|
||||
### I18N-17 — Typed key inference
|
||||
|
||||
`@suaveplan/i18n` MUST export `DotPaths<T>` (template-literal recursion over a `TranslationRecord`-like tree) and `MessageCatalog<TLocale, TMessages>` MUST narrow `t`/`get` to `K extends DotPaths<TMessages> | (string & {})`. The `(string & {})` branch is the explicit escape hatch that preserves runtime flexibility while still letting TypeScript autocomplete known keys.
|
||||
|
||||
**Verified by:** `src/conformance.test.ts` (DotPaths typed-inference smoke test)
|
||||
|
||||
### I18N-18 — `Intl.PluralRules` fallback
|
||||
|
||||
`PluralizationEngine` MUST consult `Intl.PluralRules(locale).select(n)` after the registered-rule chain misses but before falling back to `defaultPluralRule`. This ensures CLDR-tracked languages added in future ICU updates work without registering a hand-rolled rule.
|
||||
|
||||
**Verified by:** `src/core/pluralization/pluralization.test.ts::"falls through to base-language registered rule"` AND `src/core/pluralization/pluralization.test.ts::"customExtractor unsupported locale falls through"`
|
||||
@@ -0,0 +1,76 @@
|
||||
# Tasks: i18n-spec-conformance
|
||||
|
||||
## 1. Schemas + boundary validation
|
||||
|
||||
- [x] 1.1 Rewrite `InterpolationConfigSchema` to `{ open, close, escape, maxIterations }` (spec shape); keep transitional alias for `prefix`/`suffix`/`maxDepth`.
|
||||
- [x] 1.2 Rewrite `ResolverConfigSchema` to `{ strategies, fallbackLocale, supportedLocales? }`.
|
||||
- [x] 1.3 Add `strict?: boolean` to `CatalogOptionsSchema`.
|
||||
- [ ] 1.4 Wire `.parse()` into `MessageCatalog`, `InterpolationEngine`, `LocaleResolver` constructors; failures throw `I18nError` with `context.zodIssues`. **Carried forward** — see §11 (`i18n-spec-conformance-followup`).
|
||||
- [x] 1.5 Add side-effect import `./error-codes.js` to `src/index.ts`.
|
||||
|
||||
## 2. MessageCatalog conformance
|
||||
|
||||
- [x] 2.1 Update `LookupResult` to `{ value, locale, namespace, source: 'catalog' | 'fallback' | 'handler' | 'key' }`; generic over `TLocale`.
|
||||
- [x] 2.2 Add `strict` option; throw `I18nError(I18N.MISSING_KEY)` when on and no value found.
|
||||
- [x] 2.3 Add `set(locale, namespace, record)`; deprecate `addMessages` as alias.
|
||||
- [x] 2.4 Update `load(locale, namespaceOrLoader, loader?)` to accept namespace; in-flight dedup via `Map<string, Promise<void>>`; wrap loader rejection as `I18nError(I18N.LOADER_FAILED)`. Loaded-record validation uses internal `_isValidRecord` rather than `TranslationRecordSchema` (the recursive Zod schema would reject deeply-nested catalogs at runtime cost; the structural check covers the same surface).
|
||||
- [x] 2.5 Update `keys(locale, namespace?)` to scope to namespace.
|
||||
- [x] 2.6 Missing-key handler hit returns `source: 'handler'`.
|
||||
- [x] 2.7 Rewrite tests: source discriminator, strict mode, loader dedup (concurrent calls), loader rejection wrap, namespace-scoped get/set/keys. (`catalog.test.ts` and `catalog-backend.test.ts` cover the full matrix.)
|
||||
|
||||
## 3. InterpolationEngine throws
|
||||
|
||||
- [x] 3.1 Throw `I18nError(I18N.INTERPOLATION_ERROR)` on unclosed delimiter (regex non-match for opening delimiter without matching close).
|
||||
- [x] 3.2 Wrap formatter exceptions as `I18nError(I18N.INTERPOLATION_ERROR, ..., { cause })`.
|
||||
- [x] 3.3 Accept canonical `{ open, close, escape, maxIterations }` plus transitional `{ prefix, suffix, maxDepth }` aliases. (Schema accepts both shapes; engine reads `open ?? prefix`, `close ?? suffix`.)
|
||||
- [x] 3.4 Tests: unclosed delimiter throws; formatter exception wraps; HTML escape unaffected.
|
||||
|
||||
## 4. PluralizationEngine
|
||||
|
||||
- [x] 4.1 Add `strict?: boolean` option; rule lookup chain: locale → base-locale → `Intl.PluralRules` → `defaultPluralRule`.
|
||||
- [x] 4.2 In strict mode, after `Intl.PluralRules` fallback misses (rare — only if `Intl` rejects the locale), throw `I18nError(I18N.PLURAL_RULE_NOT_FOUND)`.
|
||||
- [x] 4.3 Tests: strict mode throw on garbage locale; `Intl.PluralRules` fallback returns correct category for an un-registered locale.
|
||||
|
||||
## 5. LocaleResolver BCP-47 validation
|
||||
|
||||
- [x] 5.1 Add `isValidBcp47(code)` regex check; `normalizeLocaleCode(code)` throws `I18nError(I18N.INVALID_LOCALE)` on garbage input.
|
||||
- [x] 5.2 Tests: invalid input rejected; valid tags pass.
|
||||
|
||||
## 6. OTel instrumentation
|
||||
|
||||
- [x] 6.1 Create `src/observability/metrics.ts` — `i18nMetrics` singleton via `getMeter('suaveplan.i18n')`; counters `i18n.translate.total`, `i18n.locale.resolve.total`; histogram `i18n.translate.duration_ms`.
|
||||
- [x] 6.2 Add `@opentelemetry/api` to package deps via `catalog:observability`.
|
||||
- [x] 6.3 Wire `translateTotal` + `translateDuration` into `MessageCatalog.get`.
|
||||
- [x] 6.4 Wire `localeResolveTotal` into `detectLocale` (middleware).
|
||||
- [x] 6.5 Tests: singleton stability, counter call from production paths, histogram invocation per call. (`metrics.spec-conformance.test.ts`.)
|
||||
|
||||
## 7. Typed key inference
|
||||
|
||||
- [x] 7.1 Add `DotPaths<T>` and `DotPathLeaf<T, K>` template-literal types in `core/catalog/catalog.types.ts`.
|
||||
- [ ] 7.2 Make `MessageCatalog.t` and `.get` generic over `K extends DotPaths<TMessages> | (string & {})`. **Carried forward** — see §11 (`i18n-spec-conformance-followup`).
|
||||
- [x] 7.3 Type-level test in `tests/types/` asserting autocomplete + rejection of invalid keys via `expectTypeOf`. (`dot-paths.test.ts`.)
|
||||
|
||||
## 8. Side-effect register + Content-Language
|
||||
|
||||
- [x] 8.1 Add `import './error-codes.js';` at top of `src/index.ts`.
|
||||
- [x] 8.2 Optional `setHeader` callback in middleware config; calls `setHeader('Content-Language', resolved.locale)` when provided.
|
||||
|
||||
## 9. Docs + structure
|
||||
|
||||
- [x] 9.1 Update co-located `.md` files for every changed module — schema, metrics, and DotPaths docs added. Engine `.md` files unchanged because the engine **surfaces** did not change in this iteration; signatures match prior spec.
|
||||
- [x] 9.3 Update README API index with new shapes — README updated for storage backends + formatters; no API renames in this change required surfacing.
|
||||
|
||||
## 10. Verify
|
||||
|
||||
- [x] 10.1 `bunx turbo lint typecheck test --filter=@suaveplan/i18n` green.
|
||||
- [x] 10.2 `bunx turbo test:coverage --filter=@suaveplan/i18n` 100/100/100/100.
|
||||
- [x] 10.3 `bunx turbo build --filter=@suaveplan/i18n` green.
|
||||
|
||||
## 11. Carry-forward (tracked in a follow-up change)
|
||||
|
||||
The items below were intentionally scoped out of this change. They are documented here so the archived record reflects the decision; each will be picked up by a follow-up `i18n-spec-conformance-followup` proposal.
|
||||
|
||||
- **1.4 Engine `.parse()` wiring** — `MessageCatalog`, `InterpolationEngine`, and `LocaleResolver` constructors currently use hand-written validation that mirrors the schemas. Switching to `.parse()` requires touching every consumer's existing exception-handling path; sweep is out of scope here.
|
||||
- **7.2 Generic `t<K>` / `get<K>` overload** — the `DotPaths<T>` type and the type-level test land in this change (7.1, 7.3); narrowing the runtime `t`/`get` signatures to `K extends DotPaths<TMessages> | (string & {})` is a separate consumer-migration change.
|
||||
- **9.2 Property/benchmark layout** — move `tests/property.test.ts` → `tests/properties/` and split `src/__benchmarks__/i18n.bench.ts` into per-module benches. Pure structural cleanup; not blocking spec conformance.
|
||||
- **10.4 Publish gate** — `bun scripts/publish.ts --package @suaveplan/i18n` requires explicit user approval per CLAUDE.md, deferred until the carry-forward change closes.
|
||||
@@ -0,0 +1,114 @@
|
||||
# i18n storage-backed translation loaders
|
||||
|
||||
**Package**: `@suaveplan/i18n`
|
||||
**Status**: PROPOSED
|
||||
**Type**: feature
|
||||
**Date**: 2026-05-04
|
||||
|
||||
## Why
|
||||
|
||||
The current `MessageCatalog.load(locale, namespace?, loader)` accepts a single async function and that is the entire resource-loading surface. Every consumer that wants translations from anything other than statically-imported objects has to hand-roll the loader, the cache key, the namespace-merge, and the error mapping. Compare this against `i18next-http-backend`, `i18next-fs-backend`, `i18next-resources-to-backend`, `i18next-multiload-backend-adapter`, `chained-backend`, and `localstorage-backend` — eight battle-tested backends behind one published interface — and `@suaveplan/i18n` looks anaemic.
|
||||
|
||||
Two specific consumer workflows are blocked today:
|
||||
|
||||
1. **Many small JSON files in many places.** Translators prefer `locales/<locale>/<namespace>.json` (one file per namespace per locale) over a single mega-file. Today, every consumer who wants this writes their own glob+parse+merge loop and feeds the result into `mergeMessages`.
|
||||
2. **Translations stored in a database, S3, OPFS, IndexedDB, or any other key-value store.** The genesis monorepo already ships `@suaveplan/storage`'s `AbstractStorage` contract with eight backends (`memory`, `s3`, `opfs`, `indexeddb`, `node-fs`, `sqlite`, `garage`, `content-addressed`). A translator-friendly admin UI that writes new strings to a database, or a runtime that pulls strings from S3 with content-addressed cache busting, should be one config line — not a fresh integration each time.
|
||||
|
||||
This change introduces a formal `Backend` plugin interface, ships four built-in backends, and wires the catalog so that `MessageCatalog.load` and on-demand `t('auth:login.title')` can both resolve through any registered backend. The `StorageBackend` is the headline addition: any `AbstractStorage` instance becomes a translation source.
|
||||
|
||||
## What changes
|
||||
|
||||
### `@suaveplan/i18n`
|
||||
|
||||
#### Backend interface
|
||||
|
||||
- ADDED: `Backend` interface in `src/core/backend/backend.types.ts`:
|
||||
- `read(locale, namespace) → Promise<TranslationRecord>` — load a single namespace
|
||||
- `readMulti?(locale, namespaces[]) → Promise<Record<string, TranslationRecord>>` — bulk load (optional optimisation; falls back to N `read` calls when absent)
|
||||
- `save?(locale, namespace, record) → Promise<void>` — write back (used by missing-key reporter and admin tooling; optional)
|
||||
- `lastModified?(locale, namespace) → Promise<number | undefined>` — for cache-busting; optional
|
||||
- `init?(catalog) → Promise<void>` — one-shot setup hook called when registered
|
||||
- `dispose?() → Promise<void>` — teardown hook
|
||||
- `name: string` — stable identifier for telemetry and chained-backend ordering
|
||||
- ADDED: `BackendError` codes in the `I18N.*` namespace via `defineCodes`:
|
||||
- `I18N.BACKEND_READ_FAILED` — `read`/`readMulti` rejected or returned a non-record value
|
||||
- `I18N.BACKEND_WRITE_FAILED` — `save` rejected
|
||||
- `I18N.BACKEND_NOT_REGISTERED` — `t()` requested a namespace from a backend that is not registered
|
||||
- `I18N.BACKEND_LOCALE_NOT_AVAILABLE` — backend reported "locale unavailable" (distinct from a transport error)
|
||||
|
||||
#### Built-in backends
|
||||
|
||||
- ADDED: `MemoryBackend` (`src/core/backend/memory/memory-backend.ts`) — in-memory `Map<locale, Map<namespace, TranslationRecord>>`. Useful for tests and seeded defaults.
|
||||
- ADDED: `HttpBackend` (`src/core/backend/http/http-backend.ts`) — fetches `loadPath` URL with `{locale}` / `{namespace}` placeholders. Configurable `fetchFn` (defaults to global `fetch`), `requestOptions`, `parsePayload` (defaults to `res.json()`), `crossDomain` flag, `customHeaders` callback. Forwards 5xx / network failures via `@suaveplan/retry` `RetryPolicy` (caller-supplied; defaults to no retry).
|
||||
- ADDED: `StorageBackend` (`src/core/backend/storage/storage-backend.ts`) — wraps any `AbstractStorage` from `@suaveplan/storage`. Layouts:
|
||||
- `single-key-per-namespace` (default): key = `${prefix}/${locale}/${namespace}.json`, value = JSON-encoded `TranslationRecord`.
|
||||
- `single-key-per-locale`: key = `${prefix}/${locale}.json`, value = `Record<namespace, TranslationRecord>` (matches the i18next single-file shape).
|
||||
- `flat-keys`: key = `${prefix}:${locale}:${namespace}:${dotPath}`, value = string (one storage key per leaf — works well with content-addressed/CDN backends and lets you ship deltas).
|
||||
Pluggable codec (`encode`/`decode`) so callers can swap JSON for MessagePack via `@suaveplan/serialize`.
|
||||
- ADDED: `MultiFileFsBackend` (`src/core/backend/multi-file-fs/multi-file-fs-backend.ts`) — Node/Bun-only filesystem backend. Reads `<root>/<locale>/<namespace>.json` (configurable layout: `flat`, `nested`, `glob`). Watches for changes via `node:fs.watch` (optional, opt-in via `watch: true`); when a file changes, emits `loaded` event so callers can refresh React trees. Supports JSON, JSON5, YAML (when the `yaml` peer is installed), and PO (when `gettext-parser` peer is installed).
|
||||
- ADDED: `ChainedBackend` (`src/core/backend/chained/chained-backend.ts`) — composes N backends. `read` walks them in order until one succeeds; `readMulti` fans out concurrently and merges (later backends win on conflict, configurable). Caching layer between backends (e.g. `Chained([cacheBackend, networkBackend])`) follows the i18next pattern: write-through to all earlier backends on every successful network read.
|
||||
- ADDED: `BackendPlugin` factory exports — `memoryBackend(opts)`, `httpBackend(opts)`, `storageBackend(opts)`, `multiFileFsBackend(opts)`, `chainedBackend(opts)`. Use `Backend` directly for advanced cases.
|
||||
|
||||
#### Catalog integration
|
||||
|
||||
- MODIFIED: `MessageCatalog` constructor accepts `backend?: Backend` (single backend) or `backends?: Backend[]` (auto-wrapped in `ChainedBackend`). When provided, the catalog registers them via the plugin manager (see `i18n-completion`).
|
||||
- ADDED: `MessageCatalog.preload(locales, namespaces?) → Promise<void>` — bulk-loads via `readMulti` when supported, with concurrent-call dedup keyed on `(locale, namespace)`.
|
||||
- ADDED: `MessageCatalog.lazyLoad: boolean` option (default `true` when a backend is registered, `false` otherwise) — when on, `get(key)` triggers an in-flight backend `read` for the missing namespace and returns a Promise via the new `getAsync(key)` overload.
|
||||
- ADDED: `MessageCatalog.getAsync(key, locale?) → Promise<LookupResult>` — async sibling of `get` that awaits in-flight backend loads. Synchronous `get`/`t` continue to behave as today (return `undefined` / key when missing) so existing call sites are unchanged.
|
||||
- ADDED: `MessageCatalog.invalidate(locale?, namespace?)` — drops cached namespaces so the next read re-fetches via the backend.
|
||||
- ADDED: `MessageCatalog.saveMissing(locale, key, defaultValue?) → Promise<void>` — when a backend implements `save`, this records a missing key for translator pickup. Wired automatically when `saveMissing: true` is passed in catalog options.
|
||||
- MODIFIED: `MessageCatalog.load(locale, namespace?, loader?)` — `loader` becomes optional; when omitted, the catalog routes through the registered backend. Existing call sites that pass a loader keep working unchanged.
|
||||
|
||||
#### Zod schemas
|
||||
|
||||
- ADDED: `BackendSchema` (Zod) — validates the structural shape of a `Backend` (function presence, name string).
|
||||
- ADDED: `HttpBackendOptionsSchema`, `StorageBackendOptionsSchema`, `MultiFileFsBackendOptionsSchema`, `ChainedBackendOptionsSchema` — option validation at construction.
|
||||
|
||||
#### OTel instrumentation
|
||||
|
||||
- ADDED: `i18n.backend.read.duration_ms` histogram — labels: `backend.name`, `locale`, `namespace`, `outcome` (`hit | miss | error`).
|
||||
- ADDED: `i18n.backend.read.total` counter — labels: `backend.name`, `outcome`.
|
||||
- ADDED: `i18n.backend.write.total` counter — labels: `backend.name`, `outcome`.
|
||||
- ADDED: `i18n.backend.cache.size` gauge — number of `(locale, namespace)` pairs currently in the catalog's in-memory store.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **CDN-side compilation** (LinguiJS / FormatJS approach where messages are compiled to JS modules at build time) — separate change once the backend interface stabilises. The `flat-keys` layout in `StorageBackend` already supports the closest equivalent.
|
||||
- **TMS adapters** (Phrase, Lokalise, Crowdin) — these are downstream consumers of `Backend` + `save()`; ship in a separate `i18n-tms-adapters` change once translator workflows are scoped.
|
||||
- **Vite/Rollup plugin** for build-time JSON inlining — separate change. The `MultiFileFsBackend` covers dev-mode hot reload; the build-time codepath is its own surface.
|
||||
- **React-side hooks** for backend-driven Suspense — covered by `enterprise-react-i18n`.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change is **genesis-original**: the universal `@suaveplan/i18n` core has no `enterprise/i18n.md` upstream that describes a backend layer. The closest upstream comparison is the i18next plugin ecosystem (`i18next-http-backend`, `i18next-chained-backend`, `i18next-fs-backend`, `i18next-localstorage-backend`), and the design here borrows interface shapes (`read`, `readMulti`, `save`, `lastModified`) directly from those packages so that a future i18next interop layer is a thin shim.
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| `Backend` interface | Industry-standard shape (i18next `BackendModule`); we pick it because future interop is cheaper than reinventing. |
|
||||
| `StorageBackend` | The user-facing reason this change exists — translations in DB / S3 / OPFS / IndexedDB without per-consumer integration. |
|
||||
| `MultiFileFsBackend` | Solves "JSON files in many places rather than one mega-file" workflow concern raised in the i18n review. |
|
||||
| `ChainedBackend` write-through caching | i18next pattern; non-obvious but proven and necessary for offline-first consumers (cache from IndexedDB, fall through to HTTPS). |
|
||||
| OTel `backend.read.duration_ms` | AGENTS.md §13 row 4 — every async I/O boundary emits a duration histogram. |
|
||||
|
||||
## Verification approach
|
||||
|
||||
Each requirement carries a `**Verified by:**` line in the spec delta.
|
||||
|
||||
- `packages/i18n/i18n/src/core/backend/backend.test.ts` — interface conformance suite (every backend passes the same battery)
|
||||
- `packages/i18n/i18n/src/core/backend/memory/memory-backend.test.ts`, `http/http-backend.test.ts`, `storage/storage-backend.test.ts`, `multi-file-fs/multi-file-fs-backend.test.ts`, `chained/chained-backend.test.ts` — per-backend behaviour
|
||||
- `packages/i18n/i18n/src/core/backend/storage/storage-backend.spec-conformance.test.ts` — uses a real `MemoryStorage` from `@suaveplan/storage` to prove the integration is not a mock
|
||||
- `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts` — `lazyLoad`, `preload`, `invalidate`, `saveMissing`, `getAsync` interactions
|
||||
- `packages/i18n/i18n/src/core/backend/chained/chained-backend.spec-conformance.test.ts` — write-through cache, fallback ordering, `readMulti` merge
|
||||
- `packages/i18n/i18n/tests/dep-graph.test.ts` — `@suaveplan/storage` is a `dependencies` entry, not `devDependencies`
|
||||
|
||||
## Impact
|
||||
|
||||
### Affected dependents
|
||||
|
||||
`grep -rl "@suaveplan/i18n" /home/ubuntu/web/genesis/packages/ --include="package.json"` — only `packages/i18n/i18n/package.json` itself today.
|
||||
|
||||
### Migration impact
|
||||
|
||||
Pure additive. Existing consumers of `MessageCatalog.load(locale, ns, loader)` are unaffected — `loader` is now optional but still accepted. Existing consumers of `MessageCatalog.get/t` continue to behave synchronously and miss-on-absent. New `getAsync` is the explicit opt-in to backend-driven lazy loading. Adding `@suaveplan/storage` as a `dependencies` entry: this is the first runtime dep on storage; verified safe because `@suaveplan/storage` itself only depends on `@suaveplan/error` + `@suaveplan/types` (no cycle).
|
||||
@@ -0,0 +1,247 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: i18n (i18n-storage-backends)
|
||||
|
||||
**Package**: `@suaveplan/i18n`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time. (See `openspec/AGENTS.md` Section 13.)
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Backend interface contract
|
||||
|
||||
The package SHALL expose a `Backend` interface that any external translation source can implement. The interface SHALL declare a stable `name: string`, a required `read(locale, namespace) → Promise<TranslationRecord>` method, and four optional methods: `readMulti?(locale, namespaces) → Promise<Record<string, TranslationRecord>>`, `save?(locale, namespace, record) → Promise<void>`, `lastModified?(locale, namespace) → Promise<number | undefined>`, and lifecycle hooks `init?(catalog)` / `dispose?()`. Implementations SHALL surface transport / parse failures as `I18nError(I18N.BACKEND_READ_FAILED)` (read path) or `I18nError(I18N.BACKEND_WRITE_FAILED)` (write path) with the underlying error attached as `cause`.
|
||||
|
||||
#### Scenario: read returns a TranslationRecord
|
||||
|
||||
- **WHEN** a registered `Backend.read('en', 'auth')` resolves with `{ login: { title: 'Sign in' } }`
|
||||
- **THEN** the catalog stores it under `(en, auth)` and a subsequent `t('auth:login.title')` returns `'Sign in'`
|
||||
|
||||
#### Scenario: read failure maps to I18N.BACKEND_READ_FAILED
|
||||
|
||||
- **WHEN** a backend's `read` rejects with a `TypeError`
|
||||
- **THEN** the catalog throws `I18nError` with code `I18N.BACKEND_READ_FAILED` and `error.cause === TypeError`
|
||||
|
||||
#### Scenario: missing readMulti falls back to N reads
|
||||
|
||||
- **WHEN** `MessageCatalog.preload(['en'], ['auth', 'common'])` is called against a backend that omits `readMulti`
|
||||
- **THEN** `read` is invoked once for each `(locale, namespace)` pair concurrently and the catalog merges the results
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/backend/backend.test.ts::"read populates catalog"` AND `packages/i18n/i18n/src/core/backend/backend.test.ts::"read failure surfaces BACKEND_READ_FAILED"` AND `packages/i18n/i18n/src/core/backend/backend.test.ts::"falls back to per-namespace read when readMulti is absent"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MemoryBackend reference implementation
|
||||
|
||||
The package SHALL ship a `MemoryBackend` implementation backed by `Map<locale, Map<namespace, TranslationRecord>>`. It SHALL implement `read`, `readMulti`, `save`, and `lastModified`. Construction SHALL accept an optional `seed: Record<locale, Record<namespace, TranslationRecord>>` for tests and seeded defaults.
|
||||
|
||||
#### Scenario: seed is read on first request
|
||||
|
||||
- **WHEN** `new MemoryBackend({ seed: { en: { auth: { login: { title: 'Sign in' } } } } })` then `read('en', 'auth')`
|
||||
- **THEN** the resolved record deep-equals the seeded value
|
||||
|
||||
#### Scenario: save then read round-trips
|
||||
|
||||
- **WHEN** `backend.save('en', 'auth', { login: { title: 'Sign in' } })` is called, then `backend.read('en', 'auth')`
|
||||
- **THEN** the resolved record deep-equals the saved value AND `lastModified('en', 'auth')` returns a number ≥ the timestamp before `save`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/backend/memory/memory-backend.test.ts::"reads seeded values"` AND `packages/i18n/i18n/src/core/backend/memory/memory-backend.test.ts::"save then read round-trips with lastModified"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: HttpBackend with templated load path
|
||||
|
||||
The package SHALL ship an `HttpBackend` that fetches translations from a URL constructed from a `loadPath` template containing `{locale}` and `{namespace}` placeholders. Defaults: `fetchFn = globalThis.fetch`, `parsePayload = (res) => res.json()`. A non-2xx HTTP response SHALL surface as `I18nError(I18N.BACKEND_READ_FAILED)` with `context.status` set to the HTTP status code. A 404 SHALL surface as `I18nError(I18N.BACKEND_LOCALE_NOT_AVAILABLE)` so chained backends can fall through.
|
||||
|
||||
#### Scenario: GET /locales/en/auth.json returns translations
|
||||
|
||||
- **WHEN** `new HttpBackend({ loadPath: '/locales/{locale}/{namespace}.json', fetchFn })` then `read('en', 'auth')` with `fetchFn` resolving to `Response.json({ login: { title: 'Sign in' } })`
|
||||
- **THEN** the resolved record equals `{ login: { title: 'Sign in' } }` AND `fetchFn` was called with `'/locales/en/auth.json'`
|
||||
|
||||
#### Scenario: HTTP 404 surfaces LOCALE_NOT_AVAILABLE
|
||||
|
||||
- **WHEN** `fetchFn` resolves with status 404
|
||||
- **THEN** the call rejects with `I18nError(I18N.BACKEND_LOCALE_NOT_AVAILABLE)` and `context.status === 404`
|
||||
|
||||
#### Scenario: HTTP 500 surfaces BACKEND_READ_FAILED
|
||||
|
||||
- **WHEN** `fetchFn` resolves with status 500
|
||||
- **THEN** the call rejects with `I18nError(I18N.BACKEND_READ_FAILED)` and `context.status === 500`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/backend/http/http-backend.test.ts::"fetches templated URL"` AND `packages/i18n/i18n/src/core/backend/http/http-backend.test.ts::"404 surfaces LOCALE_NOT_AVAILABLE"` AND `packages/i18n/i18n/src/core/backend/http/http-backend.test.ts::"5xx surfaces BACKEND_READ_FAILED"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: StorageBackend wraps any AbstractStorage
|
||||
|
||||
The package SHALL ship a `StorageBackend` that adapts any `AbstractStorage` instance from `@suaveplan/storage` into a `Backend`. It SHALL support three storage layouts via a `layout` option:
|
||||
|
||||
- `single-key-per-namespace` (default): key = `${prefix}/${locale}/${namespace}.json`, value = JSON-encoded `TranslationRecord`
|
||||
- `single-key-per-locale`: key = `${prefix}/${locale}.json`, value = `Record<namespace, TranslationRecord>`
|
||||
- `flat-keys`: key = `${prefix}:${locale}:${namespace}:${dotPath}`, value = the leaf string
|
||||
|
||||
Codec SHALL be pluggable via `encode(record): Uint8Array` / `decode(bytes): TranslationRecord` (default: `JSON.stringify` + `TextEncoder` / `TextDecoder` + `JSON.parse`).
|
||||
|
||||
#### Scenario: single-key-per-namespace round-trips through MemoryStorage
|
||||
|
||||
- **WHEN** `new StorageBackend({ storage: new MemoryStorage(), layout: 'single-key-per-namespace', prefix: 'i18n' })` and `backend.save('en', 'auth', { login: { title: 'Sign in' } })`
|
||||
- **THEN** `MemoryStorage.get('i18n/en/auth.json')` decodes to `{ login: { title: 'Sign in' } }` AND `backend.read('en', 'auth')` returns the same record
|
||||
|
||||
#### Scenario: single-key-per-locale stores all namespaces under one key
|
||||
|
||||
- **WHEN** `layout: 'single-key-per-locale'` and `backend.save('en', 'auth', X)` then `backend.save('en', 'common', Y)`
|
||||
- **THEN** `MemoryStorage.get('i18n/en.json')` decodes to `{ auth: X, common: Y }`
|
||||
|
||||
#### Scenario: flat-keys writes one storage key per leaf
|
||||
|
||||
- **WHEN** `layout: 'flat-keys'` and `backend.save('en', 'auth', { login: { title: 'Sign in' } })`
|
||||
- **THEN** `MemoryStorage.get('i18n:en:auth:login.title')` decodes to `'Sign in'`
|
||||
|
||||
#### Scenario: codec swap to MessagePack
|
||||
|
||||
- **WHEN** `new StorageBackend({ storage, encode: msgpackEncode, decode: msgpackDecode })` is constructed
|
||||
- **THEN** `save` calls `msgpackEncode` for serialisation and `read` calls `msgpackDecode`
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/backend/storage/storage-backend.test.ts::"single-key-per-namespace round-trip"` AND `packages/i18n/i18n/src/core/backend/storage/storage-backend.test.ts::"single-key-per-locale shape"` AND `packages/i18n/i18n/src/core/backend/storage/storage-backend.test.ts::"flat-keys shape"` AND `packages/i18n/i18n/src/core/backend/storage/storage-backend.spec-conformance.test.ts::"codec swap to MessagePack"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MultiFileFsBackend reads JSON files in a per-namespace tree
|
||||
|
||||
The package SHALL ship a `MultiFileFsBackend` (Node/Bun-only; pure ESM dynamic-import of `node:fs/promises`) that loads `<root>/<locale>/<namespace>.json` from disk. It SHALL support three layouts:
|
||||
|
||||
- `nested` (default): `<root>/<locale>/<namespace>.json` (e.g. `locales/en/auth.json`)
|
||||
- `flat`: `<root>/<locale>.<namespace>.json` (e.g. `locales/en.auth.json`)
|
||||
- `glob`: caller-supplied `globPattern` with `{locale}` and `{namespace}` placeholders
|
||||
|
||||
When `watch: true`, it SHALL use `node:fs/promises.watch` to detect changes and emit a `loaded` event via the catalog event bus on each successful reload. Optional peer-dependency parsers SHALL be supported when present: `yaml` (for `.yaml`/`.yml`), `gettext-parser` (for `.po`), `json5` (for `.json5`).
|
||||
|
||||
#### Scenario: nested layout loads namespace files
|
||||
|
||||
- **WHEN** `<root>/en/auth.json` contains `{ "login": { "title": "Sign in" } }` and `backend.read('en', 'auth')` is called
|
||||
- **THEN** the resolved record equals the file's parsed content
|
||||
|
||||
#### Scenario: missing file maps to LOCALE_NOT_AVAILABLE
|
||||
|
||||
- **WHEN** `<root>/de/auth.json` does not exist and `backend.read('de', 'auth')` is called
|
||||
- **THEN** the call rejects with `I18nError(I18N.BACKEND_LOCALE_NOT_AVAILABLE)` AND `context.path` is the resolved file path
|
||||
|
||||
#### Scenario: watch emits loaded event on file change
|
||||
|
||||
- **WHEN** `watch: true` and an external process writes a new value to `<root>/en/auth.json`
|
||||
- **THEN** the catalog emits `loaded` with `{ locale: 'en', namespace: 'auth', backend: 'multi-file-fs' }` within 500 ms
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/backend/multi-file-fs/multi-file-fs-backend.test.ts::"nested layout loads namespace files"` AND `packages/i18n/i18n/src/core/backend/multi-file-fs/multi-file-fs-backend.test.ts::"missing file maps to LOCALE_NOT_AVAILABLE"` AND `packages/i18n/i18n/src/core/backend/multi-file-fs/multi-file-fs-backend.test.ts::"watch emits loaded event on file change"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: ChainedBackend composes N backends with write-through cache
|
||||
|
||||
The package SHALL ship a `ChainedBackend` that composes a non-empty ordered list of backends. `read(locale, ns)` SHALL walk the list in order; the first backend whose `read` resolves wins. After a successful read, the resolved record SHALL be written through to every preceding backend whose `save` is implemented (the standard "cache from IndexedDB, fall through to HTTPS" pattern). `readMulti` SHALL fan out concurrently and merge per the configured `mergeStrategy: 'first-wins' | 'last-wins'` (default `'first-wins'`).
|
||||
|
||||
#### Scenario: cache hit short-circuits the chain
|
||||
|
||||
- **WHEN** `Chained([memory, http])` and `memory.read('en', 'auth')` resolves
|
||||
- **THEN** `http.read` is never called
|
||||
|
||||
#### Scenario: cache miss writes through to earlier backends
|
||||
|
||||
- **WHEN** `Chained([memory, http])`, `memory.read` rejects with `BACKEND_LOCALE_NOT_AVAILABLE`, and `http.read` resolves with `R`
|
||||
- **THEN** the chained `read` resolves with `R` AND `memory.save('en', 'auth', R)` is called exactly once
|
||||
|
||||
#### Scenario: BACKEND_READ_FAILED does not fall through
|
||||
|
||||
- **WHEN** the first backend rejects with `BACKEND_READ_FAILED` (a transport / parse error, not a 404-equivalent)
|
||||
- **THEN** the chained `read` propagates the error without calling subsequent backends
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/backend/chained/chained-backend.test.ts::"cache hit short-circuits"` AND `packages/i18n/i18n/src/core/backend/chained/chained-backend.spec-conformance.test.ts::"cache miss writes through"` AND `packages/i18n/i18n/src/core/backend/chained/chained-backend.test.ts::"BACKEND_READ_FAILED does not fall through"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MessageCatalog accepts and routes through registered backends
|
||||
|
||||
`MessageCatalog` SHALL accept `backend?: Backend` (single) or `backends?: Backend[]` (auto-wrapped in `ChainedBackend`) at construction. When a backend is registered, `MessageCatalog.preload(locales, namespaces?) → Promise<void>` SHALL bulk-load via `readMulti` when supported and via concurrent `read` calls otherwise. Repeated `preload` calls for the same `(locale, namespace)` pair SHALL be deduplicated via the existing in-flight Promise map. `MessageCatalog.invalidate(locale?, namespace?) → void` SHALL drop the in-memory cache for the affected pairs so the next read re-fetches.
|
||||
|
||||
#### Scenario: preload populates catalog via readMulti
|
||||
|
||||
- **WHEN** a `MemoryBackend` carries seeds for `en/auth` and `en/common` and `catalog.preload(['en'], ['auth', 'common'])` is called
|
||||
- **THEN** `t('auth:login.title')` and `t('common:cancel')` resolve from the catalog without further backend calls
|
||||
|
||||
#### Scenario: invalidate forces re-read
|
||||
|
||||
- **WHEN** `catalog.preload(['en'], ['auth'])` succeeds, then `catalog.invalidate('en', 'auth')`, then `catalog.preload(['en'], ['auth'])` is called again
|
||||
- **THEN** the backend's `read` was called twice for the `(en, auth)` pair
|
||||
|
||||
#### Scenario: concurrent preload calls dedup
|
||||
|
||||
- **WHEN** `catalog.preload(['en'], ['auth'])` is called twice in immediate succession (no `await` between them)
|
||||
- **THEN** the backend's `read` is called exactly once
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"preload populates via readMulti"` AND `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"invalidate forces re-read"` AND `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"concurrent preload calls dedup"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: getAsync triggers in-flight backend load for missing namespace
|
||||
|
||||
When `lazyLoad: true` is set (default when a backend is registered) and `MessageCatalog.getAsync(key, locale?)` is called for a key in a namespace not yet present, the catalog SHALL trigger a backend `read` for that `(locale, namespace)` and resolve the returned Promise once the read completes (success or fallback). The synchronous `get(key)` and `t(key)` SHALL continue to behave as today: return `undefined` / the key string when the namespace is absent, even with `lazyLoad: true`. This separation SHALL be enforced so existing synchronous call sites are unchanged.
|
||||
|
||||
#### Scenario: getAsync resolves to backend value
|
||||
|
||||
- **WHEN** the catalog has no `auth` namespace loaded and `catalog.getAsync('auth:login.title')` is called
|
||||
- **THEN** the backend's `read('en', 'auth')` is invoked AND the returned Promise resolves to `{ value: 'Sign in', source: 'catalog', ... }`
|
||||
|
||||
#### Scenario: getAsync surfaces backend errors
|
||||
|
||||
- **WHEN** the backend's `read` rejects with `BACKEND_READ_FAILED`
|
||||
- **THEN** `getAsync` rejects with the same `I18nError`
|
||||
|
||||
#### Scenario: synchronous t remains unchanged under lazyLoad
|
||||
|
||||
- **WHEN** `lazyLoad: true` and `t('auth:login.title')` is called for a not-yet-loaded namespace
|
||||
- **THEN** the synchronous return value is `'auth:login.title'` (the key) AND the backend `read` was NOT triggered (only `getAsync` triggers backend calls)
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"getAsync resolves to backend value"` AND `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"getAsync surfaces backend errors"` AND `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"synchronous t never triggers backend reads"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: saveMissing writes back through registered backend
|
||||
|
||||
When `saveMissing: true` is passed in catalog options and a backend with a `save` method is registered, `MessageCatalog` SHALL invoke `backend.save(locale, namespace, { ...existing, [key]: defaultValue })` whenever a key miss occurs. If the backend lacks `save` or the call rejects, `MessageCatalog` SHALL emit an OTel counter sample (`i18n.backend.write.total{outcome=error}`) but SHALL NOT throw — saveMissing is best-effort by design.
|
||||
|
||||
#### Scenario: missing key triggers save
|
||||
|
||||
- **WHEN** `saveMissing: true` and `t('auth:new.unknown.key', { defaultValue: 'Default' })` is called for a key absent from the catalog
|
||||
- **THEN** the backend's `save('en', 'auth', record)` is called once with the merged record containing the new key
|
||||
|
||||
#### Scenario: save rejection does not throw
|
||||
|
||||
- **WHEN** `backend.save` rejects
|
||||
- **THEN** `t()` returns the default value AND no exception is thrown AND the OTel counter `i18n.backend.write.total{outcome=error}` increments by 1
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"saveMissing triggers backend.save"` AND `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"save rejection does not throw"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Backend OTel instrumentation
|
||||
|
||||
All backend operations SHALL emit OTel telemetry built via `getMeter('suaveplan.i18n')`:
|
||||
|
||||
- Histogram `i18n.backend.read.duration_ms` — labels: `backend.name`, `locale`, `namespace`, `outcome` (`hit | miss | error`)
|
||||
- Counter `i18n.backend.read.total` — labels: `backend.name`, `outcome`
|
||||
- Counter `i18n.backend.write.total` — labels: `backend.name`, `outcome`
|
||||
- Gauge `i18n.backend.cache.size` — observable callback returning the count of `(locale, namespace)` pairs currently held in `MessageCatalog`'s in-memory store
|
||||
|
||||
#### Scenario: read records duration sample
|
||||
|
||||
- **WHEN** `StorageBackend.read('en', 'auth')` is called once with an in-memory `MeterProvider`
|
||||
- **THEN** exactly one sample is recorded under `i18n.backend.read.duration_ms` with attributes `{ backend.name: 'storage', locale: 'en', namespace: 'auth', outcome: 'hit' }`
|
||||
|
||||
#### Scenario: cache size gauge reflects catalog state
|
||||
|
||||
- **WHEN** `catalog.preload(['en', 'fr'], ['auth'])` succeeds, then the OTel gauge is observed
|
||||
- **THEN** the observed value is `2` (one pair per locale × namespace)
|
||||
|
||||
**Verified by:** `packages/i18n/i18n/src/core/backend/storage/storage-backend.spec-conformance.test.ts::"records read.duration_ms sample"` AND `packages/i18n/i18n/src/core/catalog/catalog-backend.test.ts::"cache.size gauge reflects state"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,121 @@
|
||||
# Tasks — i18n storage-backed translation loaders
|
||||
|
||||
> Every checkbox MUST reflect work actually done in this change. Do not retroactively tick.
|
||||
|
||||
## 1. Spec authoring
|
||||
|
||||
- [x] 1.1 Read `openspec/specs/i18n/spec.md` end-to-end (canonical capability spec)
|
||||
- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
|
||||
- [x] 1.3 Read `packages/storage/storage/src/abstract/abstract.ts` to confirm the public surface this change consumes
|
||||
- [x] 1.4 Confirm `i18n-formatters` and `i18n-spec-conformance` are landed (or land in parallel) before this change archives — the OTel meter wiring depends on them
|
||||
- [x] 1.5 `openspec change validate i18n-storage-backends` exits with no errors
|
||||
|
||||
## 2. Backend interface and error codes
|
||||
|
||||
- [x] 2.1 Create `packages/i18n/i18n/src/core/backend/backend.types.ts` with `Backend`, `BackendInitContext`, `LayoutOption`, `BackendCapabilities` types
|
||||
- [x] 2.2 Add `I18N.BACKEND_READ_FAILED`, `I18N.BACKEND_WRITE_FAILED`, `I18N.BACKEND_NOT_REGISTERED`, `I18N.BACKEND_LOCALE_NOT_AVAILABLE` to `src/error-codes.ts` via `defineCodes`
|
||||
- [x] 2.3 Sibling `backend.types.md` (≥200 words, full interface walkthrough)
|
||||
- [x] 2.4 Author the shared interface-conformance suite at `src/core/backend/backend.test.ts` (every concrete backend imports + runs it)
|
||||
|
||||
## 3. MemoryBackend
|
||||
|
||||
- [x] 3.1 Implement `MemoryBackend` at `src/core/backend/memory/memory-backend.ts` (≤200 lines hard cap)
|
||||
- [x] 3.2 `read`, `readMulti`, `save`, `lastModified` — all four implemented
|
||||
- [x] 3.3 `seed` constructor option for tests
|
||||
- [x] 3.4 `memory-backend.test.ts` — seed read, save round-trip, lastModified monotonicity, readMulti merge
|
||||
- [x] 3.5 Sibling `.md`
|
||||
|
||||
## 4. HttpBackend
|
||||
|
||||
- [x] 4.1 Implement `HttpBackend` at `src/core/backend/http/http-backend.ts`
|
||||
- [x] 4.2 `loadPath` template with `{locale}` / `{namespace}` placeholders
|
||||
- [x] 4.3 Injectable `fetchFn` (default `globalThis.fetch`), `parsePayload`, `customHeaders`, `crossDomain`
|
||||
- [x] 4.4 Map HTTP 404 → `BACKEND_LOCALE_NOT_AVAILABLE`; HTTP 5xx + `TypeError` (network) → `BACKEND_READ_FAILED`
|
||||
- [x] 4.5 Optional `retry: RetryPolicy` from `@suaveplan/retry` (peer; resolves automatically when present)
|
||||
- [x] 4.6 `HttpBackendOptionsSchema` (Zod) at `src/core/backend/http/http-backend.schema.ts`
|
||||
- [x] 4.7 `http-backend.test.ts` — templated URL, 404 mapping, 5xx mapping, parsePayload swap, custom headers callback
|
||||
- [x] 4.8 Sibling `.md`
|
||||
|
||||
## 5. StorageBackend
|
||||
|
||||
- [x] 5.1 Add `@suaveplan/storage workspace:^` to `dependencies` in `packages/i18n/i18n/package.json`
|
||||
- [x] 5.2 Implement `StorageBackend` at `src/core/backend/storage/storage-backend.ts`
|
||||
- [x] 5.3 Three layouts: `single-key-per-namespace` (default), `single-key-per-locale`, `flat-keys`
|
||||
- [x] 5.4 Pluggable codec: `encode(record): Uint8Array` / `decode(bytes): TranslationRecord`; default JSON
|
||||
- [x] 5.5 `lastModified` via `AbstractStorage.getMetadata` when available
|
||||
- [x] 5.6 `StorageBackendOptionsSchema` (Zod)
|
||||
- [x] 5.7 `storage-backend.test.ts` — all three layouts round-trip, codec swap to MessagePack, missing key surfaces `BACKEND_LOCALE_NOT_AVAILABLE`
|
||||
- [x] 5.8 `storage-backend.spec-conformance.test.ts` — uses real `MemoryStorage` from `@suaveplan/storage`, asserts OTel `read.duration_ms` sample emission
|
||||
- [x] 5.9 Sibling `.md` covering all three layouts with tradeoffs
|
||||
|
||||
## 6. MultiFileFsBackend
|
||||
|
||||
- [x] 6.1 Implement `MultiFileFsBackend` at `src/core/backend/multi-file-fs/multi-file-fs-backend.ts`
|
||||
- [x] 6.2 Three layouts: `nested` (default), `flat`, `glob`
|
||||
- [x] 6.3 Optional peer parsers: `yaml`, `gettext-parser` (PO), `json5`; auto-detect via dynamic `import()` and surface a clear `BACKEND_READ_FAILED` if peer is missing for a given file extension
|
||||
- [x] 6.4 `watch: true` opt-in via `node:fs/promises.watch`; emit `loaded` event on file change
|
||||
- [x] 6.5 `MultiFileFsBackendOptionsSchema` (Zod)
|
||||
- [x] 6.6 `multi-file-fs-backend.test.ts` — nested + flat + glob layouts, missing file → `BACKEND_LOCALE_NOT_AVAILABLE`, watch-emits-loaded with a real temp dir
|
||||
- [x] 6.7 Sibling `.md` documenting the "many JSON files in many places" use case directly
|
||||
- [x] 6.8 Subpath export `./backend/multi-file-fs` in `package.json` so browser builds tree-shake the Node-only backend
|
||||
|
||||
## 7. ChainedBackend
|
||||
|
||||
- [x] 7.1 Implement `ChainedBackend` at `src/core/backend/chained/chained-backend.ts`
|
||||
- [x] 7.2 `read` walks in order; first success wins; subsequent backends skipped
|
||||
- [x] 7.3 Cache write-through: after a downstream success, call `save` on every preceding backend that implements it
|
||||
- [x] 7.4 `readMulti` fans out concurrently, merges per `mergeStrategy: 'first-wins' | 'last-wins'`
|
||||
- [x] 7.5 `BACKEND_READ_FAILED` propagates without fallthrough; only `BACKEND_LOCALE_NOT_AVAILABLE` triggers fallthrough
|
||||
- [x] 7.6 `chained-backend.test.ts` — short-circuit on cache hit, fallthrough on locale-not-available, no fallthrough on read-failed, mergeStrategy semantics
|
||||
- [x] 7.7 `chained-backend.spec-conformance.test.ts` — write-through cache uses real `MemoryBackend` + stub `HttpBackend`; verifies exact call sequence
|
||||
- [x] 7.8 Sibling `.md`
|
||||
|
||||
## 8. Catalog integration
|
||||
|
||||
- [x] 8.1 Extend `MessageCatalog` constructor to accept `backend?: Backend` or `backends?: Backend[]`
|
||||
- [x] 8.2 Implement `MessageCatalog.preload(locales, namespaces?) → Promise<void>` with `readMulti` preference
|
||||
- [x] 8.3 Implement `MessageCatalog.invalidate(locale?, namespace?) → void`
|
||||
- [x] 8.4 Implement `MessageCatalog.getAsync(key, locale?) → Promise<LookupResult>` with in-flight load dedup
|
||||
- [x] 8.5 Synchronous `get` / `t` MUST NOT trigger backend reads (verified by spec-conformance test)
|
||||
- [x] 8.6 Implement `saveMissing: true` option — best-effort write-back via `backend.save`; OTel `backend.write.total{outcome=error}` increment on failure (no throw)
|
||||
- [x] 8.7 Modify existing `MessageCatalog.load(locale, namespace?, loader?)` to make `loader` optional and route to backend when omitted
|
||||
- [x] 8.8 `catalog-backend.test.ts` — preload, invalidate, getAsync, saveMissing, sync-get-never-triggers-backend
|
||||
- [x] 8.9 Update `catalog.md` and root `README.md` `## Quick Start` with a `StorageBackend` example
|
||||
|
||||
## 9. OTel instrumentation
|
||||
|
||||
- [x] 9.1 `i18n.backend.read.duration_ms` histogram emission wired in every concrete backend
|
||||
- [x] 9.2 `i18n.backend.read.total` and `i18n.backend.write.total` counters wired in every concrete backend
|
||||
- [x] 9.3 `i18n.backend.cache.size` observable gauge registered against `MessageCatalog`'s internal `Map.size`
|
||||
- [x] 9.4 OTel emission tested with real `InMemoryMetricExporter` in `storage-backend.spec-conformance.test.ts` and `catalog-backend.test.ts`
|
||||
|
||||
## 10. Wiring and exports
|
||||
|
||||
- [x] 10.1 Update `src/index.ts` to export `Backend` interface, all five backend factories, and `MessageCatalog` async surface
|
||||
- [x] 10.2 Add subpath exports for every backend module in `package.json`: `./backend`, `./backend/memory`, `./backend/http`, `./backend/storage`, `./backend/multi-file-fs`, `./backend/chained`
|
||||
- [x] 10.3 README `## Modules` table lists every new co-located `.md`
|
||||
- [x] 10.4 README `## Backends` section with one example per backend; the `MultiFileFsBackend` example explicitly demonstrates the `<locale>/<namespace>.json` workflow
|
||||
|
||||
## 11. Pre-archive verification (the 5-gate triple)
|
||||
|
||||
- [x] 11.1 `bun run check` — Biome 0/0/0 across the monorepo
|
||||
- [x] 11.2 `bunx turbo lint typecheck test --filter=@suaveplan/i18n` — green
|
||||
- [x] 11.3 `bunx turbo test:coverage --filter=@suaveplan/i18n` — 100/100/100/100
|
||||
- [x] 11.4 `bun scripts/openspec-conformance.ts @suaveplan/i18n` — exit 0, no `error` findings
|
||||
- [x] 11.5 `bunx turbo build --filter=@suaveplan/i18n` — green
|
||||
|
||||
## 12. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
||||
|
||||
- [x] 12.1 Generics threaded; `expectTypeOf` assertions on `Backend.read` return type narrowing for typed message trees
|
||||
- [x] 12.2 Zod schemas wired at every public boundary (`HttpBackendOptionsSchema`, `StorageBackendOptionsSchema`, `MultiFileFsBackendOptionsSchema`, `ChainedBackendOptionsSchema`)
|
||||
- [x] 12.3 All four new error codes thrown from at least one production path
|
||||
- [x] 12.4 Strict-mode tested: `getAsync` rejection vs sync-get fallback paths
|
||||
- [x] 12.5 OTel histograms / counters / gauge emitted from production paths and asserted with a real in-memory `MeterProvider`
|
||||
- [x] 12.6 Lifecycle dedup: concurrent `preload(en, [auth])` calls trigger one backend read; concurrent `getAsync('auth:k')` calls trigger one backend read
|
||||
- [x] 12.7 No retroactive tick — every box reflects work done in this change
|
||||
|
||||
## 13. Archive
|
||||
|
||||
- [x] 13.1 Fold spec delta into `openspec/specs/i18n/spec.md`
|
||||
- [x] 13.2 Move `openspec/changes/i18n-storage-backends/` → `openspec/archive/<yyyy-mm-dd>-i18n-storage-backends/`
|
||||
- [x] 13.3 Refresh `MANIFEST.md` if dep set changed (`@suaveplan/storage` is a new dep)
|
||||
128
openspec/changes/archive/2026-05-04-network-core/proposal.md
Normal file
128
openspec/changes/archive/2026-05-04-network-core/proposal.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# OpenSpec Change: network-core
|
||||
|
||||
- **Change ID**: network-core
|
||||
- **Package**: `@suaveplan/network` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
Genesis has production-grade crypto (`crypto-cipher`), streams (`streams` with real AEAD + compression + framing), bitpacker, storage, and event-bus primitives — but no networking layer to compose them. The suaveplan `network` package exists in `../suaveplan/packages/universal/network` with the right architecture (plugin-based, hierarchical topology, governance, failover) but its transform layer contains documented stubs (fake encryption, fake compression, unimplemented ping). Rather than port the whole monolith, we extract the **core plugin architecture and abstractions** into a genesis-native package, then add real plugin packages that wire to genesis primitives.
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `NetworkPlugin` interface — universal contract for all network extensions (`name`, `install(node)`, `start()`, `stop()`, `dispose?()`).
|
||||
- **ADDED**: `NetworkNode` class — single entry-point that owns plugin lifecycle, message routing, and envelope validation.
|
||||
- **ADDED**: `MessageEnvelope` schema — Zod-validated envelope with `id`, `type`, `senderId`, `targetId`, `payload`, `timestamp`, `headers`.
|
||||
- **ADDED**: `Transport` interface — abstract contract for transport plugins (`connect`, `disconnect`, `send`, `onMessage`, `getConnectedPeers`).
|
||||
- **ADDED**: `NetworkBus` — typed pub/sub broker wrapping `@suaveplan/events` with bounded-queue backpressure and interceptors.
|
||||
- **ADDED**: `PluginManager` — installs plugins in registration order, starts them, stops them in reverse, disposes in reverse.
|
||||
- **ADDED**: `MessageRouter` — routes envelopes to transports (unicast by `targetId`, broadcast to all peers, fan-out across transports).
|
||||
- **ADDED**: `NETWORK_CODES` — frozen error registry (`defineCodes("NET", [...])`).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Concrete transport implementations → `network-plugin-webrtc`, `network-plugin-websocket` (deferred).
|
||||
- Governance/election logic → `network-plugin-governance`.
|
||||
- Peer registry / delta sync → `network-plugin-registry`.
|
||||
- Heartbeat / failover FSM → `network-plugin-failover`.
|
||||
- Tiered topology management → `network-plugin-topology`.
|
||||
- Signaling server → deferred; plugins accept a pluggable `SignalingClient` interface.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/network.md` and `../suaveplan/packages/universal/network/src/core/engine/`, `src/contracts/`, `src/plugin/`.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| Plugin lifecycle (install → start → stop → dispose) | `network/src/plugin/manager/manager.md` | verbatim contract |
|
||||
| NetworkNode unified API | `network/src/core/network/unified-node/network-node.md` | reworded; genesis uses `NetworkBus` instead of direct EventEmitter |
|
||||
| MessageEnvelope shape | `network/src/contracts/core.types.md` | extended with Zod schema |
|
||||
| Transport abstraction | `network/src/contracts/transport.types.md` | verbatim |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| Zod validation on every envelope | Genesis cross-cutting requirement per AGENTS.md |
|
||||
| `NetworkBus` wraps `@suaveplan/events` | Genesis already has a typed event bus; no need to invent a second one |
|
||||
| `PluginManager` reverse-order stop/dispose | Defensive programming not explicitly in source docs |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/plugin/plugin.spec-conformance.test.ts` — pins `NetworkPlugin` interface shape and lifecycle order.
|
||||
- `src/node/node.spec-conformance.test.ts` — pins `NetworkNode` public API, envelope validation, and plugin wiring.
|
||||
- `src/bus/bus.spec-conformance.test.ts` — pins `NetworkBus` FIFO, backpressure, interceptor behavior.
|
||||
- `src/router/router.spec-conformance.test.ts` — pins unicast, broadcast, and transport fan-out.
|
||||
- `src/envelope/envelope.spec-conformance.test.ts` — pins Zod schema rejections and valid envelope acceptance.
|
||||
- `tests/dep-graph.test.ts` — pins no circular deps, no external runtime deps beyond workspace.
|
||||
|
||||
## Enhancement: API Versioning Infrastructure
|
||||
|
||||
**Source**: `docs/old-network-planning/ADAPT_2.md` §API Versioning, `PHASE_0_IMPLEMENTATION_PLAN.md` §Version Info
|
||||
|
||||
The core needs versioning from the start to ensure interoperability as the mesh evolves:
|
||||
|
||||
- `VersionInfo` — semantic versioning with `major.minor.patch`. `isCompatibleWith(other)` checks same major and minor >= required.
|
||||
- `VersionManager` — tracks current library version, provides migration paths between versions, stability classification (`experimental`, `stable`, `deprecated`).
|
||||
- `VersionNegotiator` — exchanges versions during peer handshake. Rejects incompatible peers.
|
||||
- Version is embedded in `MessageEnvelope` headers.
|
||||
|
||||
## Enhancement: Network Timestamps
|
||||
|
||||
**Source**: `docs/old-network-planning/ADAPT_4.md` §Timestamp Handling
|
||||
|
||||
Cross-node operations require reliable time handling:
|
||||
|
||||
- `NetworkTimestamp` — standardized timestamp with multiple formats: ISO8601, unix, custom. Timezone support with adjustment. Precision levels: millisecond, microsecond, nanosecond.
|
||||
- `Clock` interface — injectable clock for testing. Default uses `performance.now()` or `Date.now()`.
|
||||
- `TimestampComparer` — `isAfter()`, `isBefore()`, `compare()` with timezone awareness.
|
||||
|
||||
## Enhancement: Standardized Event Constants
|
||||
|
||||
**Source**: `docs/old-network-planning/PHASE_0_IMPLEMENTATION_PLAN.md` §Event Constants
|
||||
|
||||
The bus uses string topics. Standardized constants prevent typos and enable IDE autocomplete:
|
||||
|
||||
- `NetworkEvents` — frozen enum of all standard bus topics:
|
||||
- Node lifecycle: `node:created`, `node:connected`, `node:disconnected`, `node:updated`, `node:removed`
|
||||
- Message: `message:sent`, `message:received`, `message:routed`, `message:dropped`
|
||||
- Hierarchy: `hierarchy:changed`, `hierarchy:parent-changed`, `hierarchy:child-added`, `hierarchy:child-removed`, `hierarchy:level-changed`
|
||||
- Plugin: `plugin:registered`, `plugin:unregistered`
|
||||
- System: `system:error`, `system:warning`, `system:info`
|
||||
|
||||
## Enhancement: Bootstrap and Cold Start
|
||||
|
||||
**Source**: `docs/old-network-planning/ADAPT_3.md` §Optimize Cold Start Procedure
|
||||
|
||||
The core must support fast initialization for first-time mesh joiners:
|
||||
|
||||
- `BootstrapOptions` — configurable bootstrap: `mode: 'aggressive' | 'balanced' | 'conservative'`, `initialPeers`, `bootstrapServers`, `connectionConcurrency`, `discoveryTimeout`, `prioritizeLocalNetwork`.
|
||||
- `NetworkNode.bootstrap(options)` — fast-path initialization that progressively discovers peers and forms hierarchy without blocking on full mesh state.
|
||||
- `ConnectionPreWarmer` — pre-opens transport connections to known peers before they are needed.
|
||||
- `StatePreLoader` — hydrates cached topology and registry state from previous session to skip full discovery.
|
||||
|
||||
## Enhancement: Transport Plugin Development Kit (PDK)
|
||||
|
||||
**Source**: `docs/old-network-planning/ADAPT_2.md` §Enhance Transport Plugin Framework
|
||||
|
||||
Third-party transport plugins need a standardized development kit:
|
||||
|
||||
- `BaseTransportPlugin` abstract class — implements common transport lifecycle (connect, disconnect, send, health tracking).
|
||||
- `TransportCapabilities` interface — `supportsDirect`, `supportsRelay`, `supportsBroadcast`, `maxMessageSize`, `reliabilityLevel`.
|
||||
- `TransportTester` — conformance test suite that any transport plugin can run: `testBasicFunctionality()`, `testReliability()`, `testBackpressure()`, `testReconnection()`.
|
||||
- `TransportBenchmark` — performance benchmark harness: throughput, latency, memory usage.
|
||||
- Plugin discovery — `PluginRegistry` supports runtime registration and lookup by capability.
|
||||
|
||||
## Enhancement: Plugin Registry and Discovery
|
||||
|
||||
**Source**: `docs/old-network-planning/ADAPT_5.md` §Develop Plugin Ecosystem Support
|
||||
|
||||
- `PluginRegistry` — runtime registry of installed plugins. `register(plugin)`, `unregister(id)`, `has(id)`, `get(id)`, `list()`.
|
||||
- `PluginDiscovery` — scans for available plugins by capability query: `findPluginsByCapability('state-sync')`.
|
||||
- `PluginCapabilityValidator` — verifies that a plugin's declared capabilities match its actual exports.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only. No consumers in genesis reference `@suaveplan/network` yet.
|
||||
86
openspec/changes/archive/2026-05-04-network-core/tasks.md
Normal file
86
openspec/changes/archive/2026-05-04-network-core/tasks.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Tasks — network-core
|
||||
|
||||
> Blocked on: none. Consumes existing genesis packages only.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network/` with `package.json` (`@suaveplan/network@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/streams`, `@suaveplan/bitpacker`, `@suaveplan/serialize`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 No external runtime deps beyond catalog.
|
||||
|
||||
## 2. Types and contracts
|
||||
|
||||
- [x] 2.1 `src/types/plugin.types.ts` — `NetworkPlugin`, `PluginContext`, `PluginLifecycle`.
|
||||
- [x] 2.2 `src/types/envelope.types.ts` — `MessageEnvelope`, `EnvelopeHeaders`, Zod schema.
|
||||
- [x] 2.3 `src/types/transport.types.ts` — `Transport`, `TransportConfig`, `PeerInfo`.
|
||||
- [x] 2.4 `src/types/node.types.ts` — `NetworkNodeConfig`, `NetworkNodeState`.
|
||||
- [x] 2.5 `src/error-codes.ts` — `defineCodes("NET", [...])` frozen registry.
|
||||
|
||||
## 3. Plugin manager
|
||||
|
||||
- [x] 3.1 `src/plugin/plugin-manager.ts` — `use(plugin)`, `installAll()`, `startAll()`, `stopAll()`, `disposeAll()` in correct order.
|
||||
- [x] 3.2 Lifecycle dedup: installing the same plugin twice is a no-op.
|
||||
|
||||
## 4. Network bus
|
||||
|
||||
- [x] 4.1 `src/bus/network-bus.ts` — wraps `@suaveplan/events` with topic-based routing, bounded queue, interceptors.
|
||||
- [x] 4.2 Topics: `peer:joined`, `peer:left`, `peer:latency`, `election:vote`, `election:completed`, `failover:triggered`, `message:received`, `topology:changed`.
|
||||
|
||||
## 5. Message router
|
||||
|
||||
- [x] 5.1 `src/router/message-router.ts` — `route(envelope)` resolves `targetId` to transport, `broadcast()` fans out to all transports.
|
||||
- [x] 5.2 `broadcast` skips the sender.
|
||||
|
||||
## 6. Network node
|
||||
|
||||
- [x] 6.1 `src/node/network-node.ts` — `use(plugin)`, `start()`, `stop()`, `send()`, `broadcast()`, `on(event)`.
|
||||
- [x] 6.2 Envelope validation via Zod before routing.
|
||||
- [x] 6.3 Idempotent `start()` / `stop()`.
|
||||
|
||||
## 7. Spec
|
||||
|
||||
- [x] 7.1 `openspec/specs/network/spec.md` — requirements `NET-01` through `NET-05` and `NET-12`.
|
||||
|
||||
## 8. Conformance tests
|
||||
|
||||
- [x] 8.1 `src/plugin/plugin.spec-conformance.test.ts` — lifecycle order, duplicate install no-op.
|
||||
- [x] 8.2 `src/node/node.spec-conformance.test.ts` — send, broadcast, envelope validation, plugin wiring.
|
||||
- [x] 8.3 `src/bus/bus.spec-conformance.test.ts` — FIFO, backpressure, interceptor.
|
||||
- [x] 8.4 `src/router/router.spec-conformance.test.ts` — unicast, broadcast, skip-sender.
|
||||
- [x] 8.5 `src/envelope/envelope.spec-conformance.test.ts` — Zod accept/reject.
|
||||
- [x] 8.6 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
- [x] 8.7 `tests/dep-graph.test.ts` — no cycles, tree-shake clean.
|
||||
|
||||
## 10. API versioning
|
||||
|
||||
- [x] 10.1 `src/versioning/version-info.ts` — `VersionInfo`, semantic versioning, compatibility check.
|
||||
- [x] 10.2 `src/versioning/version-manager.ts` — `VersionManager`, migration paths, stability classification.
|
||||
- [x] 10.3 `src/versioning/version-negotiator.ts` — `VersionNegotiator`, exchanges versions during handshake.
|
||||
- [x] 10.4 Version embedded in `MessageEnvelope` headers.
|
||||
|
||||
## 11. Network timestamps
|
||||
|
||||
- [x] 11.1 `src/timing/network-timestamp.ts` — `NetworkTimestamp`, ISO8601/unix/custom, timezone, precision.
|
||||
- [x] 11.2 `src/timing/clock.ts` — `Clock` interface, injectable for testing.
|
||||
- [x] 11.3 `src/timing/timestamp-comparer.ts` — `TimestampComparer`, `isAfter`, `isBefore`, `compare`.
|
||||
|
||||
## 12. Standardized event constants
|
||||
|
||||
- [x] 12.1 `src/events/network-events.ts` — `NetworkEvents`, frozen enum of all standard bus topics.
|
||||
- [x] 12.2 Node lifecycle, message, hierarchy, plugin, system topics.
|
||||
|
||||
## 13. Spec
|
||||
|
||||
- [x] 13.1 Update `openspec/specs/network/spec.md` with `NET-53`, `NET-54`, `NET-55`.
|
||||
|
||||
## 14. Conformance tests
|
||||
|
||||
- [x] 14.1 `src/versioning/versioning.spec-conformance.test.ts` — compatibility, negotiation, rejection.
|
||||
- [x] 14.2 `src/timing/timing.spec-conformance.test.ts` — formats, timezone, precision, comparison.
|
||||
- [x] 14.3 `src/events/events.spec-conformance.test.ts` — constants, no typos, coverage.
|
||||
|
||||
## 15. Verify
|
||||
|
||||
- [x] 15.1 `bunx turbo lint typecheck test --filter=@suaveplan/network` green.
|
||||
- [x] 15.2 `bunx turbo test:coverage --filter=@suaveplan/network` 100/100/100/100.
|
||||
- [x] 15.3 `bun scripts/openspec-conformance.ts @suaveplan/network` PASS.
|
||||
@@ -0,0 +1,203 @@
|
||||
# OpenSpec Change: network-plugin-assignment
|
||||
|
||||
- **Change ID**: network-plugin-assignment
|
||||
- **Package**: `@suaveplan/network-plugin-assignment` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-01
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Implement mesh auto-assignment and load balancing. When a new peer connects to the system, there is currently no algorithm to decide which mesh it should join. This plugin provides the "placement layer": tracking mesh capacity across the fleet, scoring candidate meshes for a new peer, rebalancing peers when meshes become overloaded, and admitting or rejecting connections based on global capacity.
|
||||
|
||||
This is a P0 gap blocking the user's stated requirement: *"automatically place a new connection in a tiered mesh with available spaces."*
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
**User requirement**: *"automatically place a new connection in a tiered mesh with available spaces"*
|
||||
|
||||
**Current state**: `enterprise-network-assignment` (dated 2026-04-24) provides consistent hashing and rendezvous hashing for **peer selection within a mesh**. It does NOT assign a new peer **to a mesh**.
|
||||
|
||||
**What's missing**:
|
||||
|
||||
- Mesh capacity tracking across the fleet
|
||||
- Algorithm for placing a new peer into the "best" mesh (latency, geography, capacity, load)
|
||||
- Rebalancing when meshes become imbalanced
|
||||
- Handling of "mesh full" scenarios
|
||||
|
||||
---
|
||||
|
||||
## Core components
|
||||
|
||||
### 1. `MeshCapacityTracker`
|
||||
|
||||
Consumes `peer:joined` / `peer:left` / `peer:updated` events from `network-plugin-registry` to maintain a live view of `currentPeers / maxPeers` per mesh.
|
||||
|
||||
```ts
|
||||
class MeshCapacityTracker {
|
||||
recordMesh(meshId: string, maxPeers: number): void;
|
||||
recordJoin(meshId: string, peerId: string): void;
|
||||
recordLeave(meshId: string, peerId: string): void;
|
||||
getUtilization(meshId: string): number; // 0.0 – 1.0
|
||||
getAvailableSlots(meshId: string): number;
|
||||
listMeshes(): string[];
|
||||
on(event: "mesh:full" | "mesh:available", handler: (meshId: string) => void): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. `AssignmentEngine`
|
||||
|
||||
Scores candidate meshes for a new peer and returns the best assignment.
|
||||
|
||||
```ts
|
||||
interface PeerInfo {
|
||||
peerId: string;
|
||||
latencyMap: Map<string, number>; // meshId → RTT ms
|
||||
region?: string;
|
||||
tierEligibility: number; // max tier this peer can reach (0, 1, 2)
|
||||
capabilities: DeviceProfile; // CONSTRAINED, STANDARD, POWERFUL, SERVER
|
||||
}
|
||||
|
||||
interface AssignmentScore {
|
||||
meshId: string;
|
||||
score: number; // higher is better
|
||||
factors: {
|
||||
latencyScore: number;
|
||||
capacityScore: number;
|
||||
loadScore: number;
|
||||
regionScore: number;
|
||||
tierFitScore: number;
|
||||
};
|
||||
}
|
||||
|
||||
class AssignmentEngine {
|
||||
constructor(options: {
|
||||
tracker: MeshCapacityTracker;
|
||||
weights: AssignmentWeights; // configurable
|
||||
minScoreThreshold: number;
|
||||
});
|
||||
assign(peer: PeerInfo): AssignmentScore | null; // null = no suitable mesh
|
||||
rankCandidates(peer: PeerInfo): AssignmentScore[];
|
||||
}
|
||||
```
|
||||
|
||||
**Scoring factors** (weights sum to 1.0, configurable):
|
||||
|
||||
- **Latency** (default 0.30): lower RTT to mesh host = higher score
|
||||
- **Capacity** (default 0.25): more available slots = higher score
|
||||
- **Load** (default 0.20): lower current CPU/bandwidth load = higher score
|
||||
- **Region** (default 0.15): same region as peer = higher score
|
||||
- **Tier fit** (default 0.10): mesh needs peers of this peer's capability level
|
||||
|
||||
**Fallback**: If all meshes are full, the engine returns `null`. The caller (`AdmissionController`) may then trigger mesh creation or reject the peer.
|
||||
|
||||
### 3. `MeshBalancer`
|
||||
|
||||
Periodic rebalancer that moves peers from overloaded meshes to underloaded ones.
|
||||
|
||||
```ts
|
||||
class MeshBalancer {
|
||||
constructor(options: {
|
||||
tracker: MeshCapacityTracker;
|
||||
imbalanceThreshold: number; // e.g. 0.20 = 20% variance triggers rebalance
|
||||
rebalanceIntervalMs: number;
|
||||
maxMovesPerCycle: number;
|
||||
});
|
||||
start(): void;
|
||||
stop(): void;
|
||||
evaluate(): RebalancePlan[];
|
||||
executePlan(plan: RebalancePlan): Promise<void>;
|
||||
}
|
||||
|
||||
interface RebalancePlan {
|
||||
peerId: string;
|
||||
fromMeshId: string;
|
||||
toMeshId: string;
|
||||
reason: string;
|
||||
}
|
||||
```
|
||||
|
||||
Rebalancing is **cooperative**: the target mesh must accept the peer, and the peer must confirm the move. Uses `network-plugin-migration` for the actual state transfer.
|
||||
|
||||
### 4. `AdmissionController`
|
||||
|
||||
Gatekeeper that accepts or rejects incoming peer connections.
|
||||
|
||||
```ts
|
||||
class AdmissionController {
|
||||
constructor(options: {
|
||||
engine: AssignmentEngine;
|
||||
balancer: MeshBalancer;
|
||||
allowMeshCreation: boolean; // if true, creates new mesh when all full
|
||||
globalMaxPeers: number;
|
||||
});
|
||||
admit(peer: PeerInfo): AdmissionResult;
|
||||
}
|
||||
|
||||
interface AdmissionResult {
|
||||
accepted: boolean;
|
||||
meshId?: string;
|
||||
reason?: string;
|
||||
alternativeMeshIds?: string[]; // ranked alternatives if primary is full
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error codes
|
||||
|
||||
```ts
|
||||
const ASSIGN_CODES = defineCodes("ASSIGN", [
|
||||
"MESH_FULL",
|
||||
"NO_MESH_AVAILABLE",
|
||||
"GLOBAL_CAPACITY_EXCEEDED",
|
||||
"PEER_REJECTED",
|
||||
"REBALANCE_FAILED",
|
||||
"TRACKER_SYNC_ERROR",
|
||||
"INVALID_PEER_INFO",
|
||||
] as const);
|
||||
```
|
||||
|
||||
`AssignmentError extends SuaveplanError<AssignmentErrorCode>`.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Consumes**: `@suaveplan/network` (`NetworkNode`, `NetworkBus`), `@suaveplan/network-plugin-registry` (peer events for capacity tracking), `@suaveplan/network-plugin-topology` (tier eligibility, region data), `@suaveplan/network-plugin-relay` (cross-mesh routing for rebalanced peers), `@suaveplan/network-plugin-migration` (state transfer during rebalance), `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`.
|
||||
- **Blocked on**: `network-core` (shipped), `network-plugin-registry`, `network-plugin-topology`.
|
||||
|
||||
---
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/tracker/tracker.spec-conformance.test.ts` — pins capacity tracking, utilization math, full/available events.
|
||||
- `src/engine/engine.spec-conformance.test.ts` — pins scoring algorithm, weights, fallback behaviour, tier fit.
|
||||
- `src/balancer/balancer.spec-conformance.test.ts` — pins imbalance detection, plan generation, maxMovesPerCycle.
|
||||
- `src/controller/controller.spec-conformance.test.ts` — pins admit/reject paths, global capacity enforcement.
|
||||
- `tests/integration/assignment.spec-conformance.test.ts` — end-to-end: 3 meshes, 10 peers, verify balanced distribution.
|
||||
- Property-based test: random peer latencies/regions/capabilities → assignment is deterministic for same inputs.
|
||||
- 100/100/100/100 Istanbul coverage.
|
||||
|
||||
---
|
||||
|
||||
## Conformance requirements (proposed)
|
||||
|
||||
- `NET-71` — `MeshCapacityTracker` tracks `currentPeers / maxPeers` per mesh from registry events.
|
||||
- `NET-72` — `AssignmentEngine` scores candidate meshes using latency, capacity, load, region, and tier fit.
|
||||
- `NET-73` — `AssignmentEngine` returns `null` when no suitable mesh is found.
|
||||
- `NET-74` — `MeshBalancer` detects imbalance and generates `RebalancePlan` objects.
|
||||
- `NET-75` — `AdmissionController` rejects peers when global capacity is exceeded.
|
||||
- `NET-76` — `AdmissionController` returns ranked alternative meshes when the primary mesh is full.
|
||||
- `NET-77` — Rebalancing triggers `network-plugin-migration` for peer state transfer.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Global DHT for mesh discovery** → handled by `network-plugin-relay` `MeshDirectory`.
|
||||
- **Forced peer eviction** → v2; v1 only does cooperative rebalancing.
|
||||
- **Real-time load metrics (CPU/bandwidth)** → consumes from `network-plugin-monitor` when available; v1 uses peer count as load proxy.
|
||||
@@ -0,0 +1,18 @@
|
||||
# Tasks: network-plugin-assignment
|
||||
|
||||
- [x] 1. Write `openspec/changes/network-plugin-assignment/proposal.md`
|
||||
- [x] 2. Write `openspec/changes/network-plugin-assignment/tasks.md`
|
||||
- [x] 3. Scaffold `packages/network/network-plugin-assignment/package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 4. Implement `src/error-codes.ts` with `ASSIGN_CODES`
|
||||
- [x] 5. Implement `src/tracker/mesh-capacity-tracker.ts` — consume registry events, track utilization
|
||||
- [x] 6. Implement `src/engine/assignment-engine.ts` — scoring algorithm, weights, ranking
|
||||
- [x] 7. Implement `src/balancer/mesh-balancer.ts` — imbalance detection, plan generation
|
||||
- [x] 8. Implement `src/controller/admission-controller.ts` — admit/reject gatekeeper
|
||||
- [x] 9. Write `src/tracker/tracker.spec-conformance.test.ts`
|
||||
- [x] 10. Write `src/engine/engine.spec-conformance.test.ts`
|
||||
- [x] 11. Write `src/balancer/balancer.spec-conformance.test.ts`
|
||||
- [x] 12. Write `src/controller/controller.spec-conformance.test.ts`
|
||||
- [x] 13. Write `tests/integration/assignment.spec-conformance.test.ts`
|
||||
- [x] 14. Write property-based tests for scoring determinism
|
||||
- [x] 15. Write `tests/dep-graph.test.ts`
|
||||
- [x] 16. Run `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-assignment` and achieve 100/100/100/100 coverage
|
||||
@@ -0,0 +1,188 @@
|
||||
# OpenSpec Change: network-plugin-auth
|
||||
|
||||
- **Change ID**: network-plugin-auth
|
||||
- **Package**: `@suaveplan/network-plugin-auth` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-01
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Implement mesh membership authentication and cross-mesh relay authorization. The `auth` package exists in genesis (`@suaveplan/auth`) but provides generic OAuth/JWT/session primitives. There is no mesh-specific authentication: verifying that a peer is allowed to join a specific mesh, issuing capability tokens that constrain which tiers a peer can occupy, or validating trust relationships between meshes for relay traffic. This plugin bridges `@suaveplan/auth` into the mesh architecture.
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
**Current state**: `network-plugin-crypto-messages` signs messages with Ed25519 and verifies server-signed session/mesh tokens. However, there is no authentication of the peer itself before it joins a mesh, no capability-based tier assignment, and no cross-mesh relay trust validation.
|
||||
|
||||
**What's missing**:
|
||||
|
||||
- Peer authentication before joining a mesh
|
||||
- Mesh capability tokens (who can be Tier 0 vs Tier 1 vs Tier 2)
|
||||
- Cross-mesh relay authorization (which meshes trust each other)
|
||||
- Message integrity at relay hops
|
||||
|
||||
---
|
||||
|
||||
## Core components
|
||||
|
||||
### 1. `MeshMembershipVerifier`
|
||||
|
||||
Verifies that a peer is authorized to join a mesh.
|
||||
|
||||
```ts
|
||||
class MeshMembershipVerifier {
|
||||
constructor(options: {
|
||||
authProvider: AuthProvider; // from @suaveplan/auth
|
||||
meshId: string;
|
||||
serverPubKey: Uint8Array;
|
||||
});
|
||||
verifyJoinRequest(request: JoinRequest): Promise<JoinResult>;
|
||||
}
|
||||
|
||||
interface JoinRequest {
|
||||
peerId: string;
|
||||
meshId: string;
|
||||
authToken: string; // JWT or opaque token from @suaveplan/auth
|
||||
publicKey: Uint8Array; // Ed25519 public key for future message verification
|
||||
claimedCapabilities: Capability[];
|
||||
}
|
||||
|
||||
interface JoinResult {
|
||||
accepted: boolean;
|
||||
peerId: string;
|
||||
assignedTier: number; // 0, 1, or 2
|
||||
capabilityToken: CapabilityToken;
|
||||
reason?: string;
|
||||
}
|
||||
```
|
||||
|
||||
**Verification steps**:
|
||||
|
||||
1. Validate `authToken` via `@suaveplan/auth`.
|
||||
2. Check that `publicKey` matches the identity in `authToken`.
|
||||
3. Verify `claimedCapabilities` against the mesh's allowed capability set.
|
||||
4. Issue a `CapabilityToken` signed by the server that constrains the peer's tier and permissions.
|
||||
|
||||
### 2. `CapabilityTokenIssuer`
|
||||
|
||||
Issues and validates capability tokens for mesh operations.
|
||||
|
||||
```ts
|
||||
interface CapabilityToken {
|
||||
peerId: string;
|
||||
meshId: string;
|
||||
tier: number; // max tier this peer can occupy
|
||||
capabilities: Capability[];
|
||||
issuedAt: number;
|
||||
expiresAt: number;
|
||||
serverSignature: Uint8Array;
|
||||
}
|
||||
|
||||
enum Capability {
|
||||
HOST = "host", // can be Tier 0
|
||||
SUBHOST = "subhost", // can be Tier 1
|
||||
RELAY = "relay", // can act as intra-mesh relay
|
||||
BRIDGE = "bridge", // can act as cross-mesh relay backbone
|
||||
AUDIT = "audit", // can write to audit log
|
||||
CREATE_SESSION = "create_session",
|
||||
JOIN_SESSION = "join_session",
|
||||
}
|
||||
|
||||
class CapabilityTokenIssuer {
|
||||
constructor(options: {
|
||||
serverKeyPair: Ed25519KeyPair;
|
||||
defaultTtlMs: number; // default 3600000 (1 hour)
|
||||
});
|
||||
issue(peerId: string, meshId: string, tier: number, capabilities: Capability[]): CapabilityToken;
|
||||
validate(token: CapabilityToken): boolean;
|
||||
renew(token: CapabilityToken): CapabilityToken;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. `CrossMeshTrustValidator`
|
||||
|
||||
Validates trust relationships between meshes for relay traffic.
|
||||
|
||||
```ts
|
||||
class CrossMeshTrustValidator {
|
||||
constructor(options: {
|
||||
trustStore: TrustStore; // meshId → trusted meshId set
|
||||
serverPubKey: Uint8Array;
|
||||
});
|
||||
validateRelay(sourceMeshId: string, targetMeshId: string): boolean;
|
||||
validateBackbone(hostId: string, meshId: string): boolean;
|
||||
addTrust(fromMeshId: string, toMeshId: string): void;
|
||||
removeTrust(fromMeshId: string, toMeshId: string): void;
|
||||
}
|
||||
|
||||
interface TrustStore {
|
||||
getTrustedMeshes(meshId: string): string[];
|
||||
isTrusted(fromMeshId: string, toMeshId: string): boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**Trust model**:
|
||||
|
||||
- By default, meshes do NOT trust each other.
|
||||
- Trust is established by the central server signing a `MeshTrustToken` that authorizes relay between two meshes.
|
||||
- Tier 0 hosts verify `MeshTrustToken` before accepting backbone connections from another mesh's host.
|
||||
- `CrossMeshTrustValidator` caches trust decisions with TTL (default 5 minutes).
|
||||
|
||||
---
|
||||
|
||||
## Error codes
|
||||
|
||||
```ts
|
||||
const MESH_AUTH_CODES = defineCodes("MESH_AUTH", [
|
||||
"JOIN_REJECTED",
|
||||
"TOKEN_EXPIRED",
|
||||
"TOKEN_INVALID_SIGNATURE",
|
||||
"CAPABILITY_DENIED",
|
||||
"TIER_NOT_ALLOWED",
|
||||
"TRUST_NOT_ESTABLISHED",
|
||||
"BACKBONE_UNTRUSTED",
|
||||
"AUTH_PROVIDER_ERROR",
|
||||
] as const);
|
||||
```
|
||||
|
||||
`MeshAuthError extends SuaveplanError<MeshAuthErrorCode>`.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Consumes**: `@suaveplan/network` (`NetworkNode`, `NetworkBus`), `@suaveplan/auth` (JWT validation, session management), `@suaveplan/network-plugin-crypto-messages` (Ed25519 signatures, server tokens), `@suaveplan/network-plugin-registry` (peer public keys), `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`.
|
||||
- **Blocked on**: `network-core` (shipped), `network-plugin-crypto-messages`, `@suaveplan/auth`.
|
||||
|
||||
---
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/verifier/verifier.spec-conformance.test.ts` — pins join request validation, tier assignment, capability checks.
|
||||
- `src/issuer/issuer.spec-conformance.test.ts` — pins token issue/validate/renew, signature verification, expiry.
|
||||
- `src/trust/trust-validator.spec-conformance.test.ts` — pins trust store, relay validation, backbone validation, cache TTL.
|
||||
- `tests/integration/auth.spec-conformance.test.ts` — end-to-end: peer joins mesh, receives capability token, relay is validated.
|
||||
- 100/100/100/100 Istanbul coverage.
|
||||
|
||||
---
|
||||
|
||||
## Conformance requirements (proposed)
|
||||
|
||||
- `NET-106` — `MeshMembershipVerifier` validates `authToken` via `@suaveplan/auth` before allowing mesh join.
|
||||
- `NET-107` — `MeshMembershipVerifier` checks that the peer's `publicKey` matches the identity in `authToken`.
|
||||
- `NET-108` — `CapabilityTokenIssuer` issues tokens signed by the server that constrain tier and capabilities.
|
||||
- `NET-109` — `CapabilityToken` includes `peerId`, `meshId`, `tier`, `capabilities`, `issuedAt`, `expiresAt`, and `serverSignature`.
|
||||
- `NET-110` — `CrossMeshTrustValidator` rejects relay between meshes unless a trust relationship is established.
|
||||
- `NET-111` — `CrossMeshTrustValidator` caches trust decisions with a configurable TTL.
|
||||
- `NET-112` — Tier 0 hosts verify `MeshTrustToken` before accepting backbone connections.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Fine-grained ACL per message type** → v2; v1 uses capability tokens.
|
||||
- **Revocation lists** → v2; v1 relies on short token expiry.
|
||||
- **Zero-knowledge proofs** → future research.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Tasks: network-plugin-auth
|
||||
|
||||
- [x] 1. Write `openspec/changes/network-plugin-auth/proposal.md`
|
||||
- [x] 2. Write `openspec/changes/network-plugin-auth/tasks.md`
|
||||
- [x] 3. Scaffold `packages/network/network-plugin-auth/package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 4. Implement `src/error-codes.ts` with `MESH_AUTH_CODES`
|
||||
- [x] 5. Implement `src/verifier/mesh-membership-verifier.ts` — join validation, tier assignment
|
||||
- [x] 6. Implement `src/issuer/capability-token-issuer.ts` — token issue/validate/renew
|
||||
- [x] 7. Implement `src/trust/cross-mesh-trust-validator.ts` — trust store, relay/backbone validation
|
||||
- [x] 8. Write `src/verifier/verifier.spec-conformance.test.ts`
|
||||
- [x] 9. Write `src/issuer/issuer.spec-conformance.test.ts`
|
||||
- [x] 10. Write `src/trust/trust-validator.spec-conformance.test.ts`
|
||||
- [x] 11. Write `tests/integration/auth.spec-conformance.test.ts`
|
||||
- [x] 12. Write `tests/dep-graph.test.ts`
|
||||
- [x] 13. Run `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-auth` and achieve 100/100/100/100 coverage
|
||||
@@ -0,0 +1,166 @@
|
||||
# OpenSpec Change: network-plugin-circuit-breaker
|
||||
|
||||
- **Change ID**: network-plugin-circuit-breaker
|
||||
- **Package**: `@suaveplan/network-plugin-circuit-breaker` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-01
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Implement circuit breakers at mesh boundaries. `@suaveplan/retry` provides per-request retry with exponential backoff, but there is no circuit breaker on cross-mesh relay paths. If Mesh A's Tier 0 host cannot reach Mesh B's Tier 0 host, repeated retries waste bandwidth, delay failure detection, and can cascade load onto alternative paths. A circuit breaker allows fast-fail and graceful degradation.
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
**Current state**: `@suaveplan/retry` exists but no circuit breaker is integrated at the mesh level. The `enterprise-network-standby-transport` proposal has transport-level failover but no mesh-level circuit breaking.
|
||||
|
||||
**Why this matters**: In a multi-mesh federation:
|
||||
|
||||
- A dead host on a relay path causes every cross-mesh message to retry N times before failing.
|
||||
- Without a circuit breaker, the mesh cannot distinguish between "slow" and "dead" quickly.
|
||||
- Cascading retries can saturate the remaining healthy paths.
|
||||
|
||||
---
|
||||
|
||||
## Core components
|
||||
|
||||
### 1. `MeshCircuitBreaker`
|
||||
|
||||
Per-path circuit breaker state machine: `CLOSED` → `OPEN` → `HALF_OPEN`.
|
||||
|
||||
```ts
|
||||
class MeshCircuitBreaker {
|
||||
constructor(options: {
|
||||
pathId: string; // e.g. "meshA:host1→meshB:host2"
|
||||
failureThreshold: number; // default 5
|
||||
successThreshold: number; // default 3
|
||||
openDurationMs: number; // default 30000
|
||||
halfOpenMaxCalls: number; // default 3
|
||||
});
|
||||
getState(): "CLOSED" | "OPEN" | "HALF_OPEN";
|
||||
recordSuccess(): void;
|
||||
recordFailure(): void;
|
||||
canExecute(): boolean;
|
||||
on(event: "state:changed", handler: (state: string) => void): void;
|
||||
}
|
||||
```
|
||||
|
||||
**States**:
|
||||
|
||||
- `CLOSED`: Normal operation. Failures are counted. When `failureThreshold` is reached → `OPEN`.
|
||||
- `OPEN`: All executions are rejected immediately (fast-fail). After `openDurationMs` → `HALF_OPEN`.
|
||||
- `HALF_OPEN`: A limited number (`halfOpenMaxCalls`) of trial executions are allowed. If `successThreshold` successes occur → `CLOSED`. If any failure → `OPEN`.
|
||||
|
||||
### 2. `CircuitBreakerRegistry`
|
||||
|
||||
Manages circuit breakers for all relay paths in the mesh.
|
||||
|
||||
```ts
|
||||
class CircuitBreakerRegistry {
|
||||
getOrCreate(pathId: string, options?: CircuitBreakerOptions): MeshCircuitBreaker;
|
||||
getState(pathId: string): "CLOSED" | "OPEN" | "HALF_OPEN" | undefined;
|
||||
remove(pathId: string): void;
|
||||
listOpenPaths(): string[];
|
||||
}
|
||||
```
|
||||
|
||||
### 3. `HalfOpenProbe`
|
||||
|
||||
Sends lightweight probe messages during `HALF_OPEN` to test path health without risking real traffic.
|
||||
|
||||
```ts
|
||||
class HalfOpenProbe {
|
||||
constructor(options: {
|
||||
registry: CircuitBreakerRegistry;
|
||||
probeIntervalMs: number; // default 5000
|
||||
probeMessageFactory: () => MessageEnvelope;
|
||||
});
|
||||
start(): void;
|
||||
stop(): void;
|
||||
}
|
||||
```
|
||||
|
||||
Probes are ping-like messages with `type: "relay:probe"` and expect an ack. They do not carry application payload.
|
||||
|
||||
### 4. `CircuitBreakerMiddleware`
|
||||
|
||||
Integrates with `network-plugin-relay` by wrapping `HostBackboneTransport.send()`:
|
||||
|
||||
```ts
|
||||
function createCircuitBreakerMiddleware(
|
||||
registry: CircuitBreakerRegistry
|
||||
): RelayMiddleware {
|
||||
return {
|
||||
beforeSend(envelope, nextHopHostId) {
|
||||
const pathId = buildPathId(localHostId, nextHopHostId);
|
||||
const cb = registry.getOrCreate(pathId);
|
||||
if (!cb.canExecute()) {
|
||||
throw new CircuitBreakerError(CB.PATH_OPEN, { pathId });
|
||||
}
|
||||
try {
|
||||
const result = next();
|
||||
cb.recordSuccess();
|
||||
return result;
|
||||
} catch (err) {
|
||||
cb.recordFailure();
|
||||
throw err;
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error codes
|
||||
|
||||
```ts
|
||||
const CB_CODES = defineCodes("CB", [
|
||||
"PATH_OPEN",
|
||||
"PATH_HALF_OPEN_REJECTED",
|
||||
"PROBE_FAILED",
|
||||
"REGISTRY_PATH_NOT_FOUND",
|
||||
] as const);
|
||||
```
|
||||
|
||||
`CircuitBreakerError extends SuaveplanError<CircuitBreakerErrorCode>`.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Consumes**: `@suaveplan/network` (`NetworkBus`, `MessageEnvelope`), `@suaveplan/network-plugin-relay` (`HostBackboneTransport`, `RelayManager`), `@suaveplan/retry` (for underlying retry policy configuration), `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`.
|
||||
- **Blocked on**: `network-core` (shipped), `network-plugin-relay`.
|
||||
|
||||
---
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/breaker/breaker.spec-conformance.test.ts` — pins CLOSED→OPEN→HALF_OPEN→CLOSED transition, threshold behaviour.
|
||||
- `src/registry/registry.spec-conformance.test.ts` — pins getOrCreate, listOpenPaths, removal.
|
||||
- `src/probe/probe.spec-conformance.test.ts` — pins probe emission, ack handling, failure counting.
|
||||
- `src/middleware/middleware.spec-conformance.test.ts` — pins relay middleware integration, fast-fail on OPEN.
|
||||
- 100/100/100/100 Istanbul coverage.
|
||||
|
||||
---
|
||||
|
||||
## Conformance requirements (proposed)
|
||||
|
||||
- `NET-84` — `MeshCircuitBreaker` transitions from `CLOSED` to `OPEN` after `failureThreshold` consecutive failures.
|
||||
- `NET-85` — `MeshCircuitBreaker` transitions from `OPEN` to `HALF_OPEN` after `openDurationMs`.
|
||||
- `NET-86` — `MeshCircuitBreaker` transitions from `HALF_OPEN` to `CLOSED` after `successThreshold` consecutive successes.
|
||||
- `NET-87` — `MeshCircuitBreaker` in `OPEN` state rejects all executions immediately.
|
||||
- `NET-88` — `HalfOpenProbe` sends lightweight probe messages during `HALF_OPEN`.
|
||||
- `NET-89` — `CircuitBreakerRegistry` manages per-path circuit breakers.
|
||||
- `NET-90` — Circuit breaker middleware wraps `HostBackboneTransport.send()` and records success/failure.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Adaptive thresholds** → v2; v1 uses fixed configuration.
|
||||
- **ML-based anomaly detection** → v2.
|
||||
- **Per-peer circuit breakers** → handled by `@suaveplan/retry` at the transport layer; this plugin focuses on mesh-boundary paths.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Tasks: network-plugin-circuit-breaker
|
||||
|
||||
- [x] 1. Write `openspec/changes/network-plugin-circuit-breaker/proposal.md`
|
||||
- [x] 2. Write `openspec/changes/network-plugin-circuit-breaker/tasks.md`
|
||||
- [x] 3. Scaffold `packages/network/network-plugin-circuit-breaker/package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 4. Implement `src/error-codes.ts` with `CB_CODES`
|
||||
- [x] 5. Implement `src/breaker/mesh-circuit-breaker.ts` — state machine, transitions
|
||||
- [x] 6. Implement `src/registry/circuit-breaker-registry.ts` — per-path registry
|
||||
- [x] 7. Implement `src/probe/half-open-probe.ts` — probe messages, acks
|
||||
- [x] 8. Implement `src/middleware/circuit-breaker-middleware.ts` — relay middleware integration
|
||||
- [x] 9. Write `src/breaker/breaker.spec-conformance.test.ts`
|
||||
- [x] 10. Write `src/registry/registry.spec-conformance.test.ts`
|
||||
- [x] 11. Write `src/probe/probe.spec-conformance.test.ts`
|
||||
- [x] 12. Write `src/middleware/middleware.spec-conformance.test.ts`
|
||||
- [x] 13. Write `tests/dep-graph.test.ts`
|
||||
- [x] 14. Run `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-circuit-breaker` and achieve 100/100/100/100 coverage
|
||||
@@ -0,0 +1,56 @@
|
||||
# OpenSpec Change: network-plugin-failover
|
||||
|
||||
- **Change ID**: network-plugin-failover
|
||||
- **Package**: `@suaveplan/network-plugin-failover` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
The tiered network requires automatic recovery when a host (Tier 0) fails. The genesis `retry`, `fsm`, and `rate-limiter` packages provide primitives, but no plugin implements the host-failure detection, state transition, and emergency-election trigger. This plugin fills that gap by consuming peer health events from the bus and coordinating the `alive → suspect → dead → recovering` lifecycle.
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `FailoverPlugin` class implementing `NetworkPlugin`.
|
||||
- **ADDED**: `FailoverCoordinator` — tracks peer health, manages state transitions, triggers elections.
|
||||
- **ADDED**: `HeartbeatManager` — sends periodic heartbeats, collects responses, detects timeout.
|
||||
- **ADDED**: `HealthMonitor` — maintains `alive | suspect | dead | recovering` states with configurable timeouts.
|
||||
- **ADDED**: `PromoterManager` — when a host is declared dead, triggers an emergency election via `GovernancePlugin` events.
|
||||
- **ADDED**: `NETWORK_FO_CODES` — frozen error registry.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Persistent state of failover log → future `network-plugin-failover-persistence`.
|
||||
- Cross-group failover federation → future scope.
|
||||
- Network partition detection (split-brain) → handled by `network-plugin-partition`. Failover manages single-host death (alive→suspect→dead). Partition manages group isolation (split-brain). The two plugins are complementary: failover emits heartbeat events that partition consumes for connectivity-map analysis.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/network-failover.md` and `../suaveplan/packages/universal/network-failover/`.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| Host failure detection (alive→suspect→dead) | `network-failover/README.md` §Failure Detection | verbatim |
|
||||
| Heartbeat interval and timeout | `network-failover/README.md` §Configuration | verbatim |
|
||||
| Automatic election trigger on dead host | `network-failover/README.md` §Automatic Recovery | verbatim |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| Consumes `peer:connected`/`peer:disconnected` from bus | Decouples failover from transport implementation |
|
||||
| Emits `failover:emergency-election` on bus | Loose coupling to governance plugin — no direct import |
|
||||
| Uses `@suaveplan/rate-limiter` to throttle heartbeat bursts | Defensive — prevents self-DOS during mass disconnect |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/failover/failover.spec-conformance.test.ts` — pins state transitions, timeout, election trigger.
|
||||
- `src/heartbeat/heartbeat.spec-conformance.test.ts` — pins interval, response, timeout.
|
||||
- `src/health/health.spec-conformance.test.ts` — pins alive→suspect→dead→recovering.
|
||||
- `src/promoter/promoter.spec-conformance.test.ts` — pins emergency election emission.
|
||||
- `tests/dep-graph.test.ts` — pins no direct import of governance or transport packages.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Tasks — network-plugin-failover
|
||||
|
||||
> Blocked on: `network-core`, `network-plugin-governance`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-failover/` with `package.json` (`@suaveplan/network-plugin-failover@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/fsm`, `@suaveplan/rate-limiter`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/health.types.ts` — `HealthState`, `HealthConfig`, `PeerHealth`.
|
||||
- [x] 2.2 `src/types/heartbeat.types.ts` — `HeartbeatFrame`, `HeartbeatConfig`.
|
||||
- [x] 2.3 `src/types/failover.types.ts` — `FailoverConfig`, `FailoverEvent`.
|
||||
- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_FO", [...])`.
|
||||
|
||||
## 3. Heartbeat manager
|
||||
|
||||
- [x] 3.1 `src/heartbeat/heartbeat-manager.ts` — sends periodic heartbeats to all peers.
|
||||
- [x] 3.2 Configurable interval and timeout.
|
||||
- [x] 3.3 Correlates echo with sequence numbers.
|
||||
- [x] 3.4 Uses `@suaveplan/rate-limiter` to throttle burst sends.
|
||||
|
||||
## 4. Health monitor
|
||||
|
||||
- [x] 4.1 `src/health/health-monitor.ts` — per-peer health state machine.
|
||||
- [x] 4.2 States: `alive → suspect → dead → recovering`.
|
||||
- [x] 4.3 Transitions on missed heartbeats (configurable thresholds).
|
||||
- [x] 4.4 Emits `health:state-change` on `NetworkBus`.
|
||||
|
||||
## 5. Promoter manager
|
||||
|
||||
- [x] 5.1 `src/promoter/promoter-manager.ts` — triggers emergency election.
|
||||
- [x] 5.2 On `dead` state, emits `failover:emergency-election` on bus.
|
||||
- [x] 5.3 Debounces to prevent duplicate triggers.
|
||||
|
||||
## 6. Failover coordinator
|
||||
|
||||
- [x] 6.1 `src/failover/failover-coordinator.ts` — orchestrates heartbeat, health, promoter.
|
||||
- [x] 6.2 Consumes `peer:connected`, `peer:disconnected`, `health:state-change` from bus.
|
||||
- [x] 6.3 Publishes `failover:emergency-election`, `health:state-change`.
|
||||
|
||||
## 7. Plugin wrapper
|
||||
|
||||
- [x] 7.1 `src/plugin/failover-plugin.ts` — `FailoverPlugin` implements `NetworkPlugin`.
|
||||
- [x] 7.2 Installs heartbeat, health, promoter, coordinator on `install()`.
|
||||
|
||||
## 8. Spec
|
||||
|
||||
- [x] 8.1 Update `openspec/specs/network/spec.md` with `NET-10`, `NET-11`.
|
||||
|
||||
## 9. Conformance tests
|
||||
|
||||
- [x] 9.1 `src/failover/failover.spec-conformance.test.ts` — state transitions, timeout, election trigger.
|
||||
- [x] 9.2 `src/heartbeat/heartbeat.spec-conformance.test.ts` — interval, response, timeout.
|
||||
- [x] 9.3 `src/health/health.spec-conformance.test.ts` — alive→suspect→dead→recovering.
|
||||
- [x] 9.4 `src/promoter/promoter.spec-conformance.test.ts` — emergency election emission, debounce.
|
||||
- [x] 9.5 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 10. Verify
|
||||
|
||||
- [x] 10.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-failover` green.
|
||||
- [x] 10.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-failover` 100/100/100/100.
|
||||
- [x] 10.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-failover` PASS.
|
||||
@@ -0,0 +1,77 @@
|
||||
# OpenSpec Change: network-plugin-governance
|
||||
|
||||
- **Change ID**: network-plugin-governance
|
||||
- **Package**: `@suaveplan/network-plugin-governance` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
The tiered network design requires small groups to nominate a host dynamically. The genesis `fsm` package provides state machines, `retry` provides backoff, and `events` provides the bus — but there is no plugin that orchestrates elections, scores candidates, and manages host transitions. This plugin fills that gap. It consumes latency data from `network-plugin-webrtc` (via bus), runs elections, and publishes the winner so `network-plugin-topology` can promote the node to Tier 0.
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `GovernancePlugin` class implementing `NetworkPlugin`.
|
||||
- **ADDED**: `ElectionEngine` — orchestrates election rounds: initiates, collects votes, computes winner, publishes result.
|
||||
- **ADDED**: `CandidateScorer` — weighted multi-criteria scoring: latency (inverse), uptime, bandwidth, and reputation. Reputation decays over time.
|
||||
- **ADDED**: `VotingManager` — collects votes via `NetworkBus`, tallies, detects quorum.
|
||||
- **ADDED**: `VoteSession` — encapsulates a single vote round with configurable topics, voting periods, participation thresholds, and consensus requirements. Lifecycle: `creation → voting → tallying → result publication`.
|
||||
- **ADDED**: `TransitionManager` — host handover lifecycle: `idle → preparing → transferring → confirming → completed` (or `failed`).
|
||||
- **ADDED**: `HostSelector` — historical trust-based scoring system. Evaluates candidates using weighted multi-factor evaluation (latency, stability, uptime, capabilities, trust score). Tracks historical hosting performance via `HostHistory` to improve future selections. Enforces stability thresholds and consensus validation before confirming a host.
|
||||
- **ADDED**: `HostHistory` — append-only record of successful/unsuccessful hosting sessions per peer. Used by `HostSelector` to compute trust scores.
|
||||
- **ADDED**: `ReputationTracker` — per-peer reputation with success/failure/violation scoring and configurable decay.
|
||||
- **ADDED**: Election modes: `metric` (score-based), `direct` (vote tally), `hybrid` (score + votes).
|
||||
- **ADDED**: `NETWORK_GOV_CODES` — frozen error registry.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Byzantine fault tolerance beyond simple reputation scoring → future hardening change.
|
||||
- Cryptographic vote signing → future `network-plugin-governance-crypto`.
|
||||
- Global consensus across many groups → each group runs its own election; federation is deferred.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/network-governance.md` and `../suaveplan/packages/universal/network-governance/`.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| Election modes (metric/direct/hybrid) | `network-governance/README.md` §Election Modes | verbatim |
|
||||
| Candidate scoring with weights | `network-governance/README.md` §Scoring | verbatim |
|
||||
| Transition lifecycle FSM | `network-governance/README.md` §Transition Lifecycle | reworded; uses `@suaveplan/fsm` |
|
||||
| Reputation tracking with decay | `network-governance/README.md` §Reputation Tracking | verbatim |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| Consumes `peer:latency` from bus | Required for metric-mode scoring without direct coupling to webrtc plugin |
|
||||
| `TransitionManager` uses `@suaveplan/fsm` | Genesis already has a production FSM; no need to hand-roll state transitions |
|
||||
| Quorum detection | Defensive — prevents declaring a winner with too few participants |
|
||||
|
||||
## Enhancement: Voting System Details
|
||||
|
||||
**Source**: `docs/old-network-planning/PHASE_4.md` §Voting System
|
||||
|
||||
- `VoteSession` — configurable topics (host selection, config changes, tier promotions).
|
||||
- Configurable voting periods and participation thresholds.
|
||||
- Result determination with configurable consensus requirements (simple majority, supermajority, unanimous).
|
||||
- `VoteSession` lifecycle: creation → voting → tallying → result publication.
|
||||
- Vote validation against session rules (e.g. only Tier 0/1 peers may vote on host selection).
|
||||
- Tamper-proof tallying — votes are signed by peers; tally is reproducible.
|
||||
- Secure voting verification — any peer can verify the published tally against individual vote signatures.
|
||||
- Vote history tracking — append-only log of all votes for audit (consumed by `network-plugin-audit-mesh`).
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/election/election.spec-conformance.test.ts` — pins all three modes, quorum, tiebreaking.
|
||||
- `src/scoring/scoring.spec-conformance.test.ts` — pins weighted criteria, reputation decay.
|
||||
- `src/transition/transition.spec-conformance.test.ts` — pins FSM states and rollback on failure.
|
||||
- `src/voting/voting.spec-conformance.test.ts` — pins vote collection, tally, duplicate rejection, session lifecycle.
|
||||
- `src/vote-session/vote-session.spec-conformance.test.ts` — pins configurable topics, thresholds, consensus requirements, vote validation.
|
||||
- `src/reputation/reputation.spec-conformance.test.ts` — pins success/failure/violation scoring and decay.
|
||||
- `tests/dep-graph.test.ts` — pins no direct import of webrtc or transport packages.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Tasks — network-plugin-governance
|
||||
|
||||
> Blocked on: `network-core`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-governance/` with `package.json` (`@suaveplan/network-plugin-governance@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/fsm`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/election.types.ts` — `ElectionMode`, `ElectionConfig`, `ElectionResult`.
|
||||
- [x] 2.2 `src/types/candidate.types.ts` — `Candidate`, `CandidateScore`, `ScoringWeights`.
|
||||
- [x] 2.3 `src/types/transition.types.ts` — `TransitionState`, `TransitionConfig`.
|
||||
- [x] 2.4 `src/types/reputation.types.ts` — `ReputationScore`, `ReputationEvent`.
|
||||
- [x] 2.5 `src/error-codes.ts` — `defineCodes("NET_GOV", [...])`.
|
||||
|
||||
## 3. Candidate scorer
|
||||
|
||||
- [x] 3.1 `src/scoring/candidate-scorer.ts` — `CandidateScorer` with weighted criteria.
|
||||
- [x] 3.2 Formula: `score = Σ(weightᵢ × normalize(metricᵢ))`.
|
||||
- [x] 3.3 Metrics: latency (inverse), uptime, bandwidth, reputation.
|
||||
- [x] 3.4 Tiebreaking: deterministic by peerId hash.
|
||||
|
||||
## 4. Reputation tracker
|
||||
|
||||
- [x] 4.1 `src/reputation/reputation-tracker.ts` — `ReputationTracker`.
|
||||
- [x] 4.2 Events: `success`, `failure`, `violation`.
|
||||
- [x] 4.3 Exponential decay: `scoreₜ = scoreₜ₋₁ × α` where α configurable.
|
||||
|
||||
## 5. Voting manager
|
||||
|
||||
- [x] 5.1 `src/voting/voting-manager.ts` — collects votes over `NetworkBus`.
|
||||
- [x] 5.2 Deduplication by `peerId`.
|
||||
- [x] 5.3 Quorum detection: configurable fraction of known peers.
|
||||
|
||||
## 6. Election engine
|
||||
|
||||
- [x] 6.1 `src/election/election-engine.ts` — `ElectionEngine`.
|
||||
- [x] 6.2 Modes: `metric` (score only), `direct` (vote tally), `hybrid` (score × vote weight).
|
||||
- [x] 6.3 Emits `election:result` on `NetworkBus` with `winnerId`, `mode`, `score`.
|
||||
|
||||
## 7. Transition manager
|
||||
|
||||
- [x] 7.1 `src/transition/transition-manager.ts` — host handover FSM using `@suaveplan/fsm`.
|
||||
- [x] 7.2 States: `idle → preparing → transferring → confirming → completed | failed`.
|
||||
- [x] 7.3 Emits `transition:state-change` on bus.
|
||||
- [x] 7.4 On `failed`, rolls back to `idle` and emits `transition:failed`.
|
||||
|
||||
## 8. Plugin wrapper
|
||||
|
||||
- [x] 8.1 `src/plugin/governance-plugin.ts` — `GovernancePlugin` implements `NetworkPlugin`.
|
||||
- [x] 8.2 Subscribes to `peer:latency`, `peer:disconnected` on bus.
|
||||
- [x] 8.3 Installs election, scorer, voting, transition, and reputation managers.
|
||||
|
||||
## 9. Spec
|
||||
|
||||
- [x] 9.1 Update `openspec/specs/network/spec.md` with `NET-08`, `NET-09`.
|
||||
|
||||
## 10. Conformance tests
|
||||
|
||||
- [x] 10.1 `src/election/election.spec-conformance.test.ts` — all three modes, quorum, tiebreaking.
|
||||
- [x] 10.2 `src/scoring/scoring.spec-conformance.test.ts` — weighted criteria, reputation decay.
|
||||
- [x] 10.3 `src/transition/transition.spec-conformance.test.ts` — FSM states, rollback on failure.
|
||||
- [x] 10.4 `src/voting/voting.spec-conformance.test.ts` — vote collection, tally, duplicate rejection.
|
||||
- [x] 10.5 `src/reputation/reputation.spec-conformance.test.ts` — success/failure/violation, decay.
|
||||
- [x] 10.6 `src/backpressure/backpressure.spec-conformance.test.ts` — not applicable (N/A).
|
||||
- [x] 10.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 11. Verify
|
||||
|
||||
- [x] 11.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-governance` green.
|
||||
- [x] 11.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-governance` 100/100/100/100.
|
||||
- [x] 11.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-governance` PASS.
|
||||
@@ -0,0 +1,178 @@
|
||||
# OpenSpec Change: network-plugin-migration
|
||||
|
||||
- **Change ID**: network-plugin-migration
|
||||
- **Package**: `@suaveplan/network-plugin-migration` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-01
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Implement peer state migration between meshes. When `network-plugin-assignment` rebalances a peer from an overloaded mesh to an underloaded one, or when a peer manually requests to join a different mesh, there is currently no mechanism to transfer state or maintain message continuity during the handoff. This plugin provides the migration protocol: state snapshot transfer, graceful handoff with a forwarding tunnel, and session persistence across mesh boundaries.
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
**User requirement**: *"automatically place a new connection in a tiered mesh with available spaces"* implies rebalancing, which implies migration.
|
||||
|
||||
**Current state**: No migration logic exists anywhere in the network suite.
|
||||
|
||||
**What's missing**:
|
||||
|
||||
- State transfer when a peer moves from Mesh A to Mesh B
|
||||
- Graceful handoff: old host forwards messages to new host during transition
|
||||
- Session persistence across mesh boundaries
|
||||
|
||||
---
|
||||
|
||||
## Core components
|
||||
|
||||
### 1. `MigrationCoordinator`
|
||||
|
||||
Orchestrates the end-to-end migration flow.
|
||||
|
||||
```ts
|
||||
class MigrationCoordinator {
|
||||
constructor(options: {
|
||||
localPeerId: string;
|
||||
localMeshId: string;
|
||||
bus: NetworkBus;
|
||||
});
|
||||
initiateMigration(request: MigrationRequest): Promise<MigrationResult>;
|
||||
acceptMigration(request: MigrationRequest): Promise<MigrationResult>;
|
||||
}
|
||||
|
||||
interface MigrationRequest {
|
||||
peerId: string;
|
||||
fromMeshId: string;
|
||||
toMeshId: string;
|
||||
reason: string; // e.g. "rebalance", "user-request", "region-optimization"
|
||||
priority: "graceful" | "urgent";
|
||||
}
|
||||
|
||||
interface MigrationResult {
|
||||
success: boolean;
|
||||
peerId: string;
|
||||
newMeshId: string;
|
||||
transferredBytes: number;
|
||||
durationMs: number;
|
||||
forwardedMessages: number;
|
||||
}
|
||||
```
|
||||
|
||||
**Migration flow**:
|
||||
|
||||
1. **Request** — `MigrationCoordinator` sends `migration:request` to the target mesh's assignment controller.
|
||||
2. **Accept** — Target mesh admits the peer via `AdmissionController`.
|
||||
3. **Snapshot** — Old host serializes peer state (registry entry, topology position, session memberships) and sends it to the new host.
|
||||
4. **Transfer** — New host installs the peer into its local registry and topology.
|
||||
5. **Tunnel** — Old host starts a forwarding tunnel for messages addressed to the migrating peer.
|
||||
6. **Cutover** — Peer disconnects from old mesh and connects to new mesh.
|
||||
7. **Drain** — Old host drains the forwarding tunnel (default 30s or until empty).
|
||||
8. **Complete** — Old host removes peer from its registry. `migration:completed` is emitted on both meshes' buses.
|
||||
|
||||
### 2. `StateTransferProtocol`
|
||||
|
||||
Serializes and deserializes peer state for migration.
|
||||
|
||||
```ts
|
||||
class StateTransferProtocol {
|
||||
serialize(peerId: string, registry: RegistrySnapshot, topology: TopologyPosition, sessions: SessionMembership[]): Uint8Array;
|
||||
deserialize(bytes: Uint8Array): PeerStateSnapshot;
|
||||
}
|
||||
|
||||
interface PeerStateSnapshot {
|
||||
peerId: string;
|
||||
registryEntry: PeerRegistryEntry;
|
||||
topologyPosition: TopologyPosition;
|
||||
sessionMemberships: SessionMembership[];
|
||||
version: number; // monotonic, for conflict detection
|
||||
}
|
||||
```
|
||||
|
||||
Uses `@suaveplan/bitpacker` for compact binary encoding. Max snapshot size: 64 KiB (peers with larger state must use lazy rehydration).
|
||||
|
||||
### 3. `ForwardingTunnel`
|
||||
|
||||
Temporary message forwarding from old host to new host during cutover.
|
||||
|
||||
```ts
|
||||
class ForwardingTunnel {
|
||||
constructor(options: {
|
||||
fromHostId: string;
|
||||
toHostId: string;
|
||||
peerId: string;
|
||||
relay: RelayManager; // from network-plugin-relay
|
||||
drainTimeoutMs: number; // default 30000
|
||||
maxBufferedMessages: number; // default 1000
|
||||
});
|
||||
open(): void;
|
||||
close(): Promise<void>;
|
||||
forward(envelope: MessageEnvelope): void;
|
||||
getBufferedCount(): number;
|
||||
}
|
||||
```
|
||||
|
||||
**Behaviour**:
|
||||
|
||||
- All messages addressed to `peerId` that arrive at the old host are forwarded to the new host via `RelayManager`.
|
||||
- If the buffer exceeds `maxBufferedMessages`, oldest messages are dropped (application is notified).
|
||||
- After `drainTimeoutMs`, the tunnel is closed regardless of buffer state.
|
||||
- `ForwardingTunnel` is only used for `graceful` migrations. `urgent` migrations skip the tunnel and accept message loss.
|
||||
|
||||
---
|
||||
|
||||
## Error codes
|
||||
|
||||
```ts
|
||||
const MIGRATE_CODES = defineCodes("MIGRATE", [
|
||||
"TARGET_MESH_REJECTED",
|
||||
"STATE_TRANSFER_FAILED",
|
||||
"TUNNEL_OVERFLOW",
|
||||
"TUNNEL_TIMEOUT",
|
||||
"CUTOVER_FAILED",
|
||||
"MIGRATION_ABORTED",
|
||||
"INVALID_SNAPSHOT",
|
||||
] as const);
|
||||
```
|
||||
|
||||
`MigrationError extends SuaveplanError<MigrationErrorCode>`.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Consumes**: `@suaveplan/network` (`NetworkNode`, `NetworkBus`), `@suaveplan/network-plugin-relay` (`RelayManager`, cross-mesh forwarding), `@suaveplan/network-plugin-assignment` (`AdmissionController`, `MeshBalancer`), `@suaveplan/network-plugin-registry` (`RegistrySnapshot`), `@suaveplan/network-plugin-topology` (`TopologyPosition`), `@suaveplan/network-plugin-session` (`SessionMembership`), `@suaveplan/bitpacker` (snapshot encoding), `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`.
|
||||
- **Blocked on**: `network-core` (shipped), `network-plugin-relay`, `network-plugin-assignment`, `network-plugin-registry`, `network-plugin-topology`, `network-plugin-session`.
|
||||
|
||||
---
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/coordinator/coordinator.spec-conformance.test.ts` — pins full migration flow: request → accept → snapshot → transfer → tunnel → cutover → drain.
|
||||
- `src/state-transfer/state-transfer.spec-conformance.test.ts` — pins serialize/deserialize roundtrip, version tracking, size limits.
|
||||
- `src/tunnel/forwarding-tunnel.spec-conformance.test.ts` — pins buffer limits, overflow drop, drain timeout.
|
||||
- `tests/integration/migration.spec-conformance.test.ts` — end-to-end: peer moves from Mesh A to Mesh B, messages continue to arrive.
|
||||
- 100/100/100/100 Istanbul coverage.
|
||||
|
||||
---
|
||||
|
||||
## Conformance requirements (proposed)
|
||||
|
||||
- `NET-99` — `MigrationCoordinator` executes a 8-step migration flow (request, accept, snapshot, transfer, tunnel, cutover, drain, complete).
|
||||
- `NET-100` — `StateTransferProtocol` serializes peer registry, topology, and session state using `@suaveplan/bitpacker`.
|
||||
- `NET-101` — `ForwardingTunnel` buffers messages for the migrating peer and forwards them to the new host.
|
||||
- `NET-102` — `ForwardingTunnel` drops oldest messages when buffer exceeds `maxBufferedMessages`.
|
||||
- `NET-103` — `ForwardingTunnel` closes after `drainTimeoutMs` regardless of buffer state.
|
||||
- `NET-104` — `urgent` migrations skip the forwarding tunnel and accept message loss.
|
||||
- `NET-105` — `migration:completed` is emitted on both the source and target mesh buses.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Live migration without disconnect** → v2; v1 requires a brief disconnect/cutover.
|
||||
- **Migration of in-flight game state** → application-level; v1 transfers session memberships only.
|
||||
- **Rollback on failure** → v2; v1 reports failure and leaves application to retry.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Tasks: network-plugin-migration
|
||||
|
||||
- [x] 1. Write `openspec/changes/network-plugin-migration/proposal.md`
|
||||
- [x] 2. Write `openspec/changes/network-plugin-migration/tasks.md`
|
||||
- [x] 3. Scaffold `packages/network/network-plugin-migration/package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 4. Implement `src/error-codes.ts` with `MIGRATE_CODES`
|
||||
- [x] 5. Implement `src/coordinator/migration-coordinator.ts` — 8-step migration flow
|
||||
- [x] 6. Implement `src/state-transfer/state-transfer-protocol.ts` — snapshot serialize/deserialize
|
||||
- [x] 7. Implement `src/tunnel/forwarding-tunnel.ts` — buffer, forward, drain
|
||||
- [x] 8. Write `src/coordinator/coordinator.spec-conformance.test.ts`
|
||||
- [x] 9. Write `src/state-transfer/state-transfer.spec-conformance.test.ts`
|
||||
- [x] 10. Write `src/tunnel/forwarding-tunnel.spec-conformance.test.ts`
|
||||
- [x] 11. Write `tests/integration/migration.spec-conformance.test.ts`
|
||||
- [x] 12. Write `tests/dep-graph.test.ts`
|
||||
- [x] 13. Run `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-migration` and achieve 100/100/100/100 coverage
|
||||
@@ -0,0 +1,183 @@
|
||||
# OpenSpec Change: network-plugin-partition
|
||||
|
||||
- **Change ID**: network-plugin-partition
|
||||
- **Package**: `@suaveplan/network-plugin-partition` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-01
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Implement split-brain detection and resolution for the mesh. The `network-plugin-failover` proposal explicitly excludes network partition detection: *"Network partition detection (split-brain) → future hardening change."* This plugin fills that exclusion. Without it, a network partition can cause:
|
||||
|
||||
- Duplicate hosts in the same mesh
|
||||
- Messages routed to the wrong partition
|
||||
- Infinite relay loops across partitioned meshes
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
**Current state**: `network-plugin-failover` handles host death (alive → suspect → dead) but does not detect when the mesh splits into two or more isolated groups, each believing it is the authoritative partition.
|
||||
|
||||
**Why this matters**: In a multi-mesh system with relay, split-brain can cause:
|
||||
|
||||
- Two Tier 0 hosts both claiming to be the primary host for the same mesh
|
||||
- `network-plugin-relay` forwarding messages into a partition that has diverged
|
||||
- `network-plugin-registry` peers replicating to hosts that are no longer reachable
|
||||
|
||||
---
|
||||
|
||||
## Core components
|
||||
|
||||
### 1. `PartitionDetector`
|
||||
|
||||
Detects network partitions using vector clocks or epoch numbers.
|
||||
|
||||
```ts
|
||||
class PartitionDetector {
|
||||
constructor(options: {
|
||||
heartbeatSource: HeartbeatSource; // consumes from failover plugin
|
||||
meshId: string;
|
||||
quorumRatio: number; // default 0.5 (majority)
|
||||
epochIntervalMs: number; // default 5000
|
||||
});
|
||||
start(): void;
|
||||
stop(): void;
|
||||
getCurrentEpoch(): number;
|
||||
getPartitionView(): PartitionView;
|
||||
}
|
||||
|
||||
interface PartitionView {
|
||||
epoch: number;
|
||||
knownPeers: string[];
|
||||
reachablePeers: string[];
|
||||
isPartitioned: boolean;
|
||||
partitionId: string; // deterministic hash of reachable set
|
||||
primary: boolean; // true if this partition believes it is the primary
|
||||
}
|
||||
```
|
||||
|
||||
**Detection strategy**:
|
||||
|
||||
- Each peer emits an `epoch` heartbeat every `epochIntervalMs`.
|
||||
- Peers track the highest epoch they've seen from every other peer.
|
||||
- If a peer misses epochs from a majority of known peers for `suspectThreshold * 2`, a partition is suspected.
|
||||
- `PartitionView.partitionId` is a deterministic hash (e.g. BLAKE3) of the sorted reachable peer set.
|
||||
- Two peers with different `partitionId` values are in different partitions.
|
||||
|
||||
### 2. `QuorumResolver`
|
||||
|
||||
Determines which partition is authoritative when split-brain is detected.
|
||||
|
||||
```ts
|
||||
class QuorumResolver {
|
||||
constructor(options: {
|
||||
strategy: QuorumStrategy; // "size" | "performance" | "age" | "hybrid"
|
||||
});
|
||||
resolve(partitions: PartitionView[]): PartitionView | null; // null = cannot resolve
|
||||
}
|
||||
|
||||
type QuorumStrategy = "size" | "performance" | "age" | "hybrid";
|
||||
```
|
||||
|
||||
**Strategies**:
|
||||
|
||||
- `size`: the partition with the most peers wins.
|
||||
- `performance`: the partition with the lowest aggregate latency / highest bandwidth wins.
|
||||
- `age`: the partition containing the oldest-established host wins.
|
||||
- `hybrid`: weighted composite of size (0.4), performance (0.4), age (0.2).
|
||||
|
||||
### 3. `MergeProtocol`
|
||||
|
||||
Reconciles diverged state when partitions heal.
|
||||
|
||||
```ts
|
||||
class MergeProtocol {
|
||||
constructor(options: {
|
||||
registryReconciler: RegistryReconciler;
|
||||
topologyReconciler: TopologyReconciler;
|
||||
auditReconciler: AuditReconciler;
|
||||
});
|
||||
initiateMerge(localView: PartitionView, remoteView: PartitionView): Promise<MergeResult>;
|
||||
}
|
||||
|
||||
interface MergeResult {
|
||||
success: boolean;
|
||||
mergedRegistry: PeerRegistrySnapshot;
|
||||
mergedTopology: TopologySnapshot;
|
||||
conflicts: MergeConflict[];
|
||||
}
|
||||
```
|
||||
|
||||
**Merge steps**:
|
||||
|
||||
1. Exchange `PartitionView` and validate epoch sequences.
|
||||
2. Compare registry snapshots: add missing peers, remove stale entries.
|
||||
3. Compare topology: re-run host election if both partitions had a Tier 0 host.
|
||||
4. Replay audit logs from the non-authoritative partition into the authoritative one.
|
||||
5. Emit `partition:healed` on the `NetworkBus`.
|
||||
|
||||
---
|
||||
|
||||
## Integration with failover
|
||||
|
||||
`network-plugin-partition` consumes heartbeat data from `network-plugin-failover` via the `NetworkBus`:
|
||||
|
||||
- Listens to `failover:triggered` events — if multiple hosts trigger failover simultaneously, partition is suspected.
|
||||
- Does NOT replace failover; it complements it. Failover handles single-host death; partition handles group isolation.
|
||||
|
||||
---
|
||||
|
||||
## Error codes
|
||||
|
||||
```ts
|
||||
const PARTITION_CODES = defineCodes("PARTITION", [
|
||||
"SPLIT_BRAIN_DETECTED",
|
||||
"QUORUM_NOT_REACHED",
|
||||
"MERGE_CONFLICT",
|
||||
"MERGE_FAILED",
|
||||
"EPOCH_SYNC_ERROR",
|
||||
"INVALID_PARTITION_VIEW",
|
||||
"PARTITION_HEAL_TIMEOUT",
|
||||
] as const);
|
||||
```
|
||||
|
||||
`PartitionError extends SuaveplanError<PartitionErrorCode>`.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Consumes**: `@suaveplan/network` (`NetworkNode`, `NetworkBus`), `@suaveplan/network-plugin-failover` (heartbeat events, FSM states), `@suaveplan/network-plugin-registry` (registry snapshots), `@suaveplan/network-plugin-topology` (topology snapshots), `@suaveplan/network-plugin-audit-mesh` (audit log replay), `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`.
|
||||
- **Blocked on**: `network-core` (shipped), `network-plugin-failover`, `network-plugin-registry`, `network-plugin-topology`.
|
||||
|
||||
---
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/detector/detector.spec-conformance.test.ts` — pins epoch tracking, partition detection, reachable-set hashing.
|
||||
- `src/quorum/quorum.spec-conformance.test.ts` — pins all four quorum strategies, tie-breaking.
|
||||
- `src/merge/merge.spec-conformance.test.ts` — pins registry merge, topology merge, conflict reporting.
|
||||
- `tests/integration/partition.spec-conformance.test.ts` — end-to-end: simulate partition, detect, resolve, heal.
|
||||
- 100/100/100/100 Istanbul coverage.
|
||||
|
||||
---
|
||||
|
||||
## Conformance requirements (proposed)
|
||||
|
||||
- `NET-78` — `PartitionDetector` tracks epochs from all known peers and detects partition when a majority is unreachable.
|
||||
- `NET-79` — `PartitionView.partitionId` is a deterministic hash of the sorted reachable peer set.
|
||||
- `NET-80` — `QuorumResolver` supports `size`, `performance`, `age`, and `hybrid` strategies.
|
||||
- `NET-81` — `MergeProtocol` reconciles registry, topology, and audit state when partitions heal.
|
||||
- `NET-82` — Non-authoritative partition peers rejoin the authoritative partition after merge.
|
||||
- `NET-83` — `partition:detected` and `partition:healed` events are emitted on the `NetworkBus`.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Byzantine fault tolerance** → v2; v1 assumes honest peers.
|
||||
- **Automatic partition creation** → v2; v1 pauses new mesh operations during partition.
|
||||
- **Cross-mesh partition detection** → handled by `network-plugin-relay` loop prevention; this plugin focuses on intra-mesh splits.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Tasks: network-plugin-partition
|
||||
|
||||
- [x] 1. Write `openspec/changes/network-plugin-partition/proposal.md`
|
||||
- [x] 2. Write `openspec/changes/network-plugin-partition/tasks.md`
|
||||
- [x] 3. Scaffold `packages/network/network-plugin-partition/package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 4. Implement `src/error-codes.ts` with `PARTITION_CODES`
|
||||
- [x] 5. Implement `src/detector/partition-detector.ts` — epoch tracking, reachable-set hashing
|
||||
- [x] 6. Implement `src/quorum/quorum-resolver.ts` — size/performance/age/hybrid strategies
|
||||
- [x] 7. Implement `src/merge/merge-protocol.ts` — registry, topology, audit reconciliation
|
||||
- [x] 8. Write `src/detector/detector.spec-conformance.test.ts`
|
||||
- [x] 9. Write `src/quorum/quorum.spec-conformance.test.ts`
|
||||
- [x] 10. Write `src/merge/merge.spec-conformance.test.ts`
|
||||
- [x] 11. Write `tests/integration/partition.spec-conformance.test.ts`
|
||||
- [x] 12. Write `tests/dep-graph.test.ts`
|
||||
- [x] 13. Run `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-partition` and achieve 100/100/100/100 coverage
|
||||
@@ -0,0 +1,97 @@
|
||||
# OpenSpec Change: network-plugin-protocol
|
||||
|
||||
- **Change ID**: network-plugin-protocol
|
||||
- **Package**: `@suaveplan/network-plugin-protocol` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
The tiered network needs a compact, versioned binary protocol for all messages between peers. The genesis `bitpacker` package provides the binary serialization, and `serialize` provides schemas. This plugin implements a 13-byte header + binary payload format that replaces the suaveplan `network-protocol` stub. It integrates with the `streams` transforms for real encryption, compression, and framing.
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `ProtocolPlugin` class implementing `NetworkPlugin`.
|
||||
- **ADDED**: `BinaryProtocol` — 13-byte header: `version(1) | flags(1) | messageType(1) | timestamp(8) | payloadLength(2)`.
|
||||
- **ADDED**: `MessageEncoder` / `MessageDecoder` — schema-aware encoding/decoding using `@suaveplan/bitpacker`.
|
||||
- **ADDED**: `ProtocolPipeline` — wires `lengthPrefixEncode` → `CryptoTransform` → `compressStream` for outgoing, and reverse for incoming.
|
||||
- **ADDED**: `FastPathDispatcher` — zero-copy fast path for common message types (heartbeat, ping, registry delta). Bypasses full pipeline when message type is in the fast-path allowlist and no encryption/compression is required.
|
||||
- **ADDED**: `NETWORK_PROTO_CODES` — frozen error registry.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Protocol negotiation / version handshake → future `network-plugin-protocol-negotiation`.
|
||||
- Custom message types beyond registry/governance/topology/failover → future plugins register their own.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/network-protocol.md` and `../suaveplan/packages/universal/network-protocol/`.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| 13-byte binary header | `network-protocol/README.md` §Binary Protocol | verbatim |
|
||||
| Version, flags, messageType, timestamp, payloadLength | `network-protocol/README.md` §Binary Protocol | verbatim |
|
||||
| Schema-aware encoding | `network-protocol/README.md` §Message Encoder/Decoder | reworded; uses `@suaveplan/bitpacker` |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| `ProtocolPipeline` using `streams` transforms | Genesis has real crypto/compression/framing; protocol should use them |
|
||||
| `ProtocolPlugin` implements `NetworkPlugin` | Required to plug into `NetworkNode` |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/protocol/protocol.spec-conformance.test.ts` — pins header format, version, flags.
|
||||
- `src/encoder/encoder.spec-conformance.test.ts` — pins schema encoding, roundtrip.
|
||||
- `src/pipeline/pipeline.spec-conformance.test.ts` — pins pipeline ordering, error handling.
|
||||
- `tests/dep-graph.test.ts` — pins direct import of `@suaveplan/bitpacker`, `@suaveplan/streams`.
|
||||
|
||||
## Enhancement: Serialization Strategy Framework
|
||||
|
||||
**Source**: `docs/old-network-planning/PHASE_9.md` §Serialization Strategies
|
||||
|
||||
The protocol plugin currently assumes a single binary encoding. The old docs defined multiple serialization strategies with a factory pattern:
|
||||
|
||||
- **JSON Serializer** — human-readable, widely compatible
|
||||
- **Binary Serializer** — compact, schema-based, optional compression
|
||||
- **MessagePack Serializer** — compact binary with extensions
|
||||
- **Protocol Buffers Serializer** — schema-based with versioning
|
||||
- **SerializerFactory** — selects serializer by content type with fallback
|
||||
|
||||
**Added to this change**:
|
||||
|
||||
- `SerializerFactory` — registers serializers by content type, returns default on unknown.
|
||||
- `JsonSerializer`, `BinarySerializer`, `MessagePackSerializer` — implement `ISerializer`.
|
||||
- Content-type negotiation in 13-byte header flags.
|
||||
|
||||
## Enhancement: Message Priority Queue & Adaptive Batching
|
||||
|
||||
**Source**: `docs/old-network-planning/PHASE_3.md` §PriorityMessageQueue, `DESCRIPTION.md` §Adaptive Batching
|
||||
|
||||
The protocol needs explicit message queueing and batching:
|
||||
|
||||
- `PriorityMessageQueue` — multiple internal queues (one per priority tier). FIFO within same tier. CRITICAL messages bypass queue.
|
||||
- `MessageBatcher` — groups related messages by type/recipient. Flushes on size, time, or priority trigger. Adaptive interval based on network conditions.
|
||||
- `BackpressureController` — detects overwhelmed downstream and slows production.
|
||||
|
||||
## Enhancement: Message TTL & Loop Detection
|
||||
|
||||
**Source**: `docs/old-network-planning/PHASE_3.md` §Message Expiration
|
||||
|
||||
- `MessageTTL` — time-to-live in hops. Drops message when `ttl <= 0`.
|
||||
- `LoopDetector` — tracks `visitedNodes` in envelope header. Drops on cycle detection.
|
||||
- `DuplicateDetector` — deduplicates broadcast messages via `messageId` + bloom filter.
|
||||
|
||||
## Enhancement: Route Caching
|
||||
|
||||
**Source**: `docs/old-network-planning/PHASE_3.md` §Route Caching
|
||||
|
||||
- `RouteCache` — caches frequently used `(source, target) → nextHop` mappings.
|
||||
- Cache invalidation on `topology:changed` bus event.
|
||||
- Adaptive cache size based on memory availability.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only.
|
||||
@@ -0,0 +1,98 @@
|
||||
# Tasks — network-plugin-protocol
|
||||
|
||||
> Blocked on: `network-core`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-protocol/` with `package.json` (`@suaveplan/network-plugin-protocol@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/bitpacker`, `@suaveplan/streams`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/protocol.types.ts` — `ProtocolHeader`, `ProtocolMessage`, `MessageType`.
|
||||
- [x] 2.2 `src/types/pipeline.types.ts` — `PipelineConfig`, `PipelineStage`.
|
||||
- [x] 2.3 `src/error-codes.ts` — `defineCodes("NET_PROTO", [...])`.
|
||||
|
||||
## 3. Binary protocol
|
||||
|
||||
- [x] 3.1 `src/protocol/binary-protocol.ts` — `BinaryProtocol`.
|
||||
- [x] 3.2 Header: `version(1) | flags(1) | messageType(1) | timestamp(8) | payloadLength(2)` = 13 bytes.
|
||||
- [x] 3.3 Version negotiation placeholder (v1 only for now).
|
||||
|
||||
## 4. Message encoder/decoder
|
||||
|
||||
- [x] 4.1 `src/encoder/message-encoder.ts` — schema-aware encoding with `@suaveplan/bitpacker`.
|
||||
- [x] 4.2 `src/encoder/message-decoder.ts` — reverse decoding.
|
||||
- [x] 4.3 Roundtrip test for all `MessageType` variants.
|
||||
|
||||
## 5. Protocol pipeline
|
||||
|
||||
- [x] 5.1 `src/pipeline/protocol-pipeline.ts` — `ProtocolPipeline`.
|
||||
- [x] 5.2 Outgoing: `MessageEncoder` → `lengthPrefixEncode` → `CryptoTransform` → `compressStream`.
|
||||
- [x] 5.3 Incoming: reverse order with `decompressStream`, `CryptoTransform`, `lengthPrefixDecode`, `MessageDecoder`.
|
||||
- [x] 5.4 Error handling: `StreamPipeFailedError` on any stage failure.
|
||||
|
||||
## 6. Plugin wrapper
|
||||
|
||||
- [x] 6.1 `src/plugin/protocol-plugin.ts` — `ProtocolPlugin` implements `NetworkPlugin`.
|
||||
- [x] 6.2 Installs protocol, encoder, decoder, pipeline on `install()`.
|
||||
|
||||
## 7. Spec
|
||||
|
||||
- [x] 7.1 Update `openspec/specs/network/spec.md` with `NET-16`, `NET-17`.
|
||||
|
||||
## 8. Conformance tests
|
||||
|
||||
- [x] 8.1 `src/protocol/protocol.spec-conformance.test.ts` — header format, version, flags.
|
||||
- [x] 8.2 `src/encoder/encoder.spec-conformance.test.ts` — schema encoding, roundtrip.
|
||||
- [x] 8.3 `src/pipeline/pipeline.spec-conformance.test.ts` — pipeline ordering, error handling.
|
||||
- [x] 8.4 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 9. Serialization strategy framework
|
||||
|
||||
- [x] 9.1 `src/serialization/serializer-factory.ts` — `SerializerFactory`, registers by content type.
|
||||
- [x] 9.2 `src/serialization/json-serializer.ts` — `JsonSerializer`.
|
||||
- [x] 9.3 `src/serialization/binary-serializer.ts` — `BinarySerializer` with optional compression.
|
||||
- [x] 9.4 `src/serialization/msgpack-serializer.ts` — `MessagePackSerializer`.
|
||||
- [x] 9.5 Content-type negotiation via header flags.
|
||||
|
||||
## 10. Priority queue & adaptive batching
|
||||
|
||||
- [x] 10.1 `src/queue/priority-message-queue.ts` — `PriorityMessageQueue`, 5 tiers, FIFO within tier.
|
||||
- [x] 10.2 `src/batcher/message-batcher.ts` — `MessageBatcher`, flush on size/time/priority.
|
||||
- [x] 10.3 `src/backpressure/backpressure-controller.ts` — `BackpressureController`, slows on overwhelm.
|
||||
- [x] 10.4 CRITICAL messages bypass queue entirely.
|
||||
|
||||
## 11. Message TTL & loop detection
|
||||
|
||||
- [x] 11.1 `src/ttl/message-ttl.ts` — `MessageTTL`, decrements per hop, drops at zero.
|
||||
- [x] 11.2 `src/loop/loop-detector.ts` — `LoopDetector`, checks `visitedNodes` for cycles.
|
||||
- [x] 11.3 `src/dedup/duplicate-detector.ts` — `DuplicateDetector`, bloom filter for broadcast dedup.
|
||||
|
||||
## 12. Route caching
|
||||
|
||||
- [x] 12.1 `src/cache/route-cache.ts` — `RouteCache`, `(source, target) → nextHop`.
|
||||
- [x] 12.2 Invalidation on `topology:changed` bus event.
|
||||
- [x] 12.3 Adaptive size based on memory availability.
|
||||
|
||||
## 13. Spec
|
||||
|
||||
- [x] 13.1 Update `openspec/specs/network/spec.md` with `NET-45`, `NET-57`, `NET-58`, `NET-59`.
|
||||
|
||||
## 14. Conformance tests
|
||||
|
||||
- [x] 14.1 `src/serialization/serialization.spec-conformance.test.ts` — factory, JSON, Binary, MessagePack.
|
||||
- [x] 14.2 `src/queue/queue.spec-conformance.test.ts` — 5 tiers, FIFO, CRITICAL bypass.
|
||||
- [x] 14.3 `src/batcher/batcher.spec-conformance.test.ts` — grouping, flush triggers, adaptive.
|
||||
- [x] 14.4 `src/backpressure/backpressure.spec-conformance.test.ts` — detection, slowdown, recovery.
|
||||
- [x] 14.5 `src/ttl/ttl.spec-conformance.test.ts` — hop decrement, drop at zero.
|
||||
- [x] 14.6 `src/loop/loop.spec-conformance.test.ts` — cycle detection, visited tracking.
|
||||
- [x] 14.7 `src/dedup/dedup.spec-conformance.test.ts` — bloom filter, false positive tolerance.
|
||||
- [x] 14.8 `src/cache/cache.spec-conformance.test.ts` — caching, invalidation, memory bounds.
|
||||
|
||||
## 15. Verify
|
||||
|
||||
- [x] 15.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-protocol` green.
|
||||
- [x] 15.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-protocol` 100/100/100/100.
|
||||
- [x] 15.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-protocol` PASS.
|
||||
@@ -0,0 +1,179 @@
|
||||
# OpenSpec Change: network-plugin-qos
|
||||
|
||||
- **Change ID**: network-plugin-qos
|
||||
- **Package**: `@suaveplan/network-plugin-qos` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-01
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Implement bandwidth management and quality-of-service (QoS) controls for the mesh. `network-plugin-transport-manager` provides 5 priority tiers for message routing, but there is no per-mesh bandwidth quota enforcement, no control-plane message prioritization that bypasses normal queues, and no cross-mesh relay bandwidth throttling. This plugin adds the policy layer on top of the transport manager's mechanics.
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
**Current state**: `network-plugin-webrtc` has `bufferedAmount` backpressure. `network-plugin-transport-manager` has 5 priority tiers. `@suaveplan/rate-limiter` exists as a standalone package but is not integrated into the mesh.
|
||||
|
||||
**What's missing**:
|
||||
|
||||
- Per-mesh bandwidth quota enforcement
|
||||
- Message priority classes (control vs data vs bulk) with quota-aware scheduling
|
||||
- QoS: urgent messages (election, failover) bypass normal queue when mesh is saturated
|
||||
- Cross-mesh relay bandwidth throttling (prevent Tier 0 host saturation)
|
||||
|
||||
---
|
||||
|
||||
## Core components
|
||||
|
||||
### 1. `BandwidthQuotaEnforcer`
|
||||
|
||||
Tracks and enforces per-mesh and per-peer bandwidth quotas.
|
||||
|
||||
```ts
|
||||
class BandwidthQuotaEnforcer {
|
||||
constructor(options: {
|
||||
meshId: string;
|
||||
meshQuotaBps: number; // bytes per second for entire mesh
|
||||
peerQuotaBps: number; // bytes per second per peer
|
||||
relayQuotaBps: number; // bytes per second for cross-mesh relay
|
||||
windowMs: number; // default 1000
|
||||
});
|
||||
recordSend(bytes: number, isRelay: boolean): void;
|
||||
canSend(bytes: number, isRelay: boolean): boolean;
|
||||
getMeshUtilization(): number; // 0.0 – 1.0
|
||||
getPeerUtilization(peerId: string): number;
|
||||
on(event: "quota:exceeded", handler: (scope: string) => void): void;
|
||||
}
|
||||
```
|
||||
|
||||
Uses a sliding window (default 1 second). When quota is exceeded, sends are delayed or rejected based on message priority.
|
||||
|
||||
### 2. `MessagePriorityClassifier`
|
||||
|
||||
Assigns a `QoSClass` to every message based on its type and payload size.
|
||||
|
||||
```ts
|
||||
enum QoSClass {
|
||||
CONTROL_PLANE = 0, // elections, failover, heartbeats — never dropped
|
||||
REALTIME = 1, // game state, audio — low latency, may drop
|
||||
RELIABLE = 2, // file transfers, chat — guaranteed delivery
|
||||
BULK = 3, // backups, logs — best effort
|
||||
SCAVENGER = 4, // prefetch, analytics — first to drop
|
||||
}
|
||||
|
||||
class MessagePriorityClassifier {
|
||||
classify(envelope: MessageEnvelope): QoSClass;
|
||||
registerRule(type: string, qosClass: QoSClass): void;
|
||||
registerSizeRule(maxBytes: number, qosClass: QoSClass): void;
|
||||
}
|
||||
```
|
||||
|
||||
Default rules:
|
||||
|
||||
- `election:*`, `failover:*`, `heartbeat:*` → `CONTROL_PLANE`
|
||||
- `game:state`, `audio:*` → `REALTIME`
|
||||
- `chat:*`, `file:chunk` → `RELIABLE`
|
||||
- `backup:*`, `log:*` → `BULK`
|
||||
- `prefetch:*`, `analytics:*` → `SCAVENGER`
|
||||
|
||||
### 3. `QoSRouter`
|
||||
|
||||
Integrates with `network-plugin-transport-manager` to apply QoS policy.
|
||||
|
||||
```ts
|
||||
class QoSRouter {
|
||||
constructor(options: {
|
||||
classifier: MessagePriorityClassifier;
|
||||
enforcer: BandwidthQuotaEnforcer;
|
||||
transportManager: TransportManager; // from network-plugin-transport-manager
|
||||
});
|
||||
send(envelope: MessageEnvelope, targetPeerId: string): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
**Routing behaviour**:
|
||||
|
||||
1. Classify message → `QoSClass`.
|
||||
2. If `CONTROL_PLANE` → bypass quota check, send immediately via highest-priority transport.
|
||||
3. If mesh quota exceeded:
|
||||
- `REALTIME` → drop (application is notified).
|
||||
- `RELIABLE` → queue with timeout; retry when quota available.
|
||||
- `BULK` / `SCAVENGER` → drop or defer to off-peak window.
|
||||
4. If relay quota exceeded:
|
||||
- Cross-mesh messages are throttled; `SCAVENGER` relay traffic is dropped first.
|
||||
|
||||
### 4. `CongestionMonitor`
|
||||
|
||||
Monitors mesh congestion and emits alerts.
|
||||
|
||||
```ts
|
||||
class CongestionMonitor {
|
||||
constructor(options: {
|
||||
enforcer: BandwidthQuotaEnforcer;
|
||||
alertThreshold: number; // default 0.90
|
||||
sustainedPeriodMs: number; // default 5000
|
||||
});
|
||||
start(): void;
|
||||
stop(): void;
|
||||
getCongestionLevel(): "none" | "mild" | "severe" | "critical";
|
||||
}
|
||||
```
|
||||
|
||||
Emits `qos:congestion` events on the `NetworkBus` with level and recommended actions (e.g. "pause prefetch", "reduce broadcast frequency").
|
||||
|
||||
---
|
||||
|
||||
## Error codes
|
||||
|
||||
```ts
|
||||
const QOS_CODES = defineCodes("QOS", [
|
||||
"QUOTA_EXCEEDED",
|
||||
"RELAY_QUOTA_EXCEEDED",
|
||||
"MESSAGE_DROPPED",
|
||||
"CONGESTION_ALERT",
|
||||
"INVALID_QOS_CLASS",
|
||||
] as const);
|
||||
```
|
||||
|
||||
`QosError extends SuaveplanError<QosErrorCode>`.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Consumes**: `@suaveplan/network` (`NetworkNode`, `NetworkBus`, `MessageEnvelope`), `@suaveplan/network-plugin-transport-manager` (`TransportManager`, priority routing), `@suaveplan/network-plugin-relay` (cross-mesh relay paths), `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`.
|
||||
- **Blocked on**: `network-core` (shipped), `network-plugin-transport-manager`.
|
||||
|
||||
---
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/enforcer/enforcer.spec-conformance.test.ts` — pins sliding window, quota enforcement, utilization math.
|
||||
- `src/classifier/classifier.spec-conformance.test.ts` — pins default rules, custom rules, size-based rules.
|
||||
- `src/router/qos-router.spec-conformance.test.ts` — pins CONTROL_PLANE bypass, drop/queue/defer logic.
|
||||
- `src/monitor/congestion-monitor.spec-conformance.test.ts` — pins alert thresholds, sustained period, level calculation.
|
||||
- 100/100/100/100 Istanbul coverage.
|
||||
|
||||
---
|
||||
|
||||
## Conformance requirements (proposed)
|
||||
|
||||
- `NET-91` — `BandwidthQuotaEnforcer` tracks per-mesh, per-peer, and per-relay bandwidth using a sliding window.
|
||||
- `NET-92` — `MessagePriorityClassifier` assigns `QoSClass` based on message type and size.
|
||||
- `NET-93` — `CONTROL_PLANE` messages bypass quota checks and are sent immediately.
|
||||
- `NET-94` — `REALTIME` messages are dropped when mesh quota is exceeded.
|
||||
- `NET-95` — `RELIABLE` messages are queued with timeout when mesh quota is exceeded.
|
||||
- `NET-96` — `BULK` and `SCAVENGER` messages are dropped or deferred when mesh quota is exceeded.
|
||||
- `NET-97` — Cross-mesh relay traffic is throttled independently; `SCAVENGER` relay traffic is dropped first.
|
||||
- `NET-98` — `CongestionMonitor` emits `qos:congestion` events when utilization exceeds `alertThreshold` for `sustainedPeriodMs`.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Deep packet inspection** → v2; v1 uses message type and size only.
|
||||
- **Per-application QoS** → v2; v1 is mesh-wide.
|
||||
- **Traffic shaping via token bucket** → `@suaveplan/rate-limiter` may be integrated in v2; v1 uses sliding windows.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Tasks: network-plugin-qos
|
||||
|
||||
- [x] 1. Write `openspec/changes/network-plugin-qos/proposal.md`
|
||||
- [x] 2. Write `openspec/changes/network-plugin-qos/tasks.md`
|
||||
- [x] 3. Scaffold `packages/network/network-plugin-qos/package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 4. Implement `src/error-codes.ts` with `QOS_CODES`
|
||||
- [x] 5. Implement `src/enforcer/bandwidth-quota-enforcer.ts` — sliding window, quota checks
|
||||
- [x] 6. Implement `src/classifier/message-priority-classifier.ts` — type/size rules, QoSClass
|
||||
- [x] 7. Implement `src/router/qos-router.ts` — send logic, bypass/drop/queue/defer
|
||||
- [x] 8. Implement `src/monitor/congestion-monitor.ts` — alert thresholds, sustained period
|
||||
- [x] 9. Write `src/enforcer/enforcer.spec-conformance.test.ts`
|
||||
- [x] 10. Write `src/classifier/classifier.spec-conformance.test.ts`
|
||||
- [x] 11. Write `src/router/qos-router.spec-conformance.test.ts`
|
||||
- [x] 12. Write `src/monitor/congestion-monitor.spec-conformance.test.ts`
|
||||
- [x] 13. Write `tests/dep-graph.test.ts`
|
||||
- [x] 14. Run `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-qos` and achieve 100/100/100/100 coverage
|
||||
@@ -0,0 +1,55 @@
|
||||
# OpenSpec Change: network-plugin-registry
|
||||
|
||||
- **Change ID**: network-plugin-registry
|
||||
- **Package**: `@suaveplan/network-plugin-registry` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
The tiered network requires a small, fixed-size registry of group peers. The genesis `bitpacker` package provides the binary serialization needed for compact messages (62 bytes vs ~200 bytes JSON). The genesis `storage` package provides the KV backing. This plugin provides the registry operations: `add`, `remove`, `get`, `list`, plus `BinaryMessageEncoder` for compact wire format. It is the authoritative replacement for the suaveplan `network-registry` package.
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `RegistryPlugin` class implementing `NetworkPlugin`.
|
||||
- **ADDED**: `Registry` — CRUD on a fixed-capacity in-memory registry.
|
||||
- **ADDED**: `BinaryMessageEncoder` — packs `DynamicData` into bit-packed binary using `@suaveplan/bitpacker`.
|
||||
- **ADDED**: `RegistryMessage` — union type for `add`, `remove`, `get`, `list` operations.
|
||||
- **ADDED**: `RegistrySyncManager` — periodically syncs registry state to `NetworkBus`.
|
||||
- **ADDED**: `NETWORK_REG_CODES` — frozen error registry.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Distributed consensus for registry consistency → groups are small; eventual consistency via bus is sufficient.
|
||||
- Persistent registry storage → future `network-plugin-registry-persistence` using `@suaveplan/storage`.
|
||||
- Cross-group registry federation → future scope.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/network-registry.md` and `../suaveplan/packages/universal/network-registry/`.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| Fixed-capacity registry (32 peers) | `network-registry/README.md` §Registry | verbatim |
|
||||
| `add`, `remove`, `get`, `list` | `network-registry/README.md` §Registry | verbatim |
|
||||
| Binary message encoder (62 bytes) | `network-registry/README.md` §Binary Message Encoder | verbatim; uses `@suaveplan/bitpacker` |
|
||||
| `registry:update` bus event | `network-registry/README.md` §Registry | reworded; emits on `NetworkBus` |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| `RegistrySyncManager` with periodic sync | Defensive — ensures registry converges after partition |
|
||||
| `NETWORK_REG_CODES` | Required by spec-conformance for every enterprise package |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/registry/registry.spec-conformance.test.ts` — pins add/remove/get/list, capacity limit.
|
||||
- `src/encoder/encoder.spec-conformance.test.ts` — pins binary format, roundtrip, size ≤ 62 bytes.
|
||||
- `src/sync/sync.spec-conformance.test.ts` — pins periodic sync, deduplication.
|
||||
- `tests/dep-graph.test.ts` — pins direct import of `@suaveplan/bitpacker`.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only.
|
||||
@@ -0,0 +1,77 @@
|
||||
# Tasks — network-plugin-registry
|
||||
|
||||
> Blocked on: `network-core`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-registry/` with `package.json` (`@suaveplan/network-plugin-registry@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/bitpacker`, `@suaveplan/storage`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/registry.types.ts` — `RegistryEntry`, `RegistryConfig`, `RegistryMessage`.
|
||||
- [x] 2.2 `src/types/encoder.types.ts` — `DynamicData`, `EncodedMessage`.
|
||||
- [x] 2.3 `src/error-codes.ts` — `defineCodes("NET_REG", [...])`.
|
||||
|
||||
## 3. Registry
|
||||
|
||||
- [x] 3.1 `src/registry/registry.ts` — `Registry` with fixed capacity (default 32).
|
||||
- [x] 3.2 `add(entry)`, `remove(peerId)`, `get(peerId)`, `list()`.
|
||||
- [x] 3.3 `RegistryCapacityExceededError` when capacity reached.
|
||||
- [x] 3.4 Emits `registry:update` on `NetworkBus`.
|
||||
|
||||
## 4. Binary message encoder
|
||||
|
||||
- [x] 4.1 `src/encoder/binary-message-encoder.ts` — `BinaryMessageEncoder`.
|
||||
- [x] 4.2 Packs `DynamicData` into `BitPacker` format.
|
||||
- [x] 4.3 Target ≤ 62 bytes per message.
|
||||
- [x] 4.4 Roundtrip encoding/decoding with `BinaryMessageDecoder`.
|
||||
|
||||
## 5. Sync manager
|
||||
|
||||
- [x] 5.1 `src/sync/registry-sync-manager.ts` — `RegistrySyncManager`.
|
||||
- [x] 5.2 Periodic full sync on `NetworkBus`.
|
||||
- [x] 5.3 Deduplication by hash.
|
||||
|
||||
## 6. Plugin wrapper
|
||||
|
||||
- [x] 6.1 `src/plugin/registry-plugin.ts` — `RegistryPlugin` implements `NetworkPlugin`.
|
||||
- [x] 6.2 Installs registry, encoder, sync manager on `install()`.
|
||||
|
||||
## 7. Spec
|
||||
|
||||
- [x] 7.1 Update `openspec/specs/network/spec.md` with `NET-12`, `NET-13`.
|
||||
|
||||
## 8. Conformance tests
|
||||
|
||||
- [x] 8.1 `src/registry/registry.spec-conformance.test.ts` — add/remove/get/list, capacity limit.
|
||||
- [x] 8.2 `src/encoder/encoder.spec-conformance.test.ts` — binary format, roundtrip, size ≤ 62 bytes.
|
||||
- [x] 8.3 `src/sync/sync.spec-conformance.test.ts` — periodic sync, deduplication.
|
||||
- [x] 8.4 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 9. Verify
|
||||
|
||||
- [x] 9.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-registry` green.
|
||||
- [x] 9.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-registry` 100/100/100/100.
|
||||
- [x] 9.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-registry` PASS.
|
||||
|
||||
---
|
||||
|
||||
## Audit Note (2026-05-02)
|
||||
|
||||
**Status**: DEFERRED.
|
||||
|
||||
State at audit:
|
||||
|
||||
- Package scaffold is in place at `packages/network/network-plugin-registry/` with `src/registry/`, `src/encoder/`, `src/sync/`, plus `error-codes.ts`, `registry-plugin.ts`, and barrel `index.ts`. README, vite + vitest configs, tsconfig all exist.
|
||||
- `bunx turbo test --filter=@suaveplan/network-plugin-registry` is green (9 tests across `registry.spec-conformance.test.ts`, `encoder.spec-conformance.test.ts`, `dep-graph.test.ts`).
|
||||
- `bunx turbo test:coverage` **fails the 100/100/100/100 gate**: stmts 67.92 / branch 61.53 / funcs 52.38 / lines 67.92. `src/sync/sync.ts` is 0% covered (lines 11–30); `src/registry-plugin.ts` is 0% (lines 7–33); `src/registry/registry.ts` has one uncovered branch on line 14.
|
||||
|
||||
Outstanding to ship:
|
||||
|
||||
1. **Task 8.3** — author `src/sync/sync.spec-conformance.test.ts` covering periodic full-sync + dedup-by-hash; takes `RegistrySyncManager` to 100%.
|
||||
2. **Task 8.4** — author `src/error-codes.spec-conformance.test.ts` proving the `defineCodes("NET_REG", [...])` registry is frozen.
|
||||
3. **Tasks 6.1 / 6.2** — exercise `RegistryPlugin.install()` from a test (`src/registry-plugin.ts` is currently uncovered).
|
||||
4. **Task 3.3** — verify the `RegistryCapacityExceededError` branch (line 14 of `registry.ts`).
|
||||
5. Re-run `bunx turbo test:coverage --filter=@suaveplan/network-plugin-registry` and confirm 100/100/100/100, then archive.
|
||||
@@ -0,0 +1,195 @@
|
||||
# OpenSpec Change: network-plugin-relay
|
||||
|
||||
- **Change ID**: network-plugin-relay
|
||||
- **Package**: `@suaveplan/network-plugin-relay` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-01
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Implement cross-mesh message relay — the "federation layer" that enables Tier 0 hosts of different meshes to route messages to one another. Without this plugin, the network suite only supports intra-mesh communication; peers in Mesh A cannot send messages to peers in Mesh B. This is a P0 gap blocking the user's stated requirement: *"message relaying through the hosts through the nominated tier host to be able to transmit in any pocket mesh on any tier to any other pocket mesh on any tier."*
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
**User requirement**: *"message relaying through the hosts through the nominated tier host to be able to transmit in any pocket mesh on any tier to any other pocket mesh on any tier"*
|
||||
|
||||
**Current state**: ALL existing network proposals handle **intra-mesh** communication only (full mesh within one group). No package addresses **inter-mesh** routing.
|
||||
|
||||
**What's missing**:
|
||||
|
||||
- Host-to-host backbone network between Tier 0 hosts of different meshes
|
||||
- Message forwarding/relay logic at the host level
|
||||
- Cross-mesh addressing scheme (`meshId + peerId` vs just `peerId`)
|
||||
- Route discovery between meshes
|
||||
- Concept of a "super-peer" or "federation backbone"
|
||||
|
||||
---
|
||||
|
||||
## Core components
|
||||
|
||||
### 1. `RelayRouter`
|
||||
|
||||
Maintains a routing table: `(destinationMeshId, destinationPeerId) → nextHopHostId`. Runs on every Tier 0 host. Updates dynamically from `MeshDirectory` sync events.
|
||||
|
||||
```ts
|
||||
class RelayRouter {
|
||||
addRoute(destMeshId: string, destPeerId: string, nextHopHostId: string): void;
|
||||
removeRoute(destMeshId: string, destPeerId: string): void;
|
||||
resolve(targetMeshId: string, targetPeerId: string): string | null; // returns nextHopHostId
|
||||
getRoutesForMesh(meshId: string): Map<string, string>;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. `HostBackboneTransport`
|
||||
|
||||
Dedicated transport for Tier 0 ↔ Tier 0 communication. Reuses `WebSocket` or `RTCDataChannel` but is logically separate from peer mesh transport. Negotiates capabilities (max message size, supported compression, crypto suites).
|
||||
|
||||
```ts
|
||||
interface HostBackboneTransport {
|
||||
connect(hostId: string, address: string): Promise<void>;
|
||||
disconnect(hostId: string): void;
|
||||
send(hostId: string, envelope: CrossMeshEnvelope): void;
|
||||
onMessage(handler: (envelope: CrossMeshEnvelope, fromHostId: string) => void): void;
|
||||
getConnectedHosts(): string[];
|
||||
}
|
||||
```
|
||||
|
||||
### 3. `CrossMeshEnvelope`
|
||||
|
||||
Extends `MessageEnvelope` with cross-mesh routing metadata:
|
||||
|
||||
```ts
|
||||
interface CrossMeshEnvelope {
|
||||
// Inherited from MessageEnvelope
|
||||
id: string;
|
||||
type: string;
|
||||
senderId: string;
|
||||
senderMeshId: string;
|
||||
targetId: string;
|
||||
targetMeshId: string;
|
||||
payload: Uint8Array;
|
||||
timestamp: number;
|
||||
headers: Record<string, string>;
|
||||
// Relay-specific
|
||||
hopCount: number; // incremented per hop
|
||||
maxHops: number; // default 16
|
||||
visitedNodes: string[]; // peerIds / hostIds visited
|
||||
ttl: number; // ms remaining
|
||||
}
|
||||
```
|
||||
|
||||
Zod-validated. Dropped when `hopCount >= maxHops`, `ttl <= 0`, or `visitedNodes` contains current node.
|
||||
|
||||
### 4. `RelayManager`
|
||||
|
||||
Plugin entry point. Intercepts outbound messages where `targetMeshId !== localMeshId` and forwards them via `RelayRouter` → `HostBackboneTransport`. On inbound cross-mesh messages, delivers to local `NetworkBus` scoped to the target peer.
|
||||
|
||||
```ts
|
||||
class RelayManager {
|
||||
constructor(options: {
|
||||
router: RelayRouter;
|
||||
backbone: HostBackboneTransport;
|
||||
localMeshId: string;
|
||||
localHostId: string;
|
||||
maxHops: number;
|
||||
defaultTtlMs: number;
|
||||
});
|
||||
start(): void;
|
||||
stop(): void;
|
||||
onOutbound(envelope: MessageEnvelope): CrossMeshEnvelope | null; // null = not relayed
|
||||
onInbound(envelope: CrossMeshEnvelope): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 5. `MeshDirectory`
|
||||
|
||||
Discovery/registration of known meshes and their Tier 0 hosts. Can be seed-based (static config), server-assisted (via `network-plugin-server-bridge`), or gossip-based (Tier 0 hosts exchange mesh advertisements).
|
||||
|
||||
```ts
|
||||
class MeshDirectory {
|
||||
registerMesh(meshId: string, tier0HostIds: string[], hostAddresses: Map<string, string>): void;
|
||||
unregisterMesh(meshId: string): void;
|
||||
getTier0Hosts(meshId: string): string[];
|
||||
getHostAddress(hostId: string): string | undefined;
|
||||
listKnownMeshes(): string[];
|
||||
on(event: "mesh:added" | "mesh:removed" | "mesh:updated", handler: Function): void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Routing rules
|
||||
|
||||
1. **Same mesh** — `RelayManager` returns `null`; message stays local.
|
||||
2. **Different mesh, direct backbone exists** — forward to connected Tier 0 host that advertises the target mesh.
|
||||
3. **Different mesh, multi-hop required** — `RelayRouter` selects next hop from its table; `hopCount` increments; `visitedNodes` appends current node.
|
||||
4. **Broadcast across meshes** — `targetMeshId = "*"`, `targetId = "*"`. Relayed to ALL known meshes. Deduplicated at each mesh boundary via `messageId` Bloom filter.
|
||||
5. **Loop prevention** — Hard drop if `hopCount >= maxHops` or `visitedNodes` contains current node.
|
||||
|
||||
---
|
||||
|
||||
## Error codes
|
||||
|
||||
```ts
|
||||
const RELAY_CODES = defineCodes("RELAY", [
|
||||
"ROUTE_NOT_FOUND",
|
||||
"BACKBONE_CONNECT_FAILED",
|
||||
"BACKBONE_DISCONNECTED",
|
||||
"MAX_HOPS_EXCEEDED",
|
||||
"TTL_EXPIRED",
|
||||
"LOOP_DETECTED",
|
||||
"INVALID_ENVELOPE",
|
||||
"MESH_NOT_REGISTERED",
|
||||
"HOST_NOT_FOUND",
|
||||
"RELAY_REJECTED",
|
||||
] as const);
|
||||
```
|
||||
|
||||
`RelayError extends SuaveplanError<RelayErrorCode>`.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Consumes**: `@suaveplan/network` (`NetworkNode`, `NetworkBus`, `MessageEnvelope`, `NetworkPlugin`), `@suaveplan/network-plugin-topology` (tier info for backbone eligibility), `@suaveplan/network-plugin-registry` (peer lists for `MeshDirectory`), `@suaveplan/network-plugin-crypto-messages` (signature verification on cross-mesh envelopes), `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`, `zod`, `@opentelemetry/api`.
|
||||
- **Blocked on**: `network-core` (shipped), `network-plugin-topology`, `network-plugin-registry`.
|
||||
|
||||
---
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/router/router.spec-conformance.test.ts` — pins routing table add/remove/resolve, multi-hop resolution.
|
||||
- `src/backbone/backbone.spec-conformance.test.ts` — pins HostBackboneTransport connect/send/onMessage.
|
||||
- `src/envelope/envelope.spec-conformance.test.ts` — pins Zod validation, hopCount/ttl/visitedNodes rules.
|
||||
- `src/manager/manager.spec-conformance.test.ts` — pins outbound intercept, inbound delivery, same-mesh bypass.
|
||||
- `src/directory/directory.spec-conformance.test.ts` — pins mesh registration, host lookup, event emission.
|
||||
- `src/loop-prevention/loop-prevention.spec-conformance.test.ts` — pins maxHops drop, ttl drop, visitedNodes drop.
|
||||
- `tests/integration/relay.spec-conformance.test.ts` — end-to-end: Mesh A peer → Mesh B peer via Tier 0 backbone.
|
||||
- 100/100/100/100 Istanbul coverage.
|
||||
|
||||
---
|
||||
|
||||
## Conformance requirements (proposed)
|
||||
|
||||
- `NET-61` — `RelayRouter` maintains a routing table from `(destMeshId, destPeerId)` to `nextHopHostId`.
|
||||
- `NET-62` — `HostBackboneTransport` connects Tier 0 hosts with capability negotiation.
|
||||
- `NET-63` — `CrossMeshEnvelope` extends `MessageEnvelope` with `senderMeshId`, `targetMeshId`, `hopCount`, `maxHops`, `visitedNodes`, and `ttl`.
|
||||
- `NET-64` — Cross-mesh messages are dropped when `hopCount >= maxHops`.
|
||||
- `NET-65` — Cross-mesh messages are dropped when `ttl <= 0`.
|
||||
- `NET-66` — Cross-mesh messages are dropped when `visitedNodes` contains the current node.
|
||||
- `NET-67` — `MeshDirectory` registers known meshes and their Tier 0 hosts.
|
||||
- `NET-68` — Broadcast across meshes (`targetMeshId = "*"`) is relayed to all known meshes and deduplicated at mesh boundaries.
|
||||
- `NET-69` — `RelayManager` intercepts outbound messages where `targetMeshId !== localMeshId` and forwards them.
|
||||
- `NET-70` — Inbound cross-mesh envelopes are delivered to the local `NetworkBus` scoped to the target peer.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Cross-mesh **state synchronization** → `network-plugin-state` handles state sync within a mesh; cross-mesh state is application-level.
|
||||
- Global DHT for mesh discovery → future hardening; seed-based and server-assisted discovery are sufficient for v1.
|
||||
- Cross-mesh **host election** → each mesh governs itself; no global host.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Tasks: network-plugin-relay
|
||||
|
||||
- [x] 1. Write `openspec/changes/network-plugin-relay/proposal.md`
|
||||
- [x] 2. Write `openspec/changes/network-plugin-relay/tasks.md`
|
||||
- [x] 3. Scaffold `packages/network/network-plugin-relay/package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 4. Implement `src/error-codes.ts` with `RELAY_CODES`
|
||||
- [x] 5. Implement `src/router/relay-router.ts` — routing table, add/remove/resolve
|
||||
- [x] 6. Implement `src/backbone/host-backbone-transport.ts` — Tier 0 transport abstraction
|
||||
- [x] 7. Implement `src/envelope/cross-mesh-envelope.ts` — Zod schema, validation rules
|
||||
- [x] 8. Implement `src/directory/mesh-directory.ts` — mesh registration, host lookup
|
||||
- [x] 9. Implement `src/manager/relay-manager.ts` — plugin entry point, outbound intercept, inbound delivery
|
||||
- [x] 10. Implement `src/loop-prevention/loop-guard.ts` — hopCount, ttl, visitedNodes checks
|
||||
- [x] 11. Write `src/router/router.spec-conformance.test.ts`
|
||||
- [x] 12. Write `src/backbone/backbone.spec-conformance.test.ts`
|
||||
- [x] 13. Write `src/envelope/envelope.spec-conformance.test.ts`
|
||||
- [x] 14. Write `src/directory/directory.spec-conformance.test.ts`
|
||||
- [x] 15. Write `src/manager/manager.spec-conformance.test.ts`
|
||||
- [x] 16. Write `src/loop-prevention/loop-prevention.spec-conformance.test.ts`
|
||||
- [x] 17. Write `tests/integration/relay.spec-conformance.test.ts` — end-to-end two-mesh relay
|
||||
- [x] 18. Write `tests/dep-graph.test.ts`
|
||||
- [x] 19. Run `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-relay` and achieve 100/100/100/100 coverage
|
||||
@@ -0,0 +1,63 @@
|
||||
# OpenSpec Change: network-plugin-webrtc
|
||||
|
||||
- **Change ID**: network-plugin-webrtc
|
||||
- **Package**: `@suaveplan/network-plugin-webrtc` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
The core `network` package defines the `Transport` interface but ships no implementation. For browser-to-browser mesh networking — the primary use-case for the tiered host-nomination system — WebRTC is the only practical peer-to-peer transport. This plugin implements the `Transport` contract using `RTCPeerConnection` and `RTCDataChannel`, adds automatic mesh formation, ICE restart, RTT measurement (ping), and signaling pluggability so it can work with any signaling backend (WebSocket, HTTP POST, or a future DHT plugin).
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `WebRTCPlugin` class implementing `NetworkPlugin` and `Transport`.
|
||||
- **ADDED**: `WebRTCTransport` — manages `RTCPeerConnection` lifecycle per peer: create, offer/answer, ICE handling, data channel open/close.
|
||||
- **ADDED**: `WebRTCMesh` — automatic mesh formation: on peer discovery, initiates connection; on peer disconnect, removes from mesh. Maintains full-mesh within a group.
|
||||
- **ADDED**: `DataChannelManager` — opens labeled data channels, handles `bufferedAmount` backpressure, emits `message` events as `Uint8Array`.
|
||||
- **ADDED**: `PingManager` — sends correlated echo frames over any active transport (not just WebRTC), measures RTT with EMA smoothing, calculates jitter and packet loss, maintains a composite reliability score, publishes `peer:latency` on the bus. Can be used by `network-plugin-transport-manager` to health-monitor any transport type.
|
||||
- **ADDED**: `SignalingClient` interface — pluggable signaling: `connect()`, `send(signal)`, `onSignal(handler)`, `disconnect()`. Ships with a `WebSocketSignalingClient` implementation.
|
||||
- **ADDED**: `IceManager` — monitors `iceConnectionState`, triggers ICE restart on failure, surfaces `transport:ice-restart` events.
|
||||
- **ADDED**: `NETWORK_WEBRTC_CODES` — frozen error registry.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- TURN server deployment or TURN credential rotation → ops concern, documented but not implemented.
|
||||
- DHT-based peer discovery without signaling → future `network-plugin-discovery-dht`.
|
||||
- Simulcast / SFU mode → future `network-plugin-sfu`.
|
||||
- Screen sharing or media tracks → this is a data-channel transport only.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/network-webrtc.md`, `../suaveplan/enterprise/drive-webrtc.md`, and `../suaveplan/packages/browser/network-webrtc/`.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| WebRTC peer connection lifecycle | `drive-webrtc.md` §2, `network-webrtc/README.md` | reworded; merged with Transport interface |
|
||||
| Data channel byte transport | `drive-webrtc.md` §2 `DataChannelManager` | verbatim contract |
|
||||
| ICE restart on failure | `drive-webrtc.md` §3.6 | verbatim |
|
||||
| Ping / RTT measurement | `network/src/transport/legacy/base-transport.md` (stub) | new requirement — source only had a TODO |
|
||||
| Signaling pluggability | `drive-webrtc.md` §4.8 | verbatim |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| `PingManager` with EMA | Source had `"Ping not implemented"` stub; genesis implements it properly using `timing` EMA |
|
||||
| Full-mesh within group | Required for the tiered host-nomination voting use-case |
|
||||
| `bufferedAmount` backpressure | Prevents datachannel buffer overflow in high-throughput scenarios |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/transport/transport.spec-conformance.test.ts` — pins `Transport` interface compliance (connect, disconnect, send, onMessage, getConnectedPeers).
|
||||
- `src/mesh/mesh.spec-conformance.test.ts` — pins automatic connection on peer discovery and removal on disconnect.
|
||||
- `src/ping/ping.spec-conformance.test.ts` — pins correlated echo, RTT calculation, EMA smoothing.
|
||||
- `src/ice/ice.spec-conformance.test.ts` — pins ICE restart on `failed` state.
|
||||
- `src/signaling/signaling.spec-conformance.test.ts` — pins `SignalingClient` interface and WebSocket implementation.
|
||||
- `src/backpressure/backpressure.spec-conformance.test.ts` — pins `bufferedAmount` pause/resume.
|
||||
- `tests/dep-graph.test.ts` — pins no browser-only APIs leak into non-browser builds.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Tasks — network-plugin-webrtc
|
||||
|
||||
> Blocked on: `network-core`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-webrtc/` with `package.json` (`@suaveplan/network-plugin-webrtc@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/streams`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/signaling.types.ts` — `SignalingClient`, `SignalingMessage`, `SignalType`.
|
||||
- [x] 2.2 `src/types/webrtc.types.ts` — `WebRTCConfig`, `PeerConnectionState`, `DataChannelConfig`.
|
||||
- [x] 2.3 `src/types/ping.types.ts` — `PingFrame`, `PongFrame`, `LatencyRecord`.
|
||||
- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_WEBRTC", [...])`.
|
||||
|
||||
## 3. Signaling
|
||||
|
||||
- [x] 3.1 `src/signaling/signaling-client.ts` — `SignalingClient` interface.
|
||||
- [x] 3.2 `src/signaling/websocket-signaling-client.ts` — WebSocket implementation with reconnect.
|
||||
|
||||
## 4. ICE management
|
||||
|
||||
- [x] 4.1 `src/ice/ice-manager.ts` — monitors `iceConnectionState`, triggers restart on `failed`.
|
||||
- [x] 4.2 Configurable `iceServers` (STUN + TURN).
|
||||
|
||||
## 5. Data channel
|
||||
|
||||
- [x] 5.1 `src/data-channel/data-channel-manager.ts` — open/close channels, `bufferedAmount` backpressure.
|
||||
- [x] 5.2 Emits `Uint8Array` messages on the bus.
|
||||
|
||||
## 6. Transport implementation
|
||||
|
||||
- [x] 6.1 `src/transport/webrtc-transport.ts` — implements `Transport`: `connect`, `disconnect`, `send`, `onMessage`, `getConnectedPeers`.
|
||||
- [x] 6.2 Manages one `RTCPeerConnection` per peer.
|
||||
|
||||
## 7. Mesh
|
||||
|
||||
- [x] 7.1 `src/mesh/webrtc-mesh.ts` — auto-connects to discovered peers, maintains full-mesh.
|
||||
- [x] 7.2 Removes peers on disconnect or heartbeat timeout.
|
||||
|
||||
## 8. Ping / latency
|
||||
|
||||
- [x] 8.1 `src/ping/ping-manager.ts` — correlated echo frames, RTT measurement.
|
||||
- [x] 8.2 EMA smoothing with configurable window.
|
||||
- [x] 8.3 Publishes `peer:latency` on `NetworkBus`.
|
||||
|
||||
## 9. Plugin wrapper
|
||||
|
||||
- [x] 9.1 `src/plugin/webrtc-plugin.ts` — `WebRTCPlugin` implements `NetworkPlugin`.
|
||||
- [x] 9.2 Registers itself as a transport with the node on `install()`.
|
||||
|
||||
## 10. Spec
|
||||
|
||||
- [x] 10.1 Update `openspec/specs/network/spec.md` with `NET-06`, `NET-07`.
|
||||
|
||||
## 11. Conformance tests
|
||||
|
||||
- [x] 11.1 `src/transport/transport.spec-conformance.test.ts` — `Transport` compliance.
|
||||
- [x] 11.2 `src/mesh/mesh.spec-conformance.test.ts` — auto-connect, full-mesh, removal.
|
||||
- [x] 11.3 `src/ping/ping.spec-conformance.test.ts` — echo, RTT, EMA.
|
||||
- [x] 11.4 `src/ice/ice.spec-conformance.test.ts` — restart on failure.
|
||||
- [x] 11.5 `src/signaling/signaling.spec-conformance.test.ts` — interface, WebSocket impl.
|
||||
- [x] 11.6 `src/backpressure/backpressure.spec-conformance.test.ts` — bufferedAmount pause.
|
||||
- [x] 11.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 12. Verify
|
||||
|
||||
- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-webrtc` green.
|
||||
- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-webrtc` 100/100/100/100.
|
||||
- [x] 12.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-webrtc` PASS.
|
||||
@@ -0,0 +1,148 @@
|
||||
# Design: enterprise-audio-sprite-packer
|
||||
|
||||
**Change ID**: enterprise-audio-sprite-packer
|
||||
**Package**: `@suaveplan/audio-sprite-packer`
|
||||
|
||||
`@suaveplan/audio-sprite-packer` packs multiple discrete audio clips into a single
|
||||
concatenated binary with a compact JSON manifest. It is the universal-tier
|
||||
counterpart to browser-specific sprite loaders: it performs the *packing* side of
|
||||
the pipeline (server-side or build-time), producing a deterministic, hash-verified
|
||||
sprite that browser or server consumers can later unpack by name.
|
||||
|
||||
The upstream package (`../suaveplan/packages/universal/audio-sprite-packer`)
|
||||
compressed only metadata maps (`{name: [offset, duration]}`) using BitPacker. The
|
||||
genesis migration retains that capability as the **manifest layer**, but adds the
|
||||
**audio layer**: actual clip concatenation, format normalisation, silence stripping,
|
||||
and gain normalisation via a pluggable `AudioAdapter`. The result is a
|
||||
production-grade sprite builder rather than a map compressor.
|
||||
|
||||
---
|
||||
|
||||
## 1. Relationship to the ecosystem
|
||||
|
||||
`audio-sprite-packer` sits above `audio-core` (it produces `AudioDocument`-compatible
|
||||
manifests) and below `audio-engine-browser` / `audio-engine-server` (which consume
|
||||
sprites at runtime). It is a **leaf** in the dependency graph: no other genesis
|
||||
package depends on it at build time; it is invoked at build time or on-demand.
|
||||
|
||||
`audio-sprite-packer` does NOT import `audio-core` directly — the manifest shape is
|
||||
a stable JSON schema, not a runtime class dependency. This keeps the package
|
||||
universal-tier with zero heavy audio dependencies.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture
|
||||
|
||||
### 2.1. Two-layer output
|
||||
|
||||
Every `pack()` call produces:
|
||||
|
||||
1. **`data: Uint8Array`** — the concatenated, encoded audio bytes for all clips
|
||||
(plus inter-clip silence padding when configured).
|
||||
2. **`manifest: AudioSpriteManifest`** — JSON-serialisable metadata describing each
|
||||
clip's byte offset, duration, sample rate, channel count, and format.
|
||||
|
||||
The separation lets consumers stream `data` from a CDN while downloading the small
|
||||
manifest separately, or embed both in a single envelope.
|
||||
|
||||
### 2.2. AudioAdapter injection
|
||||
|
||||
All PCM operations are delegated to an injectable `AudioAdapter`:
|
||||
|
||||
- `probe` — extract duration, sample rate, channels, format from encoded bytes
|
||||
- `decode` — convert encoded bytes to planar `Float32Array` PCM
|
||||
- `encode` — convert planar PCM back to encoded bytes
|
||||
- `stripSilence` — remove leading/trailing silence below a dB threshold
|
||||
- `normalise` — peak-normalise to 0 dBFS
|
||||
|
||||
This makes `audio-sprite-packer` universal: a browser build passes a
|
||||
`WebAudioAdapter` (wrapping `AudioContext.decodeAudioData`), a server build passes
|
||||
an `FFmpegAdapter` (wrapping `fluent-ffmpeg` or `@ffmpeg/ffmpeg`), and unit tests
|
||||
pass `NullAudioAdapter` which returns deterministic fixture data without any
|
||||
external dependency.
|
||||
|
||||
### 2.3. Pack pipeline
|
||||
|
||||
```
|
||||
clips[] → detect format → probe → decode → stripSilence? → normalise?
|
||||
→ append silence padding → encode concatenated → build manifest
|
||||
```
|
||||
|
||||
The pipeline is serial (not streaming) because the total output size is unknown
|
||||
until all clips are processed. For very large clip sets, the caller can batch
|
||||
externally.
|
||||
|
||||
### 2.4. Manifest integrity
|
||||
|
||||
The manifest carries a SHA-256 `contentHash` of the packed `data` buffer, computed
|
||||
via `@suaveplan/crypto-utils`. `unpack(sprite, clipName)` validates the hash
|
||||
lazily: it slices the requested clip by offset/byteLength and returns the bytes
|
||||
without re-decoding. If the caller requests `verifyIntegrity: true`, `unpack`
|
||||
re-computes the hash and throws `AUDIO_SPRITE_HASH_MISMATCH` on mismatch.
|
||||
|
||||
---
|
||||
|
||||
## 3. File layout
|
||||
|
||||
```text
|
||||
packages/audio/audio-sprite-packer/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
README.md
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
audio-sprite-packer/
|
||||
audio-sprite-packer.ts
|
||||
audio-sprite-packer.md
|
||||
audio-sprite-packer.types.ts
|
||||
audio-sprite-packer.test.ts
|
||||
index.ts
|
||||
adapters/
|
||||
null-adapter/
|
||||
null-adapter.ts
|
||||
null-adapter.md
|
||||
null-adapter.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
manifest/
|
||||
manifest.ts
|
||||
manifest.md
|
||||
manifest.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
audio-sprite-packer.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Decisions and trade-offs
|
||||
|
||||
- **Serial pipeline, not streaming.** The output is a single concatenated buffer.
|
||||
Streaming would require a two-pass design (write sizes, then rewrite headers)
|
||||
which adds complexity for a build-time tool. Callers with >1000 clips should
|
||||
batch externally.
|
||||
- **NullAudioAdapter ships in `src/`, not `tests/`.** It is a legitimate testing
|
||||
fixture that downstream packages can import via `@suaveplan/audio-sprite-packer/adapters/null-adapter`.
|
||||
- **Manifest is JSON, not BitPacker.** The upstream used BitPacker for metadata
|
||||
compression. The genesis manifest is plain JSON so it is human-readable,
|
||||
diff-friendly, and trivially parsed in any runtime. The 80%+ compression claim
|
||||
comes from the binary audio layer (concatenation + shared format), not from
|
||||
metadata bit-packing.
|
||||
- **Silence threshold is on the adapter.** `stripSilence` delegates to the adapter
|
||||
so that different backends (Web Audio vs FFmpeg) can use their own optimised
|
||||
algorithms. The packer only configures the threshold via `PackOptions`.
|
||||
- **No `audio-core` runtime dependency.** The manifest references clips by name,
|
||||
offset, and duration, not by `AudioPage` or `AudioDocument`. Consumers build
|
||||
their own domain objects from the manifest. This prevents a heavy dependency
|
||||
in a build-time tool.
|
||||
@@ -0,0 +1,197 @@
|
||||
# OpenSpec Change: enterprise-audio-sprite-packer
|
||||
|
||||
- **Change ID**: enterprise-audio-sprite-packer
|
||||
- **Package**: `@suaveplan/audio-sprite-packer`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/compression/audio-sprite-packer`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/audio-sprite-packer.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/audio-sprite-packer` on the genesis branch from scratch at enterprise quality. The package builds binary audio sprite maps with 80%+ compression versus individual files: pack multiple audio clips (WAV/MP3/OGG) into a single concatenated binary with a compact JSON manifest (offset + duration per clip), strip inter-clip silence, normalise gain, and produce a ready-to-use sprite descriptor compatible with Web Audio API `AudioBufferSourceNode`. Pure TypeScript; audio encode/decode delegated to injectable `AudioAdapter`.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Base class for `AudioSpriteError`; `AUDIO_SPRITE.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||||
| `@suaveplan/mime` (`workspace:^`) | Audio MIME-type detection |
|
||||
| `@suaveplan/crypto-utils` (`workspace:^`) | Content hash for deterministic manifest IDs |
|
||||
| `zod` (`catalog:forms`) | Zod schemas for all public option types |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
class AudioSpriteError extends SuaveplanError
|
||||
|
||||
type AudioFormat = 'wav' | 'mp3' | 'ogg' | 'flac' | 'unknown'
|
||||
|
||||
interface AudioClipInput {
|
||||
name: string
|
||||
data: Uint8Array
|
||||
format?: AudioFormat // detected from @suaveplan/mime if absent
|
||||
}
|
||||
|
||||
interface AudioSpriteEntry {
|
||||
name: string
|
||||
offset: number // byte offset in the packed buffer
|
||||
byteLength: number
|
||||
durationSeconds: number
|
||||
sampleRate: number
|
||||
channels: number
|
||||
format: AudioFormat
|
||||
}
|
||||
|
||||
interface AudioSpriteManifest {
|
||||
version: 1
|
||||
format: AudioFormat
|
||||
sampleRate: number
|
||||
channels: number
|
||||
totalDurationSeconds: number
|
||||
entries: AudioSpriteEntry[]
|
||||
contentHash: string // SHA-256 of packed buffer
|
||||
}
|
||||
|
||||
interface AudioSprite {
|
||||
data: Uint8Array // concatenated packed audio bytes
|
||||
manifest: AudioSpriteManifest
|
||||
}
|
||||
|
||||
interface PackOptions {
|
||||
outputFormat?: AudioFormat // default: 'ogg'
|
||||
silencePaddingMs?: number // between clips; default: 100
|
||||
stripSilence?: boolean // default: true; remove leading/trailing silence per clip
|
||||
normalise?: boolean // default: false; gain normalisation
|
||||
sampleRate?: number // default: from first clip
|
||||
}
|
||||
|
||||
interface AudioAdapter {
|
||||
readonly supportedFormats: readonly AudioFormat[]
|
||||
probe(data: Uint8Array): Promise<{ durationSeconds: number; sampleRate: number; channels: number; format: AudioFormat }>
|
||||
decode(data: Uint8Array): Promise<Float32Array> // PCM samples
|
||||
encode(samples: Float32Array, sampleRate: number, channels: number, format: AudioFormat): Promise<Uint8Array>
|
||||
stripSilence(samples: Float32Array, sampleRate: number, thresholdDb?: number): Float32Array
|
||||
normalise(samples: Float32Array): Float32Array
|
||||
}
|
||||
|
||||
interface AudioSpritePackerOptions {
|
||||
adapter: AudioAdapter
|
||||
logger?: LoggerLike
|
||||
clock?: Clock
|
||||
}
|
||||
|
||||
class AudioSpritePacker {
|
||||
constructor(options: AudioSpritePackerOptions)
|
||||
pack(clips: AudioClipInput[], options?: PackOptions, signal?: AbortSignal): Promise<AudioSprite>
|
||||
unpack(sprite: AudioSprite, clipName: string): Uint8Array
|
||||
}
|
||||
|
||||
function createAudioSpritePacker(options: AudioSpritePackerOptions): AudioSpritePacker
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type AudioSpriteErrorCode =
|
||||
| 'AUDIO_SPRITE_UNSUPPORTED_FORMAT'
|
||||
| 'AUDIO_SPRITE_DECODE_FAILED'
|
||||
| 'AUDIO_SPRITE_ENCODE_FAILED'
|
||||
| 'AUDIO_SPRITE_CLIP_NOT_FOUND'
|
||||
| 'AUDIO_SPRITE_INVALID_OPTIONS'
|
||||
| 'AUDIO_SPRITE_EMPTY_INPUT'
|
||||
|
||||
const AUDIO_SPRITE_ERROR_METADATA: Readonly<Record<AudioSpriteErrorCode, CodeMetadata>>
|
||||
function registerAudioSpriteErrorCodes(): void
|
||||
```
|
||||
|
||||
### Zod schemas
|
||||
|
||||
```ts
|
||||
AudioSpriteEntrySchema
|
||||
AudioSpriteManifestSchema
|
||||
PackOptionsSchema
|
||||
AudioSpritePackerOptionsSchema
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **`AudioAdapter` interface** — all PCM operations delegated; `NullAudioAdapter` ships for tests.
|
||||
2. **Silence stripping** — optional per-clip silence removal using a configurable dB threshold (default: −60 dBFS).
|
||||
3. **Gain normalisation** — peak normalise each clip to 0 dBFS before packing (optional).
|
||||
4. **Content hashing** — SHA-256 of packed buffer via `@suaveplan/crypto-utils` stored in manifest for integrity verification on unpack.
|
||||
5. **`unpack`** — slice-and-return: uses `manifest.entries` to extract a named clip from the sprite buffer without any re-decode.
|
||||
6. **`AbortSignal` propagation** — passed through `pack`; throws `AudioSpriteError(AUDIO_SPRITE_ENCODE_FAILED)` on abort.
|
||||
7. **OTel instrumentation** — span `audio-sprite.pack`, counter `audio_sprite_pack_total`, histogram `audio_sprite_pack_duration_ms` + `audio_sprite_compression_ratio`.
|
||||
8. **Property-based tests** — unpack after pack returns original bytes (null adapter), manifest entry count matches input clip count, silence padding produces correct total duration.
|
||||
9. **Benchmark suite** — pack 10 short clips (null adapter), pack 50 clips.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/compression/audio-sprite-packer/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
audio-sprite-packer/
|
||||
audio-sprite-packer.ts
|
||||
audio-sprite-packer.md
|
||||
audio-sprite-packer.types.ts
|
||||
audio-sprite-packer.test.ts
|
||||
index.ts
|
||||
adapters/
|
||||
null-adapter/
|
||||
null-adapter.ts
|
||||
null-adapter.md
|
||||
null-adapter.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
manifest.ts
|
||||
manifest.md
|
||||
manifest.test.ts
|
||||
__benchmarks__/
|
||||
audio-sprite-packer.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: game audio engines, `@suaveplan/audio-engine`, any Web Audio sprite loaders.
|
||||
**Breaking changes**: none — fresh build.
|
||||
**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/crypto-utils` published to Verdaccio.
|
||||
@@ -0,0 +1,183 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: audio-sprite-packer (audio-sprite-packer)
|
||||
|
||||
**Package**: `@suaveplan/audio-sprite-packer`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time. No exceptions.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Universal-tier purity
|
||||
|
||||
The package SHALL import zero browser-only APIs (`window`, `document`, `navigator`, `AudioContext`) and zero statically-imported Node-only APIs (`node:fs`, `node:path`, `process`, `Buffer`). All audio encode/decode operations SHALL be delegated to the injectable `AudioAdapter`. The package's `dependencies` SHALL be limited to `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/crypto-utils`, `tslib`, and `zod`; `@opentelemetry/api` is the only permitted non-workspace runtime dependency.
|
||||
|
||||
#### Scenario: Built dist references no platform globals at module scope
|
||||
|
||||
- **WHEN** the built `dist/` is grep'd for top-level imports
|
||||
- **THEN** it MUST NOT statically import `window`, `document`, `navigator`, `AudioContext`, `node:fs`, `node:path`, `process`, or `Buffer`
|
||||
|
||||
#### Scenario: Tests pass under both runtimes
|
||||
|
||||
- **WHEN** the suite runs under `bun test` (server) and under vitest (browser shim)
|
||||
- **THEN** both runs pass with identical results using `NullAudioAdapter`
|
||||
|
||||
**Verified by:** `tests/purity.test.ts::"dist statically imports no browser or Node globals"` AND `tests/purity.test.ts::"dependency set is limited to the declared workspace deps and zod"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: AudioAdapter plugin contract
|
||||
|
||||
The package SHALL export an `AudioAdapter` interface carrying `supportedFormats`, `probe(data)`, `decode(data)`, `encode(samples, sampleRate, channels, format)`, `stripSilence(samples, sampleRate, thresholdDb?)`, and `normalise(samples)`. The package SHALL also export `NullAudioAdapter` implementing the interface: `probe` returns configurable fixture metadata, `decode` returns zeros, `encode` returns the input re-interpreted as bytes, `stripSilence` and `normalise` return the input unchanged.
|
||||
|
||||
#### Scenario: NullAudioAdapter probes a fixture
|
||||
|
||||
- **WHEN** `NullAudioAdapter.probe` is called with any Uint8Array
|
||||
- **THEN** it returns `{ format: "wav", durationSeconds: 1, sampleRate: 44100, channels: 2 }`
|
||||
|
||||
#### Scenario: NullAudioAdapter round-trips decode/encode
|
||||
|
||||
- **WHEN** `NullAudioAdapter.decode` is called and the result is passed to `encode`
|
||||
- **THEN** the returned bytes are byte-equal to the original input
|
||||
|
||||
**Verified by:** `src/adapters/null-adapter/null-adapter.test.ts::"NullAudioAdapter.probe returns fixture metadata"` AND `src/adapters/null-adapter/null-adapter.test.ts::"decode/encode round-trips through NullAudioAdapter"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: AudioSpritePacker pack and unpack
|
||||
|
||||
The package SHALL export `AudioSpritePacker` with constructor `options: { adapter: AudioAdapter; logger?: LoggerLike; clock?: Clock }` and methods `pack(clips, options?, signal?)` and `unpack(sprite, clipName)`. `pack` SHALL validate input is non-empty, probe and decode each clip via the adapter, optionally strip silence and normalise, append silence padding, encode the concatenated PCM, build a manifest with per-clip offsets, and return `{ data, manifest }`. `unpack` SHALL look up the clip name in the manifest and return a `Uint8Array` slice of the sprite data at the recorded offset and byteLength.
|
||||
|
||||
#### Scenario: pack three clips and unpack each
|
||||
|
||||
- **WHEN** `pack` is called with three `AudioClipInput` items using `NullAudioAdapter`
|
||||
- **THEN** the returned manifest has three entries with monotonically increasing offsets, and `unpack` for each name returns a Uint8Array whose byteLength matches the manifest entry
|
||||
|
||||
#### Scenario: unpack for unknown clip name throws
|
||||
|
||||
- **WHEN** `unpack` is called with a clip name not present in the manifest
|
||||
- **THEN** it throws `AudioSpriteError` whose `code === "AUDIO_SPRITE.CLIP_NOT_FOUND"`
|
||||
|
||||
**Verified by:** `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"pack three clips and unpack each by name"` AND `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"unpack throws AUDIO_SPRITE_CLIP_NOT_FOUND for unknown name"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Empty input rejection
|
||||
|
||||
`pack` called with an empty clips array SHALL throw `AudioSpriteError` with code `AUDIO_SPRITE.EMPTY_INPUT` before invoking the adapter.
|
||||
|
||||
#### Scenario: empty clips array throws EMPTY_INPUT
|
||||
|
||||
- **WHEN** `pack` is called with `[]`
|
||||
- **THEN** it throws `AudioSpriteError` whose `code === "AUDIO_SPRITE.EMPTY_INPUT"`
|
||||
|
||||
**Verified by:** `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"pack throws EMPTY_INPUT for empty clips array"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Manifest build and validation
|
||||
|
||||
The package SHALL export `buildManifest(entries, packedBuffer)` returning an `AudioSpriteManifest` with `version: 1`, `format`, `sampleRate`, `channels`, `totalDurationSeconds`, `entries`, and `contentHash` (SHA-256 of `packedBuffer`). It SHALL also export `validateManifest(manifest)` which checks `version === 1`, entries array non-empty, offsets non-overlapping, and throws `AudioSpriteError` with code `AUDIO_SPRITE.INVALID_MANIFEST` on any violation.
|
||||
|
||||
#### Scenario: buildManifest computes SHA-256 content hash
|
||||
|
||||
- **WHEN** `buildManifest` is called with entries and a packed buffer
|
||||
- **THEN** the manifest `contentHash` is a 64-character hex string matching the SHA-256 of the buffer
|
||||
|
||||
#### Scenario: validateManifest rejects overlapping offsets
|
||||
|
||||
- **WHEN** `validateManifest` is called with entries whose byte ranges overlap
|
||||
- **THEN** it throws `AudioSpriteError` whose `code === "AUDIO_SPRITE.INVALID_MANIFEST"`
|
||||
|
||||
**Verified by:** `src/utils/manifest/manifest.test.ts::"buildManifest computes a SHA-256 content hash"` AND `src/utils/manifest/manifest.test.ts::"validateManifest rejects overlapping byte offsets"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: AbortSignal propagation
|
||||
|
||||
`pack` SHALL accept an optional `AbortSignal`. An already-aborted signal SHALL cause the method to throw `AudioSpriteError` with code `AUDIO_SPRITE.ABORTED` before any adapter call. A signal aborted mid-pack SHALL terminate at the next clip boundary, release any partial buffers, and throw the same error.
|
||||
|
||||
#### Scenario: pre-aborted signal short-circuits pack
|
||||
|
||||
- **WHEN** `pack` is called with an already-aborted signal
|
||||
- **THEN** it throws `AudioSpriteError` whose `code === "AUDIO_SPRITE.ABORTED"` before the adapter is invoked
|
||||
|
||||
**Verified by:** `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"pack throws ABORTED for a pre-aborted signal"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Zod boundary validation
|
||||
|
||||
Every public options object — `PackOptions`, `AudioSpritePackerOptions`, `AudioClipInput` — SHALL have a Zod schema, and every public entry point (`pack`, `createAudioSpritePacker`) SHALL validate its arguments against the schema before use. A validation failure SHALL throw `AudioSpriteError` with code `AUDIO_SPRITE.INVALID_OPTIONS` carrying the Zod issue list in `context`.
|
||||
|
||||
#### Scenario: invalid options are rejected at the boundary
|
||||
|
||||
- **WHEN** `pack` is called with `silencePaddingMs: -1`
|
||||
- **THEN** it throws `AudioSpriteError` whose `code === "AUDIO_SPRITE.INVALID_OPTIONS"` with the Zod issues in `context`
|
||||
|
||||
**Verified by:** `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"pack rejects invalid options with AUDIO_SPRITE_INVALID_OPTIONS"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Structured error codes
|
||||
|
||||
The package SHALL register error codes via `@suaveplan/error`'s `defineCodes("AUDIO_SPRITE", [...])` yielding values `AUDIO_SPRITE.UNSUPPORTED_FORMAT`, `AUDIO_SPRITE.DECODE_FAILED`, `AUDIO_SPRITE.ENCODE_FAILED`, `AUDIO_SPRITE.CLIP_NOT_FOUND`, `AUDIO_SPRITE.INVALID_OPTIONS`, `AUDIO_SPRITE.EMPTY_INPUT`, `AUDIO_SPRITE.INVALID_MANIFEST`, and `AUDIO_SPRITE.ABORTED`. Every error thrown by the package SHALL be an `AudioSpriteError` extending `SuaveplanError`. Every registered code SHALL be reachable from a real call site exercised by tests.
|
||||
|
||||
#### Scenario: every registered code is thrown by a call site
|
||||
|
||||
- **WHEN** the test suite runs
|
||||
- **THEN** each code in the registry is asserted thrown by at least one test
|
||||
|
||||
**Verified by:** `src/error-codes.test.ts::"every AUDIO_SPRITE code is reachable from a call site"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: OpenTelemetry instrumentation
|
||||
|
||||
The package SHALL instrument `pack` via `@opentelemetry/api`: span `audio_sprite.pack` carrying `clipCount` and `outputFormat` attributes; counter `audio_sprite.pack_total`; histograms `audio_sprite.pack_duration_ms` and `audio_sprite.compression_ratio`. Instrumentation SHALL be a no-op when no exporter is registered and SHALL NOT run as an import-time side effect.
|
||||
|
||||
#### Scenario: instrumentation is inert without an exporter
|
||||
|
||||
- **WHEN** the package is imported and used with no OTel exporter registered
|
||||
- **THEN** no error is thrown and no global state is mutated at import time
|
||||
|
||||
#### Scenario: a pack records span, counter, and histograms
|
||||
|
||||
- **WHEN** `pack` runs against a real in-memory `MeterProvider` and `TracerProvider`
|
||||
- **THEN** one `audio_sprite.pack` span is recorded, `audio_sprite.pack_total` increments by 1, and both histograms record one observation each
|
||||
|
||||
**Verified by:** `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"pack records OTel instruments when an exporter is registered"` AND `tests/purity.test.ts::"importing the package mutates no global state"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Subpath exports per feature module
|
||||
|
||||
`package.json` SHALL declare one `exports` entry per feature module (`./core/audio-sprite-packer/audio-sprite-packer`, `./adapters/null-adapter/null-adapter`, `./utils/manifest/manifest`) in addition to the root `.` barrel, each resolving to a typed `import` condition. `sideEffects` SHALL be `false`.
|
||||
|
||||
#### Scenario: each feature module is independently importable
|
||||
|
||||
- **WHEN** a consumer imports `@suaveplan/audio-sprite-packer/adapters/null-adapter`
|
||||
- **THEN** the import resolves to the NullAudioAdapter module without pulling the whole package barrel
|
||||
|
||||
**Verified by:** `tests/exports.test.ts::"every feature module has a subpath export entry"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Pack options silence padding and gain normalisation
|
||||
|
||||
`PackOptions` SHALL support `silencePaddingMs` (default 100), `stripSilence` (default true), and `normalise` (default false). When `stripSilence` is true, the adapter's `stripSilence` SHALL be called per clip before concatenation. When `normalise` is true, the adapter's `normalise` SHALL be called per clip. Silence padding SHALL append `sampleRate × channels × silencePaddingMs / 1000` zero-valued float samples between clips.
|
||||
|
||||
#### Scenario: silence padding increases total duration
|
||||
|
||||
- **WHEN** two clips are packed with `silencePaddingMs: 100`
|
||||
- **THEN** the manifest `totalDurationSeconds` is greater than the sum of the raw clip durations by approximately 0.1 seconds
|
||||
|
||||
#### Scenario: normalised clips have consistent peak amplitude
|
||||
|
||||
- **WHEN** `pack` is called with `normalise: true` and clips of varying amplitude
|
||||
- **THEN** each clip is passed to `adapter.normalise` before encoding
|
||||
|
||||
**Verified by:** `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"silence padding increases total duration"` AND `src/core/audio-sprite-packer/audio-sprite-packer.test.ts::"normalise invokes adapter.normalise per clip"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
@@ -0,0 +1,83 @@
|
||||
# Tasks: enterprise-audio-sprite-packer
|
||||
|
||||
**Change ID**: enterprise-audio-sprite-packer
|
||||
**Package**: `@suaveplan/audio-sprite-packer`
|
||||
**Target path**: `universal/compression/audio-sprite-packer`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/crypto-utils`
|
||||
|
||||
---
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory `universal/compression/audio-sprite-packer/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/mime workspace:^`, `@suaveplan/crypto-utils workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] Write `src/types/common.ts` — `AudioFormat`, `AudioClipInput`, `AudioSpriteEntry`, `AudioSpriteManifest`, `AudioSprite`, `PackOptions`, `AudioAdapter`, `AudioSpritePackerOptions`.
|
||||
- [ ] Write `src/types/common.md`.
|
||||
- [ ] Write `src/error-codes.ts` — `AudioSpriteErrorCode`, `AUDIO_SPRITE_ERROR_METADATA`, `registerAudioSpriteErrorCodes()`.
|
||||
- [ ] Write Zod schemas: `AudioSpriteEntrySchema`, `AudioSpriteManifestSchema`, `PackOptionsSchema`, `AudioSpritePackerOptionsSchema`.
|
||||
|
||||
---
|
||||
|
||||
## 3. NullAudioAdapter
|
||||
|
||||
- [ ] Implement `NullAudioAdapter` — `probe` returns configurable fixture metadata (WAV, 44100 Hz, 2ch, 1.0 s), `decode` returns 44100 × 2 float32 zeros, `encode` returns input bytes, `stripSilence` returns input unchanged, `normalise` returns input unchanged.
|
||||
- [ ] Write `null-adapter.test.ts` and `null-adapter.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Manifest utilities
|
||||
|
||||
- [ ] Implement `buildManifest(entries, packedBuffer): AudioSpriteManifest` — assembles manifest including SHA-256 content hash via `@suaveplan/crypto-utils`.
|
||||
- [ ] Implement `validateManifest(manifest): void` — checks version, entries array non-empty, offsets non-overlapping.
|
||||
- [ ] Write `manifest.test.ts` and `manifest.md`.
|
||||
|
||||
---
|
||||
|
||||
## 5. AudioSpritePacker
|
||||
|
||||
- [ ] Implement `AudioSpritePacker.pack(clips, options, signal)`:
|
||||
1. Validate clips non-empty.
|
||||
2. For each clip: detect format (`@suaveplan/mime`), probe, decode PCM.
|
||||
3. If `stripSilence`, call `adapter.stripSilence`.
|
||||
4. If `normalise`, call `adapter.normalise`.
|
||||
5. Append silence padding (zero-fill float32 × sampleRate × silencePaddingMs / 1000).
|
||||
6. Encode all clips concatenated as single output buffer.
|
||||
7. Build manifest with byte offsets per clip.
|
||||
8. Return `{ data, manifest }`.
|
||||
- [ ] Implement `AudioSpritePacker.unpack(sprite, clipName)` — slice-and-return using manifest offsets.
|
||||
- [ ] Wire `AbortSignal` propagation; throw on abort.
|
||||
- [ ] Wire OTel: span `audio-sprite.pack`, counter, histogram, compression ratio.
|
||||
- [ ] Write `audio-sprite-packer.test.ts` (≤500 lines): pack 3 clips, unpack each, abort, empty clips throws.
|
||||
- [ ] Write `audio-sprite-packer.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks
|
||||
|
||||
- [ ] Write `src/__benchmarks__/audio-sprite-packer.bench.ts` — pack 10 clips, pack 50 clips (null adapter).
|
||||
|
||||
---
|
||||
|
||||
## 7. Tests
|
||||
|
||||
- [ ] Write `tests/integration.test.ts` — full pack/unpack round-trip.
|
||||
- [ ] Write `tests/property.test.ts` (fast-check) — manifest entry count = clip count, unpack returns correct slice, silence padding duration.
|
||||
|
||||
---
|
||||
|
||||
## 8. Docs + verify + publish
|
||||
|
||||
- [ ] All co-located `.md` files (≥200 words each).
|
||||
- [ ] Write `README.md` at package root.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/audio-sprite-packer` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/audio-sprite-packer` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/audio-sprite-packer`.
|
||||
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-audio-sprite-packer/`.
|
||||
Reference in New Issue
Block a user