# Capability Spec: schema-registry

**Package**: `@suaveplan/schema-registry`
**Version**: 0.0.0 (genesis)
**Status**: ADDED

---

## ADDED Requirements

### SR-01 — Subject + version model

A subject MUST carry `SubjectConfig` and a sequence of `SchemaVersion { id, subject, version, schema, fingerprint, createdAt }`. `version` MUST be monotonic starting at `1`. `fingerprint` MUST be stable over canonicalised schema output.

### SR-02 — Canonicalisation

`canonicalizeSchema(schema)` MUST produce a deterministic, lexically sorted representation such that semantically identical schemas yield identical canonical output. `computeFingerprint(schema)` MUST hash the canonical form. `djb2Hash` MUST be a reference 32-bit DJB2 implementation.

### SR-03 — Compatibility modes

`CompatibilityMode` MUST include `'none' | 'backward' | 'backward-transitive' | 'forward' | 'forward-transitive' | 'full' | 'full-transitive'`. `checkCompatibility(current, candidate, mode)` MUST return `CompatibilityResult { compatible, violations }`. `checkTransitiveCompatibility(history, candidate, mode)` MUST evaluate against every prior version per the transitive mode.

### SR-04 — Register contract

`SchemaRegistry.register(subject, schema, options?)` MUST canonicalise, compute a fingerprint, look up an existing version by fingerprint, and reuse it if found. Otherwise it MUST check compatibility against the latest (or full history if transitive) and either persist a new version or throw `SchemaCompatibilityError` with code `SCHEMA_REGISTRY.INCOMPATIBLE`.

### SR-05 — Lookup

`get(subject, version?)` MUST return the latest version when `version` is omitted. `getByFingerprint(subject, fingerprint)` MUST be supported. Unknown subject MUST throw `SCHEMA_REGISTRY.SUBJECT_NOT_FOUND`; unknown version MUST throw `SCHEMA_REGISTRY.VERSION_NOT_FOUND`.

### SR-06 — Store contract

`SchemaStoreAdapter` MUST provide `list`, `put`, `get`, `getLatest`, `delete`. `MemorySchemaStore` MUST implement it synchronously; `DatabaseSchemaStore` MUST accept a `DatabaseAdapter` for durable storage. Both MUST pass the same contract test suite.

### SR-07 — Diff

`diffSchemas(prev, next)` MUST return `SchemaDiffResult` listing `SchemaDiffChange` entries (`added | removed | modified | type-changed | optionality-changed`). `formatDiffReport` MUST produce a human-readable Markdown summary.

### SR-08 — Observability

Every register / compatibility / diff call MUST record its corresponding OTel metric; incompatible registrations MUST increment `schema_registry.incompatible.total{subject, mode}`.