# OpenSpec Change: enterprise-schema-registry

- **Change ID**: enterprise-schema-registry
- **Package**: `@suaveplan/schema-registry`
- **Category**: universal
- **Target path**: `universal/validation/schema-registry`
- **Status**: PROPOSED
- **Date**: 2026-04-19
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/schema-registry.md`

## Summary

Greenfield rebuild of `@suaveplan/schema-registry` — Kafka-/Confluent-style schema registry. Stores versioned schemas per subject, runs backward/forward/full compatibility checks, emits structured diffs, and exposes pluggable stores (in-memory + database adapter). Used by event-sourcing, api contracts, and future `utils` package.

## Current-state audit (genesis)

Package does not exist yet — fresh build.

## Dependencies

- Workspace: `@suaveplan/error`, `@suaveplan/types`
- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`
- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`

## Preserved public surface

### Registry

- `SchemaRegistry`, `createSchemaRegistry`, `SchemaRegistryConfig`
- `createSchemaIncompatibleError`, `SchemaCompatibilityError`

### Versioning / store

- `createSchemaVersion`, `MemorySchemaStore`, `DatabaseSchemaStore`, `resolveCompatibility`

### Compatibility

- `checkCompatibility`, `checkTransitiveCompatibility`
- `buildTransitiveReport`, `checkTransitiveAgainstAll`, `isTransitiveMode`, `stripTransitive`, `TransitiveReport`, `TransitiveVersionResult`

### Diff

- `diffSchemas`, `formatDiffReport`

### Utils / constants

- `canonicalizeSchema`, `computeFingerprint`, `djb2Hash`, `flattenFields`, `isOptionalOrHasDefault`
- `DEFAULT_COMPATIBILITY`, `DEFAULT_MAX_VERSIONS`

### Types / error codes

`CompatibilityMode`, `CompatibilityResult`, `DatabaseAdapter`, `DiffChangeType`, `LookupOptions`, `RegisterOptions`, `SchemaDefinition`, `SchemaDiffChange`, `SchemaDiffResult`, `SchemaField`, `SchemaStoreAdapter`, `SchemaType`, `SchemaVersion`, `SubjectConfig`, `SchemaRegistryErrorCode`, `registerSchemaRegistryErrorCodes`, `SCHEMA_REGISTRY_ERROR_METADATA`.

## New genesis additions

- Codes via `defineCodes`: `SCHEMA_REGISTRY.SUBJECT_NOT_FOUND`, `SCHEMA_REGISTRY.VERSION_NOT_FOUND`, `SCHEMA_REGISTRY.INCOMPATIBLE`, `SCHEMA_REGISTRY.STORE_ERROR`, `SCHEMA_REGISTRY.INVALID_SCHEMA`.
- OTel counters `schema_registry.register.total`, `schema_registry.incompatible.total`; histogram `schema_registry.compatibility.duration_ms`.
- Property tests: registering the same canonicalised schema twice returns the same version; compatibility transitivity across N versions.

## Impact

- Adds one new package: `universal/validation/schema-registry`
- Adds one new spec capability: `schema-registry`
- Unblocks `utils` (which currently depends on schema-registry on main).