Hotel reservation assistant

End-traveler flow from hotel selection to confirmed reservation, with a conditional finance approval branch and a post-confirmation cancellation window.

"Done" for the user is the booking artifact (confirmation page + email with vendor confirmation number) plus a visible 24h cancel button. "Done" for the org is a settled domain_effects row for book_hotel and an audit trail tying the reservation to the finance approval (when applicable).

The workflow starts when the user taps Confirm on a draft they already shaped in the app.

• ingress = user_request (in-app action, not a webhook)
• command_type = hotel_reservation.confirm
• idempotency_key = "confirm_booking:{draft_id}" — the draft is the dedup anchor; a double-tap on Confirm hits the same row
• requested_by = user_id from the session
• context = { workspace_id, user_id, app_id, trace_id }

Two commands

• hotel_reservation.draft — sync, validates inputs, creates the draft artifact, returns to UI.
• hotel_reservation.confirm — async, the main workflow. Depends on the draft command via command_dependencies (parent required_status = succeeded, propagate_cancellation = true).

Per-command shape

command_id          uuid
command_type        hotel_reservation.confirm
requested_by        user_id
ingress             user_request
payload             { draft_id, reason, accepted_terms_at }
context             { workspace_id, user_id, app_id, trace_id }
status              created → validated → queued → running → ...
cancellation_mode   compensate_then_stop
idempotency_key     confirm_booking:{draft_id}
dbos_workflow_id    set on enqueue

Status path: created → validated → queued → running → succeeded on the happy path. On user-initiated cancel inside the 24h window: running → cancelling → compensating → compensated → cancelled. On policy denial or approval rejection: failed.

Policies are composed in order on the confirm command. The first non-allow decision short-circuits the rest (except where noted).

• permission — user must hold the book_travel capability in their workspace.
• cost — per-user / per-workspace daily cap on hotel spend; hard deny on overflow.
• approval_requirement — if total_amount > $500 returns require_approval with reviewer group = finance_approvers.
• external_sharing — we send guest name + dates to the vendor; check that the workspace allows third-party PII egress.
• destructive_action — tagged because a successful book costs real money and the inverse (cancel) is time-bounded by the vendor.
• rate_limit — bucket per user (e.g. 5 confirms / hour) to defang accidental loops in the app.
• connector_scope — the vendor connector must declare both book and cancel capabilities before this command can register.

Async deterministic plan. Sync prelude validates and creates the command record; the bulk runs on durable queues.

Queues

Execution modes used: sync_function, connector_call, human_task, external_job (the scheduled window-close timer).

Effects are declared upfront from CoreResult.effects and inserted as domain_effects rows in planned state; the runtime adapter walks them.

Lightweight, opt-in. The workflow itself doesn't require memory to function; it's an enhancement.

• scope = user
• type = preference — preferred hotel chain, room type, bed type.
• type = approval_preference — finance team's running notes on a requester (e.g. "approved for client travel through Q3").
• Writes are candidates first; require memory_consent policy allow before commit.
• Conflict resolution: latest wins, with a memory_supersede audit row.

• booking_draft — type connector_snapshot, status draft → validated → archived. Created during the draft command.
• booking_confirmation — type report, status created → published. Includes hotel, dates, total, vendor confirmation number, and the 24h cancellation deadline.
• approval_packet — type approval_packet, only produced when the approval branch fires.

All three are Postgres pointers; no large blobs to push to object storage. Versioning: each confirmation is a single immutable row; a cancellation produces a new booking_cancellation artifact rather than mutating the original.

Single conditional gate. Fires only when total_amount > $500. Reviewer group: finance_approvers. First member to act wins.

Review packet

• requested action — book hotel via vendor X
• requester — user_id, display name, manager
• reason — free-text from the user at confirm time
• affected data — hotel name, check-in, check-out, room type, total
• triggering policy — approval_requirement (threshold: $500)
• expected outcome — a single book_hotel effect against the vendor
• risk level — medium (reversible inside 24h, irreversible after)
• expiration — 48h; expired = rejected by default

On rejected or expired: command transitions to failed, no effects executed, user gets a rejection email. No alternate path — the user can re-draft.

Not agentic. The plan is deterministic; no AgentRun or SwarmRun is involved.

Single append-only domain_events table. All rows here use purpose = audit unless noted.

Business stream (purpose = event) emits booking.confirmed, booking.cancelled, booking.rejected for downstream consumers (analytics, finance ledger).

cancellation_mode = compensate_then_stop. The vendor booking is real money and the user is promised a 24h reversible window, so a clean undo is non-negotiable.

Two distinct cancel paths exist:

