Initial commit from solverforge new

.gitignore

@@ -0,0 +1,2 @@
+/target
+**/*.rs.bk

Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "solverforge-fsr"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.95"
+description = "Constraint optimizer built with SolverForge"
+
+[[bin]]
+name = "solverforge_fsr"
+path = "src/main.rs"
+
+[dependencies]
+solverforge = { version = "0.10.0", features = ["serde", "console", "verbose-logging"] }
+solverforge-ui = { version = "0.6.4" }
+solverforge-maps = { version = "2.1.3" }
+# Web server
+axum = "0.8.9"
+tokio = { version = "1.52.1", features = ["full"] }
+tokio-stream = { version = "0.1.18", features = ["sync"] }
+tower-http = { version = "0.6.8", features = ["fs", "cors"] }
+tower = "0.5.3"
+
+# Serialization
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.149"
+
+# Utilities
+uuid = { version = "1.23.1", features = ["v4", "serde"] }
+parking_lot = "0.12.5"

README.md

@@ -0,0 +1,53 @@
+# solverforge-fsr
+
+A SolverForge constraint optimization project (scaffold: `neutral scaffold`).
+
+## Versioning
+
+- CLI version used to scaffold this project: `2.0.2`
+- SolverForge runtime target for this scaffold: `solverforge 0.10.0`
+- SolverForge UI target for this scaffold: `solverforge-ui 0.6.4`
+- SolverForge maps target for this scaffold: `solverforge-maps 2.1.3`
+- Runtime dependency currently wired into `Cargo.toml`: `crates.io: solverforge 0.10.0`
+- Frontend UI dependency currently wired into `Cargo.toml`: `crates.io: solverforge-ui 0.6.4`
+- Maps dependency currently wired into `Cargo.toml`: `crates.io: solverforge-maps 2.1.3`
+
+This project was scaffolded by `solverforge-cli`, and it currently targets `SolverForge crate target 0.10.0` through the configured crate dependency targets.
+
+## Quick Start
+
+```bash
+# Start the solver server
+solverforge server
+
+# Or run directly
+cargo run --release
+```
+
+## Development
+
+```bash
+# Add a new constraint
+solverforge generate constraint my_rule --unary --hard
+
+# Add a domain entity
+solverforge generate entity worker --planning-variable shift_idx
+
+# Add a problem fact
+solverforge generate fact location
+
+# Remove a resource
+solverforge destroy constraint my_rule
+```
+
+## Project Structure
+
+| Directory | Purpose |
+|-----------|--------|
+| `src/domain/` | Planning entities, facts, and solution struct |
+| `src/constraints/` | Constraint definitions (scored by the solver) |
+| `src/solver/` | Solver service and configuration |
+| `src/api/` | HTTP routes and DTOs |
+| `src/data/` | Data loading and generation |
+| `solverforge.app.toml` | Scaffolded app/domain contract |
+| `solver.toml` | Solver configuration (termination, phases) |

solver.toml

@@ -0,0 +1,15 @@
+[[phases]]
+type = "construction_heuristic"
+construction_heuristic_type = "first_fit"
+
+[[phases]]
+type = "local_search"
+[phases.acceptor]
+type = "late_acceptance"
+late_acceptance_size = 400
+[phases.forager]
+type = "accepted_count"
+limit = 4
+
+[termination]
+seconds_spent_limit = 30

solverforge.app.toml

@@ -0,0 +1,17 @@
+[app]
+name = "solverforge-fsr"
+starter = "neutral-shell"
+cli_version = "2.0.2"
+
+[runtime]
+target = "solverforge 0.10.0"
+runtime_source = "crates.io: solverforge 0.10.0"
+ui_source = "crates.io: solverforge-ui 0.6.4"
+
+[demo]
+default_size = "standard"
+available_sizes = ["small", "standard", "large"]
+
+[solution]
+name = "Plan"
+score = "HardSoftScore"

src/api/dto.rs

@@ -0,0 +1,247 @@
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+use solverforge::{
+    HardSoftScore, SolverLifecycleState, SolverSnapshot, SolverSnapshotAnalysis, SolverStatus,
+    SolverTelemetry, SolverTerminalReason,
+};
+use std::time::Duration;
+
+use crate::domain::Plan;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PlanDto {
+    #[serde(flatten)]
+    pub fields: Map<String, Value>,
+    #[serde(default)]
+    pub score: Option<String>,
+}
+
+/// Constraint analysis result.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ConstraintAnalysisDto {
+    pub name: String,
+    pub weight: String,
+    pub score: String,
+    pub match_count: usize,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AnalyzeResponse {
+    pub score: String,
+    pub constraints: Vec<ConstraintAnalysisDto>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TelemetryDto {
+    pub elapsed_ms: u64,
+    pub step_count: u64,
+    pub moves_generated: u64,
+    pub moves_evaluated: u64,
+    pub moves_accepted: u64,
+    pub score_calculations: u64,
+    pub generation_ms: u64,
+    pub evaluation_ms: u64,
+    pub moves_per_second: u64,
+    pub acceptance_rate: f64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct JobSummaryDto {
+    pub id: String,
+    pub job_id: String,
+    pub lifecycle_state: &'static str,
+    pub terminal_reason: Option<&'static str>,
+    pub checkpoint_available: bool,
+    pub event_sequence: u64,
+    pub snapshot_revision: Option<u64>,
+    pub current_score: Option<String>,
+    pub best_score: Option<String>,
+    pub telemetry: TelemetryDto,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct JobSnapshotDto {
+    pub id: String,
+    pub job_id: String,
+    pub snapshot_revision: u64,
+    pub lifecycle_state: &'static str,
+    pub terminal_reason: Option<&'static str>,
+    pub current_score: Option<String>,
+    pub best_score: Option<String>,
+    pub telemetry: TelemetryDto,
+    pub solution: PlanDto,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct JobAnalysisDto {
+    pub id: String,
+    pub job_id: String,
+    pub snapshot_revision: u64,
+    pub lifecycle_state: &'static str,
+    pub terminal_reason: Option<&'static str>,
+    pub analysis: AnalyzeResponse,
+}
+
+impl PlanDto {
+    pub fn from_plan(plan: &Plan) -> Self {
+        let mut fields = match serde_json::to_value(plan).expect("failed to serialize plan") {
+            Value::Object(map) => map,
+            _ => Map::new(),
+        };
+        let score = fields.remove("score").and_then(|value| {
+            if value.is_null() {
+                None
+            } else if let Some(score) = value.as_str() {
+                Some(score.to_string())
+            } else {
+                Some(value.to_string())
+            }
+        });
+
+        Self { fields, score }
+    }
+
+    pub fn to_domain(&self) -> Result<Plan, serde_json::Error> {
+        let mut fields = self.fields.clone();
+        let _ = &self.score;
+        fields.insert("score".to_string(), Value::Null);
+        serde_json::from_value(Value::Object(fields))
+    }
+}
+
+impl TelemetryDto {
+    pub fn from_runtime(telemetry: &SolverTelemetry) -> Self {
+        Self {
+            elapsed_ms: duration_to_millis(telemetry.elapsed),
+            step_count: telemetry.step_count,
+            moves_generated: telemetry.moves_generated,
+            moves_evaluated: telemetry.moves_evaluated,
+            moves_accepted: telemetry.moves_accepted,
+            score_calculations: telemetry.score_calculations,
+            generation_ms: duration_to_millis(telemetry.generation_time),
+            evaluation_ms: duration_to_millis(telemetry.evaluation_time),
+            moves_per_second: whole_units_per_second(telemetry.moves_evaluated, telemetry.elapsed),
+            acceptance_rate: derive_acceptance_rate(
+                telemetry.moves_accepted,
+                telemetry.moves_evaluated,
+            ),
+        }
+    }
+}
+
+impl JobSummaryDto {
+    pub fn from_status(job_id: usize, status: &SolverStatus<HardSoftScore>) -> Self {
+        Self {
+            id: job_id.to_string(),
+            job_id: job_id.to_string(),
+            lifecycle_state: lifecycle_state_label(status.lifecycle_state),
+            terminal_reason: status.terminal_reason.map(terminal_reason_label),
+            checkpoint_available: status.checkpoint_available,
+            event_sequence: status.event_sequence,
+            snapshot_revision: status.latest_snapshot_revision,
+            current_score: status.current_score.map(|score| score.to_string()),
+            best_score: status.best_score.map(|score| score.to_string()),
+            telemetry: TelemetryDto::from_runtime(&status.telemetry),
+        }
+    }
+}
+
+impl JobSnapshotDto {
+    pub fn from_snapshot(snapshot: &SolverSnapshot<Plan>) -> Self {
+        Self {
+            id: snapshot.job_id.to_string(),
+            job_id: snapshot.job_id.to_string(),
+            snapshot_revision: snapshot.snapshot_revision,
+            lifecycle_state: lifecycle_state_label(snapshot.lifecycle_state),
+            terminal_reason: snapshot.terminal_reason.map(terminal_reason_label),
+            current_score: snapshot.current_score.map(|score| score.to_string()),
+            best_score: snapshot.best_score.map(|score| score.to_string()),
+            telemetry: TelemetryDto::from_runtime(&snapshot.telemetry),
+            solution: PlanDto::from_plan(&snapshot.solution),
+        }
+    }
+}
+
+impl JobAnalysisDto {
+    pub fn from_snapshot_analysis(
+        snapshot: &SolverSnapshotAnalysis<HardSoftScore>,
+        analysis: AnalyzeResponse,
+    ) -> Self {
+        Self {
+            id: snapshot.job_id.to_string(),
+            job_id: snapshot.job_id.to_string(),
+            snapshot_revision: snapshot.snapshot_revision,
+            lifecycle_state: lifecycle_state_label(snapshot.lifecycle_state),
+            terminal_reason: snapshot.terminal_reason.map(terminal_reason_label),
+            analysis,
+        }
+    }
+}
+
+pub fn analysis_response(analysis: &solverforge::ScoreAnalysis<HardSoftScore>) -> AnalyzeResponse {
+    AnalyzeResponse {
+        score: analysis.score.to_string(),
+        constraints: analysis
+            .constraints
+            .iter()
+            .map(|constraint| ConstraintAnalysisDto {
+                name: constraint.name.clone(),
+                weight: constraint.weight.to_string(),
+                score: constraint.score.to_string(),
+                match_count: constraint.match_count,
+            })
+            .collect(),
+    }
+}
+
+pub fn lifecycle_state_label(state: SolverLifecycleState) -> &'static str {
+    match state {
+        SolverLifecycleState::Solving => "SOLVING",
+        SolverLifecycleState::PauseRequested => "PAUSE_REQUESTED",
+        SolverLifecycleState::Paused => "PAUSED",
+        SolverLifecycleState::Completed => "COMPLETED",
+        SolverLifecycleState::Cancelled => "CANCELLED",
+        SolverLifecycleState::Failed => "FAILED",
+    }
+}
+
+pub fn terminal_reason_label(reason: SolverTerminalReason) -> &'static str {
+    match reason {
+        SolverTerminalReason::Completed => "completed",
+        SolverTerminalReason::TerminatedByConfig => "terminated_by_config",
+        SolverTerminalReason::Cancelled => "cancelled",
+        SolverTerminalReason::Failed => "failed",
+    }
+}
+
+fn duration_to_millis(duration: Duration) -> u64 {
+    duration.as_millis().min(u128::from(u64::MAX)) as u64
+}
+
+fn whole_units_per_second(count: u64, elapsed: Duration) -> u64 {
+    let nanos = elapsed.as_nanos();
+    if nanos == 0 {
+        0
+    } else {
+        let per_second = u128::from(count)
+            .saturating_mul(1_000_000_000)
+            .checked_div(nanos)
+            .unwrap_or(0);
+        per_second.min(u128::from(u64::MAX)) as u64
+    }
+}
+
+fn derive_acceptance_rate(moves_accepted: u64, moves_evaluated: u64) -> f64 {
+    if moves_evaluated == 0 {
+        0.0
+    } else {
+        moves_accepted as f64 / moves_evaluated as f64
+    }
+}

src/api/mod.rs

@@ -0,0 +1,6 @@
+mod dto;
+mod routes;
+mod sse;
+
+pub use dto::PlanDto;
+pub use routes::{router, AppState};

src/api/routes.rs

@@ -0,0 +1,215 @@
+use axum::{
+    extract::{Path, Query, State},
+    http::StatusCode,
+    routing::{get, post},
+    Json, Router,
+};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+use super::dto::{analysis_response, JobAnalysisDto, JobSnapshotDto, JobSummaryDto, PlanDto};
+use super::sse;
+use crate::data::{generate, DemoData};
+use crate::solver::SolverService;
+
+/// Shared application state.
+pub struct AppState {
+    pub solver: SolverService,
+}
+
+impl AppState {
+    pub fn new() -> Self {
+        Self {
+            solver: SolverService::new(),
+        }
+    }
+}
+
+impl Default for AppState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Creates the API router.
+pub fn router(state: Arc<AppState>) -> Router {
+    Router::new()
+        .route("/health", get(health))
+        .route("/info", get(info))
+        .route("/demo-data", get(list_demo_data))
+        .route("/demo-data/{id}", get(get_demo_data))
+        .route("/jobs", post(create_job))
+        .route("/jobs/{id}", get(get_job).delete(delete_job))
+        .route("/jobs/{id}/status", get(get_job_status))
+        .route("/jobs/{id}/snapshot", get(get_snapshot))
+        .route("/jobs/{id}/analysis", get(analyze_by_id))
+        .route("/jobs/{id}/pause", post(pause_job))
+        .route("/jobs/{id}/resume", post(resume_job))
+        .route("/jobs/{id}/cancel", post(cancel_job))
+        .route("/jobs/{id}/events", get(sse::events))
+        .with_state(state)
+}
+
+#[derive(Serialize)]
+struct HealthResponse {
+    status: &'static str,
+}
+
+async fn health() -> Json<HealthResponse> {
+    Json(HealthResponse { status: "UP" })
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct InfoResponse {
+    name: &'static str,
+    version: &'static str,
+    solver_engine: &'static str,
+}
+
+async fn info() -> Json<InfoResponse> {
+    Json(InfoResponse {
+        name: env!("CARGO_PKG_NAME"),
+        version: env!("CARGO_PKG_VERSION"),
+        solver_engine: "SolverForge",
+    })
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct DemoDataCatalogResponse {
+    default_id: &'static str,
+    available_ids: Vec<&'static str>,
+}
+
+async fn list_demo_data() -> Json<DemoDataCatalogResponse> {
+    Json(DemoDataCatalogResponse {
+        default_id: DemoData::default_demo_data().id(),
+        available_ids: DemoData::available_demo_data()
+            .iter()
+            .map(|demo| demo.id())
+            .collect(),
+    })
+}
+
+async fn get_demo_data(Path(id): Path<String>) -> Result<Json<PlanDto>, StatusCode> {
+    let demo = id.parse::<DemoData>().map_err(|_| StatusCode::NOT_FOUND)?;
+    let plan = generate(demo);
+    Ok(Json(PlanDto::from_plan(&plan)))
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct CreateJobResponse {
+    id: String,
+}
+
+async fn create_job(
+    State(state): State<Arc<AppState>>,
+    Json(dto): Json<PlanDto>,
+) -> Result<Json<CreateJobResponse>, StatusCode> {
+    let plan = dto.to_domain().map_err(|_| StatusCode::BAD_REQUEST)?;
+    let id = state
+        .solver
+        .start_job(plan)
+        .map_err(status_from_solver_error)?;
+    Ok(Json(CreateJobResponse { id }))
+}
+
+async fn get_job(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<Json<JobSummaryDto>, StatusCode> {
+    let job_id = parse_job_id(&id)?;
+    let status = state
+        .solver
+        .get_status(&id)
+        .map_err(status_from_solver_error)?;
+    Ok(Json(JobSummaryDto::from_status(job_id, &status)))
+}
+
+async fn get_job_status(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<Json<JobSummaryDto>, StatusCode> {
+    get_job(State(state), Path(id)).await
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct SnapshotQuery {
+    snapshot_revision: Option<u64>,
+}
+
+async fn get_snapshot(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+    Query(query): Query<SnapshotQuery>,
+) -> Result<Json<JobSnapshotDto>, StatusCode> {
+    let snapshot = state
+        .solver
+        .get_snapshot(&id, query.snapshot_revision)
+        .map_err(status_from_solver_error)?;
+    Ok(Json(JobSnapshotDto::from_snapshot(&snapshot)))
+}
+
+async fn analyze_by_id(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+    Query(query): Query<SnapshotQuery>,
+) -> Result<Json<JobAnalysisDto>, StatusCode> {
+    let snapshot_analysis = state
+        .solver
+        .analyze_snapshot(&id, query.snapshot_revision)
+        .map_err(status_from_solver_error)?;
+    let analysis = analysis_response(&snapshot_analysis.analysis);
+    Ok(Json(JobAnalysisDto::from_snapshot_analysis(
+        &snapshot_analysis,
+        analysis,
+    )))
+}
+
+async fn pause_job(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<StatusCode, StatusCode> {
+    state.solver.pause(&id).map_err(status_from_solver_error)?;
+    Ok(StatusCode::ACCEPTED)
+}
+
+async fn resume_job(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<StatusCode, StatusCode> {
+    state.solver.resume(&id).map_err(status_from_solver_error)?;
+    Ok(StatusCode::ACCEPTED)
+}
+
+async fn cancel_job(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<StatusCode, StatusCode> {
+    state.solver.cancel(&id).map_err(status_from_solver_error)?;
+    Ok(StatusCode::ACCEPTED)
+}
+
+async fn delete_job(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<StatusCode, StatusCode> {
+    state.solver.delete(&id).map_err(status_from_solver_error)?;
+    Ok(StatusCode::NO_CONTENT)
+}
+
+fn parse_job_id(id: &str) -> Result<usize, StatusCode> {
+    id.parse::<usize>().map_err(|_| StatusCode::NOT_FOUND)
+}
+
+fn status_from_solver_error(error: solverforge::SolverManagerError) -> StatusCode {
+    match error {
+        solverforge::SolverManagerError::NoFreeJobSlots => StatusCode::SERVICE_UNAVAILABLE,
+        solverforge::SolverManagerError::JobNotFound { .. } => StatusCode::NOT_FOUND,
+        solverforge::SolverManagerError::InvalidStateTransition { .. } => StatusCode::CONFLICT,
+        solverforge::SolverManagerError::NoSnapshotAvailable { .. } => StatusCode::CONFLICT,
+        solverforge::SolverManagerError::SnapshotNotFound { .. } => StatusCode::NOT_FOUND,
+    }
+}

src/api/sse.rs

@@ -0,0 +1,65 @@
+use axum::{
+    body::Body,
+    extract::{Path, State},
+    http::{header, StatusCode},
+    response::Response,
+};
+use std::sync::Arc;
+use tokio_stream::wrappers::BroadcastStream;
+use tokio_stream::StreamExt;
+
+use super::routes::AppState;
+
+pub async fn events(
+    State(state): State<Arc<AppState>>,
+    Path(id): Path<String>,
+) -> Result<Response<Body>, StatusCode> {
+    let rx = state.solver.subscribe(&id).ok_or(StatusCode::NOT_FOUND)?;
+    let bootstrap_json = state
+        .solver
+        .bootstrap_event(&id)
+        .map_err(|_| StatusCode::NOT_FOUND)?;
+    let bootstrap_event_sequence = event_sequence_from_json(&bootstrap_json);
+    let bootstrap = tokio_stream::iter(std::iter::once(Ok::<_, std::convert::Infallible>(
+        format!("data: {}\n\n", bootstrap_json).into_bytes(),
+    )));
+
+    let live = BroadcastStream::new(rx).filter_map(move |msg| match msg {
+        Ok(json) => {
+            if event_is_not_newer(&json, bootstrap_event_sequence) {
+                return None;
+            }
+            Some(Ok::<_, std::convert::Infallible>(
+                format!("data: {}\n\n", json).into_bytes(),
+            ))
+        }
+        Err(_) => None, // Lagged - skip missed messages
+    });
+
+    let stream = bootstrap.chain(live);
+
+    Ok(Response::builder()
+        .header(header::CONTENT_TYPE, "text/event-stream")
+        .header(header::CACHE_CONTROL, "no-cache")
+        .header("X-Accel-Buffering", "no")
+        .body(Body::from_stream(stream))
+        .unwrap())
+}
+
+fn event_sequence_from_json(json: &str) -> Option<u64> {
+    serde_json::from_str::<serde_json::Value>(json)
+        .ok()
+        .and_then(|value| {
+            value
+                .get("eventSequence")
+                .and_then(serde_json::Value::as_u64)
+        })
+}
+
+fn event_is_not_newer(json: &str, bootstrap_event_sequence: Option<u64>) -> bool {
+    let Some(bootstrap_event_sequence) = bootstrap_event_sequence else {
+        return false;
+    };
+    event_sequence_from_json(json)
+        .is_some_and(|event_sequence| event_sequence <= bootstrap_event_sequence)
+}

src/constraints/mod.rs

@@ -0,0 +1,22 @@
+/* Constraint definitions.
+
+Add constraint modules with `solverforge generate constraint ...`.
+The neutral shell starts with an empty constraint set. */
+
+use crate::domain::Plan;
+use solverforge::prelude::*;
+
+pub use self::assemble::create_constraints;
+
+// @solverforge:begin constraint-modules
+// @solverforge:end constraint-modules
+
+mod assemble {
+    use super::*;
+
+    pub fn create_constraints() -> impl ConstraintSet<Plan, HardSoftScore> {
+        // @solverforge:begin constraint-calls
+        ()
+        // @solverforge:end constraint-calls
+    }
+}

