Feature Package PK-01 + PK-08 — Front Office, Reservations & Guest Experience
Status: Package Specification
Domain: Rooms / Front Office / Guest Experience
Maps to: Process 3 (Schedules & Resource Booking), Playbooks H-1 & H-10
External integration: PMS (system of engagement), ERPNext (folio/fiscal), Keycloak (identity)
1. What These Packages Do
PK-01 (Front Office & Reservations) manages the room lifecycle from reservation through folio to check-out. PK-08 (Guest Experience & Identity) manages guest identity, selective disclosure, and access permissions. Together they replace fragmented PMS folios, paper registration cards, and uncoordinated front-desk tools.
2. Features & Functionality — Front Office & Reservations (PK-01)
| Feature | What it does | Who uses it | What stands behind it |
|---|---|---|---|
| Reservation capture | Reservation (PMS webhook or manual) becomes a claim bound to a room resource via a time-bounded lease | Front desk agent, revenue manager | cns://claim/type/hotel/reservation; truth_edge guest→occupies→room |
| Folio management | Room charges, F&B, minibar, incidentals posted as folio-line claims; running total | Cashier, front desk agent | cns://claim/type/hotel/folio_line; budget pool binding |
| Threshold-gated adjustments | Folio adjustments above a tier require named approver(s) | Front office manager, finance controller | lookup.claims.threshold.v1; fn::poce::record_step |
| Check-out & settlement | Folio finalized; ERPNext invoice mirror written; occupancy lease released | Cashier, front desk agent | fn::poce::finalize_session; integration_entity (ERPNext) |
| Room status coordination | Room status (vacant-dirty, vacant-clean, occupied, out-of-order) visible to housekeeping and front desk | Front desk, housekeeping | lookup.hotel.room.status.v1; shared resource state |
| Revenue visibility | Live folio and ADR data from the state of record (no hardcoded metrics) | Revenue manager, GM | SurrealDB query on claim table |
3. Features & Functionality — Guest Experience & Identity (PK-08)
| Feature | What it does | Who uses it | What stands behind it |
|---|---|---|---|
| Guest identity record | One identity per guest linked to Keycloak DID; used across reservations, folio, and access | Front desk, guest relations | cns://truth/node/person; Keycloak realm |
| Selective disclosure (BBS+) | Guest proves age or nationality without surrendering the full ID document | Front desk, security | BBS+ credential (s121-s123); selective disclosure |
| Access permissions | Role-based access to rooms, areas, and systems per guest/staff profile | Security, IT | APF resolve_effective; X-Sovereign-DID-Proof header |
| Communication preference | Guest language and contact channel (SMS/WhatsApp/email) for reports and updates | Front desk, GM | Identity claim attributes; NATS/WebSocket delivery |
4. Workflow (Reservation → Check-out)
- Reservation arrives (PMS webhook) → reservation claim created; room lease bound
- Guest checks in → identity verified (BBS+ optional); receptionist signs; PoCE step
- Stay: folio lines posted as charges occur (room, F&B, minibar)
- Folio adjustment above tier → dual-custody approval (PoCE step)
- Check-out → settlement finalized → ERPNext invoice → room lease released → housekeeping task triggered (PK-02)
- PoCE receipt issued for the entire stay
5. Guard Rails
- No auto-charge without a folio-line claim
- No check-out without PoCE finalize
- No rate change without named approver
- PMS owns fiscal reservation details; Sovereign owns operational state and audit
- No PHI/system-of-record for medical clinics (non-goal)
6. Evidence & Audit
- Reservation claim, folio lines, identity proof receipt, approval signatures, settlement receipt, ERPNext invoice reference
- Verifiable by finance and data-protection auditors offline