Sourcing & Optimization for Hotels
Status: Capability Specification
Sources: S-12 — Sourcing and Optimization: First-Class Capabilities (stakeholder), D-09 — Optimization Capability (developer), Sourcing × Solvers / Optimizers — First-Class Integration, D-03 — Jijibora Playbook Designs (developer)
1. Principle — Machines Propose, Rules Dispose
The solver-gateway (:3070) and optimisation engines propose — they never award, dispatch, approve, or settle on their own. A named person or governed rule must say "yes" before anything moves. This keeps scoring errors or stale estimates from becoming real commitments.
Three operations, kept separate:
- Sourcing: discovers the best candidate who is allowed and able (e.g., which vendor can supply F&B this week).
- Solving: turns the shortlist into a feasible answer under constraints (least-cost basket split, route sequence, shift roster).
- Optimizing: replans as the day changes (room turnovers, housekeeping re-sequencing, maintenance re-dispatch).
Rules:
- Solving only happens after sourcing has produced a real match (no match, no solve).
- A feasible plan and an explicit "cannot be done" are different outcomes — the platform says so plainly instead of over-allocating.
- When the solving service is down, the platform refuses with a reason (
503 invent_refuse) — never a fake "optimal".
2. Solver Gateway Contract
Endpoint: POST /v1/decisions (decision-request-v1 → decision-result-v1); NATS svc.solver.v1.<capability>.<version>.solve
Verdict contract (decision-result-v1):
OPTIMAL— proven best (bound = objective)FEASIBLE— valid, not proven bestINFEASIBLE— proven impossible (certified)TIMEOUT— deadline hit, greedy-seeded incumbent with bindingdeadline(never upgraded to OPTIMAL)
Failure guards (fail closed, no invention):
- Solver-gateway down →
503 invent_refuse; never synthetic OPTIMAL/fill/routes - VROOM/OSRM down → no invented routes; refuse or declare fallback with provenance
- NATS/Kestra down →
502/503; no fill invented;LIVEunmet → refuse - Infeasible shortlist → emit
sourcing.fill_infeasible(certified); never over-allocate - Solver TIMEOUT →
200with statusTIMEOUT(or FEASIBLE incumbent withdeadlinebinding) - Checker rejects →
status: ERROR,error.code: checker_rejected; nothing leaves unchecked - Stale entitlement/presence/supply snapshot → refuse before solver invoke
3. Hotel Optimisation Use Cases
| Use Case | Capability | Input | Output (proposal) | Who disposes |
|---|---|---|---|---|
| F&B basket split across vendors | procurement.basket_split@1 (branch_and_bound 1.4.0) | line items, quantities, vendor price/stock/qty | least-cost vendor split | Executive chef / procurement |
| Housekeeping route sequencing | solver-gateway (route plan) | rooms due turnover, attendant shifts, supplies | attendant route order | Housekeeping supervisor |
| Maintenance crew dispatch | solver-gateway (route plan) | work orders, technician skills, parts, location | dispatch sequence | Engineering lead |
| Staff shift rostering | solver-gateway (scheduling) | demand forecast, staff availability, labour rules | draft roster | HR / front office manager |
| Linen / laundry replenishment | solver-gateway (basket split) | par levels, usage, vendor stock | replenishment plan | Housekeeping / linen room |
Each solver invocation emits a NATS outbox anchor (Data Fabric — Message Bus and Engine Interfaces (Developer Concept Doc)) for audit traceability.
4. Hotel-Specific Examples
F&B Procurement Basket Split (H-4)
The weekly F&B requisition (produce, dairy, dry goods, amenities) is split across approved vendors. The solver evaluates price, stock, quantity per line, and stop constraints. It returns a FEASIBLE or OPTIMAL split — the executive chef reviews and approves (PoCE step). If no feasible split exists (vendor stock insufficient), the platform returns INFEASIBLE certified — never invents a vendor or substitutes silently.
Housekeeping Route Optimization (H-2)
Each morning, rooms due turnover are matched to available attendants (skills, shift, supplies). The solver proposes an attendant route order minimising travel and balancing load. The housekeeping supervisor confirms or adjusts (PoCE sign-off). Rooms are not auto-assigned without human confirmation.
Maintenance Crew Dispatch (H-3)
Fault work orders are matched to technicians by skill, location, parts availability, and priority. The solver proposes a dispatch sequence; the engineering lead confirms. Parts are deducted from resource:budget_maintenance only on work-order close with expert sign-off.
5. Honest Limits
- No specific percentage saving, cost cut, or time saving is promised until the hotel's own baseline is measured.
- Optimisation can only replan on signals it actually receives (room status, attendant check-in, technician completion). When a crew is offline, the optimizer works from last-known facts and says so — never invents positions or completions.
- "Best candidate" assumes vendors keep stock/capacity/licence/availability fresh. The optimizer cannot summon a vendor the register does not have.
- Full natural-language per-decision explainability is not a shipped guarantee; do not quote parity with enterprise competitors until demonstrated on a live decision.