src/data/data_seed.rs

@@ -0,0 +1,66 @@
+// @generated by solverforge-cli: data v1
+
+use std::str::FromStr;
+
+use crate::domain::Plan;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DemoData {
+    Small,
+    Standard,
+    Large,
+}
+
+const AVAILABLE_DEMO_DATA: &[DemoData] = &[DemoData::Small, DemoData::Standard, DemoData::Large];
+const DEFAULT_DEMO_DATA: DemoData = DemoData::Standard;
+
+pub fn default_demo_data() -> DemoData {
+    DEFAULT_DEMO_DATA
+}
+
+pub fn available_demo_data() -> &'static [DemoData] {
+    AVAILABLE_DEMO_DATA
+}
+
+impl DemoData {
+    pub fn id(self) -> &'static str {
+        match self {
+            DemoData::Small => "SMALL",
+            DemoData::Standard => "STANDARD",
+            DemoData::Large => "LARGE",
+        }
+    }
+
+    pub fn default_demo_data() -> Self {
+        default_demo_data()
+    }
+
+    pub fn available_demo_data() -> &'static [Self] {
+        available_demo_data()
+    }
+}
+
+impl FromStr for DemoData {
+    type Err = ();
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_ascii_uppercase().as_str() {
+            "SMALL" => Ok(DemoData::Small),
+            "STANDARD" => Ok(DemoData::Standard),
+            "LARGE" => Ok(DemoData::Large),
+            _ => Err(()),
+        }
+    }
+}
+
+pub fn generate(demo: DemoData) -> Plan {
+    match demo {
+        DemoData::Small => generate_plan(),
+        DemoData::Standard => generate_plan(),
+        DemoData::Large => generate_plan(),
+    }
+}
+
+fn generate_plan() -> Plan {
+    Plan::new()
+}

