The Composition Root Pattern: Eliminating Startup Duplication Between Production and Certification
VANI resolved duplicated startup logic between production execution and certification by introducing a single Application Composition Root that both paths use — discovered as an improvement during Phase 0 implementation.
- Reference
- V013
- Project
- VANI
- Status
- Completed — Phase 0
- Evidence
- high
- Source
- 013-composition-root-pattern.md
Context
When a certification system (or test system) needs to construct and start the same application as production, but through a separate code path, you get two problems: duplication of startup logic, and divergence over time (the certification path doesn't reflect changes made to the production path, or vice versa).
The Composition Root pattern solves this by centralizing construction in one place.
The Question
How should a system that has both production execution and a certification system construct the same application without duplicating startup logic?
What Happened
From docs/phases/phase0/LESSONS_LEARNED.md:
"Introducing a dedicated Application Composition Root removed duplicated startup logic between production execution and certification. Both production and certification now construct the operating system through the same application entry point, reducing maintenance overhead. Future execution paths should continue using the same composition root."
From docs/phases/phase0/IMPLEMENTATION_REPORT.md, Version 0.10.0 (Application Layer):
"The Application became the single production entry point used by both runtime execution and certification."
The StandardApplication class was implemented with:
- Application contracts
- Bootstrap integration
- Runtime startup
- Runtime shutdown
Both certifications/main.py (certification entry point) and the production runtime use StandardApplication to construct the Cognitive Operating System.
Evidence
docs/phases/phase0/LESSONS_LEARNED.md— Composition Root lesson (explicit text)docs/phases/phase0/IMPLEMENTATION_REPORT.md— Application Layer section (Version 0.10.0)docs/phases/phase0/CHANGELOG.md— Version 0.10.0 "Application Layer" additionssrc/application/— Application source directory (containsStandardApplication)docs/phases/phase0/CERTIFICATION.md— Certification execution section:python certifications/main.py
Diagnosis
Established: The Composition Root was introduced as a solution to a duplication problem discovered during Phase 0. The lessons learned document records it explicitly as a discovery.
Established: Both production and certification use the same entry point. This is confirmed in the lessons learned document and corroborated by the certification execution command in the certification report.
Established: This was implemented in Version 0.10.0 (second to last version) — meaning it was discovered late in Phase 0 development, not designed upfront. The problem of startup duplication was encountered and then solved.
Observation: The Composition Root pattern is a well-known pattern in dependency injection literature (Mark Seemann's "Dependency Injection in .NET" describes it). Its discovery here was organic — derived from the specific need to avoid duplicated startup logic between production and certification.
What Changed
The Application Composition Root was introduced in Version 0.10.0. Prior to this, the certification and production paths likely constructed the system independently. After this, both use StandardApplication.
What I Learned
When you have both a production system and a validation system (certification, integration tests) that need to construct the same application, the construction logic must be centralized. If it's not, changes to the production startup path won't automatically apply to the validation path — and you'll eventually have validation that doesn't actually validate what production does.
The organic discovery of this lesson (late in Phase 0) confirms that it's a real problem encountered in practice, not a theoretical concern.
Broader Principle
Any application that is both deployed and tested needs a single place where its dependencies are assembled. This "composition root" is the only place in the codebase where concrete implementations are assigned to abstract contracts. Moving this logic out of production-only code into a shared location allows both production and test/certification contexts to use the same construction path, preventing divergence.
Technical References
docs/phases/phase0/LESSONS_LEARNED.md— Composition Root lessondocs/phases/phase0/CHANGELOG.md— Version 0.10.0docs/phases/phase0/IMPLEMENTATION_REPORT.md— Application Layer sectionsrc/application/— StandardApplication source
Failure sequence
On the record- Attempt
- How should a system that has both production execution and a certification system construct the same application without duplicating startup logic?
- Failure
- From `docs/phases/phase0/LESSONS_LEARNED.md`: > "Introducing a dedicated Application Composition Root removed duplicated startup logic between production execution and certification. Both production and certification now construct the operating system through the same application entry point, reducing maintenance overhead. Future execution paths should continue using the same composition root." From `docs/phases/phase0/IMPLEMENTATION_REPORT.md`, Version 0.10.0 (Application Layer): > "The Application became the single production entry point used by both runtime execution and certification." The `StandardApplication` class was implemented with: - Application contracts - Bootstrap integration - Runtime startup - Runtime shutdown Both `certifications/main.py` (certification entry point) and the production runtime use `StandardApplication` to construct the Cognitive Operating System.
- Diagnosis
- **Established:** The Composition Root was introduced as a solution to a duplication problem discovered during Phase 0. The lessons learned document records it explicitly as a discovery. **Established:** Both production and certification use the same entry point. This is confirmed in the lessons learned document and corroborated by the certification execution command in the certification report. **Established:** This was implemented in Version 0.10.0 (second to last version) — meaning it was discovered late in Phase 0 development, not designed upfront. The problem of startup duplication was encountered and then solved. **Observation:** The Composition Root pattern is a well-known pattern in dependency injection literature (Mark Seemann's "Dependency Injection in .NET" describes it). Its discovery here was organic — derived from the specific need to avoid duplicated startup logic between production and certification.
- Lesson
- When you have both a production system and a validation system (certification, integration tests) that need to construct the same application, the construction logic must be centralized. If it's not, changes to the production startup path won't automatically apply to the validation path — and you'll eventually have validation that doesn't actually validate what production does. The organic discovery of this lesson (late in Phase 0) confirms that it's a real problem encountered in practice, not a theoretical concern.
- Next iteration
- The Application Composition Root was introduced in Version 0.10.0. Prior to this, the certification and production paths likely constructed the system independently. After this, both use `StandardApplication`.