Replace core components
Cheetah separates stable responsibilities from their implementations. This makes it possible to supply product-specific authentication, policy, storage, tracing, routing, history, or platform behavior without forking the framework.
An interface is a replacement seam, not a guarantee that any collection of implementations forms a coherent system.
Begin with responsibility, not technology
Identify the component that already owns the behavior. Improve or replace that component rather than adding a second path around it. For example, tenant-scoped history belongs in the history boundary; duplicating records in an unrelated dispatcher creates two retention and authorization models.
Read the interface, its default implementations, and every caller that relies on behavioral details. Method signatures rarely capture all required semantics. Ordering, idempotency, fencing, exception meanings, lifecycle, notification, and retention can be just as important as input and output types.
Preserve the neighboring contracts
Distributed components often share a coordination domain:
- registry and dispatcher agree on route ownership and runtime identity;
- dispatcher and correlator agree on command and attempt identity;
- ingestion, deduplication, history, notification, and correlation agree on accepted-message ordering and terminal semantics;
- context and browser-window registries agree on assignment and placement ownership;
- all tenant-aware components agree on the effective principal and storage namespace.
Replacing one member can therefore require a compatibility review of the family. A custom history that stores messages correctly but emits no compatible notification can leave waiting readers asleep.
Implement lifecycle explicitly
If a component has start() or stop() behavior, attach it to the host's ordered lifecycle. Do not start a listener before its registry or subscription is ready. On shutdown, stop new traffic, drain or fence in-flight work according to policy, stop consumers, then close shared backing services.
Readiness should describe the role's ability to perform its responsibility. Process liveness alone is not enough for a role whose Redis subscription or storage dependency failed.
Validate tenancy and security properties
Shared-tenancy composition accepts only components whose tenant behavior is known and validated. Satisfying the ordinary interface does not establish isolation. A custom implementation must scope reads, writes, iteration, notification, correlation, cleanup, and administrative access consistently.
The same caution applies to authentication, token signing, payload storage, and audit data. Preserve redaction and fail-closed behavior at every error boundary.
Prove the replacement
Use a bounded conformance suite that covers:
- ordinary success and empty-state behavior;
- duplicate, stale-instance, and out-of-order inputs;
- restart and reconnect where the component owns durable or current state;
- cancellation, timeout, and shutdown while work is in flight;
- cross-process notification and history visibility when distributed;
- tenant isolation and administrative access when shared;
- the maintained end-to-end command proof through the new component.
Document the replacement's persistence, capacity, consistency, and recovery properties next to its configuration. A deployer should not need to inspect source code to learn whether a restart erases correlation or whether a missed signal can be recovered from history.