@holoscript/plugin-restaurant 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @holoscript/plugin-restaurant
+
+## 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-restaurant",
+  "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__/restaurantsolver.test.ts

@@ -0,0 +1,314 @@
+/**
+ * Restaurant operations solver tests — restaurant-plugin
+ *
+ * Reference values verified against:
+ *  - Kasavana M, Smith D (1982) Menu Engineering. Hospitality Publications.
+ *  - National Restaurant Association food cost standards (28-32%)
+ *  - SJF scheduling theory
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  tableAssignment,
+  kitchenQueueScheduler,
+  menuEngineering,
+  foodCostAnalysis,
+  turnTimePredictor,
+  buildRestaurantReceipt,
+} from '../restaurantsolver';
+
+// ─── Table Assignment ─────────────────────────────────────────────────────────
+
+describe('tableAssignment', () => {
+  const tables = [
+    { id: 'T1', capacity: 2, section: 'patio', available: true },
+    { id: 'T2', capacity: 4, section: 'main',  available: true },
+    { id: 'T3', capacity: 6, section: 'main',  available: true },
+    { id: 'T4', capacity: 8, section: 'bar',   available: true },
+  ];
+
+  it('party of 2 assigned to smallest fitting table (best-fit)', () => {
+    const parties = [{ id: 'P1', partySize: 2, priorityGuest: false }];
+    const r = tableAssignment(tables, parties);
+    const assigned = r.assignments.find(a => a.partyId === 'P1');
+    expect(assigned!.tableCapacity).toBeGreaterThanOrEqual(2);
+    // Best-fit: should assign T1 (cap=2) over T2 (cap=4)
+    expect(assigned!.tableCapacity).toBe(2);
+  });
+
+  it('priority guests seated before regular guests', () => {
+    const parties = [
+      { id: 'Regular', partySize: 4, priorityGuest: false },
+      { id: 'VIP',     partySize: 4, priorityGuest: true  },
+    ];
+    const r = tableAssignment(tables, parties);
+    // VIP should be assigned (both should fit since we have 2 4+ tables)
+    expect(r.assignments.some(a => a.partyId === 'VIP')).toBe(true);
+  });
+
+  it('party larger than any table goes to unassigned', () => {
+    const parties = [{ id: 'Huge', partySize: 20, priorityGuest: false }];
+    const r = tableAssignment(tables, parties);
+    expect(r.unassigned).toContain('Huge');
+  });
+
+  it('utilization = partySize / tableCapacity', () => {
+    const parties = [{ id: 'P1', partySize: 3, priorityGuest: false }];
+    const r = tableAssignment(tables, parties);
+    const assigned = r.assignments.find(a => a.partyId === 'P1');
+    expect(assigned!.utilization).toBeCloseTo(assigned!.partySize / assigned!.tableCapacity, 4);
+  });
+
+  it('section preference respected when available', () => {
+    const parties = [{ id: 'P1', partySize: 2, preferredSection: 'patio', priorityGuest: false }];
+    const r = tableAssignment(tables, parties);
+    const assigned = r.assignments.find(a => a.partyId === 'P1');
+    expect(assigned!.sectionMatch).toBe(true);
+    expect(assigned!.tableId).toBe('T1');
+  });
+
+  it('overallUtilization in [0, 1]', () => {
+    const parties = [{ id: 'P1', partySize: 2, priorityGuest: false }];
+    const r = tableAssignment(tables, parties);
+    expect(r.overallUtilization).toBeGreaterThanOrEqual(0);
+    expect(r.overallUtilization).toBeLessThanOrEqual(1);
+  });
+
+  it('throws for empty tables', () => {
+    expect(() => tableAssignment([], [{ id: 'P1', partySize: 2, priorityGuest: false }])).toThrow();
+  });
+});
+
+// ─── Kitchen Queue Scheduler ──────────────────────────────────────────────────
+
+describe('kitchenQueueScheduler', () => {
+  const tickets = [
+    { id: 'T1', estimatedMinutes: 15, priority: 2 as const, tableId: 'A', items: ['burger'] },
+    { id: 'T2', estimatedMinutes: 8,  priority: 1 as const, tableId: 'B', items: ['soup']   },
+    { id: 'T3', estimatedMinutes: 20, priority: 2 as const, tableId: 'C', items: ['steak']  },
+    { id: 'T4', estimatedMinutes: 5,  priority: 3 as const, tableId: 'D', items: ['dessert'] },
+  ];
+
+  it('priority 1 ticket scheduled first', () => {
+    const r = kitchenQueueScheduler(tickets);
+    expect(r.sequence[0].ticketId).toBe('T2'); // priority 1 ticket
+  });
+
+  it('makespan = sum of all cook times (sequential)', () => {
+    const r = kitchenQueueScheduler(tickets);
+    const expected = tickets.reduce((s, t) => s + t.estimatedMinutes, 0);
+    expect(r.makespan).toBe(expected);
+  });
+
+  it('sequence covers all tickets', () => {
+    const r = kitchenQueueScheduler(tickets);
+    expect(r.sequence).toHaveLength(tickets.length);
+  });
+
+  it('each ticket starts at previous end', () => {
+    const r = kitchenQueueScheduler(tickets);
+    for (let i = 1; i < r.sequence.length; i++) {
+      expect(r.sequence[i].startMin).toBe(r.sequence[i - 1].endMin);
+    }
+  });
+
+  it('within same priority: shorter job goes first (SJF)', () => {
+    const r = kitchenQueueScheduler(tickets);
+    // Priority 2 tickets: T1 (15min) and T3 (20min) → T1 before T3
+    const t1pos = r.sequence.findIndex(s => s.ticketId === 'T1');
+    const t3pos = r.sequence.findIndex(s => s.ticketId === 'T3');
+    expect(t1pos).toBeLessThan(t3pos);
+  });
+
+  it('avgWaitMin ≥ 0', () => {
+    const r = kitchenQueueScheduler(tickets);
+    expect(r.avgWaitMin).toBeGreaterThanOrEqual(0);
+  });
+
+  it('throws for empty tickets', () => {
+    expect(() => kitchenQueueScheduler([])).toThrow();
+  });
+});
+
+// ─── Menu Engineering ─────────────────────────────────────────────────────────
+
+describe('menuEngineering', () => {
+  /**
+   * Stars: high popularity + high margin
+   * Plow-horses: high popularity + low margin
+   * Puzzles: low popularity + high margin
+   * Dogs: low popularity + low margin
+   */
+  const items = [
+    { id: 'burger', name: 'Burger',  popularity: 100, contributionMargin: 12.00 }, // star — avg margin = (12+4+25+3)/4 = 11; 12 > 11 → star
+    { id: 'pasta',  name: 'Pasta',   popularity: 80,  contributionMargin: 4.00 },   // plow-horse
+    { id: 'lobster',name: 'Lobster', popularity: 20,  contributionMargin: 25.00 },  // puzzle
+    { id: 'salad',  name: 'Salad',   popularity: 30,  contributionMargin: 3.00 },   // dog
+  ];
+
+  it('burger (high pop, high margin) → star', () => {
+    const r = menuEngineering(items);
+    const burger = r.items.find(i => i.id === 'burger');
+    expect(burger!.category).toBe('star');
+  });
+
+  it('pasta (high pop, low margin) → plow-horse', () => {
+    const r = menuEngineering(items);
+    const pasta = r.items.find(i => i.id === 'pasta');
+    expect(pasta!.category).toBe('plow-horse');
+  });
+
+  it('lobster (low pop, high margin) → puzzle', () => {
+    const r = menuEngineering(items);
+    const lobster = r.items.find(i => i.id === 'lobster');
+    expect(lobster!.category).toBe('puzzle');
+  });
+
+  it('salad (low pop, low margin) → dog', () => {
+    const r = menuEngineering(items);
+    const salad = r.items.find(i => i.id === 'salad');
+    expect(salad!.category).toBe('dog');
+  });
+
+  it('averagePopularity = mean of item popularities', () => {
+    const r = menuEngineering(items);
+    const expected = items.reduce((s, i) => s + i.popularity, 0) / items.length;
+    expect(r.averagePopularity).toBeCloseTo(expected, 4);
+  });
+
+  it('categoryCount sums to total items', () => {
+    const r = menuEngineering(items);
+    const total = r.categoryCount.star + r.categoryCount['plow-horse'] + r.categoryCount.puzzle + r.categoryCount.dog;
+    expect(total).toBe(items.length);
+  });
+
+  it('throws for empty items', () => {
+    expect(() => menuEngineering([])).toThrow();
+  });
+});
+
+// ─── Food Cost Analysis ───────────────────────────────────────────────────────
+
+describe('foodCostAnalysis', () => {
+  /**
+   * Burger: ingredient $3, price $12, sold 100 → food cost 25%
+   * Steak: ingredient $15, price $35, sold 50 → food cost 42.9%
+   */
+  const lines = [
+    { item: 'burger', ingredientCostUSD: 3, sellingPriceUSD: 12, unitsSold: 100 },
+    { item: 'steak',  ingredientCostUSD: 15, sellingPriceUSD: 35, unitsSold: 50 },
+  ];
+
+  it('per-item foodCostPct = ingredient / price', () => {
+    const r = foodCostAnalysis(lines);
+    expect(r.lines[0].foodCostPct).toBeCloseTo(3 / 12, 4);
+    expect(r.lines[1].foodCostPct).toBeCloseTo(15 / 35, 4);
+  });
+
+  it('totalRevenue = sum of price × units', () => {
+    const r = foodCostAnalysis(lines);
+    const expected = 12 * 100 + 35 * 50;
+    expect(r.totalRevenue).toBeCloseTo(expected, 2);
+  });
+
+  it('blendedFoodCostPct = totalCost / totalRevenue', () => {
+    const r = foodCostAnalysis(lines);
+    expect(r.blendedFoodCostPct).toBeCloseTo(r.totalCost / r.totalRevenue, 4);
+  });
+
+  it('overTarget=true when blended cost exceeds target', () => {
+    // Steak-heavy menu at 42.9% → over standard 30% target
+    const heavySteak = [{ item: 'steak', ingredientCostUSD: 15, sellingPriceUSD: 35, unitsSold: 200 }];
+    const r = foodCostAnalysis(heavySteak, 0.30);
+    expect(r.overTarget).toBe(true);
+  });
+
+  it('overTarget=false when within target', () => {
+    const lowCost = [{ item: 'drink', ingredientCostUSD: 1, sellingPriceUSD: 8, unitsSold: 100 }];
+    const r = foodCostAnalysis(lowCost, 0.30);
+    expect(r.overTarget).toBe(false);
+  });
+
+  it('throws for empty lines', () => {
+    expect(() => foodCostAnalysis([])).toThrow();
+  });
+});
+
+// ─── Turn Time Predictor ──────────────────────────────────────────────────────
+
+describe('turnTimePredictor', () => {
+  it('dinner base is longer than lunch', () => {
+    const lunch  = turnTimePredictor({ partySize: 2, mealPeriod: 'lunch',  specialEvent: false });
+    const dinner = turnTimePredictor({ partySize: 2, mealPeriod: 'dinner', specialEvent: false });
+    expect(dinner.predictedTurnMin).toBeGreaterThan(lunch.predictedTurnMin);
+  });
+
+  it('special event adds to turn time', () => {
+    const normal  = turnTimePredictor({ partySize: 2, mealPeriod: 'dinner', specialEvent: false });
+    const special = turnTimePredictor({ partySize: 2, mealPeriod: 'dinner', specialEvent: true  });
+    expect(special.predictedTurnMin).toBeGreaterThan(normal.predictedTurnMin);
+  });
+
+  it('larger party → longer turn time', () => {
+    const small = turnTimePredictor({ partySize: 2, mealPeriod: 'dinner', specialEvent: false });
+    const large = turnTimePredictor({ partySize: 8, mealPeriod: 'dinner', specialEvent: false });
+    expect(large.predictedTurnMin).toBeGreaterThan(small.predictedTurnMin);
+  });
+
+  it('turnsPerEvening = 480 / predictedTurnMin', () => {
+    const r = turnTimePredictor({ partySize: 4, mealPeriod: 'dinner', specialEvent: false });
+    expect(r.turnsPerEvening).toBeCloseTo(480 / r.predictedTurnMin, 4);
+  });
+
+  it('confidenceInterval spans ±10% of predictedTurnMin', () => {
+    const r = turnTimePredictor({ partySize: 4, mealPeriod: 'dinner', specialEvent: false });
+    const margin = r.predictedTurnMin * 0.10;
+    expect(r.confidenceInterval[0]).toBeCloseTo(r.predictedTurnMin - margin, 1);
+    expect(r.confidenceInterval[1]).toBeCloseTo(r.predictedTurnMin + margin, 1);
+  });
+
+  it('throws for partySize < 1', () => {
+    expect(() => turnTimePredictor({ partySize: 0, mealPeriod: 'dinner', specialEvent: false })).toThrow();
+  });
+});
+
+// ─── Receipt ─────────────────────────────────────────────────────────────────
+
+describe('buildRestaurantReceipt', () => {
+  it('plugin=restaurant and CAEL event correct', () => {
+    const menu = menuEngineering([{ id: 'burger', name: 'Burger', popularity: 100, contributionMargin: 8 }]);
+    const receipt = buildRestaurantReceipt({ menuEngineering: menu, converged: true });
+    expect(receipt.plugin).toBe('restaurant');
+    expect(receipt.cael.event).toBe('restaurant.operations_analysis');
+    expect(receipt.payloadHash).toBeTruthy();
+  });
+
+  it('accepted=true for efficient operation', () => {
+    const foodCost = foodCostAnalysis([{ item: 'drink', ingredientCostUSD: 1, sellingPriceUSD: 8, unitsSold: 100 }]);
+    const receipt = buildRestaurantReceipt({ foodCost, converged: true });
+    expect(receipt.acceptance.accepted).toBe(true);
+  });
+
+  it('accepted=false when food cost over target', () => {
+    const foodCost = foodCostAnalysis(
+      [{ item: 'steak', ingredientCostUSD: 15, sellingPriceUSD: 35, unitsSold: 100 }],
+      0.30,  // 42.9% actual > 30% target
+    );
+    const receipt = buildRestaurantReceipt({ foodCost, converged: true });
+    expect(receipt.acceptance.accepted).toBe(false);
+    expect(receipt.acceptance.violations.length).toBeGreaterThan(0);
+  });
+
+  it('accepted=false when parties unassigned', () => {
+    const tables = [{ id: 'T1', capacity: 2, section: 'main', available: true }];
+    const parties = [{ id: 'Huge', partySize: 20, priorityGuest: false }];
+    const tableAssign = tableAssignment(tables, parties);
+    const receipt = buildRestaurantReceipt({ tableAssign, converged: true });
+    expect(receipt.acceptance.accepted).toBe(false);
+  });
+
+  it('uses provided runId', () => {
+    const receipt = buildRestaurantReceipt({ converged: true }, { runId: 'rst-run-007' });
+    expect(receipt.runId).toBe('rst-run-007');
+  });
+});

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from './restaurantsolver';
+export { createMenuHandler, type MenuConfig, type MenuItem } from './traits/MenuTrait';
+export { createOrderHandler, type OrderConfig, type OrderItem, type OrderStatus } from './traits/OrderTrait';
+export { createKitchenDisplayHandler, type KitchenDisplayConfig, type KitchenTicket } from './traits/KitchenDisplayTrait';
+export { createTableManagementHandler, type TableManagementConfig, type Table, type TableStatus } from './traits/TableManagementTrait';
+export * from './traits/types';
+
+import { createMenuHandler } from './traits/MenuTrait';
+import { createOrderHandler } from './traits/OrderTrait';
+import { createKitchenDisplayHandler } from './traits/KitchenDisplayTrait';
+import { createTableManagementHandler } from './traits/TableManagementTrait';
+
+export const pluginMeta = { name: '@holoscript/plugin-restaurant', version: '1.0.0', traits: ['menu', 'order', 'kitchen_display', 'table_management'] };
+export const traitHandlers = [createMenuHandler(), createOrderHandler(), createKitchenDisplayHandler(), createTableManagementHandler()];

