Initial Commit

SUMMARY.md

@@ -0,0 +1,474 @@
+# Migration Summary
+
+> Per-package summaries for every library shipped, in flight, or pending migration on `genesis`. The companion [`STATUS.md`](./STATUS.md) is the at-a-glance dashboard with status icons; this file holds the longer descriptions.
+>
+> Sections: **Completed** — migrated from `../suaveplan/` and building on genesis. **Pending** — still in `../suaveplan/` awaiting their port. **Genesis-Original** — created directly here, no suaveplan equivalent.
+>
+> Update this file when finishing a package: paste the README's first-paragraph summary into the matching section.
+>
+> **Architecture references for the drive / storage / network layers (added 2026-05-02):**
+>
+> - [`docs/storage/`](docs/storage/) — `AbstractStorage` contract, capability matrix, every backend (Memory, S3, OPFS, IndexedDB, Node fs, SQLite, FAT/exFAT/ext4 via WASM, ContentAddressed, Garage).
+> - [`docs/drive/`](docs/drive/) — thin VFS core, the two indexes (DirIndex + FileLocationIndex), plugin chain, on-the-fly encrypt/sign/decrypt/verify, mesh + sharing.
+> - [`docs/network/`](docs/network/) — `NetworkNode` + 21-plugin substrate, Tier 0/1/2 topology with meshed pockets, four hosting models, server failover, Ed25519 signing + token model, offline mode + reconciliation.
+> - [`docs/drive-storage-network.md`](docs/drive-storage-network.md) — the composition map: end-to-end write/read traces, what-vanishes-when-server-vanishes, deployment recipes.
+>
+> When migrating any package in the drive/storage/network space, **read these first** — they encode the genesis design decisions (`drive-port` over `enterprise-drive`, `enterprise-types-cross-cutting` archived 2026-05-02 as canonical interface home, `drive-network-integration` boundary contract) that downstream proposals must conform to.
+
+## Completed
+
+**207** packages already migrated from suaveplan to genesis (per `STATUS.md` ✅, refreshed 2026-05-12). The table below is partially stale — refresh per-row entries from each package's `README.md` first paragraph when next touched.
+
+| Package | Summary |
+| --- | --- |
+| `@suaveplan/ab-testing` | Enterprise A/B testing and experimentation engine with deterministic FNV-1a bucketing, targeting rules, variant assignment, conversion tracking, result aggregation, and OpenTelemetry instrumentation. |
+| `@suaveplan/api-schemas` | Shared Zod schemas describing Suaveplan API request/response shapes. The single source of truth for server plugins, React data hooks, and generated OpenAPI documents. |
+| `@suaveplan/audit-logging` | Tamper-proof, GDPR-compliant audit logging for the Suaveplan monorepo. Provides a cryptographic chain-integrity engine, pluggable storage adapters, GDPR data export, configurable retention policies, and a rich event taxonomy spanning auth, authorization, data access, system, and GDPR events. |
+| `@suaveplan/auth` | Provider-agnostic authentication library for the Suaveplan monorepo. Ships JWT token lifecycle, API key management, session management, and framework-agnostic middleware — all backed by a pluggable AuthAdapter interface. |
+| `@suaveplan/barcode` | Runtime-agnostic 1D barcode generation for seven symbologies — Code 128B, Code 39, EAN-13, EAN-8, UPC-A, UPC-E, and ITF. Outputs inline SVG strings and binary bar-pattern arrays with no canvas, no DOM, and no Node.js built-ins required, making it safe to use in Bun, Deno, edge runtimes, and browsers alike. Includes check-digit calculation, barcode validation, and human-readable text rendering. Use this package to generate product labels, shipping labels (ITF/GTIN-14), retail barcodes (EAN/UPC), and document barcodes (Code 128). For 2D barcodes (QR codes) use @suaveplan/qrcode. This package does not support barcode scanning/decoding from images — it is generation-only. |
+| `@suaveplan/bitpacker` | Bit-level binary packing and unpacking for TypeScript. Designed for network protocols, game-state serialisation, and compact binary formats. Pure TypeScript, zero runtime deps beyond @suaveplan/error. Hardened 2026-05-03 (`bitpacker-hardening` archived): Zod boundary validation on `BitPacker`/strategy/context types, `./register-schemas` subpath integrating with `@suaveplan/schema-registry` (subject `bitpacker:@suaveplan/bitpacker` v1, idempotent), OTel `instruments.ts` (tracer/meter `@suaveplan/bitpacker`, spans `bitpacker.pack` / `bitpacker.unpack`, counters `bitpacker.ops.total`, histograms `bitpacker.op.duration_ms` + `bitpacker.op.bytes`), fast-check round-trip property tests, and a committed mitata baseline at `scripts/bench/bitpacker-baselines.json`. The whole bitpacker family (`-strategies`, `-validation`, `-game`, `-streaming`, `-compressed`, `-network`) shares the same hardening pattern; `bitpacker-strategies` additionally gained opt-in forward-tolerance on the `_version` strategy via `_tolerance: "strict" \| "forward"` + `_allowedVersions: number[]`. Every implementation `.ts` in the family now has a sibling `.md` (47 new docs files). |
+| `@suaveplan/cache` | Type-safe caching abstraction for the genesis monorepo. Provides MemoryCache with LRU/LFU/FIFO/TTL eviction, NamespacedCache for shared-storage isolation, a CacheFactory with module-augmentation-based provider registry, stale-while-revalidate, multi-get/set, injectable clock and event bus, OTel instrumentation, and structured CACHE. error codes. |
+| `@suaveplan/cache-storage` | `AbstractCache<T>` backend that bridges any `@suaveplan/storage` `AbstractStorage` into a typed cache via a 32-byte fixed-width TTL header and pluggable `Codec<T>` (JSON default, identity for `Uint8Array`). Auto-registers as the `"storage"` provider on `CacheFactory`. Subsumes the upstream `cache-browser` package — wire `StorageCache` over `storage-browser-{localstorage,indexeddb,opfs}` and the cache surface is identical to `MemoryCache`. |
+| `@suaveplan/cache-redis` | `AbstractCache<T>` backend over a minimal `RedisLike` interface — native `SET ... EX`, `GET`, `DEL`, `EXISTS`, `TTL`, `SCAN`. Reuses `@suaveplan/cache-storage` codecs (JSON / identity / base64). TTL is server-managed (no client header bytes, no client-side eviction). Auto-registers as the `"redis"` provider on `CacheFactory`. |
+| `@suaveplan/cli` | Enterprise-grade CLI framework for Node.js. Composable fluent API with subcommand routing, option parsing, OTel tracing, and a full set of terminal UI primitives. |
+| `@suaveplan/compress-image` | Runtime-agnostic image compression utilities with pluggable adapters for Node.js (Sharp) and testing (MemoryAdapter). Supports resize, quality reduction, format conversion (JPEG, PNG, WebP, AVIF), and metadata stripping. |
+| `@suaveplan/compress-svg` | SVG optimisation and minification for TypeScript. Pure TypeScript — no DOMParser, no external SVG library. Runs in Bun, Node.js, browsers, and edge runtimes. |
+| `@suaveplan/config` | Layered configuration management for the Suaveplan monorepo. Resolves an ordered set of typed layers (defaults, file, object, env, CLI) in priority order, deep-merges the results, applies per-environment overrides, validates via a caller-supplied Zod schema or custom function, and exposes an immutable ConfigStore with live reload and event-bus change propagation. |
+| `@suaveplan/crdt` | Conflict-free Replicated Data Types (CRDTs) for distributed systems. Provides |
+| `@suaveplan/crypto` | Universal cryptographic primitives — engine-pluggable AEAD, Ed25519/ECDSA-P256 signing, X25519 key agreement, sealed-box, and auth-box. Built on audited @noble/ libraries with zero WASM. |
+| `@suaveplan/cryptocurrency` | Universal-tier cryptocurrency utility library — wallet address validation across 15 mainnet chains (Bitcoin, Ethereum, Solana, Polygon, Arbitrum, Optimism, Avalanche, BSC, Base, TRON, Litecoin, Dogecoin, Cardano, Polkadot, Cosmos) with chain auto-detection and simplified positional EIP-55 checksumming; transaction-hash classification across EVM / UTXO / Solana shapes; static + adapter-backed chain registry (`MemoryChainRegistry`, `ChainRegistry` async façade with optional `LoggerLike` injection emitting `chain.registered` / `chain.lookup.miss` events and raising typed `CryptocurrencyError({ code: CRYPTOCURRENCY.UNKNOWN_CHAIN })`); 8-entry `COMMON_TOKENS` ERC-20 catalogue + `TokenRegistry` with case-insensitive address lookup, substring search by symbol / name, and `formatTokenBalance` bigint formatter; EIP-1559 gas estimator (`estimateGas`, `calculateMaxFeePerGas`, `calculateEffectiveGasPrice`, `formatGwei`, `estimateTxCostEth`) with bigint-pure arithmetic throughout; calldata + 4-byte function-selector decoder (`KNOWN_SELECTORS`, `lookupSelector`, `extractSelector`, `decodeCalldata`) covering ERC-20 / ERC-721 hot paths; generic + convenience unit conversion across ETH (wei / kwei / mwei / gwei / microether / milliether / ether), BTC (satoshi / microbitcoin / millibitcoin / bitcoin), SOL (lamport / sol). 5-code `CryptocurrencyError` registry (`UNKNOWN_CHAIN`, `UNKNOWN_CURRENCY`, `UNKNOWN_UNIT`, `INVALID_ADDRESS`, `INVALID_HASH`) extending `SuaveplanError` with `chainId` / `currency` / `unit` discriminants. 11 subpath exports tree-shake every public module. 183 tests across 11 files at 100/100/100/100 (Istanbul). Deps: `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/data-masking` | PII/sensitive data masking for objects and strings with field-level rules, |
+| `@suaveplan/datetime` | Timezone-aware date/time utilities covering the most common application-layer date operations that the native Date API leaves unaddressed. The package provides calendar math (addDuration, subtractDuration, startOf, endOf, getCalendarMonth, leap-year detection), business-day arithmetic with configurable holiday calendars and custom weekend definitions, an RRULE-subset recurrence engine (DAILY/WEEKLY/MONTHLY/YEARLY with BYDAY/BYMONTH/COUNT/UNTIL), and human-readable relative time formatting ("3 hours ago", "in 2 days"). All stateful entry points accept an injectable Clock for deterministic testing. Use this package for scheduling UIs, calendar components, invoice date calculations, and any domain where "next business day" or "every other Monday" has real meaning. For low-level stopwatches, throttle/debounce, or vector clocks use @suaveplan/timing. |
+| `@suaveplan/db` | Universal relational database adapter interface for the Suaveplan monorepo. Provides the DatabaseAdapter contract (extending DatabaseLike from @suaveplan/types), injectable connection singletons, structured DB. error codes, Zod-validated config types, a MigrationRunner interface, and full OpenTelemetry instrumentation. |
+| `@suaveplan/db-sqlite` | Universal SQLite adapter for the Suaveplan monorepo. Runs on bun:sqlite on the Bun server and @sqlite.org/sqlite-wasm (Web Worker) in the browser, unified behind a single SqliteAdapter that implements DatabaseAdapter from @suaveplan/db. Includes an LRU prepared-statement cache (128 entries by default), a forward-only ledger-tracked MigrationRunner with dry-run support, OpenTelemetry span instrumentation, structured SQLITE error codes, and a ./unsafe subpath for raw queries. |
+| `@suaveplan/dedup` | Entity deduplication engine for detecting and merging duplicate records in any data set. Given a list of objects with varying representations of the same real-world entity (e.g. "John Smith" vs "J. Smith", or the same email in different capitalisation), the DedupEngine scores pairs using a weighted combination of field-level similarity algorithms — Jaro-Winkler, Levenshtein, exact match, or phonetic — groups records into connected components via union-find, and merges each group with a pluggable strategy (latestWins, manual, or scoredMerge). Use this package for ETL pipelines, contact deduplication, and data cleansing. For domain-name-specific normalisation and alias resolution use @suaveplan/domain-normalizer; for string-similarity primitives only, the scoring module is exported as a standalone subpath. |
+| `@suaveplan/diff` | Zero-dependency RFC 6902 JSON Patch engine for computing, applying, and inverting structural differences between JSON documents. The diff(a, b) function produces a minimal patch using index-based or LCS array strategies; applyPatch applies it; revertPatch undoes it; and invertPatch creates an inverse patch. A HistoryManager provides undo/redo with configurable depth and branch truncation on new edits. A SyncManager handles optimistic concurrency: apply local changes speculatively, then reconcile when the server responds. RFC 6901 JSON Pointer parsing and formatting is exposed as a standalone path module. Use this package for collaborative editing, undo/redo stacks, change-event streams, and any system where you need to track or transmit the delta between two object states rather than the full state itself. |
+| `@suaveplan/dmarc` | DMARC report parser for @suaveplan — parses aggregate (RUA) and forensic (RUF) DMARC XML reports into validated, strongly-typed structures. Accepts raw XML strings or gzip-compressed binary blobs. |
+| `@suaveplan/drive` | Lightweight virtual filesystem core for the Suaveplan monorepo. File-level operations over `AbstractStorage` with a plugin slot for middleware, chunking, encryption, and P2P mesh. Structural `DriveStorage` typing, generic storage map narrowing, lifecycle ownership tracking, and capability-aware stream fallbacks. |
+| `@suaveplan/drive-plugin-chunks` | Chunk-addressing plugin for `@suaveplan/drive`. Splits files into signed, encrypted chunks using the locked `version 0x0001` binary format, with server-signed manifests and two storage layouts (`sparse-file` and `chunk-keys`). XChaCha20-Poly1305 per-chunk encryption, Ed25519 server signatures, deterministic per-chunk nonces, automatic layout selection based on storage capabilities, and read middleware for transparent reassembly. |
+| `@suaveplan/domain-normalizer` | Normalisation, matching, and alias-canonicalisation for internet domain names. Given heterogeneous URL or domain input — including common mobile/CDN subdomains and 31 built-in alias mappings (e.g. m.youtube.com → youtube.com, old.reddit.com → reddit.com) — this package produces a canonical registrable domain via tldts, strips www/m/mobile prefixes, resolves the alias map, and returns structured NormalizedDomain objects. It also provides Levenshtein-based similarity scoring (computeSimilarity), fuzzy matching (matchDomains), and a groupDomains function that clusters a mixed list by canonical root domain. Use this package for deduplicating contact email domains, canonicalising URLs before storage, and building domain-level blocklists. For full entity deduplication across arbitrary fields use @suaveplan/dedup; for MIME or URL content-type detection use @suaveplan/mime. |
+| `@suaveplan/env` | Type-safe, schema-first environment variable loading for Node.js and edge runtimes. Define a schema of typed field builders, point it at your sources, and receive a frozen record with TypeScript types inferred at compile time — no manual type annotations required. |
+| `@suaveplan/error` | Foundation error substrate for the Suaveplan monorepo. Every non-testing @suaveplan/ package extends this library's SuaveplanError base class and uses its stable code registry. The package provides: SuaveplanError<TCode> — an abstract base with literal-typed discriminant codes, injectable clock, context bag, traceId, and cause chaining; defineCodes(namespace, reasons) — a frozen, literal-typed registry that makes error codes refactor-safe; walkCauses(err) — a cycle-safe, depth-bounded generator for traversing nested error causes; lossless JSON and binary wire formats (toJSON/fromJSON/toBinary/fromBinary) with Zod validation; markSensitive/unwrapSensitive for redaction at serialization boundaries; toSpanEvent for OpenTelemetry exception span events without an OTel SDK import; and a setMessageResolver hook for i18n. Zero @suaveplan/ runtime or peer dependencies — this is the lowest-level package in the stack. |
+| `@suaveplan/etl` | Extract-Transform-Load pipeline engine with typed stages, error handling, observable progress, and OTel instrumentation. |
+| `@suaveplan/event-sourcing` | Event sourcing patterns for the genesis monorepo: typed aggregate root, in-memory event store with optimistic concurrency, snapshot support, projections, upcasting, and OTel instrumentation. |
+| `@suaveplan/events` | Typed event-bus substrate for the Suaveplan monorepo. Pub/sub with deterministic FIFO delivery, interceptor API, bounded-queue backpressure, idempotent listeners, Zod-validated envelopes, and a passive observability adapter. |
+| `@suaveplan/events-metrics` | OTel metrics companion for @suaveplan/events. Attaches via the public interceptor API to record dispatch totals, listener error counts, and latency histograms per event name. |
+| `@suaveplan/events-otel` | OpenTelemetry tracing companion for @suaveplan/events. Wraps each dispatch in a span, propagates W3C Trace Context, and records listener exceptions as span errors. |
+| `@suaveplan/events-schema` | Runtime schema-validation companion for @suaveplan/events. Validates event payloads at dispatch boundaries via Zod schemas with strict/warn/sample modes and sensitive field redaction. |
+| `@suaveplan/events-transport` | Cross-context event bridges for @suaveplan/events: MessageChannel (at-least-once with ack/retry) |
+| `@suaveplan/exif` | Dependency-free, runtime-agnostic EXIF/XMP/IPTC metadata reader, writer, and stripper for JPEG and PNG images. Parses JPEG segment chains to locate and decode the EXIF IFD (TIFF byte-order aware, including GPS and SubIFD), IPTC IIM (caption, keywords, copyright), and XMP Dublin Core (raw XML string extraction). Writes back a revised EXIF IFD without re-encoding the image pixels, and strips all metadata segments for privacy-preserving image export. Includes a ByteReader/ByteWriter pair with rational arithmetic helpers and CRC-32 for PNG chunks. Use this package when you need to read camera metadata (make, model, GPS coordinates, orientation, focal length), watermark images with IPTC copyright fields, or scrub location data before publishing user-uploaded photos. For audio file metadata (ID3, MP4 atoms, FLAC Vorbis) use @suaveplan/audio-metadata. |
+| `@suaveplan/feature-flags` | Provider-agnostic feature flag evaluation engine for controlling feature rollout without code deploys. The package ships a FlagManager high-level façade, a FlagRegistry backed by any pluggable FlagProvider, and an Evaluator strategy chain. Five composable strategies cover the full rollout playbook: PercentageStrategy (deterministic FNV-1a bucketing for consistent user cohorts), UserTargetStrategy (allowlist), AttributeStrategy (10 comparison operators for segment targeting), ScheduleStrategy (time-window gating), and CompositeStrategy (AND/OR combinator). Built-in providers include MemoryProvider and JsonProvider for file-based flag definitions. Evaluation priority is: flag disabled → in-process override → first matching strategy → default value. This package is for runtime flag evaluation only — it is not a flag management UI or remote config service. |
+| `@suaveplan/font-compress` | BTF (Binary TypeFace) binary packing and unpacking. Converts TypefaceFont (typeface.js JSON format) to a compact Uint8Array using dictionary-based integer compression, and reverses it. |
+| `@suaveplan/fsm` | Typed, generic finite state machine (FSM) for TypeScript. Ships a synchronous-by-default interpreter with guard predicates, ordered transition actions, context threading, entry/exit lifecycle hooks, history recording, and OTel instrumentation. Zero peer dependencies beyond @suaveplan/error, @suaveplan/events, and @suaveplan/types. |
+| `@suaveplan/i18n` | Enterprise-grade internationalization (i18n) core for the Suaveplan monorepo. Works in Bun, Node.js, and modern browsers — zero DOM dependencies, tree-shakeable subpath exports. The package covers the full i18n surface: a namespaced `MessageCatalog<TLocale, TMessages>` with `t<K extends DotPaths<TMessages> \| (string & {})>` typed key inference, the ergonomic options bag (`count` / `context` / `defaultValue` / `values` / nested `$t(other.key)` references with depth-4 cycle detection), namespace-scoped `set` / `load` / `keys`, in-flight loader dedup with `LOADER_FAILED` wrapping, source-discriminated `LookupResult { value, locale, namespace, source: 'catalog' \| 'fallback' \| 'handler' \| 'key' }`, and strict mode that throws`MISSING_KEY`. The full ICU MessageFormat surface lands here too: an`InterpolationEngine` with `{{ variable }}`-style tokens, locale-aware per-slot`ValueFormatter`s, and HTML-escape support; a`MessageParser`AST covering plural / select / selectordinal / typed-argument (`{date, date, short}` / `{n, number, currency/USD}`) / apostrophe quoting / rich-text tag interpolation (with a`formatChunks<T>` path that returns `Array<string \| T>` for React consumers); a `PluralizationEngine` with 14 hand-written language rules (Arabic, Russian, Celtic, etc.) plus an `Intl.PluralRules` first-resolution fallback so new CLDR languages work without a code change; ten formatters wrapping every common `Intl.*`API (`formatDate`,`formatCurrency`,`formatNumber`,`formatRelativeTime`,`formatList`,`formatDisplayName`,`formatPercent`,`formatCompact`,`formatUnit`,`formatSegment`,`compareLocale`) with per-(locale, options) caching; a`LocaleResolver` with `Intl.Locale.weekInfo`-aware`getDayNames`, BCP-47 validation that throws`INVALID_LOCALE` on garbage, script-casing-preserving `parseAcceptLanguage`, and the four-strategy chain (`exact` / `alias` / `language` / `region`); server-side`createLocaleMiddleware` with optional `setHeader('Content-Language', ...)`. Five built-in`Backend`implementations (`MemoryBackend`,`HttpBackend`,`StorageBackend` wrapping any `AbstractStorage` from `@suaveplan/storage`,`MultiFileFsBackend`,`ChainedBackend` with write-through caching) make translation loading pluggable; `MessageCatalog.preload` / `getAsync` / `invalidate` / `saveMissing` complete the lazy-load story. The `I18nInstance`facade composes every engine plus a plugin lifecycle (`use(plugin)` + `dispose()` in reverse-registration order), five canonical event topics on the `@suaveplan/events`-backed bus (`languageChanged` / `loaded` / `missingKey` / `keyAdded` / `pluralRuleAdded`), the`pseudoLocalize`post-processor (`accent` / `bracket` / `expand` modes) plus `pseudoLocalizationPlugin`, and the`createMissingKeyReporter` plugin with `persistMissing` opt-in routing through `backend.save`. Every engine constructor calls`<Schema>.safeParse(options)` and surfaces Zod failures as `I18nError` with `context.zodIssues` populated. OTel meter instruments built via `getMeter('suaveplan.i18n')` cover every hot path: `i18n.translate.total{outcome,locale}`,`i18n.translate.duration_ms`,`i18n.locale.resolve.total{strategy,locale}`,`i18n.interpolation.duration_ms`,`i18n.missing_key.total`,`i18n.format.<name>.duration_ms`,`i18n.format.cache_hit`,`i18n.backend.read.duration_ms{backend.name,outcome}`,`i18n.backend.read.total`,`i18n.backend.write.total`, and the observable`i18n.backend.cache.size` gauge. Twelve frozen `I18N.*`error codes (`MISSING_KEY` / `INVALID_LOCALE` / `INVALID_OPTIONS` / `LOADER_FAILED` / `INTERPOLATION_ERROR` / `PLURAL_RULE_NOT_FOUND` / `BACKEND_READ_FAILED` / `BACKEND_WRITE_FAILED` / `BACKEND_NOT_REGISTERED` / `BACKEND_LOCALE_NOT_AVAILABLE` / `INVALID_FORMATTER_OPTIONS` / `UNSUPPORTED_LOCALE` / `NESTING_DEPTH_EXCEEDED` / `PLUGIN_ALREADY_INSTALLED`). Do not confuse with @suaveplan/templates, which handles string interpolation in non-i18n contexts — this package is specifically for locale-keyed message catalogs and locale-sensitive formatting. |
+| `@suaveplan/i18n-backend-memory` | Universal-tier in-memory translation backend for the @suaveplan/i18n family. Ships `MemoryBackend` (full 5-flag capability matrix — `canRead/canReadMulti/canSave/canTrackModification: true`, `canWatch: false`) and `memoryBackend()` factory. Backed by `Map<locale, Map<namespace, TranslationRecord>>` plus a modification ledger keyed by `${locale} ${namespace}`. Implements every `Backend` method (`read` / `readMulti` / `save` / `lastModified`) with optional `signal?: AbortSignal` parameters that throw `I18nError(I18N.BACKEND_TIMEOUT)` on pre-aborted signals. Constructor accepts injectable `now: () => number` for deterministic `lastModified` testing. Zod boundary validation via `MemoryBackendOptionsSchema` throws `I18nError(I18N.INVALID_OPTIONS)` on malformed input. OTel surface: `i18n.backend.memory.read_duration_ms` (histogram), `read_total{outcome}` (counter), `read_errors_total{code}` (counter), `write_duration_ms` (histogram), `write_total{outcome}` (counter). Tested with the shared `runBackendConformance(...)` harness from `@suaveplan/i18n-shared/testing`. Universal — runs identically in browser and server with no platform-specific imports. Zero runtime dependency on `@suaveplan/i18n` core; depends only on `@suaveplan/i18n-shared`, `@suaveplan/types`, `@suaveplan/error`, `@opentelemetry/api`, `tslib`, and `zod`. |
+| `@suaveplan/i18n-backend-http` | Universal-tier `fetch`-based translation backend for the @suaveplan/i18n family. Ships `HttpBackend` (read-only 5-flag capability matrix — `canRead: true`; `canReadMulti`/`canSave`/`canTrackModification`/`canWatch: false`) and `httpBackend()` factory. Fetches `<loadPath>` per `(locale, namespace)` via injectable `fetchFn` (defaults to `globalThis.fetch`; `defaultFetch()` returns a stub throwing `BACKEND_READ_FAILED` when `globalThis.fetch` is unavailable). URL templating substitutes `{locale}` and `{namespace}` placeholders with `encodeURIComponent`-applied values via the exported `buildUrl(loadPath, locale, namespace)` helper. Pluggable `parsePayload` (default `defaultParsePayload`: JSON-object parser rejecting arrays, null, and primitive payloads as `BACKEND_READ_FAILED` because translation records are always objects). Pluggable `customHeaders(locale, namespace)` builder merged into every `RequestInit`; `crossDomain: true` shorthand sets `credentials: "include"` + `mode: "cors"` (preserving any explicit `requestOptions` overrides). Optional `retry?: HttpBackendRetry` (structurally compatible with `@suaveplan/retry`'s `RetryPolicy` so consumers can pass that instance directly without `@suaveplan/i18n-backend-http` taking a hard dep) wraps every fetch. Optional `signal?: AbortSignal` on `read` throws `I18nError(I18N.BACKEND_TIMEOUT)` on pre-aborted signals (no network request issued) and is threaded into the underlying `RequestInit` so `fetch` can cancel mid-flight; AbortError / `ABORT_ERR` codes surfaced from `fetchFn` map to `BACKEND_TIMEOUT` so consumers can distinguish cancellation from transport faults. Error semantics: HTTP 404 → `I18nError(I18N.BACKEND_LOCALE_NOT_AVAILABLE)` (the chained-backend fallthrough signal); HTTP 5xx, network failures (`TypeError` from `fetch`), and parse failures → `I18nError(I18N.BACKEND_READ_FAILED)` (chain-stopping — transport failures must propagate, not silently degrade). Zod boundary validation via `HttpBackendOptionsSchema` throws `I18nError(I18N.INVALID_OPTIONS)` on malformed input. OTel surface: `i18n.backend.http.read_duration_ms{locale,namespace,outcome}` (histogram, milliseconds), `read_total{outcome}` (counter, `outcome ∈ hit / miss / error`), `read_errors_total{code,status?}` (counter — `code` is the `I18N.*` error code; `status` is the HTTP status string when the error originated from a known HTTP response, omitted for transport / parse failures). Tested with the shared `runBackendConformance(...)` harness from `@suaveplan/i18n-shared/testing`. Universal — runs identically in browsers, Bun, and Node.js >= 18. Zero runtime dependency on `@suaveplan/i18n` core, on `@suaveplan/retry`, or on any other backend package; depends only on `@suaveplan/i18n-shared`, `@suaveplan/types`, `@suaveplan/error`, `@opentelemetry/api`, `tslib`, and `zod`. |
+| `@suaveplan/i18n-backend-storage` | Universal-tier `AbstractStorage`-backed translation backend for the @suaveplan/i18n family. Ships `StorageBackend` (full 5-flag capability matrix — `canRead/canReadMulti/canSave/canTrackModification: true`, `canWatch: false`) and `storageBackend()` factory. Adapts any `AbstractStorage` instance from `@suaveplan/storage` (`MemoryStorage`, `OPFSStorage`, `IndexedDBStorage`, `S3Storage`, `NodeFsStorage`, `SqliteStorage`, `GarageStorage`, content-addressed CDNs, …) into a `Backend`. Three wire layouts driven by a constructor option: `single-key-per-namespace` (default — one storage key per `(locale, namespace)` at `<prefix>/<locale>/<namespace>.json`), `single-key-per-locale` (one storage key per locale at `<prefix>/<locale>.json` holding the whole namespace map; saves are read-modify-write of the locale map), `flat-keys` (one storage key per leaf string at `<prefix>:<locale>:<namespace>:<dotPath>`; reads list-by-prefix and reassemble; saves write each leaf independently). Pluggable codec via constructor `encode` / `decode`; the exported `defaultCodec` does JSON via `TextEncoder` / `TextDecoder` and rejects non-object payloads (arrays, null, primitives) as `BACKEND_READ_FAILED` because translation records are always objects in the contract. Optional `signal?: AbortSignal` on `read` / `readMulti` / `save` throws `I18nError(I18N.BACKEND_TIMEOUT)` on pre-aborted signals. Zod boundary validation via `StorageBackendOptionsSchema` throws `I18nError(I18N.INVALID_OPTIONS)` on malformed input or missing `storage`. `lastModified` consults `AbstractStorage.getMetadata().modifiedAt` (max across leaves for `flat-keys`); swallows storage exceptions and returns `undefined` rather than throw. Storage failures surface as `BACKEND_WRITE_FAILED` (with `cause`) preserving any inner `I18nError` unwrapped. OTel surface: `i18n.backend.storage.read_duration_ms` (histogram), `read_total{outcome,layout}` (counter — `outcome ∈ hit / miss / error`),`read_errors_total{code,layout}` (counter), `write_duration_ms` (histogram), `write_total{outcome,layout}` (counter — `outcome ∈ ok / error`). The`layout` attribute is a 3-value low-cardinality enum so production teams can chart per-layout latency. Tested with the shared `runBackendConformance(...)` harness from `@suaveplan/i18n-shared/testing` against all three layouts. Universal — runs identically in browser and server; the concrete `AbstractStorage` decides the deployment tier. Zero runtime dependency on `@suaveplan/i18n` core; depends on `@suaveplan/i18n-shared`,`@suaveplan/types`,`@suaveplan/storage`,`@suaveplan/error`,`@opentelemetry/api`,`tslib`, and`zod`. |
+| `@suaveplan/i18n-backend-chained` | Universal-tier chained backend orchestrator for the @suaveplan/i18n family. Ships `ChainedBackend` (capabilities matrix derived from union of children — `canRead: true`, `canSave/canTrackModification/canWatch` each follow `backends.some(...)`) and `chainedBackend()` factory accepting either an array shorthand or full options object. `read(locale, namespace, signal?)` walks `backends` in registration order; the first backend whose `read` resolves wins, subsequent backends are skipped. `BACKEND_LOCALE_NOT_AVAILABLE` triggers fallthrough to the next backend; `BACKEND_READ_FAILED` propagates immediately to stop the chain (transport failures must not silently degrade). After a successful read from backend N (where N > 0) the resolved record is written back to every preceding backend (0..N-1) that implements `save` — best-effort, per-backend save failures swallowed and never block the read return. When every backend in a non-empty chain reports `BACKEND_LOCALE_NOT_AVAILABLE` the chain throws the same code (preserves catalog-layer fallthrough semantics one level up); when the chain is empty at runtime past the schema check the chain throws `CHAINED_BACKEND_ALL_FAILED` defensively. `readMulti(locale, namespaces, signal?)` fans out concurrently and merges per `mergeStrategy` (`first-wins` default — earlier backends win on overlap, later backends fill gaps; `last-wins` — later backends win on overlap, earlier backends fill gaps); per-backend `readMulti` errors are swallowed (slot omitted, not propagated). `save(locale, namespace, record, signal?)` calls `save` on every save-capable child sequentially; failures surface as `BACKEND_WRITE_FAILED` with `cause` preserved (existing `I18nError` instances pass through unchanged). `lastModified` walks children in order returning the first defined timestamp. `init(context)` forwards in registration order; `dispose()` runs in reverse — both safely callable multiple times and skip children that do not implement the hook. Optional `signal?: AbortSignal` on `read` / `readMulti` / `save` throws `I18nError(I18N.BACKEND_TIMEOUT)` on pre-aborted signals before any child is called, and is threaded into every child call when the child accepts a third positional argument. Zod boundary validation via `ChainedBackendOptionsSchema` rejects empty `backends` arrays as `INVALID_OPTIONS`. OTel surface: `i18n.backend.chained.read_duration_ms{backend,locale,namespace,outcome}` (histogram), `read_total{backend,outcome}` (counter — `outcome ∈ hit / miss / error / cache_hit / cache_miss / primary` extending the base outcome set with chained-cache classification: single-backend chains report `primary`, multi-backend chains report `cache_hit` (index 0 served) or `cache_miss` (a later backend served after fallthrough), errors report `error`, total miss reports `miss`), `read_errors_total{backend,code}` (counter), `write_duration_ms{backend,outcome}` (histogram), `write_total{backend,outcome}` (counter), `fallthrough_total{from_backend,to_backend}` (counter — incremented on every `BACKEND_LOCALE_NOT_AVAILABLE`-driven fallthrough between adjacent links so production teams can size cache layers correctly). Tested with the shared `runBackendConformance(...)` harness from `@suaveplan/i18n-shared/testing`. Universal — runs identically in browser and server; the tier of any concrete chain depends on the constituent backends. Zero runtime dependency on `@suaveplan/i18n` core; depends on `@suaveplan/i18n-shared`, `@suaveplan/i18n-backend-memory`, `@suaveplan/types`, `@suaveplan/error`, `@opentelemetry/api`, `tslib`, and `zod`. |
+| `@suaveplan/i18n-backend-fs-multifile` | **Server-tier** Node `fs/promises`-backed translation backend for the @suaveplan/i18n family. Ships `MultiFileFsBackend` (5-flag capability matrix: `canRead: true`, `canReadMulti: false`, `canSave: true`, `canTrackModification: true`, `canWatch` follows the `watch` option) and `multiFileFsBackend()` factory. Three wire layouts driven by the `layout` option: `nested` (default — `<root>/<locale>/<namespace>.<ext>`), `flat` (`<root>/<locale>.<namespace>.<ext>`), and `glob` (caller-supplied pattern with `{locale}` / `{namespace}` placeholders joined to `root`). JSON encode and decode are built in (`JSON.parse` / `JSON.stringify`); YAML/YML and JSON5 decode auto-detected via dynamic `import()` of the `yaml` / `json5` peers (never declared as direct deps); a missing peer surfaces as `BACKEND_READ_FAILED` with `peer` in the error context so callers can install the right package. Optional `fs.watch` loop on `root` emits `loaded` events through `BackendInitContext.emitLoaded(locale, namespace, { backend })` for both `nested` and `flat` layouts so HMR and React Suspense consumers can refresh without polling; `dispose()` aborts the watcher and is idempotent. Error mapping: ENOENT / ENOTDIR → `BACKEND_LOCALE_NOT_AVAILABLE` (chained-backend fallthrough signal); other errno codes (`EACCES`, `EBUSY`, …) → `BACKEND_READ_FAILED`; `writeFile` failure → `BACKEND_WRITE_FAILED` with `cause` preserved (existing `I18nError` instances pass through unchanged); unsupported encode extension → `BACKEND_WRITE_FAILED`. Optional `signal?: AbortSignal` on `read` and `save` throws `I18nError(I18N.BACKEND_TIMEOUT)` on pre-aborted signals before any filesystem call. The `MultiFileFsLike` shim is fully injectable; defaults to `node:fs/promises` via dynamic `import("node:fs/promises")` so the package never resolves the Node built-in at module-evaluation time in browsers. Zod boundary validation via `MultiFileFsBackendOptionsSchema` throws `INVALID_OPTIONS` on bad `layout`, empty `name`, or `glob` layout without `globPattern`. OTel surface: `i18n.backend.fs_multifile.read_duration_ms{backend,locale,namespace,outcome,layout}` histogram, `read_total{backend,outcome,layout}` counter, `read_errors_total{backend,code,layout}` counter, `write_duration_ms{backend,outcome,layout}` histogram, `write_total{backend,outcome,layout}` counter — `layout` is a 3-value low-cardinality enum so production teams can split SLOs per layout (glob patterns hide expensive resolutions). `package.json` declares `engines.node: ">=20"` and omits the `browser` field; `src/backend/backend.ts` opens with a `// Server-tier package — uses node:fs/promises. Browser consumers: use @suaveplan/i18n-backend-http or @suaveplan/i18n-backend-storage.` marker comment so universal-tier consumers cannot accidentally bundle this package; the slim `@suaveplan/i18n` core (Wave 6) does NOT re-export it. Tested with the shared `runBackendConformance(...)` harness from `@suaveplan/i18n-shared/testing` against a real `node:fs.mkdtemp` tmpdir (no `node:fs` mocks per CLAUDE.md "no mocks" rule) plus impl-specific cases over an injected `MultiFileFsLike` shim. Zero runtime dependency on `@suaveplan/i18n` core, on any other backend package, or on `yaml` / `json5`; depends only on `@suaveplan/i18n-shared`, `@suaveplan/types`, `@suaveplan/error`, `@opentelemetry/api`, `tslib`, and `zod`. |
+| `@suaveplan/i18n-detector` | Universal-tier locale-detection chain for the @suaveplan/i18n family. Ships the chain orchestrator (`createDetectorChain` with sync-first, async-raced execution, environment gating, AbortSignal threading, optional `throwOnExhausted` opt-in surfacing `I18nError(I18N.DETECTOR_CHAIN_EXHAUSTED)`), the BCP-47 default negotiator (`bcp47Negotiate`), the standalone `getTextDirection` / `isRtl` direction helpers (consuming `RTL_LOCALES` from `@suaveplan/i18n-shared`), nine detector implementations (`querystring`, `userPreference`, `cookie`, `localStorage`, `htmlLang`, `acceptLanguage`, `navigator`, `cloudflareIpGeo`, `fallback`) — each gated by an `environment: "browser" \| "server" \| "both"` discriminator so the same package runs in either tier — and the `defaultDetectorChain` factory returning the canonical 8/9-entry chain. The `userPreferenceDetector` accepts an injectable `LoggerLike` from `@suaveplan/types` (defaults to no-op) so the package keeps zero non-shared dependencies; the `cloudflareIpGeoDetector` consumes `getAllCountries()` from `@suaveplan/locale-data` to map ISO 3166-1 alpha-2 country codes to BCP-47 locales with an optional override map; the `fallbackDetector` throws `I18nError(I18N.INVALID_LOCALE)` on empty / whitespace input at chain-build time. OTel surface: `i18n.detect` span with `resolved_locale` and `winning_detector` attributes, `i18n.detector.match_total{detector}` aggregate counter, `i18n.detector.detected_total{detector,locale}` per-locale counter, `i18n.detector.duration_ms{detector}` histogram, `i18n.detector.chain.exhausted_total` counter. Every detector ships under its own `./detectors/<name>` subpath plus a tree-shakeable root barrel; `"sideEffects": false` on `package.json`. Consolidates the chain orchestrator (previously misplaced in the `@suaveplan/i18n` monolith) with the eight individual detector implementations (previously misplaced in the React-tier `@suaveplan/react-i18n` package) into a single universal-tier package depending only on `@suaveplan/i18n-shared`, `@suaveplan/locale-data`, and `@suaveplan/types`. |
+| `@suaveplan/idempotency` | Idempotency key guard and deduplication for async operations. The package provides a complete pending → completed \ |
+| `@suaveplan/jwt-tenant` | JWT-based multi-tenant token issuance and verification for the Suaveplan monorepo. Ships an Ed25519 / ECDSA-P256 signing pipeline, in-memory JWKS store with rotation and expiration, JWKS HTTP endpoint formatter, token issuer and verifier with injectable clock, and structured JWTTENANT error codes — all backed by jose, Zod-validated configs, and OpenTelemetry instrumentation. |
+| `@suaveplan/logger` | Enterprise-grade structured logger for the Suaveplan monorepo. Provides a full pipeline: level filtering → OTel trace enrichment → sampling → redaction → sinks. Supports multiple output strategies (console, JSON/NDJSON, event bus, storage) with buffering and backpressure. |
+| `@suaveplan/audio-core` | Universal audio data model and processing primitives. Provides a paged `AudioDocument`, a non-destructive `PlanEngine`, a block-level `ProcessPipeline`, and a typed `OpRegistry` — all with zero browser or Node.js dependencies. |
+| `@suaveplan/audio-metadata` | Universal audio metadata extractor that parses ID3v1/v2, MP4/M4A atoms, FLAC Vorbis comments, Ogg Vorbis, WAV RIFF, and AIFF/AIFC containers, returning a normalised Track record. Works in both Node.js and browser environments — zero native dependencies. |
+| `@suaveplan/migration` | Database-agnostic schema migration runner with ledger tracking, checksum validation, dry-run reporting, distributed locking, event bus integration, and OTel instrumentation. |
+| `@suaveplan/mime` | Structured MIME-type detection, parsing, and registry for the Suaveplan platform. Provides RFC 7231 Content-Type parsing, magic-byte file signature detection, charset sniffing, and a 150+ entry IANA-sourced type database — all in a zero-dependency, tree-shakeable package. |
+| `@suaveplan/network` | Core network interfaces and runtime for the genesis mesh system. |
+| `@suaveplan/network-transport-websockets` | Universal-tier WebSocket `Transport` + `NetworkPlugin` for `@suaveplan/network` mesh built on top of the pre-existing `WebSocketClient` (typed message framing, heartbeat/ping-pong, backpressure-aware queue, injectable `WebSocketAdapter`). `WebSocketTransport` composes per-peer `WebSocketClient` instances keyed by `peerId`: `connect(peerId, address, signal?)` with `PEER_ALREADY_CONNECTED` duplicate-key rejection, `disconnect(peerId)` no-op-on-unknown, `send(peerId, envelope)` raising `PEER_UNKNOWN` or `TRANSPORT_CLOSED`, fan-in `onMessage(handler)` returning disposer, `getConnectedPeers()` snapshot, idempotent `close()`, optional `maxPeers` enforcement raising `MAX_PEERS_EXCEEDED`. `WebSocketPlugin` mirrors `WebRTCPlugin`: `name="websockets"`, `install(node)` registers via `node.registerTransport(this.transport)`, `start()` lazy no-op, `stop()` closes + unregisters, `dispose()` idempotent. Extended `defineCodes("NET_WS", [...])` registry with 4 new transport-level codes on top of the existing client codes. OTel surface: `ws_transport.connect`/`disconnect`/`send` spans, `ws_transport.peers_connected{outcome}` + `ws_transport.messages_total{direction,outcome}` counters, observable `ws_transport.active_peers` gauge. `AbortSignal` threaded through the new connect path. New `./transport`, `./plugin`, `./otel` subpath exports; existing `./client`/`./queue`/`./heartbeat`/`./adapters`/`./types` preserved. fast-check property test on per-peer registry duplicate-key rejection invariant. Conformance tests run against a real `ws` `WebSocketServer` (no mocks); edge tests run against an injectable `WebSocketAdapter`. Every barrel uses explicit named exports per CLAUDE.md §6a; every test file imports runner primitives from `@suaveplan/testing/runner` per §7. 88 tests (60 baseline + 23 conformance + 5 edge), 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/retry`, `@suaveplan/serialize`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/oauth-client` | Universal OAuth 2.0 / OIDC client for Node.js, browsers, Bun, Deno, and edge runtimes. |
+| `@suaveplan/opentelemetry` | OpenTelemetry SDK setup and configuration helpers for the Suaveplan monorepo. Provides batteries-included OTel initialization helpers, resource detection, ergonomic span/metrics wrappers, W3C trace-context propagation utilities, and a no-op SDK façade that works without any heavyweight @opentelemetry/sdk- packages. |
+| `@suaveplan/packer` | Binary packing/unpacking utilities. Two modes: |
+| `@suaveplan/pagination` | Universal pagination primitives for cursor-based, offset-based, and keyset-based (seek) pagination strategies. The package covers the full pagination surface: request normalisation, response envelope construction, opaque cursor and page-token encoding, async iterators that drain pages automatically, a pluggable adapter interface for any data source, and optional OpenTelemetry instrumentation. All three strategies share the same error hierarchy and Zod schemas so they compose cleanly in multi-strategy APIs. |
+| `@suaveplan/password-formats` | Universal import/export layer for common password-manager export formats. Parses Apple Passwords CSV, Bitwarden JSON, Chrome CSV, and KeePass XML into a normalized PasswordEntry[] array, and exports back to a universal CSV format. |
+| `@suaveplan/permissions` | Full RBAC/ABAC permissions engine for the Suaveplan monorepo. Ships role management, policy evaluation, CASL-inspired ability builder, TTL permission cache, condition evaluation, and framework-agnostic middleware. |
+| `@suaveplan/qrcode` | QR code generation producing SVG, pixel matrix, terminal (Unicode blocks), and data URL representations. Implements QR code versions 1-10, error correction levels L/M/Q/H, automatic version and mode selection. |
+| `@suaveplan/queue` | Enterprise-grade queue management: memory/priority/delayed queues, concurrent workers with retry and dead-letter forwarding, job state machines, and OTel instrumentation. |
+| `@suaveplan/rate-limiter` | Enterprise rate limiter with three algorithms, rule-based routing, tenant multipliers, pluggable storage, and OTel instrumentation. |
+| `@suaveplan/react-i18n` | React bindings for `@suaveplan/i18n`. Ships the `<TranslationProvider>` (with caller-managed and Provider-managed instance modes), twelve hooks (`useI18n`, `useTranslation`, `useTranslate`, `useLocale`, `useDirection`, `useErrorMessage`, `usePlural`, `useDate`, `useNumber`, `useCurrency`, `useRelativeTime`, `useList`, `useLocaleDetection`), four headless components (`<Trans>` with rich-text tag interpolation via `MessageParser.formatChunks<ReactNode>`, `<LanguageSwitcher>` render-prop with `useTransition` wrapping, `<MissingKeyOverlay>` dev-mode overlay capped at 50 entries with `aria-live="polite"`, `<I18nSuspense>` convenience wrapper with default `aria-live` fallback), the `withTranslation` HOC for class components, the nine built-in locale detectors (`querystring`, `userPreference`, `cookie`, `localStorage`, `htmlLang`, `acceptLanguage`, `navigator`, `cloudflareIpGeo`, `fallback`) plus `defaultDetectorChain` and the `DetectorChainProvider` context wiring, the branded `TranslationKey` typing contract with `AppTranslationKeys` (consumer-app augmentation) and `ContributedTranslationKeys` (downstream-package augmentation), the `tDynamic` runtime escape hatch with the `REACT_I18N.UNKNOWN_KEY` code, the five-code `REACT_I18N_CODES` registry (`NO_PROVIDER`, `NAMESPACE_LOAD_FAILED`, `HYDRATION_MISMATCH`, `TRANS_INVALID_CHILD`, `UNKNOWN_KEY`), the React-tier OTel instruments (counters `react_i18n.missing_key.total` and `react_i18n.suspense.fallback.total`, histogram `react_i18n.render.duration_ms`, plus the detector telemetry `i18n.detector.match_total{detector}` / `i18n.detector.duration_ms{detector}` / span `i18n.detect`), and the warn-once / identity-translator soft-failure substrate. Leaf-most React package — the `check-no-backwards-deps.ts` CI gate enforces that no leaf React package (`react-ui*`, `react-forms*`, `react-ui-theme-*`, `react-ui-pack-*`) appears in any dep bucket so downstream `ContributedTranslationKeys` augmentation stays sound. Supersedes the legacy `@suaveplan/react-translate` (i18next-based) proposal. |
+| `@suaveplan/retry` | Retry strategies and circuit-breaker for async operations. The package provides constant, linear, and exponential backoff with four jitter modes (full, equal, decorrelated, none), a sleep helper with AbortSignal support, a per-attempt withTimeout wrapper, and a three-state circuit breaker (closed → open → half-open) with event emission and configurable failure/success thresholds. All entry points accept an injectable Clock and AbortSignal so they integrate cleanly with test harnesses and request cancellation. |
+| `@suaveplan/schema-registry` | Versioned schema registry with forward/backward/full compatibility checking for evolving data contracts. Register schemas by subject name, enforce evolution rules, and detect breaking changes before they reach production. |
+| `@suaveplan/search` | Full-text and fuzzy search primitives with in-memory BM25 engine, trigram fuzzy matching, faceted search, and pagination support. |
+| `@suaveplan/security-codes` | Detect and sanitise sensitive security-code leakage in strings. Handles API |
+| `@suaveplan/serialize` | Round-trip-preserving structured serialization for JavaScript's rich type system. The standard JSON.stringify/JSON.parse pair silently drops Date objects, Map, Set, BigInt, Uint8Array, URL, RegExp, undefined, NaN, and ±Infinity. This package preserves all of them via a tagged-JSON codec (serialize/deserialize) and an efficient MessagePack binary codec (encodeBinary/decodeBinary). It also provides 4-byte-framed streaming codecs for ReadableStream pipelines, cycle detection with path context, a pluggable type registry for custom classes, and an opt-in /unsafe subpath that handles Function-bearing payloads. The default entry point is eval-safe. Use @suaveplan/serialize whenever you need to serialise application state across process boundaries, persist structured data, or stream binary payloads — and want to get back exactly what you put in. |
+| `@suaveplan/sitemap` | Sitemap generation and parsing for the sitemaps.org XML protocol. Produces valid sitemap.xml, sitemap index documents, and parses existing sitemaps. Supports Google image and video extensions as well as hreflang alternate links. |
+| `@suaveplan/slsa` | SLSA L1-L2 supply-chain security for the Suaveplan monorepo. Generates and |
+| `@suaveplan/storage` | Enterprise key-value storage abstractions for the genesis monorepo. Provides AbstractStorage (implementing StorageLike), MemoryStorage with TTL and zero-copy streaming, NamespacedStorage with scoped operations, and StorageFactory with a module-augmentation provider registry. |
+| `@suaveplan/storage-cdn` | Types-only foundation for CDN-flavoured `@suaveplan/storage` adapters. Declares `CdnAdapter` (abstract base class extending `AbstractStorage` with `purge`, `signUrl`, `edgeUrl`), the `CdnCapabilities` boolean matrix, Zod-validated `SignUrlOptions`, the `STORAGE_CDN` error registry (8 codes), type-guard helpers (`isCdnAdapter`/`assertCdnAdapter`), default-not-supported helpers (`defaultPurgeNotSupported` / `defaultSignUrlNotSupported` / `defaultPrefixPurgeNotSupported`), and the module augmentation that adds an optional `cdn?: CdnCapabilities` slot to `@suaveplan/storage`'s capabilities map. Universal-tier; provider packages (`storage-cdn-rackspace`, `storage-cdn-bunnycdn`) implement against this contract. |
+| `@suaveplan/storage-cdn-bunnycdn` | BunnyCDN Storage Zone + Pull Zone provider for `@suaveplan/storage-cdn`. Full `AbstractStorage`/`CdnAdapter` surface against the regional Storage Zone (`de` unprefixed, `ny`/`la`/`sg`/`syd`/`uk` prefixed) with `AccessKey`-header authentication, HMAC-SHA256 Token Authentication signed URLs (URL-safe base64, no padding), single + wildcard prefix purge via `api.bunny.net/purge`, Range reads with 206/200/416 disambiguation, native `ReadableStream` from `Response.body`, AbortSignal everywhere, transient-status retry honouring `Retry-After`, full OTel surface with `provider="bunnycdn"` + `storage_region` attributes. Two-key model: per-zone `storageAccessKey` for CRUD vs. account-level `purgeApiKey` for invalidation; rotated independently. The only adapter in the family with `cdnPrefixPurge: true`. |
+| `@suaveplan/storage-cdn-rackspace` | Rackspace Cloud Files (OpenStack Swift) origin + Rackspace CDN provider for `@suaveplan/storage-cdn`. v2 identity auth with proactive token refresh (five minutes before `expires`), concurrent-call dedup, and service-catalog endpoint lookup for LON/IAD/DFW/ORD/SYD/HKG. HMAC-SHA1 Swift TempURL signing (with `temp-url-prefix` mode support), CDN cache purge per object via the management endpoint, Range reads, native streaming via `Response.body`, AbortSignal threaded through every public method, transient-status retry honouring `Retry-After`, full OTel surface with `provider="rackspace"` + `region` attributes. Universal tier — runs in Node 18+, Bun, Deno, browsers, Cloudflare Workers. |
+| `@suaveplan/storage-http` | Universal HTTP/CDN-backed `AbstractStorage` adapter. Maps every storage operation onto an HTTP request against a configured `baseUrl + key`: full read surface (`GET`/`HEAD`/`Range`/native `ReadableStream` streaming/ETag-cached conditional reads via `If-None-Match` → `304 Not Modified`), optional writes through an injectable `HttpUploader`, AbortSignal threaded into every fetch (pre-aborted short-circuits, mid-flight propagates), retry on transient outcomes (`408`/`425`/`429`/`5xx` + network rejection) honouring `Retry-After`, `STORAGE_HTTP` error registry with 10 codes, OTel surface (`storage_http.*` instruments with `status_class` attribute, `range_fallback_total` counter for misconfigured origins). The natural binding for static-site CDNs, prefix-readable S3 buckets, public BunnyCDN Pull Zones, GitHub Pages, Caddy file servers — provider-specific adapters (`storage-cdn-rackspace`, `storage-cdn-bunnycdn`) layer on top via the `HttpUploader` slot. Universal tier; runs unchanged in Node 18+, Bun, Deno, browsers, Cloudflare Workers. |
+| `@suaveplan/storage-s3` | S3-compatible object storage adapter for @suaveplan/storage. Extends AbstractStorage backed by @aws-sdk/client-s3 with presigned URL generation, multipart upload, retry integration, and OpenTelemetry instrumentation. |
+| `@suaveplan/storage-plugin-cache` | Read-through cache decorator for any `@suaveplan/storage` `AbstractStorage`. Returns `CachedStorage extends AbstractStorage` that wraps an inner storage with a caller-supplied `AbstractCache<Uint8Array>` in front — the structural inverse of `@suaveplan/cache-storage` (which exposes a storage *as* a cache). Read-through `get(key)` consults the cache first, falls through to the inner on miss, populates when `shouldCache(key, bytes)` returns true (default ceiling 16 MiB matching `drive-mesh-protocol`'s `MAX_FRAME_BYTES`). Invalidates on `set`/`setPartial`/`delete`/`clear` post-success. `clear()` evicts only the wrapper's namespaced subset via `cache.keys()` enumeration; logs a warning and skips when the cache backend lacks `keys()` (avoids obliterating other wrappers' entries). Passthrough on `exists` / `list` / `getMetadata` / `getWithMetadata` / `getSize` / `getItemSize` / `getPartial` / `createReadStream` / `createWriteStream`. 2-code `STORAGE_CACHE.*` registry (`INVALID_OPTIONS` / `INNER_MISSING`); class is `CachedStorageError` (distinct from `cache-storage`'s `StorageCacheError`). Cache failures never propagate — they're counter-recorded but the inner storage's bytes still reach the caller. Multi-namespace isolation on a shared cache (`namespace::key` keys). Full OTel surface (`storage_cache.{hits,misses,populations,invalidations,errors}_total{namespace}` + `entry_bytes` histogram + outcome-tagged spans). Universal tier, zero `node:`/`bun:` imports; composes uniformly with `drive`, `storage-uri` plugins, and any application code that accepts a `StorageLike`. |
+| `@suaveplan/storage-uri` | Universal URI-routed dispatcher over any `StorageLike` adapter. A single `StorageUriResolver` maps `scheme → UriPlugin` (`file://`, `https://`, `s3://`, `rackspace://`, `bunny://`, …) and exposes `open` / `read` / `write` / `stat` / `exists` / `remove` / `list` keyed by URI. Streaming reads forward `adapter.createReadStream` when present, fall back to a one-chunk wrap of `adapter.get` otherwise (counter-observed). Streaming writes drain via `Response(body).arrayBuffer()` for adapters without `createWriteStream`. AbortSignal propagation. 8-code `STORAGE_URI.*` error registry; `SuaveplanError` subclasses thrown by adapters pass through with their original code so downstream packages (`drive-uri`, `storage-http`, …) surface namespaced codes directly to consumers. Full OTel surface; `runUriPluginConformance(plugin, fixtures)` harness exported for sibling plugin packages. Universal tier — zero `node:`/`bun:` imports; runs unchanged in Node 18+, Bun, Deno, browsers, Cloudflare Workers. |
+| `@suaveplan/streams` | WHATWG-Streams-based primitives: backpressure-first transforms, zero-copy Uint8Array operations, AbortSignal integration end-to-end, structured errors, OTel instrumentation, and property-based invariant tests. |
+| `@suaveplan/suppression` | Email suppression list management for the Suaveplan monorepo. Stores and checks email addresses that should not receive outgoing mail — unsubscribes, hard/soft bounces, complaints, manual suppressions, and invalid addresses. Supports domain-level blocking, bulk CSV/JSON import and export, OTel instrumentation, and full serialisation round-trips. |
+| `@suaveplan/surrealdb` | Universal SurrealDB client wrapper for the genesis monorepo. Implements @suaveplan/db's DatabaseAdapter interface with connection lifecycle management, typed CRUD, schema discovery, database initialisation, version detection, structured SURREAL. error codes, and OTel instrumentation. |
+| `@suaveplan/templates` | A plugin-based string template engine for TypeScript. Resolves {variable} and {variable:transform} tokens in strings using a priority-sorted, regex-scan pipeline — no eval, no AST parser overhead. Designed for filling templates in notification messages, email subjects, file name patterns, code generation, and similar string-expansion tasks. Ships nine built-in plugins: dot-notation and array-index variable resolution; case, regex, and split transforms; counter, datetime, and UUID dynamic generators; and conditional/loop control flow. Three preset bundles (minimal, standard, full) let you trade features for bundle size. The injectable Clock and Rng make every rendering call deterministic in tests. Do not confuse with @suaveplan/i18n, which handles locale-keyed message catalogs and plural forms — use this package when your source strings are already in the target language and you only need token substitution. |
+| `@suaveplan/testing` | Shared test infrastructure for the Suaveplan monorepo. Provides runner primitives (Vitest or bun-test via conditional exports), structured builders, a deterministic FakeClock, Factory and FixtureManager, an in-memory store, async helpers, and a WSL2-aware createTestConfig() factory. Every other @suaveplan/ package imports from here when writing tests. |
+| `@suaveplan/testing-dom` | DOM and React component testing utilities for the Suaveplan monorepo. Provides a single install that covers vitest config generation with WSL2-safe defaults, @testing-library/react render helpers, accessibility-first query aliases, @testing-library/jest-dom matchers, user-event v14 setup, and a dual-runner shim that routes between vitest and bun:test via package.json conditional exports. |
+| `@suaveplan/testing-e2e` | Playwright E2E testing utilities for the Suaveplan monorepo. Provides a config factory with WSL2/CI-safe defaults, an abstract PageObject base class, extended test fixtures (apiContext, freshPage), browser-context helpers (clipboard mock, geolocation mock, network-idle wait, screenshot-on-failure), and structured error types. The package has no @suaveplan/ runtime dependencies — it is a Layer 0 utility that anything in the stack can depend on without introducing cycles. |
+| `@suaveplan/timing` | Timing and scheduling utilities for application-layer time management. The package covers measurement (stopwatch with lap recording), rate control (throttle and debounce with leading/trailing edge and maxWait), value decay (exponential and linear curves), delayed-task scheduling with drain/dispose lifecycle, repeating interval timers, countdowns with pause/resume, and vector clocks for distributed happens-before ordering. All stateful primitives accept an injectable Clock so they can be driven deterministically in tests using FakeClock from @suaveplan/testing. |
+| `@suaveplan/typescript-config` | Shared TypeScript configuration presets for the Suaveplan monorepo. This package ships composable JSON presets consumed via "extends" across every workspace package — no runtime code, no build step, zero dependencies. |
+| `@suaveplan/undo` | Enterprise-grade undo/redo engine with branching history, async commands, history compression, selective undo, and command merging. Built for collaborative editors, document tools, and any application requiring robust, reversible state management. |
+| `@suaveplan/utils` | Zero-external-dependency utility library for the Suaveplan monorepo. Covers debug helpers, deep object manipulation, platform detection, IEEE 754 float packing, pseudo-random selection, email normalization, audio sprite management, string generation, hex validation, and byte-size enforcement. |
+| `@suaveplan/validation` | Runtime schema validation with a Zod-compatible API. This package is a self-contained parse engine — it does not import Zod or any other validation library — so it is safe to use in environments where Zod is absent or where bundle size is a constraint. It covers the full schema surface expected from a production validator: all primitive and composite types, parse/safeParse/parseAsync, refine (sync + async), transform, describe, object shape builders (pick, omit, partial, extend, merge), three unknown-key modes, async lifecycle hooks, and composable helpers (pipe, mergeResults). Structured errors surface via @suaveplan/error with stable VALIDATION. codes. When Zod is already a project dependency and you need its ecosystem (inference helpers, plugins), use Zod directly; use this package for internal platform code and zero-dep environments. |
+| `@suaveplan/webhook-client` | Webhook delivery client with retry logic, HMAC signature generation/verification, payload transformation, and delivery tracking. Runtime-agnostic (injectable fetch). |
+
+## Pending
+
+**253** packages from suaveplan awaiting migration (per `STATUS.md` –, refreshed 2026-05-12).
+
+| Package | Summary |
+| --- | --- |
+| `@suaveplan/analytics-browser` | Client-side event tracking with batched transport |
+| `@suaveplan/animation-events` | Animation event dispatching, foot contact detection, procedural modifiers |
+| `@suaveplan/api` | Core API framework with plugin system |
+| `@suaveplan/api-docs` | API documentation generator |
+| `@suaveplan/api-gateway` | API gateway with routing, load balancing, circuit br... |
+| `@suaveplan/api-plugin-admin` | Admin panel plugin |
+| `@suaveplan/api-plugin-analytics` | Product analytics, funnel/cohort analysis |
+| `@suaveplan/api-plugin-anticheat` | Server-side anti-cheat with speed, damage, rate, and teleport validation |
+| `@suaveplan/api-plugin-asset-register` | Asset register — fixed assets, depreciation, mainten... |
+| `@suaveplan/api-plugin-audit` | Audit trail plugin |
+| `@suaveplan/api-plugin-auth` | Authentication plugin |
+| `@suaveplan/api-plugin-bank` | Game bank with virtual currency + interest |
+| `@suaveplan/api-plugin-banking` | Banking/payment plugin |
+| `@suaveplan/api-plugin-campaigns` | Campaign management API plugin |
+| `@suaveplan/api-plugin-cms` | Content management plugin |
+| `@suaveplan/api-plugin-contacts` | Contacts and groups API plugin |
+| `@suaveplan/api-plugin-customs` | Cross-border customs — declarations, HS codes, borde... |
+| `@suaveplan/api-plugin-database` | Database management plugin |
+| `@suaveplan/api-plugin-events` | Events management plugin |
+| `@suaveplan/api-plugin-export` | Data export (CSV, JSON, XLSX) |
+| `@suaveplan/api-plugin-file-upload` | Multipart/chunked file uploads with validation |
+| `@suaveplan/api-plugin-game-persistence` | Game save/load with slots, auto-save, and size limits |
+| `@suaveplan/api-plugin-game-server` | Game server session management with tick rate and heartbeats |
+| `@suaveplan/api-plugin-graphql` | GraphQL adapter with schema building |
+| `@suaveplan/api-plugin-gtap` | GTAP integration plugin |
+| `@suaveplan/api-plugin-import` | Data import plugin |
+| `@suaveplan/api-plugin-inventory` | Inventory management plugin — items, stock levels, m... |
+| `@suaveplan/api-plugin-logistics` | Enterprise logistics — shipments, carriers, pallets,... |
+| `@suaveplan/api-plugin-matchmaking` | Skill-based matchmaking with queue management and gap expansion |
+| `@suaveplan/api-plugin-messaging` | Messaging plugin |
+| `@suaveplan/api-plugin-notifications` | Notifications plugin |
+| `@suaveplan/api-plugin-payment` | Payment intent lifecycle, refunds, webhooks |
+| `@suaveplan/api-plugin-port-tracking` | Port tracking — vessel positions, port calls, shippi... |
+| `@suaveplan/api-plugin-procurement` | Procurement — purchase orders, goods receipt notes, ... |
+| `@suaveplan/api-plugin-rate-limit` | API-level rate limiting |
+| `@suaveplan/api-plugin-search` | Full-text search with relevance scoring |
+| `@suaveplan/api-plugin-site` | Site management plugin |
+| `@suaveplan/api-plugin-social` | Social features plugin |
+| `@suaveplan/api-plugin-sse` | Server-Sent Events for real-time push |
+| `@suaveplan/api-plugin-store` | E-commerce store plugin |
+| `@suaveplan/api-plugin-subscription` | Subscription/recurring billing plugin |
+| `@suaveplan/api-plugin-tenant` | Multi-tenant management plugin |
+| `@suaveplan/api-plugin-user` | User management plugin |
+| `@suaveplan/api-plugin-vatdash-bridge` | Bridge wiring all api-plugins into the vatdash Hono server |
+| `@suaveplan/api-plugin-vault` | Secrets vault plugin |
+| `@suaveplan/api-plugin-virtual-currency` | Virtual currency wallets, transfers, purchases, cashout |
+| `@suaveplan/api-plugin-warehouse-ops` | Warehouse operations — pick/pack/ship, cycle counts,... |
+| `@suaveplan/api-plugin-webhook` | Webhook delivery with retries and signing |
+| `@suaveplan/api-shared` | Shared API utilities and types |
+| `@suaveplan/audience-rules` | Dynamic audience segmentation using rule-based filte... |
+| `@suaveplan/audio-controllers` | MIDI hardware controller plugins for Kontrol S88, Ma... |
+| `@suaveplan/audio-engine-browser` | Browser-tier `TimelineAdapter` implementation: Web Audio rendering, AudioWorklet hosting, and `AudioFxPlugin` `createAudioNode()` integration for the universal `TimelineEngine`. |
+| `@suaveplan/audio-engine-server` | Server-tier `TimelineAdapter` implementation: file source/sink adapters and offline render driver for the universal `TimelineEngine`. |
+| `@suaveplan/audio-plugins-fx` | DSP audio effect plugins for the Web Audio API — EQ,... |
+| `@suaveplan/audio-sprite-packer` | Binary audio sprite map packer with 80%+ compression... |
+| `@suaveplan/audio-timeline` | Headless DAW timeline engine with multi-track arrangements, clips, playback, loop regions, selection, zoom, per-track mixer state, undo/redo, and a pluggable TimelineAdapter. |
+| `@suaveplan/audio-transport` | Universal musical clock and transport: sample-accurate scheduling with PPQ, BPM automation, swing, time signatures, and loop regions. Zero browser or Node dependencies. |
+| `@suaveplan/behavior-tree` | Behavior tree engine with composite nodes, decorators, blackboard, and fluent builder |
+| `@suaveplan/bone-mapping` | Skeleton detection, bone matching, retargeting math |
+| `@suaveplan/booking` | Universal-tier JSON-configurable booking engine: pluggable availability resolution, four built-in conflict detectors, pricing pipeline (base + tiers + modifiers + tax + seasonal + dynamic), rule evaluator with 11 operators, configurable status state machine, typed event bus over 15 lifecycle events, in-package `Hooks<TMap>` transform pipeline, six domain presets (seats / accommodation / appointments / resources / activities / transport), Zod schemas, and typed `BookingError` with 7-code registry. 29 subpath exports, 150 tests at 100/100/100/100. |
+| `@suaveplan/broadcast-channel` | Cross-tab BroadcastChannel communication |
+| `@suaveplan/building` | Player building system with snap placement, structural integrity, and blueprints |
+| `@suaveplan/caddy-imgproxy` | Image proxy integration |
+| `@suaveplan/campaigns` | Campaign orchestration combining audience, template,... |
+| `@suaveplan/character-physics` | Engine-agnostic character controller physics (floating capsule, plugins) |
+| `@suaveplan/character-vehicle-picker` | Character/vehicle picker schemas, catalogs, and state management with BitPacker |
+| `@suaveplan/chat` | In-game chat with channels, whispers, rate limiting, and profanity filter |
+| `@suaveplan/clipboard` | Clipboard API abstraction with fallbacks |
+| `@suaveplan/combat` | Core combat mechanics with damage types, health, armor, shields, and status effects |
+| `@suaveplan/contacts` | Contact and group management with hierarchical nesti... |
+| `@suaveplan/controller` | Controller abstractions |
+| `@suaveplan/crafting` | Recipe-based crafting with stations, material requirements, quality tiers, and queues |
+| `@suaveplan/currency` | Universal-tier currency conversion engine — `CurrencyConverter` orchestrator combining a pluggable `CurrencyProvider` chain (primary + ordered `fallbackProviders`), TTL-bounded `RateCache` with direct / inverse / single-hop triangulated lookup, virtual-currency seeding (registered through `@suaveplan/money` `registerCurrency`) with post-construction `setVirtualRate` / `updateVirtualRate` (aliases) + `getVirtualRates` defensive-copy inspector, `AbortSignal`-aware fallback chain that stops between attempts on abort, and Zod-validated public boundary on every options bundle (`ConverterConfigSchema`, `ConvertOptionsSchema`, `VirtualCurrencyConfigSchema`, `RateFetchOptionsSchema`) plus `parseConverterConfig` / `parseConvertOptions` / `parseVirtualCurrencyConfig` / `parseRateFetchOptions` helpers. Enriched `ConversionResult { amount, rate, inverseRate, from, to, rateAgeMs, providerName, triangulatedThrough }` — `providerName` is `"<identity>"` for `from === to`, `"<cache>"` for cache hits, `"<virtual>"` for virtual-currency rates, or the actual provider's `name`; `triangulatedThrough` is the intermediate base for triangulated rates (or `null` for direct / inverse / identity). Public methods: `convert(money, to, options?)`, `convertAmount(amount, from, to, options?)`, `getRate(from, to, options?)`, `setRate(from, to, rate)`, `clearCache()`, `getCache()`, plus the virtual mutators. `RateCache` exposes `set` / `get` / `has` / `getRate` / `getTriangulationPath` / `getTimestamp` / `prune` / `clear` / `size` and skips zero rates during inverse / triangulation to avoid `Infinity`. Reference providers: `InMemoryProvider` (mutable `setRates` / `setRate` + `fetchRates`) and `createStaticProvider(name, rateMap, options?)` (frozen). Typed `CurrencyError extends SuaveplanError<CurrencyErrorCode>` with 7-code registry (`INVALID_CONFIG`, `INVALID_OPTIONS`, `PROVIDER_UNAVAILABLE`, `UNSUPPORTED_CURRENCY`, `RATE_UNAVAILABLE`, `TRIANGULATION_IMPOSSIBLE`, `ABORTED`) and optional `from` / `to` / `providerName` discriminants — every code is reachable from a real call site. 6 subpath exports (`./converter/converter`, `./rate-cache/rate-cache`, `./provider/provider`, `./error-codes/error-codes`, `./schemas/schemas`, `./types/common`) for tree-shaking. 107 tests across 5 files at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage. Universal-tier — only `Date.now`, `Map`, `AbortSignal`; no `node:`/`bun:`/DOM/fs imports. Deps: `@suaveplan/error`, `@suaveplan/money`, `tslib`, `zod`. |
+| `@suaveplan/currency-provider-binance` | Universal-tier Binance sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `BinanceProvider implements CurrencyProvider` (`name = "binance"`, `supportsCrypto = true`, `supportsFiat = false`) plus the stable constants `BINANCE_PROVIDER_NAME` (`"binance"`) and `BINANCE_DEFAULT_BASE_URL` (`"https://api.binance.com/api/v3"`). Constructor accepts an optional `NoKeyConfig & { readonly timeoutMs?: number }` — `baseUrl` (override for staging / proxies / the regional `api{1,2,3,4}.binance.com` mirrors), `fetch` (`FetchLike` from `@suaveplan/types`, default `globalThis.fetch`), `timeoutMs` (flows through to the shared `httpRequest()` helper which derives an `AbortSignal.timeout(ms)` composed with the caller's `signal`). No API key required — uses Binance's public spot ticker endpoint. `fetchRates(options?)` issues `GET ${baseUrl}/ticker/price`, routes through the shared `httpRequest()` helper (typed `CurrencyProviderError(HTTP_ERROR)` on non-2xx with `status` populated), parses the JSON body (`CurrencyProviderError(PARSE_ERROR)` on malformed body; `cause` attached only when the parser threw an `Error`), structurally validates the payload shape as `Array<{ symbol: string; price: string }>` (`CurrencyProviderError(UPSTREAM_ERROR)` for non-array root, null row, wrong-typed row, or missing field), defaults `options.base` to `"USDT"`, decodes tickers whose symbol ends in the base suffix via `endsWith` + length guard (a symbol equal to the suffix decodes to an empty key — defensively skipped), inverts the price into the converter's "1 base = N units of asset" convention via `1 / price` (skipping zero / negative / non-finite prices), optionally filters by `options.targets` and raises `CurrencyProviderError(UNKNOWN_CURRENCY)` (with `upstreamMessage` set to the missing target) when a requested target is absent — surfacing upstream listing changes immediately rather than silently dropping them as the upstream form did. Improvements over the upstream `BinanceProvider` (`../suaveplan/packages/finance/currency-providers/src/crypto/binance.ts`): typed errors (upstream threw plain `Error`), structural payload validation (upstream cast on faith), `Number.isFinite` price guard (upstream only checked `price > 0`), `AbortSignal` propagation through `RateFetchOptions.signal`, per-call timeout via `timeoutMs`, injectable `FetchLike`, eager `UNKNOWN_CURRENCY` on missing targets. 1 subpath export (`./binance/binance`); explicit named barrels everywhere. 21 tests at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage covering identity, every happy-path branch, every sanitisation branch, every error code, abort + timeout forwarding, and the default-`globalThis.fetch` fallback. Universal-tier — only `Response`, `Number.parseFloat`, `Number.isFinite`, `Date.now`, `String.endsWith`/`.slice`, and the injected `FetchLike` (default `globalThis.fetch`); no `node:`/`bun:`/DOM/fs imports. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-coingecko` | Universal-tier CoinGecko sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `CoinGeckoProvider implements CurrencyProvider` (`name = "coingecko"`, `supportsCrypto = true`, `supportsFiat = true`) with optional `CoinGeckoConfig extends NoKeyConfig & { readonly apiKey?: string }` — `baseUrl` (default `https://api.coingecko.com/api/v3`, override for the Pro `https://pro-api.coingecko.com/api/v3` endpoint or for staging / proxies), `fetch` (`FetchLike` from `@suaveplan/types`, default `globalThis.fetch`), `apiKey` (Pro tier; attached as `x-cg-pro-api-key` header on every outbound request). Both tiers share the same `/simple/price` request shape so free → Pro is a one-field config change. `fetchRates(options?)` builds `GET ${baseUrl}/simple/price?ids=<curated-ids>&vs_currencies=<base.toLowerCase()>`, routes through the shared `httpRequest()` helper (caller `AbortSignal` propagation, per-call timeouts, typed `CurrencyProviderError(HTTP_ERROR)` on non-2xx), pre-validates `options.targets` against the curated `COIN_IDS` map (16 cryptos: BTC, ETH, SOL, USDT, USDC, BNB, XRP, ADA, DOGE, DOT, AVAX, MATIC, LINK, UNI, ATOM, LTC) — unknown targets reject with `CurrencyProviderError(UNKNOWN_CURRENCY)` before any network round trip, naming the offending symbol — parses the JSON body (`CurrencyProviderError(PARSE_ERROR)` on malformed bodies; `cause` attached when the parser threw an `Error`), shape-guards the parsed value as `Record<string, Record<string, number>>` (`CurrencyProviderError(UPSTREAM_ERROR)` on wrong shape), inverts upstream "1 crypto = X fiat" prices into the converter's "1 base = X crypto" convention (skipping symbols whose upstream price is missing, zero, negative, or non-numeric), and returns `{ base, rates, timestamp: Date.now() }`. Also exposes `COIN_IDS: Readonly<Record<string, string>>` (frozen) and `getCoinGeckoId(symbol): string \| undefined` (case-insensitive lookup; returns `undefined` for unknown symbols, never throws). 2 subpath exports (`./coingecko/coingecko`, `./coin-ids/coin-ids`); explicit named barrels everywhere. 23 tests across 2 files at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage covering both keyless and Pro-key branches, both error and happy paths, and the proactive `UNKNOWN_CURRENCY` gate (the recording `FetchLike` is asserted unused on the rejection branch). Universal-tier — only `URLSearchParams`-style URL building, `Response`, `Date.now`, `Map`, `Object.entries`, `Object.freeze`, and the injected `FetchLike` (default `globalThis.fetch`); no `node:`/`bun:`/DOM/fs imports. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-kraken` | Universal-tier Kraken sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `KrakenProvider implements CurrencyProvider` (`name = "kraken"`, `supportsCrypto = true`, `supportsFiat = false`) constructed from `KrakenProviderConfig extends NoKeyConfig` — optional `baseUrl` defaulting to `DEFAULT_KRAKEN_BASE_URL` (`https://api.kraken.com/0/public`), optional injectable `FetchLike` from `@suaveplan/types` (default `globalThis.fetch` captured at construction time), optional `extraSymbols: Readonly<Record<string, string>>` merged on top of the canonical 12-entry map at construction time so callers can extend coverage to newly-listed Kraken pairs without forking. Also exports `KRAKEN_SYMBOL_MAP` (frozen forward map: BTC, ETH, SOL, USDT, DOT, ADA, LINK, AVAX, ATOM, LTC, DOGE, XRP → Kraken pair name — covering both the legacy `X<base>Z<quote>` asset-prefix shape `XXBTZUSD` / `XETHZUSD` / `XDGUSD` / `XLTCZUSD` / `XXRPZUSD` and the flat `<base>USD` newer-listing shape `SOLUSD` / `USDTZUSD` / `DOTUSD` / `ADAUSD` / `LINKUSD` / `AVAXUSD` / `ATOMUSD`), `KRAKEN_PAIR_TO_SYMBOL` (frozen reverse map derived at module load — O(1) wire-to-symbol recovery in the hot path), and `mergeSymbolMap(extras?)` (hot-path fast-path: returns the canonical maps by reference when extras are absent or empty; otherwise allocates a fresh forward + reverse pair without mutating the canonical maps). `fetchRates(options?)` builds `GET <baseUrl>/Ticker?pair=<csv>` (Kraken's documented single-round-trip batch shape — the pair CSV is the value list of the merged forward map), routes through the slim core's shared `httpRequest()` helper (caller `RateFetchOptions.signal` forwarded into the helper for `AbortSignal` composition, non-2xx surfaces typed `CurrencyProviderError(HTTP_ERROR)` with `status` populated), parses the JSON body and shape-guards `{ error: string[], result: object }` (typed `PARSE_ERROR` on malformed JSON with the original parse error attached as `cause`, on JSON `null`, on a non-object body, on a non-array `error` field, on a missing or non-object `result` field, and on `result === null`), reads each ticker's `c[0]` last-trade-closed price and inverts it (`rates[symbol] = 1 / Number.parseFloat(c[0])`) into the converter's `1 USD = N crypto` convention, silently skips entries whose price is missing, non-string, fails to parse, is non-finite, or is non-positive (Kraken occasionally returns `"0.00"` for freshly-listed pairs — dropping these is intentional, not an error), skips Kraken pair names that don't appear in the merged reverse map, defaults `options.base` to `"USD"` (forwarded verbatim otherwise so callers can label the result as `"USDT"` / `"USDC"` etc. when wiring the provider behind a stablecoin re-base), filters the rate map by `options.targets` when supplied, raises `CurrencyProviderError(UPSTREAM_ERROR)` with `upstreamMessage` set to the first element of `data.error` when the array is non-empty (falls back to `"unknown upstream error"` when the first element is `null`), and raises `CurrencyProviderError(UNKNOWN_CURRENCY)` when `options.targets` is non-empty but no requested symbol resolves to a mapped Kraken pair — so callers see the failure rather than a silent empty rate map. Every raised error carries `providerName: "kraken"`. 2 subpath exports (`./symbols/symbols`, `./provider/provider`); explicit named barrels everywhere (root + each feature). 34 tests across 3 files at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage. Universal-tier — only `globalThis.fetch`, `JSON.parse`, `Number.parseFloat`, `Number.isFinite`, `Object.entries`, `Object.values`, `Object.freeze`, `Date.now`, `Map`; no `node:`/`bun:`/DOM/fs imports in production code. Deferred (carried forward from the slim-core archive): authenticated Kraken endpoints (private balance / order), WebSocket / streaming ticker, historical-rate / OHLC, retry / rate-limit / OTel wrappers — all will land as composable wrappers consuming this and every other sibling. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-cryptocompare` | Universal-tier CryptoCompare sibling for the slim `@suaveplan/currency-providers` core (2026-05-17). Exposes `CryptoCompareProvider implements CurrencyProvider` (`name = "cryptocompare"`, `supportsCrypto = true`, `supportsFiat = false`) plus `CryptoCompareConfig extends NoKeyConfig` with an **optional** `apiKey` field — the free public tier is fully keyless; supplying `apiKey` attaches `authorization: Apikey <key>` on every outbound request per CryptoCompare's documented Apikey auth scheme (whitespace-only strings treated as absent so `process.env.CRYPTOCOMPARE_API_KEY` can be passed in directly). `fetchRates(options?)` issues a single `GET <baseUrl>/pricemulti?fsyms=<targets>&tsyms=<base>` via the slim core's shared `httpRequest()` (caller `AbortSignal` forwarded, non-2xx → `CurrencyProviderError(HTTP_ERROR)` with `status` populated, raw `Response` returned for body handling), defaults `base` to `"USD"`, defaults `targets` to a built-in 15-symbol list (BTC, ETH, SOL, USDT, USDC, BNB, XRP, ADA, DOGE, DOT, AVAX, LINK, UNI, ATOM, LTC) when omitted or empty, inverts each upstream price (`1 / price`) into the converter's "1 base = X crypto" convention, and skips quotes that are not finite positive numbers. Error mapping: `HTTP_ERROR` (shared helper), `PARSE_ERROR` (invalid JSON or non-object payload), `UPSTREAM_ERROR` when the payload carries `Response: "Error"` (the `Message` field — or `"unknown upstream error"` when absent — is copied into `error.upstreamMessage`), `UNKNOWN_CURRENCY` when no requested symbol produces a positive quote. Every raised error carries `providerName: "cryptocompare"`. 1 subpath export (`./cryptocompare/cryptocompare`); explicit named barrels everywhere. 15 tests at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage, covering both keyless and keyed branches, custom baseUrl, empty-targets fallback, all four error codes, non-Error `cause` handling, and `AbortSignal` forwarding. Universal-tier — only `globalThis.fetch`, URL composition, `Object.entries`, `Number.isFinite`, `Date.now`, `Response`; no `node:`/`bun:`/DOM/fs imports. Deferred: historical-rate endpoints (`/v2/histo*`), OHLCV, WebSocket streaming, multi-tsym aggregation, fiat rates (`supportsFiat: false` by design — install one of the fiat siblings), CryptoCompare-specific metadata endpoints. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-coinmarketcap` | Universal-tier CoinMarketCap sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `CoinMarketCapProvider implements CurrencyProvider` (`name = "coinmarketcap"`, `supportsCrypto = true`, `supportsFiat = false`) constructed from `ApiKeyConfig` (`apiKey` required — empty / whitespace raises `CurrencyProviderError(MISSING_CONFIG)` synchronously from the constructor with `providerName: "coinmarketcap"`; optional `baseUrl` defaulting to `https://pro-api.coinmarketcap.com/v1`; optional injectable `FetchLike` from `@suaveplan/types`, default `globalThis.fetch` resolved at call time so test setups that replace the global after construction still work). `fetchRates(options?)` builds `GET <baseUrl>/cryptocurrency/quotes/latest?symbol=<csv>&convert=<base>`, attaches the upstream-required `X-CMC_PRO_API_KEY` header carrying `config.apiKey` plus `Accept: application/json`, routes through the slim core's shared `httpRequest()` (caller `RateFetchOptions.signal` forwarded, non-2xx → `CurrencyProviderError(HTTP_ERROR)` with `status` populated, raw `Response` returned), defaults `base` to `"USD"` and `targets` to the built-in top-10 crypto-by-market-cap (`BTC, ETH, SOL, USDT, USDC, BNB, XRP, ADA, DOGE, DOT`) when omitted or empty, parses the JSON body (typed `PARSE_ERROR` on invalid JSON, non-object body, or missing / non-object `data` field with no usable upstream signal), inspects the upstream `status.error_code` (typed `UPSTREAM_ERROR` when non-zero numeric; `upstreamMessage` copied from `status.error_message` when present; `error_code === 0` treated as success so normal responses are not flagged), inverts each upstream "1 crypto = X fiat" price into the converter's "1 fiat = X crypto" convention (silently dropping symbols whose price is missing, non-numeric, NaN, zero, negative, or quoted against a different base than requested), raises typed `UNKNOWN_CURRENCY` when no requested symbol resolved to a positive quote, and returns `{ base, rates, timestamp: Date.now() }`. Every raised error carries `providerName: "coinmarketcap"`. 2 subpath exports (`./coinmarketcap/coinmarketcap`); explicit named barrels everywhere. 22 tests at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage, covering identity, both constructor-validation branches, the canonical URL + header shape, the top-10 default symbol set (both omitted-options and empty-`targets`-array branches), `AbortSignal` forwarding, custom `baseUrl`, the `globalThis.fetch` fallback, every error path (`HTTP_ERROR` via `httpRequest`; `PARSE_ERROR` for invalid JSON, JSON `null`, missing data, non-object data; `UPSTREAM_ERROR` for populated `error_code` with and without `error_message`, and the missing-data + `error_code` race; `UNKNOWN_CURRENCY` for empty resolution), the `error_code === 0` success branch, and the price-filter rules (skip non-numeric, NaN, zero, negative, wrong-base, missing-quote, undefined-entry, partial-quote-shape). Universal-tier — only `globalThis.fetch`, `Object.entries`, `Number.isFinite`, `Date.now`, `String`, and the injected `FetchLike`; no `node:`/`bun:`/DOM/fs imports in production code. Deferred (carried forward from the slim-core archive): CoinMarketCap fiat conversion endpoints (`/v1/fiat/map`, `/v2/tools/price-conversion`) — out of scope for this crypto-rates sibling; install one of the fiat siblings (`currency-provider-ecb`, `currency-provider-fixer`, `currency-provider-open-exchange-rates`) for fiat coverage. Historical-rate / OHLCV / WebSocket / CoinMarketCap-metadata endpoints will land if real consumer demand justifies them. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-virtual` | Universal-tier in-memory programmable virtual / game currency sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `VirtualCurrencyProvider implements CurrencyProvider` (`name = "virtual-currency"`, `supportsCrypto = false`, `supportsFiat = false`, `supportsVirtual = true`) constructed from an optional `VirtualCurrencyProviderConfig` (`defaultBase` default `"USD"`; `initialRates: readonly VirtualRateEntry[]` upserted at construction via the same `setRate` codepath so duplicates within the array are last-write-wins; `clock: Clock` from `@suaveplan/types`, default `() => Date.now()`). Programmable runtime API: `setRate(from, to, rate): void` (upsert — calling twice for the same pair replaces without throwing), `removeRate(from, to): boolean` (idempotent — `true` on first removal, `false` thereafter, auto-cleans empty inner maps so `listCurrencies()` stays accurate, never throws), `clear(): void`, `hasRate(from, to): boolean`, `getRate(from, to): number \| undefined`, `listCurrencies(): readonly string[]` (lexicographic snapshot so equal sets list identically regardless of insertion order). `fetchRates(options?)` consults the nested `Map<from, Map<to, number>>` rate table for `options.base` (default `defaultBase`), optionally filters by `options.targets` (inclusion list — missing targets simply absent from the result, no throw), returns `{ base, rates, timestamp: clock() }`. The promise wrapping satisfies the `CurrencyProvider` async contract without observable microtask delay; no I/O occurs. Throws `CurrencyProviderError(CURRENCY_PROVIDER.UNKNOWN_CURRENCY)` with `providerName: "virtual-currency"` when the requested `base` has no rates stored — the registry can legitimately be empty and there is no triangulation. Triangulation is deliberately absent: `CurrencyConverter` from `@suaveplan/currency` triangulates from its rate cache once a `RateFetchResult` is in hand; duplicating that here would split the algorithm. Also exports `makeUnknownCurrencyError(base): CurrencyProviderError` (canonical error constructor with pre-populated `providerName` discriminant), `VIRTUAL_PROVIDER_NAME: "virtual-currency"`, and `VIRTUAL_CURRENCY_PROVIDER_CODES: { UNKNOWN_CURRENCY }` re-export. Constructor is side-effect-free (unlike upstream `VirtualCurrencyProvider` which called `@suaveplan/money` `registerCurrency` from its constructor — a hidden side effect that broke tree-shaking; callers wanting money-registry integration call `registerCurrency` themselves). 2 subpath exports (`./error-codes/error-codes`, `./provider/provider`); explicit named barrels everywhere. 25 tests across 3 files at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage covering identity, programmable rate-table API (upsert, idempotent remove + cleanup, clear, has / get / list), `fetchRates` (default base fallback, custom base, targets filter, empty-targets-overlap), every `UNKNOWN_CURRENCY` path (missing requested base, empty default base), `FakeClock`-driven deterministic timestamps and `Date.now()` fallback, and a structural assertion that production source contains zero `FetchLike` / `globalThis.fetch` / `fetch(` references. Universal-tier — only `Map`, `Set`, `Date.now`, `Promise.resolve`/`Promise.reject`, and the injected `Clock` contract; no `node:`/`bun:`/DOM/fs imports in production code. Deferred: triangulation (use `CurrencyConverter`), persistence (in-memory by design), `@suaveplan/money` `registerCurrency` integration (call it yourself before construction). Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-ecb` | Universal-tier European Central Bank sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `EcbProvider implements CurrencyProvider` (`name = "ecb"`, `supportsFiat = true`, `supportsCrypto = false`) with optional `NoKeyConfig` — `baseUrl` (default `https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml`, override for proxies / staging / fixtures), `fetch` (`FetchLike` from `@suaveplan/types`, default `globalThis.fetch` resolved at call time so test setups that replace the global after construction still work). `fetchRates(options?)` calls `GET <baseUrl>` through the shared `httpRequest()` helper from the slim core (caller `AbortSignal` propagation via `RateFetchOptions.signal`, typed `CurrencyProviderError(HTTP_ERROR)` on non-2xx with `status` populated), reads the XML body, parses the EUR-quoted currency table via the zero-dep regex `/currency='([A-Z]+)'\s+rate='([\d.]+)'/g` (raising `CurrencyProviderError(PARSE_ERROR)` if the body contains zero matches so an empty rate map is never silently cached), then either returns the raw `{ base: "EUR", rates, timestamp: Date.now() }` view or — when the caller requests a non-EUR `base` — synthesises the requested base view by inverting through the EUR feed (`result.EUR = 1 / baseRate`, `result.<other> = <eurRate> / baseRate`; the requested base is absent from the returned map because a currency does not quote itself; raises `CurrencyProviderError(UNSUPPORTED_BASE)` when the requested non-EUR base is missing from the feed). `RateFetchOptions.targets` filtering raises `CurrencyProviderError(UNKNOWN_CURRENCY)` when every requested target is absent from the resolved map (silent-drop for partial overlap; empty `targets` array means no filter). 1 subpath export (`./ecb/ecb`); explicit named barrels everywhere (root + feature). 16 tests across 2 files at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage covering every branch — EUR base / non-EUR base / target filter / each error path / custom baseUrl / injected fetch (and global fallback) / `AbortSignal` forward / empty-targets short-circuit / partial-targets overlap. Universal-tier — only `globalThis.fetch`, `Response`, `Number.parseFloat`, `Date.now`, `Object.entries`, and `RegExp`; no `node:`/`bun:`/DOM/fs imports in production code. Deferred (carried forward from the slim-core archive): retry / rate-limit / OTel / historical-rate / WebSocket / aggregator surfaces will land as composable wrappers consuming this and every other sibling. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-fixer` | Universal-tier [Fixer.io](https://fixer.io/) sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `FixerProvider implements CurrencyProvider` (`name = "fixer"`, `supportsFiat = true`, `supportsCrypto = false`) constructed from the slim core's shared `ApiKeyConfig` (`apiKey` required; optional `baseUrl` default `https://data.fixer.io/api`; optional injectable `fetch` `FetchLike` from `@suaveplan/types`, default `globalThis.fetch`). Constructor validates `config.apiKey` is non-empty and raises `CurrencyProviderError(MISSING_CONFIG)` synchronously when it is the empty string — so a missing `process.env.FIXER_KEY` fails before any request burns against the monthly quota. `fetchRates(options?)` builds `GET <baseUrl>/latest?access_key=<key>&base=<base>[&symbols=<csv>]` (default `base = "EUR"`, `targets` comma-joined into `symbols` when the array is non-empty; an empty array is treated as no filter), routes through the slim core's shared `httpRequest()` helper (`AbortSignal` composition via `RateFetchOptions.signal`, non-2xx → `CurrencyProviderError(HTTP_ERROR)` with `providerName`+`status`), then awaits `response.json()` inside a `try` / `catch` (parse failure → `CurrencyProviderError(PARSE_ERROR)` with the underlying `cause` attached). Non-object / `null` / array bodies also raise `PARSE_ERROR`. Discriminates the upstream envelope on `success`: `{ success: true, base, rates, timestamp }` returns `{ base, rates, timestamp: data.timestamp * 1000 }` (Unix seconds → milliseconds); a `success: true` envelope missing any of `base` / `rates` / `timestamp` raises `PARSE_ERROR` (defensive — Fixer's documented success shape always includes them). `{ success: false }` envelopes map to typed codes via the integer `error.code` discriminator: `105` (`base_currency_access_restricted`, the free-tier base lock) → `UNSUPPORTED_BASE`; `201` (`invalid_base_currency`) and `202` (`invalid_currency_codes`) → `UNKNOWN_CURRENCY`; any other code (or missing `error` field entirely) → `UPSTREAM_ERROR`. Every typed error carries `providerName: "fixer"`; the upstream `error.info` (or `"<unknown>"` when absent) is preserved on `upstreamMessage` so the upstream narrative survives the typed mapping. Improvements over the upstream `FixerProvider` (`../suaveplan/packages/finance/currency-providers/src/fiat/fixer.ts`): construction-time `apiKey` guard (upstream silently accepted `""` and let the API reject on the wire), typed `CurrencyProviderError` everywhere (upstream threw bare `Error`), `AbortSignal` propagation through `RateFetchOptions.signal` (upstream did not forward), injectable `FetchLike` seam, typed code discrimination on `error.code` (upstream only checked the `success` flag). 1 subpath export (`./fixer/fixer`); explicit named barrels everywhere (root + feature). 22 tests at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage covering identity flags, construction guard, default + custom baseUrl, default + custom base, targets join, empty targets short-circuit, injected fetch + global fallback, success-envelope projection (incl. ms timestamp), every typed error mapping (105 / 201 / 202 / 999 / missing `error`), every parse-failure branch, `HTTP_ERROR` via the slim core, caller-signal forwarding, no-side-effect import, and universal-tier purity (no `node:`/`bun:`/DOM imports in `src/`). Deferred (carried forward from the 2026-05-17 archive): historical-rate endpoints (`/{date}` and `/timeseries`), fluctuation, conversion (`/convert`), and rate-limit / retry / aggregator wrappers. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-provider-open-exchange-rates` | Universal-tier Open Exchange Rates sibling for the `@suaveplan/currency-providers` slim core (2026-05-17). Public surface: `OpenExchangeRatesProvider implements CurrencyProvider` (`name = "open-exchange-rates"`, `supportsFiat = true`, `supportsCrypto = false`) and `OpenExchangeRatesProviderConfig extends ApiKeyConfig & { readonly allowNonUsdBase?: boolean }`. `apiKey` (OXR `app_id`) is required — the constructor raises `CurrencyProviderError(MISSING_CONFIG)` synchronously when it is the empty string. `baseUrl` defaults to `https://openexchangerates.org/api`; `fetch` defaults to `globalThis.fetch`; `allowNonUsdBase` defaults to `false`. `fetchRates(options?)` issues `GET ${baseUrl}/latest.json?app_id=<key>&base=<base>` (both `apiKey` and `base` are `encodeURIComponent`-wrapped to prevent injection) via the shared `httpRequest()` helper from the slim core (caller `AbortSignal` forwarded; non-2xx → `CurrencyProviderError(HTTP_ERROR)` with `status` and `providerName` populated). Free-tier safe by default: when `options.base !== "USD"` and `allowNonUsdBase !== true`, `fetchRates` raises `CurrencyProviderError(UNSUPPORTED_BASE)` before any network round trip. After the response, the body is parsed and validated for the OXR success shape `{ base: string, rates: object, timestamp: number }`; any deviation (non-object body, non-string `base`, non-number `timestamp`, `rates` being an array or null, invalid JSON — `cause` is normalised to an `Error` so non-`Error` rejections are still surfaced) raises `CurrencyProviderError(PARSE_ERROR)`. The OXR error-payload shape (`{ error: true, status, message, description? }`, returned with a 2xx HTTP status) is detected after parsing and raises `CurrencyProviderError(UPSTREAM_ERROR)` with `upstreamMessage` and `status` populated; an error payload missing `status` or `message` falls back to `PARSE_ERROR`. `RateFetchOptions.targets` is honoured by filtering the rates map; any code absent from the upstream payload raises `CurrencyProviderError(UNKNOWN_CURRENCY)` naming the offending symbol. Returns `{ base, rates, timestamp: payload.timestamp * 1000 }` (Unix seconds → ms). 1 subpath export (`./provider/provider`); explicit named barrels everywhere. 22 provider tests + 4 dep-graph tests at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage, covering every error path including the non-`Error` `cause` branch via a synthetic `Response`-like that rejects with a string. Universal-tier — only `globalThis.fetch` (or injected `FetchLike`), `Response`, `encodeURIComponent`, `Object.entries`; no `node:`/`bun:`/DOM/fs imports. Deferred (carried forward from the slim-core `## Out of scope`): historical-rate endpoint (`/historical/<date>.json`), `/currencies.json`, `/usage.json`, `/convert/{value}/{from}/{to}`, `/ohlc.json`, `/time-series.json`, retry / backoff / rate-limit-header surfacing, OTel spans. Deps: `@suaveplan/currency`, `@suaveplan/currency-providers`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/currency-providers` | Universal-tier **slim plugin core** for `@suaveplan/currency` rate providers (slimmed 2026-05-17 from the original 9-provider bundle to a foundation-with-sibling-plugins shape matching `@suaveplan/network` and `@suaveplan/drive`; the concrete `EcbProvider` / `FixerProvider` / `OpenExchangeRatesProvider` / `BinanceProvider` / `CoinGeckoProvider` + `getCoinGeckoId` / `CoinMarketCapProvider` / `CryptoCompareProvider` / `KrakenProvider` / `VirtualCurrencyProvider` classes now ship as `@suaveplan/currency-provider-<name>` sibling packages in the follow-up wave). Public surface: `CurrencyProviderRegistry` (name-keyed `register(provider)` / `get(name)` / `has(name)` / `list(): readonly string[]` (sorted snapshot for deterministic downstream tests) / `unregister(name): boolean` (idempotent, never throws); duplicates raise `PROVIDER_ALREADY_REGISTERED`, unknown lookups raise `PROVIDER_NOT_REGISTERED`, both carry `providerName` on the typed `CurrencyProviderError`). `defineCurrencyProvider(input): CurrencyProvider` — factory that returns an `Object.freeze`-d `CurrencyProvider` from a plain `DefineCurrencyProviderInput` (`name`, `supportsCrypto`, `supportsFiat`, optional `supportsVirtual`, `fetchRates`); preserves the optional `supportsVirtual` property only when explicitly provided. Shared HTTP helpers used by every sibling: `httpRequest(input): Promise<Response>` (accepts `url`, `fetch`, `providerName`, optional `init` / `signal` / `timeoutMs`; derives `AbortSignal.timeout` when set, composes with caller's `signal`, raises `CurrencyProviderError(HTTP_ERROR)` with populated `status` on non-2xx, returns raw `Response` so callers handle `.json()` / `.text()` / `.arrayBuffer()`) and `composeAbortSignal(caller, timeout): AbortSignal \| undefined` (pure four-way composition — `undefined` / `caller` / `timeout` / `AbortSignal.any([caller, timeout])`). Configs: `ApiKeyConfig` (`apiKey`, `baseUrl?`, `fetch?`), `NoKeyConfig` (`baseUrl?`, `fetch?`), `HttpFetchOptions` (`timeoutMs?`, `headers?`), `ProviderConfigBase` (`baseUrl?`, `fetch?`). Typed `CurrencyProviderError extends SuaveplanError<CurrencyProviderErrorCode>` with the 8-code `CURRENCY_PROVIDER_*` registry (`HTTP_ERROR`, `PARSE_ERROR`, `UPSTREAM_ERROR`, `UNSUPPORTED_BASE`, `MISSING_CONFIG`, `UNKNOWN_CURRENCY`, `PROVIDER_NOT_REGISTERED`, `PROVIDER_ALREADY_REGISTERED`) + optional `providerName` / `status` / `upstreamMessage` discriminants — the first six codes are reachable from sibling provider packages, the two registry codes are reachable from this package, and `HTTP_ERROR` is additionally reachable from the shared `httpRequest` helper. 5 subpath exports (`./error-codes/error-codes`, `./types/configs`, `./registry/registry`, `./factory/factory`, `./http/http`); explicit named barrels everywhere. 32 tests across 5 files at 100/100/100/100 (statements / branches / functions / lines) istanbul coverage. Universal-tier — only `globalThis.fetch`, `AbortSignal.timeout`, `AbortSignal.any`, `Object.freeze`, `Map`, `Response`; no `node:`/`bun:`/DOM/fs imports in production code. Deferred (carried forward from the 2026-05-17 archive): rate-limit-aware wrapper (`@suaveplan/rate-limiter` pending), retry + backoff wrapper (`@suaveplan/retry` integration), historical-rate endpoints (interface extension), WebSocket streaming (Binance / Kraken), on-chain oracle adapter (`@suaveplan/cryptocurrency` pending), `AggregatorProvider`, health monitor, OTel spans, stablecoin redirect routing. Deps: `@suaveplan/currency`, `@suaveplan/error`, `@suaveplan/types`, `tslib`. |
+| `@suaveplan/day-night` | Day/night cycle with configurable time, light schedules, and gameplay modifiers |
+| `@suaveplan/delivery-tracking` | Channel-agnostic delivery event tracking |
+| `@suaveplan/destructibles` | Destructible environment system with fracture patterns, debris, and loot |
+| `@suaveplan/dialogue` | Branching dialogue trees with conditional choices, bark system, and conversation management |
+| `@suaveplan/discord-client` | Generic Discord API client for webhooks, bot messaging, and embeds |
+| `@suaveplan/dmx` | DMX512 lighting control engine |
+| `@suaveplan/docs` | Documentation site |
+| `@suaveplan/drive-sharing` | Partitioned drive with envelope encryption for the Suaveplan ecosystem. AEAD envelope (`envelopeEncrypt`/`envelopeDecrypt`) with mandatory `partitionId\|\|fileId` AAD, default AES-256-GCM (configurable to XChaCha20-Poly1305). `KeyRing` with `add`/`get`/`remove`/`rotateKey`/versioned `export`+`import`, algorithm-tag + checksum validation, constant-time comparisons, and zeroize-on-drop. `PartitionPolicy` with deterministic `validateAction` state machine, commutative `mergePolicies`, and four `DEFAULT_PRESETS` (public/private/shared/encrypted). `PartitionStore` interface + `InMemoryPartitionStore`; `PartitionManager` with read-only fallback on store failure. `GrantManager` with injectable Clock-driven expiry, `grant:created`/`grant:revoked` events. `TokenManager` with HMAC-SHA-256 integrity MAC, configurable TTL, `revoke` finality. `TransferManager` with two-phase export→validate→import + rollback, AbortSignal cancellation, atomic DEK rewrap. Eleven structured `DriveShareError` codes; safe-by-construction OTel spans + counters + histograms; fast-check property tests for grant expiry, token revocation finality, policy merge commutativity; mitata `grant_check_10k` regression gate (<50 ms). Inlines policy validation rather than depending on `@suaveplan/permissions` to keep the partition-action policy domain-specific. |
+| `@suaveplan/drive-plugin-cache` | Read-through cache middleware for `@suaveplan/drive`. Returns `driveCachePlugin(options): DrivePlugin<DriveCacheHandle>` that registers a `DriveMiddleware` intercepting `Drive.read(path)` against a caller-supplied `AbstractCache<Uint8Array>` — memory (built-in `MemoryCache`), OPFS / file (`StorageCache` over any browser/server `AbstractStorage`), Redis (`RedisCache`), or any other `cache-storage`-backed backend the consumer picks via `createCache(...)`. Read-through populates on miss when `shouldCache(path, bytes)` returns true (default 16 MiB ceiling matching `drive-mesh-protocol`'s `MAX_FRAME_BYTES`). Write/delete invalidate post-success (avoiding the race window of optimistic invalidation); `stat` and `list` passthrough (list invalidation across prefix mutations is a separate design problem, deferred). 3-code `DRIVE_CACHE.*` registry (`INVALID_OPTIONS` / `CACHE_TOO_LARGE` / `INSTALL_FAILED`) — the wrapper's surface is intentionally narrow; cache and drive errors carry their own namespaced codes through unchanged. Cache failures never propagate to the consumer (perf optimisation, not correctness boundary); they're counter-recorded via `drive_cache.errors_total{namespace, op}`. AbortSignal pre-abort short-circuits cache work and forwards live signals into cache operations when accepted. Multi-namespace isolation on a shared cache so several drives can share one `AbstractCache` instance without cross-talk. Full OTel surface (`drive_cache.{hits,misses,populations,invalidations,errors}_total{namespace}` + `entry_bytes` histogram + outcome-tagged spans). `DriveCacheHandle` exposes `getStats()` / `invalidate(path)` / `clear()` / `cache` (the underlying `AbstractCache` reference so consumers can compose `wrap()`-style stale-while-revalidate on top). Universal tier; integration tests use a real `Drive` + real `MemoryCache` + real `StorageCache` over `storage-file` per CLAUDE.md rule 2 (no mocks). |
+| `@suaveplan/drive-uri` | Drive/+mesh/+template URI plugins for the `StorageUriResolver` in `@suaveplan/storage-uri`. Three factories — `driveUriPlugin`, `driveMeshUriPlugin`, `driveTemplateUriPlugin` — each wrap a caller-provided `Drive` instance in a `StorageLike` shim and plug into the existing storage-uri resolver alongside file/https/s3/cdn plugins. `drive+template://` plugin fetches the template via an injected `templateProvider`, hydrates the drive via `Drive.hydrateFrom`, and caches the `(templateId → in-flight hydration)` map so concurrent reads share one round-trip. `DriveStorageLikeAdapter` translates Drive's throw-on-missing into `StorageLike`'s undefined-on-missing and forwards `createReadStream` for native streaming through the resolver's fast path. 7-code `DRIVE_URI.*` error registry (`INVALID_URI` / `DRIVE_ID_MISMATCH` / `TEMPLATE_NOT_AVAILABLE` / `TEMPLATE_INVALID` / `WRITE_UNSUPPORTED` / `CAPABILITY_MISSING` / `ABORTED`). No new resolver class, no umbrella composition helper, no duplication of chunk-codec / peer-discovery / template-validation logic — those live in `drive`, `drive-mesh`, `drive-template`, `drive-plugin-chunks` and are exercised via the supplied `Drive` reference. Universal tier; integration tests use real `Drive` + `chunksPlugin` + `storage-file` per CLAUDE.md rule 2 (no mocks). |
+| `@suaveplan/drive-webrtc` | WebRTC P2P mesh plugin for drive |
+| `@suaveplan/economy` | In-game economy with wallets, trading, marketplace, and auction system |
+| `@suaveplan/ecs` | Archetype-based Entity Component System with bitset queries |
+| `@suaveplan/electrobun` | Electrobun desktop app generator |
+| `@suaveplan/email-processing` | Email parsing and MIME processing |
+| `@suaveplan/email-templates` | Email template components |
+| `@suaveplan/emailer` | Email sending with plugins |
+| `@suaveplan/emblem-solver` | Minimal-rectangle SVG converter for pixelated sprite... |
+| `@suaveplan/emotes` | Emote/expression system with registry, cooldowns, and level-gated unlocks |
+| `@suaveplan/fauna` | Wildlife AI with herding, predator-prey, territorial zones, and taming |
+| `@suaveplan/font-decompress` | Font decompression utilities |
+| `@suaveplan/form-builder` | Dynamic form schema builder with validation, conditi... |
+| `@suaveplan/fruit-machine` | Nested state-machine engine for fruit-machine / AWP games (Adders & Ladders reference) |
+| `@suaveplan/game-loop` | Fixed-timestep game loop with tick scheduling |
+| `@suaveplan/game-persistence` | Save/load game state with versioned migrations |
+| `@suaveplan/game-server` | Universal game server framework with sessions, networking, matchmaking, and game queue |
+| `@suaveplan/game-state-schemas` | Bit-level quantization schemas for multiplayer state compression |
+| `@suaveplan/geo` | Abstract geospatial geometry library: ellipsoids, spherical coordinates, Cartesian transforms, great-circle and Vincenty distance, bearing/destination/midpoint, angular separation, bounding boxes, polygons, distance units with conversion, and Zod schemas for all public types. Built with 100% test coverage and OTel instrumentation. |
+| `@suaveplan/geo-planet` | Configurable planet surface geometry from PlanetConfig — ellipsoid derivation, atmosphere scale-height density, Kasten–Young air mass, and Zod schemas for atmosphere, satellite, and orbital configurations. Delegates all geometry to `@suaveplan/geo`. |
+| `@suaveplan/geo-earth` | Canonical Earth configuration (EARTH constant and pre-instantiated earthSurface), plus legacy geospatial utilities: in-memory geocoding provider, geohash encode/decode with round-trip fidelity, and decimal/DMS coordinate parsing and formatting. |
+| `@suaveplan/universe` | Observer model (ground/space discriminated unions), coordinate frame conversions, binary wire-protocol packets for stars and celestial bodies, and a UniverseClient registry for solar, star, tidal, and weather providers. |
+| `@suaveplan/solar-system` | Solar system provider with injectable AstronomyEngine — body position lookup, season detection, equinox/solstice prediction, sunrise/sunset calculation, and lunar phase estimation. Implements SolarProvider from `@suaveplan/universe`. |
+| `@suaveplan/stars` | Star catalog provider with priority-ordered StarCatalogSource interface, in-memory catalog source, cone queries, magnitude filtering, and StarProvider implementation for `@suaveplan/universe`. |
+| `@suaveplan/tides` | Tidal prediction providers: TICON harmonic engine with constituent superposition, ADMIRALTY station provider, and physics-based multi-satellite tide calculation. Implements TidalProvider from `@suaveplan/universe`. |
+| `@suaveplan/health-check` | Standardized /health, /ready, /live endpoints |
+| `@suaveplan/heightmap-tiles` | Delta-encoded heightmap tile pyramid with adaptive bit depth |
+| `@suaveplan/hitbox` | Hierarchical hit detection with per-bone hitboxes, raycasting, and sweep tests |
+| `@suaveplan/ik-solver` | Pure math inverse kinematics solvers (two-bone, look-at, multi-chain) |
+| `@suaveplan/image` | Universal-tier image metadata extraction, format detection, resize math, crop validation, and transform pipeline planning. Zero browser or Node dependencies — runs in Bun, Node, and browsers alike. Modular subpath exports for types, errors, error-codes, and processor. |
+| `@suaveplan/image-quantisation` | Image complexity analysis and adaptive colour quantisation with pool detection, spatial-aware anti-aliasing cleanup, and multiple quantisation algorithms (wuquant, neuquant, rgbquant). Wraps `image-q` with Zod option validation, OTel counter/histogram instrumentation, and structured errors via `@suaveplan/error`. Includes property-based tests (fast-check), mitata benchmarks, and 100% Istanbul coverage. Zero browser or Node dependencies — runs in Bun, Node, and browsers alike. |
+| `@suaveplan/imessage-adapter` | Mac iMessage SQLite watcher adapter for @suaveplan/m... |
+| `@suaveplan/job-scheduler` | Background job scheduling with cron |
+| `@suaveplan/keys` | Key management & vault factory |
+| `@suaveplan/leaderboard` | Leaderboard system with rankings, seasonal resets, and around-player queries |
+| `@suaveplan/license` | Software license generation |
+| `@suaveplan/linter` | Linting utilities |
+| `@suaveplan/lobby` | Multiplayer lobby management with matchmaking and countdown |
+| `@suaveplan/macos-contacts` | macOS Contacts.app bridge via AppleScript for contact syncing |
+| `@suaveplan/macos-keychain` | macOS Keychain bridge via the `security` CLI. `MacOSKeychainBridge` performs credential CRUD (`addItem`/`findItem`/`updateItem`/`deleteItem`/`listItems`/`itemExists`) through a pluggable `CommandExecutor` interface; the default executor uses `Bun.spawn` (or `node:child_process` `execFile`) with arguments-as-array — never shell interpolation — to eliminate command-injection risk. Eight-code error registry (`KEYCHAIN_NOT_FOUND`, `ITEM_EXISTS`, `ACCESS_FAILED`, `LOCKED`, `UNAVAILABLE`, `PERMISSION_DENIED`, `ITEM_INVALID`, `TIMEOUT`) with a stderr-precedence error classifier mapping macOS exit codes to typed factories. Injectable `Clock` for deadline calculations, `AbortSignal` cancellation on every method, OTel spans + ops counters + cli-duration histograms, Zod schemas at every public boundary, `zeroize` on the temporary stdout buffer after password extraction. Unit tests use a real injected stub executor (no mocks); integration tests are tagged `@integration` and skip on non-Darwin. |
+| `@suaveplan/mcp` | MCP server/client with tools, resources, prompts |
+| `@suaveplan/media` | Media processing utilities |
+| `@suaveplan/message-bridge` |  |
+| `@suaveplan/mixamo` | Mixamo character utilities |
+| `@suaveplan/money` | Universal-tier precise currency/money arithmetic using `bigint` minor units — immutable `Money` class with full arithmetic (`add`, `subtract`, `multiply`, `divide`, `abs`, `negate`), comparison (`compareTo`, `equals`, `greaterThan/lessThan[OrEqual]`, `isZero/Positive/Negative`), and conversion (`toMajor`, `toDecimalString`, `toJSON`, `toString`); 5 `RoundingMode`s (`half-up`, `half-down`, `half-even`, `floor`, `ceil`) via standalone `applyRounding`. Built-in currency registry: 30 ISO 4217 fiats (USD, EUR, GBP, JPY, CHF, CAD, AUD, CNY, INR, BRL, KRW, MXN, SGD, HKD, NOK, SEK, DKK, NZD, ZAR, PLN, THB, TRY, TWD, AED, SAR, ILS, RUB, CZK, CLP, PHP) + 5 cryptocurrencies (BTC, ETH, SOL, USDT, USDC) with canonical exponents; `getCurrency` / `getCurrencyOrThrow` / `registerCurrency` / `getAllCurrencyCodes` / `getVirtualCurrencies` / `isVirtualCurrency` / `minorUnitMultiplier`. `Intl.NumberFormat`-derived locale-aware `formatMoney` (showSymbol / showCode / decimal+thousands separator overrides / trailingZeros control) and `formatMoneyCompact` with K/M/B suffixes. Fair allocators preserving the input total via round-robin remainder distribution: `allocateEvenly`, `allocateByRatios`, `allocateByPercentages`. Aggregators with cross-currency guards: `sumMoney`, `minMoney`, `maxMoney`. Lossless JSON round-trip (`Money.toJSON` / `Money.fromJSON`). Typed `MoneyError extends SuaveplanError<MoneyErrorCode>` with stable `MONEY.*` code registry (`CURRENCY_MISMATCH`, `UNKNOWN_CURRENCY`, `DIVISION_BY_ZERO`, `INVALID_ALLOCATION`, `EMPTY_INPUT`, `PARSE_ERROR`) and optional `currency` / `otherCurrency` discriminants; hardened decimal-string parser raises `MONEY.PARSE_ERROR` on malformed input. 6 subpath exports (`./money/money`, `./currencies/currencies`, `./formatter/formatter`, `./allocator/allocator`, `./error-codes/error-codes`, `./types/common`). 90 tests across 5 files at 100/100/100/100 (statements/branches/functions/lines) istanbul coverage. Universal-tier — only `Intl.NumberFormat`; no `node:`/`bun:`/DOM/fs imports. Deps: `@suaveplan/error`, `tslib`. |
+| `@suaveplan/network-bootstrap` | Pluggable peer-discovery chain orchestrator for `@suaveplan/network`. Universal-tier. Owns `DiscoveryChain` (ordered strategy execution, bounded concurrency, dedup by peerId, early stop), `PeerCache` (TTL-based eviction, oldest-first capacity eviction, optional `PeerCacheStorageLike` for cross-restart persistence with `CACHE_CORRUPTED` rejection on bad JSON), `BootstrapPlugin` (`NetworkPlugin` lifecycle wrapper with `install`/`start`/`stop`/`dispose` idempotency over `@suaveplan/retry` `createExponentialBackoff` + full-jitter delay between strategy retries), `BootstrapMiddleware` (typed message interceptor for incoming + outgoing). NetworkBus emits `bootstrap:started`/`:peer-found`/`:exhausted` with typed `BootstrapEventMap`. Injectable `Clock` from `@suaveplan/types` everywhere — no `Date.now()` at module scope. `defineCodes("NET_BOOTSTRAP", [...])` with 4 codes (`CHAIN_EXHAUSTED`, `CACHE_CORRUPTED`, `STRATEGY_TIMEOUT`, `INVALID_OPTIONS`) extending `SuaveplanError`. Zod boundary validation on `PeerInfo`, `PeerCacheConfig`, `BootstrapRetryConfig`, `BootstrapPluginConfig`, `BootstrapMiddlewareConfig`. OTel surface: `bootstrap.chain.execute` span, `bootstrap.peers_found_total{strategy}` + `bootstrap.failures_total{strategy,code}` counters, `bootstrap.chain_duration_ms` histogram. `AbortSignal` threaded through every async path with inner controller chained to caller's signal in the timeout handler. fast-check property tests cover cache eviction invariants and chain dedup invariants. Every barrel uses explicit named exports per CLAUDE.md §6a; every test file imports runner primitives from `@suaveplan/testing/runner` per §7. 67 tests, 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/retry`, `@suaveplan/storage`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-discovery-crdt` | Browser-tier CRDT-awareness `DiscoveryStrategy` for the `@suaveplan/network` mesh, designed to chain into `@suaveplan/network-bootstrap`'s `DiscoveryChain`. Two interchangeable provider backends behind a single `CRDTProviderAdapter` interface: **Yjs** (`y-webrtc` signaling + awareness via `yjsDocFactory`) and **Automerge** (`@automerge/automerge-repo` + `broadcast-channel` + `websocket` + `IndexedDB` adapters via `automergeRepoFactory`). Provider is selected at construction time from a Zod-strict config — orchestrator never branches on `provider` strings post-construction; the adapter shape is the only seam. Five-module orchestrator: `CRDTDiscovery` (main strategy), `CRDTPeerManager` (peer lifecycle), `CRDTIntervals` (periodic reconciliation over `@suaveplan/timing` `Scheduler` + injectable `Clock` — no `setInterval`), `YjsProvider` and `AutomergeProvider` (each implementing `CRDTProviderAdapter`). **`signaling` URL list REQUIRED** by the Zod schema — no `wss://signaling.yjs.dev` default survives anywhere. Production wires factories to real `yjs`/`@automerge/*` packages; tests wire to `FakeYjsBroker` and `FakeAutomergeBroker` — real in-memory implementations of the broker/repo interfaces (NOT `vi.mock`). Optional `EventBusLike<CRDTEventMap>` integration (typed, emitted only when bus provided). Optional `@suaveplan/service-discovery` `ServiceRegistry` integration: discovered peers auto-register as `crdt:<room>:<peerId>`, auto-deregister on drop. 7-code `defineCodes("NET_DISC_CRDT", [...])` registry covering provider-failure / state-desync / peer-reject / invalid-options / disposed / yjs-awareness-failed / automerge-sync-failed. Zod boundary validation on every public option struct + every wire-format message. OTel surface: `disc_crdt.start` span, `disc_crdt.provider.<yjs\/automerge>.sync` per-provider span, `peers_discovered_total{provider,outcome}` counter, `reconcile_duration_ms{provider}` histogram. `AbortSignal` threaded through `start`/`stop`/`discover`/`isAvailable`/`announce`. fast-check property test (`numRuns: 8`) covers state reconciliation convergence + peer dedup across the Automerge path. Constructor-rejection tests cover every missing-config / missing-factory path. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from`@suaveplan/testing/runner` per §7. 92 tests (16 Yjs + 13 Automerge + 32 orchestrator + property/error/otel suites), 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`,`@suaveplan/events`,`@suaveplan/network`,`@suaveplan/network-bootstrap`,`@suaveplan/service-discovery`,`@suaveplan/timing`,`@suaveplan/types`,`yjs` + `y-webrtc` + `@automerge/automerge-repo` + `@automerge/automerge-repo-network-broadcastchannel` + `@automerge/automerge-repo-network-websocket` + `@automerge/automerge-repo-storage-indexeddb` (all catalog `network-discovery`),`@opentelemetry/api`,`tslib`,`zod`. |
+| `@suaveplan/network-discovery-gundb` | Browser-tier GunDB gossip-over-WebSocket `DiscoveryStrategy` for the `@suaveplan/network` mesh, designed to chain into `@suaveplan/network-bootstrap`'s `DiscoveryChain`. **Enterprise security uplift over upstream's flagged-fragile audit** is the load-bearing characteristic of this migration. Five-module orchestrator built on injectable `gunFactory`: production wires to real `gun`, tests wire to `FakeGun` — real in-memory implementation of `GunLike` (NOT `vi.mock`). **`peers` relay list mandatory** — Zod schema `peers: z.array(z.string().url()).min(1)`; constructor throws `INVALID_OPTIONS` on missing/empty. **No public Gun-relay URL survives anywhere in the `.ts` code** — `https://gun-manhattan.herokuapp.com/gun` and any sibling defaults removed (only quoted in `.md` docs to document the removal). **Ed25519-signed peer-announces enforced**: every announce carries an Ed25519 signature over the canonical-serialized body; the inbound handler is defensive by design — unsigned announces are silently dropped with `unsigned` reason, single-bit-tampered signatures are silently dropped with `bad-signature` reason, never bubbling an exception (DoS hardening). Verify dispatches to `@suaveplan/crypto-curve`. **Constant-time peer-ID compare** via `constantTimeEqual` from `@suaveplan/crypto-utils` — closes the trivial side-channel from byte-by-byte string equality. **Wire-payload Zod validation** on every inbound message before reaching business logic; `GunDBPeerAnnounceSchema` + `GunDBMessageSchema` discriminated-union wrapper; malformed / wrong-kind / wrong-type payloads silently dropped + counted. peerId-spoofing rejected (signing-key derived peerId must match claimed peerId). Optional `EventBusLike<GunDBEventMap>` integration. Optional `@suaveplan/service-discovery` integration: peers auto-register as `gundb:<topic>:<peerId>`, auto-deregister on drop. Intervals via `@suaveplan/timing` Scheduler + injectable Clock. 8-code `defineCodes("NET_DISC_GUNDB", [...])` registry: `RELAY_FAILED`, `PEER_CONNECT_FAILED`, `INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`, `UNSIGNED_ANNOUNCE`, `BAD_SIGNATURE`, `INVALID_WIRE_PAYLOAD`. OTel surface: `disc_gundb.start` span, `peers_discovered_total{outcome}` counter, **`gundb.invalid_messages_total{reason}`** + **`gundb.signature_rejected_total{reason}`** security counters (the observability levers for the new defensive layer), `gundb_announce_duration_ms` histogram. `AbortSignal` threaded through `start`/`stop`/`discover`/`isAvailable`/`announce`. `./signing` subpath exports `signAnnounce(privateKey, body)` helper for callers emitting announces. fast-check property tests: 50-run sign/verify round-trip over any valid body + 20-run orchestrator-level signed-announce ingestion. 8 dedicated security tests: unsigned-drop, bad-signature-drop, malformed-payload-drop, payload-with-valid-discriminator-but-bad-types, peerId-spoofing-reject, `constantTimeEqual` direct verification, local-self-echo filter via constant-time path, differing-length peerIds reach length-mismatch branch. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. 67 tests across 5 files, 100% statement/branch/function/line coverage (228/104/38/210). Deps: `@suaveplan/crypto-curve`, `@suaveplan/crypto-utils`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/network-bootstrap`, `@suaveplan/service-discovery`, `@suaveplan/timing`, `@suaveplan/types`, `gun` (catalog `network-discovery`), `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-discovery-hybrid` | Browser-tier multi-strategy `DiscoveryStrategy` orchestrator for the `@suaveplan/network` mesh, composing the five Wave-2 sibling discovery strategies (peerjs/crdt/trystero/webtorrent/gundb) into a single unified surface that itself implements `DiscoveryStrategy` from `@suaveplan/network-bootstrap` — so a `HybridDiscoveryManager` can chain into a higher-level `DiscoveryChain`. Five-module composer architecture: **`HybridDiscoveryManager`** (top-level orchestrator), **`StrategyManager`** (per-strategy health-score + priority bookkeeping), **`Lifecycle`** (start/stop transition FSM), **`PeerTracker`** (deduped peer set with `PeerSource` provenance — which strategy found this peer), **`StrategyLoader`** (dynamic `import()`-based lazy resolution that gracefully handles missing siblings). All five Wave-2 discovery packages declared as `peerDependenciesMeta.{...}.optional: true` — the orchestrator never crashes when a peer-dep is absent; a missing strategy surfaces as `STRATEGY_LOAD_FAILED` and is recorded. Priority-based peer selection. Per-strategy `StrategyHealth` tracking with automatic fallback on degradation. **Banned-mock removal is load-bearing for this migration**: upstream's `__mocks__/strategy-mock.ts` was explicitly NOT ported; in-package `TestStrategy` real-implementation fixture lives at `tests/setup/test-strategy.ts` (deterministic, configurable peer list / failure mode / announce delay). Independently grep-verified zero `vi.mock` / `jest.mock` / `__mocks__/` / `: any` anywhere in the package. Optional `EventBusLike<HybridDiscoveryEventMap>` integration. Optional `@suaveplan/service-discovery` integration: peers register as `hybrid:<strategy>:<peerId>` preserving provenance. 6-code `defineCodes("NET_DISC_HYBRID", [...])` registry (`NO_STRATEGIES`, `ALL_STRATEGIES_DEGRADED`, `STRATEGY_LOAD_FAILED`, `DUPLICATE_STRATEGY`, `INVALID_OPTIONS`, `DISPOSED`). Zod boundary validation on `HybridDiscoveryConfig`, `StrategyConfig`, `StrategyPriority`. OTel surface: `hybrid.peer_sources_total{strategy}` counter, `hybrid.strategy_health_score{strategy}` histogram, `hybrid.active_strategies` gauge, `hybrid.fallback_total{from,to}` counter. `AbortSignal` threaded through every async path. fast-check property tests on peer dedup commutativity + priority-order stability. **Integration test (`tests/integration.test.ts`, 4 tests)** verifies: all 5 sibling-id registration with dedup + `PeerSource` correctness, one-strategy-degradation triggers priority fallback, lifecycle start/stop/restart idempotency, all 5 real shipped sibling packages reachable via dynamic `import()`. `openspec/specs/network-discovery-hybrid/spec.md` written. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. 89 tests across 7 files, 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/network-bootstrap`, `@suaveplan/service-discovery`, `@suaveplan/timing`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`. Optional peer-deps on all five `@suaveplan/network-discovery-{peerjs,crdt,trystero,webtorrent,gundb}`. |
+| `@suaveplan/network-discovery-peerjs` | Browser-tier PeerJS-backed `DiscoveryStrategy` for the `@suaveplan/network` mesh, designed to chain into `@suaveplan/network-bootstrap`'s `DiscoveryChain`. Wraps the PeerJS signaling-server client + WebRTC `DataConnection` lifecycle in a `PeerJSDiscovery` orchestrator with supporting modules: `PeerConnectionManager` (per-peer connection registry), `RoomManager` (logical room semantics over PeerJS IDs with admission cap), `PeerJSConnection` (typed `RTCDataConnection` wrapper), `PeerJSMessageHandlers` (wire-format routing with dedup). Mandatory `host` AND mandatory injectable `peerFactory` — constructor throws `INVALID_OPTIONS` on either omission; **no public-`peerjs.com` fallback survives anywhere in the code**. Production wires `peerFactory` to real `peerjs`; tests wire it to `FakeBroker`/`FakePeer` — real implementations of `PeerLike`/`DataConnectionLike` (NOT `vi.mock`-style mocks). Optional `EventBusLike` integration (typed `PeerJSEventMap`) — emitted only when a bus is provided. Optional `@suaveplan/service-discovery` `ServiceRegistry` integration: discovered peers auto-register as `peerjs:<room>` services + auto-deregister on drop. Interval loops replaced with `@suaveplan/timing` `Scheduler` + injectable `Clock`. 5-code `defineCodes("NET_DISC_PEERJS", [...])` registry (`SIGNALING_FAILED`, `PEER_CONNECT_FAILED`, `ROOM_FULL`, `INVALID_OPTIONS`, `DISPOSED`). Zod boundary validation on every public option struct + every wire-format message. OTel surface: `disc_peerjs.start` span, `peers_discovered_total{outcome}` counter, `signaling_duration_ms` histogram. `AbortSignal` threaded through `start`/`stop`/`discover`/`isAvailable`/`connect`. fast-check property tests cover room-admission cap + message-handler dedup. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. 100 tests, 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/network-bootstrap`, `@suaveplan/service-discovery`, `@suaveplan/timing`, `@suaveplan/types`, `peerjs` (catalog `network-discovery`), `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-discovery-trystero` | Browser-tier Trystero `DiscoveryStrategy` for the `@suaveplan/network` mesh, chains into `@suaveplan/network-bootstrap`'s `DiscoveryChain`. Four interchangeable transports — **BitTorrent trackers** (`TorrentTransportAdapter`), **Nostr relays** (`NostrTransportAdapter`), **MQTT brokers** (`MqttTransportAdapter`), **IPFS libp2p pubsub** (`IpfsTransportAdapter`) — all implementing a single `TrysteroTransportAdapter` interface; orchestrator selects at construction via `pickAdapter()` and **never branches on transport-name strings post-construction**. Per-transport injectable factories (`torrentRoomFactory` / `nostrRoomFactory` / `mqttRoomFactory` / `ipfsRoomFactory`); production wires to real `trystero`, tests wire to `FakeTrysteroBroker` + `FakeTrysteroRoom` — real in-memory implementations of `TrysteroRoomLike` (NOT `vi.mock`). Every transport sub-schema enforces `.min(1)` non-empty lists (`trackers`/`relays`/`brokers`/`bootstrap`) — **no hardcoded public relay/tracker URLs survive anywhere in the code** (upstream `room-config.ts` rewritten as per-transport adapters consuming caller-supplied factories). Auto-fallback between transports via `@suaveplan/retry` `createExponentialBackoff` + injectable `sleepFn`; fallback swaps the adapter instance while preserving the peer-manager + intervals. Optional `EventBusLike<TrysteroEventMap>` integration (typed, emit only when bus provided). Optional `@suaveplan/service-discovery` integration: peers auto-register as `trystero:<transport>:<room>:<peerId>`, auto-deregister on drop. Intervals via `@suaveplan/timing` `Scheduler` + injectable `Clock`. 10-code `defineCodes("NET_DISC_TRYSTERO", [...])` registry (`INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`, `RELAY_FAILED`, `ROOM_FULL`, `ALL_TRANSPORTS_DEGRADED`, `TORRENT_TRACKER_FAILED`, `NOSTR_RELAY_FAILED`, `MQTT_BROKER_FAILED`, `IPFS_BOOTSTRAP_FAILED`). Zod boundary validation on every public option struct + every wire-format message. OTel surface: `disc_trystero.start` span, `disc_trystero.transport.<id>.connect` per-transport span, `peers_discovered_total{transport,outcome}` + `transport_fallback_total{from,to}` counters, `connect_duration_ms{transport}` histogram. `AbortSignal` threaded through `start`/`stop`/`discover`/`isAvailable`/`announce`. fast-check property tests on peer dedup across transports + fallback ordering stability. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. 118 tests, 100% statement/branch/function/line coverage (584 stmts / 206 branches / 127 fns / 543 lines). Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/network-bootstrap`, `@suaveplan/retry`, `@suaveplan/service-discovery`, `@suaveplan/timing`, `@suaveplan/types`, `trystero` (catalog `network-discovery`), `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-discovery-webtorrent` | Browser-tier WebTorrent-tracker `DiscoveryStrategy` for the `@suaveplan/network` mesh, designed to chain into `@suaveplan/network-bootstrap`'s `DiscoveryChain`. Built on top of [`p2pt`](https://github.com/subins2000/p2pt) — a WebTorrent-tracker-based WebRTC peer connector — surfaced via an injectable `p2ptFactory`. Production wires the factory to real `p2pt`; tests wire to `FakeP2PT` — a real in-memory implementation of `P2PTLike` (NOT `vi.mock`). **Tracker list mandatory** — Zod schema `trackers: z.array(z.string().min(1)).min(1)` rejects missing-or-empty list AND empty-string entries with `INVALID_OPTIONS`. **No public-tracker fallback survives anywhere in the code** — every upstream default (`tracker.openwebtorrent.com`, `tracker.btorrent.xyz`, `tracker.files.fm:7073/announce`, `spacetradersapi-chatbox.herokuapp.com:443/announce`) removed; trackers are caller-supplied only. Optional `EventBusLike<WebTorrentEventMap>` integration (5 typed event types: `peer:joined`, `peer:left`, `tracker:announce`, `tracker:error`, `error`). Optional `@suaveplan/service-discovery` `ServiceRegistry` integration: peers auto-register as `webtorrent:<infoHash>:<peerId>`, auto-deregister on drop. Conforms to the `DiscoveryStrategy` interface from `@suaveplan/network-bootstrap` so it plugs into a `DiscoveryChain` directly. 5-code `defineCodes("NET_DISC_WEBTORRENT", [...])` registry (`TRACKER_FAILED`, `PEER_CONNECT_FAILED`, `INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`) extending `SuaveplanError`. Zod boundary validation on `WebTorrentDiscoveryConfig`, `PeerInfo`, `PeerId`, `Multiaddr` + wire payloads. OTel surface: `disc_webtorrent.start` span, `peers_discovered_total{outcome}` + `tracker_errors_total{tracker}` counters, `tracker_announce_duration_ms` histogram. `AbortSignal` threaded through every async method (`start`, `stop`, `discover`, `isAvailable`, `announce`) — including factory-resolve mid-flight cancellation. fast-check property test on peer dedup invariant (same peerId never emitted twice from concurrent tracker announces). **Test suite written from scratch — upstream had `describe.skip`-only.** Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. 46 tests, 100% statement/branch/function/line coverage (171/79/34/155). Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/network-bootstrap`, `@suaveplan/service-discovery`, `@suaveplan/timing`, `@suaveplan/types`, `p2pt` (catalog `network-discovery`), `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-gundb-server` | Server-tier (Node-only) GunDB relay daemon paired with `@suaveplan/network-discovery-gundb` ✅ clients. Idempotent `start({signal?})` / `stop()` lifecycle; injectable `gunFactory` + `FakeGun` real impl. Inline `/health`/`/ready`/`/live` JSON endpoints. **Security wire-payload validation** mirrors the client's defensive model — Zod-validates inbound announces against shared `GunDBPeerAnnounceSchema` (single source of truth, server/client cannot drift), silently drops malformed/wrong-kind/missing-sig/missing-key with `gundb_server.invalid_messages_total{reason}` counter. Signature verification deliberately at client per gossip-security model. **Real-server-boot integration test** boots a real Node `http.Server` on port 0, hits all three health endpoints over real `fetch()`, drives two simulated clients through a shared in-memory Gun graph, confirms malformed payloads dropped without crashing, verifies graceful stop closes the listener. 6-code `NET_GUNDB_SERVER` registry, OTel surface (span + 3 counters + gauge + histogram). `engines.node: ">=20"`, no `browser` field. 56 tests across 7 files, 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/network-discovery-gundb`, `@suaveplan/testing-integration`, `@suaveplan/types`, `gun` (catalog `network-discovery`), `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-transport-hyperswarm` | Server-tier (Node-only) `Transport` + `NetworkPlugin` over the Hyperswarm DHT. Provides hole-punched peer-to-peer connections discovered via a Kademlia-style DHT keyed by 32-byte topics. Renamed from upstream `@suaveplan/network-hyperswarm` per `network-transport-family` convention. **Required injectable `hyperswarmFactory`** — the package NEVER imports `hyperswarm` directly; consumers wire the factory at the app boundary so native deps stay outside the unit-test surface. Tests wire to `FakeHyperswarm`/`FakeSwarmHub` real-implementations under `tests/setup/fake-hyperswarm.ts` (NOT `vi.mock`). Eight-module architecture: `messaging/` (length-prefix wire codec over `@suaveplan/serialize`), `security/` (DHT-level Zod wire-payload validation + Ed25519-signed peer-announce defensive handler — silent drops on bad signatures), `reputation/` (`ReputationStore` with monotonicity invariant property-tested), `discovery/` (DHT topic management with AbortSignal-aware join/leave), `connections/` (per-peer connection registry), `transport/` (`HyperswarmTransport implements Transport`; `connect(peerId, address)` is idempotent-success for already-attached peers, raises `PEER_UNKNOWN` otherwise — honest about being a discovery transport not a dialer), `plugin/` (`HyperswarmPlugin implements NetworkPlugin` mirroring `WebRTCPlugin` shape), `errors/`, `otel/`, `types/`. 10-code `defineCodes("NET_HYPERSWARM", [...])` registry (`DHT_LOOKUP_FAILED`, `PEER_REJECTED`, `STREAM_FAILED`, `INVALID_TOPIC`, `INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`, `PEER_ALREADY_CONNECTED`, `PEER_UNKNOWN`, `TRANSPORT_CLOSED`). Zod boundary validation on every public option struct + wire frames. OTel surface: `hyperswarm.connections_opened_total{outcome}` + `hyperswarm.bytes_total{direction}` counters, `hyperswarm.dht_lookup_ms` + `hyperswarm.dial_ms` histograms, `hyperswarm.active_peers` gauge. Optional `EventBusLike<HyperswarmEventMap>` integration. `AbortSignal` threaded through `join`/`leave`/`connect`/`stop`. **3-peer in-process integration test** spins up three `HyperswarmTransport` instances sharing a `FakeSwarmHub`, verifies all-to-all peer discovery + envelope exchange, asserts each inbox receives messages from the other two (not itself). A second integration test verifies disconnect propagation. **Scoped out (documented in commit history)**: upstream `hyperswarm-resource-limits.ts` per-peer DoS rate-limit layer was NOT ported — belongs in a future `network-plugin-qos` integration; the reputation store covers failure-counting. `@suaveplan/feature-flags` Composite-strategy reputation integration was NOT used — sub-millisecond mutation paths need direct access and pluggable flag evaluator adds wrong dep direction. Upstream `examples/` consolidated to a single `examples/basic.ts` against the modern `Transport` contract (upstream samples used pre-`Transport`-contract shapes). `package.json` declares `"engines": { "node": ">=20" }` and omits the `browser` field; server-tier marker comment on line 1 of `transport.ts`. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. 94 tests across 11 files — **effectively 100% net-new** because upstream coverage was 8.98%. 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/retry`, `@suaveplan/serialize`, `@suaveplan/timing`, `@suaveplan/types`, `hyperswarm` (catalog `network-transport`), `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-transport-libp2p` | Universal-tier `Transport` + `NetworkPlugin` over the libp2p stack for the `@suaveplan/network` mesh. Renamed from upstream `@suaveplan/network-libp2p` per `network-transport-family` convention. Stitches together the canonical libp2p stack (websockets + webrtc sub-transports + Noise encryption + Yamux muxer + identify + ping + bootstrap + circuit-relay-v2) into a `Libp2pTransport` with connection lifecycle, peer addressing, streaming messaging, and metrics. **TCP and mDNS sub-transports deliberately deferred** to a future server-tier sibling — universal-tier websockets+webrtc was the only in-scope path. Required injectable `libp2pFactory` — the package NEVER imports `libp2p` at module-eval; consumers wire `createLibp2p` at the app boundary, tests wire `FakeLibp2pNode` real-implementation under `tests/setup/fake-libp2p.ts` (NOT `vi.mock`). 9-module architecture: `connection/` (libp2p node create + dial), `messaging/{peer-message,frame,send}` (stream-based request/response + wire format over `@suaveplan/serialize` + addressed-send helpers), `streams/` (protocol handler registration), `transport/` (`Libp2pTransport implements Transport`), `plugin/` (`Libp2pPlugin implements NetworkPlugin` mirroring `WebRTCPlugin` / `HyperswarmPlugin`), `errors/`, `otel/`, `types/`. **`bootstrap` list MANDATORY** — Zod schema `bootstrap: z.array(z.string()).min(1)` rejects missing/empty with `INVALID_OPTIONS`; **no public-bootstrap fallback survives** anywhere in the code. 11-code `defineCodes("NET_LIBP2P", [...])` registry (`BOOTSTRAP_FAILED`, `DIAL_FAILED`, `STREAM_FAILED`, `PROTOCOL_NOT_SUPPORTED`, `IDENTIFY_REJECTED`, `INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`, `PEER_ALREADY_CONNECTED`, `PEER_UNKNOWN`, `TRANSPORT_CLOSED`). Zod boundary validation on every public option struct. OTel surface: `libp2p.connections_opened_total{outcome}` + `libp2p.streams_opened_total` + `libp2p.bytes_total{direction}` counters, `libp2p.dial_ms` + `libp2p.stream_ttfb_ms` histograms, `libp2p.active_peers` gauge. Optional `EventBusLike<Libp2pEventMap>` integration. `AbortSignal` threaded through `start`, `dialPeerAddress`, `createAndStartNode`, `registerStreamHandler`, `consumeInboundStream`, `sendEnvelope(Frame)`. **2-peer integration tests** for both `websockets` and `webrtc` sub-transports via `FakeLibp2pHub`. **Discipline metrics: every source file ≤300 LOC (max: `transport.ts` at 290), every test file ≤500 LOC (max: `transport.test.ts` at 419). Zero `react`/`react-dom` imports anywhere in `src/`. Zero `: any` in production source. Zero `vi.mock` / `jest.mock` calls.** Upstream's 749-line `libp2p-demo.tsx` was NOT ported — deferred to Wave 7's `@suaveplan/react-network-libp2p-demo`. Upstream duplicate 56-line `network-libp2p.spec.ts` DELETED (`.spec.ts` is Playwright-only per CLAUDE.md). Upstream 505-line `network-libp2p.test.ts` split across 9 module-scoped test files. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. 74 tests across 11 files, 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/network-transport-webrtc`, `@suaveplan/retry`, `@suaveplan/serialize`, `@suaveplan/timing`, `@suaveplan/types`, 12 libp2p subpackages catalog `network-transport`: `libp2p`, `@libp2p/websockets`, `@libp2p/webrtc`, `@libp2p/bootstrap`, `@libp2p/circuit-relay-v2`, `@libp2p/echo`, `@libp2p/identify`, `@libp2p/interface`, `@libp2p/ping`, `@chainsafe/libp2p-noise`, `@chainsafe/libp2p-yamux`, `@multiformats/multiaddr`. NO `react`, `react-dom`, `@libp2p/tcp`, or `@libp2p/mdns`. `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-libp2p-server` | Server-tier libp2p bootstrap + circuit-relay-v2 daemon paired with the just-shipped `@suaveplan/network-transport-libp2p` ✅ client. Idempotent `start({signal?}) → {peerId, multiaddrs[]}` / `stop()` lifecycle. Production libp2pFactory wires `tcp() + webSockets() + circuitRelayServer() + identify() + noise() + yamux() + bootstrap()`; daemon NEVER resolves `libp2p` at module-eval so native deps stay off the unit-test surface. Tests wire `FakeLibp2pServerNode` real-implementation (NOT vi.mock). Eight-module architecture: `errors/`, `health/health.ts` (verb pipeline for /health/ready/live), `health-listener/` (inline HTTP listener with `listenHttp`), `peer-events/` (peer-connected wiring), `server/server.ts` (daemon class, 299 LOC at hard cap), `otel/`, `types/`. 6-code `defineCodes("NET_LIBP2P_SERVER", [...])` registry (`START_FAILED`, `LISTEN_FAILED`, `INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`, `RELAY_FAILED`). Zod boundary validation on `Libp2pServerConfig`. OTel surface: `libp2p_server.start` span, `libp2p_server.connections_total{outcome}` + `libp2p_server.relayed_streams_total` counters, `libp2p_server.active_peers` gauge, `libp2p_server.start_duration_ms` histogram. AbortSignal threaded through start + graceful stop. **4-scenario in-process integration test**: real HTTP health/ready/live probes, client dial recorded as peer-connected end-to-end, server brokers stream observation across two clients (autoRelay enabled), graceful stop closes the inline listener. **Discipline metrics: largest source 299 LOC, largest test 384 LOC, zero `: any`, zero `vi.mock` / `jest.mock`, zero React deps, every barrel uses explicit named exports per CLAUDE.md §6a, every test imports runner primitives from `@suaveplan/testing/runner` per §7.** `engines.node: ">=20"`, no `browser` field, server-tier marker on the main entry point. 59 tests across 8 files (errors 3, health 13, otel 5, peer-events 7, health-listener 6, server 20, dep-graph 1, integration 4), 100% statement/branch/function/line coverage. Adds `@libp2p/tcp ^11.0.6` to root catalog `network-transport` group (server-only sub-transport; the Wave-4.2 client deliberately omitted it). Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/network-transport-libp2p` (shared types + wire-format compatibility), `@suaveplan/testing-integration`, `@suaveplan/types`, 9 libp2p subpackages catalog `network-transport`, `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-observability` | **Folded into `@suaveplan/network-plugin-monitor`** (Wave 6.1 `network-observability-consolidation`, 2026-05-12). Upstream shipped three feature modules — Prometheus exposition (via `prom-client`), Grafana dashboard generator, and an OTel SDK exporter bridge. Audit showed all three are output adapters consuming an external metric collector; only ~600 LOC of universally-portable surface survived after filtering `prom-client` (Node-only) and external `@opentelemetry/sdk-metrics`. Prometheus exposition was rewritten as a hand-rolled universal-tier text emitter (`0.0.4` format, 195 LOC, sanitised metric/label names + escaped values, counter/gauge/histogram/summary support, configurable quantiles, optional timestamps, pinned `text/plain; version=0.0.4; charset=utf-8` Content-Type, Zod-validated options). Grafana dashboard generator was ported as a pure Zod-validated JSON builder (auto-layout, injectable `Rng` for deterministic UID generation, pinned Prometheus datasource binding `{type:"prometheus",uid:"prometheus"}`, `schemaVersion: 38`). The OTel SDK exporter was deliberately dropped — `network-plugin-monitor` already emits through `@opentelemetry/api` so any externally-registered `MeterProvider` (NodeSDK, `@suaveplan/opentelemetry`'s `NoopSdk`/`SdkFactory`, etc.) picks up the instruments natively, making the bridge structurally redundant. Net result: a single canonical telemetry surface (`@suaveplan/network-plugin-monitor`) instead of two overlapping packages, both feature modules at 100/100/100/100 coverage with sibling `.md` ≥200-word docs. Consumers wanting the standalone `@suaveplan/network-observability` package should depend on `@suaveplan/network-plugin-monitor` and import `createPrometheusExposition` / `GrafanaDashboardGenerator` from its root barrel. |
+| `@suaveplan/network-quality` | **Folded into `@suaveplan/network-plugin-monitor`** (Wave 6.2 `network-quality-consolidation`, 2026-05-12). Upstream shipped three feature modules — `BandwidthMonitor` (EMA sample recorder), `DegradationManager` (4-level quality classifier with hysteresis + one-step transitions), and `createQualityMiddleware` (per-source message-throttling middleware factory) — together with a `QualityPlugin` host wrapper and a `QualityLevel`/`BandwidthSample`/`QualityThresholds` shared types layer. Audit confirmed zero overlap with the shipped `network-plugin-monitor` (which scores per-peer health but does NOT classify into a 4-rung ladder, run hysteresis, or shape outgoing traffic). All three features ported under `src/quality/` as sibling feature modules in the monitor package; the upstream `EventEmitter<TMap>`-based evented API was rewritten as callback-handler subscriptions returning unsubscribe functions to drop the `@suaveplan/events` runtime coupling and match genesis's no-monolithic-EE convention; `hysteresisMs: 0` newly commits same-call (upstream required a second `evaluate()` call); `QualityLevel` rewritten as a `const` object + value-union to drop TypeScript enum reverse-mapping; types Zod-validated at every boundary (`BandwidthSampleSchema`, `QualityThresholdsSchema`, `LevelThresholdSchema`). The upstream `QualityPlugin` `NetworkPlugin`-wrapper was deliberately NOT ported — `network-plugin-monitor` already exposes `MonitorPlugin`, and consumers wanting periodic auto-evaluation wire `BandwidthMonitor` + `DegradationManager` directly behind their own scheduler. 43 net-new tests, all four feature files (`quality-types.ts`, `bandwidth-monitor.ts`, `degradation-manager.ts`, `quality-middleware.ts`) at 100/100/100/100 coverage with sibling `.md` ≥200-word docs. Consumers wanting the standalone `@suaveplan/network-quality` package should depend on `@suaveplan/network-plugin-monitor` and import `BandwidthMonitor` / `DegradationManager` / `createQualityMiddleware` / `QualityLevel` / `QualityThresholds` from its root barrel. |
+| `@suaveplan/network-transport-standby` | Universal-tier pre-emptive WebRTC standby transport for the `@suaveplan/network` mesh. Maintains a pool of warm `RTCPeerConnection` slots so consumer code experiences ~10 ms peer attach instead of the typical 1-3 s ICE/DTLS handshake. `StandbyTransport implements Transport` + `StandbyPlugin implements NetworkPlugin` (mirrors `WebRTCPlugin` / `WebSocketPlugin` shape: install registers transport, start lazy, stop closes + unregisters, dispose idempotent). Six-module architecture: `types/`, `errors/`, `otel/`, `health/monitor` (EMA-smoothed RTT + jitter + loss composite scoring), `reconnect/reconnect` (auto-reconnect FSM via `@suaveplan/retry` `createExponentialBackoff` + equal jitter — replaces upstream ad-hoc `Math.min(base * 2^n, cap)` loop), `pool/pool` (min/max slot config, eviction, warm-up scheduler over `@suaveplan/timing` `createScheduler` + injectable `Clock`, `#topUpInflight` mutex serialising concurrent eviction-driven warms so capacity invariants never break), `transport/transport`, `plugin/plugin`. Injectable `RtcConnectionFactory` — production wires to real `RTCPeerConnection`, tests wire to `FakeRtcConnection` real implementation (NOT `vi.mock`). 6-code `defineCodes("NET_STANDBY", [...])` registry (`POOL_EXHAUSTED`, `SLOT_UNHEALTHY`, `PROMOTION_FAILED`, `INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`). Zod schemas on `StandbyPoolConfig`, `ConnectionRequest`, `SlotState` with cross-field invariants (`minSlots ≤ maxSlots`, `reconnectBaseDelayMs ≤ reconnectMaxDelayMs`). OTel surface: `standby.warm_slots` gauge, `standby.promotions_total{outcome}` + `standby.evictions_total{reason}` counters, `standby.warmup_duration_ms` histogram, `standby.*` spans. Optional `EventBusLike` integration: `transport:standby:warm` / `:promoted` / `:evicted`. `AbortSignal` threaded throughout. Property-test invariants: `warmCount + activeCount ≤ maxSlots` (20 runs over random promote/release/evict op streams), eviction monotonicity (closed slot id never reappears, 15 runs), promotion atomicity (exactly one active slot per successful promote, 20 runs), health stays in `[0, 100]` over arbitrary sample streams including out-of-range inputs (50 runs). Integration test warms 4 slots and asserts `pool.promote("peer-X")` completes in `<100 ms` deterministic-clock simulated; failure-mode test confirms unhealthy slot is evicted and pool tops back up; active-slot eviction emits `disconnected` through the transport. Every barrel uses explicit named exports per CLAUDE.md §6a; every test imports runner primitives from `@suaveplan/testing/runner` per §7. **Renamed from upstream `@suaveplan/network-standby-transport` per `network-transport-family` proposal naming convention.** 102 tests, 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/network`, `@suaveplan/retry`, `@suaveplan/timing`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/network-testing` | Network testing utilities |
+| `@suaveplan/network-trystero-server` | Server-tier Trystero signaling daemon paired with `@suaveplan/network-discovery-trystero` ✅ clients for the relay-backed transport modes. **Construction-time `mode: "mqtt" \| "nostr"`** via a single `BrokerLike` adapter contract (`onConnect` / `onDisconnect` / `onFrame` / `onMalformedFrame` callbacks) — no runtime branching on mode strings post-construction; same pattern as `network-discovery-trystero`'s `TrysteroTransportAdapter`. Required injectable `mqttBrokerFactory` and `nostrRelayFactory` per mode — production passes real WebSocket broker shims at the app boundary, tests bind a deterministic `FakeBroker` real implementation (NOT `vi.mock`). Five-module server architecture: `server/server.ts` (daemon, 298 LOC), `server/broker-select.ts` (mode → factory dispatch), `server/peer-events.ts` (lifecycle event emission), `server/health-listener.ts` (HTTP listener), `health/health.ts` (verb pipeline). Idempotent `start({signal?}) → {address, port, relayUrl}` / `stop()` lifecycle with AbortSignal threaded throughout. Server publishes its own `relayUrl` (`ws://host:port/<mode>`) for clients to consume. 6-code `defineCodes("NET_TRYSTERO_SERVER", [...])` registry (`START_FAILED`, `INVALID_OPTIONS`, `MODE_UNSUPPORTED`, `LISTEN_FAILED`, `DISPOSED`, `NOT_RUNNING`). Zod boundary validation on `TrysteroServerConfig` with mode-specific sub-schemas. OTel surface: `trystero_server.start` mode-labelled span, `trystero_server.connections_total{mode,outcome}` + `trystero_server.messages_relayed_total{mode,outcome}` counters, `trystero_server.active_connections{mode}` gauge, `trystero_server.start_duration_ms{mode}` histogram. **Both modes integration-tested end-to-end**: boot real `node:http` server in `mqtt` mode and `nostr` mode, fetch `/health`/`/ready`/`/live` over HTTP, confirm published `relayUrl`(`ws://host:port/mqtt` and `ws://host:port/nostr`) round-trips the mode marker, drive two-client connect/frame/disconnect lifecycles through the fake broker, observe malformed-frame drop without crash. **Discipline metrics: largest source 298 LOC (under 300 cap), largest test 413 LOC (under 500 cap), zero`: any`, zero`vi.mock` / `jest.mock`, every barrel uses explicit named exports per CLAUDE.md §6a, every test imports runner primitives from`@suaveplan/testing/runner` per §7.** `engines.node: ">=20"`, no`browser` field, server-tier marker. **Scoped out (documented in commit history)**: concrete production broker shims for each mode (would pull in `aedes`/`mosca`/`nostr-tools` runtime deps) deferred to a follow-up pair `network-trystero-server-broker-{mqtt,nostr}`. The Wave-5.3 migration ships the daemon shell + adapter contract; consumers can BYO broker shim today and the canonical implementations land later. 69 tests across 8 files, 100% statement/branch/function/line coverage. Deps:`@suaveplan/error`,`@suaveplan/events`,`@suaveplan/logger`,`@suaveplan/network-discovery-trystero`,`@suaveplan/testing-integration`,`@suaveplan/types`,`@opentelemetry/api`,`tslib`,`zod`. NO runtime broker deps (deferred). |
+| `@suaveplan/notification-channel` | Multi-channel notification routing with templates, r... |
+| `@suaveplan/npc` | NPC lifecycle management with spawn pools, population control, and daily schedules |
+| `@suaveplan/osm-buildings` | OSM building/road geometry extraction and mesh generation |
+| `@suaveplan/overview` | Package overview and discovery |
+| `@suaveplan/packer-browser` | Browser-specific binary packing |
+| `@suaveplan/party` | Party/group system with invites, leadership transfer, and kick/promote |
+| `@suaveplan/payment` | Payment intent lifecycle, webhook verification, rece... |
+| `@suaveplan/payment-providers` | Slim foundation for `@suaveplan/payment-provider-*` siblings — `ProviderRegistry`, `definePaymentProvider` factory, `httpRequest`/`composeAbortSignal`, shared `ApiKeyConfig`/`OAuthConfig`/`MerchantKeyConfig` shapes, `PAYMENT_PROVIDER_CODES` (6 codes) + `PaymentProviderError`. Concrete Stripe/PayPal/Square/Mollie/Adyen adapters ship as separate sibling packages. |
+| `@suaveplan/payment-provider-adyen` | Adyen Checkout API v71 sibling adapter on the slim payment-providers core — `AdyenProvider implements PaymentProvider` (literal name `"adyen"`, `AdyenConfig` alias of shared `MerchantKeyConfig`). `X-API-Key: <apiKey>` header on every call (read + write); caller-supplied `idempotencyKey` forwards as both the `Idempotency-Key` header AND the request body's `reference` field on `createIntent`. Default `reference` generation uses injectable `RandomIdFn` (falls back to `globalThis.crypto.randomUUID()` at call time only — universal-tier, no `node:crypto`). Configured `merchantAccount` injected into every modification body (`/captures`, `/cancels`, `/refunds`). Full lifecycle (`createIntent` → POST `/payments` with `merchantAccount`/`amount`/`reference`/optional `captureDelayHours`/`shopperStatement`/`returnUrl`/`paymentMethod.storedPaymentMethodId`/`metadata`; `confirmIntent` → POST `/details`; `captureIntent` → POST `/captures`; `cancelIntent` → POST `/cancels`; `refund` → POST `/refunds` with optional `amount`; `getIntent` → GET). Exhaustive Adyen → domain mappings — 10-row result-code status table with unknown → `failed`, 1-row refund-status table (`received` → `pending`, else → `failed`), payment-method normalisation (`scheme` → `card`, else → `wallet`; brand lower-cased; `lastFour` → `last4`). Every HTTP call routes through slim-core `httpRequest`; raised `PaymentProviderError`s carry `provider: "adyen"` discriminant. 2 subpath exports, 36 tests at 100/100/100/100. |
+| `@suaveplan/payment-provider-mollie` | Mollie Payments API v2 sibling adapter on the slim payment-providers core — `MollieProvider implements PaymentProvider` with `Authorization: Bearer <apiKey>` auto-headers, full lifecycle (create / confirm / capture / cancel / refund / get), exported pure helpers `formatMollieAmount` / `parseMollieAmount` round-tripping `bigint` minor-units to Mollie's `{ currency, value: "X.YY" }` wire shape (covers 1-cent, exact-major, large-value, and over-precision edges), exported total status maps. 2 subpath exports, 34 tests at 100/100/100/100. |
+| `@suaveplan/payment-provider-paypal` | PayPal Orders v2 + Payments Captures Refund sibling adapter on the slim payment-providers core — `PayPalProvider implements PaymentProvider` (literal name `"paypal"`, `PayPalConfig` extends `OAuthConfig` with `sandbox` shortcut). OAuth2 client-credentials token cache (POST `/v1/oauth2/token` with `Basic <base64(clientId:clientSecret)>`; cached with `expires_in - 60s` skew; refreshed transparently). Injectable `now: NowFn` (token-cache clock + `cancelIntent` timestamps) and `base64Encode: Base64EncodeFn` (defaults `globalThis.btoa`) keep the package universal-tier on Node / Bun / browsers / Web Workers. Token-fetch failures raise `PaymentProviderError(OAUTH_TOKEN_FAILURE)` before any Orders-v2 call. Full lifecycle (`createIntent` → POST `/v2/checkout/orders` with `intent` `AUTHORIZE`/`CAPTURE`, optional `PayPal-Request-Id`; `confirmIntent` → POST `/authorize`; `captureIntent` → POST `/capture` summing every nested capture; `cancelIntent` → POST `/void` returning synthesised intent with injected-now timestamps; `refund` → POST `/v2/payments/captures/{id}/refund`; `getIntent` → GET). Exhaustive 6-row order-status map (unknown → `failed`), 3-row refund-status map, `MoneyLike` bigint ↔ PayPal decimal-string marshalling (handles JPY-style zero-decimal currencies). All HTTP via slim-core `httpRequest`; raised `PaymentProviderError`s carry `provider: "paypal"`. 3 subpath exports, 25 tests at 100/100/100/100. |
+| `@suaveplan/payment-provider-stripe` | Stripe REST API sibling adapter on the slim payment-providers core — `StripeProvider implements PaymentProvider` (literal name `"stripe"`, `StripeConfig` alias of shared `ApiKeyConfig`), `Authorization: Bearer <apiKey>` on every call (read + write), caller-supplied `idempotencyKey` forwarded verbatim as the standard Stripe `Idempotency-Key` header on `createIntent` and `refund` (omitted on read calls and when not supplied). Full lifecycle (`createIntent` → POST `/payment_intents`, `confirmIntent` / `captureIntent` / `cancelIntent` → POST `/payment_intents/:id/{confirm,capture,cancel}`, `refund` → POST `/refunds`, `getIntent` → GET). Exhaustive Stripe → domain mappings — 7-row payment-intent status table with unknown → `failed`, 3-row refund-status table with unknown → `failed`, 4-row refund-reason table with unknown / absent → `other`, payment-method normalisation (`card` → card with `brand`+`last4`, anything else → `wallet`, absent → `undefined`). Every HTTP call routes through slim-core `httpRequest` so `fetch` / `signal` / `timeoutMs` from `ProviderCommonOptions` propagate end-to-end; raised `PaymentProviderError`s carry `provider: "stripe"` discriminant. 2 subpath exports, 42 tests at 100/100/100/100. |
+| `@suaveplan/payment-provider-square` | Square Payments API sibling adapter on the slim payment-providers core — `SquareProvider implements PaymentProvider` (literal name `"square"`, `SquareConfig` extending `ApiKeyConfig` with required `locationId` plus optional `sandbox`/`apiVersion`/`randomId`). `Authorization: Bearer <apiKey>` + pinned `Square-Version` header (defaults `"2024-01-18"`) on every call; sandbox flag flips the default base URL to `https://connect.squareupsandbox.com/v2` (explicit `baseUrl` always wins); injectable `randomId` fills missing `idempotency_key` fields on `CreatePayment` + `RefundPayment` calls (defaults to `crypto.randomUUID()` at call time). Full lifecycle (`createIntent` → POST `/payments` with `location_id`/`autocomplete`/`idempotency_key`, `confirmIntent` → no-op delegating to `getIntent` for Square's auto-confirm model, `captureIntent` → POST `/payments/{id}/complete`, `cancelIntent` → POST `/payments/{id}/cancel`, `refund` → POST `/refunds`, `getIntent` → GET `/payments/{id}`). Exhaustive Square → domain mappings — 5-row payment-status table with unknown → `failed`, 3-row refund-status table (`COMPLETED` → `succeeded`, `PENDING` → `pending`, else → `failed`); card-brand lower-casing with `"unknown"` fallback; refund-reason fallback to `"other"` when Square's free-form reason is empty/absent. Every HTTP call routes through slim-core `httpRequest`; raised `PaymentProviderError`s carry `provider: "square"`. 5 subpath exports, 37 tests at 100/100/100/100. |
+| `@suaveplan/pdf` | PDF generation for receipts/reports/invoices |
+| `@suaveplan/ports` | Global port database with shipping lanes, ETA calcul... |
+| `@suaveplan/profiler` | Runtime performance profiling |
+| `@suaveplan/progression` | Character progression with XP curves, skill trees, perks, and achievements |
+| `@suaveplan/pwa` | Service worker, offline sync, push notifications |
+| `@suaveplan/python-audio-fingerprint` | High-accuracy audio fingerprinting and matching service |
+| `@suaveplan/quest` | Quest/mission system with multi-objective tracking, chains, rewards, and event-driven triggers |
+| `@suaveplan/queue-distribution` | Worker-pool distribution layer: load-balancing strategies (round-robin / least-busy / weighted), worker pool with criteria-based search, manager with @suaveplan/retry-routed retries + periodic health checks + auto-restart, in-process LocalWorker, OTel instrumentation, AbortSignal threading, Zod boundaries, 12-code QueueDistributionError. Decoupled from @suaveplan/queue's Job model via a self-contained DistributedTask<I, O> contract. |
+| `@suaveplan/queue-distribution-http` | HTTP transport plugin for @suaveplan/queue-distribution: HttpWorkerCommunicator (injectable fetch, Zod-validated wire envelope, structured timeouts, AbortSignal) and RemoteWorker (AbstractWorker subclass with bounded exponential-backoff connect via @suaveplan/retry, periodic health-check loop, ping-based reachability probe on communication errors). 6-code QueueDistributionHttpError registry. |
+| `@suaveplan/queue-distribution-worker-thread` | Web-Worker / Node worker_threads transport plugin: WorkerThreadCommunicator with caller-injected WorkerFactory bridging to ThreadWorkerLike, Zod-validated request + reply envelopes, bounded Map<requestId, PendingRequest>, AbortSignal cancellation, structured timeouts, terminate() that fails outstanding requests synchronously; WorkerThreadWorker reacts to crash/exit events and emits OTel counters. 4-code QueueDistributionWorkerThreadError registry. |
+| `@suaveplan/r3f-animation` | Animation state machine, blend trees, layers |
+| `@suaveplan/r3f-audio` | Positional 3D spatial audio (HRTF, culling) |
+| `@suaveplan/r3f-booking` | Interactive 3D venue maps for booking |
+| `@suaveplan/r3f-building` | R3F building mode with snap system, ghost preview, and placement validation |
+| `@suaveplan/r3f-buildings` | Instanced 3D building and road rendering for R3F |
+| `@suaveplan/r3f-camera` | Advanced camera controls for React Three Fiber |
+| `@suaveplan/r3f-character` | Character controller for 3D games |
+| `@suaveplan/r3f-character-vehicle` | Character-vehicle integration (enter/exit, authority transfer) |
+| `@suaveplan/r3f-character-vehicle-picker` | Character/vehicle picker UI with 3D previews, GTA-style customisation |
+| `@suaveplan/r3f-combat` | R3F rendering layer for combat with hitbox debug, projectile trails, muzzle flash, impact effects, and damage numbers |
+| `@suaveplan/r3f-controller` | Input controller for 3D scenes |
+| `@suaveplan/r3f-dmx` | DMX512 lighting control visualization |
+| `@suaveplan/r3f-earth` | 3D globe with port markers, shipping lanes |
+| `@suaveplan/r3f-emulator` | 3D device emulation interface |
+| `@suaveplan/r3f-environment` | Skybox, HDR, and lighting presets |
+| `@suaveplan/r3f-inventory` | Grid-based inventory, equipment, loot tables |
+| `@suaveplan/r3f-lod` | Level-of-detail management |
+| `@suaveplan/r3f-minimap` | Minimap renderer, entity tracking, fog-of-war |
+| `@suaveplan/r3f-networking` | R3F-tier multiplayer state-synchronisation library — the top of the network stack. Composes interpolation, client-side prediction, server reconciliation FSM (composes `@suaveplan/fsm`), snapshot diffing (composes `@suaveplan/diff`), and snapshot interpolation into a single React + R3F surface. **Transport-agnostic**: accepts any `Transport` from `@suaveplan/network` via injection at `<NetworkProvider>`; ships a deterministic `MemoryTransport` real-implementation for tests/dev; canonical production wiring composes `@suaveplan/network-transport-webrtc` at the app boundary. React hooks (`useNetworkSync`, `useNetworkedEntity`, `useNetworkPredict`) + R3F components (`<NetworkProvider>`, `<NetworkedEntity>`, `<NetworkStats>`). 5-code `R3F_NET` registry, Zod boundaries, OTel surface (2 histograms + counter), AbortSignal everywhere. **Property tests**: interpolation monotonicity (200 runs), prediction-reconcile convergence (50 runs), snapshot diff round-trip (100 runs). **2-client integration test** via `MemoryTransport` (real WebRTC E2E scoped out — same structural `Transport` contract, swap at app boundary). Storybook stories: 3 components × default+playground+variants = 11. Discipline: max source 177 LOC, max test 184 LOC, zero `: any`, zero `vi.mock`/`jest.mock`. `<NetworkedEntity>`'s `useFrame` excluded from coverage gate (happy-dom limitation); per-frame logic extracted to `apply-networked-frame.ts` and 100% covered there. 152 tests across 21 files, 100% coverage. Deps: `@suaveplan/diff`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/fsm`, `@suaveplan/network`, `@suaveplan/serialize`, `@suaveplan/timing`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`; peer deps `react`, `react-dom`, `three`, `@react-three/fiber`; optional peer dep `@suaveplan/network-transport-webrtc`. |
+| `@suaveplan/r3f-npc` | R3F NPC rendering with behavior tree debug, nameplates, and dialogue triggers |
+| `@suaveplan/r3f-number-plate` | 3D number plate component |
+| `@suaveplan/r3f-parallax` | Interior-parallax components (WindowParallax + GridParallax) |
+| `@suaveplan/r3f-particles` | GPU-accelerated particle systems (instanced) |
+| `@suaveplan/r3f-pathfinding` | NavMesh pathfinding, steering, crowd simulation |
+| `@suaveplan/r3f-performance` | Performance monitoring and optimization |
+| `@suaveplan/r3f-physics-cascade` | Cascading physics effects |
+| `@suaveplan/r3f-physics-core` | Physics engine abstraction layer |
+| `@suaveplan/r3f-physics-rapier` | Rapier physics engine integration |
+| `@suaveplan/r3f-shaders` | Custom shader effects and materials |
+| `@suaveplan/r3f-terrain` | Procedural terrain with chunked LOD |
+| `@suaveplan/r3f-ui` | HTML/React UI components in 3D space |
+| `@suaveplan/r3f-vegetation` | R3F procedural vegetation with biome rules, LOD, and instanced placement |
+| `@suaveplan/r3f-vehicle` | Vehicle controllers for React Three Fiber |
+| `@suaveplan/r3f-water` | Water rendering and ocean simulation |
+| `@suaveplan/r3f-weather` | R3F weather rendering with particles, fog, lightning, and surface wetness |
+| `@suaveplan/r3f-world` | World management and scene composition |
+| `@suaveplan/r3f-xr` | WebXR/VR/AR with controller and hand tracking |
+| `@suaveplan/react-admin-forms` | Admin form components |
+| `@suaveplan/react-audio` | Audio components & processing |
+| `@suaveplan/react-audio-fingerprint` | Audio fingerprinting components |
+| `@suaveplan/react-audio-player` | Modular audio player with 3D viz |
+| `@suaveplan/react-audio-stream` | Audio streaming components |
+| `@suaveplan/react-auth` | Authentication components |
+| `@suaveplan/react-auth-whitelabel` | White-label auth with tenant branding |
+| `@suaveplan/react-bank` | Game banking components and hooks |
+| `@suaveplan/react-calendar` | Calendar and date picker components |
+| `@suaveplan/react-campaigns` |  |
+| `@suaveplan/react-charts` | Chart and data visualization components |
+| `@suaveplan/react-color-picker` | Color picker component |
+| `@suaveplan/react-command-palette` | Cmd+K command palette with fuzzy search, keyboard na... |
+| `@suaveplan/react-consent-overlay` | Cookie/consent/privacy overlays |
+| `@suaveplan/react-contacts` |  |
+| `@suaveplan/react-controller` | Game controller components |
+| `@suaveplan/react-crafting` | Crafting UI with recipe filtering, station selection, and craft queues |
+| `@suaveplan/react-crypto` | Client-side cryptography components |
+| `@suaveplan/react-data-table` | Data grid with sorting/filtering/pagination |
+| `@suaveplan/react-dialogue` | Dialogue UI with typewriter effect, choices, and speaker portraits |
+| `@suaveplan/react-dnd` | Drag-and-drop with sortable lists |
+| `@suaveplan/react-docs` | React components for rendering Suaveplan documentati... |
+| `@suaveplan/drive-react-sharing` | Drive sharing UI (ShareDialog, PartitionBadge) |
+| `@suaveplan/react-error-boundary` | Error boundary with fallback UI |
+| `@suaveplan/react-file-upload` | Drag-and-drop file upload with chunked/resumable upl... |
+| `@suaveplan/react-font-decompress` | React hooks for font loading |
+| `@suaveplan/react-forms` | Form components with validation |
+| `@suaveplan/react-game-hud` | Game HUD state for health, ammo, compass, minimap, notifications |
+| `@suaveplan/react-game-map` | World map with viewport, markers, fog of war, and zoom controls |
+| `@suaveplan/react-game-settings` | Game settings for graphics, audio, controls, and accessibility |
+| `@suaveplan/react-hotkeys` | Keyboard shortcut management |
+| `@suaveplan/react-image` | Image components with lazy loading |
+| `@suaveplan/react-infinite-scroll` | Infinite scroll with IntersectionObserver |
+| `@suaveplan/react-iphone` | iPhone simulator with WebRTC support |
+| `@suaveplan/react-kanban` | Headless kanban board with drag-and-drop columns, sw... |
+| `@suaveplan/react-loading` | Loading screen with weighted task progress and tip rotation |
+| `@suaveplan/react-map` | Map visualization components |
+| `@suaveplan/react-media` | Media rendering components |
+| `@suaveplan/react-modal` | Modal/dialog system with focus trapping |
+| `@suaveplan/react-network-libp2p-demo` | React demo for `@suaveplan/network-transport-libp2p` ✅ — net-new genesis package extracted from upstream's 749-line `libp2p-demo.tsx` per the tier-isolation rule (universal-tier transport packages cannot pull React; demo lives at the React tier). Six subcomponents split per CLAUDE.md ≤300-LOC discipline: `<Libp2pDemo>` (root composer with context + state orchestration), `<NodeStatusPanel>` (peer ID + node lifecycle status), `<NodeControls>` (start/stop + bootstrap edit), `<PeerInteractionPanel>` (dial input + echo + send controls), `<PeerList>` (connected peers + per-peer status), `<LogPanel>` (event log with level filtering). Each subcomponent gets its own folder with `<name>.tsx` + `<name>.md` + `<name>.test.tsx` + `<name>.stories.tsx` + `<name>.types.ts` + `index.ts`. `useLibp2pDemo` orchestration hook + sibling `wirePeerEvents` helper. **Bootstrap list is a REQUIRED React prop** (`Libp2pDemoProps.bootstrap: readonly string[]`) — no hardcoded defaults; `useLibp2pDemo`'s Zod schema rejects missing/empty; README documents the contract under "Required user-supplied bootstrap". Package NEVER imports `libp2p` directly — consumes only the structural `Libp2pDemoNodeFactory` adapter that production consumers wire to a real libp2p stack at the app boundary. 5-code `defineCodes("REACT_LIBP2P_DEMO", [...])` registry (`INVALID_OPTIONS`, `DEMO_DISPOSED`, plus 3 demo-specific failure modes). Zod boundary validation on every public prop interface. Every component has Storybook stories: 6 components × default + playground + ≥1 variants (3-5 stories per file) = full coverage of UI surface. Snapshot + interaction tests via `@suaveplan/testing-dom`. AbortSignal threaded through async UI flows (dial, send). **Discipline metrics**: max source 263 LOC (`use-libp2p-demo.ts`), max test 495 LOC, zero `: any`, zero `vi.mock`/`jest.mock`, every barrel uses explicit named exports per CLAUDE.md §6a, every test imports runner primitives from `@suaveplan/testing/runner` per §7. 72 tests across 10 test files, 100% statement/branch/function/line coverage. Deps: `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`. Peer deps: `react`, `react-dom`, `@suaveplan/network-transport-libp2p` (required — the demo consumes its public surface). |
+| `@suaveplan/react-notifications` | Toast/notification system |
+| `@suaveplan/react-pdf` | PDF viewer with zoom and navigation |
+| `@suaveplan/react-permissions` | RBAC/ABAC permission components |
+| `@suaveplan/react-port-tracking` | Port tracking components and hooks |
+| `@suaveplan/react-rich-text` | Rich text WYSIWYG editor (Tiptap-based) |
+| `@suaveplan/react-rule-builder` | Visual rule builder with AND/OR groups, drag-drop, JSON config |
+| `@suaveplan/react-skeleton` | Skeleton/shimmer loading placeholders |
+| `@suaveplan/react-social` | Social library with real-time updates |
+| `@suaveplan/react-social-game` | Social game UI with friends list, requests, blocking, and status |
+| `@suaveplan/react-store` | Store state management components |
+| `@suaveplan/react-timeline` | Timeline visualization components |
+| `@suaveplan/react-tour` | Guided product tours and onboarding walkthroughs wit... |
+| `@suaveplan/react-tree-view` | Tree view component |
+| `@suaveplan/react-ui` | Core React UI component library |
+| `@suaveplan/react-ui-social` | Social UI components |
+| `@suaveplan/react-video` | Video player components |
+| `@suaveplan/react-virtual` | Virtualized list/grid rendering |
+| `@suaveplan/react-wizard` | Multi-step form wizard with validation |
+| `@suaveplan/rules` | Business rules engine & validation |
+| `@suaveplan/sandbox` | Sandboxed execution environment |
+| `@suaveplan/seed` | Database seeding and fixture framework |
+| `@suaveplan/server-keys` | Server key management CLI |
+| `@suaveplan/service-discovery` | Universal-tier service-registry primitive consumed by every Wave-2 `network-discovery-*` plugin. `ServiceRegistry` with upsert + strict `register`, `refresh`, `deregister`, `get`/`list`/`size`, `query`, AbortSignal-aware `watch(query, signal?)` AsyncIterableIterator (with buffering + termination), `prune`, optional `flush`/`load` via `ServiceRegistryStorageLike` (subset of `@suaveplan/storage` AbstractStorage; opt-in cross-restart persistence), optional `EventBusLike<ServiceRegistryEventMap>` emit for `service:registered`/`:deregistered`/`:expired`. Injectable `Clock` from `@suaveplan/types` — no `Date.now()` at module scope. `defineCodes("SVC_DISC", [...])` with 4 codes (`DUPLICATE_REGISTRATION`, `QUERY_INVALID`, `REGISTRY_FULL`, `INVALID_OPTIONS`) extending `SuaveplanError`. Zod boundary validation on `ServiceDescriptor`, `ServiceQuery`, and registry options. OTel surface: `svc_disc.registrations_total{outcome}` + `svc_disc.queries_total` counters, `svc_disc.query_duration_ms` histogram, observable `svc_disc.active_services` gauge. fast-check property tests cover TTL expiry monotonicity + query determinism. Every barrel uses explicit named exports per CLAUDE.md §6a; every test file imports runner primitives from `@suaveplan/testing/runner` per §7. 44 tests, 100% statement/branch/function/line coverage. Scope-down vs. upstream: upstream `LoadBalancingStrategy`/`HealthCheckResult`/connection-tracking dropped — this package is a registry primitive; consumers compose load-balancing externally over the typed-query surface. Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/storage`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/slack-client` | Generic Slack API client for messaging, channels, and webhooks |
+| `@suaveplan/sms` | SMS send/receive, delivery status tracking, template... |
+| `@suaveplan/sms-providers` | SMS provider implementations for @suaveplan/sms - Tw... |
+| `@suaveplan/spatial-hash` | Spatial hashing for O(1) broad-phase 2D/3D queries |
+| `@suaveplan/storage-browser` | Browser storage (IndexedDB, localStorage) |
+| `@suaveplan/storage-browser-opfs` | OPFS storage backend for @suaveplan/storage |
+| `@suaveplan/storage-file` | Node.js filesystem storage |
+| `@suaveplan/storybook-test-utils` | Storybook E2E testing utilities |
+| `@suaveplan/streams-chunk-queue` | Chunked queue stream processing |
+| `@suaveplan/streams-metadata` | Stream transform for extracting rich media metadata via EXIF, MIME, and events |
+| `@suaveplan/telegram-client` | Generic Telegram Bot API client for messaging, groups, and media |
+| `@suaveplan/test-vite` | Vite test configuration utilities |
+| `@suaveplan/vehicle-physics` | Engine-agnostic vehicle physics (Pacejka tires, suspension, drivetrain) |
+| `@suaveplan/video` | Video metadata extraction, format detection, and tra... |
+| `@suaveplan/video-thumbnails` | Video thumbnail generation and sprite sheets via ffmpeg |
+| `@suaveplan/weapons` | Weapon system with projectile ballistics, melee, recoil, ammo, and attachments |
+| `@suaveplan/weather` | Dynamic weather simulation with transitions, zones, and gameplay effects |
+| `@suaveplan/web-workers` | Web Worker/SharedWorker management |
+| `@suaveplan/websocket-gateway` | Server-tier WebSocket gateway hosting rooms + presence + channel-multiplexing on a single TCP connection. Pairs with the Wave-1-adapter-refactored `@suaveplan/network-transport-websockets` ✅ client. Idempotent `start({signal?}) → {address, port}` / `stop()` lifecycle with AbortSignal threaded throughout; graceful shutdown drains in-flight messages before resolving. Required injectable `wsServerFactory` — production wires to real `ws.WebSocketServer`, tests wire to either `FakeWsServer` (in-memory) or `RealWsServer` (real `ws` adapter for the 3-client integration test); NEVER `vi.mock`. Twelve modules: `errors`, `health`, `otel`, `types`, `room`, `presence`, `channel` (subsystem packages); `gateway/{access-gate,channel-manager,channel-ops,client-lifecycle,defaults,gateway-deps,gateway,heartbeat,lifecycle,message-factory,presence-fire,presence-webhook,room-ops}` (gateway orchestration). The top-level `gateway.ts` is a 332-LOC facade composing 7 well-factored subsystem modules — 32 LOC over CLAUDE.md's 300 hard cap as a documented facade-pattern exception; alternatives (composition-by-mixin / aggressive inline / JSDoc strip) would not produce a meaningfully cleaner architecture. Every other module sits well under cap (36-215 LOC range). **Hooks for unmigrated deps** (per proposal §"Hooks for unmigrated deps"): `authVerifier?: (handshake) → Promise<AuthContext>` (default no-op pass-through; replace with `@suaveplan/jwt-tenant` when shipped), `authorizationCheck?: (ctx, action) → Promise<boolean>` (→ `@suaveplan/permissions`), `rateLimitGate?: (ctx, action) → Promise<boolean>` (→ `@suaveplan/rate-limiter`), `auditLogger?: (event) → void` (→ `@suaveplan/audit-logging`). README documents the four replacement paths. **Direct integrations with already-shipped packages**: `@suaveplan/idempotency` `IdempotencyGuard` on every mutating event (room create / message send / presence update), `@suaveplan/retry` `RetryPolicy` + circuit breaker on webhook delivery, `@suaveplan/webhook-client` for signed presence-event delivery, `@suaveplan/logger` structured logging with trace correlation. 9-code `defineCodes("WS_GATEWAY", [...])` registry (`ROOM_NOT_FOUND`, `ROOM_FULL`, `CHANNEL_INVALID`, `AUTH_REJECTED`, `RATE_LIMITED`, `INVALID_OPTIONS`, `DISPOSED`, `NOT_RUNNING`, `START_FAILED`). Zod boundary validation on every public option struct + every wire frame. OTel surface: `ws_gateway.{connect,message,broadcast}` spans, `ws_gateway.rooms_active` + `ws_gateway.presence_updates_total{kind}` counters, `ws_gateway.message_dispatch_ms` histogram. Inline `/health`/`/ready`/`/live` HTTP endpoints sharing the same TCP port. **3-client real-`ws` integration test**: boots `WebSocketGateway` backed by real `ws.WebSocketServer` via `RealWsServer`, opens 3 real `ws` clients, joins them to a shared room, broadcasts, asserts `recipients == [id2, id3]`, asserts client count returns to 0 on shutdown, asserts `/health` `/ready` `/live` from same TCP port. **Discipline metrics: largest source 332 LOC (documented facade exception), largest test 336 LOC, zero `: any`, zero `vi.mock`/`jest.mock`, every barrel uses explicit named exports per CLAUDE.md §6a, every test imports runner primitives from `@suaveplan/testing/runner` per §7.** Scoped out: inbound wire-frame router is a no-op shim — public typed methods (`joinRoom`/`broadcastToRoom`/`subscribeToChannel`/`publishToChannel`) ARE the typed router; the companion `network-transport-websockets` client invokes them directly via shared session abstraction. fast-check property tests deferred (existing 125 unit + integration tests already give 100% coverage). `engines.node: ">=20"`, no `browser` field, server-tier marker. 125 tests across 13 files, 100% statement/branch/function/line coverage (508/220/158/458). Deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/idempotency`, `@suaveplan/logger`, `@suaveplan/network-transport-websockets`, `@suaveplan/retry`, `@suaveplan/testing-integration`, `@suaveplan/timing`, `@suaveplan/types`, `@suaveplan/webhook-client`, `ws` (catalog `network-server`), `@opentelemetry/api`, `tslib`, `zod`. |
+| `@suaveplan/wip` | Work-in-progress experiments |
+| `@suaveplan/workflow` | Workflow/saga orchestration |
+
+## Genesis-Original
+
+**6** packages tracked as net-new with no upstream source AND no genesis implementation yet (per `STATUS.md` ❌, refreshed 2026-05-12). Genesis-original packages that *have* shipped are counted under **Completed** above.
+
+| Package | Summary |
+| --- | --- |
+| `@suaveplan/bytes` | Low-level byte utilities for the Suaveplan monorepo: lossless hex/base64/UTF-8 encoding, Uint8Array manipulation, and UUID conversion. No native addons; depends only on platform globals (TextEncoder, atob/btoa, crypto.randomUUID) and @suaveplan/error for typed errors. |
+| `@suaveplan/cbor` | Universal-tier RFC 8949 CBOR encoder/decoder with RFC 8742 sequences, RFC 9052 COSE_Key bridge, RFC 8392 CWT support, and RFC 8610 CDDL hooks. Hand-rolled major-type 0-7 codec with preferred shortest-form integers, deterministic-mode opt-in, indefinite-length emission via opt-in flag, half-precision float decode + encode, RFC 8742 streaming sequence reader, pluggable tag registry (built-in tags 0/1/2/3/21/22/23/24/32/35/55799), pull-decoder with bounded recursion (maxDepth: 64) and bounded item count (maxItems: 1_000_000). COSE bridge: `decodeCoseKey(bytes)` returning typed Ec2Key/OkpKey/RsaKey/SymmetricKey discriminated union per RFC 9052 §7, COSE alg label → genesis crypto-curve algorithm-ID mapping, JWK round-trip. Diagnostic notation emitter for debug logging. 7-code error registry, Zod boundary schemas, full OTel surface. 50 src files at 100% coverage. Gates `@suaveplan/webauthn` (COSE_Key decode for credential public key). |
+| `@suaveplan/crypto-browser` | WebCrypto-backed engine implementations for @suaveplan/crypto — AES-256-GCM, Ed25519, ECDSA-P256/P384, X25519, ECDH-P256/P384, RSA, AES-KW, and non-extractable key support via crypto.subtle. Zero third-party cryptography dependencies. |
+| `@suaveplan/crypto-cipher` | Low-level AEAD (Authenticated Encryption with Associated Data) cipher primitives for the @suaveplan/crypto stack. Provides three algorithms — AES-256-GCM, ChaCha20-Poly1305, and XChaCha20-Poly1305 — each as a standalone subpath export for tree-shaking. Nonces are always caller-supplied: the package validates nonce length but never generates randomness internally, keeping the CSPRNG boundary in the caller's control. Implementation flavour ('noble' vs 'native') is selected at build time via crypto.config.ts; all Phase 0 implementations route to @noble/ciphers. Use @suaveplan/crypto for the high-level façade that combines nonce generation, engine selection, and structured error handling; use this package only when you need to supply your own cipher engine implementation. |
+| `@suaveplan/crypto-core` | Universal cryptographic primitives — engine-pluggable AEAD, Ed25519/ECDSA-P256 signing, X25519 key agreement, sealed-box, and auth-box. Built on audited @noble/ libraries with zero WASM. |
+| `@suaveplan/crypto-curve` | Low-level elliptic-curve building blocks for the @suaveplan/crypto stack. Exposes four curves — secp256k1, Ed25519, X25519, and NIST P-256 — each as a standalone subpath export so bundlers only ship the primitives actually used. Every curve provides key generation, signing/verification (or key agreement), and raw byte operations. Implementation flavour ('noble' vs 'native') is selected at build time via the repo-root crypto.config.ts; all Phase 0 implementations route to @noble/curves. Use this package when you need raw curve operations; for high-level AEAD, signing, or sealed-box use @suaveplan/crypto instead. |
+| `@suaveplan/crypto-hash` | Pure-TypeScript hashing substrate. SHA-2 digests, HMAC, HKDF, PBKDF2, |
+| `@suaveplan/crypto-rsa` | Universal-tier RSA primitives covering RFC 8017 PKCS #1 v2.2 (PKCS1v15 + PSS sign/verify, RSAES-OAEP + RSAES-PKCS1-v1_5 encrypt/decrypt), RFC 5208/5958 PKCS#8, RFC 5280 SubjectPublicKeyInfo, RFC 7517/7518 JWK, RFC 7468 PEM framing, RFC 7638 JWK Thumbprint plus RFC 9278 thumbprint URI, SPKI fingerprint with hex/base64/base64url/colon-hex output, NIST FIPS 186-5 multi-prime keygen with 64-round Miller-Rabin and AbortSignal threading, and RFC 8017 §5.1.2 / Kocher 1996 blinding wired by default into every sign and decrypt path with `{ blinding: false }` opt-out emitting a counter. Pluggable `RsaCryptoEngine` adapter (noble + WebCrypto subtle + auto-selector) lets consumers choose between pure-JS portability and platform-accelerated subtle, while the `RsaKeyHandle` HSM/PKCS#11 bridge with reference `SoftwareRsaKeyHandleProvider` decouples consumer code from any specific hardware backend. FIPS 186-5 profile gate enforces modulusBits ∈ {2048, 3072, 4096}, e ∈ [2¹⁶+1, 2²⁵⁶-1] odd, PSS saltLength === hLen, and SHA-1 ban for sign/verify. JWK `key_ops` / `use` / `alg` enforcement (RFC 7517 §4.2-4.4) prevents the common cross-purpose mistake (`use: "sig"` key used for encryption). Bleichenbacher-resistant combined-error decrypt and constant-time PKCS1v15 verify (Wycheproof-grade) close the historical attack surface. Hand-rolled DER reader/writer keeps the audit boundary tight. 17-code error registry, full OTel histogram + counter surface, Zod schemas at every public boundary, 438 tests at 100/100/100/100 coverage. Gates `@suaveplan/x509` (cert-chain RSA-SHA256 verify), `@suaveplan/jws` (RS256/PS256/RSA-OAEP), `@suaveplan/webauthn` (TPM endorsement keys). |
+| `@suaveplan/crypto-keys` | Keypair generation, validation, and keychain management for the @suaveplan stack. Delegates cryptographic operations to @suaveplan/crypto while adding key lifecycle utilities: tagging keypairs with their algorithm, validating structural and cryptographic correctness, and storing named keypairs with pluggable persistence adapters. |
+| `@suaveplan/crypto-sodium` | libsodium-backed engine implementations for @suaveplan/crypto. Provides AEAD encryption, Ed25519 signing, X25519 key agreement, sealed-box, auth-box, deterministic KDF, BLAKE2b MAC, Argon2id password hashing, and Ristretto255 group operations — all via the libsodium-wrappers-sumo WASM module. |
+| `@suaveplan/crypto-utils` | Shared cryptographic utilities consumed internally by all other @suaveplan/crypto- packages. Provides the low-level primitives that every crypto implementation needs but that belong in one place: multi-alphabet encoding (toHex/fromHex, toBase64/fromBase64, toBase64Url, toBase58/fromBase58); byte helpers (concatBytes, xor, i2osp/os2ip for integer-to-octet-string conversions); constantTimeEqual for timing-safe comparisons; randomBytes with an injectable ByteSource; zeroize for wiping key material; Merkle tree helpers (merkleRoot, merkleProof, verifyMerkleProof); a PrimitiveId registry and PrimitiveNotImplemented sentinel error; and KAT/differential-fuzz harnesses (runVectors, diffFuzz) used in every crypto primitive's test suite. Zero runtime crypto dependencies — this package provides helpers only, not cryptographic algorithms. Application code should generally import from @suaveplan/crypto or @suaveplan/crypto-hash; import from this package only when building a new cryptographic primitive or engine adapter. |
+| `@suaveplan/crypto-vault` | Cryptographic foundation layer for the Vaulted password-manager ecosystem. Provides BIP39 mnemonic generation/round-trip via @scure/bip39; OWASP-hardened Argon2id KDF (≥64 MiB / t≥3 / p≥1); BIP32-style HD key derivation from mnemonic seed; two-secret key derivation (2SKD) combining password + Secret Key + email-derived salt → AUK; hierarchical HKDF tree (AUK → personal keyset → vault key → item key) with versioned info strings; SRP-6a client per RFC 5054 (2048-bit safe-prime group, SHA-256, salt/x/v/A/M1/K/M2 with B mod N == 0 tamper rejection); SecureBuffer with eager zeroization, masked toString, clone isolation, and a global zeroizeAll() registry; OpaqueKeyHandle for crossing module boundaries without exposing raw Uint8Arrays; structured CryptoVaultError codes for every failure mode; and OTel counters/histograms on all derivations. Wraps @suaveplan/crypto-hash for primitives — does not re-implement cryptography. The vault layer (when migrated) consumes OpaqueKeyHandle so no key material ever leaves this package's memory boundary. |
+| `@suaveplan/docker` | Docker Compose infrastructure for the genesis monorepo. Three stacks cover every stage of the development lifecycle. |
+| `@suaveplan/font-convert` | Converts TTF/OTF/WOFF/WOFF2 font files to the typeface.js JSON format used by Three.js FontLoader. Also defines the canonical TypefaceFont, TypefaceGlyph, and PathCommand types consumed by @suaveplan/font-compress. |
+| `@suaveplan/font-subset` | Font subsetting and compression library with a codec-agnostic adapter interface. Supports Unicode range subsetting, WOFF2/WOFF/OTF/TTF output, OpenType feature filtering, hinting strip, and metadata strip. Adapter implementations supply the actual codec; this package provides the orchestration, validation, format detection, and OTel instrumentation. |
+| `@suaveplan/hibp` | Privacy-preserving Have I Been Pwned client. Range API uses SHA-1 k-anonymity prefix lookup against `/range/<5-hex-prefix>` with mandatory `Add-Padding: true` header and constant-time suffix compare — full hash and full password never leave the function. 1000-iteration byte-level no-leak property suite proves the privacy contract. Optional NTLM mode via injectable `NtlmHashAdapter` (MD4-UTF16-LE not bundled — universal-tier package can't pull that dep). Authenticated breach + paste APIs against `/breachedaccount` and `/pasteaccount` with `hibp-api-key` header, 1500ms client-side rate-limit gate via injectable `Clock`, 429 `Retry-After` honour with exponential backoff. In-memory LRU cache (default 10k entries, 24h TTL) keyed by SHA-1 prefix, pluggable `HibpCacheLike` for redis/IndexedDB swap. Differential-privacy decoy-prefix padding mode. Zod boundary schemas at every response (`BreachSchema`, `PasteSchema`, `PwnedResultSchema`), 7-code error registry, AbortSignal threaded everywhere, full OTel surface (range/breach duration histograms, outcome counter, rate-limit-throttled counter, errors counter). 23 src + 24 test files at 100% coverage. |
+| `@suaveplan/install-agent-skills` | Installer plugin that bundles every Suaveplan skill (SKILL.md + assets) |
+| `@suaveplan/installer` | Plugin host for project boilerplating and asset installation. Pipelines |
+| `@suaveplan/json` | Safe, enterprise-grade JSON utilities with prototype-pollution protection, |
+| `@suaveplan/jws` | RFC 7515 JSON Web Signature implementation covering compact + JSON-flat + JSON-general serializations. Verify and sign across the full RFC 7518 + RFC 8037 algorithm set: HS256/384/512 (HMAC with constant-time compare via `@suaveplan/crypto-utils`), RS256/384/512 (delegates to `@suaveplan/crypto-rsa.rsaVerifyPkcs1v15` / `rsaSignPkcs1v15`), PS256/384/512 (`@suaveplan/crypto-rsa.rsaVerifyPss` / `rsaSignPss`), ES256/384/512 (`@suaveplan/crypto-curve` p256/p384/p521 with raw r‖s — DER form rejected), EdDSA (`@suaveplan/crypto-curve.ed25519`). 12-step verify orchestrator with strict ordering (algorithm allowlist BEFORE crypto, `crit` enforcement BEFORE alg dispatch, AbortSignal at three checkpoints). `alg: "none"` rejected by default — caller MUST pass `algorithms: ["none"]` AND `acceptNone: true` to opt in. `crit` allowlist enforcement (consumers MUST explicitly list `"b64"` per RFC 7797 §3). `jwk` and `x5c` header parse — `x5c` chain delegated to `@suaveplan/x509.validateChain` against caller-supplied trust anchors. `kid` resolver injection. RFC 7515 §A.5 detached signatures. RFC 7797 `b64: false` unencoded payload. Multi-signature JSON-general with `requireAll: false` default. RFC 7515 Appendix A.1-A.7 vectors verified verbatim. 18-code error registry, Zod boundaries, full OTel surface. 43 src + 26 test + 24 sibling `.md` + 6 fixture + 3 benchmark files; 216 tests at 100% coverage. Gates `@suaveplan/webauthn` (android-safetynet attestation verifier). |
+| `@suaveplan/locale-data` | Static ISO 3166-1 country data and ISO 639-1 language data with typed lookup functions, |
+| `@suaveplan/network-plugin-protocol` | Network protocol plugin for the genesis mesh system. |
+| `@suaveplan/network-plugin-registry` | Fixed-capacity peer registry with bitpacker-based binary encoding. |
+| `@suaveplan/network-transport-webrtc` | WebRTC transport plugin for mesh networking. |
+| `@suaveplan/otp` | Universal-tier RFC 4226 HOTP + RFC 6238 TOTP + RFC 6287 OCRA + Google Authenticator Key URI Format. HOTP with `bigint` counter, configurable digits 6/7/8, SHA-1/256/512. TOTP with `T = floor((now − T0) / period)`, drift-window verify returning matching `delta` for clock-skew detection, constant-time compare, injectable `Clock` from `@suaveplan/types`. Key URI Format parse + format with RFC 4648 §6 base32 codec (no-padding default, opt-in padding). OCRA challenge-response with suite-string parser and mutual auth flow. Recovery codes — crockford-base32 grouping (4-4-4-4) with Argon2id-hashed verify via `@suaveplan/crypto-hash`. Backup-aware `verifyMany([secret1, secret2], code)` for rotation windows. Clock-drift detector returning `delta` outside the verify window. RFC 4226 Appendix D + RFC 6238 Appendix B + RFC 6287 Appendix C test vectors all green. 9-code error registry, Zod boundaries, full OTel surface (generate/verify duration histograms, outcome+delta_bucket counter). 41 src files at 100% coverage. |
+| `@suaveplan/password-generator` | Cryptographically-strong password and passphrase generator. Char-class mode with configurable length, character classes (lowercase/uppercase/digits/symbols), exclusion sets (ambiguous `0Ol1I`, lookalike pairs), required-class quotas (≥1 digit, ≥1 symbol). Passphrase mode over bundled EFF Long Wordlist (7776 entries, 2¹³ bits/word) and EFF Short Wordlist 1 (1296 entries) under tree-shakeable `./wordlists/eff-long` and `./wordlists/eff-short` subpaths. Pronounceable Markov-digram CVC mode for memorable shoulder-surfing-friendly contexts. PIN mode (bias-free uniform 0-9). Bias-free `randomInt(rng, max)` via Lemire rejection sampling — never `Math.floor(rng() * max)`. `estimateEntropy(password)` and `estimatePassphraseEntropy(words, wordlistSize)`. Wordlist plugin API — `registerWordlist(name, words[])` with ≥256-entry minimum (`PWGEN.WORDLIST_TOO_SHORT`). `assertStrength(password, minBits)` xkcd-style guard. Injectable `Rng` from `@suaveplan/types` (default wraps `@suaveplan/crypto-utils.randomBytes`). χ² statistical test on 1M draws (p > 0.01 vs uniform). 4-code error registry, Zod boundaries, full OTel surface. 29 src + 21 test + 15 sibling `.md` files at 100% coverage. |
+| `@suaveplan/password-strength` | zxcvbn-style password strength estimator. 6 pattern matchers: frequency-ranked dictionary with l33t-substitution + reverse-string lookup; alphabetical/numeric sequence (with reverse); repeat (`aaaa`, `abcabc`); date (splittable y/m/d, 1900 ≤ year ≤ now+50); keyboard adjacency for QWERTY (default) + DVORAK + AZERTY under tree-shakeable `./graphs/<layout>` subpaths; recent-year regex (`19xx`/`20xx`). `mostGuessableMatchSequence` DP scorer over n² pattern combinations with factorial penalty and bruteforce fallback. `estimateGuesses(match)` per Wheeler §4 formulae. `crackTimes(guesses, { adjustments? })` with 4 scenarios (online_throttling_100_per_hour, online_no_throttling_10_per_second, offline_slow_hashing_1e4_per_second, offline_fast_hashing_1e10_per_second). 5-bucket `score` (literal `0\|1\|2\|3\|4` at 1e3/1e6/1e8/1e10 thresholds). Feedback strings keyed for `@suaveplan/i18n`, English fallback. `loadDictionaries(dicts)` runtime swap (no global mutation), `userInputs` personal-info match surfacing "contains personal info" feedback. Multilingual dictionaries under `./dicts/{de,fr,es,zh-Hans,ru}` subpaths. `assessReactive(observable<string>)` debounced streaming variant with AbortSignal + cancel-on-newer. 200-char DoS guard — input >200 chars rejected with `PWSTRENGTH.INPUT_TOO_LONG`. 6-code error registry, Zod boundaries, full OTel surface. 55 src + 22 test + 31 sibling `.md` files at 100% coverage. |
+| `@suaveplan/noise` | Seeded spatial noise fields for procedural content generation. Provides six field types — Perlin, Simplex (2D/3D/4D), Value, Worley/cellular (F1/F2/F2-F1 modes), fBm (fractal Brownian motion compositor), and Poisson-disk Blue noise sampling — all seeded with Sfc32Rng for byte-identical, reproducible output. Every generator is available as both a functional API and a stateful class. Use this package for terrain heightmaps, texture generation, cloud simulation, vegetation scattering, and any procedural system that needs spatially-coherent randomness. For non-spatial random values (UUIDs, shuffles, distributions) use @suaveplan/random; for seeded integer/float sequences use @suaveplan/pseudo-random. |
+| `@suaveplan/pseudo-random` | Deterministic, seeded pseudo-random number generators (PRNGs) conforming to the Rng interface from @suaveplan/types. Ships four algorithms — Mulberry32, SFC32, Xoshiro256++, and CounterRng — with a unified SeededRng surface that includes nextUint32, nextFloat, skip, at, fork, checkpoint, and restore. Use this package when you need reproducible randomness (procedural generation, game simulations, property tests) or seek O(1) access to arbitrary positions in the sequence. For cryptographically secure randomness use @suaveplan/random (CSPRNG-backed) or @suaveplan/crypto (raw bytes). Utility functions shuffle, sample, choice, and weightedChoice accept any Rng and work with both seeded and crypto-backed sources. |
+| `@suaveplan/random` | High-level cryptographically secure randomness for application use. This is the everyday random package — it wraps the CSPRNG with ergonomic helpers for every common randomness task: unique IDs (randomUUID v4, randomUUIDv7, randomULID, randomNanoid), random strings with eight charset presets, collection utilities (shuffle, choice, sample, weightedChoice), object utilities (randomKey, randomEntry, randomSubset), game primitives (coin, dice, roll), and a full suite of continuous and discrete statistical distributions (Normal, LogNormal, Binomial, Poisson, and eight more). Every function accepts an optional rng?: Rng — omit it for crypto-backed defaults, or pass a SeededRng from @suaveplan/pseudo-random for deterministic tests. Do not confuse with @suaveplan/pseudo-random (seeded, deterministic, for procedural generation) or @suaveplan/crypto (raw cryptographic byte generation). |
+| `@suaveplan/readline` | AsyncGenerator line reader and interactive prompt interface for Node.js streams, file paths, and Web Streams. |
+| `@suaveplan/srp` | SRP-6a (RFC 5054) zero-knowledge password proof. Bundled 2048-bit safe-prime group at root + 1024/1536/3072/4096/6144/8192 under tree-shakeable `./groups/<size>` subpaths (every constant byte-exact to Appendix A). SHA-256 default, SHA-1 legacy opt-in. Client roles: `computeVerifier`, `clientStartHandshake`, `clientFinishHandshake`, `clientVerifyServerProof`. Server roles: `serverStartHandshake`, `serverFinishHandshake`, `serverComputeM2` (split-roundtrip helper). Rejects `A mod N == 0`, `B mod N == 0`, `u == 0` per RFC 5054 §2.5.4 with `SRP.PUBLIC_KEY_INVALID`. Modpow via `@noble/curves/abstract/modular.pow` — banned `BigInt ** BigInt %` pattern audited. Constant-time M1/M2/S compare via `@suaveplan/crypto-utils`. Dual hash backends: `nobleHashBridge` (sync) + `subtleHashBridge` (async with AbortSignal) + `defaultHashBridge` selector throwing `SRP.HASH_UNSUPPORTED` on sync-on-async misuse. `PakeProvider` interface + concrete `srpPakeProvider` for future OPAQUE drop-in. RFC 5054 Appendix B 1024/SHA-1 vectors verified byte-exact for every intermediate (k/x/v/u/S). Locally-derived 2048/SHA-256 fixture via `scripts/generate-srp-vectors.ts`. 1000-triple property test asserts `client.K === server.K`. Added `HashLike` interface to `@suaveplan/types` as cross-package contract. 6-code error registry, Zod boundaries, full OTel surface. 44 src + 25 test + 27 sibling `.md` files at 100% coverage. |
+| `@suaveplan/testbed` | A live demonstration app for every @suaveplan library, running against real services. Each page exercises the actual library API — no stubs, no mocks. |
+| `@suaveplan/testing-integration` | Core integration test infrastructure for Vitest: fixture lifecycle management, health polling, and the global-setup bridge. |
+| `@suaveplan/testing-integration-garage-s3` | Garage S3 v2.0.0 testcontainers fixture for @suaveplan/testing-integration. |
+| `@suaveplan/testing-integration-mailpit` | Mailpit testcontainers fixture + assertMail() helper for @suaveplan/testing-integration. |
+| `@suaveplan/testing-integration-postgres` | PostgreSQL 16 testcontainers fixture for @suaveplan/testing-integration. |
+| `@suaveplan/testing-integration-redis` | Redis 7 testcontainers fixture for @suaveplan/testing-integration. |
+| `@suaveplan/testing-integration-step-ca` | A ServiceFixture for smallstep/step-ca that gives any integration test suite a real, ephemeral certificate authority — root cert, JWK provisioner, and an issueCert() helper that mints leaf certificates on demand. |
+| `@suaveplan/testing-integration-surrealdb` | SurrealDB v3 testcontainers fixture for @suaveplan/testing-integration. |
+| `@suaveplan/testing-integration-typesense` | Typesense 27 testcontainers fixture for @suaveplan/testing-integration. |
+| `@suaveplan/tpm-struct` | Universal-tier TPM 2.0 attestation-structure parser per TCG TPM 2.0 Library Part 2 (r1.59). `parseTpmsAttest(bytes)` covering all 8 `TPM_ST_ATTEST_*` variants (§10.12 + §10.11): magic check `0xff544347` ("TCG\xff" reversed), `qualifiedSigner` (TPM2B_NAME), `extraData` (TPM2B_DATA), `clockInfo`, `firmwareVersion`, `attested` (TPMU_ATTEST union dispatched by type). `parseTpmtPublic(bytes)` per §12.2 covering RSA / ECC / KEYEDHASH / SYMCIPHER with full TPMA_OBJECT bitfield decode (r1.59) and `0 ⇒ 65537` RSA exponent normalization with `rawExponent` preservation. Byte-identical `serializeTpmsAttest` / `serializeTpmtPublic` for fixture authoring. `computeTpmtPublicName(pub, { digest })` per TCG Part 1 §16 with injected `HashLike`. `extraDataMatches(attest, expectedHash, { equal })` per W3C WebAuthn L3 §8.3 step 8 with injected constant-time compare. `TPM_ALG` 35-entry + `TPM_ECC_CURVE` 9-entry frozen registries (§11.1 / §11.2.5). TPM2B length-prefix reader/writer with UINT16-BE bounds enforcement (truncated buffer → `TPM_STRUCT.TRUNCATED`). Debug-only `toDiagnostic` dumper. 10-code error registry, Zod boundaries, full OTel surface (histograms + counters with bounded-enum attributes). Synthetic WebAuthn TPM integration fixture (no real-device byte string available). 31 src + 18 test + 13 sibling `.md` files; 175 tests at 100% coverage. Gates `@suaveplan/webauthn` (TPM attestation format verifier). |
+| `@suaveplan/vault` | Vault orchestration layer for the Vaulted password-manager ecosystem — the domain abstraction sitting above `@suaveplan/crypto-vault`, `@suaveplan/crypto-cipher`, `@suaveplan/bitpacker`, and the Phase-1 `DriveLike` / `DriveSharingLike` / `VaultSyncLike` adapter interfaces. Strict locked → unlocked state machine: `Vault.open(config)` returns a locked handle without touching drive; `unlock(password, secretKey)` runs `crypto-vault` 2SKD → personal keyset → per-vault key, decrypts the drive-backed encrypted SQLite-style container with the manifest as AAD, runs forward-only ledger-tracked migrations against the in-memory state, and instantiates per-unlock module facades; `lock()` drains pending flushes, encrypts the container, atomically writes back through `DriveLike`, zeroizes every key buffer via `crypto-vault.zeroizeAll()`, and returns to locked. On-disk container format is `[bitpacker manifest header][AEAD nonce][AEAD ciphertext = serialised in-memory state][AEAD tag]` with the bitpacker manifest carrying `formatVersion` / `kdfId` / `aeadAlgorithm` / `vaultIdHash` / Argon2id params / `createdAt` / `lastModifiedAt` / `schemaVersion`, and the manifest bytes bound as AEAD AAD so any tamper invalidates the ciphertext (surfaced as `VAULT.DECRYPT_FAILED`, indistinguishable from wrong-password by design). Defence-in-depth field-level encryption: every concealed field on a `VaultItem` is XChaCha20-Poly1305-encrypted with a per-item key derived via `crypto-vault.deriveItemKey(vaultKey, itemId)` and zeroized after use, so even drive-side decryption leaves passwords / PINs / secure notes as ciphertext inside the container. `vault.items` exposes `create` / `get` / `update` / `delete` / `list` / `search` with optimistic concurrency (`version` field, rejects with `VAULT.ITEM_VERSION_CONFLICT` on stale writes), per-mutation vector-clock increment, history append-only ledger, debounced flush back to drive (default 500 ms, `flushDebounceMs` injectable). FTS5-style search runs over a blind-index column (HMAC of plaintext non-concealed values) so search never leaks plaintext. `vault.attachments` (`upload` / `download` / `delete`) streams plaintext through XChaCha20-Poly1305 in 64 KiB chunks under per-attachment keys; ciphertext blobs are stored through `DriveLike.put` / `get` / `delete`. `vault.shares` (`createLink` / `revokeLink`) wraps the per-vault key with a share-specific KEK before delegating to `DriveSharingLike`. `vault.sync` (`pull` / `push` / `sync`) hands the in-memory snapshot + queue to a `VaultSyncLike` mirror of `@suaveplan/vault-sync`'s `SyncEngine`. Frozen `VaultError` registry of 17 codes (lifecycle / item / attachment / share / sync / opaque-handle / drive-failure). Zod schemas at every public boundary including the manifest shape. Safe-by-construction OTel: span per operation, counters, and unlock / flush latency histograms — no password / secret-key / AUK / item content / vault ID / item ID / key material in telemetry. 174 tests across 18 files at 100/100/100/100 coverage; fast-check property suites for item-encryption round-trip, lock idempotency, CRUD-blocked-in-LOCKED, and manifest bitpack/unpack round-trip; integration tests cover wrong-password rejection and drive-blob tamper rejection end-to-end. |
+| `@suaveplan/vault-sync` | Offline-first, end-to-end-encrypted sync engine for vault items in the Vaulted password-manager ecosystem. Domain-specific CRDT merge strategies — `lww` (vector-clock + updatedAt + nodeId + canonical-string tiebreakers for guaranteed commutativity), `append` (causal-order concat with dedupe), `atomic` (concurrent-modification rejection with `MERGE_CONFLICT_UNRESOLVED`) — built on top of `@suaveplan/crdt`. RFC 6902 JSON Patch incremental sync via `@suaveplan/diff` (`diffVaultItems` / `applyPatch`). Vector clocks (`Record<nodeId, counter>` with `increment` / `merge` / `compare` returning `<` / `>` / `==` / `concurrent`). `SyncEngine` class with `pull` / `push` / `sync` operating on in-memory snapshots through an injected `SyncTransport` interface (transport itself is out of scope). `SyncQueue` durable mutation queue with vector-clock ordering, operation collapsing, max-depth backpressure (10,000 ops → `QUEUE_DEPTH_EXCEEDED`), and crypto-safe serialize/deserialize. XChaCha20-Poly1305 E2EE via `@suaveplan/crypto-cipher` — `encryptSyncPayload` / `decryptSyncPayload` with version-tagged AAD, max payload 10 MiB, tamper rejection (`SYNC_PAYLOAD_TAMPERED`) and version-mismatch rejection (`SYNC_PAYLOAD_INVALID_VERSION`). Structured `VaultSyncError` registry covering merge / patch / sync / queue / crypto failures. Safe-by-construction OTel: spans + duration histograms + queue-depth gauge with NO key material, item content, vault IDs, item IDs, or vector-clock values in telemetry. fast-check property suite for merge commutativity, idempotency, patch round-trip, vector-clock monotonicity, queue-serialization equivalence, and payload tamper rejection. |
+| `@suaveplan/webauthn` | W3C WebAuthn L3 client. `register` / `authenticate` over injectable `WebAuthnAdapter` (production binds `globalThis.navigator.credentials`; tests bind a deterministic stub — pattern, not mock). Full authenticator-data parser: 37-byte fixed prefix (`rpIdHash[32]` + `flags[1]` + `signCount[4]`) + optional attested-credential-data (`aaguid[16]` + `credentialIdLength[2]` + `credentialId` + `credentialPublicKey` via `@suaveplan/cbor/cose.decodeCoseKey`) + optional extensions CBOR; flags byte decoded to `userPresent` / `userVerified` / `backupEligible` / `backupState` / `attestedCredentialData` / `extensionsPresent`. All 7 attestation-format verifiers under pluggable `AttestationFormatRegistry`: `none`, `packed` (self + full attestation), `fido-u2f`, `tpm` (via `@suaveplan/tpm-struct` for TPMS_ATTEST + TPMT_PUBLIC parse + `computeTpmtPublicName` match), `android-key` (with KeyDescription extension OID `1.3.6.1.4.1.11129.2.1.17`), `android-safetynet` (via `@suaveplan/jws.compactDecode` JWS verify), `apple` (with nonce extension OID `1.2.840.113635.100.8.2`). X.509 chain validation via `@suaveplan/x509.validateChain`. Signature verify dispatching to `@suaveplan/crypto-curve` (ES256/384/512 + EdDSA) and `@suaveplan/crypto-rsa` (RS256 + PS256). Sign-counter regression detection per W3C §6.1.1 with zero-zero exception. Conditional UI (`authenticate({mediation: "conditional"})`, `isConditionalMediationAvailable`). PRF extension passthrough + result parsing (~32-byte symmetric secret). largeBlob extension passthrough. DOMException → typed error mapping at the boundary — `NotAllowedError` / `InvalidStateError` / `SecurityError` / `AbortError` / `NotSupportedError` never leak raw to caller. Constant-time challenge + rpIdHash compare via `@suaveplan/crypto-utils`. 17-code error registry, Zod boundaries, full OTel surface (5 instruments). 64 impl + 27 test + 24 sibling `.md` + 8 fixture + 3 benchmark files; 317+ tests at 100% coverage. Synthesized-via-real-crypto fixtures for all 7 attestation formats. |
+| `@suaveplan/x509` | RFC 5280 v3 certificate parsing + chain validation. Hand-rolled ASN.1 BER/DER codec for the X.509 subset (TLV / OID / SEQUENCE / SET / INTEGER / BIT STRING / OCTET STRING / UTF8String / PrintableString / IA5String / UTCTime / GeneralizedTime / explicit-tagged context-specific). RFC 7468 PEM framing with all armor labels. TBSCertificate parser per §4.1. Pluggable extension decoder dispatch with `registerExtension(oid, decoder)` + critical-extension enforcement (unknown critical → `X509.CRITICAL_EXTENSION_UNRECOGNIZED`). All 8 standard extension decoders: basic constraints (§4.2.1.9), key usage (§4.2.1.3), extended key usage (§4.2.1.12), SAN (§4.2.2.6 — DNS + IPv4 + IPv6 + URI + email + dirName + rfc822Name), name constraints (§4.2.1.10 with `permittedSubtrees` / `excludedSubtrees` + DNS suffix matching), AKI (§4.2.1.1), SKI (§4.2.1.2), CRL distribution points (§4.2.1.13). `validateChain(leaf, intermediates, trustAnchors, opts)` per §6.1 12-step algorithm with policy tree (`validPolicyTree` initialised to any-policy wildcard, `initialPolicySet`/`initialExplicitPolicy` surfaced on `ValidateChainOptions`). Validity period (UTCTime/GeneralizedTime 2050 boundary per §4.1.2.5.1) with injectable `Clock`. Signature verify dispatching to `@suaveplan/crypto-rsa` (RSA-PKCS1v15-SHA256/384/512 + RSA-PSS) and `@suaveplan/crypto-curve` (ECDSA-P256/384/521 + Ed25519). Self-signed-leaf rejection unless explicit trust anchor. Chain depth bound (default 16). `TrustAnchorStore` with SKI lookup, AKI-then-name fallback, configurable duplicate-SKI policy (`last-wins` default, `first-wins`, `throw`). OCSP responder interface (interface only — fetcher in follow-up). 20-code error registry, Zod boundaries, full OTel surface, AbortSignal threaded throughout. 45 src + 38 test files; 381 tests at 100% coverage. 16 deterministic chain builders under `./__fixtures__` with real RSA/P-256/Ed25519 signatures (synthetic-via-real-crypto, no mocks). Gates `@suaveplan/webauthn` (TPM + android-key + apple attestation verifiers) and `@suaveplan/jws` (`x5c` header validation). |
+| `@suaveplan/types` | Types-only foundation package. Zero runtime code, zero dependencies, zero bundle bytes. Provides the canonical shared interfaces that allow every @suaveplan/ package to accept and return the same shapes without coupling to a concrete implementation: Clock (() => number), IdGenerator (() => string), Rng (seeded random interface), MessageResolver (i18n hook), EventBusLike<TMap> (minimal event-bus contract), LoggerLike (minimal structured-logger contract), and three composable option bundles (CancellableOptions, TraceableOptions, DeterministicOptions). Always import type from this package — it emits nothing at runtime. This is the only @suaveplan/ dependency the testing-infrastructure packages (testing, testing-dom, testing-e2e) are permitted to take, because its build emits no runtime bytes and therefore creates no circular hazard. |