@holoscript/plugin-travel-hospitality 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @holoscript/plugin-travel-hospitality
+
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies [c64fc1a]
+  - @holoscript/core@8.0.6
+
+## 2.0.0
+
+### Patch Changes
+
+- @holoscript/core@6.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 HoloScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@holoscript/plugin-travel-hospitality",
+  "version": "2.0.1",
+  "main": "src/index.ts",
+  "peerDependencies": {
+    "@holoscript/core": "8.0.6"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests"
+  }
+}

package/src/__tests__/revenuemanagement.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Revenue management tests — travel-hospitality-plugin
+ *
+ * Reference values verified against:
+ *  - Belobaba PP (1987) MIT thesis — EMSR benchmarks
+ *  - STR (Smith Travel Research) RevPAR methodology
+ *  - Cross RG (1997) Revenue Management — overbooking models
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  emsrYieldManagement,
+  revparAnalysis,
+  overbookingOptimization,
+  groupDisplacementAnalysis,
+  hotelDemandForecast,
+  buildTravelReceipt,
+  type RateClass,
+} from '../revenuemanagement';
+
+// ─── EMSR yield management ────────────────────────────────────────────────────
+
+describe('emsrYieldManagement', () => {
+  /**
+   * Classic 2-class example:
+   * Class 1 (high): ADR=$200, demand=80±20
+   * Class 2 (low):  ADR=$100, demand=120±30
+   * Capacity: 150 rooms
+   *
+   * By Littlewood: P(D1 ≥ protection) = r_low/r_high = 100/200 = 0.5
+   * At 50th percentile of N(80,20): protection ≈ 80 rooms
+   */
+  const twoClass: RateClass[] = [
+    { id: 'BAR', adr: 200, expectedDemand: 80, demandStdDev: 20 },
+    { id: 'Discount', adr: 100, expectedDemand: 120, demandStdDev: 30 },
+  ];
+
+  it('returns protection and booking limits', () => {
+    const r = emsrYieldManagement(150, twoClass);
+    expect(r.protectionLevels).toHaveLength(2);
+    expect(r.bookingLimits).toHaveLength(2);
+  });
+
+  it('high-ADR class has more protection than low-ADR class', () => {
+    const r = emsrYieldManagement(150, twoClass);
+    // Class sorted [high→low ADR]: protectionLevels[0] = protect high class
+    expect(r.protectionLevels[0]).toBeGreaterThanOrEqual(0);
+  });
+
+  it('rate classes are sorted high→low ADR in output', () => {
+    const r = emsrYieldManagement(150, twoClass);
+    for (let i = 1; i < r.rateClasses.length; i++) {
+      expect(r.rateClasses[i].adr).toBeLessThanOrEqual(r.rateClasses[i - 1].adr);
+    }
+  });
+
+  it('expectedRevenue is positive', () => {
+    const r = emsrYieldManagement(150, twoClass);
+    expect(r.expectedRevenue).toBeGreaterThan(0);
+  });
+
+  it('booking limits are non-negative', () => {
+    const r = emsrYieldManagement(150, twoClass);
+    for (const bl of r.bookingLimits) expect(bl).toBeGreaterThanOrEqual(0);
+  });
+
+  it('3-class EMSR returns correct array lengths', () => {
+    const threeClass: RateClass[] = [
+      { id: 'Suite',   adr: 400, expectedDemand: 20, demandStdDev: 8 },
+      { id: 'Standard', adr: 200, expectedDemand: 60, demandStdDev: 15 },
+      { id: 'Budget',   adr: 100, expectedDemand: 100, demandStdDev: 25 },
+    ];
+    const r = emsrYieldManagement(200, threeClass);
+    expect(r.protectionLevels).toHaveLength(3);
+    expect(r.bookingLimits).toHaveLength(3);
+  });
+
+  it('throws for capacity ≤ 0', () => {
+    expect(() => emsrYieldManagement(0, twoClass)).toThrow();
+  });
+
+  it('throws for empty rate classes', () => {
+    expect(() => emsrYieldManagement(150, [])).toThrow();
+  });
+});
+
+// ─── RevPAR analysis ─────────────────────────────────────────────────────────
+
+describe('revparAnalysis', () => {
+  /**
+   * 200 rooms, 160 occupied, revenue=$24,000
+   * Occupancy = 80%, ADR = 24000/160 = $150, RevPAR = 150 × 0.80 = $120
+   */
+  it('occupancy = occupied / available', () => {
+    const r = revparAnalysis(200, 160, 24_000);
+    expect(r.occupancyRate).toBeCloseTo(0.80, 5);
+  });
+
+  it('ADR = revenue / occupied rooms', () => {
+    const r = revparAnalysis(200, 160, 24_000);
+    expect(r.adr).toBeCloseTo(150, 3);
+  });
+
+  it('RevPAR = ADR × occupancy', () => {
+    const r = revparAnalysis(200, 160, 24_000);
+    expect(r.revpar).toBeCloseTo(r.adr * r.occupancyRate, 5);
+  });
+
+  it('full occupancy → RevPAR = ADR', () => {
+    const r = revparAnalysis(100, 100, 15_000);
+    expect(r.revpar).toBeCloseTo(r.adr, 5);
+  });
+
+  it('zero revenue → ADR = 0', () => {
+    const r = revparAnalysis(100, 0, 0);
+    expect(r.adr).toBe(0);
+    expect(r.revpar).toBe(0);
+  });
+
+  it('throws when occupiedRooms > availableRooms', () => {
+    expect(() => revparAnalysis(100, 110, 10_000)).toThrow();
+  });
+
+  it('throws for zero available rooms', () => {
+    expect(() => revparAnalysis(0, 0, 0)).toThrow();
+  });
+});
+
+// ─── Overbooking optimization ─────────────────────────────────────────────────
+
+describe('overbookingOptimization', () => {
+  /**
+   * Capacity=100, noShowRate=0.10, ADR=$150, walkCost=$300
+   * Critical ratio = 150/(150+300) = 1/3 — expect some overbooking to be optimal
+   */
+  it('overbooking level ≥ 0', () => {
+    const r = overbookingOptimization(100, 0.10, 150, 300, 95);
+    expect(r.overbook).toBeGreaterThanOrEqual(0);
+  });
+
+  it('authorized bookings = capacity + overbook', () => {
+    const r = overbookingOptimization(100, 0.10, 150, 300, 95);
+    expect(r.authorizedBookings).toBe(r.capacity + r.overbook);
+  });
+
+  it('higher walk cost → lower overbooking', () => {
+    const r1 = overbookingOptimization(100, 0.10, 150, 100, 90);  // low walk cost
+    const r2 = overbookingOptimization(100, 0.10, 150, 1000, 90); // high walk cost
+    expect(r2.overbook).toBeLessThanOrEqual(r1.overbook);
+  });
+
+  it('expectedWalkCost ≥ 0', () => {
+    const r = overbookingOptimization(100, 0.10, 150, 300, 95);
+    expect(r.expectedWalkCost).toBeGreaterThanOrEqual(0);
+  });
+
+  it('zero no-show rate → no overbooking optimal', () => {
+    const r = overbookingOptimization(100, 0, 150, 300, 90);
+    expect(r.overbook).toBe(0);
+  });
+
+  it('throws for noShowRate > 1', () => {
+    expect(() => overbookingOptimization(100, 1.5, 150, 300, 90)).toThrow();
+  });
+});
+
+// ─── Group displacement ───────────────────────────────────────────────────────
+
+describe('groupDisplacementAnalysis', () => {
+  /**
+   * Group ADR=$120, 50 room-nights; Transient ADR=$180, prob=1.0
+   * Displacement cost = (180-120) × 50 = $3000
+   * Net value = 120×50 − 180×50 = $6000 − $9000 = −$3000 (unprofitable)
+   */
+  it('displacement cost = (transientADR - groupADR) × roomNights × prob', () => {
+    const r = groupDisplacementAnalysis(120, 50, 180, 1.0);
+    expect(r.displacementCost).toBeCloseTo((180 - 120) * 50, 4);
+  });
+
+  it('group with ADR > transient is profitable', () => {
+    const r = groupDisplacementAnalysis(200, 50, 150, 1.0);
+    expect(r.profitable).toBe(true);
+    expect(r.netValue).toBeGreaterThan(0);
+  });
+
+  it('group with ADR < transient at full demand probability is unprofitable', () => {
+    const r = groupDisplacementAnalysis(120, 50, 180, 1.0);
+    expect(r.profitable).toBe(false);
+    expect(r.netValue).toBeLessThan(0);
+  });
+
+  it('low transient demand probability → group becomes profitable', () => {
+    // If transient demand prob is very low, displacement cost low → group profitable
+    const r = groupDisplacementAnalysis(120, 50, 180, 0.1);
+    expect(r.profitable).toBe(true);
+  });
+
+  it('throws for zero groupADR', () => {
+    expect(() => groupDisplacementAnalysis(0, 50, 150, 1.0)).toThrow();
+  });
+});
+
+// ─── Hotel demand forecast ────────────────────────────────────────────────────
+
+describe('hotelDemandForecast', () => {
+  // 28 days of occupancy data with weekend peaks
+  const historical = Array.from({ length: 28 }, (_, i) => {
+    const dow = i % 7;
+    return 80 + (dow === 5 || dow === 6 ? 15 : 0) + Math.round(Math.random() * 5);
+  });
+
+  it('forecast length = forecastDays', () => {
+    const r = hotelDemandForecast(historical, 7);
+    expect(r.forecast).toHaveLength(7);
+  });
+
+  it('seasonal indices have 7 elements (one per day of week)', () => {
+    const r = hotelDemandForecast(historical, 7);
+    expect(r.seasonalIndices).toHaveLength(7);
+  });
+
+  it('RMSE is non-negative', () => {
+    const r = hotelDemandForecast(historical, 7);
+    expect(r.rmse).toBeGreaterThanOrEqual(0);
+  });
+
+  it('forecast values are non-negative', () => {
+    const r = hotelDemandForecast(historical, 14);
+    for (const f of r.forecast) expect(f).toBeGreaterThanOrEqual(0);
+  });
+
+  it('weekend indices > weekday indices (reflects weekend demand spike)', () => {
+    const r = hotelDemandForecast(historical, 7);
+    const weekdayAvg = (r.seasonalIndices[0] + r.seasonalIndices[1] + r.seasonalIndices[2] +
+                        r.seasonalIndices[3] + r.seasonalIndices[4]) / 5;
+    const weekendAvg = (r.seasonalIndices[5] + r.seasonalIndices[6]) / 2;
+    expect(weekendAvg).toBeGreaterThan(weekdayAvg);
+  });
+
+  it('throws for fewer than 14 days of history', () => {
+    expect(() => hotelDemandForecast([80, 90, 100], 7)).toThrow();
+  });
+
+  it('throws for zero forecastDays', () => {
+    expect(() => hotelDemandForecast(historical, 0)).toThrow();
+  });
+});
+
+// ─── Receipt ─────────────────────────────────────────────────────────────────
+
+describe('buildTravelReceipt', () => {
+  it('produces receipt with plugin=travel-hospitality and CAEL event', () => {
+    const revpar = revparAnalysis(200, 160, 24_000);
+    const receipt = buildTravelReceipt({ revpar, converged: true });
+    expect(receipt.plugin).toBe('travel-hospitality');
+    expect(receipt.cael.event).toBe('travel_hospitality.revenue_management');
+    expect(receipt.payloadHash).toBeTruthy();
+  });
+
+  it('accepted=true for healthy 80% occupancy', () => {
+    const revpar = revparAnalysis(200, 160, 24_000); // 80% occupancy
+    const receipt = buildTravelReceipt({ revpar, converged: true });
+    expect(receipt.acceptance.accepted).toBe(true);
+  });
+
+  it('accepted=false for low occupancy < 40%', () => {
+    const revpar = revparAnalysis(200, 70, 7_000); // 35% occupancy
+    const receipt = buildTravelReceipt({ revpar, converged: true });
+    expect(receipt.acceptance.accepted).toBe(false);
+    expect(receipt.acceptance.violations.length).toBeGreaterThan(0);
+  });
+
+  it('accepted=false for unprofitable group booking', () => {
+    const groupDisplacement = groupDisplacementAnalysis(120, 50, 180, 1.0);
+    const receipt = buildTravelReceipt({ groupDisplacement, converged: true });
+    expect(receipt.acceptance.accepted).toBe(false);
+  });
+
+  it('uses provided runId', () => {
+    const receipt = buildTravelReceipt({ converged: true }, { runId: 'travel-run-77' });
+    expect(receipt.runId).toBe('travel-run-77');
+  });
+});

