Initial Commit

openspec/archive/2026-04-24-enterprise-events-schema/proposal.md

@@ -0,0 +1,225 @@
+# OpenSpec Change: enterprise-events-schema
+
+- **Change ID**: enterprise-events-schema
+- **Package**: `@suaveplan/events-schema`
+- **Category**: universal
+- **Target path**: `universal/events/events-schema`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/events-schema.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/events-schema` on the genesis branch from scratch at enterprise quality. The package is a runtime schema-validation companion for `@suaveplan/events`: it validates event envelopes and payloads at publish and subscribe boundaries against Zod schemas registered in `@suaveplan/schema-registry`, surfaces structured rejections with redacted field values, and supports three validation modes (strict, warn, sample) for production rollout. Attaches via the public `@suaveplan/events` interceptor API.
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — fresh build. No prior source, no test results, no coverage data.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/events` (`workspace:^`) | Event bus and interceptor API |
+| `@suaveplan/schema-registry` (`workspace:^`) | Schema registration, version history, compatibility checking |
+| `@suaveplan/error` (`workspace:^`) | Base class for `EventsSchemaError`; `defineCodes` for `EVENTS_SCHEMA.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `Rng` injection interfaces |
+| `zod` (`catalog:forms`) | Zod schemas for event envelope contract and option types |
+| `@opentelemetry/api` (`catalog:observability`) | Rejection counters, validation latency histograms |
+| `tslib` (`catalog:build`) | Runtime helpers |
+
+Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
+
+---
+
+## Public API surface
+
+### Setup
+
+```ts
+// Attaches schema-validation companion to an existing EventBus
+function attachEventSchemas(bus: EventBusLike, options?: EventSchemasOptions): EventSchemasHandle
+
+interface EventSchemasOptions {
+  registry?: SchemaRegistry             // default: global registry
+  mode?: ValidationMode                 // default: "strict"
+  sampleRate?: number                   // used when mode === "sample"; 0.0–1.0
+  onRejection?: RejectionHandler
+  redactSensitive?: boolean             // default: true
+  clock?: Clock
+  rng?: Rng
+  logger?: LoggerLike
+}
+
+type ValidationMode = "strict" | "warn" | "sample"
+
+type RejectionHandler = (rejection: ValidationRejection) => void
+
+interface EventSchemasHandle {
+  detach(): void
+  registerSchema(eventName: string, schema: ZodSchema, version?: string): void
+  stats(): SchemaValidationStats
+}
+```
+
+### Schema registration
+
+```ts
+// Register a Zod schema for an event name (standalone, outside attachEventSchemas)
+function registerEventSchema(
+  registry: SchemaRegistry,
+  eventName: string,
+  schema: ZodSchema,
+  options?: SchemaRegistrationOptions
+): void
+
+interface SchemaRegistrationOptions {
+  version?: string        // default: "1.0.0"
+  description?: string
+  compatibility?: "BACKWARD" | "FORWARD" | "FULL" | "NONE"
+}
+```
+
+### Validation result
+
+```ts
+interface ValidationRejection {
+  eventName: string
+  eventId?: string
+  payload: unknown
+  errors: ValidationError[]
+  mode: ValidationMode
+  timestamp: Date
+}
+
+interface ValidationError {
+  path: string
+  message: string
+  expected?: string
+  received?: string        // redacted if field is marked @sensitive
+}
+```
+
+### Stats
+
+```ts
+interface SchemaValidationStats {
+  validationsTotal: Record<string, number>   // keyed by event.name
+  rejectionsTotal: Record<string, number>
+  avgValidationMs: Record<string, number>
+  unknownSchemaTotal: number
+}
+```
+
+### Error handling
+
+```ts
+class EventsSchemaError extends SuaveplanError<EventsSchemaErrorCode>
+
+type EventsSchemaErrorCode =
+  | "EVENTS_SCHEMA_VALIDATION_FAILED"
+  | "EVENTS_SCHEMA_UNKNOWN"
+  | "EVENTS_SCHEMA_COMPATIBILITY_BREAK"
+  | "EVENTS_SCHEMA_ATTACH_FAILED"
+
+function registerEventsSchemaErrorCodes(): void
+```
+
+### Zod schemas
+
+```ts
+const EventSchemasOptionsSchema: ZodSchema
+const ValidationRejectionSchema: ZodSchema
+const SchemaRegistrationOptionsSchema: ZodSchema
+```
+
+---
+
+## New additions for genesis
+
+### 1. Three validation modes
+
+- `"strict"` — reject the dispatch and throw `EventsSchemaError` if validation fails
+- `"warn"` — log the rejection via `LoggerLike` but let the event through; useful for canary rollouts
+- `"sample"` — validate a random `sampleRate` fraction of events; the rest pass-through unchecked; useful for high-volume events where full validation is too expensive
+
+### 2. Sensitive field redaction
+
+When `redactSensitive: true`, field values that fail validation are replaced with `"[REDACTED]"` in the `ValidationError.received` output. Fields are marked sensitive via a Zod `.meta({ sensitive: true })` convention.
+
+### 3. Schema compatibility CI hook
+
+`EventSchemasHandle.registerSchema` calls `registry.checkCompatibility` under the hood. An incompatible schema registration throws `EventsSchemaError("EVENTS_SCHEMA_COMPATIBILITY_BREAK")` synchronously.
+
+### 4. OTel instrumentation
+
+- Counter: `events_schema.validations_total` (attribute: `event.name`, `validation.result: "pass"|"fail"`)
+- Counter: `events_schema.unknown_schema_total`
+- Histogram: `events_schema.validation_duration_ms` (attribute: `event.name`)
+
+### 5. Property-based tests (fast-check)
+
+- Schema round-trip: valid payloads generated by the schema always pass validation
+- Rejection completeness: every field-level Zod error surfaces as a `ValidationError` entry
+- Mode behaviour: `"warn"` mode never throws; `"strict"` always throws on invalid payloads; `"sample"` at 0.0 never validates
+- Compatibility check: re-registering a schema with a removed required field always throws under `BACKWARD` compatibility
+
+---
+
+## File layout
+
+```text
+universal/events/events-schema/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/
+      index.ts
+    core/
+      attach-event-schemas/
+        attach-event-schemas.ts
+        attach-event-schemas.md
+        attach-event-schemas.types.ts
+        attach-event-schemas.test.ts
+        index.ts
+    schema/
+      register-event-schema/
+        register-event-schema.ts
+        register-event-schema.md
+        register-event-schema.test.ts
+        index.ts
+    validation/
+      validator/
+        validator.ts
+        validator.md
+        validator.types.ts
+        validator.test.ts
+        index.ts
+      redaction/
+        redaction.ts
+        redaction.md
+        redaction.test.ts
+        index.ts
+  tests/
+    integration.test.ts
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream packages**: any event-driven application needing runtime contract enforcement without deploying a separate message broker schema registry. Works alongside `@suaveplan/events-otel` and `@suaveplan/events-metrics`.
+
+**Workspace dep prerequisites**: `@suaveplan/events`, `@suaveplan/schema-registry`, `@suaveplan/error`, `@suaveplan/types` must be published to Verdaccio.
+
+**Breaking changes**: none (new package).