Initial Commit

openspec/specs/json/spec.md

@@ -0,0 +1,38 @@
+# json
+
+## Purpose
+
+Safe JSON parse/stringify surface for the Suaveplan monorepo. Wraps the platform `JSON` global with prototype-pollution defense, AbortSignal handling, structured `JsonError` codes registered under the `JSON.*` namespace, OpenTelemetry spans, and a `tryParse` / `isValidJSON` / `getStringifySize` ergonomic layer that the platform global does not provide.
+
+**Package path:** `universal/data/json`
+**Landed:** 2026-04-20
+
+## Requirements
+
+- **R1** The package MUST expose `safeParse<T>(text, options?)` that parses JSON
+  and throws `JsonError(PARSE.FAILED)` on invalid syntax.
+- **R2** `safeParse` MUST reject keys in the `forbiddenKeys` list (default:
+  `__proto__`, `constructor`, `prototype`) with `JsonError(PARSE.PROTOTYPE_POLLUTION)`.
+- **R3** `safeParse` MUST accept an `AbortSignal` and throw `JsonError(PARSE.FAILED)`
+  when the signal is already aborted before parsing begins.
+- **R4** The package MUST expose `safeStringify(value, options?)` that stringifies
+  and throws `JsonError(STRINGIFY.CIRCULAR)` on circular references.
+- **R5** `safeStringify` MUST allow DAG sharing (same object at multiple
+  non-cyclic paths) without throwing.
+- **R6** `safeStringify` MUST accept an `AbortSignal` and throw
+  `JsonError(STRINGIFY.FAILED)` when the signal is already aborted.
+- **R7** `safeStringify` MUST throw `JsonError(STRINGIFY.FAILED)` for any
+  non-circular, non-`JsonError` exception from `JSON.stringify` (e.g. `BigInt`).
+- **R8** The package MUST expose `tryParse<T>(text, options?)` that returns
+  `undefined` instead of throwing.
+- **R9** The package MUST expose `isValidJSON(text)` that returns `true` for the
+  `"null"` literal (not `false` as a naïve `tryParse() !== undefined` check
+  would yield).
+- **R10** The package MUST expose `getStringifySize(value)` returning UTF-8
+  byte length of `JSON.stringify(value)`.
+- **R11** `safeParse` and `safeStringify` MUST emit OpenTelemetry spans via
+  `@opentelemetry/api`.
+- **R12** All error codes MUST be registered under the `JSON.*` namespace via
+  `defineCodes` from `@suaveplan/error`.
+- **R13** Istanbul coverage on all 4 thresholds: 100%.
+- **R14** Docs coverage: 100%.