suaveplan/openspec/archive/2026-05-17-add-booking/proposal.md

# Add @suaveplan/booking — universal JSON-configurable booking engine

**Package**: `@suaveplan/booking`
**Status**: PROPOSED
**Type**: migration (upstream `../suaveplan/packages/security/booking`)

- **Design**: ./design.md
- **Spec delta**: ./specs/booking/spec.md

## Why

`STATUS.md` lists `@suaveplan/booking` as Pending. The upstream package is a substantial, universal-tier, runtime-pure library (51 source files across 11 feature groups, 27 test files, ~99% upstream coverage) that owns a problem genesis currently has no answer for: a JSON-driven booking engine that runs identically in Bun, Node, browsers, and Web Workers and covers six distinct domains (seats, accommodation, appointments, resources, activities, transport) through a single pipeline (availability → conflict detection → pricing → rules → state machine → events). No genesis package covers this surface today, and a string of pending downstream packages (`@suaveplan/r3f-booking`, the `api-plugin-bank`/`api-plugin-banking` plugins, future commerce-tier UIs) depend on the `BookingSystemConfig`, `Bookable`, `Booking`, and `BookingEngine` contracts. Migrating it now unblocks every booking-aware package downstream.

The migration upgrades the package to genesis quality: every plain `throw new Error(...)` becomes a `BookingError` extending `SuaveplanError` with a stable `BOOKING.*` code registry; the inline `@suaveplan/events/hooks` dependency (not migrated on genesis) is replaced by a small in-package `Hooks<TMap>` implementation that ships under `src/hooks/` with the same public surface the upstream engine consumed; subpath exports become exhaustive (one per public module) so consumers tree-shake; every implementation file gets a sibling `.md`; coverage moves from upstream's ~99% to 100/100/100/100; the package starts at `0.1.0`. The enterprise audit (`../suaveplan/enterprise/booking.md`) lists ambitious additions (property-based tests, full OTel observability, persistence-tier integration, `AbortSignal` propagation, feature flags) — the typed-error upgrade and the in-package `Hooks` are in scope here; the other audit items are explicitly deferred to follow-up changes.

## What changes