1. Mid-flight cancel (before book_hotel succeeds, e.g. during approval wait) — nothing to compensate at the vendor; the approval row is marked cancelled, command exits at cancelled.
2. Post-confirmation cancel (within 24h) — the workflow re-enters via a new hotel_reservation.cancel command that triggers the compensation chain on the original.

Status transitions on the original command: succeeded → cancelling → compensating → compensated → cancelled. propagate_cancellation = true on command_dependencies means a draft-side cancel never gets here in production, but it's defensive correctness.

Two-effect chain, each with a declared inverse. The graph validator at startup confirms no cycles, depth = 1, and both compensations declare of targets that exist.

Order of compensation walk is reverse of planned effects: notify-cancellation runs after the vendor cancel succeeds, so the user is never told the booking is cancelled if the vendor leg fails.

cancel_reservation declares counter_effects = true; the runtime drift detector compares emitted effects against the declared inverse set and writes a compensation_drift row if they diverge. send_cancellation_email declares counter_effects = false — it's a new outbound email, not an inverse of the original send.

Runtime adapter

DBOS for v1. The compensation chain has depth 1 and is orchestrated by Concord as a sub-workflow, so SAGA_COMPENSATION_NATIVE isn't required.

Required adapter capabilities

Retry policies

Connector

• vendor_hotel_api — capabilities: book, cancel; auth: OAuth client_credentials; idempotency: native, header X-Idempotency-Key.
• notification_provider — capabilities: send_email; idempotency: client-supplied message_id.

Unit (functional core)

• Pure: amount threshold returns require_approval at $500.01, allow at $500.00.
• Pure: idempotency key shape is confirm_booking:{draft_id}.
• Pure: cancellation window predicate flips at the 24h boundary.

Integration (Postgres + runtime adapter)

• Insert command, expect domain_effects rows in planned.
• Approval row transitions pending → approved via signal; workflow resumes.
• Schedule fires the 24h window close; subsequent cancel is refused.

Workflow (end-to-end)

• Happy path under $500: confirm → book → confirmation artifact published.
• Happy path over $500 with approval: full sequence with approval row.
• Cancel inside 24h: book → cancel_reservation at vendor, command compensated → cancelled.
• Vendor returns 500 once then 200: single book_hotel effect at vendor (idempotency works).

Safety

• Policy denial: user without book_travel capability — command fails before any effect runs.
• Approval rejected: command failed, no effects, rejection email sent.
• Forbidden tool: a code path that tries to call vendor.modify (not in scope) is rejected at registration.
• Compensation drift: simulate vendor cancel that also issues a credit; compensation_drift row appears.
• Memory consent: write attempt without consent is rejected; nothing in memory_candidates.

Boundary discipline

• concord_boundary_check.py rejects dbos / temporalio imports outside the runtime adapter file.

Acceptance criterion

For every confirmed booking, exactly one book_hotel effect row reaches succeeded with a vendor confirmation number, and the user sees the confirmation artifact within 30 seconds of approval (or immediately, in the no-approval path). For every cancel inside 24h, exactly one matching cancel_reservation effect reaches succeeded.

• Assumed: the $500 threshold is in a single currency. If the app is multi-currency, the threshold needs a normalized comparison (FX snapshot at confirm time) and the threshold itself becomes a per-workspace policy parameter.
• Assumed: the vendor's idempotency TTL is ≥ our retry window. Confirm with vendor docs. If shorter, retries past TTL risk duplicate bookings; cap max_attempts accordingly or switch to a slower backoff inside the TTL.
• Assumed: the 24h cancel window is wall-clock from confirmation time, regardless of the hotel's local timezone. Confirm with product whether this should instead be local-to-check-in.
• Assumed: first-finance-approver-wins is acceptable. If finance wants two-of-N, this becomes a swarm-style join with quorum — out of scope for v1 but flagged.
• Risk: approval expiration at 48h while the hotel rate is held by the vendor for less — rate could move between approval and book. Consider re-pricing on approval and re-confirming with the user if delta > threshold.
• Risk: partial vendor outage during compensation. The retry policy on cancel_reservation is generous (5 attempts) but if the vendor stays down, the user thinks they cancelled while we have a live reservation. Need an alerting path on compensation.failed.
• Risk: PII egress. external_sharing policy needs to be wired to the workspace's data residency settings; not all customers may allow guest names to leave the org.
• Deferred: versioning of the command shape. WORKFLOW_VERSIONING is not declared by the DBOS adapter; if the payload schema changes, in-flight commands need a migration path. Revisit when scaling beyond a single deploy.
• Deferred: finance approver UI — assumed to live in the same app shell, but could be Slack with a callback. Slack would route via approval_callback ingress on a sibling command.