Specs#
Contract and SearchSpace boundaries pass connection conditions and representations as declarative values rather than processing them directly. This page calls these declarative values specs. Specs are immutable values, not Component subclasses, that the Compiler uses to determine connections and requirements.
Specs’ role#
Specs own the boundary that passes connection conditions, representations, and required services to the Compiler rather than performing the processing itself.
They do not hold Component execution state; ComponentContract and SearchSpace own the declarative values.
PortSpec and PortContract#
PortSpec is one port declaration containing a port name, direction, DataSpec, cardinality, required services, and optionality.
PortContract is the set of input and output ports belonging to one role.
Port names must be unique within each direction.
The Compiler uses ONE, MANY, and OPTIONAL cardinalities to determine whether a provided value satisfies the consumer’s requirement.
A connection is incompatible when its direction, registered data kind, schema binding, or cardinality does not match.
DataSpec and ServiceRequirement#
DataSpec represents a registered nominal data kind and schema binding.
Fixed values, variables, containment conditions, and product bindings can unify the same schema variable across ports.
DataSpec kind compatibility, schema unification, and service resolution are separate checks.
ServiceRequirement declares a named service required by a port or Component.
SearchSpace services such as SamplingService and ValidationService are matched as space capabilities.
EvaluationAdapter is an adapter at the evaluation boundary, while FeatureEncoder is an adapter subtype exposed as saealib.space.FeatureEncoder.
FeatureEncoder converts a GenomeBatch to a FeatureBatch and provides the semantic transformation that determines features a surrogate model can learn. It differs in nature from space capabilities such as SamplingService.
In the current implementation, the SurrogateManager contract declares ServiceRequirement("FeatureEncoder"), and VectorSpace registers a default FeatureEncoder as a service, so numeric vector spaces resolve it without extra configuration. ObjectSpace, PermutationSpace, and SequenceSpace raise an error unless the user supplies a FeatureEncoder. The user determines the input passed to the surrogate model.
RepresentationSpec boundary#
RepresentationSpec is the candidate-representation specification on the SearchSpace side.
It describes candidate type, shape, and representation, but is not part of a ComponentContract’s ports, state, or execution.
Therefore, SearchSpace services, EvaluationAdapter, FeatureEncoder, and the RepresentationSpec held by the space are separate boundaries that the Compiler connects.
Declarative value |
Owner |
Boundary using it |
|---|---|---|
|
|
Graph connections and port compatibility |
|
Port or contract |
Data kind and schema binding unification |
|
Component or port |
Resolving services provided by SearchSpace and Problem |
|
|
Candidate representation and representation-service consistency |
Construction time and use time#
PortSpec, DataSpec, and ServiceRequirement are created when a ComponentContract is built and used by the Compiler when connecting the graph.
The contract or SearchSpace owns these values; the Runtime does not rewrite them during execution.
Invariants and diagnostics#
An unregistered kind, undefined cardinality, mismatched schema binding, or missing required service becomes a Diagnostic.
The implementation reports these with codes such as unknown_data_spec, unknown_cardinality, unknown_schema_variable, and unresolved_service.
Extension points#
When adding a data kind or service, state its registration and compatibility rules explicitly and do not connect it through an implicit type conversion.