- ADDED: `BookingEngine<TBookableMeta, TBookingMeta>` and `createBookingEngine` — the pipeline orchestrator with `configure`, `registerBookable`, `getBookable`, `listBookables`, `checkAvailability`, `getAvailableSlots`, `createHold`, `getHold`, `confirmBooking`, `cancelBooking`, `modifyBooking`, `calculatePrice`, `joinWaitlist`, `on`, `off`, `getBooking`, and the `bookingHooks` getter exposing the in-package `Hooks<BookingHookMap>`.
- ADDED: `StateMachine` and `createStateMachine` — configurable status-transition state machine with `canTransition`, `getAvailableTransitions`, `getAutoTransitions`, `getAllStatuses`. `TransitionRequest`/`TransitionResult` types preserved.
- ADDED: `EventBus` and `createEventBus` — typed booking event bus with `on`/`off`/`emit`/`clear`/`listenerCount`/`eventTypes`.
- ADDED: `Hooks<TMap extends HookMap>` — in-package data-transform pipeline (replaces the upstream `@suaveplan/events/hooks` dependency that does not exist on genesis). Public surface preserves `hook`/`unhook`/`unhookAll`/`applyHooks`/`applyHooksAsync`/`applyHooksWithResult`/`hookNames`/`hookCount`/`hasHook`. Types `HookMap`/`HookContext`/`HookHandler`/`HookHandlerOptions`/`HookResult`/`RegisteredHook` re-exported.
- ADDED: Temporal — `windowsOverlap`, `windowsOverlapWithBuffer`, `mergeWindows`, `splitWindow`, `windowDurationMs`, `windowContains`, `createWindow`, `isValidWindow`, `windowsAdjacent`; `expandRecurrence`, `isRecurring`, `createRecurrenceRule`; `generateTimeSlots`, `generateDailySlots`, `filterAvailableSlots`, `reduceSlotCapacity`.
- ADDED: Conflict detection — pluggable `registerDetector`/`detectConflicts`/`getRegisteredModes`/`clearDetectorRegistry` registry with four built-ins (`detectExactMatch`, `detectRangeOverlap`, `detectSlotCapacity`, `detectProviderOverlap`). `OverlapResult`/`ConflictDetectionMode`/`ConflictDetectorFn`/`CapacityContext` types exported.
- ADDED: Pricing — `calculatePrice`, `calculateBasePrice`, `applyTiers`, `applyModifiers`, `calculateTax`; `applySeasonalRate`, `calculateSeasonalMultiplier`, `findApplicableRates`, `getSeasonName`; `applyDynamicPricing`, `calculateDynamicMultiplier`, `createDynamicContext`, `findApplicableDynamicRules`. `PriceCalculationContext`/`PricingPipelineStep`/`DynamicPricingContext` types exported.
- ADDED: Rules — `evaluateRule`, `evaluateRules` evaluator with 11 operators (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `between`, `regex`, default deny); built-in condition factories `createMinDurationCondition`, `createMaxDurationCondition`, `createAdvanceBookingCondition`, `createQuantityRangeCondition`, `createAttributeCondition`, `createWeekendCondition`, `createStatusCondition`, `createCustomerLimitCondition`. `EvaluationContext`/`ConditionEvaluatorFn` types exported.
- ADDED: Availability — pluggable `registerAvailabilityStrategy`/`resolveAvailability`/`getRegisteredStrategies`/`clearStrategyRegistry` with three built-ins (`exactMatchStrategy`, `rangeOverlapStrategy`, `capacityStrategy`). `AvailabilityStrategyFn`/`SlotAvailability` types exported.
- ADDED: Domain presets — `createBaseConfig`, `createSeatConfig`, `createAccommodationConfig`, `createAppointmentConfig`, `createResourceConfig`, `createActivityConfig`, `createTransportConfig`. Domain meta types `SeatBookableMeta`, `AccommodationBookableMeta`, `AppointmentBookableMeta`, `ResourceBookableMeta`, `ActivityBookableMeta`, `TransportBookableMeta` exported.
- ADDED: Schemas — `bookableSchema`, `bookingSchema`, `bookingRequestSchema`, `holdRequestSchema`, `timeWindowSchema`, `validateBookable`, `validateBooking`, `validateBookingRequest`; `bookingSystemConfigSchema`, `validateConfig`, `safeValidateConfig`.
- ADDED: Utils — `parseDurationMs` (ISO-8601 duration), `clampNumber`, `deepFreeze`, `generateId`, `isNonEmptyString`.
- ADDED: Constants — `DEFAULT_HOLD_DURATION_MINUTES`, `DEFAULT_MAX_HOLD_DURATION_MINUTES`, `DEFAULT_MAX_ADVANCE_DAYS`, `DEFAULT_SCHEMA_VERSION`, `DEFAULT_CURRENCY`, `DEFAULT_TAX_STRATEGY`, `DEFAULT_ROUNDING_MODE`, `DEFAULT_ROUNDING_PRECISION`, `DEFAULT_AVAILABILITY_REFRESH_MS`, `DEFAULT_CACHE_TTL_MS`, `DEFAULT_SLOT_DURATION_MS`, `DEFAULT_LOCALE`, `DEFAULT_DATE_FORMAT`, `DEFAULT_TIME_FORMAT`, `DEFAULT_FIRST_DAY_OF_WEEK`.
- ADDED: `BOOKING_CODES` registry via `defineCodes("BOOKING", [...])` and `BookingError extends SuaveplanError<BookingErrorCode>` carrying optional `bookingId`/`holdId`/`mode`/`strategy` discriminants. Codes: `ENGINE_NOT_CONFIGURED`, `BOOKING_NOT_FOUND`, `BOOKING_CONFLICT`, `TRANSITION_NOT_ALLOWED`, `UNKNOWN_CONFLICT_MODE`, `UNKNOWN_AVAILABILITY_STRATEGY`, `HOOK_RETURNED_PROMISE_IN_SYNC`.
- ADDED: All public types — `Bookable`, `BookableId`, `BookableQuery`, `BookableQueryResult`, `Booking`, `BookingId`, `BookingModification`, `BookingRequest`, `CancellationResult`, `CancellationTerms`, `HoldRequest`, `WaitlistRequest`, `BookingHold`, `CapacityPool`, `OverbookingStrategy`, `WaitlistEntry`, `BookingSystemConfig` and every sub-type (`TenantConfig`, `EngineConfig`, `StrategyRegistration`, `HoldConfig`, `WaitlistConfig`, `NotificationConfig`, `NotificationTrigger`, `StatusTransition`, `AttributeDefinition`, `BookableTypeDefinition`, `LayoutConfig`, `LocaleConfig`, `AvailabilityConfig`, `ConflictDetectorConfig`, `PricingEngineConfig`), `BookingEvent`, `BookingEventHandler`, `BookingEventType`, `EventSubscription`, `LayoutColorScheme`, `LayoutNode`, `NodePosition`, `BookingPrice`, `DynamicPricingRule`, `PriceModifier`, `PriceRule`, `PriceTier`, `SeasonalRate`, `BookingRule`, `RuleAction`, `RuleCondition`, `RuleEvaluationResult`, `RecurrenceRule`, `TimeSlot`, `TimeWindow`, `BookingHookMap`, `BookingCreatingHookData`, `BookingCancellingHookData`, `BookingCreatingHandler`, `BookingCancellingHandler`, `AvailabilityQuery`, `AvailabilityResult`, `BookingEngineInterface`, `ConflictResult`, `PriceCalculationRequest`, `TransitionRequest`, `TransitionResult`.
- ADDED: Subpath exports per feature module (29 subpaths). Tree-shakeable.

