This chapter defines the planned engineering improvements required to keep Coyote3 maintainable, auditable, and predictable as scope grows.
The roadmap exists to reduce risk in three areas:
Coyote3 currently carries debt in the following areas.
Interpretation state remains partly mutable at case level. This is practical for active work but can make historical reconstruction harder if report-linked context is not treated as the source of truth.
Annotation data includes both older and newer scope models. The application handles this correctly, but mixed structure increases matching complexity and maintenance cost.
Some blueprint modules still carry orchestration and business rules together. This slows feature delivery, complicates testing, and increases regression risk.
Configuration versioning exists, but critical runtime paths still depend primarily on mutable “current” records rather than immutable version references.
The target state is:
The goal is to ensure every saved report can be reconstructed exactly from stored context.
Current reported_variants behavior is already the foundation. The next step is to persist complete report context metadata together with report identity, including resolved configuration identity and effective filters used at generation time.
Outcome: report-time truth becomes independent of future sample/filter/config changes.
Configuration should evolve through explicit versions, with clear distinction between active version and historical versions.
Recommended model:
Outcome: rollback, audit, and release reproducibility become operationally safe and simple.
Annotation records should converge on a single deterministic identity-and-scope contract.
Required direction:
Migration should preserve legacy compatibility while moving matching logic to strict-scope-first with controlled fallback behavior.
Outcome: predictable matching behavior, easier debugging, and lower maintenance complexity.
Business orchestration should move from large route modules into dedicated services.
Primary extraction targets:
Outcome: smaller route handlers, clearer responsibilities, easier test onboarding, and lower change risk.
Core hardening tasks:
Outcome: fewer production surprises and faster operational troubleshooting.
Priority order:
This roadmap is complete when: