Spaces:

SolverForge
/

solverforge-hospital

Sleeping

App Files Files Community

github-actions[bot] commited on Jul 30

Commit

ea74628

0 Parent(s):

chore: sync uc-hospital Space

Browse files

This view is limited to 50 files because it contains too many changes. See raw diff

Files changed (50) hide show

.gitattributes +1 -0
.gitignore +27 -0
.pre-commit-config.yaml +21 -0
AGENTS.md +112 -0
CHANGELOG.md +69 -0
Cargo.lock +1628 -0
Cargo.toml +31 -0
Dockerfile +40 -0
Makefile +314 -0
README.md +212 -0
WIREFRAME.md +300 -0
docs/api-and-solver-policy.md +90 -0
docs/screenshot.png +3 -0
solver.toml +43 -0
solverforge.app.toml +83 -0
src/api/dto.rs +259 -0
src/api/dto/tests.rs +146 -0
src/api/mod.rs +13 -0
src/api/routes.rs +225 -0
src/api/routes/tests.rs +239 -0
src/api/sse.rs +74 -0
src/constraints/assigned_shift.rs +14 -0
src/constraints/balance_assignments.rs +12 -0
src/constraints/desired_day.rs +33 -0
src/constraints/minimum_rest.rs +38 -0
src/constraints/mod.rs +43 -0
src/constraints/one_shift_per_day.rs +21 -0
src/constraints/overlapping_shift.rs +28 -0
src/constraints/required_skill.rs +24 -0
src/constraints/unavailable_employee.rs +58 -0
src/constraints/undesired_day.rs +33 -0
src/data/data_seed.rs +28 -0
src/data/data_seed/availability.rs +72 -0
src/data/data_seed/cohorts.rs +198 -0
src/data/data_seed/coverage.rs +47 -0
src/data/data_seed/demand.rs +273 -0
src/data/data_seed/employees.rs +150 -0
src/data/data_seed/entrypoints.rs +52 -0
src/data/data_seed/large.rs +59 -0
src/data/data_seed/preferences.rs +190 -0
src/data/data_seed/preferences/exchange.rs +102 -0
src/data/data_seed/preferences/floor.rs +76 -0
src/data/data_seed/preferences/support.rs +103 -0
src/data/data_seed/preferences/top_up.rs +115 -0
src/data/data_seed/shifts.rs +54 -0
src/data/data_seed/skills.rs +42 -0
src/data/data_seed/solve_tests.rs +75 -0
src/data/data_seed/tests.rs +284 -0
src/data/data_seed/time_utils.rs +119 -0
src/data/data_seed/validation.rs +32 -0

.gitattributes ADDED Viewed

	@@ -0,0 +1 @@


1	+ docs/screenshot.png filter=lfs diff=lfs merge=lfs -text

.gitignore ADDED Viewed

	@@ -0,0 +1,27 @@

+# Generated by Cargo
+# will have compiled files and executables
+debug
+target
+# These are backup files generated by rustfmt
+**/*.rs.bk
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+# Generated by cargo mutants
+# Contains mutation testing data
+**/mutants.out*/
+test-results/
+playwright-report/
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+PRD.md
+# OSM routing cache
+.osm_cache/

.pre-commit-config.yaml ADDED Viewed

	@@ -0,0 +1,21 @@

+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+    -   id: check-merge-conflict
+    -   id: check-added-large-files
+-   repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0
+    hooks:
+    -   id: gitleaks
+-   repo: https://github.com/doublify/pre-commit-rust
+    rev: v1.0
+    hooks:
+    -   id: fmt
+        args: ["--", "--check"]
+    -   id: clippy
+        args: ["--", "-D", "warnings"]

AGENTS.md ADDED Viewed

	@@ -0,0 +1,112 @@

+# Repository Guidelines
+## Project Structure & Module Organization
+`src/` follows the current `solverforge-cli` app shape: `api/` for HTTP
+routes, SSE, and DTOs; `solver/` for retained-job orchestration; `domain/mod.rs`
+for the current `solverforge::planning_model!` manifest; `domain/` for the
+exported model modules; `constraints/mod.rs` for constraint assembly; and
+`constraints/*.rs` for the individual score rules. `data/mod.rs` is the stable
+wrapper; `data/data_seed.rs` is the thin public data surface; and
+`data/data_seed/` holds the deterministic sample dataset modules, including the
+public entrypoints and the `LARGE` instance builder. `domain/plan.rs` owns
+`Plan`, the scalar-variable `Shift`, and the scalar nearby hook functions;
+`domain/employee.rs` and `domain/care_hub.rs` hold supporting domain types.
+`static/` holds the browser app (`static/app/**/*.mjs`) and generated UI config.
+Frontend tests live in `tests/frontend/`. Container packaging is defined by
+`Dockerfile`.
+This project depends on the published `solverforge` and `solverforge-ui` crates.
+## Build, Test, and Development Commands
+- `make help` — show the supported local development and validation commands.
+- `make run-release` — run the app locally on `:7860`.
+- `make test` — run the standard Rust, frontend, and Playwright validation surface.
+- `make test-e2e` — run the real browser Playwright smoke.
+- `make ci-local` — run the Space-oriented local CI pipeline: fmt, clippy,
+  release build, standard tests, and Docker image build.
+- `make test-slow` — run the ignored large-demo acceptance solve.
+- `make pre-release` — run `make ci-local` plus the slow acceptance solve.
+- `make space-build` — build the Docker image used by the Docker-based Space
+  deployment path.
+- `cargo run --release --bin solverforge-hospital` — run the app locally on
+  `:7860`.
+- `cargo test` — run Rust unit and integration tests.
+- `cargo test large_demo_solves_to_feasible_terminal_state -- --ignored --nocapture`
+  — slow end-to-end solver acceptance test.
+- `find static/app -name '*.mjs' -print0 | xargs -0 -n1 node --check` —
+  syntax-check frontend modules.
+- `node --test tests/frontend/*.test.js` — run browserless frontend tests.
+- `docker build -f Dockerfile -t solverforge-hospital .` — build the image from
+  the repository root context.
+## Coding Style & Naming Conventions
+Use Rust 2021 style with `cargo fmt`; keep imports and formatting
+rustfmt-compatible. Prefer small, explicit functions over clever indirection.
+Rust module and file names are `snake_case`; types are `UpperCamelCase`; tests
+should describe behavior plainly. Frontend modules are plain ES modules in
+`snake-case` filenames. Keep generator logic deterministic: do not introduce
+random behavior without a fixed seed and an explicit reason.
+## Documentation And Commenting Policy
+Assume a beginner reader who is new to SolverForge and new to optimization
+modeling.
+- Treat `README.md`, `WIREFRAME.md`, this file,
+  `docs/api-and-solver-policy.md`, `docs/screenshot.png`,
+  `solver.toml` comments, and the visible API help in
+  `static/app/shell/api-guide.mjs` as one canonical documentation surface. When
+  one changes, audit the others that describe the same behavior.
+- Add module-level docs or comments for every new module that explain its role
+  in the app and where it sits in the data flow.
+- Add function comments when the function does real coordination work, rebuilds
+  invariants, shapes demo data, converts between layers, or otherwise does
+  something a beginner would not infer immediately from the signature.
+- Write comments that explain intent, domain meaning, invariants, and runtime
+  consequences. Do not write comments that merely restate syntax.
+- Keep comments truthful. If behavior changes, update or delete the stale
+  comment in the same patch.
+- When docs mention versions, counts, routes, solver policy, or validation
+  expectations, verify those facts against the current code and tests in the
+  same turn.
+- Prefer present-tense current-state docs after a refactor lands. Do not leave
+  future-tense planning language in repo docs unless the file is intentionally a
+  still-pending plan.
+- When onboarding surfaces change, keep `README.md`, `WIREFRAME.md`, and this
+  file aligned.
+The standard to aim for is: a new reader should be able to understand why a
+piece of code exists before they need to understand every line of how it works.
+The bundle-level `.github/workflows/ci.yml` installs browser dependencies and
+runs the root `make ci-local`, which dispatches this app's standard checks. The
+app Makefile remains the authoritative standalone and Hugging Face Space
+validation surface, especially `make ci-local` and `make pre-release`.
+## Testing Guidelines
+Add Rust tests next to the behavior they protect, usually in `src/...`
+`#[cfg(test)]` modules. Frontend behavior belongs in `tests/frontend/` and
+should use the existing fake DOM support in `tests/support/`; real browser
+flows belong in `tests/e2e/`. If you change solver behavior, run both
+`cargo test` and the ignored large-demo solve. If you change UI modules, run
+the Node syntax check, frontend tests, and Playwright tests.
+## Commit & Pull Request Guidelines
+Follow the workspace commit style seen upstream: conventional prefixes such as
+`fix(...)`, `feat(...)`, `refactor(...)`, `test(...)`, and `chore(...)` (for
+example, `fix(runtime): route pure scalar construction to descriptor path`).
+PRs should state user-visible impact, changed config or API surface, and the
+exact validation commands run. Include screenshots only for visible UI changes.
+## Configuration & Runtime Notes
+`solver.toml` is embedded from `src/domain/plan.rs` via
+`#[planning_solution(..., solver_toml = "../../solver.toml")]`; treat it as
+the runtime source of truth. Keep `solverforge.app.toml`,
+`static/sf-config.json`, and Docker/runtime port settings aligned with any port
+or route changes.

CHANGELOG.md ADDED Viewed

	@@ -0,0 +1,69 @@

+# Changelog
+All notable changes to this use case are documented in this file.
+## 2.0.6 (2026-07-29)
+### Maintenance
+* **release:** target SolverForge 0.19.3.
+## 2.0.5 (2026-07-17)
+### Bug Fixes
+* **hospital:** target SolverForge 0.19.0 88f38bd
+## 2.0.4 (2026-07-13)
+### Maintenance
+* **release:** target SolverForge 0.18.0.
+* **tests:** align zero-work retained-job coverage with the unified solver lifecycle.
+* **docs:** align CI, browser boot, event payload, and solver-policy descriptions with code.
+* **metadata:** use the canonical uppercase `LARGE` demo id.
+## 2.0.3 (2026-06-16)
+### Maintenance
+* **release:** target SolverForge 0.17.1 and solverforge-cli 2.2.2.
+* **metadata:** publish the hospital facts, entities, variables, and constraints in app metadata.
+## 2.0.2 (2026-05-28)
+### Maintenance
+* **release:** target SolverForge 0.15.0.
+## 2.0.1 (2026-05-16)
+### Maintenance
+* **release:** target SolverForge 0.14.1.
+## 2.0.0 (2026-05-14)
+### Maintenance
+* **release:** set the public app release line to 2.0.0 across Cargo metadata and release validation.
+## 1.0.2 (2026-05-14)
+### Maintenance
+* **release:** align the bundled app with SolverForge 0.13.1 and solverforge-ui 0.6.5.
+* **docs:** standardize the use-case README and add beginner-facing SolverForge maintenance notes.
+## 1.0.1 (2026-04-26)
+### Features
+* **app:** add hospital scheduling application b7e7f16
+### Bug Fixes
+* **space:** satisfy Hugging Face metadata validation 470faf8

Cargo.lock ADDED Viewed

	@@ -0,0 +1,1628 @@

+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+[[package]]
+name = "android_system_properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+dependencies = [
+ "libc",
+]
+[[package]]
+name = "anyhow"
+version = "1.0.102"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+[[package]]
+name = "axum"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
+dependencies = [
+ "axum-core",
+ "bytes",
+ "form_urlencoded",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "serde_core",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+[[package]]
+name = "axum-core"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+[[package]]
+name = "bitflags"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+[[package]]
+name = "bytes"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
+[[package]]
+name = "cc"
+version = "1.2.64"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dad887fd958be91b5098c0248def011f4523ab786cd411be668777e55063501f"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+[[package]]
+name = "chacha20"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "rand_core",
+]
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "js-sys",
+ "num-traits",
+ "serde",
+ "wasm-bindgen",
+ "windows-link",
+]
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+[[package]]
+name = "either"
+version = "1.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+[[package]]
+name = "futures-channel"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+dependencies = [
+ "futures-core",
+]
+[[package]]
+name = "futures-core"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+[[package]]
+name = "futures-sink"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
+[[package]]
+name = "futures-task"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+[[package]]
+name = "futures-util"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+[[package]]
+name = "getrandom"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "rand_core",
+ "wasip2",
+ "wasip3",
+]
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash",
+]
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+[[package]]
+name = "http"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+[[package]]
+name = "http-body"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
+dependencies = [
+ "bytes",
+ "http",
+]
+[[package]]
+name = "http-body-util"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+[[package]]
+name = "http-range-header"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9171a2ea8a68358193d15dd5d70c1c10a2afc3e7e4c5bc92bc9f025cebd7359c"
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+[[package]]
+name = "hyper"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55281c53a1894c864990125767da440a4e630446785086f52523b20033b74498"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "http",
+ "http-body",
+ "httparse",
+ "httpdate",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+]
+[[package]]
+name = "hyper-util"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
+dependencies = [
+ "bytes",
+ "http",
+ "http-body",
+ "hyper",
+ "pin-project-lite",
+ "tokio",
+ "tower-service",
+]
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+[[package]]
+name = "id-arena"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
+[[package]]
+name = "include_dir"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "923d117408f1e49d914f1a379a309cffe4f18c05cf4e3d12e613a15fc81bd0dd"
+dependencies = [
+ "include_dir_macros",
+]
+[[package]]
+name = "include_dir_macros"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7cab85a7ed0bd5f0e76d93846e0147172bed2e2d3f859bcc33a8d9699cad1a75"
+dependencies = [
+ "proc-macro2",
+ "quote",
+]
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+ "serde",
+ "serde_core",
+]
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+[[package]]
+name = "js-sys"
+version = "0.3.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2025f20d7a4fa7785846e7b63d10a76d3f1cee98ee5cb79ea59703f95e42162"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+[[package]]
+name = "leb128fmt"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+[[package]]
+name = "log"
+version = "0.4.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "953f07c43838f8e6f9758cab68bf5bed85465e7587ebe0b823f1bcd81978ad3a"
+[[package]]
+name = "matchers"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9"
+dependencies = [
+ "regex-automata",
+]
+[[package]]
+name = "matchit"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
+[[package]]
+name = "memchr"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+[[package]]
+name = "mime"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
+[[package]]
+name = "mime_guess"
+version = "2.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
+dependencies = [
+ "mime",
+ "unicase",
+]
+[[package]]
+name = "mio"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys",
+]
+[[package]]
+name = "nu-ansi-term"
+version = "0.50.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
+dependencies = [
+ "windows-sys",
+]
+[[package]]
+name = "num-format"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a652d9771a63711fd3c3deb670acfbe5c30a4072e664d7a3bf5a9e1056ac72c3"
+dependencies = [
+ "arrayvec",
+ "itoa",
+]
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+[[package]]
+name = "owo-colors"
+version = "4.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d211803b9b6b570f68772237e415a029d5a50c65d382910b879fb19d3271f94d"
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+[[package]]
+name = "rand"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
+dependencies = [
+ "chacha20",
+ "getrandom",
+ "rand_core",
+]
+[[package]]
+name = "rand_chacha"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e6af7f3e25ded52c41df4e0b1af2d047e45896c2f3281792ed68a1c243daedb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+[[package]]
+name = "serde_path_to_error"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
+dependencies = [
+ "itoa",
+ "serde",
+ "serde_core",
+]
+[[package]]
+name = "serde_spanned"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6662b5879511e06e8999a8a235d848113e942c9124f211511b16466ee2995f26"
+dependencies = [
+ "serde_core",
+]
+[[package]]
+name = "serde_urlencoded"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
+dependencies = [
+ "form_urlencoded",
+ "itoa",
+ "ryu",
+ "serde",
+]
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+[[package]]
+name = "sharded-slab"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
+dependencies = [
+ "lazy_static",
+]
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+[[package]]
+name = "socket2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+[[package]]
+name = "solverforge"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15d0a5dfb480a56ec3ee9aa048fd54bba3e65b04866bde610c1a956b89b4da80"
+dependencies = [
+ "solverforge-bridge",
+ "solverforge-config",
+ "solverforge-console",
+ "solverforge-core",
+ "solverforge-cvrp",
+ "solverforge-macros",
+ "solverforge-scoring",
+ "solverforge-solver",
+]
+[[package]]
+name = "solverforge-bridge"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c78f964f79318c3c0ee3161ed3004c708f04c4a751f784fe7d0ccc908194aaa3"
+dependencies = [
+ "solverforge-config",
+ "solverforge-core",
+ "solverforge-scoring",
+ "solverforge-solver",
+]
+[[package]]
+name = "solverforge-config"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27d4cb13eb5097514c5d18eeddb0f88521e3f3d8d402a0d22ffbbdcd08c90c21"
+dependencies = [
+ "serde",
+ "serde_yaml",
+ "solverforge-core",
+ "thiserror",
+ "toml",
+]
+[[package]]
+name = "solverforge-console"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f64e369266512f53d2bd335592975193fdc4d8c2d6da99929f152edfd721562"
+dependencies = [
+ "num-format",
+ "owo-colors",
+ "tracing",
+ "tracing-subscriber",
+]
+[[package]]
+name = "solverforge-core"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6118e7d98c3c8ef58646b2779603dd1ab6f9dc9f25481cb104402cbcd06be46"
+dependencies = [
+ "serde",
+ "thiserror",
+]
+[[package]]
+name = "solverforge-cvrp"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "554c12afb5908f396833688be18e649eee5967df8c41c0e4f20f0a10445ff651"
+dependencies = [
+ "solverforge-solver",
+]
+[[package]]
+name = "solverforge-hospital"
+version = "2.0.6"
+dependencies = [
+ "axum",
+ "chrono",
+ "parking_lot",
+ "rand",
+ "serde",
+ "serde_json",
+ "solverforge",
+ "solverforge-ui",
+ "tokio",
+ "tokio-stream",
+ "tower",
+ "tower-http",
+]
+[[package]]
+name = "solverforge-macros"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22c15f305806b185fc4815f8da0ec73acb9acbba5de3583433ab7b6bb2eeffa4"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "solverforge-scoring"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ddf9f9af52b0d2525f581f921e41fac8352dc2f6f1deb7f9100aff9cfedba25"
+dependencies = [
+ "solverforge-core",
+ "thiserror",
+]
+[[package]]
+name = "solverforge-solver"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19d30aece798a48d08edc630734a181dd2d9bcc1e806de7ec27701f9885989a6"
+dependencies = [
+ "rand",
+ "rand_chacha",
+ "rayon",
+ "serde",
+ "smallvec",
+ "solverforge-config",
+ "solverforge-core",
+ "solverforge-scoring",
+ "thiserror",
+ "tokio",
+ "tracing",
+]
+[[package]]
+name = "solverforge-ui"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c7fa2d78c84af9a1e264adcffc1bdf8cb4edab8d73a3543fb448d166c95596f"
+dependencies = [
+ "axum",
+ "include_dir",
+]
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+[[package]]
+name = "thiserror"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+dependencies = [
+ "thiserror-impl",
+]
+[[package]]
+name = "thiserror-impl"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "thread_local"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
+dependencies = [
+ "cfg-if",
+]
+[[package]]
+name = "tokio"
+version = "1.52.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "parking_lot",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "socket2",
+ "tokio-macros",
+ "windows-sys",
+]
+[[package]]
+name = "tokio-macros"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "tokio-stream"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32da49809aab5c3bc678af03902d4ccddea2a87d028d86392a4b1560c6906c70"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+ "tokio",
+ "tokio-util",
+]
+[[package]]
+name = "tokio-util"
+version = "0.7.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "pin-project-lite",
+ "tokio",
+]
+[[package]]
+name = "toml"
+version = "1.1.2+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "81f3d15e84cbcd896376e6730314d59fb5a87f31e4b038454184435cd57defee"
+dependencies = [
+ "indexmap",
+ "serde_core",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_parser",
+ "toml_writer",
+ "winnow",
+]
+[[package]]
+name = "toml_datetime"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+dependencies = [
+ "serde_core",
+]
+[[package]]
+name = "toml_parser"
+version = "1.1.2+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2abe9b86193656635d2411dc43050282ca48aa31c2451210f4202550afb7526"
+dependencies = [
+ "winnow",
+]
+[[package]]
+name = "toml_writer"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "756daf9b1013ebe47a8776667b466417e2d4c5679d441c26230efd9ef78692db"
+[[package]]
+name = "tower"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tokio",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+[[package]]
+name = "tower-http"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
+dependencies = [
+ "bitflags",
+ "bytes",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "http-range-header",
+ "httpdate",
+ "mime",
+ "mime_guess",
+ "percent-encoding",
+ "pin-project-lite",
+ "tokio",
+ "tokio-util",
+ "tower-layer",
+ "tower-service",
+]
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "log",
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+ "valuable",
+]
+[[package]]
+name = "tracing-log"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3"
+dependencies = [
+ "log",
+ "once_cell",
+ "tracing-core",
+]
+[[package]]
+name = "tracing-subscriber"
+version = "0.3.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
+dependencies = [
+ "matchers",
+ "nu-ansi-term",
+ "once_cell",
+ "regex-automata",
+ "sharded-slab",
+ "smallvec",
+ "thread_local",
+ "tracing",
+ "tracing-core",
+ "tracing-log",
+]
+[[package]]
+name = "unicase"
+version = "2.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+[[package]]
+name = "unicode-xid"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+[[package]]
+name = "valuable"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+[[package]]
+name = "wasip2"
+version = "1.0.3+wasi-0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6"
+dependencies = [
+ "wit-bindgen 0.57.1",
+]
+[[package]]
+name = "wasip3"
+version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
+dependencies = [
+ "wit-bindgen 0.51.0",
+]
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a254a4b10c19a76f09a27640e7ffbf9bc30bf67e16a3bf28aaefa4920fe81563"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24a40fc75b0ec6f3746ceb10d36f53a93dcd68a93b11b6445983945d79eba0dc"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "908f34bd9b9ce3d4caf07b72dfab63d61504d156856c6bd3cd87fa350cf3985b"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7acbf7616c27b194bbb550bf77ed0c2c3e5b7fd1260a93082b95fb7f47959b92"
+dependencies = [
+ "unicode-ident",
+]
+[[package]]
+name = "wasm-encoder"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319"
+dependencies = [
+ "leb128fmt",
+ "wasmparser",
+]
+[[package]]
+name = "wasm-metadata"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
+dependencies = [
+ "anyhow",
+ "indexmap",
+ "wasm-encoder",
+ "wasmparser",
+]
+[[package]]
+name = "wasmparser"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
+dependencies = [
+ "bitflags",
+ "hashbrown 0.15.5",
+ "indexmap",
+ "semver",
+]
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+[[package]]
+name = "winnow"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0592e1c9d151f854e6fd382574c3a0855250e1d9b2f99d9281c6e6391af352f1"
+[[package]]
+name = "wit-bindgen"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
+dependencies = [
+ "wit-bindgen-rust-macro",
+]
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+[[package]]
+name = "wit-bindgen-core"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc"
+dependencies = [
+ "anyhow",
+ "heck",
+ "wit-parser",
+]
+[[package]]
+name = "wit-bindgen-rust"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
+dependencies = [
+ "anyhow",
+ "heck",
+ "indexmap",
+ "prettyplease",
+ "syn",
+ "wasm-metadata",
+ "wit-bindgen-core",
+ "wit-component",
+]
+[[package]]
+name = "wit-bindgen-rust-macro"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a"
+dependencies = [
+ "anyhow",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wit-bindgen-core",
+ "wit-bindgen-rust",
+]
+[[package]]
+name = "wit-component"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
+dependencies = [
+ "anyhow",
+ "bitflags",
+ "indexmap",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "wasm-encoder",
+ "wasm-metadata",
+ "wasmparser",
+ "wit-parser",
+]
+[[package]]
+name = "wit-parser"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
+dependencies = [
+ "anyhow",
+ "id-arena",
+ "indexmap",
+ "log",
+ "semver",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "unicode-xid",
+ "wasmparser",
+]
+[[package]]
+name = "zerocopy"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
+dependencies = [
+ "zerocopy-derive",
+]
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"