## Out of scope

- **Property-based tests via fast-check.** Listed in the enterprise audit. The upstream test suite covers every operator, allocation invariant, conflict mode, and pipeline branch at ~99% coverage with example-based tests; reaching 100% on the migrated surface is the gate, and fast-check will be folded in once the deterministic suite is green. Reason: deterministic suite hits the 100% gate first; property tests are an additive quality layer, not a parity requirement.
- **OpenTelemetry observability surface (spans/counters/histograms on every public entry point).** Listed in the enterprise audit. Reason: the universal-tier package has no in-process observability today, and adding it requires designing a `LoggerLike`/`MeterLike` dependency injection contract that the upstream package does not have. Belongs to a follow-up `add-booking-observability` change after the enterprise observability story for universal-tier packages stabilises.
- **`AbortSignal` propagation through every async path.** The package surface is currently synchronous (the only async path is `Hooks.applyHooksAsync`); upstream does not thread `AbortSignal`. Adding cancellation to a sync surface requires public-API changes outside the parity scope. Reason: behaviour-preserving migration; cancellation is a separate concern.
- **Persistence-tier integration (`StorageLike`/`DatabaseLike` backed bookable+booking repositories).** Upstream uses an in-memory `Map` for both. Reason: the parity contract is the in-memory engine; persistence belongs to `@suaveplan/booking-persistence` follow-up that consumes this package.
- **Feature-flag-gated rollouts of risky new behaviours.** Listed in the enterprise audit. Reason: the migration adds no new risky behaviours; the typed-error replacement is a strict additive narrowing.
- **i18n keys for error messages.** Errors currently carry English strings. Reason: `@suaveplan/error` exposes an i18n resolver hook; wiring booking-specific message keys is a follow-up when the genesis i18n catalog for booking lands.
- **Migration to `@suaveplan/events/hooks` once that subpath ships.** Genesis `@suaveplan/events` does not yet expose `/hooks` or `/hooks.types`. The migration ships a small `Hooks<TMap>` implementation inside `src/hooks/` with the same public API; once events ships the hooks subpath, a follow-up change can replace the inline impl with the dependency import without breaking consumers. Reason: dependency unavailability — see §0b parity rule.
- **Benchmarks via mitata.** §9 of CLAUDE.md asks for `src/__benchmarks__/`. Reason: deferred — coverage and gates are the primary acceptance criteria; benchmarks land in a follow-up alongside the observability surface.
- **`@suaveplan/schema-registry` integration for versioned config schemas.** Listed in the enterprise audit. Reason: schema-registry consumers don't exist on genesis yet for this package; will land when first network-tier consumer surfaces.

## Source mapping

This change derives from `../suaveplan/enterprise/booking.md` and the upstream source at `../suaveplan/packages/security/booking/src/`.

| Requirement | Source lines | Notes |
|---|---|---|
| Universal-tier purity (zero browser/Node/React deps) | enterprise/booking.md L37; CLAUDE.md cross-cutting | Reinforced here |
| Pluggable booking engine pipeline (availability → conflict → pricing → rules → state machine → events) | upstream `src/core/engine/engine.ts` L1-L441 | Verbatim behaviour, typed errors |
| Configurable status state machine | upstream `src/core/state-machine/state-machine.ts` L1-L98 | Verbatim |
| Typed booking event bus (pub/sub for 15 event types) | upstream `src/core/event-bus/event-bus.ts` L1-L96 | Verbatim |
| In-package `Hooks<TMap>` data-transform pipeline | upstream `src/types/booking-hooks.ts` + `@suaveplan/events/hooks` | Migration replaces external dep with in-package impl (see Out of Scope) |
| Temporal window operations (overlap, merge, split, duration, contains, adjacent, validity) | upstream `src/temporal/windows/windows.ts` L1-L125 | Verbatim |
| Recurrence rule expansion (daily/weekly/monthly/yearly + exceptions + days-of-week) | upstream `src/temporal/recurrence/recurrence.ts` L1-L100 | Verbatim |
| Time-slot generation (fixed interval + daily-window helpers + filtering + capacity reduction) | upstream `src/temporal/slots/slots.ts` L1-L94 | Verbatim |
| Pluggable conflict-detector registry with four built-in modes | upstream `src/conflict/detector/detector.ts` + `src/conflict/{exact-match,range-overlap,slot-capacity,provider-overlap}/*.ts` | Verbatim, typed errors |
| Price calculation pipeline (base → tiers → modifiers → tax → rounding) | upstream `src/pricing/calculator/calculator.ts` L1-L179 | Verbatim |
| Seasonal rate resolver (wrap-around year, multiplier, season name lookup) | upstream `src/pricing/seasonal/seasonal.ts` L1-L80 | Verbatim |
| Dynamic pricing rules (occupancy / advance days / demand score triggers) | upstream `src/pricing/dynamic/dynamic.ts` L1-L62 | Verbatim |
| Rule evaluator with 11 operators and condition aggregation logic (`all`/`any`) | upstream `src/rules/evaluator/evaluator.ts` L1-L153 | Verbatim |
| Condition factories (min/max duration, advance booking, quantity range, attribute, weekend, status, customer-limit) | upstream `src/rules/conditions/conditions.ts` L1-L103 | Verbatim |
| Pluggable availability strategy registry with three built-ins | upstream `src/availability/resolver/resolver.ts` + `src/availability/strategies/strategies.ts` | Verbatim, typed errors |
| Six domain presets returning fully populated `BookingSystemConfig` | upstream `src/domains/shared.ts` + `src/domains/{seats,accommodation,appointments,resources,activities,transport}/*.ts` | Verbatim — defaults preserved |
| Zod validation schemas (bookable, booking, booking request, hold request, time window, config) | upstream `src/schemas/booking.schema.ts` + `src/schemas/config.schema.ts` | Verbatim |
| Utility helpers (`parseDurationMs`, `clampNumber`, `deepFreeze`, `generateId`, `isNonEmptyString`) | upstream `src/utils/utils.ts` L1-L79 | Verbatim |
| Default constants (15 entries) | upstream `src/constants/index.ts` L1-L21 | Verbatim |
| Typed error hierarchy `BookingError` extending `SuaveplanError` with stable `BOOKING.*` codes | enterprise/booking.md L43, L61 (cross-cutting "structured errors") | Migration upgrade: replaces every `throw new Error(...)` |
| Subpath exports per public module (29 subpaths) | enterprise/booking.md L37 (tree-shakeable) | Expanded from upstream's 28 |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| 100% test coverage (istanbul, all four axes) | Genesis-wide policy (CLAUDE.md §7) — upstream was at ~99% |
| Sibling `.md` per implementation file (≥200 words, basic + advanced examples) | Genesis-wide policy (CLAUDE.md §4) — upstream had partial docs |
| Test files import runner primitives from `@suaveplan/testing/runner` | Genesis-wide policy (AGENTS.md §7) — upstream imported `vitest` directly |
| Explicit named re-exports in every feature-module barrel (no `export *`) | Genesis-wide policy (AGENTS.md §6a) |
| Package version starts at `0.1.0` | Genesis-wide policy (CLAUDE.md "Editing") — upstream was `1.0.6` |
| In-package `Hooks<TMap>` replaces external `@suaveplan/events/hooks` import | Dependency not migrated on genesis (§0b) — see Out of Scope for the migration path |

