solverforge 0.6.8__tar.gz → 0.6.9__tar.gz

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

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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solverforge
-Version: 0.6.8
+Version: 0.6.9
 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.9`, 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.9"
 ```
 
 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.9` 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.9"
 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.9}/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.9`, 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.9"
 ```
 
 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.9` 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.9"
 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.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "solverforge"
-version = "0.6.8"
+version = "0.6.9"
 description = "Dynamic Python bindings for the SolverForge constraint solver."
 readme = "README.md"
 license = { text = "Apache-2.0" }

{solverforge-0.6.8 → solverforge-0.6.9}/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.9"
 
 __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.9}/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,19 @@ 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

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

@@ -181,6 +181,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 +206,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(

{solverforge-0.6.8 → solverforge-0.6.9}/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.9}/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.9}/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.9}/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.9}/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.9}/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(),