package/src/index.ts

@@ -0,0 +1,13 @@
+export { createReservationHandler, type ReservationConfig, type ReservationStatus } from './traits/ReservationTrait';
+export { createItineraryHandler, type ItineraryConfig, type ItineraryItem } from './traits/ItineraryTrait';
+export { createRateManagementHandler, type RateManagementConfig, type RatePeriod } from './traits/RateManagementTrait';
+export * from './traits/types';
+
+import { createReservationHandler } from './traits/ReservationTrait';
+import { createItineraryHandler } from './traits/ItineraryTrait';
+import { createRateManagementHandler } from './traits/RateManagementTrait';
+
+export * from './revenuemanagement';
+
+export const pluginMeta = { name: '@holoscript/plugin-travel-hospitality', version: '1.0.0', traits: ['reservation', 'itinerary', 'rate_management', 'emsr_yield', 'revpar', 'overbooking', 'group_displacement', 'demand_forecast'] };
+export const traitHandlers = [createReservationHandler(), createItineraryHandler(), createRateManagementHandler()];

package/src/revenuemanagement.ts

@@ -0,0 +1,419 @@
+/**
+ * Revenue management solvers — travel-hospitality-plugin
+ *
+ * Implements:
+ *  - Hotel yield management (EMSR-b overbooking model)
+ *  - Dynamic pricing (bid-price control)
+ *  - RevPAR / ADR / Occupancy analytics
+ *  - Demand forecasting (exponential smoothing with seasonality)
+ *  - Overbooking optimization (walk cost vs denied revenue trade-off)
+ *  - Displacement cost calculation for group bookings
+ *
+ * References:
+ *  - Littlewood K (1972) 12th AGIFORS Symposium — original yield management
+ *  - Belobaba PP (1987) MIT thesis — EMSR
+ *  - Cross RG (1997) Revenue Management — practical implementation
+ */
+
+import { buildDomainSimulationReceipt, type DomainSimulationReceipt } from '@holoscript/core';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface RateClass {
+  /** Rate class identifier */
+  id: string;
+  /** Average daily rate for this class ($) */
+  adr: number;
+  /** Expected demand (units) */
+  expectedDemand: number;
+  /** Demand standard deviation */
+  demandStdDev: number;
+}
+
+export interface EMSRResult {
+  /** Protection levels per class (units to hold for higher classes) */
+  protectionLevels: number[];
+  /** Booking limits per class (open capacity for each class) */
+  bookingLimits: number[];
+  /** Expected revenue at optimal allocation */
+  expectedRevenue: number;
+  /** Rate classes (sorted high→low ADR) */
+  rateClasses: RateClass[];
+}
+
+export interface RevPARResult {
+  /** Rooms available */
+  availableRooms: number;
+  /** Rooms occupied */
+  occupiedRooms: number;
+  /** Occupancy rate [0,1] */
+  occupancyRate: number;
+  /** Average Daily Rate ($) */
+  adr: number;
+  /** Revenue Per Available Room = ADR × occupancy */
+  revpar: number;
+  /** Total room revenue ($) */
+  totalRevenue: number;
+}
+
+export interface OverbookingResult {
+  /** Total capacity */
+  capacity: number;
+  /** Optimal overbooking level (rooms above capacity) */
+  overbook: number;
+  /** Authorized bookings to accept */
+  authorizedBookings: number;
+  /** Expected no-show rate */
+  noShowRate: number;
+  /** Expected walk cost per displaced guest ($) */
+  walkCostPerGuest: number;
+  /** Expected total walk cost */
+  expectedWalkCost: number;
+  /** Expected revenue gain from overbooking vs no overbooking */
+  expectedRevenueGain: number;
+}
+
+export interface GroupDisplacementResult {
+  /** Group ADR */
+  groupAdr: number;
+  /** Group room-nights */
+  groupRoomNights: number;
+  /** Estimated transient ADR displaced */
+  transientAdr: number;
+  /** Displacement cost = (transientAdr - groupAdr) × roomNights */
+  displacementCost: number;
+  /** Net value: group revenue − displacement cost */
+  netValue: number;
+  /** Whether group booking is profitable */
+  profitable: boolean;
+}
+
+export interface HotelForecastResult {
+  historical: number[];
+  forecast: number[];
+  /** Seasonal indices (7-day weekly pattern) */
+  seasonalIndices: number[];
+  rmse: number;
+}
+
+export interface RevenueReceiptOptions {
+  runId?: string;
+}
+
+// ─── EMSR-b yield management ──────────────────────────────────────────────────
+
+/** Normal CDF approximation (Abramowitz & Stegun) */
+function normalCDF(x: number): number {
+  if (x < -6) return 0;
+  if (x > 6) return 1;
+  const a1 = 0.254829592, a2 = -0.284496736, a3 = 1.421413741;
+  const a4 = -1.453152027, a5 = 1.061405429, p = 0.3275911;
+  const sign = x >= 0 ? 1 : -1;
+  const absX = Math.abs(x);
+  const t = 1 / (1 + p * absX);
+  const poly = ((((a5 * t + a4) * t) + a3) * t + a2) * t + a1;
+  const erfVal = 1 - poly * t * Math.exp(-absX * absX);
+  return 0.5 * (1 + sign * erfVal);
+}
+
+/** Littlewood's rule: P(demand ≥ x) ≥ r_low/r_high → protect x seats for high class */
+function littlewoodProtection(
+  rLow: number,
+  rHigh: number,
+  mu: number,
+  sigma: number,
+): number {
+  // Find x such that P(D_high ≥ x) = r_low / r_high
+  const threshold = rLow / rHigh;
+  // P(D ≥ x) = 1 - Φ((x - μ)/σ)
+  // 1 - Φ(z) = threshold → z = Φ⁻¹(1 - threshold)
+  // Approximate Φ⁻¹ via rational approximation
+  const p = 1 - threshold;
+  const z = normInvApprox(p);
+  return Math.max(0, Math.round(mu + sigma * z));
+}
+
+/** Approximate normal quantile (Peter Acklam's approximation) */
+function normInvApprox(p: number): number {
+  if (p <= 0) return -6;
+  if (p >= 1) return 6;
+  const a = [-3.969683028665376e+01, 2.209460984245205e+02, -2.759285104469687e+02,
+              1.383577518672690e+02, -3.066479806614716e+01, 2.506628277459239e+00];
+  const b = [-5.447609879822406e+01, 1.615858368580409e+02, -1.556989798598866e+02,
+              6.680131188771972e+01, -1.328068155288572e+01];
+  const c = [-7.784894002430293e-03, -3.223964580411365e-01, -2.400758277161838e+00,
+              -2.549732539343734e+00, 4.374664141464968e+00, 2.938163982698783e+00];
+  const d = [7.784695709041462e-03, 3.224671290700398e-01, 2.445134137142996e+00, 3.754408661907416e+00];
+  const pLow = 0.02425, pHigh = 1 - pLow;
+
+  let q: number, r: number;
+  if (p < pLow) {
+    q = Math.sqrt(-2 * Math.log(p));
+    return (((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) /
+           ((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1);
+  } else if (p <= pHigh) {
+    q = p - 0.5; r = q * q;
+    return (((((a[0]*r+a[1])*r+a[2])*r+a[3])*r+a[4])*r+a[5])*q /
+           (((((b[0]*r+b[1])*r+b[2])*r+b[3])*r+b[4])*r+1);
+  } else {
+    q = Math.sqrt(-2 * Math.log(1 - p));
+    return -(((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) /
+             ((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1);
+  }
+}
+
+/**
+ * EMSR-b (Expected Marginal Seat Revenue-b) multi-class yield management.
+ * Rate classes must be provided in any order; sorted high→low ADR internally.
+ * capacity: total rooms available.
+ */
+export function emsrYieldManagement(
+  capacity: number,
+  rateClasses: RateClass[],
+): EMSRResult {
+  if (capacity <= 0) throw new Error('capacity must be positive');
+  if (rateClasses.length === 0) throw new Error('At least one rate class required');
+
+  // Sort descending by ADR
+  const sorted = [...rateClasses].sort((a, b) => b.adr - a.adr);
+
+  const protectionLevels: number[] = [];
+  const bookingLimits: number[] = [];
+
+  // EMSR-b: aggregate demand from classes j+1..n and find protection for class j
+  for (let j = 0; j < sorted.length - 1; j++) {
+    const r_j   = sorted[j].adr;       // higher class fare
+    const r_j1  = sorted[j + 1].adr;   // lower class fare
+
+    // Aggregate demand for classes 0..j (high-value classes)
+    let aggMu = 0, aggVar = 0;
+    for (let k = 0; k <= j; k++) {
+      aggMu  += sorted[k].expectedDemand;
+      aggVar += sorted[k].demandStdDev ** 2;
+    }
+    const aggSigma = Math.sqrt(aggVar);
+
+    const prot = littlewoodProtection(r_j1, r_j, aggMu, aggSigma);
+    protectionLevels.push(prot);
+  }
+  protectionLevels.push(0); // lowest class has no protection
+
+  // Booking limits: cumulative from lowest to highest
+  let remaining = capacity;
+  const bls: number[] = new Array(sorted.length).fill(0);
+  for (let j = sorted.length - 1; j >= 0; j--) {
+    const protect = j > 0 ? protectionLevels[j - 1] : 0;
+    bls[j] = Math.max(0, remaining - protect);
+    remaining = Math.max(0, remaining - sorted[j].expectedDemand);
+  }
+
+  // Expected revenue estimate
+  let expectedRevenue = 0;
+  for (let j = 0; j < sorted.length; j++) {
+    const expectedSales = Math.min(sorted[j].expectedDemand, bls[j]);
+    expectedRevenue += expectedSales * sorted[j].adr;
+  }
+
+  return { protectionLevels, bookingLimits: bls, expectedRevenue, rateClasses: sorted };
+}
+
+// ─── RevPAR / ADR / Occupancy ─────────────────────────────────────────────────
+
+export function revparAnalysis(
+  availableRooms: number,
+  occupiedRooms: number,
+  totalRevenue: number,
+): RevPARResult {
+  if (availableRooms <= 0) throw new Error('availableRooms must be positive');
+  if (occupiedRooms < 0) throw new Error('occupiedRooms must be non-negative');
+  if (occupiedRooms > availableRooms) throw new Error('occupiedRooms cannot exceed availableRooms');
+  if (totalRevenue < 0) throw new Error('totalRevenue must be non-negative');
+
+  const occupancyRate = occupiedRooms / availableRooms;
+  const adr = occupiedRooms > 0 ? totalRevenue / occupiedRooms : 0;
+  const revpar = adr * occupancyRate;
+
+  return { availableRooms, occupiedRooms, occupancyRate, adr, revpar, totalRevenue };
+}
+
+// ─── Overbooking optimization ─────────────────────────────────────────────────
+
+/**
+ * Optimal overbooking level using newsvendor-style model.
+ * Overbook = Q such that P(no-shows ≥ overbook) = walkCost / (revenue + walkCost)
+ *
+ * No-show count modeled as Binomial(n+overbook, noShowRate) ≈ Normal.
+ */
+export function overbookingOptimization(
+  capacity: number,
+  noShowRate: number,
+  adr: number,
+  walkCostPerGuest: number,
+  expectedBookings: number,
+): OverbookingResult {
+  if (capacity <= 0) throw new Error('capacity must be positive');
+  if (noShowRate < 0 || noShowRate > 1) throw new Error('noShowRate must be in [0, 1]');
+  if (adr <= 0) throw new Error('adr must be positive');
+  if (walkCostPerGuest < 0) throw new Error('walkCostPerGuest must be non-negative');
+
+  // Critical ratio for overbooking newsvendor
+  const criticalRatio = adr / (adr + walkCostPerGuest);
+
+  // No-show distribution at bookings = capacity + overbook
+  // Expected no-shows = noShowRate × bookings
+  // For small overbook, find overbook* where P(no-shows ≥ overbook) = 1 - criticalRatio
+  let optOverbook = 0;
+  for (let ob = 0; ob <= Math.floor(capacity * 0.3); ob++) {
+    const bookings = capacity + ob;
+    const mu = noShowRate * bookings;
+    const sigma = Math.sqrt(bookings * noShowRate * (1 - noShowRate));
+    const pNoShowGe = 1 - normalCDF((ob - mu) / Math.max(sigma, 0.1));
+    if (pNoShowGe < 1 - criticalRatio) {
+      optOverbook = Math.max(0, ob - 1);
+      break;
+    }
+    optOverbook = ob;
+  }
+
+  const authorizedBookings = capacity + optOverbook;
+  const mu = noShowRate * authorizedBookings;
+  const sigma = Math.sqrt(authorizedBookings * noShowRate * (1 - noShowRate));
+
+  // Expected walks = E[max(0, shows - capacity)] where shows = bookings - noShows
+  let expectedWalks = 0;
+  for (let w = 1; w <= optOverbook + 5; w++) {
+    const pWalk = 1 - normalCDF((w - 0.5 - (authorizedBookings - mu - capacity)) / Math.max(sigma, 0.1));
+    expectedWalks += pWalk;
+    if (pWalk < 1e-6) break;
+  }
+  expectedWalks = Math.max(0, expectedWalks);
+
+  const expectedWalkCost = expectedWalks * walkCostPerGuest;
+  // Revenue gain vs no-overbooking: each additional booking accepted at ADR, less expected walk cost
+  const expectedRevenueGain = Math.max(0, optOverbook * adr * noShowRate - expectedWalkCost);
+
+  return { capacity, overbook: optOverbook, authorizedBookings, noShowRate, walkCostPerGuest, expectedWalkCost, expectedRevenueGain };
+}
+
+// ─── Group displacement ───────────────────────────────────────────────────────
+
+/**
+ * Calculate whether accepting a group booking displaces more-valuable transient demand.
+ */
+export function groupDisplacementAnalysis(
+  groupAdr: number,
+  groupRoomNights: number,
+  transientAdr: number,
+  transientDemandProbability = 1.0,
+): GroupDisplacementResult {
+  if (groupAdr <= 0) throw new Error('groupAdr must be positive');
+  if (groupRoomNights <= 0) throw new Error('groupRoomNights must be positive');
+  if (transientAdr <= 0) throw new Error('transientAdr must be positive');
+
+  const displacementCost = (transientAdr - groupAdr) * groupRoomNights * transientDemandProbability;
+  const netValue = groupAdr * groupRoomNights - (transientAdr * groupRoomNights * transientDemandProbability);
+  const profitable = netValue > 0;
+
+  return { groupAdr, groupRoomNights, transientAdr, displacementCost, netValue, profitable };
+}
+
+// ─── Demand forecasting with weekly seasonality ───────────────────────────────
+
+/**
+ * Hotel room demand forecast using exponential smoothing + weekly seasonality indices.
+ * Requires at least 14 days of history for seasonal estimation.
+ */
+export function hotelDemandForecast(
+  historical: number[],
+  forecastDays: number,
+): HotelForecastResult {
+  if (historical.length < 14) throw new Error('At least 14 days of history required for seasonal estimation');
+  if (forecastDays < 1) throw new Error('forecastDays must be ≥ 1');
+
+  // Estimate weekly seasonal indices (7 days)
+  const seasonalIndices = Array(7).fill(0);
+  const dayCounts = Array(7).fill(0);
+  const overallMean = historical.reduce((a, b) => a + b, 0) / historical.length;
+
+  historical.forEach((v, i) => {
+    const dow = i % 7;
+    seasonalIndices[dow] += v;
+    dayCounts[dow]++;
+  });
+  seasonalIndices.forEach((s, i) => {
+    seasonalIndices[i] = overallMean > 0 ? (s / dayCounts[i]) / overallMean : 1;
+  });
+
+  // Deseasonalise
+  const deseason = historical.map((v, i) => {
+    const idx = seasonalIndices[i % 7];
+    return idx > 0 ? v / idx : v;
+  });
+
+  // Simple exponential smoothing on deseasonalised series (alpha=0.3)
+  const alpha = 0.3;
+  const s = [deseason[0]];
+  for (let i = 1; i < deseason.length; i++) s.push(alpha * deseason[i] + (1 - alpha) * s[i - 1]);
+  const lastLevel = s[s.length - 1];
+
+  // RMSE on deseasonalised
+  let errSum = 0;
+  for (let i = 1; i < historical.length; i++) {
+    errSum += (historical[i] - s[i - 1] * seasonalIndices[i % 7]) ** 2;
+  }
+  const rmse = Math.sqrt(errSum / (historical.length - 1));
+
+  // Forecast
+  const startDow = historical.length % 7;
+  const forecast = Array.from({ length: forecastDays }, (_, i) => {
+    return Math.max(0, Math.round(lastLevel * seasonalIndices[(startDow + i) % 7]));
+  });
+
+  return { historical, forecast, seasonalIndices, rmse };
+}
+
+// ─── Receipt ──────────────────────────────────────────────────────────────────
+
+export interface TravelAnalysisResult {
+  emsr?: EMSRResult;
+  revpar?: RevPARResult;
+  overbooking?: OverbookingResult;
+  groupDisplacement?: GroupDisplacementResult;
+  forecast?: HotelForecastResult;
+  converged: true;
+}
+
+export function buildTravelReceipt(
+  result: TravelAnalysisResult,
+  options?: RevenueReceiptOptions,
+): DomainSimulationReceipt {
+  const violations: Array<{ criterion: string; message: string }> = [];
+
+  if (result.revpar && result.revpar.occupancyRate < 0.40) {
+    violations.push({
+      criterion: 'occupancy',
+      message: `Occupancy ${(result.revpar.occupancyRate * 100).toFixed(1)}% is critically low (<40%)`,
+    });
+  }
+  if (result.groupDisplacement && !result.groupDisplacement.profitable) {
+    violations.push({
+      criterion: 'group_displacement',
+      message: `Group booking net value is negative ($${result.groupDisplacement.netValue.toFixed(0)}) — displaces more valuable transient demand`,
+    });
+  }
+
+  return buildDomainSimulationReceipt({
+    plugin: 'travel-hospitality',
+    pluginVersion: '1.0.0',
+    runId: options?.runId ?? `travel-${Date.now().toString(36)}`,
+    solverConfig: { solverType: 'revenue-management', scale: 'property' },
+    resultSummary: {
+      revpar: result.revpar?.revpar ?? null,
+      occupancyRate: result.revpar?.occupancyRate ?? null,
+      emsrExpectedRevenue: result.emsr?.expectedRevenue ?? null,
+      overbookLevel: result.overbooking?.overbook ?? null,
+    },
+    cael: { version: 'cael.v1', event: 'travel_hospitality.revenue_management', solverType: 'travel-hospitality.emsr-b' },
+    acceptance: { accepted: violations.length === 0, violations },
+  });
+}

package/src/traits/ItineraryTrait.ts

@@ -0,0 +1,25 @@
+/** @itinerary Trait — Trip itinerary planning. @trait itinerary */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface ItineraryItem { id: string; day: number; time: string; activity: string; location: string; durationMin: number; bookingRef?: string; notes?: string; }
+export interface ItineraryConfig { tripName: string; startDate: string; endDate: string; travelers: number; items: ItineraryItem[]; }
+export interface ItineraryState { currentDay: number; completedItems: string[]; totalDays: number; }
+
+const defaultConfig: ItineraryConfig = { tripName: '', startDate: '', endDate: '', travelers: 1, items: [] };
+
+export function createItineraryHandler(): TraitHandler<ItineraryConfig> {
+  return { name: 'itinerary', defaultConfig,
+    onAttach(n: HSPlusNode, c: ItineraryConfig, ctx: TraitContext) {
+      const days = c.startDate && c.endDate ? Math.max(1, Math.ceil((new Date(c.endDate).getTime() - new Date(c.startDate).getTime()) / 86400000)) : 1;
+      n.__itinState = { currentDay: 1, completedItems: [], totalDays: days };
+      ctx.emit?.('itinerary:planned', { days, items: c.items.length });
+    },
+    onDetach(n: HSPlusNode, _c: ItineraryConfig, ctx: TraitContext) { delete n.__itinState; ctx.emit?.('itinerary:removed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, _c: ItineraryConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__itinState as ItineraryState | undefined; if (!s) return;
+      if (e.type === 'itinerary:complete_item') { const id = e.payload?.itemId as string; if (!s.completedItems.includes(id)) { s.completedItems.push(id); ctx.emit?.('itinerary:item_done', { id, completed: s.completedItems.length }); } }
+      if (e.type === 'itinerary:next_day') { s.currentDay = Math.min(s.totalDays, s.currentDay + 1); ctx.emit?.('itinerary:day_changed', { day: s.currentDay }); }
+    },
+  };
+}

package/src/traits/RateManagementTrait.ts

@@ -0,0 +1,24 @@
+/** @rate_management Trait — Dynamic pricing and rate control. @trait rate_management */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface RatePeriod { startDate: string; endDate: string; rate: number; minStay: number; }
+export interface RateManagementConfig { baseRate: number; currency: string; seasons: RatePeriod[]; weekendMultiplier: number; dynamicPricingEnabled: boolean; minRate: number; maxRate: number; }
+export interface RateManagementState { currentRate: number; occupancyPercent: number; revenueToday: number; }
+
+const defaultConfig: RateManagementConfig = { baseRate: 100, currency: 'USD', seasons: [], weekendMultiplier: 1.2, dynamicPricingEnabled: false, minRate: 50, maxRate: 500 };
+
+export function createRateManagementHandler(): TraitHandler<RateManagementConfig> {
+  return { name: 'rate_management', defaultConfig,
+    onAttach(n: HSPlusNode, c: RateManagementConfig, ctx: TraitContext) { n.__rateState = { currentRate: c.baseRate, occupancyPercent: 0, revenueToday: 0 }; ctx.emit?.('rate:configured', { base: c.baseRate }); },
+    onDetach(n: HSPlusNode, _c: RateManagementConfig, ctx: TraitContext) { delete n.__rateState; ctx.emit?.('rate:removed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: RateManagementConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__rateState as RateManagementState | undefined; if (!s) return;
+      if (e.type === 'rate:update_occupancy') {
+        s.occupancyPercent = (e.payload?.occupancy as number) ?? 0;
+        if (c.dynamicPricingEnabled) { s.currentRate = Math.min(c.maxRate, Math.max(c.minRate, c.baseRate * (1 + s.occupancyPercent / 100))); ctx.emit?.('rate:adjusted', { rate: s.currentRate, occupancy: s.occupancyPercent }); }
+      }
+      if (e.type === 'rate:record_sale') { s.revenueToday += s.currentRate; ctx.emit?.('rate:sale_recorded', { revenue: s.revenueToday }); }
+    },
+  };
+}

package/src/traits/ReservationTrait.ts

@@ -0,0 +1,27 @@
+/** @reservation Trait — Booking and reservation management. @trait reservation */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type ReservationStatus = 'pending' | 'confirmed' | 'checked_in' | 'checked_out' | 'cancelled' | 'no_show';
+export interface ReservationConfig { confirmationNumber: string; guestName: string; roomType: string; checkIn: string; checkOut: string; guests: number; ratePerNight: number; currency: string; specialRequests?: string; }
+export interface ReservationState { status: ReservationStatus; totalNights: number; totalCost: number; }
+
+const defaultConfig: ReservationConfig = { confirmationNumber: '', guestName: '', roomType: 'standard', checkIn: '', checkOut: '', guests: 1, ratePerNight: 0, currency: 'USD' };
+
+export function createReservationHandler(): TraitHandler<ReservationConfig> {
+  return { name: 'reservation', defaultConfig,
+    onAttach(n: HSPlusNode, c: ReservationConfig, ctx: TraitContext) {
+      const nights = c.checkIn && c.checkOut ? Math.max(1, Math.ceil((new Date(c.checkOut).getTime() - new Date(c.checkIn).getTime()) / 86400000)) : 1;
+      n.__resState = { status: 'pending' as ReservationStatus, totalNights: nights, totalCost: nights * c.ratePerNight };
+      ctx.emit?.('reservation:created', { confirmation: c.confirmationNumber, nights });
+    },
+    onDetach(n: HSPlusNode, _c: ReservationConfig, ctx: TraitContext) { delete n.__resState; ctx.emit?.('reservation:removed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, _c: ReservationConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__resState as ReservationState | undefined; if (!s) return;
+      if (e.type === 'reservation:confirm') { s.status = 'confirmed'; ctx.emit?.('reservation:confirmed'); }
+      if (e.type === 'reservation:check_in') { s.status = 'checked_in'; ctx.emit?.('reservation:checked_in'); }
+      if (e.type === 'reservation:check_out') { s.status = 'checked_out'; ctx.emit?.('reservation:checked_out', { total: s.totalCost }); }
+      if (e.type === 'reservation:cancel') { s.status = 'cancelled'; ctx.emit?.('reservation:cancelled'); }
+    },
+  };
+}

package/src/traits/types.ts

@@ -0,0 +1,4 @@
+export interface HSPlusNode { id?: string; properties?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitContext { emit?: (event: string, payload?: unknown) => void; [key: string]: unknown; }
+export interface TraitEvent { type: string; payload?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitHandler<T = unknown> { name: string; defaultConfig: T; onAttach(n: HSPlusNode, c: T, ctx: TraitContext): void; onDetach(n: HSPlusNode, c: T, ctx: TraitContext): void; onUpdate(n: HSPlusNode, c: T, ctx: TraitContext, d: number): void; onEvent(n: HSPlusNode, c: T, ctx: TraitContext, e: TraitEvent): void; }

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../../tsconfig.json", "compilerOptions": { "outDir": "dist", "rootDir": "src", "declaration": true }, "include": ["src"] }

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+  },
+});