### Parity Checklist

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| `BookingEngine` full surface (configure, registerBookable, getBookable, listBookables, checkAvailability, getAvailableSlots, createHold, getHold, confirmBooking, cancelBooking, modifyBooking, calculatePrice, joinWaitlist, on, off, getBooking, bookingHooks) | ✅ | ✅ | Verbatim |
| `StateMachine` full surface | ✅ | ✅ | Verbatim |
| `EventBus` full surface (15 event types) | ✅ | ✅ | Verbatim |
| Temporal: windows / recurrence / slots (16 functions total) | ✅ | ✅ | Verbatim |
| Conflict: 4 built-in detectors + pluggable registry | ✅ | ⬆️ Enhanced | `Unknown conflict detection mode` raises `BookingError({ code: BOOKING.UNKNOWN_CONFLICT_MODE })` |
| Pricing: calculator + seasonal + dynamic (15 functions total) | ✅ | ✅ | Verbatim |
| Rules: evaluator (11 operators) + 8 condition factories | ✅ | ✅ | Verbatim |
| Availability: 3 built-in strategies + pluggable registry | ✅ | ⬆️ Enhanced | `Unknown availability strategy` raises `BookingError({ code: BOOKING.UNKNOWN_AVAILABILITY_STRATEGY })` |
| Domain presets (seats / accommodation / appointments / resources / activities / transport + base) | ✅ | ✅ | Verbatim defaults |
| Zod schemas (bookable / booking / booking-request / hold-request / time-window / config) | ✅ | ✅ | Verbatim |
| Utils (`parseDurationMs`, `clampNumber`, `deepFreeze`, `generateId`, `isNonEmptyString`) | ✅ | ✅ | Verbatim |
| Default constants (15 entries) | ✅ | ✅ | Verbatim |
| All public types (~50 type exports) | ✅ | ✅ | Verbatim — every name preserved |
| `@suaveplan/events/hooks` dependency | ✅ | ⬆️ Replaced | In-package `Hooks<TMap>` ships under `src/hooks/`; same public surface |
| Plain `throw new Error(...)` from boundaries | ✅ | ⬆️ Replaced | All raised errors extend `SuaveplanError` with stable `BOOKING.*` codes |
| Subpath exports per public module | ✅ | ⬆️ Enhanced | 29 subpaths (up from upstream 28; adds `./hooks/hooks`) |
| Property-based tests (fast-check) | 🚫 upstream (audit asks) | 🚫 deferred | Deterministic suite hits 100% first; fast-check added in follow-up |
| OTel observability surface | 🚫 upstream (audit asks) | 🚫 deferred | Requires `MeterLike`/`LoggerLike` DI design; follow-up change |
| `AbortSignal` propagation | 🚫 upstream (audit asks) | 🚫 deferred | Sync surface; cancellation belongs to async-rewrite follow-up |
| Persistence-tier integration | 🚫 upstream (audit asks) | 🚫 deferred | Belongs to `@suaveplan/booking-persistence` |
| Feature flags | 🚫 upstream (audit asks) | 🚫 deferred | No risky new behaviours introduced by this migration |
| i18n message keys | 🚫 upstream (audit asks) | 🚫 deferred | Wired when the booking i18n catalog lands |
| `@suaveplan/schema-registry` integration | 🚫 upstream (audit asks) | 🚫 deferred | No network-tier consumer yet |
| Benchmarks (mitata) | 🚫 upstream (audit asks) | 🚫 deferred | Coverage gate is primary criterion; benches land alongside observability |
| `BookingError` discriminants (`bookingId`/`holdId`/`mode`/`strategy`) | 🚫 upstream | ⬆️ Added | Genesis convention for typed errors |