package/src/restaurantsolver.ts

@@ -0,0 +1,350 @@
+/**
+ * Restaurant operations solvers — restaurant-plugin
+ *
+ * Implements:
+ *  - Table assignment optimizer (bin-packing / best-fit-decreasing)
+ *  - Kitchen queue scheduler (Shortest Job First + priority)
+ *  - Menu engineering matrix (Star/Plow-horse/Puzzle/Dog — Kasavana & Smith 1982)
+ *  - Food cost optimizer (target cost % → price calculation)
+ *  - Turn time predictor (regression on party size + meal period)
+ *  - Seating utilization metrics
+ *
+ * References:
+ *  - Kasavana M, Smith D (1982) Menu Engineering. Hospitality Publications.
+ *  - Siguaw J, Enz C (1999) Cornell Hotel and Restaurant Admin. Quarterly 40(6).
+ *  - National Restaurant Association — FoodCost % standard 28-32%
+ */
+
+import { buildDomainSimulationReceipt, type DomainSimulationReceipt } from '@holoscript/core';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface RestaurantTable {
+  id: string;
+  capacity: number;
+  section: string;
+  available: boolean;
+}
+
+export interface PartyRequest {
+  id: string;
+  partySize: number;
+  preferredSection?: string;
+  priorityGuest: boolean;
+}
+
+export interface TableAssignmentResult {
+  assignments: Array<{
+    partyId: string;
+    tableId: string;
+    tableCapacity: number;
+    partySize: number;
+    utilization: number;
+    sectionMatch: boolean;
+  }>;
+  unassigned: string[];
+  overallUtilization: number;
+}
+
+export interface KitchenTicket {
+  id: string;
+  /** Estimated cook time minutes */
+  estimatedMinutes: number;
+  /** 1=fire immediately (rush), 2=normal, 3=can-wait */
+  priority: 1 | 2 | 3;
+  /** Table/order id */
+  tableId: string;
+  items: string[];
+}
+
+export interface KitchenQueueResult {
+  sequence: Array<{
+    ticketId: string;
+    startMin: number;
+    endMin: number;
+    tableId: string;
+  }>;
+  makespan: number;  // total completion time minutes
+  avgWaitMin: number;
+  avgFlowMin: number;
+}
+
+export interface MenuItem {
+  id: string;
+  name: string;
+  /** Average monthly units sold */
+  popularity: number;
+  /** Contribution margin = price − variable cost */
+  contributionMargin: number;
+}
+
+export type MenuCategory = 'star' | 'plow-horse' | 'puzzle' | 'dog';
+
+export interface MenuEngineeringResult {
+  items: Array<{
+    id: string;
+    name: string;
+    popularity: number;
+    contributionMargin: number;
+    popularityIndex: number;   // vs average popularity
+    marginIndex: number;       // vs average margin
+    category: MenuCategory;
+  }>;
+  averagePopularity: number;
+  averageMargin: number;
+  categoryCount: Record<MenuCategory, number>;
+}
+
+export interface FoodCostLine {
+  item: string;
+  ingredientCostUSD: number;
+  sellingPriceUSD: number;
+  unitsSold: number;
+}
+
+export interface FoodCostResult {
+  lines: Array<{
+    item: string;
+    ingredientCostUSD: number;
+    sellingPriceUSD: number;
+    unitsSold: number;
+    foodCostPct: number;
+    revenueUSD: number;
+    costUSD: number;
+    grossProfitUSD: number;
+  }>;
+  totalRevenue: number;
+  totalCost: number;
+  blendedFoodCostPct: number;
+  targetFoodCostPct: number;
+  variance: number;
+  overTarget: boolean;
+}
+
+export interface RestaurantReceiptOptions {
+  runId?: string;
+}
+
+// ─── Table Assignment (Best-Fit-Decreasing bin-packing) ───────────────────────
+
+/**
+ * Assign parties to tables using best-fit strategy:
+ * priority guests first, then largest parties first,
+ * assign to smallest available table that fits.
+ */
+export function tableAssignment(
+  tables: RestaurantTable[],
+  parties: PartyRequest[],
+): TableAssignmentResult {
+  if (tables.length === 0) throw new Error('No tables available');
+  if (parties.length === 0) throw new Error('No parties to seat');
+
+  const available = tables.map(t => ({ ...t }));
+  const sorted = [...parties].sort((a, b) => {
+    // Priority guests first, then by descending party size
+    if (a.priorityGuest !== b.priorityGuest) return a.priorityGuest ? -1 : 1;
+    return b.partySize - a.partySize;
+  });
+
+  const assignments: TableAssignmentResult['assignments'] = [];
+  const unassigned: string[] = [];
+
+  for (const party of sorted) {
+    // Best-fit: find smallest available table that fits
+    const candidates = available.filter(t => t.available && t.capacity >= party.partySize);
+    if (candidates.length === 0) { unassigned.push(party.id); continue; }
+
+    // Prefer preferred section, then smallest-capacity table
+    const sectionMatch = candidates.filter(t => !party.preferredSection || t.section === party.preferredSection);
+    const pool = sectionMatch.length > 0 ? sectionMatch : candidates;
+    pool.sort((a, b) => a.capacity - b.capacity);
+    const table = pool[0];
+
+    table.available = false;
+    assignments.push({
+      partyId: party.id,
+      tableId: table.id,
+      tableCapacity: table.capacity,
+      partySize: party.partySize,
+      utilization: party.partySize / table.capacity,
+      sectionMatch: !party.preferredSection || table.section === party.preferredSection,
+    });
+  }
+
+  const seatedSeats = assignments.reduce((a, x) => a + x.partySize, 0);
+  const totalSeats = tables.reduce((a, t) => a + t.capacity, 0);
+
+  return { assignments, unassigned, overallUtilization: totalSeats > 0 ? seatedSeats / totalSeats : 0 };
+}
+
+// ─── Kitchen Queue (SJF with priority) ───────────────────────────────────────
+
+/**
+ * Schedule kitchen tickets using priority-ordered SJF.
+ * Priority 1 always goes first, then within each priority level: shortest job.
+ */
+export function kitchenQueueScheduler(tickets: KitchenTicket[]): KitchenQueueResult {
+  if (tickets.length === 0) throw new Error('No kitchen tickets');
+
+  // Sort: priority level first, then shortest cook time
+  const sorted = [...tickets].sort((a, b) =>
+    a.priority !== b.priority ? a.priority - b.priority : a.estimatedMinutes - b.estimatedMinutes,
+  );
+
+  const sequence: KitchenQueueResult['sequence'] = [];
+  let time = 0;
+  let totalWait = 0, totalFlow = 0;
+
+  for (const ticket of sorted) {
+    const start = time;
+    const end = time + ticket.estimatedMinutes;
+    sequence.push({ ticketId: ticket.id, startMin: start, endMin: end, tableId: ticket.tableId });
+    totalWait += start;
+    totalFlow += end;
+    time = end;
+  }
+
+  return {
+    sequence,
+    makespan: time,
+    avgWaitMin: totalWait / tickets.length,
+    avgFlowMin: totalFlow / tickets.length,
+  };
+}
+
+// ─── Menu Engineering Matrix ──────────────────────────────────────────────────
+
+/**
+ * Kasavana & Smith (1982) Menu Engineering:
+ * - Star:        high popularity, high margin
+ * - Plow-horse:  high popularity, low margin
+ * - Puzzle:      low popularity, high margin
+ * - Dog:         low popularity, low margin
+ */
+export function menuEngineering(items: MenuItem[]): MenuEngineeringResult {
+  if (items.length === 0) throw new Error('No menu items');
+
+  const avgPopularity = items.reduce((s, i) => s + i.popularity, 0) / items.length;
+  const avgMargin     = items.reduce((s, i) => s + i.contributionMargin, 0) / items.length;
+
+  const analyzed = items.map(item => {
+    const popularityIndex = item.popularity / avgPopularity;
+    const marginIndex     = item.contributionMargin / avgMargin;
+    const category: MenuCategory =
+      popularityIndex >= 1 && marginIndex >= 1 ? 'star' :
+      popularityIndex >= 1 && marginIndex <  1 ? 'plow-horse' :
+      popularityIndex <  1 && marginIndex >= 1 ? 'puzzle' : 'dog';
+    return { id: item.id, name: item.name, popularity: item.popularity, contributionMargin: item.contributionMargin, popularityIndex, marginIndex, category };
+  });
+
+  const categoryCount: Record<MenuCategory, number> = { star: 0, 'plow-horse': 0, puzzle: 0, dog: 0 };
+  for (const a of analyzed) categoryCount[a.category]++;
+
+  return { items: analyzed, averagePopularity: avgPopularity, averageMargin: avgMargin, categoryCount };
+}
+
+// ─── Food Cost Optimizer ──────────────────────────────────────────────────────
+
+export function foodCostAnalysis(
+  lines: FoodCostLine[],
+  targetFoodCostPct = 0.30,
+): FoodCostResult {
+  if (lines.length === 0) throw new Error('No food cost lines');
+  if (targetFoodCostPct <= 0 || targetFoodCostPct >= 1) throw new Error('targetFoodCostPct must be in (0,1)');
+
+  const analyzed = lines.map(l => {
+    const revenueUSD    = l.sellingPriceUSD * l.unitsSold;
+    const costUSD       = l.ingredientCostUSD * l.unitsSold;
+    const grossProfitUSD = revenueUSD - costUSD;
+    const foodCostPct   = l.sellingPriceUSD > 0 ? l.ingredientCostUSD / l.sellingPriceUSD : 0;
+    return { ...l, foodCostPct, revenueUSD, costUSD, grossProfitUSD };
+  });
+
+  const totalRevenue = analyzed.reduce((s, l) => s + l.revenueUSD, 0);
+  const totalCost    = analyzed.reduce((s, l) => s + l.costUSD,    0);
+  const blendedFoodCostPct = totalRevenue > 0 ? totalCost / totalRevenue : 0;
+  const variance = blendedFoodCostPct - targetFoodCostPct;
+
+  return { lines: analyzed, totalRevenue, totalCost, blendedFoodCostPct, targetFoodCostPct, variance, overTarget: variance > 0 };
+}
+
+// ─── Turn Time Predictor ──────────────────────────────────────────────────────
+
+export interface TurnTimePredictorInput {
+  partySize: number;
+  /** 'lunch' | 'dinner' | 'brunch' */
+  mealPeriod: 'lunch' | 'dinner' | 'brunch';
+  /** Is the party a special event (birthday, anniversary)? */
+  specialEvent: boolean;
+}
+
+export interface TurnTimeResult {
+  /** Predicted table turn time in minutes */
+  predictedTurnMin: number;
+  /** Tables turned per evening (8hr dinner service) */
+  turnsPerEvening: number;
+  /** 95% confidence interval [low, high] minutes */
+  confidenceInterval: [number, number];
+}
+
+/**
+ * Linear regression model for turn time:
+ * base = (lunch=45, dinner=75, brunch=55) + 5×partySize + 15×specialEvent
+ */
+export function turnTimePredictor(input: TurnTimePredictorInput): TurnTimeResult {
+  if (input.partySize < 1) throw new Error('partySize must be ≥ 1');
+
+  const periodBase = input.mealPeriod === 'lunch' ? 45 : input.mealPeriod === 'brunch' ? 55 : 75;
+  const predictedTurnMin = periodBase + 5 * input.partySize + (input.specialEvent ? 15 : 0);
+  const turnsPerEvening = 480 / predictedTurnMin;  // 8hr service / turn time
+
+  // ±10% CI (simplified residual from regression)
+  const margin = predictedTurnMin * 0.10;
+  const confidenceInterval: [number, number] = [predictedTurnMin - margin, predictedTurnMin + margin];
+
+  return { predictedTurnMin, turnsPerEvening, confidenceInterval };
+}
+
+// ─── Receipt ──────────────────────────────────────────────────────────────────
+
+export interface RestaurantAnalysisResult {
+  tableAssign?: TableAssignmentResult;
+  queue?: KitchenQueueResult;
+  menuEngineering?: MenuEngineeringResult;
+  foodCost?: FoodCostResult;
+  turnTime?: TurnTimeResult;
+  converged: true;
+}
+
+export function buildRestaurantReceipt(
+  result: RestaurantAnalysisResult,
+  options?: RestaurantReceiptOptions,
+): DomainSimulationReceipt {
+  const violations: Array<{ criterion: string; message: string }> = [];
+
+  if (result.tableAssign && result.tableAssign.unassigned.length > 0) {
+    violations.push({ criterion: 'unseated_parties', message: `${result.tableAssign.unassigned.length} party/parties could not be seated` });
+  }
+  if (result.foodCost?.overTarget) {
+    violations.push({ criterion: 'food_cost', message: `Blended food cost ${(result.foodCost.blendedFoodCostPct * 100).toFixed(1)}% exceeds ${(result.foodCost.targetFoodCostPct * 100).toFixed(0)}% target` });
+  }
+  if (result.queue && result.queue.makespan > 60) {
+    violations.push({ criterion: 'kitchen_throughput', message: `Kitchen makespan ${result.queue.makespan.toFixed(0)} min exceeds 60 min service standard` });
+  }
+
+  return buildDomainSimulationReceipt({
+    plugin: 'restaurant',
+    pluginVersion: '1.0.0',
+    runId: options?.runId ?? `rst-${Date.now().toString(36)}`,
+    solverConfig: { solverType: 'restaurant-operations', scale: 'shift' },
+    resultSummary: {
+      seatingUtilization: result.tableAssign?.overallUtilization ?? null,
+      unseatatedParties: result.tableAssign?.unassigned.length ?? null,
+      kitchenMakespan: result.queue?.makespan ?? null,
+      blendedFoodCostPct: result.foodCost?.blendedFoodCostPct ?? null,
+      menuStarCount: result.menuEngineering?.categoryCount.star ?? null,
+    },
+    cael: { version: 'cael.v1', event: 'restaurant.operations_analysis', solverType: 'restaurant.table-assignment' },
+    acceptance: { accepted: violations.length === 0, violations },
+  });
+}