src/data/mod.rs

@@ -0,0 +1,3 @@
+mod data_seed;
+
+pub use data_seed::{available_demo_data, default_demo_data, generate, DemoData};

src/domain/mod.rs

@@ -0,0 +1,9 @@
+solverforge::planning_model! {
+    root = "src/domain";
+
+    // @solverforge:begin domain-exports
+    mod plan;
+
+    pub use plan::Plan;
+    // @solverforge:end domain-exports
+}

src/domain/plan.rs

@@ -0,0 +1,37 @@
+use serde::{Deserialize, Serialize};
+use solverforge::prelude::*;
+
+// @solverforge:neutral-solution
+// @solverforge:begin solution-imports
+// @solverforge:end solution-imports
+
+/// The root planning solution.
+///
+/// Fresh projects start as a neutral shell. Add fact collections, planning
+/// entity collections, and variable fields through the CLI as your domain
+/// takes shape.
+#[planning_solution(
+    constraints = "crate::constraints::create_constraints",
+    solver_toml = "../../solver.toml"
+)]
+#[derive(Serialize, Deserialize)]
+pub struct Plan {
+    // @solverforge:begin solution-collections
+    // @solverforge:end solution-collections
+    #[planning_score]
+    pub score: Option<HardSoftScore>,
+}
+
+impl Plan {
+    #[rustfmt::skip]
+    pub fn new(
+        // @solverforge:begin solution-constructor-params
+        // @solverforge:end solution-constructor-params
+    ) -> Self {
+        Self {
+            // @solverforge:begin solution-constructor-init
+            // @solverforge:end solution-constructor-init
+            score: None,
+        }
+    }
+}

src/lib.rs

@@ -0,0 +1,14 @@
+/* solverforge-fsr — neutral constraint optimizer built with SolverForge
+
+Structure:
+  domain/      — Plan (solution) plus CLI-generated entities and facts
+  constraints/ — Scoring rules
+  solver/      — Engine, service, termination config
+  api/         — HTTP API (axum)
+  data/        — Demo data / data loading */
+
+pub mod api;
+pub mod constraints;
+pub mod data;
+pub mod domain;
+pub mod solver;

src/main.rs

@@ -0,0 +1,38 @@
+/* solverforge-fsr — unified optimizer with SolverForge
+   Run with: solverforge server
+   Then open the printed local URL (default port 7860) */
+
+use solverforge_fsr::api;
+
+use std::net::SocketAddr;
+use std::sync::Arc;
+use tower_http::cors::{Any, CorsLayer};
+use tower_http::services::ServeDir;
+
+#[tokio::main]
+async fn main() {
+    solverforge::console::init();
+
+    let state = Arc::new(api::AppState::new());
+
+    let cors = CorsLayer::new()
+        .allow_origin(Any)
+        .allow_methods(Any)
+        .allow_headers(Any);
+
+    let app = api::router(state)
+        .merge(solverforge_ui::routes())
+        .fallback_service(ServeDir::new("static"))
+        .layer(cors);
+
+    let port = std::env::var("PORT")
+        .ok()
+        .and_then(|value| value.parse::<u16>().ok())
+        .unwrap_or(7860);
+    let addr = SocketAddr::from(([0, 0, 0, 0], port));
+    println!("▸ solverforge-fsr listening on http://{}", addr);
+    println!("▸ Open http://localhost:{} in your browser\n", port);
+
+    let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
+    axum::serve(listener, app).await.unwrap();
+}

