Initial Commit

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

@@ -0,0 +1,41 @@
+# Proposal: enterprise-json
+
+## Summary
+
+Add `@suaveplan/json` to `universal/data/json` — a safe, enterprise-grade JSON
+utility package with prototype-pollution protection, circular-reference
+detection, and OTel instrumentation.
+
+## Motivation
+
+Raw `JSON.parse` / `JSON.stringify` calls are littered across application code
+with no shared protection against:
+
+- **Prototype pollution** — keys like `__proto__`, `constructor`, `prototype`
+  can silently mutate the prototype chain.
+- **Circular references** — `JSON.stringify` throws an unformatted error that
+  leaks internal stack frames.
+- **Untyped failures** — errors from `JSON.parse` are unstructured `SyntaxError`
+  instances with no stable code or OTel trace attachment.
+
+## What ships
+
+| Export        | Description                                                       |
+|---------------|-------------------------------------------------------------------|
+| `safeParse`   | `JSON.parse` with forbidden-key reviver + structured `JsonError`  |
+| `safeStringify` | `JSON.stringify` with circular-ref detection + structured error |
+| `tryParse`    | `safeParse` wrapped in try/catch → returns `undefined` on failure |
+| `isValidJSON` | Boolean validity check (handles `null` literal correctly)         |
+| `getStringifySize` | UTF-8 byte size of the JSON representation                  |
+
+## Non-goals
+
+- Full JSON5 / JSONC support (separate package if needed).
+- Schema validation (use `zod` directly or `@suaveplan/validation`).
+
+## Acceptance criteria
+
+- 100% Istanbul coverage on all 4 thresholds.
+- 100% docs coverage (`bun run docs:check`).
+- Green `bunx turbo lint typecheck test --filter=@suaveplan/json`.
+- Published to Verdaccio at `0.1.0`.