Skip to main content

solverforge_core/domain/dynamic/
assignment.rs

1//! Dynamic metadata for declarative scalar-assignment groups.
2//!
3//! This is intentionally a metadata boundary, not a construction-phase API.
4//! Host-language bindings register one metadata object with one scalar group;
5//! the solver owns all candidate generation, construction, and local search.
6
7/// Structural capabilities supplied by a dynamic scalar-assignment group.
8///
9/// A capability says whether metadata is declared, rather than inferring that
10/// fact from a value returned while solving.  The solver uses this distinction
11/// when validating construction heuristics and assignment-rule dependencies.
12#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
13pub struct DynamicScalarAssignmentMetadataCapabilities {
14    /// [`DynamicScalarAssignmentMetadata::required_entity`] is declared.
15    pub required_entity: bool,
16    /// [`DynamicScalarAssignmentMetadata::capacity_key`] is declared.
17    pub capacity_key: bool,
18    /// [`DynamicScalarAssignmentMetadata::position_key`] is declared.
19    pub position_key: bool,
20    /// [`DynamicScalarAssignmentMetadata::sequence_key`] is declared.
21    pub sequence_key: bool,
22    /// [`DynamicScalarAssignmentMetadata::entity_order_key`] is declared.
23    pub entity_order: bool,
24    /// [`DynamicScalarAssignmentMetadata::value_order_key`] is declared.
25    pub value_order: bool,
26    /// [`DynamicScalarAssignmentMetadata::assignment_edge_allowed`] is
27    /// declared; requires `sequence_key`.
28    pub assignment_rule: bool,
29}
30
31/// Object-safe metadata access for one dynamic scalar-assignment group.
32///
33/// Implementors are bound to a concrete group at model compilation time.  They
34/// must not select a group indirectly from thread-local state, a runtime name
35/// lookup, or the active phase.  Typed Rust groups retain their direct
36/// function-pointer metadata and never use this dynamic boundary.
37pub trait DynamicScalarAssignmentMetadata<S>: Send + Sync {
38    /// Metadata this group declares. An undeclared capability's method must
39    /// return its neutral result.
40    fn capabilities(&self) -> DynamicScalarAssignmentMetadataCapabilities;
41
42    /// Whether the row must be assigned before the solution is complete; neutral result `false`.
43    fn required_entity(&self, solution: &S, entity_index: usize) -> bool;
44
45    /// Capacity key consumed by assigning `value` to the row; at most one
46    /// assigned row may hold each key. `None` consumes no capacity.
47    fn capacity_key(&self, solution: &S, entity_index: usize, value: usize) -> Option<usize>;
48
49    /// Position of the row used to order assigned rows; `None` when the row has no position.
50    fn position_key(&self, solution: &S, entity_index: usize) -> Option<i64>;
51
52    /// Position of the `(row, value)` assignment in the value's sequence; rows
53    /// at sequence keys `k` and `k + 1` for the same value are adjacent. `None`
54    /// when unsequenced.
55    fn sequence_key(&self, solution: &S, entity_index: usize, value: usize) -> Option<usize>;
56
57    /// Ranking key for the row in entity-ordered construction; `None` when undeclared.
58    fn entity_order_key(&self, solution: &S, entity_index: usize) -> Option<i64>;
59
60    /// Ranking key for `value` on the row in value-ordered construction; `None` when undeclared.
61    fn value_order_key(&self, solution: &S, entity_index: usize, value: usize) -> Option<i64>;
62
63    /// Whether `left_entity` holding `left_value` may directly precede
64    /// `right_entity` holding `right_value` in a sequence; neutral result
65    /// `true`.
66    fn assignment_edge_allowed(
67        &self,
68        solution: &S,
69        left_entity: usize,
70        left_value: usize,
71        right_entity: usize,
72        right_value: usize,
73    ) -> bool;
74}