Feat/fixtures events config versioning

[devfoma]

Closes #118
Closes #116
Closes #113

Summary

This pull request resolves three high-priority infrastructure and platform stability issues for the Trellis API:

1. Local Deterministic Fixture Generator (Trellis API: Add local deterministic fixture generator for contributor testing #118): Adds a seedable pseudo-random fixture generator module and CLI script to produce repeatable datasets across normal, edge, and failure scenarios.
2. Structured Domain Event Schemas with Versioned Consumers (Trellis API: Add structured domain event schema with versioned consumers #116): Implements explicit schema versioning, producer-side payload validation, and consumer fallback mechanisms for domain events.
3. Protocol Configuration Versioning & Compatibility Checks (Trellis API: Add protocol configuration versioning and compatibility checks #113): Introduces semver-based compatibility checking for protocol configurations to fail early on incompatible or deprecated versions.

---

Design Decisions & Tradeoffs

1. Local Deterministic Fixture Generator (#118)

• PRNG Engine: Implemented SeededRandom using a Mulberry32 PRNG algorithm. This guarantees 100% stable, identical output across different environments when given the same seed (e.g. --seed=42).
• Core Scenarios: Created 5 distinct test scenarios:
  • STANDARD_USER: Valid user, clean state, active Stellar balance.
  • HIGH_VOLUME_OPERATOR: Institutional operator with high transaction throughput and rate-limit edge states.
  • CORRUPT_PAYLOAD: Malformed input modeling invalid field types and schema validation errors.
  • AUTH_EXPIRED_OR_INVALID: Unauthorized state modeling expired JWT tokens and signature mismatches.
  • UNINDEXED_OR_BOUNDARY_STATE: Edge state with boundary values (MAX_SAFE_INTEGER balance) and lagging indexer blocks.
• Tradeoff: Used a lightweight custom Mulberry32 PRNG rather than heavy external random seed libraries to minimize external dependencies.

2. Structured Domain Event Schemas (#116)

• Producer-Side Validation: DomainEventProducer validates all event payloads against the DomainEventRegistry prior to dispatch, throwing DomainEventValidationError if mandatory fields are missing or types mismatch.
• Explicit Schema Versioning: Enforces schemaVersion on all DomainEventEnvelope payloads.
• Versioned & Fallback Consumers: VersionedDomainEventConsumer dispatches events to registered version handlers. If a specific version handler is missing, it falls back to registered fallback handlers or throws UnknownEventVersionError.
• Tradeoff: Schema registration is currently maintained in code via the registry singleton, keeping event validation fast without needing dynamic JSON schema compilation at runtime.

3. Protocol Configuration Versioning (#113)

• Compatibility Validation: Utilizes semver range evaluation (minSupportedVersion to maxSupportedVersion) via validateProtocolConfig and assertProtocolCompatibility.
• Early Failure: Incompatible versions (below minimum, deprecated, or future unsupported major versions) throw IncompatibleProtocolVersionError immediately prior to executing dependent operations.
• Tradeoff: Version boundaries are declared as constants with override capabilities for custom deployments.

---

Test Results & Output

All 3 automated test suites (15 total tests) pass cleanly:

PASS src/common/events/domain-event-schema.spec.ts
  Structured Domain Event Schema with Versioned Consumers (#116)
    √ should validate and publish a valid domain event with explicit schema version
    √ should reject event publishing when missing a required payload field (producer-side validation)
    √ should handle unknown version with UnknownEventVersionError
    √ should invoke exact version handler when available
    √ should fallback to consumer fallback handler when specific version handler is missing

PASS src/config/protocol-config-versioning.spec.ts
  Protocol Configuration Versioning & Compatibility Checks (#113)
    √ should validate current version successfully without warnings
    √ should validate old-compatible version within supported range
    √ should fail early with clear error for old-incompatible version below minSupportedVersion
    √ should fail early with clear error for future-unknown version exceeding maxSupportedVersion
    √ should fail early for deprecated versions
    √ should throw for invalid semver strings

PASS src/testing/fixtures/fixture-generator.spec.ts
  Local Deterministic Fixture Generator (#118)
    √ should generate stable deterministic output for the same seed across multiple runs
    √ should generate different outputs for different seeds
    √ should cover all five core scenarios
    √ should produce valid PRNG values using SeededRandom

Test Suites: 3 passed, 3 total
Tests:       15 passed, 15 total

[github-actions]

Code Review & Auto-Merge — @dorismaduegbunam 🚀

Thank you @devfoma for your contribution!

• PR Title: Feat/fixtures events config versioning
• Author: @devfoma
• Branch: feat/fixtures-events-config-versioning -> main
• Linked Issues: Closes Trellis API: Add local deterministic fixture generator for contributor testing #118, Closes Trellis API: Add structured domain event schema with versioned consumers #116, Closes Trellis API: Add protocol configuration versioning and compatibility checks #113
• Status: Approved & Merged into main.

Verified code changes and repository requirements. Merging pull request.