Architecture Mapping — Hotel Operations to Canonical Primitives

Status: Technical Specification
Sources: Playbook Engine Architecture & Runtime Execution Model §2, Integration Matrix & System Adapters Specification, Jijibora Architecture — Design Thesis in Developer Terms, AGENTS.md — Sovereign OS / Cosmic Circuit Schema Architecture

1. Governing Rule — Zero Bespoke Tables

No hotel-specific tables (room_reservation, housekeeping_task, guest_folio, work_order, purchase_order) are created. Every hotel entity maps to the existing canonical base infrastructure:

claim — discrete statements of fact, reservations, requisitions, approval gates, tasks, bookings, incident reports (CNS-typed, traits, signatures)
truth_node & truth_edge — structural relationship graph (guest→room, room→floor, staff→shift, requisition→budget, evidence links)
resource & resource_edge — tangible/digital assets (rooms, inventory, equipment, budget pools)
integration_entity (Stratum 356) — universal mirror for external records (PMS reservation, ERPNext PO, OpenMAINT card, Plane task)
s184_record_federation — boundary security for records crossing property/group boundaries

If an entity cannot be mapped to these primitives, stop and ask — do not create a new table.

2. Canonical Mapping Table

Hotel Concept	Canonical Primitive	CNS Type / Binding	Example Fields
Guest profile	`truth_node`	`cns://truth/node/person`	name, ID doc, loyalty tier, contact preferences
Room / unit	`resource`	`cns://resource/room`	room number, floor, type, status, rate class
Reservation / booking	`claim`	`cns://claim/type/hotel/reservation`	confirmation no., dates, guests, rate, source
Folio / invoice line	`claim`	`cns://claim/type/hotel/folio_line`	charge code, amount, tax, posting date
Housekeeping task	`claim`	`cns://workflow/task`	room, attendant, status, checklist, PoCE step
Maintenance work order	`claim`	`cns://operations/work_order`	asset, fault, priority, technician, OpenMAINT card ref
Purchase requisition	`claim`	`cns://workflow/requisition`	vendor, line items, budget, approval tier
Event / banquet booking	`claim`	`cns://claim/type/hotel/event`	function space, dates, F&B minimum, AV needs
Mood board / event design	`claim`	`cns://creative/mood_board`	layout, color palette, assets, approvals
Staff shift / assignment	`truth_edge`	staff→shift→role	shift dates, role, site, roster
Incident / security report	`claim`	`cns://claim/type/hotel/incident`	location, severity, reporter, evidence, PoCE
Vendor / supplier record	`truth_node`	`cns://truth/node/organization`	tax ID, contract, rating, payment terms
PMS reservation mirror	`integration_entity`	system: "pms", external_id	PMS confirmation, last synced, checksum
ERPNext PO mirror	`integration_entity`	system: "erpnext", external_id	PO number, fiscal status
OpenMAINT work order mirror	`integration_entity`	system: "openmaint", external_id	WO number, asset code
Plane task mirror	`integration_entity`	system: "plane", external_id	issue ID, board lane
Synapse room mirror	`integration_entity`	system: "synapse", external_id	Matrix room_id

3. Truth Edge Examples (Hotel Relationship Graph)

text

truth_node:guest_G123  --occupies-->  resource:room_405
truth_node:guest_G123  --has_claim-->  claim:reservation_RES-2026-001
claim:reservation_RES-2026-001  --charges_budget-->  resource:budget_front_office_q4
claim:housekeeping_HK-405  --assigned_to-->  truth_node:staff_attendant_9
claim:housekeeping_HK-405  --services-->  resource:room_405
claim:workorder_WO-88  --maintains-->  resource:asset_hvac_lobby
claim:requisition_REQ-77  --requires_gate-->  claim:approval_gate_tiered
claim:requisition_REQ-77  --submitted_by-->  truth_node:staff_procurement_3

Each edge is created via fn::create_truth_edge (10-arg signature from s25_reactive_edge_protocol.surql) and is subject to vault scope / lease gates (fn::vault::check_scope_access, fn::vault::grant_lease).

4. Hotel Multi-Property (Group) Architecture

For hotel groups, each property is a scope with isolation boundaries. Cross-property operations (group procurement, staff transfers, shared vendors) use s184_record_federation:

cns_federation_policy — which CNS schemas may cross property borders (e.g., cns://claim/type/hotel/requisition may federate; cns://claim/type/hotel/folio_line may not)
record_federation_binding — binds a local record to an authorized peer property scope
record_federation_event — immutable audit ledger of cross-property actions
APF (s230) resolves effective permissions per user per property scope

See Cross-Organization Federation & Federated PoCE Specification for the federated PoCE sequence (multi-party escrow release on group contracts).

5. PoCE Integration Points for Hotels

Every critical hotel state transition starts a PoCE session (fn::lifecycle::start_poce_session):

Transition	PoCE trigger	Evidence recorded
Guest check-in	lifecycle event	ID verification, room assignment, receptionist signature
Housekeeping room sign-off	`record_poce_step`	attendant, checklist items, photo evidence hash, timestamp
Maintenance completion	`record_poce_step`	technician, parts consumed, OpenMAINT close, expert sign-off
PO approval	`fn::poce::record_step`	approvers, quorum threshold, dual-custody signatures
Event settlement / escrow release	`fn::poce::finalize_session`	client sign-off, delivery verification, payment authorization

See Core Subsystem → PoCE Bridge Architecture and Playbook Engine Architecture & Runtime Execution Model §3.

6. What We Do NOT Build (Honesty Limits)

Per AGENTS.md — Sovereign OS / Cosmic Circuit mandates and the Jijibora architecture (Jijibora Architecture — Design Thesis in Developer Terms §7 Non-goals):

No PMS replacement as a bespoke vertical. The PMS remains the guest-facing system of engagement; Sovereign OS is the headless state of record and integration backbone.
No dynamic room-rate engine unless it can be expressed as solver-gateway capability + declarative lookups (not hardcoded).
No synthetic "optimal" occupancy, housekeeping route, or procurement plan. If the solver-gateway (:3070) is down, refuse with 502/503 (mandate: fail closed).
No fake metrics on dashboards (no 98.4%, no 12 active rooms). UI renders live data or honest skeleton/empty states (mandate 12).
No filesystem lookups at runtime. All hotel config lives in NATS JetStream KV (SOVEREIGN_LOOKUPS, SOVEREIGN_SCENARIOS, SOVEREIGN_TEMPLATES), seeded offline via scripts/seed-nats-kv-declarative.mjs.