The Moira Subsystem Constitutional Process is the canonical method by which a computational subsystem is transformed into a governed backend domain.
It is not a stylistic checklist. It is a directed sequence of epistemological dependencies. Each phase becomes possible only because earlier phases have made its claims knowable, testable, and stable.
This document is intended to be the first doctrine document in moira/docs
because it explains why the backend standards, validation codices, and public
API freezes exist, and why they were built in the order they were built.
A subsystem is constitutionalized when:
The output of constitutional process is not merely “working code.” The output is a backend subsystem with constitutional order.
Moira does not treat backend maturity as “feature complete.” It treats backend maturity as the point at which:
Without constitutional process, a subsystem can appear complete while remaining epistemically weak: hard to inspect, easy to misuse, difficult to validate, and impossible to freeze without ambiguity.
The constitutional phase order is not arbitrary.
It is a directed acyclic graph of epistemological dependencies expressed as a phase sequence.
This means:
Examples:
The sequence is linear in execution, but the reason for the sequence is the DAG of dependency beneath it.
The following terms are normative in constitutional process:
| Term | Meaning |
|---|---|
| computational core | the authoritative engine that performs the actual domain computation |
| truth preservation | additive preservation of doctrinal/computational facts already computed by the core |
| classification | typed descriptive structure over preserved truth |
| inspectability | derived convenience access that exposes already-known truth more clearly |
| policy | explicit control over admitted doctrine already supported by the engine |
| formalization | turning implicit relational logic into explicit result vessels |
| integration | combining existing local truths into a coherent higher-order profile |
| aggregate intelligence | chart-wide or subsystem-wide summaries derived from local integrated truth |
| network intelligence | structural graph projection over already-formalized relations |
| hardening | explicit invariants, failure behavior, determinism, and misuse resistance |
| constitution | the written backend standard and validation codex that freezes the subsystem |
| public API curation | deliberate exposure of the stable surface while keeping helpers internal |
constitutional process currently consists of twelve phases.
Purpose: Preserve richer doctrinal and computational truth from the authoritative core without changing semantics.
Dependency: Requires a real computational core to already exist.
Without it: Later layers must reconstruct hidden logic from flattened labels or scores.
Purpose: Add typed descriptive structure to preserved truth.
Dependency: Requires structured truth to already exist.
Without it: Classification would either be lossy, invented, or forced to classify legacy flattened outputs directly.
Purpose: Expose derived convenience views and harden vessel consistency.
Dependency: Requires preserved truth and classification to already exist.
Without it: Inspectability helpers either duplicate logic or expose unstable half-formed concepts.
Purpose: Make doctrinal choices explicit and governable without changing default behavior.
Dependency: Requires the existing doctrine to be observable in preserved truth and classification.
Without it: Policy becomes speculative and disconnected from the engine it claims to govern.
Purpose: Turn previously implicit relational logic into explicit backend result vessels.
Dependency: Requires policy-bounded local truth to already exist.
Without it: Relations are inferred ad hoc instead of derived from authoritative doctrine.
Purpose: Harden the newly formalized relation layer and distinguish detected, admitted, and scored subsets explicitly.
Dependency: Requires a formal relation layer to already exist.
Without it: Cross-layer consistency involving relations cannot be stated clearly.
Purpose: Integrate per-entity truth into a coherent local condition profile.
Dependency: Requires preserved, classified, inspectable, policy-bounded, and relation-aware local truth.
Without it: Any higher-order condition layer is forced to recompute doctrine or skip important dimensions.
Purpose: Build chart-wide or subsystem-wide structural intelligence from integrated local profiles.
Dependency: Requires Phase 7.
Without it: Aggregate intelligence has no authoritative local unit to aggregate.
Purpose: Project relation and condition truth into a structural network.
Dependency: Requires formalized relations and integrated local profiles, and therefore depends on Phases 5-8.
Without it: Network summaries are disconnected from the condition model and become a second independent system.
Purpose: Freeze cross-layer invariants, deterministic ordering, failure behavior, and misuse resistance across the whole subsystem.
Dependency: Requires the major layers to already exist, especially the relation, integration, aggregate, and network layers.
Without it: There is no full subsystem to harden, only isolated components.
Purpose: Write the formal backend standard and validation doctrine for the subsystem as it actually exists.
Dependency: Requires the subsystem invariants, terminology, boundaries, and failure behavior to already be explicit.
Without it: The standard would be aspirational prose rather than a constitutional document.
Purpose: Expose the stable constitutional surface publicly and keep helpers internal.
Dependency: Requires the subsystem’s stable constitutional surface to already be known.
Without it: The package exports leak implementation detail because stability has not yet been established.
The constitutional dependency rule is:
A phase may only formalize, aggregate, freeze, or expose truths that have already become explicit in earlier phases.
Corollaries:
This is why the process is constitutional rather than incremental. It is not just adding capabilities. It is making each layer legitimate before the next layer is allowed to exist.
Phase 11 is not “write the docs.”
Phase 11 is:
write the constitution of a subsystem whose constitutional facts are already explicit
That requires at least:
If those are not already real in code and tests, then the backend standard is not a constitution. It is only an intention.
Phase 12 is not merely “export more names.”
It is:
expose the stable constitutional surface after the subsystem has already declared what is stable, what is internal, and what guarantees attach to the public surface
This is why public API curation belongs at the end of the process rather than near the beginning.
When constitutional process is correctly completed for a subsystem, the repository should contain:
The backend standard is not supplemental. It is a deliverable of the process.
00_SUBSYSTEM_CONSTITUTIONALIZATION_PROCESS.md belongs at the top of
moira/docs because it explains the governing logic under which the subsystem
standards were produced.
The order is intentional:
Validation reports show that the code works.
This process explains how Moira decides what it means for a backend subsystem to become constitutional in the first place.
This process is the default doctrine for any Moira backend subsystem that:
It is especially applicable to subsystems that evolve from:
into:
Any future backend subsystem standard should be interpretable as an instance of this process unless explicitly declared otherwise.
Any future Moira subsystem that departs materially from this process should state:
Absent such a declaration, this process is the default constitutional doctrine of backend development in Moira.