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

Tasks: enterprise-events-schema

• Change ID: enterprise-events-schema
• Package: @suaveplan/events-schema
• Date: 2026-04-24

Prerequisites (must be published to Verdaccio first)

• @suaveplan/events
• @suaveplan/schema-registry
• @suaveplan/error
• @suaveplan/types

Tasks

1. Scaffold package

• Create universal/events/events-schema/ directory tree per file layout in proposal.md
• Write package.json (name @suaveplan/events-schema, version 0.1.0, sideEffects: false, correct workspace deps and catalog externals)
• Write tsconfig.json extending @suaveplan/typescript-config/library.json
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config

2. Error codes (src/error-codes.ts)

• Define EventsSchemaErrorCode union type
• Call defineCodes to register all EVENTS_SCHEMA.* codes
• Export registerEventsSchemaErrorCodes() and EventsSchemaError

3. Types (src/types/common.ts)

• Define and export EventSchemasOptions, EventSchemasHandle, ValidationMode, RejectionHandler, ValidationRejection, ValidationError, SchemaValidationStats, SchemaRegistrationOptions
• Write common.md

4. Sensitive field redaction (src/validation/redaction/)

• Implement redaction logic: scan ZodError issues for paths, mask .received values when field schema carries .meta({ sensitive: true })
• Write .md, .test.ts, index.ts

5. Validator (src/validation/validator/)

• Implement validation logic for strict, warn, and sample modes
• Inject rng for sample-rate decisions
• Apply redaction before constructing ValidationError entries
• Write .md, .types.ts, .test.ts, index.ts

6. Schema registration helper (src/schema/register-event-schema/)

• Implement registerEventSchema(registry, eventName, schema, options?) that calls registry.checkCompatibility before registering
• Throw EventsSchemaError("EVENTS_SCHEMA_COMPATIBILITY_BREAK") on incompatible change
• Write .md, .test.ts, index.ts

7. Core attachEventSchemas (src/core/attach-event-schemas/)

• Implement attachEventSchemas(bus, options?) via @suaveplan/events interceptor API only
• Validate payload against registered schema on each dispatch using configured mode
• Accumulate SchemaValidationStats
• Emit OTel counters and histogram per proposal.md §4
• Return EventSchemasHandle with detach(), registerSchema(), stats()
• Write .md, .types.ts, .test.ts, index.ts

8. Tests

• Unit tests co-located (100% coverage target)
• tests/integration.test.ts — attach to real EventBus, register schema, dispatch valid and invalid payloads, assert rejection counts and mode behaviour
• tests/property.test.ts — fast-check properties per proposal.md §5

9. Docs

• Every .ts implementation file has a sibling .md
• Root README.md

10. Pre-publish gate

• bunx turbo lint typecheck test --filter=@suaveplan/events-schema green
• bunx turbo test:coverage --filter=@suaveplan/events-schema ≥ 100% on touched modules

11. Publish

• bun scripts/publish.ts --package @suaveplan/events-schema

12. Archive

• Fold spec delta into openspec/specs/events/spec.md
• mv openspec/changes/enterprise-events-schema openspec/archive/2026-04-24-enterprise-events-schema