Cargo.toml ADDED Viewed

	@@ -0,0 +1,31 @@

+[package]
+name = "solverforge-hospital"
+version = "2.0.6"
+edition = "2021"
+rust-version = "1.95"
+description = "SolverForge hospital scheduling example"
+publish = false
+[dependencies]
+solverforge = { version = "0.19.3", features = [
+  "serde",
+  "console",
+  "verbose-logging",
+] }
+solverforge-ui = "0.6.5"
+rand = "0.10.1"
+axum = "0.8.9"
+tokio = { version = "1.52.3", features = ["full"] }
+tokio-stream = { version = "0.1.18", features = ["sync"] }
+tower-http = { version = "0.6.10", features = ["fs", "cors"] }
+tower = "0.5.3"
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.149"
+chrono = { version = "0.4.44", features = ["serde"] }
+parking_lot = "0.12.5"
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1

Dockerfile ADDED Viewed

	@@ -0,0 +1,40 @@

+# Multi-stage build for solverforge-hospital.
+FROM rust:1.95-alpine AS builder
+# Install build dependencies
+RUN apk add --no-cache musl-dev
+WORKDIR /build
+COPY Cargo.toml Cargo.lock ./
+COPY src/ ./src/
+COPY static/ ./static/
+COPY solver.toml ./solver.toml
+# Build release binary with musl target for static linking
+RUN cargo build --release --target x86_64-unknown-linux-musl
+# Runtime stage - minimal Alpine image
+FROM alpine:latest
+RUN apk add --no-cache ca-certificates
+WORKDIR /app
+# Copy binary from builder (musl static binary)
+COPY --from=builder /build/target/x86_64-unknown-linux-musl/release/solverforge-hospital ./solverforge-hospital
+# Copy static files
+COPY --from=builder /build/static/ ./static/
+# Copy solver config
+COPY --from=builder /build/solver.toml ./solver.toml
+ENV PORT=7860
+# Expose the same port the container binds to by default.
+EXPOSE 7860
+# Run the application
+CMD ["./solverforge-hospital"]

Makefile ADDED Viewed

	@@ -0,0 +1,314 @@

