Staff Queue Operations

Current Shape

The queue worker mounts admin queue, admin entry, admin queue metrics, admin customer, public queue, public check-in, and staff routes (workers/queue/src/index.ts:23-29).

The edge gateway routes public queue traffic to the queue worker and also reserves /branches/:id/host-assist under the public branch route branch (workers/edge-gateway/src/router.ts:37-51).

Queue State Machine

The queue-specific state machine has six statuses: waiting, called, being_served, completed, no_show, and left (workers/queue/src/state-machine.ts:3-9).

Allowed queue transitions are waiting to called, no_show, or left; called to being_served, no_show, or left; and being_served to completed or no_show (workers/queue/src/state-machine.ts:3-7).

Queue terminal states are completed, no_show, and left, and the helper API exposes transition validation plus valid target lookup (workers/queue/src/state-machine.ts:9-20).

The broader staff-feed engine has a larger service-session state model for appointment, queue, and event work, including checked_in, waiting_in_queue, assigned, being_served, completed, no_show, cancelled, transferred, waitlisted, and rescheduled (workers/staff-feed/src/engine/state-machine.ts:1-54).

Queue Join and Recovery

Public queue join validates queue open state, validates submitted data, detects recoverable active entries by phone or recent name/service, applies capacity policy, inserts a waiting queue entry, creates a waiting_in_queue service session, and refreshes alerts (workers/queue/src/routes/entries.ts:802-956).

Recoverable active-entry lookup matches phone exactly or a recent name/service combination within a ten-minute window (workers/queue/src/routes/entries.ts:219-255).

Queue position and board routes expose customer-facing position data and active board state after join (workers/queue/src/routes/entries.ts:958-1065).

Assignment and Service Flow

Staff eligibility for queue work is checked through the service_staff relationship before assignment (workers/queue/src/routes/entries.ts:171-189).

Active assignment conflict detection prevents assigning a staff member who is already serving another active queue entry (workers/queue/src/routes/entries.ts:191-217).

The queue assignment helper supports queue_next and serve_now; queue_next assigns a waiting entry, while serve_now can move waiting or called entries into being_served and synchronize service-session, staff-status, calendar-sync, and alert records (workers/queue/src/routes/entries.ts:283-381).

The serve route validates transition to being_served, checks staff busy state, updates queue and service-session rows, updates staff status, dispatches calendar sync, and refreshes alerts (workers/queue/src/routes/entries.ts:383-455).

The complete route transitions the entry, updates queue and service-session completion fields, clears staff active status, dispatches calendar sync, and creates a pending order/order item for paid services (workers/queue/src/routes/entries.ts:457-576).

The no-show route transitions the entry to no_show, updates the related service session, clears staff active status for called or being-served entries, and refreshes alerts (workers/queue/src/routes/entries.ts:578-627).

The return-to-queue route supports returning called, being-served, no-show, or left entries to waiting, repositions the entry at the front or back, and clears staff status fields (workers/queue/src/routes/entries.ts:678-749).

The leave route records queue abandonment for entries that exit without being completed (workers/queue/src/routes/entries.ts:751-800).

Staff Feed Transitions

The staff-feed transition engine loads the session, validates the requested transition, applies an optimistic version update, and returns VERSION_CONFLICT when another update wins the race (workers/staff-feed/src/engine/transition.ts:74-132).

The transition engine loads enabled side effects by company, target status, optional from-status, service, and condition expression before executing those effects (workers/staff-feed/src/engine/transition.ts:134-214).

Slot Finder and Assignment Engine

The schedule engine uses a five-minute quantum and defines constants for quanta per hour, day, and week (packages/schedule-engine/src/constants.ts:1-5).

The schedule bitset stores availability in a Uint32Array and exposes constructors, bit read/write, boolean operations, population count, contiguous chunk search, binary serialization, equality, and clone operations (packages/schedule-engine/src/bitset.ts:1-168).

Availability-affecting statuses include appointment, queue, hold, and externally created session states, so queue occupancy and appointment occupancy can share the same scheduling substrate (packages/schedule-engine/src/constants.ts:7-31).

The assignment engine supports skill match, workload balance, round robin, next available, and language match strategies (packages/assignment-engine/src/index.ts:1-7).

Eligible-staff discovery loads service-staff eligibility, active staff in branch, active bookings, active service sessions, prior assignments, next availability, staff skills, certifications, and language tokens (packages/assignment-engine/src/index.ts:295-368).

Host-Assist Status

The public gateway currently routes /branches/:id/host-assist to the queue worker, but the queue worker route table does not show a dedicated host-assist route mounted at that path (workers/edge-gateway/src/router.ts:37-40, workers/queue/src/index.ts:23-29).

The correct current documentation is that host-assist is a gateway-reserved public route surface, while implemented queue operations are the admin/public queue, check-in, staff, metrics, entries, and customers route families mounted by the queue worker (workers/queue/src/index.ts:23-29).

Corrections From Frozen HTML

The frozen page's six-state queue machine remains accurate for queue entries, but it should not be confused with the broader staff-feed service-session state machine (workers/queue/src/state-machine.ts:3-20, workers/staff-feed/src/engine/state-machine.ts:1-54).

The frozen page's host-assist language was stronger than current implementation evidence; current code proves routing but not a dedicated mounted handler in the queue worker (workers/edge-gateway/src/router.ts:37-40, workers/queue/src/index.ts:23-29).

last verified: 2026-04-24, commit 14f3b190db8817399dcd30e1dc4e1ae7674bbf8a