# 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`.