### Reference docs consulted

- ✅ `../suaveplan/packages/security/booking/src/` — all 51 implementation files read
- ✅ `../suaveplan/packages/security/booking/README.md` — public API documentation
- ✅ `../suaveplan/packages/security/booking/package.json` — dep graph + subpath exports (28 entries)
- ✅ `../suaveplan/enterprise/booking.md` — enterprise audit, in full
- ✅ `../suaveplan/packages/universal/events/src/hooks/` — upstream Hooks impl + types (re-implemented in-package)
- 🚫 `../suaveplan/openspec/specs/booking/spec.md` — does not exist (upstream has no formal spec; parity contract is the source itself)
- 🚫 `../suaveplan/openspec/changes/*/proposal.md` touching booking — none found beyond `enterprise-booking`

## Verification approach

Every requirement in the spec delta carries a `**Verified by:**` line naming the test files that pin its scenarios. The test layout mirrors the source layout (one `<feature>.test.ts` per `<feature>.ts`):

- `src/error-codes/error-codes.test.ts` — every `BOOKING.*` code reachable from a real call site
- `src/hooks/hooks.test.ts` — `Hooks<TMap>` register/unhook/apply/applyAsync/applyWithResult/abort/once/priority/hookCount/hasHook
- `src/temporal/windows/windows.test.ts`, `src/temporal/recurrence/recurrence.test.ts`, `src/temporal/slots/slots.test.ts` — temporal operations
- `src/conflict/detector/detector.test.ts`, `src/conflict/exact-match/exact-match.test.ts`, `src/conflict/range-overlap/range-overlap.test.ts`, `src/conflict/slot-capacity/slot-capacity.test.ts`, `src/conflict/provider-overlap/provider-overlap.test.ts`
- `src/pricing/calculator/calculator.test.ts`, `src/pricing/seasonal/seasonal.test.ts`, `src/pricing/dynamic/dynamic.test.ts`
- `src/rules/evaluator/evaluator.test.ts`, `src/rules/conditions/conditions.test.ts`
- `src/availability/resolver/resolver.test.ts`, `src/availability/strategies/strategies.test.ts`
- `src/domains/shared.test.ts`, `src/domains/{seats,accommodation,appointments,resources,activities,transport}/<domain>.test.ts`
- `src/schemas/booking.schema.test.ts`, `src/schemas/config.schema.test.ts`
- `src/core/engine/engine.test.ts`, `src/core/state-machine/state-machine.test.ts`, `src/core/event-bus/event-bus.test.ts`
- `src/utils/utils.test.ts`

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/booking` to enumerate.

- No dependents — this is a new universal-tier leaf package being added to genesis. Every potential downstream (`@suaveplan/r3f-booking`, the `api-plugin-bank`/`api-plugin-banking` plugins) is still in the `Pending` list and will adopt this package when migrated.

## Migration impact

None — additive only. No existing genesis package imports `@suaveplan/booking`.