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}