solverforge 0.6.8__tar.gz → 0.6.10__tar.gz

{solverforge-0.6.8 → solverforge-0.6.10}/Cargo.lock

@@ -644,7 +644,7 @@ dependencies = [
 
 [[package]]
 name = "solverforge_py"
-version = "0.6.8"
+version = "0.6.10"
 dependencies = [
  "indexmap",
  "once_cell",

{solverforge-0.6.8 → solverforge-0.6.10}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "solverforge_py"
-version = "0.6.8"
+version = "0.6.10"
 edition = "2021"
 license = "Apache-2.0"
 rust-version = "1.95"

{solverforge-0.6.8 → solverforge-0.6.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solverforge
-Version: 0.6.8
+Version: 0.6.10
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -51,12 +51,12 @@ requirements, and other APIs that are not part of this package.
 
 ## Installation
 
-The package version prepared by this checkout is `solverforge` `0.6.8`, targeting
+The package version prepared by this checkout is `solverforge` `0.6.10`, targeting
 the published and registry-locked SolverForge Rust `0.19.7` dependency base.
 Install the matching package after its Python release with:
 
 ```sh
-python3.14 -m pip install "solverforge==0.6.8"
+python3.14 -m pip install "solverforge==0.6.10"
 ```
 
 The installable wheel contains the core `solverforge` package, native extension,
@@ -76,12 +76,12 @@ make deliveries-run PORT=7861
 ```
 
 The same source-checkout examples can be run against the matching published
-package once `0.6.8` is released, without `PYTHONPATH` or an editable checkout:
+package once `0.6.10` is released, without `PYTHONPATH` or an editable checkout:
 
 ```sh
 python3.14 -m venv .venv-examples
 . .venv-examples/bin/activate
-python -m pip install "solverforge[examples]==0.6.8"
+python -m pip install "solverforge[examples]==0.6.10"
 python examples/nqueens.py
 python -m examples.solverforge_hospital
 python -m examples.solverforge_deliveries
@@ -104,16 +104,19 @@ from solverforge import (
     Solver,
     constraint_provider,
     planning_entity,
+    planning_pin,
     planning_solution,
     planning_variable,
 )
 
 @planning_entity
 class Shift:
+    pinned = planning_pin()
     nurse = planning_variable(value_range_provider="nurses", allows_unassigned=True)
 
     def __init__(self, required: bool = True, nurse: int | None = None) -> None:
         self.required = required
+        self.pinned = False
         self.nurse = nurse
 
 @constraint_provider
@@ -243,11 +246,21 @@ Run `make help` for focused targets such as `make test-hospital`,
   per-query Python callbacks. Provider-backed value ranges are imported once per
   variable and shared across rows in Rust-owned state. Row candidate callbacks
   remain row-specific and define move legality throughout construction and local
-  search, including assignment-group swaps and rematches. `pinning=True` is
-  rejected with `ModelValidationError` rather than ignored: SolverForge pins a
-  whole planning entity through an entity-level descriptor predicate, and no
-  public bridge seam exposes entity pinning to the Python binding yet. Pin an
-  input value by restricting `candidate_values` instead.
+  search, including assignment-group swaps and rematches.
+- `planning_pin()` declares the entity attribute that holds an entity's pinned
+  flag. The declared attribute must hold a `bool` on every instance; an unset or
+  non-`bool` value is rejected at import rather than read as "not pinned". A
+  pinned entity keeps its input planning state: its genuine scalar value and the
+  elements its list variable owns survive construction, local search,
+  ruin/recreate, and exhaustive search, while every unpinned entity in the same
+  solve is still constructed and searched. Pinning preserves input state, it does
+  not exempt a row from the mandatory-completion gate: a pinned required scalar
+  that nothing assigned fails the solve, and a pinned `allows_unassigned` scalar
+  stays unassigned. It is a declared field, not a callback — there is no dynamic
+  `is_pinned()` hook, because the compiled runtime reads a resolved per-row flag.
+  The variable-level `planning_variable(pinning=True)` flag stays rejected with
+  `ModelValidationError`: SolverForge pins whole entities, and that flag names a
+  route the framework does not have.
 - `scalar_assignment_group(...)` declares assignment-aware scalar groups for
   grouped scalar local search and assignment-group construction. Group metadata
   covers required entities, capacity keys, assignment rules, ordering callbacks,

{solverforge-0.6.8 → solverforge-0.6.10}/README.md

@@ -20,12 +20,12 @@ requirements, and other APIs that are not part of this package.
 
 ## Installation
 
-The package version prepared by this checkout is `solverforge` `0.6.8`, targeting
+The package version prepared by this checkout is `solverforge` `0.6.10`, targeting
 the published and registry-locked SolverForge Rust `0.19.7` dependency base.
 Install the matching package after its Python release with:
 
 ```sh
-python3.14 -m pip install "solverforge==0.6.8"
+python3.14 -m pip install "solverforge==0.6.10"
 ```
 
 The installable wheel contains the core `solverforge` package, native extension,
@@ -45,12 +45,12 @@ make deliveries-run PORT=7861
 ```
 
 The same source-checkout examples can be run against the matching published
-package once `0.6.8` is released, without `PYTHONPATH` or an editable checkout:
+package once `0.6.10` is released, without `PYTHONPATH` or an editable checkout:
 
 ```sh
 python3.14 -m venv .venv-examples
 . .venv-examples/bin/activate
-python -m pip install "solverforge[examples]==0.6.8"
+python -m pip install "solverforge[examples]==0.6.10"
 python examples/nqueens.py
 python -m examples.solverforge_hospital
 python -m examples.solverforge_deliveries
@@ -73,16 +73,19 @@ from solverforge import (
     Solver,
     constraint_provider,
     planning_entity,
+    planning_pin,
     planning_solution,
     planning_variable,
 )
 
 @planning_entity
 class Shift:
+    pinned = planning_pin()
     nurse = planning_variable(value_range_provider="nurses", allows_unassigned=True)
 
     def __init__(self, required: bool = True, nurse: int | None = None) -> None:
         self.required = required
+        self.pinned = False
         self.nurse = nurse
 
 @constraint_provider
@@ -212,11 +215,21 @@ Run `make help` for focused targets such as `make test-hospital`,
   per-query Python callbacks. Provider-backed value ranges are imported once per
   variable and shared across rows in Rust-owned state. Row candidate callbacks
   remain row-specific and define move legality throughout construction and local
-  search, including assignment-group swaps and rematches. `pinning=True` is
-  rejected with `ModelValidationError` rather than ignored: SolverForge pins a
-  whole planning entity through an entity-level descriptor predicate, and no
-  public bridge seam exposes entity pinning to the Python binding yet. Pin an
-  input value by restricting `candidate_values` instead.
+  search, including assignment-group swaps and rematches.
+- `planning_pin()` declares the entity attribute that holds an entity's pinned
+  flag. The declared attribute must hold a `bool` on every instance; an unset or
+  non-`bool` value is rejected at import rather than read as "not pinned". A
+  pinned entity keeps its input planning state: its genuine scalar value and the
+  elements its list variable owns survive construction, local search,
+  ruin/recreate, and exhaustive search, while every unpinned entity in the same
+  solve is still constructed and searched. Pinning preserves input state, it does
+  not exempt a row from the mandatory-completion gate: a pinned required scalar
+  that nothing assigned fails the solve, and a pinned `allows_unassigned` scalar
+  stays unassigned. It is a declared field, not a callback — there is no dynamic
+  `is_pinned()` hook, because the compiled runtime reads a resolved per-row flag.
+  The variable-level `planning_variable(pinning=True)` flag stays rejected with
+  `ModelValidationError`: SolverForge pins whole entities, and that flag names a
+  route the framework does not have.
 - `scalar_assignment_group(...)` declares assignment-aware scalar groups for
   grouped scalar local search and assignment-group construction. Group metadata
   covers required entities, capacity keys, assignment rules, ordering callbacks,

{solverforge-0.6.8 → solverforge-0.6.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "solverforge"
-version = "0.6.8"
+version = "0.6.10"
 description = "Dynamic Python bindings for the SolverForge constraint solver."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -51,6 +51,10 @@ strip = true
 testpaths = ["tests/python"]
 pythonpath = ["python"]
 
+[tool.black]
+line-length = 100
+target-version = ["py314"]
+
 [tool.ruff]
 line-length = 100
 target-version = "py314"

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/__init__.py

@@ -28,6 +28,7 @@ from .fields import (
     SolutionField,
     planning_id,
     planning_list_variable,
+    planning_pin,
     planning_variable,
 )
 from .groups import (
@@ -40,7 +41,7 @@ from .manager import JobHandle, SolverManager
 from .score import HardMediumSoftScore, HardSoftDecimalScore, HardSoftScore, SoftScore
 from .solver import Solver
 
-__version__ = "0.6.8"
+__version__ = "0.6.10"
 
 __all__ = [
     "CallbackError",
@@ -78,6 +79,7 @@ __all__ = [
     "planning_entity",
     "planning_id",
     "planning_list_variable",
+    "planning_pin",
     "planning_solution",
     "planning_variable",
     "problem_fact",

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/_native.pyi

@@ -38,18 +38,14 @@ class SolverManager:
     def _preflight_qualified_candidate_trace_provenance(
         self,
         *,
-        qualified_candidate_trace_provenance: (
-            QualifiedCandidateTraceProvenance | None
-        ) = None,
+        qualified_candidate_trace_provenance: QualifiedCandidateTraceProvenance | None = None,
     ) -> None: ...
     def solve(
         self,
         solution: object,
         schema: CompiledSchema,
         *,
-        qualified_candidate_trace_provenance: (
-            QualifiedCandidateTraceProvenance | None
-        ) = None,
+        qualified_candidate_trace_provenance: QualifiedCandidateTraceProvenance | None = None,
     ) -> int: ...
     def get_status(self, job_id: int) -> dict[str, object]: ...
     def telemetry_detail(self, job_id: int) -> dict[str, object]: ...

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/config.py

@@ -162,9 +162,7 @@ def _normalize_phases(phases: list[dict[str, Any]]) -> list[dict[str, Any]]:
                 dict(phase_copy["termination"])
             ).to_dict()
         if "child_phases" in phase_copy:
-            phase_copy["child_phases"] = _normalize_phases(
-                list(phase_copy["child_phases"])
-            )
+            phase_copy["child_phases"] = _normalize_phases(list(phase_copy["child_phases"]))
         normalized.append(phase_copy)
     return normalized
 

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/constraints.py

@@ -163,10 +163,7 @@ class ListPrecedenceMakespanConstraintStream:
         if plan.precedence_duration is None and plan.precedence_duration_field is None:
             msg = f"{self.entity_type.__name__}.{self.variable_name} requires precedence_duration"
             raise TypeError(msg)
-        if (
-            plan.precedence_successors is None
-            and plan.precedence_successors_field is None
-        ):
+        if plan.precedence_successors is None and plan.precedence_successors_field is None:
             msg = f"{self.entity_type.__name__}.{self.variable_name} requires precedence_successors"
             raise TypeError(msg)
         if plan.element_owner is None and plan.element_owner_field is None:
@@ -382,9 +379,7 @@ class ConstraintFactory:
         self.score_family = score_family
 
     def for_each(self, entity_type: type[object]) -> UniConstraintStream:
-        return UniConstraintStream(
-            entity_type=entity_type, score_family=self.score_family
-        )
+        return UniConstraintStream(entity_type=entity_type, score_family=self.score_family)
 
     def for_each_unassigned_element(
         self,
@@ -409,14 +404,10 @@ class ConstraintFactory:
         )
 
     def join(self, *_args: Any, **_kwargs: Any) -> None:
-        raise NotImplementedError(
-            "dynamic join is implemented in the native stream planner"
-        )
+        raise NotImplementedError("dynamic join is implemented in the native stream planner")
 
     def if_exists(self, *_args: Any, **_kwargs: Any) -> None:
-        raise NotImplementedError(
-            "dynamic if_exists is implemented in the native stream planner"
-        )
+        raise NotImplementedError("dynamic if_exists is implemented in the native stream planner")
 
     def if_not_exists(self, *_args: Any, **_kwargs: Any) -> None:
         raise NotImplementedError(
@@ -424,14 +415,10 @@ class ConstraintFactory:
         )
 
     def group_by(self, *_args: Any, **_kwargs: Any) -> None:
-        raise NotImplementedError(
-            "dynamic group_by is implemented in the native stream planner"
-        )
+        raise NotImplementedError("dynamic group_by is implemented in the native stream planner")
 
     def flattened(self, *_args: Any, **_kwargs: Any) -> None:
-        raise NotImplementedError(
-            "dynamic flattened is implemented in the native stream planner"
-        )
+        raise NotImplementedError("dynamic flattened is implemented in the native stream planner")
 
 
 def joiner_to_native(joiner: object) -> object:
@@ -462,9 +449,7 @@ def collector_to_native(collector: object) -> object:
     return collector
 
 
-def _list_variable_element_collection(
-    entity_type: type[object], variable_name: str
-) -> str:
+def _list_variable_element_collection(entity_type: type[object], variable_name: str) -> str:
     field_info = _list_variable_metadata(entity_type, variable_name)
     collection = field_info.get("element_collection")
     if isinstance(collection, str) and collection:
@@ -473,9 +458,7 @@ def _list_variable_element_collection(
     raise TypeError(msg)
 
 
-def _list_variable_metadata(
-    entity_type: type[object], variable_name: str
-) -> dict[str, object]:
+def _list_variable_metadata(entity_type: type[object], variable_name: str) -> dict[str, object]:
     metadata = getattr(entity_type, "__solverforge_entity__", None)
     if not isinstance(metadata, dict):
         msg = f"{entity_type.__name__} is not marked with @planning_entity"

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/decorators.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any, TypeVar
 
+from .errors import ModelValidationError
 from .fields import (
     CapacityRouteFeasibility,
     EntityCallback,
@@ -22,8 +23,11 @@ T = TypeVar("T", bound=type[object])
 
 def _collect_fields(cls: type[object]) -> list[dict[str, object]]:
     fields: list[dict[str, object]] = []
+    pin_fields: list[str] = []
     for name, value in vars(cls).items():
         if isinstance(value, PlanningField):
+            if value.metadata.kind == "planning_pin":
+                pin_fields.append(name)
             fields.append(
                 {
                     "name": name,
@@ -51,6 +55,9 @@ def _collect_fields(cls: type[object]) -> list[dict[str, object]]:
                     "list_metadata": _list_metadata(value.metadata.list_metadata),
                 }
             )
+    if len(pin_fields) > 1:
+        msg = f"{cls.__name__} declares more than one planning_pin field"
+        raise ModelValidationError(msg)
     return fields
 
 
@@ -133,12 +140,18 @@ def planning_entity(cls: T) -> T:
 
 
 def problem_fact(cls: T) -> T:
+    fields = _collect_fields(cls)
+    if any(field["kind"] == "planning_pin" for field in fields):
+        msg = (
+            f"{cls.__name__} is a problem fact; planning_pin is only valid on a " "planning entity"
+        )
+        raise ModelValidationError(msg)
     setattr(
         cls,
         "__solverforge_fact__",
         {
             "type_name": cls.__name__,
-            "fields": _collect_fields(cls),
+            "fields": fields,
         },
     )
     return cls
@@ -206,9 +219,7 @@ def planning_solution(
     shadow_variable_updates: dict[str, Any] | list[dict[str, Any]] | None = None,
 ) -> Callable[[T], T]:
     def decorate(cls: T) -> T:
-        updates = (
-            shadow_updates if shadow_updates is not None else shadow_variable_updates
-        )
+        updates = shadow_updates if shadow_updates is not None else shadow_variable_updates
         if updates is None:
             update_list: list[dict[str, Any]] = []
         elif isinstance(updates, dict):

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/errors.py

@@ -12,4 +12,3 @@ class CallbackError(SolverForgeError):
 
 class NativeBridgeError(SolverForgeError):
     """Raised when the PyO3 bridge reports a native-side failure."""
-

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/events.py

@@ -10,4 +10,3 @@ class SolverEvent:
     lifecycle_state: str
     snapshot_revision: int | None = None
     error: str | None = None
-

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/fields.py

@@ -59,9 +59,7 @@ class SolutionCallback:
             raise TypeError("SolutionCallback callback must be callable")
 
 
-ListValueSource: TypeAlias = (
-    RowField | SolutionField | EntityCallback | SolutionCallback
-)
+ListValueSource: TypeAlias = RowField | SolutionField | EntityCallback | SolutionCallback
 ListFeasibilityFieldSource: TypeAlias = RowField | SolutionField
 
 
@@ -74,14 +72,10 @@ class CapacityRouteFeasibility:
 
     def __post_init__(self) -> None:
         if self.capacity is None or self.demand is None:
-            raise TypeError(
-                "CapacityRouteFeasibility requires capacity and demand sources"
-            )
+            raise TypeError("CapacityRouteFeasibility requires capacity and demand sources")
 
 
-ListFeasibilitySource: TypeAlias = (
-    EntityCallback | SolutionCallback | CapacityRouteFeasibility
-)
+ListFeasibilitySource: TypeAlias = EntityCallback | SolutionCallback | CapacityRouteFeasibility
 
 
 @dataclass(frozen=True)
@@ -94,9 +88,7 @@ class ListRouteHooks:
 
     def __post_init__(self) -> None:
         if self.depot is None or self.distance is None or self.feasible is None:
-            raise TypeError(
-                "ListRouteHooks requires depot, distance, and feasible sources"
-            )
+            raise TypeError("ListRouteHooks requires depot, distance, and feasible sources")
 
 
 @dataclass(frozen=True)
@@ -181,6 +173,17 @@ def planning_id() -> PlanningField:
     return PlanningField(FieldMetadata(kind="planning_id"))
 
 
+def planning_pin() -> PlanningField:
+    """Declares the entity attribute that holds this entity's pinned flag.
+
+    The declared attribute must hold a ``bool`` on every instance. A pinned
+    entity keeps its input planning state: its genuine scalar value and its
+    list ownership survive construction and search.
+    """
+
+    return PlanningField(FieldMetadata(kind="planning_pin"))
+
+
 def planning_variable(
     *,
     value_range_provider: str,
@@ -195,9 +198,8 @@ def planning_variable(
     if pinning:
         msg = (
             "planning_variable(pinning=True) is not supported: SolverForge pins a whole "
-            "planning entity through an entity-level descriptor predicate, and no public "
-            "bridge seam exposes entity pinning to the Python binding yet. Pin an input "
-            "value by restricting candidate_values instead."
+            "planning entity, not one variable. Declare an entity pin field with "
+            "planning_pin() instead."
         )
         raise ModelValidationError(msg)
     value_candidates = _resolve_metadata_source(
@@ -393,9 +395,7 @@ def _resolve_list_value_source(
             solution_arity,
         )
         return source
-    raise TypeError(
-        f"{name} must be RowField, SolutionField, EntityCallback, or SolutionCallback"
-    )
+    raise TypeError(f"{name} must be RowField, SolutionField, EntityCallback, or SolutionCallback")
 
 
 def _resolve_required_list_value_source(
@@ -445,9 +445,7 @@ def _resolve_list_feasibility_source(
             solution_arity,
         )
         return source
-    raise TypeError(
-        f"{name} must be EntityCallback, SolutionCallback, or CapacityRouteFeasibility"
-    )
+    raise TypeError(f"{name} must be EntityCallback, SolutionCallback, or CapacityRouteFeasibility")
 
 
 def _resolve_list_feasibility_field_source(
@@ -491,10 +489,7 @@ def _callback_accepts_arity(callback: Callable[..., object], arity: int) -> bool
                 required_positional_count += 1
         elif parameter.kind is Parameter.VAR_POSITIONAL:
             accepts_extra_positionals = True
-        elif (
-            parameter.kind is Parameter.KEYWORD_ONLY
-            and parameter.default is Parameter.empty
-        ):
+        elif parameter.kind is Parameter.KEYWORD_ONLY and parameter.default is Parameter.empty:
             return False
 
     if arity < required_positional_count:

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/groups.py

@@ -89,17 +89,10 @@ class ScalarAssignmentGroup:
             ),
         ):
             if callback is not None and field is not None:
-                raise TypeError(
-                    f"{callback_name} and {field_name} cannot both be configured"
-                )
+                raise TypeError(f"{callback_name} and {field_name} cannot both be configured")
             if field is not None and (not isinstance(field, str) or not field):
-                raise TypeError(
-                    f"{field_name} must be a non-empty string when provided"
-                )
-        if (
-            self.assignment_rule is not None
-            and self.same_value_conflict_field is not None
-        ):
+                raise TypeError(f"{field_name} must be a non-empty string when provided")
+        if self.assignment_rule is not None and self.same_value_conflict_field is not None:
             raise TypeError(
                 "assignment_rule and same_value_conflict_field cannot both be configured"
             )
@@ -107,9 +100,7 @@ class ScalarAssignmentGroup:
             not isinstance(self.same_value_conflict_field, str)
             or not self.same_value_conflict_field
         ):
-            raise TypeError(
-                "same_value_conflict_field must be a non-empty string when provided"
-            )
+            raise TypeError("same_value_conflict_field must be a non-empty string when provided")
 
     def to_native(self) -> dict[str, Any]:
         return {

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/model.py

@@ -90,9 +90,7 @@ def _schema_shape(value: object) -> tuple[SchemaShape, bool]:
 
     def shape(item: object, *, callback_state: bool = False) -> SchemaShape:
         nonlocal cacheable, next_marker
-        recursive = isinstance(
-            item, (dict, list, tuple, FunctionType, MethodType, partial)
-        )
+        recursive = isinstance(item, (dict, list, tuple, FunctionType, MethodType, partial))
         item_id = id(item)
         if recursive:
             if item_id in active:
@@ -147,8 +145,7 @@ def _schema_shape(value: object) -> tuple[SchemaShape, bool]:
                     for cell in (item.__closure__ or ())
                 )
                 defaults = tuple(
-                    shape(default, callback_state=True)
-                    for default in (item.__defaults__ or ())
+                    shape(default, callback_state=True) for default in (item.__defaults__ or ())
                 )
                 keyword_defaults = tuple(
                     (name, shape(default, callback_state=True))
@@ -241,7 +238,9 @@ def _scalar_groups(callbacks: object) -> list[dict[str, object]]:
         callback = cast(Callable[..., object], item)
         metadata = getattr(callback, "__solverforge_scalar_group__", None)
         if not isinstance(metadata, dict):
-            msg = f"{callback!r} is not marked with @scalar_group and is not a ScalarAssignmentGroup"
+            msg = (
+                f"{callback!r} is not marked with @scalar_group and is not a ScalarAssignmentGroup"
+            )
             raise ModelValidationError(msg)
         name = metadata.get("name")
         if not isinstance(name, str) or not name:
@@ -262,9 +261,7 @@ def _conflict_repairs(callbacks: object) -> list[dict[str, object]]:
         if not isinstance(metadata, dict):
             msg = f"{callback!r} is not marked with @conflict_repair"
             raise ModelValidationError(msg)
-        constraint_names = list(
-            cast(Iterable[object], metadata.get("constraints") or [])
-        )
+        constraint_names = list(cast(Iterable[object], metadata.get("constraints") or []))
         if not constraint_names or not all(
             isinstance(name, str) and name for name in constraint_names
         ):

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/solver.py

@@ -9,9 +9,7 @@ from .model import _compiled_schema_for_solution
 
 class Solver:
     @staticmethod
-    def solve(
-        solution: object, config: SolverConfig | dict[str, Any] | None = None
-    ) -> object:
+    def solve(solution: object, config: SolverConfig | dict[str, Any] | None = None) -> object:
         schema = _compiled_schema_for_solution(solution)
         return _native.solve(solution, schema, _resolve_config(config))
 

{solverforge-0.6.8 → solverforge-0.6.10}/python/solverforge/typing.py

@@ -14,4 +14,3 @@ class PlanningEntityProtocol(Protocol):
 
 class PlanningSolutionProtocol(Protocol):
     score: object | None
-

{solverforge-0.6.8 → solverforge-0.6.10}/src/schema/build.rs

@@ -1,14 +1,26 @@
-use std::any::TypeId;
+use std::any::{Any, TypeId};
 
 use solverforge_bridge::{EntityClassId, VariableId};
 use solverforge_core::domain::{EntityDescriptor, SolutionDescriptor, VariableDescriptor};
 
 use crate::descriptor::extractor::DynamicEntityExtractor;
 use crate::intern::intern;
+use crate::state::entity_table::DynamicEntityRow;
 use crate::state::PyDynamicSolution;
 
 use super::DynamicSchema;
 
+/// The one entity pin predicate for every compiled Python schema.
+///
+/// The declaration is resolved per row at import, so this stays a capture-free
+/// function over Rust-owned state: no thread-local slot lookup, no Python
+/// callback, and no per-candidate reinterpretation of the declared attribute.
+fn pinned_row_predicate(entity: &dyn Any) -> bool {
+    entity
+        .downcast_ref::<DynamicEntityRow>()
+        .is_some_and(|row| row.pinned)
+}
+
 pub fn solution_descriptor(schema: &DynamicSchema) -> SolutionDescriptor {
     let mut descriptor = SolutionDescriptor::new(
         intern(schema.solution_type.clone()),
@@ -37,6 +49,11 @@ pub fn solution_descriptor(schema: &DynamicSchema) -> SolutionDescriptor {
             .with_logical_id(VariableId(variable_index));
             entity_descriptor = entity_descriptor.with_variable(descriptor_variable);
         }
+        if let Some(pin_field) = entity.pin_field.as_deref() {
+            entity_descriptor = entity_descriptor
+                .with_pin_field(intern(pin_field.to_string()))
+                .with_pin_predicate(pinned_row_predicate);
+        }
         descriptor = descriptor.with_entity(entity_descriptor);
     }
     descriptor

{solverforge-0.6.8 → solverforge-0.6.10}/src/schema/parse.rs

@@ -34,9 +34,20 @@ pub fn parse_schema(schema: &Bound<'_, PyDict>) -> PyResult<DynamicSchema> {
             .ok_or_else(|| py_err(format!("entity `{type_name}` is missing `fields`")))?;
         let fields = fields_any.cast::<PyList>()?;
         let mut variables = Vec::new();
+        let mut pin_field: Option<String> = None;
         for field_any in fields.iter() {
             let field = field_any.cast::<PyDict>()?;
             let kind = required_str(field, "kind")?;
+            if kind == "planning_pin" {
+                let name = required_non_empty_str(field, "name")?;
+                if pin_field.is_some() {
+                    return Err(py_err(format!(
+                        "entity `{type_name}` declares more than one planning_pin field"
+                    )));
+                }
+                pin_field = Some(name);
+                continue;
+            }
             if kind == "planning_variable" || kind == "planning_list_variable" {
                 let list_metadata = if kind == "planning_list_variable" {
                     Some(parse_list_metadata(field)?)
@@ -98,10 +109,19 @@ pub fn parse_schema(schema: &Bound<'_, PyDict>) -> PyResult<DynamicSchema> {
                 });
             }
         }
+        if let Some(pin_field) = pin_field.as_deref() {
+            if variables.iter().any(|variable| variable.name == pin_field) {
+                return Err(py_err(format!(
+                    "entity `{type_name}` declares `{pin_field}` as both a planning \
+                     variable and a planning_pin field"
+                )));
+            }
+        }
         entities.push(EntitySchema {
             type_name,
             collection,
             variables,
+            pin_field,
         });
     }
     let facts = parse_facts(schema)?;

{solverforge-0.6.8 → solverforge-0.6.10}/src/schema/types.rs

@@ -7,6 +7,10 @@ pub struct EntitySchema {
     pub type_name: String,
     pub collection: String,
     pub variables: Vec<VariableSchema>,
+    /// The declared entity attribute holding this entity's pinned flag. It is
+    /// read once per instance at import and enforced by the compiled
+    /// SolverForge runtime, never by wrapper-owned phase code.
+    pub pin_field: Option<String>,
 }
 
 #[derive(Debug)]

{solverforge-0.6.8 → solverforge-0.6.10}/src/state/entity_table.rs

@@ -76,6 +76,11 @@ pub struct DynamicEntityRow {
     pub scalar_values: Vec<Option<usize>>,
     pub candidate_values: Vec<Option<Arc<[usize]>>>,
     pub list_values: Vec<Option<Vec<usize>>>,
+    /// The entity's declared pinned flag, resolved once at import. It is the
+    /// only input the compiled runtime reads through the descriptor's pin
+    /// predicate. It is a plain row field, so every copy of a row that clones
+    /// (candidate, snapshot, or detached solution) carries the resolved value.
+    pub pinned: bool,
 }
 
 impl DynamicEntityRow {

{solverforge-0.6.8 → solverforge-0.6.10}/src/state/marshal.rs

@@ -2,7 +2,7 @@ use std::collections::{BTreeMap, BTreeSet};
 use std::sync::Arc;
 
 use pyo3::prelude::*;
-use pyo3::types::{PyDict, PyInt, PyList, PyString};
+use pyo3::types::{PyBool, PyDict, PyInt, PyList, PyString};
 use solverforge_config::SolverConfig;
 
 use crate::schema::runtime_plan::CompiledRuntimePlan;
@@ -116,6 +116,9 @@ pub fn import_solution(
                 Some(&row_metadata_fields),
             )?;
             import_named_fields(&item, &extra_field_names, &mut row)?;
+            if let Some(pin_field) = entity.pin_field.as_deref() {
+                row.pinned = import_pin_value(&item, pin_field, &entity.type_name)?;
+            }
             rows.push(row);
             objects.push(item.unbind());
         }
@@ -1176,6 +1179,40 @@ fn import_named_fields(
     Ok(())
 }
 
+/// Reads one entity's declared pinned flag.
+///
+/// The declaration is a contract on the instance, not a hint: an unset, missing,
+/// or non-`bool` value is an error rather than an implicit "not pinned", because
+/// a silently unpinned declaration would look identical to a working one while
+/// preserving nothing. The declared attribute is a `planning_pin()` descriptor,
+/// so an instance that never sets it reads back as `None` rather than raising.
+fn import_pin_value(item: &Bound<'_, PyAny>, pin_field: &str, type_name: &str) -> PyResult<bool> {
+    let value = match item.getattr(pin_field) {
+        Ok(value) => value,
+        Err(cause) => {
+            // Keep the original failure as the cause: a declared attribute that
+            // exists but raises is a different problem from one that is absent,
+            // and the operator needs the original traceback to tell them apart.
+            let error = crate::error::py_err(format!(
+                "pinned entity `{type_name}` has no readable `{pin_field}` attribute"
+            ));
+            error.set_cause(item.py(), Some(cause));
+            return Err(error);
+        }
+    };
+    if value.is_none() {
+        return Err(crate::error::py_err(format!(
+            "pinned entity `{type_name}` must set a bool `{pin_field}` attribute per instance"
+        )));
+    }
+    if !value.is_instance_of::<PyBool>() {
+        return Err(crate::error::py_err(format!(
+            "pinned entity `{type_name}` attribute `{pin_field}` must be a bool"
+        )));
+    }
+    value.extract::<bool>()
+}
+
 fn is_read_only_property(
     item: &Bound<'_, PyAny>,
     name: &str,

{solverforge-0.6.8 → solverforge-0.6.10}/src/state/solution.rs

@@ -741,6 +741,7 @@ mod tests {
             entities: vec![EntitySchema {
                 type_name: "Route".to_string(),
                 collection: "routes".to_string(),
+                pin_field: None,
                 variables: vec![VariableSchema {
                     name: "visits".to_string(),
                     storage_name: "__solverforge_visits".to_string(),