package/src/traits/KitchenDisplayTrait.ts

@@ -0,0 +1,33 @@
+/** @kitchen_display Trait — Kitchen display system (KDS). @trait kitchen_display */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface KitchenTicket { orderId: string; items: string[]; priority: 'normal' | 'rush' | 'vip'; receivedAt: number; startedAt: number | null; completedAt: number | null; }
+export interface KitchenDisplayConfig { stations: string[]; maxActiveTickets: number; targetPrepTimeMin: number; }
+export interface KitchenDisplayState { activeTickets: KitchenTicket[]; completedToday: number; avgPrepTimeMin: number; }
+
+const defaultConfig: KitchenDisplayConfig = { stations: ['grill', 'salad', 'dessert'], maxActiveTickets: 20, targetPrepTimeMin: 15 };
+
+export function createKitchenDisplayHandler(): TraitHandler<KitchenDisplayConfig> {
+  return { name: 'kitchen_display', defaultConfig,
+    onAttach(n: HSPlusNode, _c: KitchenDisplayConfig, ctx: TraitContext) { n.__kdsState = { activeTickets: [], completedToday: 0, avgPrepTimeMin: 0 }; ctx.emit?.('kds:online'); },
+    onDetach(n: HSPlusNode, _c: KitchenDisplayConfig, ctx: TraitContext) { delete n.__kdsState; ctx.emit?.('kds:offline'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: KitchenDisplayConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__kdsState as KitchenDisplayState | undefined; if (!s) return;
+      if (e.type === 'kds:new_ticket') {
+        const ticket: KitchenTicket = { orderId: (e.payload?.orderId as string) ?? '', items: (e.payload?.items as string[]) ?? [], priority: (e.payload?.priority as KitchenTicket['priority']) ?? 'normal', receivedAt: Date.now(), startedAt: null, completedAt: null };
+        if (s.activeTickets.length < c.maxActiveTickets) { s.activeTickets.push(ticket); ctx.emit?.('kds:ticket_received', { orderId: ticket.orderId }); }
+        else ctx.emit?.('kds:queue_full');
+      }
+      if (e.type === 'kds:complete_ticket') {
+        const idx = s.activeTickets.findIndex(t => t.orderId === (e.payload?.orderId as string));
+        if (idx >= 0) { const t = s.activeTickets.splice(idx, 1)[0]; t.completedAt = Date.now(); s.completedToday++;
+          const prepTime = (t.completedAt - t.receivedAt) / 60000;
+          s.avgPrepTimeMin = (s.avgPrepTimeMin * (s.completedToday - 1) + prepTime) / s.completedToday;
+          ctx.emit?.('kds:ticket_done', { orderId: t.orderId, prepMin: Math.round(prepTime) });
+          if (prepTime > c.targetPrepTimeMin) ctx.emit?.('kds:slow_ticket', { orderId: t.orderId, prepMin: Math.round(prepTime) });
+        }
+      }
+    },
+  };
+}

package/src/traits/MenuTrait.ts

@@ -0,0 +1,19 @@
+/** @menu Trait — Restaurant menu management. @trait menu */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface MenuItem { id: string; name: string; price: number; category: string; description: string; allergens: string[]; calories?: number; available: boolean; }
+export interface MenuConfig { items: MenuItem[]; currency: string; taxRate: number; serviceChargePercent: number; }
+
+const defaultConfig: MenuConfig = { items: [], currency: 'USD', taxRate: 0.08, serviceChargePercent: 0 };
+
+export function createMenuHandler(): TraitHandler<MenuConfig> {
+  return { name: 'menu', defaultConfig,
+    onAttach(n: HSPlusNode, c: MenuConfig, ctx: TraitContext) { n.__menuState = { availableItems: c.items.filter(i => i.available).length, categories: [...new Set(c.items.map(i => i.category))] }; ctx.emit?.('menu:loaded', { items: c.items.length }); },
+    onDetach(n: HSPlusNode, _c: MenuConfig, ctx: TraitContext) { delete n.__menuState; ctx.emit?.('menu:unloaded'); },
+    onUpdate() {},
+    onEvent(_n: HSPlusNode, c: MenuConfig, ctx: TraitContext, e: TraitEvent) {
+      if (e.type === 'menu:search') { const q = ((e.payload?.query as string) ?? '').toLowerCase(); const results = c.items.filter(i => i.available && (i.name.toLowerCase().includes(q) || i.category.toLowerCase().includes(q))); ctx.emit?.('menu:results', { count: results.length, items: results.map(r => ({ id: r.id, name: r.name, price: r.price })) }); }
+      if (e.type === 'menu:toggle_availability') { const item = c.items.find(i => i.id === (e.payload?.itemId as string)); if (item) { item.available = !item.available; ctx.emit?.('menu:availability_changed', { item: item.name, available: item.available }); } }
+    },
+  };
+}

package/src/traits/OrderTrait.ts

@@ -0,0 +1,27 @@
+/** @order Trait — Customer order lifecycle. @trait order */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type OrderStatus = 'new' | 'confirmed' | 'preparing' | 'ready' | 'served' | 'paid' | 'cancelled';
+export interface OrderItem { menuItemId: string; name: string; quantity: number; price: number; modifications?: string[]; }
+export interface OrderConfig { tableNumber: number; items: OrderItem[]; orderType: 'dine_in' | 'takeout' | 'delivery'; }
+export interface OrderState { status: OrderStatus; orderId: string; subtotal: number; createdAt: number; }
+
+const defaultConfig: OrderConfig = { tableNumber: 0, items: [], orderType: 'dine_in' };
+
+export function createOrderHandler(): TraitHandler<OrderConfig> {
+  return { name: 'order', defaultConfig,
+    onAttach(n: HSPlusNode, c: OrderConfig, ctx: TraitContext) {
+      const subtotal = c.items.reduce((s, i) => s + i.price * i.quantity, 0);
+      n.__orderState = { status: 'new' as OrderStatus, orderId: `ORD-${Date.now()}`, subtotal, createdAt: Date.now() };
+      ctx.emit?.('order:created', { table: c.tableNumber, items: c.items.length, subtotal });
+    },
+    onDetach(n: HSPlusNode, _c: OrderConfig, ctx: TraitContext) { delete n.__orderState; ctx.emit?.('order:removed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, _c: OrderConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__orderState as OrderState | undefined; if (!s) return;
+      const flow: OrderStatus[] = ['new','confirmed','preparing','ready','served','paid'];
+      if (e.type === 'order:advance') { const i = flow.indexOf(s.status); if (i < flow.length - 1) { s.status = flow[i+1]; ctx.emit?.('order:status_changed', { status: s.status, orderId: s.orderId }); } }
+      if (e.type === 'order:cancel') { s.status = 'cancelled'; ctx.emit?.('order:cancelled', { orderId: s.orderId }); }
+    },
+  };
+}

package/src/traits/TableManagementTrait.ts

@@ -0,0 +1,35 @@
+/** @table_management Trait — Restaurant table/seating management. @trait table_management */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type TableStatus = 'available' | 'reserved' | 'occupied' | 'cleaning' | 'blocked';
+export interface Table { id: string; seats: number; section: string; status: TableStatus; partySize?: number; seatedAt?: number; }
+export interface TableManagementConfig { tables: Table[]; turnoverTargetMin: number; waitlistEnabled: boolean; }
+export interface TableManagementState { availableCount: number; occupiedCount: number; waitlistSize: number; avgTurnoverMin: number; }
+
+const defaultConfig: TableManagementConfig = { tables: [], turnoverTargetMin: 60, waitlistEnabled: true };
+
+export function createTableManagementHandler(): TraitHandler<TableManagementConfig> {
+  return { name: 'table_management', defaultConfig,
+    onAttach(n: HSPlusNode, c: TableManagementConfig, ctx: TraitContext) {
+      const avail = c.tables.filter(t => t.status === 'available').length;
+      n.__tableState = { availableCount: avail, occupiedCount: c.tables.length - avail, waitlistSize: 0, avgTurnoverMin: 0 };
+      ctx.emit?.('tables:initialized', { total: c.tables.length, available: avail });
+    },
+    onDetach(n: HSPlusNode, _c: TableManagementConfig, ctx: TraitContext) { delete n.__tableState; ctx.emit?.('tables:closed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: TableManagementConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__tableState as TableManagementState | undefined; if (!s) return;
+      if (e.type === 'tables:seat') {
+        const tableId = e.payload?.tableId as string; const party = (e.payload?.partySize as number) ?? 1;
+        const table = c.tables.find(t => t.id === tableId);
+        if (table && table.status === 'available') { table.status = 'occupied'; table.partySize = party; table.seatedAt = Date.now(); s.availableCount--; s.occupiedCount++; ctx.emit?.('tables:seated', { table: tableId, party }); }
+      }
+      if (e.type === 'tables:clear') {
+        const tableId = e.payload?.tableId as string;
+        const table = c.tables.find(t => t.id === tableId);
+        if (table && table.status === 'occupied') { table.status = 'available'; s.availableCount++; s.occupiedCount--; ctx.emit?.('tables:cleared', { table: tableId }); }
+      }
+      if (e.type === 'tables:add_waitlist') { s.waitlistSize++; ctx.emit?.('tables:waitlist_updated', { size: s.waitlistSize }); }
+    },
+  };
+}

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,
+  },
+});