src/solver/mod.rs

@@ -0,0 +1,4 @@
+mod service;
+
+pub use service::SolverService;
+pub use solverforge::SolverStatus;

src/solver/service.rs

@@ -0,0 +1,364 @@
+use parking_lot::RwLock;
+use serde::Serialize;
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::sync::{broadcast, mpsc};
+
+use solverforge::{
+    HardSoftScore, SolverEvent, SolverEventMetadata, SolverLifecycleState, SolverManager,
+    SolverManagerError, SolverSnapshot, SolverSnapshotAnalysis, SolverStatus, SolverTelemetry,
+    SolverTerminalReason,
+};
+
+use crate::api::PlanDto;
+use crate::domain::Plan;
+
+// Static manager — must be 'static for retained job execution.
+static MANAGER: SolverManager<Plan> = SolverManager::new();
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct TelemetryPayload {
+    elapsed_ms: u64,
+    step_count: u64,
+    moves_generated: u64,
+    moves_evaluated: u64,
+    moves_accepted: u64,
+    score_calculations: u64,
+    generation_ms: u64,
+    evaluation_ms: u64,
+    moves_per_second: u64,
+    acceptance_rate: f64,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct JobEventPayload {
+    id: String,
+    job_id: String,
+    event_type: &'static str,
+    event_sequence: u64,
+    lifecycle_state: &'static str,
+    terminal_reason: Option<&'static str>,
+    telemetry: TelemetryPayload,
+    current_score: Option<String>,
+    best_score: Option<String>,
+    snapshot_revision: Option<u64>,
+    solution: Option<PlanDto>,
+    error: Option<String>,
+}
+
+struct JobState {
+    sse_tx: broadcast::Sender<String>,
+}
+
+/// Manages retained solving jobs and broadcasts lifecycle-complete SSE payloads.
+pub struct SolverService {
+    jobs: Arc<RwLock<HashMap<usize, JobState>>>,
+}
+
+impl SolverService {
+    pub fn new() -> Self {
+        Self {
+            jobs: Arc::new(RwLock::new(HashMap::new())),
+        }
+    }
+
+    pub fn start_job(&self, plan: Plan) -> Result<String, SolverManagerError> {
+        let (job_id, receiver) = MANAGER.solve(plan)?;
+        let (sse_tx, _) = broadcast::channel(64);
+
+        self.jobs.write().insert(
+            job_id,
+            JobState {
+                sse_tx: sse_tx.clone(),
+            },
+        );
+
+        let jobs = Arc::clone(&self.jobs);
+        tokio::spawn(async move {
+            drain_receiver(jobs, job_id, sse_tx, receiver).await;
+        });
+
+        Ok(job_id.to_string())
+    }
+
+    pub fn subscribe(&self, id: &str) -> Option<broadcast::Receiver<String>> {
+        let job_id = parse_job_id(id).ok()?;
+        self.jobs
+            .read()
+            .get(&job_id)
+            .map(|state| state.sse_tx.subscribe())
+    }
+
+    pub fn bootstrap_event(&self, id: &str) -> Result<String, SolverManagerError> {
+        let job_id = parse_job_id(id)?;
+        let status = MANAGER.get_status(job_id)?;
+        if let Some(revision) = status.latest_snapshot_revision {
+            let snapshot = MANAGER.get_snapshot(job_id, Some(revision))?;
+            return Ok(snapshot_status_event_payload(
+                job_id,
+                bootstrap_snapshot_event_type(status.lifecycle_state),
+                &status,
+                &snapshot,
+            ));
+        }
+
+        Ok(status_event_payload(
+            job_id,
+            bootstrap_event_type(status.lifecycle_state),
+            &status,
+        ))
+    }
+
+    pub fn get_status(&self, id: &str) -> Result<SolverStatus<HardSoftScore>, SolverManagerError> {
+        let job_id = parse_job_id(id)?;
+        MANAGER.get_status(job_id)
+    }
+
+    pub fn pause(&self, id: &str) -> Result<(), SolverManagerError> {
+        MANAGER.pause(parse_job_id(id)?)
+    }
+
+    pub fn resume(&self, id: &str) -> Result<(), SolverManagerError> {
+        MANAGER.resume(parse_job_id(id)?)
+    }
+
+    pub fn cancel(&self, id: &str) -> Result<(), SolverManagerError> {
+        MANAGER.cancel(parse_job_id(id)?)
+    }
+
+    pub fn delete(&self, id: &str) -> Result<(), SolverManagerError> {
+        let job_id = parse_job_id(id)?;
+        MANAGER.delete(job_id)?;
+        self.jobs.write().remove(&job_id);
+        Ok(())
+    }
+
+    pub fn get_snapshot(
+        &self,
+        id: &str,
+        snapshot_revision: Option<u64>,
+    ) -> Result<SolverSnapshot<Plan>, SolverManagerError> {
+        MANAGER.get_snapshot(parse_job_id(id)?, snapshot_revision)
+    }
+
+    pub fn analyze_snapshot(
+        &self,
+        id: &str,
+        snapshot_revision: Option<u64>,
+    ) -> Result<SolverSnapshotAnalysis<HardSoftScore>, SolverManagerError> {
+        MANAGER.analyze_snapshot(parse_job_id(id)?, snapshot_revision)
+    }
+}
+
+async fn drain_receiver(
+    jobs: Arc<RwLock<HashMap<usize, JobState>>>,
+    job_id: usize,
+    sse_tx: broadcast::Sender<String>,
+    mut receiver: mpsc::UnboundedReceiver<SolverEvent<Plan>>,
+) {
+    while let Some(event) = receiver.recv().await {
+        let payload = match &event {
+            SolverEvent::Progress { metadata } => {
+                event_payload(job_id, "progress", metadata, None, None)
+            }
+            SolverEvent::BestSolution { metadata, solution } => {
+                event_payload(job_id, "best_solution", metadata, Some(solution), None)
+            }
+            SolverEvent::PauseRequested { metadata } => {
+                event_payload(job_id, "pause_requested", metadata, None, None)
+            }
+            SolverEvent::Paused { metadata } => {
+                event_payload(job_id, "paused", metadata, None, None)
+            }
+            SolverEvent::Resumed { metadata } => {
+                event_payload(job_id, "resumed", metadata, None, None)
+            }
+            SolverEvent::Completed { metadata, solution } => {
+                event_payload(job_id, "completed", metadata, Some(solution), None)
+            }
+            SolverEvent::Cancelled { metadata } => {
+                event_payload(job_id, "cancelled", metadata, None, None)
+            }
+            SolverEvent::Failed { metadata, error } => {
+                event_payload(job_id, "failed", metadata, None, Some(error.as_str()))
+            }
+        };
+
+        if !jobs.read().contains_key(&job_id) {
+            return;
+        }
+
+        let _ = sse_tx.send(payload);
+    }
+}
+
+fn parse_job_id(id: &str) -> Result<usize, SolverManagerError> {
+    id.parse::<usize>()
+        .map_err(|_| SolverManagerError::JobNotFound { job_id: usize::MAX })
+}
+
+fn status_event_payload(
+    job_id: usize,
+    event_type: &'static str,
+    status: &SolverStatus<HardSoftScore>,
+) -> String {
+    serialize_payload(JobEventPayload {
+        id: job_id.to_string(),
+        job_id: job_id.to_string(),
+        event_type,
+        event_sequence: status.event_sequence,
+        lifecycle_state: lifecycle_state_label(status.lifecycle_state),
+        terminal_reason: status.terminal_reason.map(terminal_reason_label),
+        telemetry: telemetry_payload(&status.telemetry),
+        current_score: status.current_score.map(|score| score.to_string()),
+        best_score: status.best_score.map(|score| score.to_string()),
+        snapshot_revision: status.latest_snapshot_revision,
+        solution: None,
+        error: None,
+    })
+}
+
+fn snapshot_status_event_payload(
+    job_id: usize,
+    event_type: &'static str,
+    status: &SolverStatus<HardSoftScore>,
+    snapshot: &SolverSnapshot<Plan>,
+) -> String {
+    serialize_payload(JobEventPayload {
+        id: job_id.to_string(),
+        job_id: job_id.to_string(),
+        event_type,
+        event_sequence: status.event_sequence,
+        lifecycle_state: lifecycle_state_label(status.lifecycle_state),
+        terminal_reason: status.terminal_reason.map(terminal_reason_label),
+        telemetry: telemetry_payload(&status.telemetry),
+        current_score: status
+            .current_score
+            .or(snapshot.current_score)
+            .map(|score| score.to_string()),
+        best_score: status
+            .best_score
+            .or(snapshot.best_score)
+            .map(|score| score.to_string()),
+        snapshot_revision: Some(snapshot.snapshot_revision),
+        solution: Some(PlanDto::from_plan(&snapshot.solution)),
+        error: None,
+    })
+}
+
+fn bootstrap_event_type(state: SolverLifecycleState) -> &'static str {
+    match state {
+        SolverLifecycleState::Solving => "progress",
+        SolverLifecycleState::PauseRequested => "pause_requested",
+        SolverLifecycleState::Paused => "paused",
+        SolverLifecycleState::Completed => "completed",
+        SolverLifecycleState::Cancelled => "cancelled",
+        SolverLifecycleState::Failed => "failed",
+    }
+}
+
+fn bootstrap_snapshot_event_type(state: SolverLifecycleState) -> &'static str {
+    match state {
+        SolverLifecycleState::Solving => "best_solution",
+        other => bootstrap_event_type(other),
+    }
+}
+
+fn event_payload(
+    job_id: usize,
+    event_type: &'static str,
+    metadata: &SolverEventMetadata<HardSoftScore>,
+    solution: Option<&Plan>,
+    error: Option<&str>,
+) -> String {
+    serialize_payload(JobEventPayload {
+        id: job_id.to_string(),
+        job_id: job_id.to_string(),
+        event_type,
+        event_sequence: metadata.event_sequence,
+        lifecycle_state: lifecycle_state_label(metadata.lifecycle_state),
+        terminal_reason: metadata.terminal_reason.map(terminal_reason_label),
+        telemetry: telemetry_payload(&metadata.telemetry),
+        current_score: metadata.current_score.map(|score| score.to_string()),
+        best_score: metadata.best_score.map(|score| score.to_string()),
+        snapshot_revision: metadata.snapshot_revision,
+        solution: solution.map(PlanDto::from_plan),
+        error: error.map(ToOwned::to_owned),
+    })
+}
+
+fn serialize_payload(payload: JobEventPayload) -> String {
+    serde_json::to_string(&payload).expect("failed to serialize solver lifecycle payload")
+}
+
+fn telemetry_payload(telemetry: &SolverTelemetry) -> TelemetryPayload {
+    TelemetryPayload {
+        elapsed_ms: duration_to_millis(telemetry.elapsed),
+        step_count: telemetry.step_count,
+        moves_generated: telemetry.moves_generated,
+        moves_evaluated: telemetry.moves_evaluated,
+        moves_accepted: telemetry.moves_accepted,
+        score_calculations: telemetry.score_calculations,
+        generation_ms: duration_to_millis(telemetry.generation_time),
+        evaluation_ms: duration_to_millis(telemetry.evaluation_time),
+        moves_per_second: whole_units_per_second(telemetry.moves_evaluated, telemetry.elapsed),
+        acceptance_rate: derive_acceptance_rate(
+            telemetry.moves_accepted,
+            telemetry.moves_evaluated,
+        ),
+    }
+}
+
+fn lifecycle_state_label(state: SolverLifecycleState) -> &'static str {
+    match state {
+        SolverLifecycleState::Solving => "SOLVING",
+        SolverLifecycleState::PauseRequested => "PAUSE_REQUESTED",
+        SolverLifecycleState::Paused => "PAUSED",
+        SolverLifecycleState::Completed => "COMPLETED",
+        SolverLifecycleState::Cancelled => "CANCELLED",
+        SolverLifecycleState::Failed => "FAILED",
+    }
+}
+
+fn terminal_reason_label(reason: SolverTerminalReason) -> &'static str {
+    match reason {
+        SolverTerminalReason::Completed => "completed",
+        SolverTerminalReason::TerminatedByConfig => "terminated_by_config",
+        SolverTerminalReason::Cancelled => "cancelled",
+        SolverTerminalReason::Failed => "failed",
+    }
+}
+
+impl Default for SolverService {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+fn duration_to_millis(duration: Duration) -> u64 {
+    duration.as_millis().min(u128::from(u64::MAX)) as u64
+}
+
+fn whole_units_per_second(count: u64, elapsed: Duration) -> u64 {
+    let nanos = elapsed.as_nanos();
+    if nanos == 0 {
+        0
+    } else {
+        let per_second = u128::from(count)
+            .saturating_mul(1_000_000_000)
+            .checked_div(nanos)
+            .unwrap_or(0);
+        per_second.min(u128::from(u64::MAX)) as u64
+    }
+}
+
+fn derive_acceptance_rate(moves_accepted: u64, moves_evaluated: u64) -> f64 {
+    if moves_evaluated == 0 {
+        0.0
+    } else {
+        moves_accepted as f64 / moves_evaluated as f64
+    }
+}

static/app.js

@@ -0,0 +1,808 @@
+/* app.js — solverforge-fsr SolverForge UI */
+
+(async function () {
+  'use strict';
+
+  var SLOT_MINUTES = 60;
+  var DEFAULT_VIEWPORT_SLOTS = 12;
+  var TIMELINE_TONES = ['emerald', 'blue', 'amber', 'rose', 'violet', 'slate'];
+
+  var config = await fetch('/sf-config.json').then(function (response) { return response.json(); });
+  var uiModel = await fetch('/generated/ui-model.json').then(function (response) { return response.json(); });
+  var app = document.getElementById('sf-app');
+  var backend = SF.createBackend({ baseUrl: '' });
+  var statusBar = SF.createStatusBar({ constraints: uiModel.constraints || [] });
+  var currentPlan = null;
+  var lastAnalysis = null;
+  var bootstrapError = null;
+  var demoCatalog = { defaultId: null, availableIds: [] };
+  var activeTab = (uiModel.views && uiModel.views.length) ? uiModel.views[0].id : 'overview';
+  var viewPanels = {};
+  var viewTimelines = {};
+
+  var tabs = (uiModel.views || []).map(function (view, index) {
+    return {
+      id: view.id,
+      label: view.label,
+      icon: view.kind === 'list' ? 'fa-list-ol' : 'fa-table-cells-large',
+      active: index === 0,
+    };
+  });
+  if (!tabs.length) {
+    tabs.push({ id: 'overview', label: 'Overview', icon: 'fa-compass', active: true });
+  }
+  tabs.push({ id: 'data', label: 'Data', icon: 'fa-table' });
+  tabs.push({ id: 'api', label: 'REST API', icon: 'fa-book' });
+
+  var header = SF.createHeader({
+    logo: '/sf/img/ouroboros.svg',
+    title: config.title,
+    subtitle: config.subtitle,
+    tabs: tabs,
+    actions: {
+      onSolve: function () { loadAndSolve(); },
+      onPause: function () { pauseSolve(); },
+      onResume: function () { resumeSolve(); },
+      onCancel: function () { cancelSolve(); },
+      onAnalyze: function () { openAnalysis(); },
+    },
+    onTabChange: function (tab) {
+      activeTab = tab;
+      Object.keys(viewPanels).forEach(function (key) {
+        viewPanels[key].style.display = key === tab ? '' : 'none';
+      });
+      overviewPanel.style.display = tab === 'overview' ? '' : 'none';
+      dataPanel.style.display = tab === 'data' ? '' : 'none';
+      apiPanel.style.display = tab === 'api' ? '' : 'none';
+    },
+  });
+  app.appendChild(header);
+  statusBar.bindHeader(header);
+  app.appendChild(statusBar.el);
+
+  var bootstrapNotice = SF.el('div', {
+    className: 'sf-content',
+    style: {
+      display: 'none',
+      padding: '16px',
+      marginBottom: '16px',
+      borderRadius: '12px',
+      border: '1px solid #dc2626',
+      background: '#fef2f2',
+      color: '#991b1b',
+    },
+  });
+  app.appendChild(bootstrapNotice);
+
+  var overviewPanel = SF.el('div', { className: 'sf-content', style: { display: activeTab === 'overview' ? '' : 'none' } });
+  var overviewContainer = SF.el('div', { id: 'sf-overview' });
+  overviewPanel.appendChild(overviewContainer);
+  app.appendChild(overviewPanel);
+
+  (uiModel.views || []).forEach(function (view) {
+    var panel = SF.el('div', { className: 'sf-content', style: { display: activeTab === view.id ? '' : 'none' } });
+    panel.appendChild(SF.el('div', { id: 'view-' + view.id }));
+    viewPanels[view.id] = panel;
+    app.appendChild(panel);
+  });
+
+  var dataPanel = SF.el('div', { className: 'sf-content', style: { display: 'none' } });
+  var tablesContainer = SF.el('div', { id: 'sf-tables' });
+  dataPanel.appendChild(tablesContainer);
+  app.appendChild(dataPanel);
+
+  var apiPanel = SF.el('div', { className: 'sf-content', style: { display: 'none' } });
+  var apiGuideContainer = SF.el('div');
+  apiPanel.appendChild(apiGuideContainer);
+  app.appendChild(apiPanel);
+
+  app.appendChild(SF.createFooter({
+    links: [
+      { label: 'SolverForge', url: 'https://www.solverforge.org' },
+      { label: 'Docs', url: 'https://www.solverforge.org/docs' },
+    ],
+  }));
+
+  var analysisModal = SF.createModal({ title: 'Score Analysis', width: '700px' });
+  var solver = SF.createSolver({
+    backend: backend,
+    statusBar: statusBar,
+    onProgress: function (meta) {
+      syncLifecycleMarkers(meta);
+    },
+    onPauseRequested: function (meta) {
+      syncLifecycleMarkers(meta);
+    },
+    onSolution: function (snapshot, meta) {
+      if (snapshot && snapshot.solution) {
+        renderAll(snapshot.solution);
+      }
+      syncLifecycleMarkers(meta);
+    },
+    onPaused: function (snapshot, meta) {
+      if (snapshot && snapshot.solution) {
+        renderAll(snapshot.solution);
+      }
+      syncLifecycleMarkers(meta);
+    },
+    onResumed: function (meta) {
+      syncLifecycleMarkers(meta);
+    },
+    onCancelled: function (snapshot, meta) {
+      if (snapshot && snapshot.solution) {
+        renderAll(snapshot.solution);
+      }
+      syncLifecycleMarkers(meta);
+    },
+    onComplete: function (snapshot, meta) {
+      if (snapshot && snapshot.solution) {
+        renderAll(snapshot.solution);
+      }
+      syncLifecycleMarkers(meta);
+    },
+    onFailure: function (message, meta, snapshot, analysis) {
+      if (snapshot && snapshot.solution) {
+        renderAll(snapshot.solution);
+      }
+      if (analysis) {
+        lastAnalysis = analysis;
+      }
+      console.error('Solver job failed:', message);
+      syncLifecycleMarkers(meta);
+    },
+    onAnalysis: function (analysis) {
+      lastAnalysis = analysis;
+      syncLifecycleMarkers();
+    },
+    onError: function (message) {
+      console.error('Solver lifecycle failed:', message);
+      syncLifecycleMarkers();
+    },
+  });
+  renderApiGuide();
+  updateSolveActionAvailability();
+  bootstrapDemoData();
+
+  window.addEventListener('beforeunload', destroyAllTimelines);
+
+  function loadAndSolve() {
+    if (solver.isRunning() || solver.getLifecycleState() === 'PAUSED' || !canSolve()) return;
+    cleanupTerminalJob()
+      .then(function (data) {
+        return data || resolvePlanForSolve();
+      })
+      .then(function (data) {
+        return solver.start(data);
+      })
+      .then(function () {
+        syncLifecycleMarkers();
+      })
+      .catch(function (err) { console.error('Solve start failed:', err); });
+  }
+
+  function pauseSolve() {
+    solver.pause()
+      .then(function () { syncLifecycleMarkers(); })
+      .catch(function (err) { console.error('Pause failed:', err); });
+  }
+
+  function resumeSolve() {
+    solver.resume()
+      .then(function () { syncLifecycleMarkers(); })
+      .catch(function (err) { console.error('Resume failed:', err); });
+  }
+
+  function cancelSolve() {
+    solver.cancel()
+      .then(function () { syncLifecycleMarkers(); })
+      .catch(function (err) { console.error('Cancel failed:', err); });
+  }
+
+  function openAnalysis() {
+    if (!solver.getJobId()) return;
+    solver.analyzeSnapshot()
+      .then(function (analysis) {
+        lastAnalysis = analysis;
+        analysisModal.setBody(buildAnalysisHtml(analysis));
+        analysisModal.open();
+      })
+      .catch(function () {});
+  }
+
+  function renderAll(data) {
+    currentPlan = clonePlan(data);
+    renderOverview(data);
+    renderViews(data);
+    renderTables(data);
+  }
+
+  function resolvePlanForSolve() {
+    if (currentPlan) {
+      return Promise.resolve(clonePlan(currentPlan));
+    }
+    if (!demoCatalog.defaultId) {
+      return Promise.reject(new Error('demo data catalog is unavailable'));
+    }
+    return fetchDemoPlan(demoCatalog.defaultId);
+  }
+
+  function bootstrapDemoData() {
+    fetchDemoCatalog()
+      .then(function (catalog) {
+        demoCatalog = catalog;
+        clearBootstrapError();
+        renderApiGuide();
+        return fetchDemoPlan(catalog.defaultId);
+      })
+      .then(function (data) {
+        renderAll(data);
+        updateSolveActionAvailability();
+      })
+      .catch(function (err) {
+        reportBootstrapError(err);
+      });
+  }
+
+  function fetchDemoCatalog() {
+    return requestJson('/demo-data', 'demo data catalog')
+      .then(function (catalog) {
+        if (!catalog || typeof catalog.defaultId !== 'string' || !Array.isArray(catalog.availableIds)) {
+          throw new Error('demo data catalog is missing defaultId or availableIds');
+        }
+        if (catalog.availableIds.indexOf(catalog.defaultId) === -1) {
+          throw new Error('demo data catalog defaultId is not present in availableIds');
+        }
+        return {
+          defaultId: catalog.defaultId,
+          availableIds: catalog.availableIds.slice(),
+        };
+      });
+  }
+
+  function fetchDemoPlan(demoId) {
+    return requestJson('/demo-data/' + encodeURIComponent(demoId), 'demo data "' + demoId + '"');
+  }
+
+  function requestJson(path, label) {
+    return fetch(path)
+      .then(function (response) {
+        if (!response.ok) {
+          throw new Error(label + ' returned HTTP ' + response.status);
+        }
+        return response.json();
+      });
+  }
+
+  function canSolve() {
+    return !bootstrapError && !!demoCatalog.defaultId;
+  }
+
+  function reportBootstrapError(err) {
+    bootstrapError = describeError(err);
+    bootstrapNotice.textContent = 'Demo data bootstrap failed: ' + bootstrapError;
+    bootstrapNotice.style.display = '';
+    app.dataset.bootstrapError = 'true';
+    renderApiGuide();
+    updateSolveActionAvailability();
+    console.error('Demo data bootstrap failed:', err);
+  }
+
+  function clearBootstrapError() {
+    bootstrapError = null;
+    bootstrapNotice.textContent = '';
+    bootstrapNotice.style.display = 'none';
+    delete app.dataset.bootstrapError;
+  }
+
+  function describeError(err) {
+    if (err && err.message) {
+      return err.message;
+    }
+    return String(err || 'unknown error');
+  }
+
+  function updateSolveActionAvailability() {
+    var solveButton = findHeaderButton('Solve');
+    var disabled = !canSolve();
+    if (!solveButton) return;
+    solveButton.disabled = disabled;
+    solveButton.setAttribute('aria-disabled', disabled ? 'true' : 'false');
+    solveButton.title = disabled
+      ? (bootstrapError ? 'Demo data bootstrap failed.' : 'Loading demo data catalog...')
+      : '';
+  }
+
+  function findHeaderButton(label) {
+    var buttons = header.querySelectorAll('button');
+    for (var i = 0; i < buttons.length; i += 1) {
+      var text = (buttons[i].textContent || '').trim();
+      if (text === label) {
+        return buttons[i];
+      }
+    }
+    return null;
+  }
+
+  function renderApiGuide() {
+    apiGuideContainer.innerHTML = '';
+    apiGuideContainer.appendChild(SF.createApiGuide({
+      endpoints: buildApiGuideEndpoints(),
+    }));
+  }
+
+  function buildApiGuideEndpoints() {
+    var defaultDemoPath = demoCatalog.defaultId
+      ? '/demo-data/' + demoCatalog.defaultId
+      : '/demo-data/{defaultId}';
+    return [
+      { method: 'GET', path: '/demo-data', description: 'Discover the default and available demo data IDs', curl: buildCurlCommand('GET', '/demo-data') },
+      { method: 'GET', path: defaultDemoPath, description: 'Fetch the discovered default demo data', curl: buildCurlCommand('GET', defaultDemoPath) },
+      { method: 'POST', path: '/jobs', description: 'Create a retained solving job', curl: buildCurlCommand('POST', '/jobs', { json: true, data: '@plan.json' }) },
+      { method: 'GET', path: '/jobs/{id}', description: 'Get current job summary', curl: buildCurlCommand('GET', '/jobs/{id}') },
+      { method: 'GET', path: '/jobs/{id}/snapshot', description: 'Fetch the latest retained snapshot', curl: buildCurlCommand('GET', '/jobs/{id}/snapshot') },
+      { method: 'GET', path: '/jobs/{id}/analysis?snapshot_revision={n}', description: 'Analyze an exact snapshot revision', curl: buildCurlCommand('GET', '/jobs/{id}/analysis?snapshot_revision=3', { quoteUrl: true }) },
+      { method: 'POST', path: '/jobs/{id}/pause', description: 'Request an exact runtime pause', curl: buildCurlCommand('POST', '/jobs/{id}/pause') },
+      { method: 'POST', path: '/jobs/{id}/resume', description: 'Resume a paused retained job', curl: buildCurlCommand('POST', '/jobs/{id}/resume') },
+      { method: 'POST', path: '/jobs/{id}/cancel', description: 'Cancel a live or paused job', curl: buildCurlCommand('POST', '/jobs/{id}/cancel') },
+      { method: 'DELETE', path: '/jobs/{id}', description: 'Delete a terminal retained job', curl: buildCurlCommand('DELETE', '/jobs/{id}') },
+      { method: 'GET', path: '/jobs/{id}/events', description: 'Stream job lifecycle updates (SSE)', curl: buildCurlCommand('GET', '/jobs/{id}/events', { stream: true }) },
+    ];
+  }
+
+  function buildCurlCommand(method, path, options) {
+    var parts = ['curl'];
+    if (options && options.stream) {
+      parts.push('-N');
+    }
+    if (method && method !== 'GET') {
+      parts.push('-X', method);
+    }
+    if (options && options.json) {
+      parts.push('-H', '"Content-Type: application/json"');
+    }
+
+    var url = buildApiUrl(path);
+    parts.push(options && options.quoteUrl ? '"' + url + '"' : url);
+
+    if (options && options.data) {
+      parts.push('-d', options.data);
+    }
+
+    return parts.join(' ');
+  }
+
+  function buildApiUrl(path) {
+    return currentOrigin() + path;
+  }
+
+  function currentOrigin() {
+    return window.location.origin || (window.location.protocol + '//' + window.location.host);
+  }
+
+  function cleanupTerminalJob() {
+    var state = solver.getLifecycleState();
+    if (!solver.getJobId() || state === 'IDLE' || state === 'PAUSED' || solver.isRunning()) {
+      return Promise.resolve(null);
+    }
+    return solver.delete()
+      .then(function () {
+        lastAnalysis = null;
+        syncLifecycleMarkers();
+        return null;
+      })
+      .catch(function (err) {
+        console.error('Delete failed:', err);
+        throw err;
+      });
+  }
+
+  function syncLifecycleMarkers(meta) {
+    var jobId = solver.getJobId();
+    var snapshotRevision = solver.getSnapshotRevision();
+    var lifecycleState = meta && meta.lifecycleState ? meta.lifecycleState : solver.getLifecycleState();
+
+    if (jobId) {
+      app.dataset.jobId = String(jobId);
+    } else {
+      delete app.dataset.jobId;
+    }
+    if (snapshotRevision != null) {
+      app.dataset.snapshotRevision = String(snapshotRevision);
+    } else {
+      delete app.dataset.snapshotRevision;
+    }
+    if (lifecycleState && lifecycleState !== 'IDLE') {
+      app.dataset.lifecycleState = lifecycleState;
+    } else {
+      delete app.dataset.lifecycleState;
+    }
+    updateSolveActionAvailability();
+  }
+
+  function clonePlan(data) {
+    return JSON.parse(JSON.stringify(data));
+  }
+
+  function renderOverview(data) {
+    overviewContainer.innerHTML = '';
+    if ((uiModel.views || []).length) {
+      overviewContainer.appendChild(SF.el(
+        'p',
+        null,
+        'The generated views now mount the canonical solverforge-ui timeline surface for every planning variable declared in your project.'
+      ));
+      overviewContainer.appendChild(SF.createTable({
+        columns: ['Active views', 'Constraints', 'Current score'],
+        rows: [[
+          String(uiModel.views.length),
+          String((uiModel.constraints || []).length),
+          String(data.score || '—'),
+        ]],
+      }));
+      return;
+    }
+    overviewContainer.appendChild(SF.el('p', null, 'No planning variables are declared yet. Use `solverforge generate entity`, `generate fact`, and `generate variable` to shape the app.'));
+  }
+
+  function renderViews(data) {
+    (uiModel.views || []).forEach(function (view) {
+      var container = document.getElementById('view-' + view.id);
+      if (!container) return;
+      if (view.kind === 'list') {
+        renderTimelinePanel(
+          container,
+          view.id,
+          buildListViewPayload(data, view),
+          'This list-variable timeline will appear once the referenced facts and entities contain data.'
+        );
+      } else {
+        renderTimelinePanel(
+          container,
+          view.id,
+          buildScalarViewPayload(data, view),
+          'This scalar-variable timeline will appear once the referenced facts and entities contain data.'
+        );
+      }
+    });
+  }
+
+  function renderTimelinePanel(container, viewId, payload, emptyMessage) {
+    container.innerHTML = '';
+    if (!payload) {
+      destroyTimeline(viewId);
+      container.appendChild(SF.el('p', null, emptyMessage));
+      return;
+    }
+
+    container.appendChild(payload.summary);
+    container.appendChild(ensureTimeline(viewId, payload.timeline).el);
+  }
+
+  function ensureTimeline(viewId, timelineConfig) {
+    var timeline = viewTimelines[viewId];
+    if (!timeline) {
+      timeline = SF.rail.createTimeline(timelineConfig);
+      viewTimelines[viewId] = timeline;
+      return timeline;
+    }
+
+    timeline.setModel(timelineConfig.model);
+    return timeline;
+  }
+
+  function destroyTimeline(viewId) {
+    var timeline = viewTimelines[viewId];
+    if (!timeline) return;
+    timeline.destroy();
+    delete viewTimelines[viewId];
+  }
+
+  function destroyAllTimelines() {
+    Object.keys(viewTimelines).forEach(function (viewId) {
+      destroyTimeline(viewId);
+    });
+  }
+
+  function buildScalarViewPayload(data, view) {
+    var entities = data[view.entityPlural] || [];
+    var facts = data[view.sourcePlural] || [];
+    if (!entities.length || !facts.length) return null;
+
+    var byIndex = {};
+    facts.forEach(function (fact, index) {
+      byIndex[index] = fact;
+    });
+
+    var assignments = facts.map(function () { return []; });
+    var detached = [];
+    entities.forEach(function (entity) {
+      var idx = entity[view.variableField];
+      if (idx == null || byIndex[idx] == null) {
+        detached.push(entity);
+        return;
+      }
+      assignments[idx].push(entity);
+    });
+
+    var peakLoad = assignments.reduce(function (maxCount, items) {
+      return Math.max(maxCount, items.length);
+    }, 0);
+    var horizon = Math.max(peakLoad, detached.length, 1);
+    var axis = buildSlotAxis(horizon);
+    var lanes = facts.map(function (fact, factIndex) {
+      var items = assignments[factIndex] || [];
+      return {
+        id: view.id + '-lane-' + factIndex,
+        label: String(factLabel(fact, factIndex)),
+        mode: 'detailed',
+        badges: items.length ? [] : ['Empty'],
+        stats: [{ label: title(view.entityPlural), value: items.length }],
+        items: items.map(function (entity, itemIndex) {
+          return buildTimelineItem(
+            view.id + '-fact-' + factIndex + '-entity-' + itemIndex,
+            itemIndex,
+            entityLabel(entity, itemIndex),
+            'Assignment ' + String(itemIndex + 1),
+            entityLabel(entity, itemIndex)
+          );
+        }),
+      };
+    });
+
+    if (detached.length) {
+      lanes.push({
+        id: view.id + '-detached',
+        label: view.allowsUnassigned ? 'Unassigned' : 'Unmapped',
+        mode: 'detailed',
+        badges: [view.allowsUnassigned ? 'Needs assignment' : 'Out of range'],
+        stats: [{ label: title(view.entityPlural), value: detached.length }],
+        items: detached.map(function (entity, itemIndex) {
+          return buildTimelineItem(
+            view.id + '-detached-' + itemIndex,
+            itemIndex,
+            entityLabel(entity, itemIndex),
+            view.allowsUnassigned ? 'Awaiting assignment' : 'Invalid source index',
+            entityLabel(entity, itemIndex)
+          );
+        }),
+      });
+    }
+
+    return {
+      summary: buildSummarySection(
+        ['Source lanes', title(view.entityPlural), 'Peak load', 'Unassigned'],
+        [
+          String(facts.length),
+          String(entities.length),
+          String(peakLoad),
+          String(detached.length),
+        ]
+      ),
+      timeline: {
+        label: title(view.sourcePlural),
+        labelWidth: 280,
+        title: view.label,
+        subtitle: title(view.entityPlural) + ' grouped by ' + title(view.sourcePlural),
+        model: {
+          axis: axis,
+          lanes: lanes,
+        },
+      },
+    };
+  }
+
+  function buildListViewPayload(data, view) {
+    var entities = data[view.entityPlural] || [];
+    var facts = data[view.sourcePlural] || [];
+    if (!entities.length || !facts.length) return null;
+
+    var byIndex = {};
+    facts.forEach(function (fact, index) {
+      byIndex[index] = fact;
+    });
+
+    var rows = entities.map(function (entity, entityIndex) {
+      var sequence = Array.isArray(entity[view.variableField]) ? entity[view.variableField] : [];
+      return {
+        entity: entity,
+        entityIndex: entityIndex,
+        sequence: sequence,
+      };
+    });
+
+    rows.sort(function (left, right) {
+      if (right.sequence.length !== left.sequence.length) {
+        return right.sequence.length - left.sequence.length;
+      }
+      return String(entityLabel(left.entity, left.entityIndex)).localeCompare(
+        String(entityLabel(right.entity, right.entityIndex))
+      );
+    });
+
+    var totalItems = rows.reduce(function (sum, row) {
+      return sum + row.sequence.length;
+    }, 0);
+    var longestSequence = rows.reduce(function (maxCount, row) {
+      return Math.max(maxCount, row.sequence.length);
+    }, 0);
+    var emptyEntities = rows.filter(function (row) { return row.sequence.length === 0; }).length;
+    var horizon = Math.max(longestSequence, 1);
+    var axis = buildSlotAxis(horizon);
+
+    var lanes = rows.map(function (row) {
+      return {
+        id: view.id + '-entity-' + row.entityIndex,
+        label: entityLabel(row.entity, row.entityIndex),
+        mode: 'detailed',
+        badges: listLaneBadges(row.sequence.length, longestSequence),
+        stats: [{ label: title(view.sourcePlural), value: row.sequence.length }],
+        items: row.sequence.map(function (factIndex, sequenceIndex) {
+          var fact = byIndex[factIndex];
+          return buildTimelineItem(
+            view.id + '-entity-' + row.entityIndex + '-item-' + sequenceIndex,
+            sequenceIndex,
+            factLabel(fact, factIndex),
+            'Position ' + String(sequenceIndex + 1),
+            factLabel(fact, factIndex)
+          );
+        }),
+      };
+    });
+
+    return {
+      summary: buildSummarySection(
+        [title(view.entityPlural), title(view.sourcePlural), 'Longest sequence', 'Empty lanes', 'Average items / lane'],
+        [
+          String(rows.length),
+          String(totalItems),
+          String(longestSequence),
+          String(emptyEntities),
+          rows.length ? (totalItems / rows.length).toFixed(1) : '0.0',
+        ]
+      ),
+      timeline: {
+        label: title(view.entityPlural),
+        labelWidth: 280,
+        title: view.label,
+        subtitle: title(view.sourcePlural) + ' ordered inside each ' + title(view.entityPlural),
+        model: {
+          axis: axis,
+          lanes: lanes,
+        },
+      },
+    };
+  }
+
+  function buildSummarySection(columns, row) {
+    var section = SF.el('div', { className: 'sf-section' });
+    section.appendChild(SF.createTable({
+      columns: columns,
+      rows: [row],
+    }));
+    return section;
+  }
+
+  function buildSlotAxis(slotCount) {
+    var normalizedSlots = Math.max(slotCount, 1);
+    var groupSize = normalizedSlots > 24 ? 8 : (normalizedSlots > 12 ? 6 : 4);
+    var days = [];
+    var ticks = [];
+
+    for (var startSlot = 0; startSlot < normalizedSlots; startSlot += groupSize) {
+      var endSlot = Math.min(normalizedSlots, startSlot + groupSize);
+      days.push({
+        id: 'window-' + startSlot,
+        label: 'Window ' + String(days.length + 1),
+        subLabel: slotRangeLabel(startSlot, endSlot),
+        startMinute: startSlot * SLOT_MINUTES,
+        endMinute: endSlot * SLOT_MINUTES,
+      });
+    }
+
+    for (var slotIndex = 0; slotIndex < normalizedSlots; slotIndex += 1) {
+      ticks.push({
+        id: 'tick-' + slotIndex,
+        minute: slotIndex * SLOT_MINUTES,
+        label: 'Slot ' + String(slotIndex + 1),
+      });
+    }
+
+    return {
+      startMinute: 0,
+      endMinute: normalizedSlots * SLOT_MINUTES,
+      days: days,
+      ticks: ticks,
+      initialViewport: {
+        startMinute: 0,
+        endMinute: Math.min(normalizedSlots, DEFAULT_VIEWPORT_SLOTS) * SLOT_MINUTES,
+      },
+    };
+  }
+
+  function buildTimelineItem(id, slotIndex, label, meta, toneKey) {
+    return {
+      id: id,
+      startMinute: slotIndex * SLOT_MINUTES,
+      endMinute: (slotIndex + 1) * SLOT_MINUTES,
+      label: String(label),
+      meta: meta || '',
+      tone: toneForKey(toneKey || label),
+    };
+  }
+
+  function slotRangeLabel(startSlot, endSlot) {
+    if (endSlot - startSlot <= 1) {
+      return 'Slot ' + String(startSlot + 1);
+    }
+    return 'Slots ' + String(startSlot + 1) + '-' + String(endSlot);
+  }
+
+  function listLaneBadges(length, longestSequence) {
+    if (length === 0) return ['Empty'];
+    var badges = [];
+    if (length === longestSequence) badges.push('Longest');
+    if (length === 1) badges.push('Single');
+    return badges;
+  }
+
+  function toneForKey(key) {
+    var text = String(key || '');
+    var hash = 0;
+
+    for (var index = 0; index < text.length; index += 1) {
+      hash = ((hash * 31) + text.charCodeAt(index)) >>> 0;
+    }
+
+    return TIMELINE_TONES[hash % TIMELINE_TONES.length];
+  }
+
+  function renderTables(data) {
+    tablesContainer.innerHTML = '';
+    (uiModel.entities || []).concat(uiModel.facts || []).forEach(function (entry) {
+      var rows = data[entry.plural] || [];
+      if (!rows.length) return;
+      var cols = Object.keys(rows[0]).filter(function (key) { return key !== 'score' && key !== 'solverStatus'; });
+      var values = rows.map(function (row) {
+        return cols.map(function (key) {
+          var value = row[key];
+          if (value == null) return '—';
+          if (Array.isArray(value)) return value.join(', ');
+          if (typeof value === 'object') return JSON.stringify(value);
+          return String(value);
+        });
+      });
+      var section = SF.el('div', { className: 'sf-section' });
+      section.appendChild(SF.el('h3', null, entry.label));
+      section.appendChild(SF.createTable({ columns: cols, rows: values }));
+      tablesContainer.appendChild(section);
+    });
+  }
+
+  function buildAnalysisHtml(analysis) {
+    if (!analysis || !analysis.constraints) return '<p>No analysis available.</p>';
+    var html = '<p><strong>Score:</strong> ' + SF.escHtml(analysis.score) + '</p>';
+    html += '<table class="sf-table"><thead><tr><th>Constraint</th><th>Type</th><th>Score</th><th>Matches</th></tr></thead><tbody>';
+    analysis.constraints.forEach(function (constraint) {
+      var matchCount = constraint.matchCount != null ? constraint.matchCount : (constraint.matches ? constraint.matches.length : 0);
+      html += '<tr><td>' + SF.escHtml(constraint.name) + '</td><td>' + SF.escHtml(constraint.constraintType || constraint.type || '') + '</td><td>' + SF.escHtml(constraint.score) + '</td><td>' + matchCount + '</td></tr>';
+    });
+    html += '</tbody></table>';
+    return html;
+  }
+
+  function factLabel(fact, fallback) {
+    if (!fact) return String(fallback);
+    return fact.name || fact.id || fallback;
+  }
+
+  function entityLabel(entity, fallback) {
+    if (!entity) return String(fallback);
+    return entity.name || entity.id || fallback;
+  }
+
+  function title(text) {
+    return String(text || '')
+      .replace(/_/g, ' ')
+      .replace(/\b\w/g, function (match) { return match.toUpperCase(); });
+  }
+})();

static/generated/ui-model.json

@@ -0,0 +1,6 @@
+{
+  "entities": [],
+  "facts": [],
+  "constraints": [],
+  "views": []
+}

static/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>solverforge-fsr — SolverForge</title>
+  <link rel="stylesheet" href="/sf/sf.css">
+  <link rel="stylesheet" href="/sf/vendor/fontawesome/css/fontawesome.min.css">
+  <link rel="stylesheet" href="/sf/vendor/fontawesome/css/solid.min.css">
+  <link rel="icon" href="/sf/img/ouroboros.svg" type="image/svg+xml">
+</head>
+<body>
+  <div id="sf-app"></div>
+  <script src="/sf/sf.js"></script>
+  <script src="/app.js"></script>
+</body>
+</html>

static/sf-config.json

@@ -0,0 +1,4 @@
+{
+  "title": "solverforge-fsr",
+  "subtitle": "Constraint Optimizer"
+}