Initial Commit

openspec/archive/2026-04-20-enterprise-utils/proposal.md

@@ -0,0 +1,30 @@
+# Proposal: @suaveplan/utils — Universal Utility Library
+
+## Change ID
+`enterprise-utils`
+
+## Status
+Shipped
+
+## Summary
+Introduce `@suaveplan/utils` as a comprehensive universal utility library under `universal/data/utils`. This package provides commonly needed utilities: debug logging with deduplication, object manipulation (deep merge, clone, pick/omit, nested path access), platform detection (Node/Browser/Bun), float encoding utilities (Float16/32/64 pack/unpack), and pseudo-random array selection.
+
+## Motivation
+Shared utility functions currently duplicated across packages. Centralizing them in a single well-tested package reduces redundancy, increases reuse, and ensures consistent error handling with OTel instrumentation.
+
+## Scope (Part 1)
+- `debug`: Circular-buffer deduplication logger
+- `object`: 15 object manipulation utilities with OTel spans
+- `platform`: Injectable platform adapter with Node/Browser/Bun detection
+- `number`: Float16/32/64 pack/unpack with DataView
+- `random`: Deterministic pseudo-random array selection
+
+## Part 2 (follow-on)
+- `email`, `sound`, `string`, `validate`, `validation` modules
+
+## Dependencies
+- `@suaveplan/error` — error substrate
+- `@suaveplan/types` — shared type interfaces
+- `@opentelemetry/api` — observability
+- `zod` — schema validation
+- `tslib` — TypeScript helpers