+# SolverForge Hospital Makefile
+# Rust + frontend + Space-oriented local build system
+#
+# This app is primarily validated for local development and Docker-based
+# Hugging Face Space deployment. `ci-local` therefore simulates the checks we
+# expect before updating a Space, rather than mirroring a GitHub Actions file.
+SHELL := /bin/sh
+.SHELLFLAGS := -eu -c
+unexport BASH_FUNC_mc%%
+# ============== Colors & Symbols ==============
+GREEN := \033[92m
+EMERALD := \033[38;2;16;185;129m
+CYAN := \033[96m
+YELLOW := \033[93m
+MAGENTA := \033[95m
+RED := \033[91m
+GRAY := \033[90m
+BOLD := \033[1m
+RESET := \033[0m
+CHECK := ✓
+CROSS := ✗
+ARROW := ▸
+PROGRESS := →
+# ============== Project Metadata ==============
+APP_NAME := solverforge-hospital
+PACKAGE_NAME := solverforge-hospital
+VERSION := $(shell sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -n1)
+RELEASE_TAG := $(PACKAGE_NAME)@$(VERSION)
+RUST_VERSION := 1.95+
+PORT ?= 7860
+DOCKER_IMAGE ?= $(APP_NAME)
+DOCKER_CONTEXT ?= .
+DOCKERFILE_PATH := Dockerfile
+PLAYWRIGHT ?= ../node_modules/.bin/playwright
+# ============== Phony Targets ==============
+.PHONY: banner help doctor build build-release run run-release test test-rust \
+        test-frontend-syntax test-frontend test-e2e test-slow test-one lint fmt fmt-check \
+        clippy check ci-local space-ci space-build space-run docker-build \
+        docker-run pre-release release-ci release-info version clean watch require-node require-docker \
+# ============== Default Target ==============
+.DEFAULT_GOAL := help
+# ============== Banner ==============
+banner:
+	@printf "$(EMERALD)$(BOLD)  ____        _                _____\n"
+	@printf " / ___|  ___ | |_   _____ _ __|  ___|__  _ __ __ _  ___\n"
+	@printf " \\___ \\\\ / _ \\\\| \\\\ \\\\ / / _ \\\\ '__| |_ / _ \\\\| '__/ _\` |/ _ \\\\\n"
+	@printf "  ___) | (_) | |\\\\ V /  __/ |  |  _| (_) | | | (_| |  __/\n"
+	@printf " |____/ \\\\___/|_| \\_/ \\___|_|  |_|  \\___/|_|  \\__, |\\___|\n"
+	@printf "                                             |___/$(RESET)\n"
+	@printf "  $(GRAY)v$(VERSION)$(RESET) $(EMERALD)Hospital demo build system$(RESET)\n\n"
+# ============== Environment Checks ==============
+require-node:
+	@command -v node >/dev/null 2>&1 || (printf "$(RED)$(CROSS) node is required for frontend validation$(RESET)\n" && exit 1)
+require-docker:
+	@command -v docker >/dev/null 2>&1 || (printf "$(RED)$(CROSS) docker is required for Space/Docker targets$(RESET)\n" && exit 1)
+doctor: banner
+	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════╗$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)║        Environment Check             ║$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════╝$(RESET)\n\n"
+	@missing=0; \
+	if command -v cargo >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) cargo: $$(cargo --version)$(RESET)\n"; \
+	else \
+		printf "$(RED)$(CROSS) cargo not found$(RESET)\n"; \
+		missing=1; \
+	fi; \
+	if command -v rustc >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) rustc: $$(rustc --version)$(RESET)\n"; \
+	else \
+		printf "$(RED)$(CROSS) rustc not found$(RESET)\n"; \
+		missing=1; \
+	fi; \
+	if command -v node >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) node: $$(node --version)$(RESET)\n"; \
+	else \
+		printf "$(RED)$(CROSS) node not found$(RESET)\n"; \
+		missing=1; \
+	fi; \
+	if command -v docker >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) docker: $$(docker --version)$(RESET)\n"; \
+	else \
+		printf "$(YELLOW)! docker not found; Space/Docker targets will be unavailable$(RESET)\n"; \
+	fi; \
+	printf "$(GRAY)Docker build context: $(DOCKER_CONTEXT)$(RESET)\n"; \
+	printf "$(GRAY)Default app port: $(PORT)$(RESET)\n"; \
+	if [ $$missing -ne 0 ]; then exit 1; fi
+	@printf "\n"
+# ============== Build & Run ==============
+build: banner
+	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════╗$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)║        Debug Build                   ║$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════╝$(RESET)\n\n"
+	@printf "$(ARROW) $(BOLD)Building $(APP_NAME)...$(RESET)\n"
+	@cargo build --bin $(APP_NAME) && \
+		printf "$(GREEN)$(CHECK) Debug build successful$(RESET)\n\n" || \
+		(printf "$(RED)$(CROSS) Debug build failed$(RESET)\n\n" && exit 1)
+build-release: banner
+	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════╗$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)║        Release Build                 ║$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════╝$(RESET)\n\n"
+	@printf "$(ARROW) $(BOLD)Building release binary...$(RESET)\n"
+	@cargo build --release --bin $(APP_NAME) && \
+		printf "$(GREEN)$(CHECK) Release build successful$(RESET)\n\n" || \
+		(printf "$(RED)$(CROSS) Release build failed$(RESET)\n\n" && exit 1)
+run:
+	@printf "$(ARROW) Running $(APP_NAME) on port $(PORT)...\n"
+	@PORT=$(PORT) cargo run --bin $(APP_NAME)
+run-release:
+	@printf "$(ARROW) Running release build on port $(PORT)...\n"
+	@PORT=$(PORT) cargo run --release --bin $(APP_NAME)
+# ============== Test Targets ==============
+test: test-rust test-frontend test-e2e
+	@printf "\n$(GREEN)$(BOLD)$(CHECK) Standard validation passed$(RESET)\n\n"
+test-rust: banner
+	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════╗$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)║         Rust Test Suite              ║$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════╝$(RESET)\n\n"
+	@printf "$(ARROW) $(BOLD)Running cargo test --quiet...$(RESET)\n"
+	@cargo test --quiet && \
+		printf "\n$(GREEN)$(CHECK) Rust tests passed$(RESET)\n\n" || \
+		(printf "\n$(RED)$(CROSS) Rust tests failed$(RESET)\n\n" && exit 1)
+test-frontend-syntax: require-node
+	@printf "$(PROGRESS) Checking frontend module syntax...\n"
+	@find static/app -name '*.mjs' -print0 | xargs -0 -n1 node --check && \
+		printf "$(GREEN)$(CHECK) Frontend syntax checks passed$(RESET)\n" || \
+		(printf "$(RED)$(CROSS) Frontend syntax checks failed$(RESET)\n" && exit 1)
+test-frontend: test-frontend-syntax
+	@printf "$(PROGRESS) Running frontend tests...\n"
+	@node --test tests/frontend/*.test.js && \
+		printf "$(GREEN)$(CHECK) Frontend tests passed$(RESET)\n" || \
+		(printf "$(RED)$(CROSS) Frontend tests failed$(RESET)\n" && exit 1)
+test-e2e: build-release require-node
+	@printf "$(PROGRESS) Running Playwright browser tests...\n"
+	@$(PLAYWRIGHT) test --config tests/e2e/playwright.config.js && \
+		printf "$(GREEN)$(CHECK) Playwright browser tests passed$(RESET)\n" || \
+		(printf "$(RED)$(CROSS) Playwright browser tests failed$(RESET)\n" && exit 1)
+test-slow: banner
+	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════╗$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)║     Slow Acceptance Solve            ║$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════╝$(RESET)\n\n"
+	@printf "$(ARROW) $(BOLD)Running large demo acceptance solve...$(RESET)\n"
+	@cargo test large_demo_solves_to_feasible_terminal_state -- --ignored --nocapture && \
+		printf "\n$(GREEN)$(CHECK) Slow acceptance solve passed$(RESET)\n\n" || \
+		(printf "\n$(RED)$(CROSS) Slow acceptance solve failed$(RESET)\n\n" && exit 1)
+test-one:
+	@printf "$(PROGRESS) Running test: $(YELLOW)$(TEST)$(RESET)\n"
+	@RUST_LOG=info cargo test $(TEST) -- --nocapture
+# ============== Lint & Format ==============
+fmt:
+	@printf "$(PROGRESS) Formatting code...\n"
+	@find src tests -name '*.rs' -print0 | xargs -0 rustfmt --edition 2021
+	@printf "$(GREEN)$(CHECK) Code formatted$(RESET)\n"
+fmt-check:
+	@printf "$(PROGRESS) Checking formatting...\n"
+	@find src tests -name '*.rs' -print0 | xargs -0 rustfmt --edition 2021 --check && \
+		printf "$(GREEN)$(CHECK) Formatting valid$(RESET)\n" || \
+		(printf "$(RED)$(CROSS) Formatting issues found$(RESET)\n" && exit 1)
+clippy:
+	@printf "$(PROGRESS) Running clippy...\n"
+	@cargo clippy --all-targets -- -D warnings && \
+		printf "$(GREEN)$(CHECK) Clippy passed$(RESET)\n" || \
+		(printf "$(RED)$(CROSS) Clippy warnings found$(RESET)\n" && exit 1)
+lint: fmt-check clippy test-frontend-syntax
+	@printf "\n$(GREEN)$(BOLD)$(CHECK) Lint checks passed$(RESET)\n\n"
+check: lint test
+# ============== Space & Docker ==============
+docker-build: require-docker
+	@printf "$(PROGRESS) Building Docker image $(DOCKER_IMAGE)...\n"
+	@docker build -f "$(DOCKERFILE_PATH)" -t "$(DOCKER_IMAGE)" "$(DOCKER_CONTEXT)" && \
+		printf "$(GREEN)$(CHECK) Docker image built$(RESET)\n" || \
+		(printf "$(RED)$(CROSS) Docker build failed$(RESET)\n" && exit 1)
+docker-run: require-docker
+	@printf "$(ARROW) Running $(DOCKER_IMAGE) on port $(PORT)...\n"
+	@docker run --rm -it -e PORT=$(PORT) -p $(PORT):$(PORT) "$(DOCKER_IMAGE)"
+space-build: docker-build
+space-run: space-build
+	@printf "$(GREEN)$(CHECK) Starting local container that mirrors the Space image$(RESET)\n"
+	@$(MAKE) docker-run --no-print-directory PORT=$(PORT) DOCKER_IMAGE=$(DOCKER_IMAGE)
+space-ci: ci-local
+# ============== CI & Release Validation ==============
+ci-local: banner
+	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════════════════════════╗$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)║          Local Space Validation Pipeline                ║$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════════════════════════╝$(RESET)\n\n"
+	@printf "$(ARROW) $(BOLD)Simulating the checks we want green before a Space update...$(RESET)\n\n"
+	@printf "$(PROGRESS) Step 1/5: Format check...\n"
+	@$(MAKE) fmt-check --no-print-directory
+	@printf "$(PROGRESS) Step 2/5: Clippy...\n"
+	@$(MAKE) clippy --no-print-directory
+	@printf "$(PROGRESS) Step 3/5: Release build...\n"
+	@$(MAKE) build-release --no-print-directory
+	@printf "$(PROGRESS) Step 4/5: Standard test surface...\n"
+	@$(MAKE) test --no-print-directory
+	@printf "$(PROGRESS) Step 5/5: Docker/Space image build...\n"
+	@$(MAKE) space-build --no-print-directory
+	@printf "\n$(GREEN)$(BOLD)╔══════════════════════════════════════════════════════════╗$(RESET)\n"
+	@printf "$(GREEN)$(BOLD)║          $(CHECK) SPACE VALIDATION PASSED                     ║$(RESET)\n"
+	@printf "$(GREEN)$(BOLD)╚══════════════════════════════════════════════════════════╝$(RESET)\n\n"
+pre-release: banner
+	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════════════════════════╗$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)║         Pre-Release Validation v$(VERSION)                  ║$(RESET)\n"
+	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════════════════════════╝$(RESET)\n\n"
+	@$(MAKE) ci-local --no-print-directory
+	@printf "$(PROGRESS) Final step: slow acceptance solve...\n"
+	@$(MAKE) test-slow --no-print-directory
+	@printf "$(GREEN)$(BOLD)$(CHECK) Ready for a Space update$(RESET)\n\n"
+release-ci: ci-local
+	@printf "$(GREEN)$(BOLD)$(CHECK) Release CI passed for $(RELEASE_TAG)$(RESET)\n\n"
+release-info:
+	@printf "$(CYAN)Package:$(RESET) $(YELLOW)$(BOLD)$(PACKAGE_NAME)$(RESET)\n"
+	@printf "$(CYAN)Version:$(RESET) $(YELLOW)$(BOLD)$(VERSION)$(RESET)\n"
+	@printf "$(CYAN)Release tag:$(RESET) $(YELLOW)$(BOLD)$(RELEASE_TAG)$(RESET)\n"
+# ============== Metadata & Cleanup ==============
+version:
+	@printf "$(CYAN)Current version:$(RESET) $(YELLOW)$(BOLD)$(VERSION)$(RESET)\n"
+	@printf "$(CYAN)Release tag:$(RESET) $(YELLOW)$(BOLD)$(RELEASE_TAG)$(RESET)\n"
+	@printf "$(CYAN)Default port:$(RESET) $(YELLOW)$(BOLD)$(PORT)$(RESET)\n"
+clean:
+	@printf "$(ARROW) Cleaning build artifacts...\n"
+	@cargo clean
+	@printf "$(GREEN)$(CHECK) Clean complete$(RESET)\n"
+watch:
+	@printf "$(ARROW) Watching and rerunning the app on port $(PORT)...\n"
+	@cargo watch --version >/dev/null 2>&1 || \
+		(printf "$(RED)$(CROSS) cargo-watch is required for make watch$(RESET)\n" && exit 1)
+	@cargo watch -x "run --bin $(APP_NAME)"
+# ============== Help ==============
+help: banner
+	@/bin/echo -e "$(CYAN)$(BOLD)Environment:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make doctor$(RESET)         - Check toolchain and Docker readiness"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(CYAN)$(BOLD)Build & Run:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make build$(RESET)          - Build the app in debug mode"
+	@/bin/echo -e "  $(GREEN)make build-release$(RESET)  - Build the app in release mode"
+	@/bin/echo -e "  $(GREEN)make run$(RESET)            - Run the app locally on port $(PORT)"
+	@/bin/echo -e "  $(GREEN)make run-release$(RESET)    - Run the release build locally on port $(PORT)"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(CYAN)$(BOLD)Tests & Validation:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make test$(RESET)           - Run the standard Rust, frontend, and Playwright test surface"
+	@/bin/echo -e "  $(GREEN)make test-rust$(RESET)      - Run Rust tests only"
+	@/bin/echo -e "  $(GREEN)make test-frontend$(RESET)  - Run frontend syntax checks and tests"
+	@/bin/echo -e "  $(GREEN)make test-e2e$(RESET)       - Run Playwright browser tests"
+	@/bin/echo -e "  $(GREEN)make test-slow$(RESET)      - Run the ignored large-demo acceptance solve"
+	@/bin/echo -e "  $(GREEN)make test-one TEST=name$(RESET) - Run a specific Rust test with output"
+	@/bin/echo -e "  $(GREEN)make lint$(RESET)           - Run fmt-check, clippy, and frontend syntax checks"
+	@/bin/echo -e "  $(GREEN)make check$(RESET)          - Run lint plus the standard test surface"
+	@/bin/echo -e "  $(GREEN)make release-ci$(RESET)     - Run the tag-publish CI gate for this app"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(CYAN)$(BOLD)Space & Docker:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make space-build$(RESET)    - Build the Docker image used for Space-style deployment"
+	@/bin/echo -e "  $(GREEN)make space-run$(RESET)      - Build and run that image locally on port $(PORT)"
+	@/bin/echo -e "  $(GREEN)make ci-local$(RESET)       - Simulate the pre-push validation for a Hugging Face Space"
+	@/bin/echo -e "  $(GREEN)make pre-release$(RESET)    - Run ci-local plus the slow acceptance solve"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(CYAN)$(BOLD)Other:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make fmt$(RESET)            - Format Rust code"
+	@/bin/echo -e "  $(GREEN)make release-info$(RESET)   - Show package version and app-scoped release tag"
+	@/bin/echo -e "  $(GREEN)make version$(RESET)        - Show version and default port"
+	@/bin/echo -e "  $(GREEN)make clean$(RESET)          - Clean build artifacts"
+	@/bin/echo -e "  $(GREEN)make watch$(RESET)          - Watch source files and rerun the app"
+	@/bin/echo -e "  $(GREEN)make help$(RESET)           - Show this help message"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(GRAY)Rust version required: $(RUST_VERSION)$(RESET)"
+	@/bin/echo -e "$(GRAY)Current version: v$(VERSION)$(RESET)"
+	@/bin/echo -e "$(GRAY)Release tag: $(RELEASE_TAG)$(RESET)"
+	@/bin/echo -e "$(GRAY)Default port: $(PORT)$(RESET)"
+	@/bin/echo -e ""

README.md ADDED Viewed

	@@ -0,0 +1,212 @@

+---
+title: SolverForge Hospital
+emoji: 🏥
+colorFrom: red
+colorTo: pink
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+short_description: SolverForge hospital scheduling example
+---
+# SolverForge Hospital
+![SolverForge Hospital screenshot](docs/screenshot.png)
+`solverforge-hospital` is a SolverForge employee-scheduling app with retained
+jobs, schedule analysis, and a browser timeline workspace.
+It answers one concrete question:
+"Given a hospital workforce and a month of shifts, which employee should cover
+each shift?"
+## Quick Start
+```sh
+make run-release
+```
+Then open `http://localhost:7860`.
+To inspect the supported command surface:
+```sh
+make help
+```
+## Documentation Map
+- `README.md`
+  Quick start, model concepts, validation, REST API, and solver policy.
+- `WIREFRAME.md`
+  As-built architecture and runtime/data flow across backend, runtime, and UI.
+- `docs/api-and-solver-policy.md`
+  Detailed route, payload, lifecycle, telemetry, and solver-policy reference.
+- `AGENTS.md`
+  Codex-facing maintenance, validation, and documentation rules.
+- `Makefile`
+  Supported local commands for development, validation, Docker, and Space work.
+- `Dockerfile`
+  Docker Space image build using Rust 1.95 and the declared crates.io line.
+## Current Dependency Shape
+- Package: `solverforge-hospital`; version is declared in `Cargo.toml`
+- Release binary: `solverforge-hospital`
+- Rust: `1.95`
+- SolverForge runtime: `solverforge` `0.19.3`
+- Browser UI assets: `solverforge-ui` `0.6.5`
+- Scaffold metadata: `solverforge-cli` `2.2.2` in `solverforge.app.toml`
+The app serves registry-backed Rust dependencies, local static browser modules,
+and Axum API routes from one process.
+## Model Concepts
+- `Employee` is a problem fact: input staff data the solver reads but does not
+  move.
+- `Shift` is the planning entity: each shift needs exactly one employee.
+- `Shift.employee_idx` is the scalar planning variable: the employee index
+  SolverForge changes during construction and local search.
+- `CareHub` is a derived domain grouping that makes nearby search prefer
+  employees close to the service line.
+- `Plan` is the planning solution with the current `HardSoftDecimalScore`.
+The app ships one deterministic `LARGE` dataset with a 28-day horizon, 50
+employees, and 688 shifts.
+## Constraints
+Hard constraints:
+- Every shift is assigned.
+- The assigned employee has the required skill.
+- An employee is not assigned to overlapping shifts.
+- An employee has at least 10 hours between two shifts.
+- An employee works at most one shift per day.
+- Unavailable employees are not assigned.
+Soft constraints:
+- Undesired days are avoided.
+- Desired days are rewarded.
+- Assignments are balanced across employees.
+## REST API
+- `GET /health`
+- `GET /info`
+- `GET /demo-data`
+- `GET /demo-data/{id}`
+- `POST /jobs`
+- `GET /jobs/{id}`
+- `DELETE /jobs/{id}`
+- `GET /jobs/{id}/status`
+- `GET /jobs/{id}/snapshot`
+- `GET /jobs/{id}/analysis`
+- `POST /jobs/{id}/pause`
+- `POST /jobs/{id}/resume`
+- `POST /jobs/{id}/cancel`
+- `GET /jobs/{id}/events`
+`snapshot_revision={n}` is optional for snapshots and analysis. SSE clients
+receive a bootstrap event and then live retained-job events. The browser also
+exposes a visible REST API guide expected to match
+`docs/api-and-solver-policy.md`.
+## Solver Policy
+`solver.toml` is embedded by `Plan` and is the runtime source of truth.
+- `cheapest_insertion` assigns employee indexes during construction.
+- Local search uses nearby change and nearby swap moves over
+  `Shift.employee_idx`.
+- Nearby search reads the app's care-hub distance signals so moves stay focused
+  on plausible employee/shift pairs.
+- `late_acceptance` with an accepted-count forager keeps several candidate
+  moves alive per step.
+- Solving stops after 30 seconds total or after 5 seconds without improvement.
+The hidden witness roster in `src/data/data_seed/witness.rs` shapes a
+hard-feasible public instance, but the solver never receives the witness itself.
+## Validation
+Standard validation:
+```sh
+make test
+```
+Full local validation:
+```sh
+make ci-local
+```
+Slow acceptance solve:
+```sh
+make test-slow
+```
+`make test` runs Rust tests, browserless frontend tests, and Playwright browser
+tests. `make ci-local` adds formatting, clippy, release build, and Docker image
+build. `make pre-release` runs `ci-local` plus the slow acceptance solve.
+## Hugging Face Space Deployment
+This repo is Docker-Space ready. The Space reads the README front matter,
+builds `Dockerfile`, and expects the app to bind `PORT=7860`.
+Local Space-equivalent commands:
+```sh
+make space-build
+make space-run
+```
+## Read The Code In This Order
+1. `src/domain/employee.rs`
+   The staff problem fact model.
+2. `src/domain/care_hub.rs`
+   Service-line grouping for nearby search.
+3. `src/domain/mod.rs`
+   The `planning_model!` manifest and public domain exports.
+4. `src/domain/plan.rs`
+   The `Shift` planning entity, `Plan` solution, derived fields, and nearby
+   meters.
+5. `src/constraints/mod.rs` and `src/constraints/*.rs`
+   The score model, one scheduling rule per file.
+6. `src/data/data_seed/entrypoints.rs`
+   Public demo-data IDs.
+7. `src/data/data_seed/large.rs` and `src/data/data_seed/witness.rs`
+   The published instance builder and hidden feasibility witness.
+8. `src/solver/service.rs`
+   Retained-job orchestration over `SolverManager<Plan>`.
+9. `src/api/routes.rs`, `src/api/dto.rs`, and `src/api/sse.rs`
+   HTTP routes, transport DTOs, and live-event streaming.
+10. `static/app/main.mjs`, `static/app/shell/`, and `static/app/schedule/`
+    Browser boot sequence, shell, and timeline views.
+## Project Shape
+- `src/domain/`
+  Planning model, domain types, derived fields, and nearby meters.
+- `src/constraints/`
+  Incremental SolverForge scoring rules.
+- `src/data/`
+  Deterministic hospital demo-data generator.
+- `src/solver/`
+  Retained-job facade and runtime event payload formatting.
+- `src/api/`
+  Axum routes, DTOs, and SSE endpoint.
+- `static/app/`
+  Browser modules built on stock `solverforge-ui` assets.
+- `tests/frontend/`
+  Browserless UI tests using the fake DOM in `tests/support/`.
+- `tests/e2e/`
+  Playwright browser tests for the served app.

WIREFRAME.md ADDED Viewed

	@@ -0,0 +1,300 @@

+# solverforge-hospital WIREFRAME
+This file is the architectural map for beginners.
+If `README.md` tells you how to run the app, this document tells you how the
+pieces fit together and in which order to read them.
+## Documentation Roles
+The docs in this repo are meant to work together rather than compete:
+- `README.md`
+  Quick start, concepts, and user-facing orientation.
+- `WIREFRAME.md`
+  Architecture, execution flow, and file-map walkthrough.
+- `docs/api-and-solver-policy.md`
+  REST routes, lifecycle semantics, payload shape, and solver policy notes.
+- `AGENTS.md`
+  Rules for keeping code, comments, tests, and docs aligned in future changes.
+- `Makefile`
+  The shared developer command surface, including the local Space validation
+  pipeline.
+- `docs/screenshot.png`
+  Current browser screenshot embedded by the README.
+## What This Repo Is Teaching
+`solverforge-hospital` is a complete SolverForge example, not just a scoring
+snippet.
+It shows how to build a planning app where:
+- the domain model is small and explicit
+- the score rules are readable one file at a time
+- the dataset is deterministic and intentionally shaped
+- the solver runs as a retained background job
+- the browser UI watches the solve through REST and SSE
+The planning question is:
+"For each hospital shift, which employee should be assigned?"
+## SolverForge Concepts In Plain Language
+- `Employee`
+  Input data. The solver reads it, but does not move it.
+- `Shift`
+  The thing the solver is allowed to assign.
+- `employee_idx`
+  The one real decision variable in this app. It points from a shift to one
+  employee inside `Plan.employees`.
+- hard score
+  Rules that must not be broken, such as missing skills or overlapping shifts.
+- soft score
+  Preferences and quality goals, such as honoring desired days or balancing
+  workload.
+- retained job
+  A solve that keeps living in memory after it starts, so the UI can poll it,
+  pause it, resume it, stop it through runtime cancel, or inspect snapshots.
+  Delete is terminal cleanup before the next fresh Solve, not the Stop action.
+## Read Order
+If you are new to this repo, read files in this order:
+1. `src/domain/employee.rs`
+   Learn the input facts first.
+2. `src/domain/care_hub.rs`
+   Learn the hospital service-line grouping used by nearby search.
+3. `src/domain/mod.rs`
+   See the `planning_model!` manifest that lists and exports the model modules.
+4. `src/domain/plan.rs`
+   Learn the planning entity, planning variable, nearby meters, and derived
+   fields.
+5. `src/constraints/mod.rs`
+   See the full score model at a glance.
+6. `src/constraints/*.rs`
+   Read one scheduling rule per file.
+7. `src/data/data_seed/entrypoints.rs`
+   See the public demo-data surface.
+8. `src/data/data_seed/large.rs`
+   See how the published dataset is assembled.
+9. `src/solver/service.rs`
+   See how a domain solve becomes a retained runtime job.
+10. `src/api/routes.rs` and `src/api/sse.rs`
+   See the HTTP contract.
+11. `static/app/main.mjs`
+    See the browser boot sequence.
+12. `static/app/shell/` and `static/app/schedule/`
+    See how stock `solverforge-ui` components are adapted to this hospital demo.
+## Runtime Flow
+The shortest way to understand the app is to follow one request all the way
+through:
+1. The browser loads `static/index.html`.
+2. `static/app/main.mjs` loads config and the generated UI model, validates the
+   configured `LARGE` id through `/demo-data`, and then fetches
+   `/demo-data/LARGE`.
+3. The frontend turns the returned `PlanDto` into schedule rails and side-panel
+   summaries.
+4. When the user clicks Solve, the frontend sends the current plan to
+   `POST /jobs`.
+5. `src/api/routes.rs` converts that HTTP request into a `PlanDto`.
+6. `PlanDto::to_domain()` rebuilds the in-memory `Plan`, including derived
+   helper fields the solver expects.
+7. `SolverService` starts a retained solve through `SolverManager<Plan>`.
+8. The solver emits lifecycle events carrying telemetry and best-solution
+   snapshots.
+9. `src/solver/service.rs` coordinates the event stream, while
+   `src/solver/service/payload.rs` converts runtime events into the JSON shapes
+   expected by the UI.
+10. The browser consumes those events over `/jobs/{id}/events` and updates the
+    visible status and timeline; analysis is fetched from
+    `/jobs/{id}/analysis` when requested.
+The browser shell also contains a visible REST API guide. That makes
+`static/app/shell/api-guide.mjs` part of the documentation surface, not just a
+UI helper.
+## File Map
+```text
+.
+├── Cargo.toml
+│   Rust crate metadata and registry dependency requests.
+├── solver.toml
+│   Embedded solver policy. This is the runtime source of truth for search.
+├── solverforge.app.toml
+│   App metadata, model surface, and the `solverforge 0.19.3` runtime target.
+├── Dockerfile
+│   Container build for running the app outside the dev checkout.
+├── Makefile
+│   Local build, validation, and Docker/Space workflow wrapper.
+├── README.md
+│   Beginner run guide and learning path.
+├── docs/api-and-solver-policy.md
+│   REST, payload, lifecycle, telemetry, and solver-policy reference.
+├── WIREFRAME.md
+│   This architectural walkthrough.
+├── AGENTS.md
+│   Repo-specific contributor and documentation rules.
+├── docs/screenshot.png
+│   Current browser screenshot used by the README.
+├── src/
+│   ├── lib.rs
+│   │   Crate root and public module surface.
+│   ├── main.rs
+│   │   Axum server bootstrap, CORS, static serving, and route composition.
+│   ├── domain/
+│   │   `planning_model!` manifest plus problem model modules.
+│   ├── constraints/
+│   │   One scheduling rule per file plus the assembler in `mod.rs`.
+│   ├── data/
+│   │   Deterministic demo-data generator and published entrypoints.
+│   ├── solver/
+│   │   Retained-job facade over the SolverForge runtime.
+│   └── api/
+│       DTOs, REST routes, and SSE streaming.
+├── static/
+│   ├── index.html
+│   │   Browser entrypoint.
+│   ├── sf-config.json
+│   │   Runtime UI config for the stock frontend shell.
+│   ├── generated/ui-model.json
+│   │   Generated view metadata used by `solverforge-ui`.
+│   └── app/
+│       ├── main.mjs
+│       │   Browser boot and wiring.
+│       ├── shell/
+│       │   App shell, state, solver controls, and panels.
+│       ├── schedule/
+│       │   Hospital-specific grouping, presentation, and rail rendering.
+│       └── views/registry.mjs
+│           Named view registration.
+└── tests/
+    ├── frontend/
+    │   Browserless frontend tests.
+    ├── e2e/
+    │   Playwright browser tests for the served app.
+    └── support/
+        Fake DOM support used by the frontend tests.
+```
+## Why The Model Looks This Way
+This app is intentionally narrow.
+- There is one planning entity type: `Shift`.
+- There is one scalar planning variable: `employee_idx`.
+- Nearby search is attached directly to that scalar variable.
+- The solver does not juggle multiple variable types, sequence assignments, or
+  list planning.
+That makes the example easier to learn because the optimization problem stays
+visible:
+- facts live in `Plan.employees`
+- decisions live in `Plan.shifts[*].employee_idx`
+- score rules read those two things and judge the assignment
+## Why The Demo Data Is Structured
+The demo-data generator is not filler.
+It is designed to give beginners a problem that is:
+- deterministic
+- feasible
+- interesting enough that local search still has work to do
+- stable enough that tests and comparisons stay meaningful
+One important design trick is the hidden witness roster in
+`src/data/data_seed/witness.rs`.
+That internal roster gives the generator a known feasible staffing pattern.
+The published dataset is then shaped around that witness, while the solver only
+sees the final public problem. This lets the repo ship a realistic-feeling
+demo without random feasibility failures.
+## Why The Runtime Uses REST And SSE
+The solve is long-lived compared with a normal request/response handler, so the
+backend splits the contract into two parts:
+- REST for control and snapshots
+- SSE for live progress
+The REST surface is:
+- `/health` and `/info` expose liveness and app metadata.
+- `/demo-data` and `/demo-data/{id}` expose the deterministic demo catalog.
+- `/jobs` creates a retained solver job.
+- `/jobs/{id}` and `/jobs/{id}/status` expose summary state.
+- `/jobs/{id}/snapshot` returns an exact or latest snapshot.
+- `/jobs/{id}/analysis` runs constraint analysis for a snapshot.
+- `/jobs/{id}/pause`, `/jobs/{id}/resume`, and `/jobs/{id}/cancel` control a
+  live job.
+- `DELETE /jobs/{id}` removes a terminal retained job.
+- `/jobs/{id}/events` streams typed lifecycle events.
+That separation keeps the frontend simple:
+- create a job
+- poll or fetch details when needed
+- subscribe once to the live event stream
+It also mirrors how a real retained SolverForge app behaves in production.
+One small but important detail: `GET /jobs/{id}` and `GET /jobs/{id}/status`
+return the same summary payload. The second route exists as a stock-compatible
+alias for clients that expect the explicit `/status` URL shape.
+## Solver Policy
+`solver.toml` is embedded by `Plan` and is therefore part of the actual model,
+not a side document.
+The shipped search policy is deliberately conservative:
+- `cheapest_insertion` builds a feasible first assignment
+- local search stays in the nearby scalar neighborhood
+- `late_acceptance` and `accepted_count` keep the search moving without blowing
+  up step cost
+That narrow configuration is the shipped 30-second policy for this demo.
+`make test-slow` is the acceptance gate for any solver-policy change.
+## Frontend Design
+The frontend is intentionally thin.
+This repo is not trying to teach a custom framework. It is showing how to take
+stock `solverforge-ui` pieces and adapt them to one concrete planning problem.
+- `shell/` owns app lifecycle, backend wiring, and side panels
+- `schedule/` owns the hospital-specific transformation from domain data to
+  visual rails
+- tests in `tests/frontend/` lock browserless presentation behavior down
+- tests in `tests/e2e/` verify the served browser app with Playwright
+## Validation Surfaces
+When you change this repo, think in six separate layers:
+1. Domain and constraint logic:
+   `make test-rust`
+2. Slow end-to-end solve quality:
+   `make test-slow`
+3. Frontend module correctness:
+   `make test-frontend-syntax`
+4. Frontend module behavior:
+   `make test-frontend`
+5. Served browser behavior:
+   `make test-e2e`
+6. Local deploy readiness for the Docker-based Space target:
+   `make ci-local`
+If you keep those six layers green, the repo remains teachable and usable.

docs/api-and-solver-policy.md ADDED Viewed

	@@ -0,0 +1,90 @@

+# API And Solver Policy
+This page holds the longer reference material that must stay aligned with
+`src/api/routes.rs`, `src/api/dto.rs`, `src/solver/service.rs`,
+`src/solver/service/payload.rs`, `solver.toml`, and the visible API guide in
+`static/app/shell/api-guide.mjs`.
+## REST API
+- `GET /health`
+- `GET /info`
+- `GET /demo-data`
+- `GET /demo-data/{id}`
+- `POST /jobs`
+- `GET /jobs/{id}`
+- `GET /jobs/{id}/status`
+- `GET /jobs/{id}/snapshot`
+- `GET /jobs/{id}/analysis`
+- `POST /jobs/{id}/pause`
+- `POST /jobs/{id}/resume`
+- `POST /jobs/{id}/cancel`
+- `DELETE /jobs/{id}`
+- `GET /jobs/{id}/events`
+## Lifecycle Semantics
+- `pause` requests an exact runtime-managed pause and checkpoint
+- `resume` continues from the retained checkpoint
+- the user-facing Stop control calls `cancel` to stop a live or paused job
+- `delete` removes a terminal retained job before the next fresh solve
+- `GET /jobs/{id}` and `GET /jobs/{id}/status` return the same summary payload
+- `snapshot_revision={n}` is optional on both snapshot and analysis requests
+- reconnects bootstrap from current runtime status plus retained snapshot
+  revision, not from cached SSE text
+## Payload Shape
+The transport payload mirrors the domain model directly. The important field is
+`employeeIdx`, which is the scalar planning assignment chosen for each shift.
+```json
+{
+  "employees": [
+    {
+      "id": "employee-0",
+      "name": "Alex Smith",
+      "homeHub": "critical_care",
+      "skills": ["Critical care doctor"],
+      "unavailableDates": [],
+      "undesiredDates": [],
+      "desiredDates": []
+    }
+  ],
+  "shifts": [
+    {
+      "id": "shift-1",
+      "start": "2024-01-01T08:00:00",
+      "end": "2024-01-01T16:00:00",
+      "location": "Critical care",
+      "careHub": "critical_care",
+      "requiredSkill": "Critical care doctor",
+      "employeeIdx": 0
+    }
+  ],
+  "score": "0hard/0soft"
+}
+```
+Telemetry is intentionally a UI-facing projection, not the raw runtime type.
+Fields like `elapsedMs`, `movesPerSecond`, and `acceptanceRate` are derived for
+display.
+## Solver Policy
+The runtime source of truth is [../solver.toml](../solver.toml).
+The currently shipped policy is deliberately narrow:
+- `construction_heuristic = cheapest_insertion`
+- one local-search phase
+- nearby scalar change/swap selectors
+- `late_acceptance`
+- `accepted_count`
+This is the policy exercised by the standard runtime tests. `make test-slow`
+runs the ignored large-demo acceptance solve and is the required quality gate
+when changing that policy.
+The canonical description of current behavior is `solver.toml`, the code,
+`README.md`, this file, and `WIREFRAME.md`.

docs/screenshot.png ADDED Viewed

Git LFS Details

SHA256: 5f7678f6eccd57c55e8f5d550c5ac3614fd3f8325177eeafec620d9273014e4e
Pointer size: 131 Bytes
Size of remote file: 151 kB

solver.toml ADDED Viewed

	@@ -0,0 +1,43 @@

+# SolverForge configuration for the hospital example.
+#
+# This app uses scalar nearby selection directly. The care-hub meters in
+# `src/domain/plan.rs` keep local search focused enough to make real progress
+# on the hospital dataset inside the configured time limit.
+random_seed = 1
+[termination]
+seconds_spent_limit = 30
+unimproved_seconds_spent_limit = 5
+[[phases]]
+type = "construction_heuristic"
+construction_heuristic_type = "cheapest_insertion"
+entity_class = "Shift"
+variable_name = "employee_idx"
+[[phases]]
+type = "local_search"
+[phases.acceptor]
+type = "late_acceptance"
+late_acceptance_size = 400
+[phases.forager]
+type = "accepted_count"
+limit = 4
+[phases.move_selector]
+type = "union_move_selector"
+[[phases.move_selector.selectors]]
+type = "nearby_change_move_selector"
+entity_class = "Shift"
+variable_name = "employee_idx"
+max_nearby = 10
+[[phases.move_selector.selectors]]
+type = "nearby_swap_move_selector"
+entity_class = "Shift"
+variable_name = "employee_idx"
+max_nearby = 10

solverforge.app.toml ADDED Viewed

	@@ -0,0 +1,83 @@

+[app]
+name = "SolverForge Hospital"
+starter = "neutral-shell"
+shell = "web"
+cli_version = "2.2.2"
+[runtime]
+target = "solverforge 0.19.3"
+runtime_source = "crates.io: solverforge 0.19.3"
+ui_source = "crates.io: solverforge-ui 0.6.5"
+[demo]
+default_size = "LARGE"
+available_sizes = ["LARGE"]
+[solution]
+name = "Plan"
+score = "HardSoftDecimalScore"
+[[facts]]
+name = "employee"
+plural = "employees"
+kind = "problem_fact"
+[[entities]]
+name = "shift"
+plural = "shifts"
+kind = "planning_entity"
+[[variables]]
+entity = "shift"
+entity_plural = "shifts"
+field = "employee_idx"
+kind = "scalar"
+range = "employees"
+elements = ""
+allows_unassigned = true
+enabled = true
+[[constraints]]
+name = "assigned_shift"
+module = "assigned_shift"
+enabled = true
+[[constraints]]
+name = "required_skill"
+module = "required_skill"
+enabled = true
+[[constraints]]
+name = "overlapping_shift"
+module = "overlapping_shift"
+enabled = true
+[[constraints]]
+name = "minimum_rest"
+module = "minimum_rest"
+enabled = true
+[[constraints]]
+name = "one_shift_per_day"
+module = "one_shift_per_day"
+enabled = true
+[[constraints]]
+name = "unavailable_employee"
+module = "unavailable_employee"
+enabled = true
+[[constraints]]
+name = "undesired_day"
+module = "undesired_day"
+enabled = true
+[[constraints]]
+name = "desired_day"
+module = "desired_day"
+enabled = true
+[[constraints]]
+name = "balance_assignments"
+module = "balance_assignments"
+enabled = true

src/api/dto.rs ADDED Viewed

	@@ -0,0 +1,259 @@

+//! Transport DTOs that turn domain/runtime types into beginner-friendly JSON.
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+use solverforge::{
+    HardSoftDecimalScore, ScoreAnalysis, SolverLifecycleState, SolverSnapshot,
+    SolverSnapshotAnalysis, SolverStatus, SolverTelemetry, SolverTerminalReason,
+};
+use std::time::Duration;
+use crate::domain::Plan;
+/// Thin JSON wrapper around the planning solution.
+///
+/// We keep the plan fields flattened so the API payload reads like the domain
+/// model instead of like a transport envelope.
+#[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>,
+}
+/// One constraint row shown in the Analyze modal.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ConstraintAnalysisDto {
+    pub name: String,
+    pub weight: String,
+    pub score: String,
+    pub match_count: usize,
+}
+/// Top-level analysis payload returned by `/jobs/{id}/analysis`.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AnalyzeResponse {
+    pub score: String,
+    pub constraints: Vec<ConstraintAnalysisDto>,
+}
+/// UI-facing telemetry summary derived from exact runtime telemetry.
+#[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,
+}
+/// Compact job summary returned by `/jobs/{id}` and `/jobs/{id}/status`.
+#[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,
+}
+/// Snapshot payload returned by `/jobs/{id}/snapshot`.
+#[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,
+}
+/// Analysis payload tied to a specific retained snapshot revision.
+#[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 {
+    /// Captures the domain plan as a JSON object while keeping `score` explicit.
+    pub fn from_plan(plan: &Plan) -> Self {
+        let mut fields = plan.to_transport_fields();
+        fields.remove("score");
+        Self {
+            fields,
+            score: plan.score.map(|score| score.to_string()),
+        }
+    }
+    /// Rebuilds the normalized domain model from the flattened JSON payload.
+    pub fn to_domain(&self) -> Result<Plan, serde_json::Error> {
+        Plan::from_transport_fields(self.fields.clone())
+    }
+}
+impl TelemetryDto {
+    /// Projects exact runtime telemetry into the fields the browser displays.
+    pub fn from_runtime(telemetry: &SolverTelemetry) -> Self {
+        Self {
+            elapsed_ms: duration_millis_u64(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_millis_u64(telemetry.generation_time),
+            evaluation_ms: duration_millis_u64(telemetry.evaluation_time),
+            moves_per_second: moves_per_second(telemetry.moves_evaluated, telemetry.elapsed),
+            acceptance_rate: acceptance_rate(telemetry.moves_accepted, telemetry.moves_evaluated),
+        }
+    }
+}
+/// Small helper so the JSON surface stays integer-based.
+fn duration_millis_u64(duration: Duration) -> u64 {
+    u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
+}
+/// Derives whole moves per second from exact elapsed time.
+fn moves_per_second(moves_evaluated: u64, elapsed: Duration) -> u64 {
+    let nanos = elapsed.as_nanos();
+    if nanos == 0 {
+        return 0;
+    }
+    let rate = u128::from(moves_evaluated)
+        .saturating_mul(1_000_000_000)
+        .checked_div(nanos)
+        .unwrap_or(0);
+    u64::try_from(rate).unwrap_or(u64::MAX)
+}
+/// Derives acceptance as a decimal fraction for easy frontend display.
+fn acceptance_rate(moves_accepted: u64, moves_evaluated: u64) -> f64 {
+    if moves_evaluated == 0 {
+        0.0
+    } else {
+        moves_accepted as f64 / moves_evaluated as f64
+    }
+}
+impl JobSummaryDto {
+    /// Converts the runtime status summary into the JSON contract used by the app.
+    pub fn from_status(job_id: usize, status: &SolverStatus<HardSoftDecimalScore>) -> 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 {
+    /// Converts a retained snapshot into the richer snapshot JSON payload.
+    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 {
+    /// Packages exact snapshot analysis together with snapshot identity metadata.
+    pub fn from_snapshot_analysis(
+        snapshot: &SolverSnapshotAnalysis<HardSoftDecimalScore>,
+        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,
+        }
+    }
+}
+/// Converts SolverForge's detailed score analysis into the browser response shape.
+pub fn analysis_response(analysis: &ScoreAnalysis<HardSoftDecimalScore>) -> 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(),
+    }
+}
+/// Re-exports lifecycle labels so routes and tests share one mapping.
+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",
+    }
+}
+/// Re-exports terminal labels so routes and tests share one mapping.
+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",
+    }
+}
+#[cfg(test)]
+mod tests;

src/api/dto/tests.rs ADDED Viewed

	@@ -0,0 +1,146 @@

+//! DTO tests that keep transport JSON and generated UI metadata aligned.
+use super::*;
+use serde::Deserialize;
+use solverforge::ConstraintSet;
+use std::fs;
+use std::time::Duration;
+#[derive(Deserialize)]
+struct UiModel {
+    entities: Vec<UiNamedEntry>,
+    facts: Vec<UiNamedEntry>,
+    constraints: Vec<UiConstraint>,
+    views: Vec<UiView>,
+}
+#[derive(Debug, Deserialize, PartialEq, Eq)]
+struct UiConstraint {
+    name: String,
+    #[serde(rename = "type")]
+    constraint_type: String,
+}
+#[derive(Debug, Deserialize, PartialEq, Eq)]
+struct UiNamedEntry {
+    name: String,
+    plural: String,
+    label: String,
+}
+#[derive(Debug, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+struct UiView {
+    id: String,
+    kind: String,
+    label: String,
+    entity: String,
+    entity_plural: String,
+    source_plural: String,
+    variable_field: String,
+    allows_unassigned: bool,
+}
+#[test]
+fn plan_dto_returns_decode_errors_for_semantically_invalid_payloads() {
+    let dto = PlanDto {
+        fields: Map::new(),
+        score: None,
+    };
+    assert!(dto.to_domain().is_err());
+}
+#[test]
+fn runtime_telemetry_derives_stock_transport_fields() {
+    let telemetry = SolverTelemetry {
+        elapsed: Duration::from_millis(2_500),
+        step_count: 9,
+        moves_generated: 300,
+        moves_evaluated: 200,
+        moves_accepted: 50,
+        score_calculations: 80,
+        generation_time: Duration::from_millis(400),
+        evaluation_time: Duration::from_millis(900),
+        ..SolverTelemetry::default()
+    };
+    let dto = TelemetryDto::from_runtime(&telemetry);
+    assert_eq!(dto.elapsed_ms, 2_500);
+    assert_eq!(dto.step_count, 9);
+    assert_eq!(dto.moves_generated, 300);
+    assert_eq!(dto.moves_evaluated, 200);
+    assert_eq!(dto.moves_accepted, 50);
+    assert_eq!(dto.score_calculations, 80);
+    assert_eq!(dto.generation_ms, 400);
+    assert_eq!(dto.evaluation_ms, 900);
+    assert_eq!(dto.moves_per_second, 80);
+    assert!((dto.acceptance_rate - 0.25).abs() < f64::EPSILON);
+}
+#[test]
+fn analyzed_constraint_names_match_ui_model() {
+    let ui_model_path = concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/static/generated/ui-model.json"
+    );
+    let ui_model: UiModel =
+        serde_json::from_str(&fs::read_to_string(ui_model_path).unwrap()).unwrap();
+    let plan = Plan::new(Vec::new(), Vec::new());
+    let constraints = crate::constraints::create_constraints();
+    let analysis = constraints.evaluate_detailed(&plan);
+    let analyzed_constraints: Vec<String> = analysis
+        .iter()
+        .map(|analysis| analysis.constraint_ref.name.to_string())
+        .collect();
+    let ui_constraints: Vec<String> = ui_model
+        .constraints
+        .iter()
+        .map(|constraint| constraint.name.clone())
+        .collect();
+    assert_eq!(analyzed_constraints, ui_constraints);
+    assert_eq!(
+        ui_model.entities,
+        vec![UiNamedEntry {
+            name: "shift".to_string(),
+            plural: "shifts".to_string(),
+            label: "Shifts".to_string(),
+        }]
+    );
+    assert_eq!(
+        ui_model.facts,
+        vec![UiNamedEntry {
+            name: "employee".to_string(),
+            plural: "employees".to_string(),
+            label: "Employees".to_string(),
+        }]
+    );
+    assert_eq!(
+        ui_model.views,
+        vec![
+            UiView {
+                id: "by-location".to_string(),
+                kind: "schedule-by-location".to_string(),
+                label: "By location".to_string(),
+                entity: "shift".to_string(),
+                entity_plural: "shifts".to_string(),
+                source_plural: "employees".to_string(),
+                variable_field: "employeeIdx".to_string(),
+                allows_unassigned: true,
+            },
+            UiView {
+                id: "by-employee".to_string(),
+                kind: "schedule-by-employee".to_string(),
+                label: "By employee".to_string(),
+                entity: "shift".to_string(),
+                entity_plural: "shifts".to_string(),
+                source_plural: "employees".to_string(),
+                variable_field: "employeeIdx".to_string(),
+                allows_unassigned: true,
+            }
+        ]
+    );
+}

src/api/mod.rs ADDED Viewed

	@@ -0,0 +1,13 @@

+//! HTTP transport surface for the example application.
+//!
+//! The API layer is split into:
+//! - DTOs that translate runtime/domain types into JSON
+//! - routes that bind those DTOs to HTTP endpoints
+//! - SSE glue for live lifecycle updates
+mod dto;
+mod routes;
+mod sse;
+pub use dto::PlanDto;
+pub use routes::{router, AppState};

src/api/routes.rs ADDED Viewed

	@@ -0,0 +1,225 @@

+//! HTTP routes for the hospital example.
+//!
+//! These handlers stay intentionally small: each one should read like
+//! "decode request -> call `SolverService` -> encode response".
+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::{self, DemoData};
+use crate::solver::SolverService;
+/// Shared application state stored inside Axum.
+pub struct AppState {
+    pub solver: SolverService,
+}
+impl AppState {
+    /// Builds the shared runtime facade once for the whole router.
+    pub fn new() -> Self {
+        Self {
+            solver: SolverService::new(),
+        }
+    }
+}
+impl Default for AppState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+/// Registers the full public HTTP surface of the example app.
+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,
+}
+/// Liveness probe used by demos and container platforms.
+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,
+}
+/// Tiny self-description endpoint for the UI and quick manual checks.
+async fn info() -> Json<InfoResponse> {
+    Json(InfoResponse {
+        name: env!("CARGO_PKG_NAME"),
+        version: env!("CARGO_PKG_VERSION"),
+        solver_engine: "SolverForge",
+    })
+}
+/// Lists the demo ids accepted by `/demo-data/{id}`.
+async fn list_demo_data() -> Json<Vec<&'static str>> {
+    Json(data::list_demo_data())
+}
+/// Materializes one demo dataset and returns it as a `PlanDto`.
+async fn get_demo_data(Path(id): Path<String>) -> Result<Json<PlanDto>, StatusCode> {
+    let demo = id.parse::<DemoData>().map_err(|_| StatusCode::NOT_FOUND)?;
+    Ok(Json(PlanDto::from_plan(&data::generate(demo))))
+}
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct CreateJobResponse {
+    id: String,
+}
+/// Starts a retained solve for the posted plan payload.
+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 }))
+}
+/// Returns the current retained-job summary.
+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)))
+}
+/// Alias route kept for the stock job-summary URL shape.
+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>,
+}
+/// Fetches either the latest retained snapshot or an exact revision.
+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)))
+}
+/// Runs exact score analysis against a retained snapshot revision.
+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,
+    )))
+}
+/// Requests that the runtime pause the job at the next exact safe point.
+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)
+}
+/// Resumes a paused retained job.
+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)
+}
+/// Cancels a live or paused retained job.
+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)
+}
+/// Deletes a terminal retained job and its cached SSE state.
+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)
+}
+/// Parses the path segment into the numeric runtime job id.
+fn parse_job_id(id: &str) -> Result<usize, StatusCode> {
+    id.parse::<usize>().map_err(|_| StatusCode::NOT_FOUND)
+}
+/// Maps stock runtime errors onto the HTTP semantics the UI expects.
+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,
+    }
+}
+#[cfg(test)]
+mod tests;

src/api/routes/tests.rs ADDED Viewed

	@@ -0,0 +1,239 @@

+//! Route tests for the retained-job HTTP contract.
+use super::*;
+use axum::body::{to_bytes, Body};
+use axum::http::Request;
+use tower::util::ServiceExt;
+use crate::domain::{Employee, Plan};
+fn empty_plan() -> PlanDto {
+    PlanDto::from_plan(&Plan::new(
+        vec![Employee::new(0, "Alex").with_skill("Doctor")],
+        vec![],
+    ))
+}
+fn heavy_plan() -> PlanDto {
+    PlanDto::from_plan(&data::generate(DemoData::Large))
+}
+async fn json_body(response: axum::response::Response) -> serde_json::Value {
+    let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+    serde_json::from_slice(&body).unwrap()
+}
+async fn post_plan(app: &Router, path: &str, plan: &PlanDto) -> axum::response::Response {
+    post_json_bytes(app, path, serde_json::to_vec(plan).unwrap()).await
+}
+async fn post_json_bytes(app: &Router, path: &str, body: Vec<u8>) -> axum::response::Response {
+    app.clone()
+        .oneshot(
+            Request::post(path)
+                .header("content-type", "application/json")
+                .body(Body::from(body))
+                .unwrap(),
+        )
+        .await
+        .unwrap()
+}
+async fn request(app: &Router, method: &str, path: &str) -> axum::response::Response {
+    app.clone()
+        .oneshot(
+            Request::builder()
+                .method(method)
+                .uri(path)
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap()
+}
+async fn wait_for_status(
+    app: &Router,
+    id: &str,
+    predicate: impl Fn(&serde_json::Value) -> bool,
+) -> serde_json::Value {
+    for _ in 0..200 {
+        let response = request(app, "GET", &format!("/jobs/{id}")).await;
+        if response.status() == StatusCode::OK {
+            let json = json_body(response).await;
+            if predicate(&json) {
+                return json;
+            }
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+    }
+    panic!("timed out waiting for job status");
+}
+async fn wait_for_ok_json(app: &Router, path: &str) -> serde_json::Value {
+    for _ in 0..200 {
+        let response = request(app, "GET", path).await;
+        if response.status() == StatusCode::OK {
+            return json_body(response).await;
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+    }
+    panic!("timed out waiting for successful response on {path}");
+}
+async fn wait_for_terminal(app: &Router, id: &str) -> serde_json::Value {
+    wait_for_status(app, id, |json| {
+        matches!(
+            json["lifecycleState"].as_str(),
+            Some("COMPLETED") | Some("CANCELLED") | Some("FAILED")
+        )
+    })
+    .await
+}
+async fn cleanup_job(app: &Router, id: &str) {
+    let status = request(app, "GET", &format!("/jobs/{id}")).await;
+    if status.status() == StatusCode::NOT_FOUND {
+        return;
+    }
+    let summary = json_body(status).await;
+    let lifecycle = summary["lifecycleState"].as_str().unwrap_or("");
+    if !matches!(lifecycle, "COMPLETED" | "CANCELLED" | "FAILED") {
+        let cancel = request(app, "POST", &format!("/jobs/{id}/cancel")).await;
+        assert!(
+            cancel.status() == StatusCode::ACCEPTED || cancel.status() == StatusCode::CONFLICT,
+            "unexpected cancel status {}",
+            cancel.status()
+        );
+        let _ = wait_for_terminal(app, id).await;
+    }
+    let delete = request(app, "DELETE", &format!("/jobs/{id}")).await;
+    assert!(
+        delete.status() == StatusCode::NO_CONTENT || delete.status() == StatusCode::NOT_FOUND,
+        "unexpected delete status {}",
+        delete.status()
+    );
+}
+#[tokio::test]
+async fn stock_jobs_contract_is_exposed_without_schedule_compatibility() {
+    let app = router(Arc::new(AppState::new()));
+    let create = post_plan(&app, "/jobs", &empty_plan()).await;
+    assert_eq!(create.status(), StatusCode::OK);
+    let create_json = json_body(create).await;
+    let terminal_id = create_json["id"].as_str().unwrap().to_string();
+    assert!(!terminal_id.is_empty());
+    assert!(create_json.get("jobId").is_none());
+    let summary = wait_for_status(&app, &terminal_id, |_| true).await;
+    assert_eq!(summary["id"], terminal_id);
+    assert_eq!(summary["jobId"], terminal_id);
+    assert!(summary.get("lifecycleState").is_some());
+    assert!(summary.get("checkpointAvailable").is_some());
+    assert!(summary.get("eventSequence").is_some());
+    assert!(summary.get("telemetry").is_some());
+    let snapshot = wait_for_ok_json(&app, &format!("/jobs/{terminal_id}/snapshot")).await;
+    assert_eq!(snapshot["id"], terminal_id);
+    assert_eq!(snapshot["jobId"], terminal_id);
+    assert!(snapshot.get("snapshotRevision").is_some());
+    assert!(snapshot.get("solution").is_some());
+    let cancel_empty = request(&app, "POST", &format!("/jobs/{terminal_id}/cancel")).await;
+    assert_eq!(cancel_empty.status(), StatusCode::ACCEPTED);
+    let terminal = wait_for_terminal(&app, &terminal_id).await;
+    assert_eq!(terminal["lifecycleState"], "CANCELLED");
+    let analysis = wait_for_ok_json(&app, &format!("/jobs/{terminal_id}/analysis")).await;
+    assert_eq!(analysis["id"], terminal_id);
+    assert_eq!(analysis["jobId"], terminal_id);
+    assert!(analysis.get("analysis").is_some());
+    let cancel_again = request(&app, "POST", &format!("/jobs/{terminal_id}/cancel")).await;
+    assert_eq!(cancel_again.status(), StatusCode::CONFLICT);
+    let delete_terminal = request(&app, "DELETE", &format!("/jobs/{terminal_id}")).await;
+    assert_eq!(delete_terminal.status(), StatusCode::NO_CONTENT);
+    let missing_status = request(&app, "GET", &format!("/jobs/{terminal_id}/status")).await;
+    assert_eq!(missing_status.status(), StatusCode::NOT_FOUND);
+    let live_create = post_plan(&app, "/jobs", &heavy_plan()).await;
+    assert_eq!(live_create.status(), StatusCode::OK);
+    let live_id = json_body(live_create).await["id"]
+        .as_str()
+        .unwrap()
+        .to_string();
+    let _ = wait_for_status(&app, &live_id, |json| {
+        json["lifecycleState"] == "SOLVING" || json["lifecycleState"] == "PAUSE_REQUESTED"
+    })
+    .await;
+    let delete_live = request(&app, "DELETE", &format!("/jobs/{live_id}")).await;
+    assert_eq!(delete_live.status(), StatusCode::CONFLICT);
+    let pause = request(&app, "POST", &format!("/jobs/{live_id}/pause")).await;
+    assert_eq!(pause.status(), StatusCode::ACCEPTED);
+    let _ = wait_for_status(&app, &live_id, |json| json["lifecycleState"] == "PAUSED").await;
+    let delete_paused = request(&app, "DELETE", &format!("/jobs/{live_id}")).await;
+    assert_eq!(delete_paused.status(), StatusCode::CONFLICT);
+    let resume = request(&app, "POST", &format!("/jobs/{live_id}/resume")).await;
+    assert_eq!(resume.status(), StatusCode::ACCEPTED);
+    let _ = wait_for_status(&app, &live_id, |json| {
+        json["lifecycleState"] == "SOLVING" || json["lifecycleState"] == "PAUSE_REQUESTED"
+    })
+    .await;
+    let cancel = request(&app, "POST", &format!("/jobs/{live_id}/cancel")).await;
+    assert_eq!(cancel.status(), StatusCode::ACCEPTED);
+    let _ = wait_for_terminal(&app, &live_id).await;
+    let delete_cancelled = request(&app, "DELETE", &format!("/jobs/{live_id}")).await;
+    assert_eq!(delete_cancelled.status(), StatusCode::NO_CONTENT);
+    let mut full_ids = Vec::new();
+    for _ in 0..16 {
+        let response = post_plan(&app, "/jobs", &heavy_plan()).await;
+        if response.status() != StatusCode::OK {
+            break;
+        }
+        let id = json_body(response).await["id"]
+            .as_str()
+            .unwrap()
+            .to_string();
+        full_ids.push(id);
+    }
+    assert_eq!(
+        full_ids.len(),
+        16,
+        "expected to occupy all 16 runtime job slots"
+    );
+    let full_response = post_plan(&app, "/jobs", &heavy_plan()).await;
+    assert_eq!(full_response.status(), StatusCode::SERVICE_UNAVAILABLE);
+    for id in full_ids {
+        cleanup_job(&app, &id).await;
+    }
+    let old_contract = request(&app, "POST", "/schedules").await;
+    assert_eq!(old_contract.status(), StatusCode::NOT_FOUND);
+}
+#[tokio::test]
+async fn semantically_invalid_jobs_payload_returns_bad_request_without_killing_router() {
+    let app = router(Arc::new(AppState::new()));
+    let invalid = post_json_bytes(&app, "/jobs", br#"{}"#.to_vec()).await;
+    assert_eq!(invalid.status(), StatusCode::BAD_REQUEST);
+    let valid = post_plan(&app, "/jobs", &empty_plan()).await;
+    assert_eq!(valid.status(), StatusCode::OK);
+    let job_id = json_body(valid).await["id"].as_str().unwrap().to_string();
+    cleanup_job(&app, &job_id).await;
+}

src/api/sse.rs ADDED Viewed

	@@ -0,0 +1,74 @@

+//! Server-Sent Events endpoint for live solver lifecycle updates.
+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;
+/// Streams one bootstrap event followed by all future live job events.
+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);
+    // New clients first receive the latest known state so the UI can render
+    // immediately instead of waiting for the next live runtime event.
+    let bootstrap = tokio_stream::iter(std::iter::once(Ok::<_, std::convert::Infallible>(
+        format!("data: {}\n\n", bootstrap_json).into_bytes(),
+    )));
+    // After the bootstrap event we forward every future retained-job update as
+    // a normal SSE `data:` frame.
+    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,
+    });
+    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())
+}
+/// Reads lifecycle sequence metadata so bootstrap and live frames do not duplicate.
+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)
+        })
+}
+/// Drops live events already represented by the bootstrap status snapshot.
+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/assigned_shift.rs ADDED Viewed

	@@ -0,0 +1,14 @@

+use crate::domain::{Plan, PlanConstraintStreams};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+const SCORE_SCALE: i64 = 100_000;
+/// Hard-penalizes each shift whose scalar planning variable is still unassigned.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .unassigned()
+        .penalize(HardSoftDecimalScore::of_hard_scaled(SCORE_SCALE))
+        .named("Assigned shift")
+}

src/constraints/balance_assignments.rs ADDED Viewed

	@@ -0,0 +1,12 @@

+use crate::domain::{Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+/// Softly penalizes uneven distribution of assigned shifts by `employee_idx`.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .balance(|shift: &Shift| shift.employee_idx)
+        .penalize(HardSoftDecimalScore::one_soft())
+        .named("Balance employee assignments")
+}

src/constraints/desired_day.rs ADDED Viewed

	@@ -0,0 +1,33 @@

+use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+/// Rewards assigning an employee to dates they explicitly prefer.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .filter(|shift: &Shift| shift.employee_idx.is_some())
+        .join((
+            ConstraintFactory::<Plan, HardSoftDecimalScore>::new().employees(),
+            joiner::equal_bi(
+                |shift: &Shift| shift.employee_idx,
+                |employee: &Employee| Some(employee.index),
+            ),
+        ))
+        .filter(|shift: &Shift, employee: &Employee| {
+            employee
+                .desired_days
+                .iter()
+                .any(|date| shift.touched_dates().contains(date))
+        })
+        .reward(|shift: &Shift, employee: &Employee| {
+            HardSoftDecimalScore::of_soft(
+                employee
+                    .desired_days
+                    .iter()
+                    .filter(|date| shift.touched_dates().contains(date))
+                    .count() as i64,
+            )
+        })
+        .named("Desired day for employee")
+}

src/constraints/minimum_rest.rs ADDED Viewed

	@@ -0,0 +1,38 @@

+use crate::domain::{Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+const SCORE_SCALE: i64 = 100_000;
+const STRUCTURAL_MINUTE_HARD_UNITS: i64 = 20;
+/// Hard-penalizes same-employee shift pairs separated by less than 10 hours.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .filter(|shift: &Shift| shift.employee_idx.is_some())
+        .join(joiner::equal(|shift: &Shift| shift.employee_idx))
+        .filter(|a: &Shift, b: &Shift| {
+            if a.index >= b.index {
+                return false;
+            }
+            let (earlier, later) = if a.end <= b.start {
+                (a, b)
+            } else if b.end <= a.start {
+                (b, a)
+            } else {
+                return false;
+            };
+            let gap_minutes = (later.start - earlier.end).num_minutes();
+            (0..600).contains(&gap_minutes)
+        })
+        .penalize(hard_weight(|a: &Shift, b: &Shift| {
+            let (earlier, later) = if a.end <= b.start { (a, b) } else { (b, a) };
+            let gap_minutes = (later.start - earlier.end).num_minutes();
+            HardSoftDecimalScore::of_hard_scaled(
+                (600 - gap_minutes) * STRUCTURAL_MINUTE_HARD_UNITS * SCORE_SCALE,
+            )
+        }))
+        .named("At least 10 hours between 2 shifts")
+}

src/constraints/mod.rs ADDED Viewed

	@@ -0,0 +1,43 @@

+#![cfg_attr(rustfmt, rustfmt_skip)]
+//! Constraint assembly for employee scheduling.
+//!
+//! Each sibling module contributes one named rule. `create_constraints()`
+//! simply lists them in the order we want them to appear in analysis output.
+use crate::domain::Plan;
+use solverforge::prelude::*;
+pub use self::assemble::create_constraints;
+// @solverforge:begin constraint-modules
+mod assigned_shift;
+mod required_skill;
+mod overlapping_shift;
+mod minimum_rest;
+mod one_shift_per_day;
+mod unavailable_employee;
+mod undesired_day;
+mod desired_day;
+mod balance_assignments;
+// @solverforge:end constraint-modules
+mod assemble {
+    use super::*;
+    /// Collects the full scoring model used by `Plan`.
+    pub fn create_constraints() -> impl ConstraintSet<Plan, HardSoftDecimalScore> {
+        // @solverforge:begin constraint-calls
+        (
+            assigned_shift::constraint(),
+            required_skill::constraint(),
+            overlapping_shift::constraint(),
+            minimum_rest::constraint(),
+            one_shift_per_day::constraint(),
+            unavailable_employee::constraint(),
+            undesired_day::constraint(),
+            desired_day::constraint(),
+            balance_assignments::constraint(),
+        )
+        // @solverforge:end constraint-calls
+    }
+}

src/constraints/one_shift_per_day.rs ADDED Viewed

	@@ -0,0 +1,21 @@

+use crate::domain::{Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+const SCORE_SCALE: i64 = 100_000;
+/// Hard-penalizes assigning two shifts that touch the same calendar day to one employee.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .filter(|shift: &Shift| shift.employee_idx.is_some())
+        .join(joiner::equal(|shift: &Shift| shift.employee_idx))
+        .filter(|a: &Shift, b: &Shift| {
+            a.index < b.index
+                && a.touched_dates()
+                    .iter()
+                    .any(|date| b.touched_dates().contains(date))
+        })
+        .penalize(HardSoftDecimalScore::of_hard_scaled(20 * SCORE_SCALE))
+        .named("One shift per day")
+}

src/constraints/overlapping_shift.rs ADDED Viewed

	@@ -0,0 +1,28 @@

+use crate::domain::{Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+const SCORE_SCALE: i64 = 100_000;
+const STRUCTURAL_MINUTE_HARD_UNITS: i64 = 20;
+/// Penalizes overlapping time windows for the same employee.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .filter(|shift: &Shift| shift.employee_idx.is_some())
+        .join(joiner::equal(|shift: &Shift| shift.employee_idx))
+        .filter(|a: &Shift, b: &Shift| a.index < b.index && a.start < b.end && b.start < a.end)
+        .penalize(hard_weight(|a: &Shift, b: &Shift| {
+            let overlap_start = a.start.max(b.start);
+            let overlap_end = a.end.min(b.end);
+            let overlap_minutes = if overlap_start < overlap_end {
+                (overlap_end - overlap_start).num_minutes()
+            } else {
+                0
+            };
+            HardSoftDecimalScore::of_hard_scaled(
+                overlap_minutes * STRUCTURAL_MINUTE_HARD_UNITS * SCORE_SCALE,
+            )
+        }))
+        .named("Overlapping shift")
+}

src/constraints/required_skill.rs ADDED Viewed

	@@ -0,0 +1,24 @@

+use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+const SCORE_SCALE: i64 = 100_000;
+/// Penalizes assignments where the employee lacks the required skill label.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .filter(|shift: &Shift| shift.employee_idx.is_some())
+        .join((
+            ConstraintFactory::<Plan, HardSoftDecimalScore>::new().employees(),
+            joiner::equal_bi(
+                |shift: &Shift| shift.employee_idx,
+                |employee: &Employee| Some(employee.index),
+            ),
+        ))
+        .filter(|shift: &Shift, employee: &Employee| {
+            !employee.skills.contains(&shift.required_skill)
+        })
+        .penalize(HardSoftDecimalScore::of_hard_scaled(10 * SCORE_SCALE))
+        .named("Required skill")
+}

src/constraints/unavailable_employee.rs ADDED Viewed

	@@ -0,0 +1,58 @@

+use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+const SCORE_SCALE: i64 = 100_000;
+const STRUCTURAL_MINUTE_HARD_UNITS: i64 = 20;
+/// Hard-penalizes unavailable-date overlap, scaled by overlapping minutes.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .filter(|shift: &Shift| shift.employee_idx.is_some())
+        .join((
+            ConstraintFactory::<Plan, HardSoftDecimalScore>::new().employees(),
+            joiner::equal_bi(
+                |shift: &Shift| shift.employee_idx,
+                |employee: &Employee| Some(employee.index),
+            ),
+        ))
+        .filter(|shift: &Shift, employee: &Employee| {
+            employee.unavailable_days.iter().any(|date| {
+                let day_start = date.and_hms_opt(0, 0, 0).unwrap();
+                let day_end = date
+                    .succ_opt()
+                    .unwrap_or(*date)
+                    .and_hms_opt(0, 0, 0)
+                    .unwrap();
+                let overlap_start = shift.start.max(day_start);
+                let overlap_end = shift.end.min(day_end);
+                overlap_start < overlap_end
+            })
+        })
+        .penalize(hard_weight(|shift: &Shift, employee: &Employee| {
+            let overlap_minutes: i64 = employee
+                .unavailable_days
+                .iter()
+                .map(|date| {
+                    let day_start = date.and_hms_opt(0, 0, 0).unwrap();
+                    let day_end = date
+                        .succ_opt()
+                        .unwrap_or(*date)
+                        .and_hms_opt(0, 0, 0)
+                        .unwrap();
+                    let overlap_start = shift.start.max(day_start);
+                    let overlap_end = shift.end.min(day_end);
+                    if overlap_start < overlap_end {
+                        (overlap_end - overlap_start).num_minutes()
+                    } else {
+                        0
+                    }
+                })
+                .sum();
+            HardSoftDecimalScore::of_hard_scaled(
+                overlap_minutes * STRUCTURAL_MINUTE_HARD_UNITS * SCORE_SCALE,
+            )
+        }))
+        .named("Unavailable employee")
+}

src/constraints/undesired_day.rs ADDED Viewed

	@@ -0,0 +1,33 @@

+use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
+use solverforge::prelude::*;
+use solverforge::IncrementalConstraint;
+/// Softly penalizes assignments that land on an employee's undesired dates.
+pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
+    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
+        .shifts()
+        .filter(|shift: &Shift| shift.employee_idx.is_some())
+        .join((
+            ConstraintFactory::<Plan, HardSoftDecimalScore>::new().employees(),
+            joiner::equal_bi(
+                |shift: &Shift| shift.employee_idx,
+                |employee: &Employee| Some(employee.index),
+            ),
+        ))
+        .filter(|shift: &Shift, employee: &Employee| {
+            employee
+                .undesired_days
+                .iter()
+                .any(|date| shift.touched_dates().contains(date))
+        })
+        .penalize(|shift: &Shift, employee: &Employee| {
+            HardSoftDecimalScore::of_soft(
+                employee
+                    .undesired_days
+                    .iter()
+                    .filter(|date| shift.touched_dates().contains(date))
+                    .count() as i64,
+            )
+        })
+        .named("Undesired day for employee")
+}

src/data/data_seed.rs ADDED Viewed

	@@ -0,0 +1,28 @@

+//! Public demo-data surface for the hospital example.
+//!
+//! Keep this file intentionally thin. The rest of the application imports
+//! `crate::data::{generate, list_demo_data, DemoData}` as a stable boundary, so
+//! the detailed dataset design lives in sibling modules where it can evolve
+//! without making the top-level data surface noisy.
+mod availability;
+mod cohorts;
+mod coverage;
+mod demand;
+mod employees;
+mod entrypoints;
+mod large;
+mod preferences;
+mod shifts;
+mod skills;
+mod time_utils;
+mod validation;
+mod vocabulary;
+mod witness;
+#[cfg(test)]
+mod solve_tests;
+#[cfg(test)]
+mod tests;
+pub use entrypoints::{generate, list_demo_data, DemoData};

src/data/data_seed/availability.rs ADDED Viewed

	@@ -0,0 +1,72 @@

+use chrono::NaiveDate;
+use std::cmp::Reverse;
+use std::collections::BTreeSet;
+use crate::domain::{Employee, Shift};
+use super::coverage::{candidate_redundancy_is_valid, public_candidate_counts};
+use super::time_utils::horizon_dates;
+use super::vocabulary::EXTRA_UNAVAILABLE_COUNT;
+/// Adds a small amount of extra unavailability without breaking public feasibility.
+///
+/// The goal is not to make the dataset impossible. The goal is to remove some
+/// trivial interchangeable assignments so local search has a clearer signal.
+pub(super) fn add_extra_unavailability(
+    employees: &mut [Employee],
+    shifts: &[Shift],
+    witness_dates: &[BTreeSet<NaiveDate>],
+) {
+    let horizon_dates = horizon_dates(shifts);
+    for _ in 0..EXTRA_UNAVAILABLE_COUNT {
+        let best_candidate = (0..employees.len())
+            .flat_map(|employee_index| {
+                horizon_dates
+                    .iter()
+                    .copied()
+                    .map(move |date| (employee_index, date))
+            })
+            .filter(|&(employee_index, date)| {
+                !employees[employee_index].unavailable_dates.contains(&date)
+                    && !witness_dates[employee_index].contains(&date)
+            })
+            .filter_map(|(employee_index, date)| {
+                let score = extra_unavailability_score(employees, shifts, employee_index, date)?;
+                Some((score, employee_index, date))
+            })
+            .max_by_key(|&(score, employee_index, date)| {
+                (score, Reverse(employee_index), Reverse(date))
+            });
+        let Some((_, employee_index, date)) = best_candidate else {
+            break;
+        };
+        employees[employee_index].unavailable_dates.insert(date);
+    }
+}
+/// Scores one candidate "employee unavailable on date" mutation.
+fn extra_unavailability_score(
+    employees: &[Employee],
+    shifts: &[Shift],
+    employee_index: usize,
+    date: NaiveDate,
+) -> Option<(usize, usize, usize)> {
+    let mut cloned: Vec<Employee> = employees.to_vec();
+    cloned[employee_index].unavailable_dates.insert(date);
+    if !candidate_redundancy_is_valid(&cloned, shifts) {
+        return None;
+    }
+    let counts = public_candidate_counts(&cloned, shifts);
+    let affected: Vec<usize> = shifts
+        .iter()
+        .enumerate()
+        .filter(|(_, shift)| shift.touched_dates.contains(&date))
+        .map(|(index, _)| counts[index])
+        .collect();
+    let min_affected = affected.into_iter().min().unwrap_or(usize::MAX);
+    let shifts_with_three_plus = counts.iter().filter(|&&count| count >= 3).count();
+    Some((min_affected, shifts_with_three_plus, counts.iter().sum()))
+}

src/data/data_seed/cohorts.rs ADDED Viewed

	@@ -0,0 +1,198 @@

+use std::cmp::Reverse;
+use super::employees::EmployeeBlueprint;
+use super::vocabulary::*;
+/// Running totals for one weekday-off cohort.
+///
+/// We use this to distribute scarce specialties across the seven primary
+/// off-day groups instead of accidentally clustering too many similar people on
+/// the same day off.
+#[derive(Default, Clone, Copy)]
+struct CohortLoad {
+    size: usize,
+    doctors: usize,
+    nurses: usize,
+    ambulatory_doctors: usize,
+    ambulatory_nurses: usize,
+    neurology_doctors: usize,
+    neurology_nurses: usize,
+    critical_doctors: usize,
+    critical_nurses: usize,
+    pediatric_doctors: usize,
+    pediatric_nurses: usize,
+    surgery_doctors: usize,
+    surgery_nurses: usize,
+    outpatient_doctors: usize,
+    outpatient_nurses: usize,
+    radiology_day: usize,
+    radiology_nurses: usize,
+    radiology_call: usize,
+    cardiology: usize,
+    anaesthetics: usize,
+}
+impl CohortLoad {
+    /// Updates the cohort totals after placing one blueprint into it.
+    fn add(&mut self, blueprint: &EmployeeBlueprint) {
+        self.size += 1;
+        if blueprint.skills.contains(DOCTOR) {
+            self.doctors += 1;
+        }
+        if blueprint.skills.contains(NURSE) {
+            self.nurses += 1;
+        }
+        if blueprint.skills.contains(AMBULATORY_DOCTOR) {
+            self.ambulatory_doctors += 1;
+        }
+        if blueprint.skills.contains(AMBULATORY_NURSE) {
+            self.ambulatory_nurses += 1;
+        }
+        if blueprint.skills.contains(NEUROLOGY_DOCTOR) {
+            self.neurology_doctors += 1;
+        }
+        if blueprint.skills.contains(NEUROLOGY_NURSE) {
+            self.neurology_nurses += 1;
+        }
+        if blueprint.skills.contains(CRITICAL_DOCTOR) {
+            self.critical_doctors += 1;
+        }
+        if blueprint.skills.contains(CRITICAL_NURSE) {
+            self.critical_nurses += 1;
+        }
+        if blueprint.skills.contains(PEDIATRIC_DOCTOR) {
+            self.pediatric_doctors += 1;
+        }
+        if blueprint.skills.contains(PEDIATRIC_NURSE) {
+            self.pediatric_nurses += 1;
+        }
+        if blueprint.skills.contains(SURGERY_DOCTOR) {
+            self.surgery_doctors += 1;
+        }
+        if blueprint.skills.contains(SURGERY_NURSE) {
+            self.surgery_nurses += 1;
+        }
+        if blueprint.skills.contains(OUTPATIENT_DOCTOR) {
+            self.outpatient_doctors += 1;
+        }
+        if blueprint.skills.contains(OUTPATIENT_NURSE) {
+            self.outpatient_nurses += 1;
+        }
+        if blueprint.skills.contains(RADIOLOGY_DAY) {
+            self.radiology_day += 1;
+        }
+        if blueprint.skills.contains(RADIOLOGY_NURSE) {
+            self.radiology_nurses += 1;
+        }
+        if blueprint.skills.contains(RADIOLOGY_CALL) {
+            self.radiology_call += 1;
+        }
+        if blueprint.skills.contains(CARDIOLOGY) {
+            self.cardiology += 1;
+        }
+        if blueprint.skills.contains(ANAESTHETICS) {
+            self.anaesthetics += 1;
+        }
+    }
+}
+/// Assigns each employee blueprint a stable primary off weekday.
+pub(super) fn assign_primary_off_days(blueprints: &mut [EmployeeBlueprint]) {
+    let mut order: Vec<usize> = (0..blueprints.len()).collect();
+    order.sort_by_key(|&index| Reverse(blueprint_priority(&blueprints[index])));
+    let mut loads = [CohortLoad::default(); 7];
+    for employee_index in order {
+        let cohort = (0..7)
+            .filter(|&candidate| loads[candidate].size < PRIMARY_OFF_COHORT_SIZES[candidate])
+            .min_by_key(|&candidate| cohort_score(&loads[candidate], &blueprints[employee_index]))
+            .expect("cohort should have spare capacity");
+        blueprints[employee_index].primary_off_weekday = cohort;
+        loads[cohort].add(&blueprints[employee_index]);
+    }
+}
+/// Scarcer or more specialized blueprints get placed first.
+fn blueprint_priority(blueprint: &EmployeeBlueprint) -> (usize, usize, usize, usize, usize) {
+    (
+        blueprint.specialty_count(),
+        usize::from(blueprint.skills.contains(DOCTOR)),
+        usize::from(blueprint.skills.contains(CARDIOLOGY)),
+        usize::from(blueprint.skills.contains(ANAESTHETICS)),
+        usize::from(blueprint.skills.contains(RADIOLOGY_CALL)),
+    )
+}
+/// Lower scores mean "this cohort needs this blueprint more".
+fn cohort_score(load: &CohortLoad, blueprint: &EmployeeBlueprint) -> (usize, usize, usize, usize) {
+    let line_pressure = weighted_line_load(load, blueprint);
+    (
+        line_pressure,
+        if blueprint.skills.contains(DOCTOR) {
+            load.doctors
+        } else {
+            load.nurses
+        },
+        load.size,
+        blueprint.primary_off_weekday,
+    )
+}
+/// Applies weighted pressure so rare specialties dominate balancing decisions.
+fn weighted_line_load(load: &CohortLoad, blueprint: &EmployeeBlueprint) -> usize {
+    let mut score = 0usize;
+    for (skill, weight) in line_balance_weights() {
+        if blueprint.has_skill(skill) {
+            score += line_load_for_skill(load, skill) * weight;
+        }
+    }
+    score
+}
+/// Manual weights that treat some specialties as harder to concentrate.
+fn line_balance_weights() -> &'static [(&'static str, usize)] {
+    &[
+        (CARDIOLOGY, 8),
+        (RADIOLOGY_CALL, 8),
+        (ANAESTHETICS, 7),
+        (SURGERY_NURSE, 6),
+        (SURGERY_DOCTOR, 6),
+        (NEUROLOGY_DOCTOR, 6),
+        (RADIOLOGY_DAY, 5),
+        (RADIOLOGY_NURSE, 5),
+        (OUTPATIENT_DOCTOR, 5),
+        (OUTPATIENT_NURSE, 5),
+        (AMBULATORY_DOCTOR, 4),
+        (AMBULATORY_NURSE, 4),
+        (PEDIATRIC_DOCTOR, 4),
+        (PEDIATRIC_NURSE, 4),
+        (NEUROLOGY_NURSE, 4),
+        (CRITICAL_DOCTOR, 3),
+        (CRITICAL_NURSE, 3),
+    ]
+}
+/// Reads the current cohort count for one specific skill.
+fn line_load_for_skill(load: &CohortLoad, skill: &'static str) -> usize {
+    match skill {
+        AMBULATORY_DOCTOR => load.ambulatory_doctors,
+        AMBULATORY_NURSE => load.ambulatory_nurses,
+        NEUROLOGY_DOCTOR => load.neurology_doctors,
+        NEUROLOGY_NURSE => load.neurology_nurses,
+        CRITICAL_DOCTOR => load.critical_doctors,
+        CRITICAL_NURSE => load.critical_nurses,
+        PEDIATRIC_DOCTOR => load.pediatric_doctors,
+        PEDIATRIC_NURSE => load.pediatric_nurses,
+        SURGERY_DOCTOR => load.surgery_doctors,
+        SURGERY_NURSE => load.surgery_nurses,
+        OUTPATIENT_DOCTOR => load.outpatient_doctors,
+        OUTPATIENT_NURSE => load.outpatient_nurses,
+        RADIOLOGY_DAY => load.radiology_day,
+        RADIOLOGY_NURSE => load.radiology_nurses,
+        RADIOLOGY_CALL => load.radiology_call,
+        CARDIOLOGY => load.cardiology,
+        ANAESTHETICS => load.anaesthetics,
+        _ => 0,
+    }
+}

src/data/data_seed/coverage.rs ADDED Viewed

	@@ -0,0 +1,47 @@

+use chrono::Timelike;
+use crate::domain::{Employee, Shift};
+use super::skills::is_specialty_skill;
+/// Checks that the public dataset still has enough legal candidates per shift.
+pub(super) fn candidate_redundancy_is_valid(employees: &[Employee], shifts: &[Shift]) -> bool {
+    let counts = public_candidate_counts(employees, shifts);
+    if counts.iter().any(|&count| count < 2) {
+        return false;
+    }
+    if counts.iter().filter(|&&count| count >= 3).count() * 4 < shifts.len() {
+        return false;
+    }
+    if shifts.iter().zip(counts.iter()).any(|(shift, &count)| {
+        is_specialty_skill(&shift.required_skill) && shift.start.time().hour() == 22 && count < 2
+    }) {
+        return false;
+    }
+    true
+}
+/// Counts legal candidates per shift without considering schedule interactions.
+pub(super) fn public_candidate_counts(employees: &[Employee], shifts: &[Shift]) -> Vec<usize> {
+    shifts
+        .iter()
+        .map(|shift| {
+            employees
+                .iter()
+                .filter(|employee| employee_can_cover_shift_without_schedule(employee, shift))
+                .count()
+        })
+        .collect()
+}
+/// Coarse feasibility check used during dataset shaping.
+pub(super) fn employee_can_cover_shift_without_schedule(
+    employee: &Employee,
+    shift: &Shift,
+) -> bool {
+    employee.skills.contains(&shift.required_skill)
+        && shift
+            .touched_dates
+            .iter()
+            .all(|date| !employee.unavailable_dates.contains(date))
+}

src/data/data_seed/demand.rs ADDED Viewed

	@@ -0,0 +1,273 @@

+use chrono::Weekday;
+use super::vocabulary::*;
+/// Reusable calendar patterns for demand templates.
+#[derive(Clone, Copy)]
+pub(super) enum WeekPattern {
+    Weekdays,
+    Weekends,
+    Daily,
+    MonWedFri,
+    Saturday,
+    Sunday,
+}
+#[derive(Clone, Copy)]
+pub(super) struct DemandRule {
+    pub(super) location: &'static str,
+    pub(super) start_hour: u32,
+    pub(super) required_skill: &'static str,
+    pattern: WeekPattern,
+    pub(super) count: usize,
+}
+// This is the published demand template for the 28-day benchmark. Each rule
+// says "on matching weekdays, create `count` eight-hour shifts of this shape".
+pub(super) const DEMAND_RULES: &[DemandRule] = &[
+    DemandRule {
+        location: "Ambulatory care",
+        start_hour: 6,
+        required_skill: AMBULATORY_DOCTOR,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+    DemandRule {
+        location: "Ambulatory care",
+        start_hour: 14,
+        required_skill: AMBULATORY_NURSE,
+        pattern: WeekPattern::Weekdays,
+        count: 2,
+    },
+    DemandRule {
+        location: "Ambulatory care",
+        start_hour: 6,
+        required_skill: AMBULATORY_DOCTOR,
+        pattern: WeekPattern::Weekends,
+        count: 1,
+    },
+    DemandRule {
+        location: "Ambulatory care",
+        start_hour: 14,
+        required_skill: AMBULATORY_NURSE,
+        pattern: WeekPattern::Weekends,
+        count: 2,
+    },
+    DemandRule {
+        location: "Neurology",
+        start_hour: 6,
+        required_skill: NEUROLOGY_DOCTOR,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+    DemandRule {
+        location: "Neurology",
+        start_hour: 14,
+        required_skill: NEUROLOGY_NURSE,
+        pattern: WeekPattern::Weekdays,
+        count: 2,
+    },
+    DemandRule {
+        location: "Neurology",
+        start_hour: 6,
+        required_skill: NEUROLOGY_DOCTOR,
+        pattern: WeekPattern::Weekends,
+        count: 1,
+    },
+    DemandRule {
+        location: "Neurology",
+        start_hour: 14,
+        required_skill: NEUROLOGY_NURSE,
+        pattern: WeekPattern::Weekends,
+        count: 1,
+    },
+    DemandRule {
+        location: "Neurology",
+        start_hour: 22,
+        required_skill: CARDIOLOGY,
+        pattern: WeekPattern::MonWedFri,
+        count: 1,
+    },
+    DemandRule {
+        location: "Critical care",
+        start_hour: 6,
+        required_skill: CRITICAL_DOCTOR,
+        pattern: WeekPattern::Daily,
+        count: 2,
+    },
+    DemandRule {
+        location: "Critical care",
+        start_hour: 14,
+        required_skill: CRITICAL_NURSE,
+        pattern: WeekPattern::Daily,
+        count: 2,
+    },
+    DemandRule {
+        location: "Critical care",
+        start_hour: 22,
+        required_skill: CRITICAL_DOCTOR,
+        pattern: WeekPattern::Daily,
+        count: 1,
+    },
+    DemandRule {
+        location: "Critical care",
+        start_hour: 9,
+        required_skill: CRITICAL_NURSE,
+        pattern: WeekPattern::Weekdays,
+        count: 2,
+    },
+    DemandRule {
+        location: "Pediatric care",
+        start_hour: 6,
+        required_skill: PEDIATRIC_DOCTOR,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+    DemandRule {
+        location: "Pediatric care",
+        start_hour: 14,
+        required_skill: PEDIATRIC_NURSE,
+        pattern: WeekPattern::Weekdays,
+        count: 2,
+    },
+    DemandRule {
+        location: "Pediatric care",
+        start_hour: 6,
+        required_skill: PEDIATRIC_DOCTOR,
+        pattern: WeekPattern::Weekends,
+        count: 1,
+    },
+    DemandRule {
+        location: "Pediatric care",
+        start_hour: 14,
+        required_skill: PEDIATRIC_NURSE,
+        pattern: WeekPattern::Weekends,
+        count: 2,
+    },
+    DemandRule {
+        location: "Surgery",
+        start_hour: 6,
+        required_skill: SURGERY_DOCTOR,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+    DemandRule {
+        location: "Surgery",
+        start_hour: 14,
+        required_skill: ANAESTHETICS,
+        pattern: WeekPattern::Weekdays,
+        count: 2,
+    },
+    DemandRule {
+        location: "Surgery",
+        start_hour: 22,
+        required_skill: SURGERY_NURSE,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 6,
+        required_skill: RADIOLOGY_DAY,
+        pattern: WeekPattern::Weekdays,
+        count: 2,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 9,
+        required_skill: RADIOLOGY_DAY,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 14,
+        required_skill: RADIOLOGY_NURSE,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 22,
+        required_skill: RADIOLOGY_CALL,
+        pattern: WeekPattern::MonWedFri,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 6,
+        required_skill: RADIOLOGY_DAY,
+        pattern: WeekPattern::Saturday,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 9,
+        required_skill: RADIOLOGY_DAY,
+        pattern: WeekPattern::Saturday,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 14,
+        required_skill: RADIOLOGY_NURSE,
+        pattern: WeekPattern::Saturday,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 6,
+        required_skill: RADIOLOGY_DAY,
+        pattern: WeekPattern::Sunday,
+        count: 1,
+    },
+    DemandRule {
+        location: "Radiology",
+        start_hour: 9,
+        required_skill: RADIOLOGY_DAY,
+        pattern: WeekPattern::Sunday,
+        count: 1,
+    },
+    DemandRule {
+        location: "Outpatient",
+        start_hour: 6,
+        required_skill: OUTPATIENT_NURSE,
+        pattern: WeekPattern::Weekdays,
+        count: 2,
+    },
+    DemandRule {
+        location: "Outpatient",
+        start_hour: 14,
+        required_skill: OUTPATIENT_DOCTOR,
+        pattern: WeekPattern::Weekdays,
+        count: 1,
+    },
+];
+impl DemandRule {
+    /// Expands a rule into the number of shifts it contributes on a specific weekday.
+    pub(super) fn count_for_date(&self, weekday: Weekday) -> usize {
+        if self.pattern.matches(weekday) {
+            self.count
+        } else {
+            0
+        }
+    }
+}
+impl WeekPattern {
+    /// Returns whether the abstract pattern includes the given weekday.
+    fn matches(self, weekday: Weekday) -> bool {
+        match self {
+            WeekPattern::Weekdays => matches!(
+                weekday,
+                Weekday::Mon | Weekday::Tue | Weekday::Wed | Weekday::Thu | Weekday::Fri
+            ),
+            WeekPattern::Weekends => matches!(weekday, Weekday::Sat | Weekday::Sun),
+            WeekPattern::Daily => true,
+            WeekPattern::MonWedFri => matches!(weekday, Weekday::Mon | Weekday::Wed | Weekday::Fri),
+            WeekPattern::Saturday => weekday == Weekday::Sat,
+            WeekPattern::Sunday => weekday == Weekday::Sun,
+        }
+    }
+}

src/data/data_seed/employees.rs ADDED Viewed

	@@ -0,0 +1,150 @@

+use chrono::{Duration, NaiveDate};
+use rand::rngs::StdRng;
+use std::collections::BTreeSet;
+use crate::domain::{CareHub, Employee};
+use super::time_utils::generate_name_permutations;
+use super::vocabulary::*;
+/// Draft workforce record used before we instantiate full `Employee` facts.
+#[derive(Clone)]
+pub(super) struct EmployeeBlueprint {
+    pub(super) name: String,
+    pub(super) skills: BTreeSet<String>,
+    pub(super) home_hub: CareHub,
+    pub(super) primary_off_weekday: usize,
+}
+/// Builds the fixed workforce composition for the public demo dataset.
+pub(super) fn build_employee_blueprints(rng: &mut StdRng) -> Vec<EmployeeBlueprint> {
+    let names = generate_name_permutations(rng);
+    let mut skill_sets: Vec<Vec<&'static str>> = Vec::with_capacity(EMPLOYEE_COUNT);
+    // The generator used to hand almost every day shift to a generic Doctor or
+    // Nurse pool. That made most legal assignments interchangeable and flattened
+    // local search almost immediately. The redesign keeps the same workforce
+    // size, but assigns each employee to one or two service lines so every
+    // shift has a smaller, more meaningful candidate set.
+    //
+    // We still retain the base DOCTOR/NURSE tags so the witness builder can
+    // reason about role families, but public shifts now require service-line
+    // skills such as `Critical care doctor` or `Outpatient nurse`.
+    push_skill_sets(&mut skill_sets, 4, &[DOCTOR, CRITICAL_DOCTOR]);
+    push_skill_sets(
+        &mut skill_sets,
+        2,
+        &[DOCTOR, CRITICAL_DOCTOR, OUTPATIENT_DOCTOR],
+    );
+    push_skill_sets(&mut skill_sets, 4, &[DOCTOR, NEUROLOGY_DOCTOR, CARDIOLOGY]);
+    push_skill_sets(
+        &mut skill_sets,
+        3,
+        &[DOCTOR, AMBULATORY_DOCTOR, PEDIATRIC_DOCTOR],
+    );
+    push_skill_sets(&mut skill_sets, 4, &[DOCTOR, SURGERY_DOCTOR, ANAESTHETICS]);
+    push_skill_sets(
+        &mut skill_sets,
+        1,
+        &[DOCTOR, OUTPATIENT_DOCTOR, AMBULATORY_DOCTOR],
+    );
+    push_skill_sets(
+        &mut skill_sets,
+        4,
+        &[DOCTOR, RADIOLOGY_CALL, OUTPATIENT_DOCTOR],
+    );
+    push_skill_sets(&mut skill_sets, 5, &[NURSE, CRITICAL_NURSE]);
+    push_skill_sets(
+        &mut skill_sets,
+        3,
+        &[NURSE, CRITICAL_NURSE, OUTPATIENT_NURSE],
+    );
+    push_skill_sets(
+        &mut skill_sets,
+        4,
+        &[NURSE, AMBULATORY_NURSE, PEDIATRIC_NURSE],
+    );
+    push_skill_sets(
+        &mut skill_sets,
+        4,
+        &[NURSE, NEUROLOGY_NURSE, PEDIATRIC_NURSE],
+    );
+    push_skill_sets(
+        &mut skill_sets,
+        4,
+        &[NURSE, SURGERY_NURSE, OUTPATIENT_NURSE],
+    );
+    push_skill_sets(&mut skill_sets, 4, &[NURSE, RADIOLOGY_DAY, RADIOLOGY_NURSE]);
+    push_skill_sets(
+        &mut skill_sets,
+        2,
+        &[NURSE, RADIOLOGY_DAY, RADIOLOGY_NURSE, ANAESTHETICS],
+    );
+    push_skill_sets(
+        &mut skill_sets,
+        2,
+        &[NURSE, AMBULATORY_NURSE, OUTPATIENT_NURSE],
+    );
+    assert_eq!(
+        skill_sets.len(),
+        EMPLOYEE_COUNT,
+        "employee blueprint count should match workforce target"
+    );
+    skill_sets
+        .into_iter()
+        .enumerate()
+        .map(|(index, skills)| {
+            let home_hub = CareHub::infer_from_skills(skills.iter().copied());
+            EmployeeBlueprint {
+                name: names[index].clone(),
+                skills: skills.into_iter().map(str::to_string).collect(),
+                home_hub,
+                primary_off_weekday: 0,
+            }
+        })
+        .collect()
+}
+/// Appends `count` identical skill bundles to the blueprint list.
+fn push_skill_sets(target: &mut Vec<Vec<&'static str>>, count: usize, skills: &[&'static str]) {
+    for _ in 0..count {
+        target.push(skills.to_vec());
+    }
+}
+impl EmployeeBlueprint {
+    /// Tiny convenience helper used by balancing heuristics.
+    pub(super) fn has_skill(&self, skill: &'static str) -> bool {
+        self.skills.contains(skill)
+    }
+    /// Counts the specialties that are intentionally scarce in this dataset.
+    pub(super) fn specialty_count(&self) -> usize {
+        usize::from(self.skills.contains(CARDIOLOGY))
+            + usize::from(self.skills.contains(ANAESTHETICS))
+            + usize::from(self.skills.contains(RADIOLOGY_CALL))
+            + usize::from(self.skills.contains(RADIOLOGY_DAY))
+    }
+}
+/// Turns the blueprints into the actual `Employee` facts published by the app.
+pub(super) fn instantiate_employees(
+    blueprints: &[EmployeeBlueprint],
+    start_date: NaiveDate,
+) -> Vec<Employee> {
+    let mut employees = Vec::with_capacity(blueprints.len());
+    for (index, blueprint) in blueprints.iter().enumerate() {
+        let mut employee = Employee::new(index, blueprint.name.clone())
+            .with_home_hub(blueprint.home_hub)
+            .with_skills(blueprint.skills.iter().map(|skill| skill.as_str()));
+        for week in 0..(DAYS_IN_SCHEDULE / 7) {
+            let date = start_date + Duration::days(week * 7 + blueprint.primary_off_weekday as i64);
+            employee.unavailable_dates.insert(date);
+        }
+        employees.push(employee);
+    }
+    employees
+}

src/data/data_seed/entrypoints.rs ADDED Viewed

	@@ -0,0 +1,52 @@

+use std::str::FromStr;
+use crate::domain::Plan;
+use super::large::generate_large;
+/// Public demo-data identifiers exposed through the HTTP API.
+///
+/// The hospital app currently ships one serious benchmark instance rather than a
+/// menu of toy presets, so the surface stays explicit instead of pretending that
+/// multiple sizes exist when they do not.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DemoData {
+    Large,
+}
+impl FromStr for DemoData {
+    type Err = ();
+    /// Parses the case-insensitive demo id exposed over HTTP.
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_uppercase().as_str() {
+            "LARGE" => Ok(DemoData::Large),
+            _ => Err(()),
+        }
+    }
+}
+impl DemoData {
+    /// Returns the canonical uppercase id used by the HTTP API.
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            DemoData::Large => "LARGE",
+        }
+    }
+}
+/// Lists the demo identifiers accepted by `/demo-data/{id}`.
+pub fn list_demo_data() -> Vec<&'static str> {
+    vec![DemoData::Large.as_str()]
+}
+/// Generates the requested demo dataset.
+///
+/// Dispatch stays here so callers see the supported public variants in one
+/// place, while the dataset assembly itself remains hidden in the per-instance
+/// modules.
+pub fn generate(demo: DemoData) -> Plan {
+    match demo {
+        DemoData::Large => generate_large(),
+    }
+}

src/data/data_seed/large.rs ADDED Viewed

	@@ -0,0 +1,59 @@

+use std::sync::OnceLock;
+use chrono::NaiveDate;
+use rand::rngs::StdRng;
+use rand::SeedableRng;
+use crate::domain::Plan;
+use super::availability::add_extra_unavailability;
+use super::cohorts::assign_primary_off_days;
+use super::employees::{build_employee_blueprints, instantiate_employees};
+use super::preferences::add_preferences;
+use super::shifts::{build_public_shifts, prepare_shifts};
+use super::time_utils::find_next_monday;
+use super::validation::validate_public_dataset;
+use super::witness::build_hidden_witness;
+/// Materializes the canonical hospital benchmark dataset.
+///
+/// We cache the built plan because demo data is immutable and deterministic.
+/// Reusing the same constructed instance avoids paying generator cost on every
+/// API request while still returning an owned `Plan` to each caller.
+pub fn generate_large() -> Plan {
+    static SCHEDULE: OnceLock<Plan> = OnceLock::new();
+    SCHEDULE.get_or_init(build_large_schedule).clone()
+}
+/// Builds the single published benchmark instance from scratch.
+fn build_large_schedule() -> Plan {
+    let mut rng = StdRng::seed_from_u64(0);
+    let start_date = find_next_monday(NaiveDate::from_ymd_opt(2024, 1, 1).unwrap());
+    // Workforce blueprints are the stable source of truth for skill mix and
+    // cohort identity. We shape off-days at the blueprint level so the later
+    // instantiated employees inherit the intended coverage structure.
+    let mut blueprints = build_employee_blueprints(&mut rng);
+    assign_primary_off_days(&mut blueprints);
+    // The public problem is what the solver sees: employees plus currently
+    // unassigned shifts. We construct that surface before adding preference
+    // pressure so all later shaping is anchored to the real published dataset.
+    let mut employees = instantiate_employees(&blueprints, start_date);
+    let mut shifts = build_public_shifts(start_date);
+    prepare_shifts(&mut shifts);
+    // The witness roster is the generator's internal "known feasible" schedule.
+    // We never expose it to the solver. We use it only to shape calendars and
+    // preferences so the public problem stays feasible while still containing
+    // soft-pressure opportunities that construction does not get for free.
+    let witness = build_hidden_witness(&employees, &shifts);
+    add_extra_unavailability(&mut employees, &shifts, &witness.employee_touched_dates);
+    add_preferences(&mut employees, start_date, &blueprints, &shifts, &witness);
+    // Validation is the last step on purpose: it checks the exact public dataset
+    // that the API will serve rather than an earlier intermediate state.
+    validate_public_dataset(&employees, &shifts);
+    Plan::new(employees, shifts)
+}

src/data/data_seed/preferences.rs ADDED Viewed

	@@ -0,0 +1,190 @@

+//! Preference shaping for the public dataset.
+//!
+//! The hidden witness gives us a hard-feasible schedule. This module then adds
+//! desired/undesired dates so the public problem contains soft-score movement
+//! without throwing away that feasibility margin.
+mod exchange;
+mod floor;
+mod support;
+mod top_up;
+use chrono::NaiveDate;
+use std::collections::{BTreeMap, BTreeSet};
+use crate::domain::{Employee, Shift};
+use self::exchange::assign_exchange_preferences;
+use self::floor::ensure_preference_floor;
+use self::top_up::{add_weekend_preference_bias, top_up_preferences};
+use super::coverage::employee_can_cover_shift_without_schedule;
+use super::employees::EmployeeBlueprint;
+use super::vocabulary::{EXCHANGE_MARK_LIMIT_PER_EMPLOYEE, MAX_DESIRED_DATES, MAX_UNDESIRED_DATES};
+use super::witness::WitnessRoster;
+#[cfg(test)]
+pub(super) fn shift_soft_preference_score(employee: &Employee, shift: &Shift) -> i64 {
+    support::shift_soft_preference_score(employee, shift)
+}
+/// Adds the full preference surface for the public dataset.
+pub(super) fn add_preferences(
+    employees: &mut [Employee],
+    start_date: NaiveDate,
+    blueprints: &[EmployeeBlueprint],
+    shifts: &[Shift],
+    witness: &WitnessRoster,
+) {
+    let analysis = PreferenceAnalysis::build(employees, shifts, witness);
+    // Phase 1: create direct witness-relative exchange pressure.
+    //
+    // For a curated subset of shifts we mark the witness holder as disliking the
+    // touched date and mark one feasible alternative as preferring it. This makes
+    // the hidden witness intentionally non-soft-optimal and, more importantly,
+    // creates real one-move improvement opportunities in the public solution
+    // space instead of generic weekday-themed noise.
+    if let Some(max_exchange_marks_per_employee) = EXCHANGE_MARK_LIMIT_PER_EMPLOYEE {
+        assign_exchange_preferences(
+            employees,
+            blueprints,
+            shifts,
+            witness,
+            &analysis,
+            max_exchange_marks_per_employee,
+        );
+    }
+    // Phase 2: fill the remaining preference volume with stable weekday-themed
+    // dates. The pure witness-relative variant created a richer soft surface,
+    // but it also made cheapest-insertion too eager to burn hard feasibility.
+    // The hybrid shape keeps one explicit exchange signal while leaving the
+    // bulk of the dataset in a feasibility-friendly, deterministic pattern.
+    top_up_preferences(employees, start_date, blueprints);
+    // Phase 3: add a tiny weekend bias only when the employee is still below the
+    // target preference floor. This keeps the designed feasibility margin while
+    // still breaking some of the largest weekday-only symmetries.
+    add_weekend_preference_bias(employees, start_date, blueprints);
+    ensure_preference_floor(
+        employees,
+        &witness.employee_touched_dates,
+        &analysis.coverable_dates_by_employee,
+        &analysis.date_pressure,
+    );
+    for employee in employees.iter() {
+        assert!(
+            employee.desired_dates.len() >= 4 && employee.desired_dates.len() <= MAX_DESIRED_DATES,
+            "desired-date volume should stay in the designed band"
+        );
+        assert!(
+            employee.undesired_dates.len() >= 4
+                && employee.undesired_dates.len() <= MAX_UNDESIRED_DATES,
+            "undesired-date volume should stay in the designed band"
+        );
+        assert!(
+            employee
+                .desired_dates
+                .iter()
+                .all(|date| !employee.undesired_dates.contains(date)),
+            "desired and undesired dates must stay disjoint"
+        );
+    }
+}
+/// Cached facts shared by the different preference-shaping passes.
+struct PreferenceAnalysis {
+    candidate_lists: Vec<Vec<usize>>,
+    candidate_counts: Vec<usize>,
+    witness_shifts_by_employee: Vec<Vec<usize>>,
+    coverable_dates_by_employee: Vec<BTreeSet<NaiveDate>>,
+    date_pressure: BTreeMap<NaiveDate, usize>,
+}
+impl PreferenceAnalysis {
+    /// Precomputes the helper views every preference phase needs.
+    fn build(employees: &[Employee], shifts: &[Shift], witness: &WitnessRoster) -> Self {
+        let candidate_lists = eligible_employees_by_shift(employees, shifts);
+        let candidate_counts: Vec<usize> = candidate_lists.iter().map(Vec::len).collect();
+        let witness_shifts_by_employee =
+            witness_shift_indices_by_employee(&witness.assignments, employees.len());
+        let coverable_dates_by_employee =
+            coverable_dates_by_employee(&candidate_lists, shifts, employees.len());
+        let date_pressure = date_pressure_by_day(shifts, &candidate_counts);
+        Self {
+            candidate_lists,
+            candidate_counts,
+            witness_shifts_by_employee,
+            coverable_dates_by_employee,
+            date_pressure,
+        }
+    }
+}
+/// Lists the legal employees for each public shift before scheduling interactions.
+pub(super) fn eligible_employees_by_shift(
+    employees: &[Employee],
+    shifts: &[Shift],
+) -> Vec<Vec<usize>> {
+    shifts
+        .iter()
+        .map(|shift| {
+            employees
+                .iter()
+                .enumerate()
+                .filter(|(_, employee)| employee_can_cover_shift_without_schedule(employee, shift))
+                .map(|(employee_index, _)| employee_index)
+                .collect()
+        })
+        .collect()
+}
+/// Reverses witness assignments into "which shifts belong to each employee".
+fn witness_shift_indices_by_employee(
+    assignments: &[usize],
+    employee_count: usize,
+) -> Vec<Vec<usize>> {
+    let mut shifts_by_employee = vec![Vec::new(); employee_count];
+    for (shift_index, &employee_index) in assignments.iter().enumerate() {
+        shifts_by_employee[employee_index].push(shift_index);
+    }
+    shifts_by_employee
+}
+/// Collects every date an employee could legally cover in the public dataset.
+fn coverable_dates_by_employee(
+    candidate_lists: &[Vec<usize>],
+    shifts: &[Shift],
+    employee_count: usize,
+) -> Vec<BTreeSet<NaiveDate>> {
+    let mut dates_by_employee = vec![BTreeSet::new(); employee_count];
+    for (shift_index, candidates) in candidate_lists.iter().enumerate() {
+        for &candidate in candidates {
+            dates_by_employee[candidate].extend(shifts[shift_index].touched_dates.iter().copied());
+        }
+    }
+    dates_by_employee
+}
+/// Scores dates by how much soft-pressure they can safely carry.
+fn date_pressure_by_day(
+    shifts: &[Shift],
+    candidate_counts: &[usize],
+) -> BTreeMap<NaiveDate, usize> {
+    let mut pressure = BTreeMap::new();
+    for (shift, &candidate_count) in shifts.iter().zip(candidate_counts.iter()) {
+        // The goal here is not to make the hard problem tighter. It is to create
+        // lots of feasible reassignment opportunities. We therefore score dates
+        // by how many "comfortable" alternatives they carry, not by how scarce
+        // they are. Scarce dates belong to feasibility; abundant dates are where
+        // soft pressure can live without poisoning construction.
+        let shift_pressure = candidate_count.clamp(2, 8) - 1;
+        for &date in &shift.touched_dates {
+            *pressure.entry(date).or_default() += shift_pressure.max(1);
+        }
+    }
+    pressure
+}

src/data/data_seed/preferences/exchange.rs ADDED Viewed

	@@ -0,0 +1,102 @@

+use chrono::Timelike;
+use std::cmp::Reverse;
+use crate::domain::{Employee, Shift};
+use super::support::{
+    can_mark_preference_date, date_pressure_for_shift, mark_preference_date, preferred_shift_date,
+    shift_prefers_doctor_family, shift_same_shape, PreferenceKind,
+};
+use super::PreferenceAnalysis;
+use crate::data::data_seed::employees::EmployeeBlueprint;
+use crate::data::data_seed::skills::is_specialty_skill;
+use crate::data::data_seed::vocabulary::DOCTOR;
+use crate::data::data_seed::witness::{shift_priority_rank, WitnessRoster};
+/// Adds a small number of witness-relative preference swaps.
+///
+/// This is the sharpest source of local-search signal in the dataset: one
+/// employee is marked as disliking a date while another feasible employee is
+/// marked as preferring it.
+pub(super) fn assign_exchange_preferences(
+    employees: &mut [Employee],
+    blueprints: &[EmployeeBlueprint],
+    shifts: &[Shift],
+    witness: &WitnessRoster,
+    analysis: &PreferenceAnalysis,
+    max_exchange_marks_per_employee: usize,
+) {
+    let mut exchange_marks_by_employee = vec![0usize; employees.len()];
+    let mut shift_order: Vec<usize> = (0..shifts.len()).collect();
+    shift_order.sort_by_key(|&shift_index| {
+        let shift = &shifts[shift_index];
+        (
+            Reverse(analysis.candidate_counts[shift_index]),
+            Reverse(date_pressure_for_shift(shift, &analysis.date_pressure)),
+            shift_priority_rank(shift),
+            shift.start,
+            shift_index,
+        )
+    });
+    for shift_index in shift_order {
+        let shift = &shifts[shift_index];
+        if analysis.candidate_counts[shift_index] < 6
+            || is_specialty_skill(&shift.required_skill)
+            || shift.start.time().hour() == 22
+        {
+            continue;
+        }
+        let holder = witness.assignments[shift_index];
+        let date = preferred_shift_date(shift, &analysis.date_pressure);
+        let Some(alternative) = analysis.candidate_lists[shift_index]
+            .iter()
+            .copied()
+            .filter(|&candidate| candidate != holder)
+            .filter(|&candidate| {
+                exchange_marks_by_employee[candidate] < max_exchange_marks_per_employee
+            })
+            .filter(|&candidate| {
+                can_mark_preference_date(&employees[candidate], date, PreferenceKind::Desired)
+            })
+            .min_by_key(|&candidate| {
+                exchange_alternative_key(candidate, shift, shifts, blueprints, witness, analysis)
+            })
+        else {
+            continue;
+        };
+        if mark_preference_date(&mut employees[alternative], date, PreferenceKind::Desired) {
+            exchange_marks_by_employee[alternative] += 1;
+        }
+    }
+}
+/// Lower keys mean "better alternative employee for this exchange mark".
+fn exchange_alternative_key(
+    candidate: usize,
+    shift: &Shift,
+    shifts: &[Shift],
+    blueprints: &[EmployeeBlueprint],
+    witness: &WitnessRoster,
+    analysis: &PreferenceAnalysis,
+) -> (usize, usize, usize, usize, usize, usize) {
+    let date = preferred_shift_date(shift, &analysis.date_pressure);
+    let same_date_in_witness =
+        usize::from(witness.employee_touched_dates[candidate].contains(&date));
+    let same_shape_load = analysis.witness_shifts_by_employee[candidate]
+        .iter()
+        .filter(|&&other_shift_index| shift_same_shape(shift, &shifts[other_shift_index]))
+        .count();
+    (
+        same_date_in_witness,
+        usize::from(
+            blueprints[candidate].skills.contains(DOCTOR) != shift_prefers_doctor_family(shift),
+        ),
+        same_shape_load,
+        witness.employee_touched_dates[candidate].len(),
+        usize::MAX - *analysis.date_pressure.get(&date).unwrap_or(&0),
+        candidate,
+    )
+}

src/data/data_seed/preferences/floor.rs ADDED Viewed

	@@ -0,0 +1,76 @@

+use chrono::NaiveDate;
+use std::cmp::Reverse;
+use std::collections::{BTreeMap, BTreeSet};
+use crate::domain::Employee;
+use super::support::{can_mark_preference_date, mark_preference_date, PreferenceKind};
+/// Ensures every employee ends up with the minimum amount of preference signal.
+pub(super) fn ensure_preference_floor(
+    employees: &mut [Employee],
+    witness_dates_by_employee: &[BTreeSet<NaiveDate>],
+    coverable_dates_by_employee: &[BTreeSet<NaiveDate>],
+    date_pressure: &BTreeMap<NaiveDate, usize>,
+) {
+    for employee_index in 0..employees.len() {
+        while employees[employee_index].undesired_dates.len() < 4 {
+            let candidate = witness_dates_by_employee[employee_index]
+                .iter()
+                .chain(coverable_dates_by_employee[employee_index].iter())
+                .copied()
+                .filter(|&date| {
+                    can_mark_preference_date(
+                        &employees[employee_index],
+                        date,
+                        PreferenceKind::Undesired,
+                    )
+                })
+                .max_by_key(|date| (*date_pressure.get(date).unwrap_or(&0), Reverse(*date)));
+            let Some(date) = candidate else {
+                break;
+            };
+            let _ = mark_preference_date(
+                &mut employees[employee_index],
+                date,
+                PreferenceKind::Undesired,
+            );
+        }
+        while employees[employee_index].desired_dates.len() < 4 {
+            let candidate = coverable_dates_by_employee[employee_index]
+                .iter()
+                .copied()
+                .filter(|&date| !witness_dates_by_employee[employee_index].contains(&date))
+                .filter(|&date| {
+                    can_mark_preference_date(
+                        &employees[employee_index],
+                        date,
+                        PreferenceKind::Desired,
+                    )
+                })
+                .max_by_key(|date| (*date_pressure.get(date).unwrap_or(&0), Reverse(*date)))
+                .or_else(|| {
+                    coverable_dates_by_employee[employee_index]
+                        .iter()
+                        .copied()
+                        .filter(|&date| {
+                            can_mark_preference_date(
+                                &employees[employee_index],
+                                date,
+                                PreferenceKind::Desired,
+                            )
+                        })
+                        .max_by_key(|date| (*date_pressure.get(date).unwrap_or(&0), Reverse(*date)))
+                });
+            let Some(date) = candidate else {
+                break;
+            };
+            let _ = mark_preference_date(
+                &mut employees[employee_index],
+                date,
+                PreferenceKind::Desired,
+            );
+        }
+    }
+}

src/data/data_seed/preferences/support.rs ADDED Viewed

	@@ -0,0 +1,103 @@

+use chrono::{NaiveDate, Timelike};
+use std::cmp::Reverse;
+use std::collections::BTreeMap;
+use crate::domain::{Employee, Shift};
+use crate::data::data_seed::skills::is_doctor_family_skill;
+use crate::data::data_seed::vocabulary::{MAX_DESIRED_DATES, MAX_UNDESIRED_DATES};
+#[derive(Clone, Copy)]
+pub(super) enum PreferenceKind {
+    Desired,
+    Undesired,
+}
+/// Returns whether a preference mark can be added without breaking the rules.
+pub(super) fn can_mark_preference_date(
+    employee: &Employee,
+    date: NaiveDate,
+    kind: PreferenceKind,
+) -> bool {
+    if employee.unavailable_dates.contains(&date) {
+        return false;
+    }
+    match kind {
+        PreferenceKind::Desired => {
+            employee.desired_dates.len() < MAX_DESIRED_DATES
+                && !employee.desired_dates.contains(&date)
+                && !employee.undesired_dates.contains(&date)
+        }
+        PreferenceKind::Undesired => {
+            employee.undesired_dates.len() < MAX_UNDESIRED_DATES
+                && !employee.undesired_dates.contains(&date)
+                && !employee.desired_dates.contains(&date)
+        }
+    }
+}
+/// Mutates the employee by adding a desired or undesired date when legal.
+pub(super) fn mark_preference_date(
+    employee: &mut Employee,
+    date: NaiveDate,
+    kind: PreferenceKind,
+) -> bool {
+    if !can_mark_preference_date(employee, date, kind) {
+        return false;
+    }
+    match kind {
+        PreferenceKind::Desired => employee.desired_dates.insert(date),
+        PreferenceKind::Undesired => employee.undesired_dates.insert(date),
+    }
+}
+/// Chooses the most "pressure-carrying" date touched by a shift.
+pub(super) fn preferred_shift_date(
+    shift: &Shift,
+    date_pressure: &BTreeMap<NaiveDate, usize>,
+) -> NaiveDate {
+    shift
+        .touched_dates
+        .iter()
+        .copied()
+        .max_by_key(|date| (*date_pressure.get(date).unwrap_or(&0), Reverse(*date)))
+        .expect("shift should touch at least one date")
+}
+/// Returns the precomputed pressure score for the date chosen above.
+pub(super) fn date_pressure_for_shift(
+    shift: &Shift,
+    date_pressure: &BTreeMap<NaiveDate, usize>,
+) -> usize {
+    let date = preferred_shift_date(shift, date_pressure);
+    *date_pressure
+        .get(&date)
+        .expect("preferred shift date should have a pressure score")
+}
+/// Small domain helper used while choosing exchange-preference targets.
+pub(super) fn shift_prefers_doctor_family(shift: &Shift) -> bool {
+    is_doctor_family_skill(&shift.required_skill)
+}
+/// Treats two shifts as the same broad "shape" for preference balancing.
+pub(super) fn shift_same_shape(left: &Shift, right: &Shift) -> bool {
+    left.required_skill == right.required_skill
+        && (left.start.time().hour() == 22) == (right.start.time().hour() == 22)
+}
+#[cfg(test)]
+/// Test helper for checking whether a move changes the preference score.
+pub(super) fn shift_soft_preference_score(employee: &Employee, shift: &Shift) -> i64 {
+    let desired_matches = employee
+        .desired_dates
+        .iter()
+        .filter(|date| shift.touched_dates.contains(date))
+        .count() as i64;
+    let undesired_matches = employee
+        .undesired_dates
+        .iter()
+        .filter(|date| shift.touched_dates.contains(date))
+        .count() as i64;
+    desired_matches - undesired_matches
+}

src/data/data_seed/preferences/top_up.rs ADDED Viewed

	@@ -0,0 +1,115 @@

+use chrono::{NaiveDate, Weekday};
+use crate::domain::Employee;
+use super::support::{can_mark_preference_date, mark_preference_date, PreferenceKind};
+use crate::data::data_seed::employees::EmployeeBlueprint;
+use crate::data::data_seed::time_utils::{choose_weekday_with_four_available_dates, weekday_dates};
+use crate::data::data_seed::vocabulary::{TARGET_DESIRED_DATES, TARGET_UNDESIRED_DATES};
+/// Fills the remaining preference slots with stable weekday-themed dates.
+pub(super) fn top_up_preferences(
+    employees: &mut [Employee],
+    start_date: NaiveDate,
+    blueprints: &[EmployeeBlueprint],
+) {
+    let dates_by_weekday = weekday_dates(start_date);
+    for (employee_index, employee) in employees.iter_mut().enumerate() {
+        let blueprint = &blueprints[employee_index];
+        let primary_off = blueprint.primary_off_weekday;
+        let preferred_weekday = choose_weekday_with_four_available_dates(
+            &employee.unavailable_dates,
+            primary_off,
+            (0..7).map(|offset| (primary_off + 2 + offset) % 7),
+        );
+        let undesired_weekday = choose_weekday_with_four_available_dates(
+            &employee.unavailable_dates,
+            primary_off,
+            (0..7).map(|offset| {
+                let candidate = (primary_off + 4 + offset) % 7;
+                if candidate == preferred_weekday {
+                    (candidate + 1) % 7
+                } else {
+                    candidate
+                }
+            }),
+        );
+        for &date in &dates_by_weekday[preferred_weekday] {
+            if employee.desired_dates.len() >= TARGET_DESIRED_DATES {
+                break;
+            }
+            let _ = mark_preference_date(employee, date, PreferenceKind::Desired);
+        }
+        for &date in &dates_by_weekday[undesired_weekday] {
+            if employee.undesired_dates.len() >= TARGET_UNDESIRED_DATES {
+                break;
+            }
+            let _ = mark_preference_date(employee, date, PreferenceKind::Undesired);
+        }
+    }
+}
+/// Adds a tiny weekend bias to break some weekday-only symmetry.
+pub(super) fn add_weekend_preference_bias(
+    employees: &mut [Employee],
+    start_date: NaiveDate,
+    blueprints: &[EmployeeBlueprint],
+) {
+    let dates_by_weekday = weekday_dates(start_date);
+    let saturdays = &dates_by_weekday[Weekday::Sat.num_days_from_monday() as usize];
+    let sundays = &dates_by_weekday[Weekday::Sun.num_days_from_monday() as usize];
+    for employee_index in 0..employees.len() {
+        let weekend_mode = (blueprints[employee_index].specialty_count()
+            + blueprints[employee_index].primary_off_weekday)
+            % 3;
+        match weekend_mode {
+            0 if employees[employee_index].desired_dates.len() < TARGET_DESIRED_DATES => {
+                if let Some(date) = saturdays
+                    .iter()
+                    .chain(sundays.iter())
+                    .copied()
+                    .find(|&date| {
+                        can_mark_preference_date(
+                            &employees[employee_index],
+                            date,
+                            PreferenceKind::Desired,
+                        )
+                    })
+                {
+                    let _ = mark_preference_date(
+                        &mut employees[employee_index],
+                        date,
+                        PreferenceKind::Desired,
+                    );
+                }
+            }
+            1 if employees[employee_index].undesired_dates.len() < TARGET_UNDESIRED_DATES => {
+                if let Some(date) = saturdays
+                    .iter()
+                    .chain(sundays.iter())
+                    .copied()
+                    .find(|&date| {
+                        can_mark_preference_date(
+                            &employees[employee_index],
+                            date,
+                            PreferenceKind::Undesired,
+                        )
+                    })
+                {
+                    let _ = mark_preference_date(
+                        &mut employees[employee_index],
+                        date,
+                        PreferenceKind::Undesired,
+                    );
+                }
+            }
+            _ => {}
+        }
+    }
+}

src/data/data_seed/shifts.rs ADDED Viewed

	@@ -0,0 +1,54 @@

+use chrono::{Datelike, Duration, NaiveDate, NaiveDateTime};
+use crate::domain::Shift;
+use super::demand::DEMAND_RULES;
+use super::time_utils::{dates_touched_by_span, find_next_monday, time};
+use super::vocabulary::DAYS_IN_SCHEDULE;
+/// Expands the demand template into the actual public shift entities.
+pub(super) fn build_public_shifts(start_date: NaiveDate) -> Vec<Shift> {
+    let mut shifts = Vec::with_capacity(expected_shift_count());
+    let mut shift_id = 0usize;
+    for day in 0..DAYS_IN_SCHEDULE {
+        let date = start_date + Duration::days(day);
+        for rule in DEMAND_RULES {
+            for _ in 0..rule.count_for_date(date.weekday()) {
+                let start = NaiveDateTime::new(date, time(rule.start_hour, 0));
+                let end = start + Duration::hours(8);
+                shifts.push(Shift::new(
+                    shift_id.to_string(),
+                    start,
+                    end,
+                    rule.location,
+                    rule.required_skill,
+                ));
+                shift_id += 1;
+            }
+        }
+    }
+    shifts
+}
+/// Fills derived shift fields after the raw templates are materialized.
+pub(super) fn prepare_shifts(shifts: &mut [Shift]) {
+    for (index, shift) in shifts.iter_mut().enumerate() {
+        shift.index = index;
+        shift.touched_dates = dates_touched_by_span(shift.start, shift.end);
+    }
+}
+/// Recomputes the expected number of public shifts from the demand template.
+pub(super) fn expected_shift_count() -> usize {
+    let start_date = find_next_monday(NaiveDate::from_ymd_opt(2024, 1, 1).unwrap());
+    let mut count = 0usize;
+    for day in 0..DAYS_IN_SCHEDULE {
+        let date = start_date + Duration::days(day);
+        for rule in DEMAND_RULES {
+            count += rule.count_for_date(date.weekday());
+        }
+    }
+    count
+}

src/data/data_seed/skills.rs ADDED Viewed

	@@ -0,0 +1,42 @@

+use super::vocabulary::*;
+/// Returns whether the skill is one of the scarcer specialty signals.
+pub(super) fn is_specialty_skill(skill: &str) -> bool {
+    matches!(
+        skill,
+        CARDIOLOGY | ANAESTHETICS | RADIOLOGY_DAY | RADIOLOGY_CALL
+    )
+}
+/// Groups service-line skills under the broad "doctor-family" umbrella.
+pub(super) fn is_doctor_family_skill(skill: &str) -> bool {
+    matches!(
+        skill,
+        DOCTOR
+            | AMBULATORY_DOCTOR
+            | NEUROLOGY_DOCTOR
+            | CRITICAL_DOCTOR
+            | PEDIATRIC_DOCTOR
+            | SURGERY_DOCTOR
+            | OUTPATIENT_DOCTOR
+            | RADIOLOGY_CALL
+            | CARDIOLOGY
+            | ANAESTHETICS
+    )
+}
+/// Groups service-line skills under the broad "nurse-family" umbrella.
+pub(super) fn is_nurse_family_skill(skill: &str) -> bool {
+    matches!(
+        skill,
+        NURSE
+            | AMBULATORY_NURSE
+            | NEUROLOGY_NURSE
+            | CRITICAL_NURSE
+            | PEDIATRIC_NURSE
+            | SURGERY_NURSE
+            | OUTPATIENT_NURSE
+            | RADIOLOGY_NURSE
+            | RADIOLOGY_DAY
+    )
+}

src/data/data_seed/solve_tests.rs ADDED Viewed

	@@ -0,0 +1,75 @@

+use chrono::Timelike;
+use solverforge::{ConstraintSet, SolverEvent, SolverManager};
+use std::collections::BTreeMap;
+use super::{generate, DemoData};
+use crate::domain::Plan;
+// Slow end-to-end acceptance test for the published benchmark instance.
+fn schedule() -> Plan {
+    generate(DemoData::Large)
+}
+#[test]
+#[ignore = "slow acceptance test for the canonical quickstart dataset"]
+fn large_demo_solves_to_feasible_terminal_state() {
+    static MANAGER: SolverManager<Plan> = SolverManager::new();
+    let schedule = schedule();
+    let (job_id, mut receiver) = MANAGER.solve(schedule).expect("job should start");
+    let mut completed_score = None;
+    while let Some(event) = receiver.blocking_recv() {
+        match event {
+            SolverEvent::Completed { solution, .. } => {
+                completed_score = solution.score;
+                if let Some(score) = solution.score {
+                    if score.hard_score() != solverforge::HardSoftDecimalScore::ZERO {
+                        let mut mismatches = BTreeMap::<(String, u32, String), usize>::new();
+                        for shift in &solution.shifts {
+                            let Some(employee_idx) = shift.employee_idx else {
+                                continue;
+                            };
+                            let employee = &solution.employees[employee_idx];
+                            if !employee.skills.contains(&shift.required_skill) {
+                                *mismatches
+                                    .entry((
+                                        shift.location.clone(),
+                                        shift.start.time().hour(),
+                                        shift.required_skill.clone(),
+                                    ))
+                                    .or_default() += 1;
+                            }
+                        }
+                        eprintln!("large demo skill mismatches: {mismatches:?}");
+                        let constraints = crate::constraints::create_constraints();
+                        let analyses = constraints.evaluate_detailed(&solution);
+                        let hard_breakdown: Vec<_> = analyses
+                            .into_iter()
+                            .filter(|analysis| {
+                                analysis.score.hard_score()
+                                    != solverforge::HardSoftDecimalScore::ZERO
+                            })
+                            .map(|analysis| {
+                                format!("{}={}", analysis.constraint_ref.name, analysis.score)
+                            })
+                            .collect();
+                        eprintln!("large demo hard breakdown: {}", hard_breakdown.join(", "));
+                    }
+                }
+                break;
+            }
+            SolverEvent::Failed { error, .. } => {
+                panic!("large demo solve failed unexpectedly: {error}");
+            }
+            _ => {}
+        }
+    }
+    let score = completed_score.expect("expected a completed score");
+    assert_eq!(score.hard_score(), solverforge::HardSoftDecimalScore::ZERO);
+    MANAGER.delete(job_id).expect("delete completed job");
+}

src/data/data_seed/tests.rs ADDED Viewed

	@@ -0,0 +1,284 @@

+use super::availability::add_extra_unavailability;
+use super::cohorts::assign_primary_off_days;
+use super::coverage::public_candidate_counts;
+use super::demand::DEMAND_RULES;
+use super::employees::{build_employee_blueprints, instantiate_employees};
+use super::preferences::{
+    add_preferences, eligible_employees_by_shift, shift_soft_preference_score,
+};
+use super::shifts::{build_public_shifts, prepare_shifts};
+use super::time_utils::find_next_monday;
+use super::vocabulary::*;
+use super::witness::build_hidden_witness;
+use super::*;
+use chrono::{Datelike, Duration, NaiveDate, Timelike};
+use rand::rngs::StdRng;
+use rand::SeedableRng;
+use solverforge::ConstraintSet;
+use std::collections::{BTreeMap, BTreeSet};
+use crate::domain::Plan;
+// These tests lock down the generator contract: workforce shape, shift counts,
+// feasibility margins, and the intended soft-score signal surface.
+fn schedule() -> Plan {
+    generate(DemoData::Large)
+}
+#[test]
+fn test_generate_large() {
+    let schedule = schedule();
+    assert_eq!(schedule.employees.len(), 50);
+    assert_eq!(schedule.shifts.len(), 688);
+}
+#[test]
+fn test_exact_workforce_composition() {
+    let schedule = schedule();
+    let employees = &schedule.employees;
+    let doctors = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(DOCTOR))
+        .count();
+    let nurses = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(NURSE))
+        .count();
+    let cardiology = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(CARDIOLOGY))
+        .count();
+    let anaesthetics = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(ANAESTHETICS))
+        .count();
+    let radiology_day = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(RADIOLOGY_DAY))
+        .count();
+    let radiology_nurse = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(RADIOLOGY_NURSE))
+        .count();
+    let radiology_call = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(RADIOLOGY_CALL))
+        .count();
+    let ambulatory_doctors = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(AMBULATORY_DOCTOR))
+        .count();
+    let ambulatory_nurses = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(AMBULATORY_NURSE))
+        .count();
+    let critical_doctors = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(CRITICAL_DOCTOR))
+        .count();
+    let critical_nurses = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(CRITICAL_NURSE))
+        .count();
+    let outpatient_doctors = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(OUTPATIENT_DOCTOR))
+        .count();
+    let outpatient_nurses = employees
+        .iter()
+        .filter(|employee| employee.skills.contains(OUTPATIENT_NURSE))
+        .count();
+    assert_eq!(doctors, 22);
+    assert_eq!(nurses, 28);
+    assert_eq!(cardiology, 4);
+    assert_eq!(anaesthetics, 6);
+    assert_eq!(radiology_day, 6);
+    assert_eq!(radiology_nurse, 6);
+    assert_eq!(radiology_call, 4);
+    assert_eq!(ambulatory_doctors, 4);
+    assert_eq!(ambulatory_nurses, 6);
+    assert_eq!(critical_doctors, 6);
+    assert_eq!(critical_nurses, 8);
+    assert_eq!(outpatient_doctors, 7);
+    assert_eq!(outpatient_nurses, 9);
+}
+#[test]
+fn test_exact_shift_template_counts() {
+    let schedule = schedule();
+    let mut actual = BTreeMap::<(String, u32, String), usize>::new();
+    for shift in &schedule.shifts {
+        *actual
+            .entry((
+                shift.location.clone(),
+                shift.start.time().hour(),
+                shift.required_skill.clone(),
+            ))
+            .or_default() += 1;
+    }
+    let mut expected = BTreeMap::<(String, u32, String), usize>::new();
+    let start_date = find_next_monday(NaiveDate::from_ymd_opt(2024, 1, 1).unwrap());
+    for day in 0..DAYS_IN_SCHEDULE {
+        let date = start_date + Duration::days(day);
+        for rule in DEMAND_RULES {
+            *expected
+                .entry((
+                    rule.location.to_string(),
+                    rule.start_hour,
+                    rule.required_skill.to_string(),
+                ))
+                .or_default() += rule.count_for_date(date.weekday());
+        }
+    }
+    assert_eq!(actual, expected);
+}
+#[test]
+fn test_preferences_are_disjoint_from_unavailability() {
+    let schedule = schedule();
+    for employee in &schedule.employees {
+        assert!(employee
+            .desired_dates
+            .iter()
+            .all(|date| !employee.unavailable_dates.contains(date)));
+        assert!(employee
+            .undesired_dates
+            .iter()
+            .all(|date| !employee.unavailable_dates.contains(date)));
+        assert!((4..=MAX_DESIRED_DATES).contains(&employee.desired_dates.len()));
+        assert!((4..=MAX_UNDESIRED_DATES).contains(&employee.undesired_dates.len()));
+        assert!(employee
+            .desired_dates
+            .iter()
+            .all(|date| !employee.undesired_dates.contains(date)));
+    }
+}
+#[test]
+fn test_preference_surface_has_one_move_signal() {
+    let schedule = schedule();
+    let witness = build_hidden_witness(&schedule.employees, &schedule.shifts);
+    let candidate_lists = eligible_employees_by_shift(&schedule.employees, &schedule.shifts);
+    let signal_shifts = schedule
+        .shifts
+        .iter()
+        .enumerate()
+        .filter(|(shift_index, shift)| {
+            let holder = witness.assignments[*shift_index];
+            let holder_score = shift_soft_preference_score(&schedule.employees[holder], shift);
+            candidate_lists[*shift_index]
+                .iter()
+                .copied()
+                .filter(|&candidate| candidate != holder)
+                .any(|candidate| {
+                    let candidate_score =
+                        shift_soft_preference_score(&schedule.employees[candidate], shift);
+                    candidate_score - holder_score >= 2
+                })
+        })
+        .count();
+    assert!(
+        signal_shifts > 0,
+        "there should still be some one-move soft improvements"
+    );
+}
+#[test]
+fn test_public_candidate_redundancy() {
+    let schedule = schedule();
+    let counts = public_candidate_counts(&schedule.employees, &schedule.shifts);
+    assert!(counts.iter().all(|&count| count >= 2));
+    assert!(counts.iter().filter(|&&count| count >= 3).count() * 4 >= counts.len());
+}
+#[test]
+fn test_candidate_width_is_not_generic_role_wide() {
+    let schedule = schedule();
+    let mut counts = public_candidate_counts(&schedule.employees, &schedule.shifts);
+    counts.sort_unstable();
+    let median = counts[counts.len() / 2];
+    let p90 = counts[counts.len() * 9 / 10];
+    assert!(median <= 7, "median candidate count should stay narrow");
+    assert!(
+        p90 <= 9,
+        "90th percentile candidate count should stay bounded"
+    );
+}
+#[test]
+fn test_hidden_witness_is_hard_feasible() {
+    let mut rng = StdRng::seed_from_u64(0);
+    let start_date = find_next_monday(NaiveDate::from_ymd_opt(2024, 1, 1).unwrap());
+    let mut blueprints = build_employee_blueprints(&mut rng);
+    assign_primary_off_days(&mut blueprints);
+    let mut employees = instantiate_employees(&blueprints, start_date);
+    let mut shifts = build_public_shifts(start_date);
+    prepare_shifts(&mut shifts);
+    let witness = build_hidden_witness(&employees, &shifts);
+    add_extra_unavailability(&mut employees, &shifts, &witness.employee_touched_dates);
+    add_preferences(&mut employees, start_date, &blueprints, &shifts, &witness);
+    for (shift, employee_idx) in shifts.iter_mut().zip(witness.assignments.iter()) {
+        shift.employee_idx = Some(*employee_idx);
+    }
+    let witness_schedule = Plan::new(employees, shifts);
+    let score = crate::constraints::create_constraints().evaluate_all(&witness_schedule);
+    assert_eq!(score.hard_score(), solverforge::HardSoftDecimalScore::ZERO);
+}
+#[test]
+fn test_employees_have_skills() {
+    let schedule = schedule();
+    for employee in &schedule.employees {
+        assert!(
+            !employee.skills.is_empty(),
+            "Employee {} has no skills",
+            employee.name
+        );
+    }
+}
+#[test]
+fn test_demo_data_from_str() {
+    assert_eq!("LARGE".parse::<DemoData>(), Ok(DemoData::Large));
+    assert_eq!("large".parse::<DemoData>(), Ok(DemoData::Large));
+    assert!("invalid".parse::<DemoData>().is_err());
+}
+#[test]
+fn test_medical_domain() {
+    let schedule = schedule();
+    let all_skills: BTreeSet<_> = schedule
+        .employees
+        .iter()
+        .flat_map(|employee| employee.skills.iter())
+        .map(|skill| skill.as_str())
+        .collect();
+    assert!(all_skills.contains(DOCTOR) || all_skills.contains(NURSE));
+    let locations: BTreeSet<_> = schedule
+        .shifts
+        .iter()
+        .map(|shift| shift.location.as_str())
+        .collect();
+    assert!(locations.contains("Ambulatory care") || locations.contains("Critical care"));
+}
+#[test]
+fn test_empty_schedule_has_score() {
+    let schedule = crate::domain::Plan::new(vec![], vec![]);
+    let score = crate::constraints::create_constraints().evaluate_all(&schedule);
+    assert_eq!(score.to_string(), "0hard/0soft");
+}

src/data/data_seed/time_utils.rs ADDED Viewed

	@@ -0,0 +1,119 @@

+use chrono::{Datelike, Duration, NaiveDate, NaiveDateTime, NaiveTime, Weekday};
+use rand::prelude::*;
+use rand::rngs::StdRng;
+use std::collections::BTreeSet;
+use crate::domain::Shift;
+use super::vocabulary::{DAYS_IN_SCHEDULE, FIRST_NAMES, LAST_NAMES};
+/// Returns the sorted set of dates touched by the published shifts.
+pub(super) fn horizon_dates(shifts: &[Shift]) -> Vec<NaiveDate> {
+    let mut dates = BTreeSet::new();
+    for shift in shifts {
+        for &date in &shift.touched_dates {
+            dates.insert(date);
+        }
+    }
+    dates.into_iter().collect()
+}
+/// Buckets every schedule date by weekday for preference shaping.
+pub(super) fn weekday_dates(start_date: NaiveDate) -> [Vec<NaiveDate>; 7] {
+    let mut dates = std::array::from_fn(|_| Vec::new());
+    for day in 0..DAYS_IN_SCHEDULE {
+        let date = start_date + Duration::days(day);
+        dates[date.weekday().num_days_from_monday() as usize].push(date);
+    }
+    dates
+}
+/// Finds a weekday that still exposes four available dates after unavailability.
+pub(super) fn choose_weekday_with_four_available_dates(
+    unavailable_dates: &BTreeSet<NaiveDate>,
+    primary_off: usize,
+    candidates: impl IntoIterator<Item = usize>,
+) -> usize {
+    candidates
+        .into_iter()
+        .filter(|&weekday| weekday != primary_off)
+        .find(|&weekday| {
+            weekday_dates(find_next_monday(
+                NaiveDate::from_ymd_opt(2024, 1, 1).unwrap(),
+            ))[weekday]
+                .iter()
+                .filter(|date| !unavailable_dates.contains(date))
+                .count()
+                == 4
+        })
+        .expect("weekday with four available dates should exist")
+}
+/// Expands a time span into the calendar dates it touches.
+pub(super) fn dates_touched_by_span(start: NaiveDateTime, end: NaiveDateTime) -> Vec<NaiveDate> {
+    let mut touched_dates = Vec::new();
+    let mut date = start.date();
+    while date <= end.date() {
+        if overlap_minutes_for_day(start, end, date) > 0 {
+            touched_dates.push(date);
+        }
+        let Some(next_date) = date.succ_opt() else {
+            break;
+        };
+        date = next_date;
+    }
+    touched_dates
+}
+/// Measures how many minutes of the span overlap one specific date.
+fn overlap_minutes_for_day(start: NaiveDateTime, end: NaiveDateTime, date: NaiveDate) -> i64 {
+    let day_start = date.and_hms_opt(0, 0, 0).unwrap();
+    let day_end = date
+        .succ_opt()
+        .unwrap_or(date)
+        .and_hms_opt(0, 0, 0)
+        .unwrap();
+    let overlap_start = start.max(day_start);
+    let overlap_end = end.min(day_end);
+    if overlap_start < overlap_end {
+        (overlap_end - overlap_start).num_minutes()
+    } else {
+        0
+    }
+}
+/// Creates a deterministic shuffled name list for the workforce generator.
+pub(super) fn generate_name_permutations(rng: &mut StdRng) -> Vec<String> {
+    let mut names = Vec::with_capacity(FIRST_NAMES.len() * LAST_NAMES.len());
+    for first in FIRST_NAMES {
+        for last in LAST_NAMES {
+            names.push(format!("{first} {last}"));
+        }
+    }
+    names.shuffle(rng);
+    names
+}
+/// Small helper so shift templates can read as `time(14, 0)`.
+pub(super) fn time(hour: u32, minute: u32) -> NaiveTime {
+    NaiveTime::from_hms_opt(hour, minute, 0).unwrap()
+}
+/// Anchors the benchmark to a Monday so weekday-based rules stay stable.
+pub(super) fn find_next_monday(date: NaiveDate) -> NaiveDate {
+    let days_until_monday = match date.weekday() {
+        Weekday::Mon => 0,
+        Weekday::Tue => 6,
+        Weekday::Wed => 5,
+        Weekday::Thu => 4,
+        Weekday::Fri => 3,
+        Weekday::Sat => 2,
+        Weekday::Sun => 1,
+    };
+    date + Duration::days(days_until_monday)
+}

src/data/data_seed/validation.rs ADDED Viewed

	@@ -0,0 +1,32 @@

+use chrono::Timelike;
+use crate::domain::{Employee, Shift};
+use super::coverage::{candidate_redundancy_is_valid, public_candidate_counts};
+/// Verifies that the exact public dataset we will ship still matches generator goals.
+pub(super) fn validate_public_dataset(employees: &[Employee], shifts: &[Shift]) {
+    let counts = public_candidate_counts(employees, shifts);
+    let min_count = counts.iter().copied().min().unwrap_or(0);
+    let three_plus = counts.iter().filter(|&&count| count >= 3).count();
+    let weakest: Vec<String> = shifts
+        .iter()
+        .zip(counts.iter())
+        .filter(|(_, &count)| count == min_count)
+        .take(5)
+        .map(|(shift, &count)| {
+            format!(
+                "{} {} {} -> {}",
+                shift.location,
+                shift.start.time().hour(),
+                shift.required_skill,
+                count
+            )
+        })
+        .collect();
+    assert!(
+        candidate_redundancy_is_valid(employees, shifts),
+        "public dataset should maintain candidate redundancy; min_count={min_count}, three_plus={three_plus}/{} weakest={weakest:?}",
+        counts.len()
+    );
+}