Service sheet & CSV exports

Exports pull your venue’s data out in three purpose-bound shapes: the print-ready daily service sheet for the floor, the operational metrics CSV for spreadsheets, and the future-bookings CSV for moving your data elsewhere. All three share one rulebook: every export names a purpose that is audited verbatim, every cell is formula-escaped, files are encrypted at rest, and downloads are re-authorized against your live membership at the moment of download. You create and verify exports from the panels in the operator console.

The three exports at a glance

Export	Contents	Renders	Who may create and download
Service sheet PDF (SERVICE_SHEET_PDF)	The day’s floor sheet: guest names, decrypted notes, placements	Through the worker, as a print-ready PDF	Owner, org admin, manager — any business date; host — today’s service date only. Finance, read-only and door staff are refused.
Metrics CSV (OPERATIONAL_METRICS_CSV)	The reports aggregates, aggregates only	Through the worker, as CSV	Owner, org admin, manager, finance, read-only (reporting.read)
Future-bookings CSV (FUTURE_BOOKINGS)	Every upcoming booking with guest contact details	Immediately at request time	Owner, org admin, manager (data.export)

Door staff hold none of these permissions — bulk guest data never moves through a door role.

The daily service sheet

The service sheet is the PII-bearing page your floor team actually prints. For one business date it lists every booking that reached the floor — statuses CONFIRMED, NO_SHOW, COMPLETED or CANCELLED — ordered by start time, with:

• one row per booking: local start time, confirmation code, party size, status, guest display name and table placement (from the live allocations, joined labels for shared tables);
• an indented note block under each booking: the decrypted note bodies with their categories (dietary, accessibility, allergy — see Guest profiles & notes), plus the guest’s special requests;
• a header with venue name, the business date and its time zone, generation time, totals (bookings and covers, with covers excluding cancelled rows), and the confidentiality notice: “CONFIDENTIAL — internal use only. Guest personal data; do not forward.”

Two bounds keep the sheet honest. The cohort is capped at 2,000 rows — a busier date is refused with EXPORT_TOO_LARGE rather than silently truncated, so narrow the request instead (the split-job facility is a recorded deferred seam). The PDF itself caps at 100 pages and trips the same error. Hosts are bound to the current venue-local service date: a host may queue and download today’s sheet only, and the bound is re-checked at download, not just at queue time. Managers and the ownership tier choose any business date.

Rendering never touches a browser. The worker writes the sheet with an internal text-only PDF writer — no network fetches, no executable structure, only typed pre-escaped values — then stores the file in the venue-scoped private storage tree under exports/{venueId}/{exportId}/.

The operational metrics CSV

This export renders the same aggregate report described in Reports & metrics as a three-column CSV (section, metric, value): demand, service outcomes, waitlist, approvals and per-currency money, with every rate carrying its numerator and denominator and the unavailable metrics listed with their reasons. Money is per currency, never combined. Every cell rides the formula escaper, so a value that could be read as a spreadsheet formula (leading =, +, -, @) is neutralized with a leading apostrophe before quoting.

The future-bookings CSV

This is the data-movement export: every booking that starts after the request instant, ordered by start time, with an optional lower bound on the business date. It is ready immediately — no worker step. The columns, in order:

Column	Contents
confirmation_code	The booking’s code
business_date	Service business date (YYYY-MM-DD)
start_utc / start_local	The start instant in UTC and in the venue’s local wall clock
party_size	Booked party size
status	Current reservation status
display_name	Guest display name from the contact snapshot
email / phone_e164	Guest contact from the contact snapshot
special_requests	The requests text, if any
expected_amount_minor / currency	Disclosed expected amount in minor units and its currency

The file is capped at the first 10,000 upcoming bookings; a venue with more than that narrows the window with the from-date filter. The download is named bookings-export.csv.

The two-step artifact flow

The service sheet and the metrics CSV are artifact exports with an explicit lifecycle:

1. Request. You name the kind, the filters and a purpose of 1–200 characters — the reason this export exists, audited verbatim, because an export is a deliberate, attributable act. The job is born QUEUED with its expiry stamped at the request instant, and a durable outbox job hands it to the worker.
2. Render. The worker renders the file, stores it in the private storage tree with a SHA-256 fingerprint, and performs a guarded QUEUED to READY transition. A replay after a crash converges; a permanent failure dead-letters the job as FAILED with its render error code recorded on the job; a crash before the guarded write leaves the job QUEUED for the outbox to retry.
3. Download. READY artifacts live 24 hours from the request instant. After that the file reads as plain not-found — an expired export and a wrong id are indistinguishable, and you simply request a fresh export.

The future-bookings CSV skips the queue: it is born READY.

Downloading, and what can go wrong

A download re-authorizes against live membership — never the stored requester’s identity — re-checks the host’s current-date bound for sheets, and refuses anything not READY. In the console panel the download command verifies the grant and returns a shape probe (file name, content type, byte count, first header line) rather than streaming the file into the page; the panel is a workflow probe, not a second bulk-PII surface, and the artifact bytes stream only through the authorized venue-scoped storage seam.

Code	Meaning and remedy
EXPORT_NOT_READY	The export is still QUEUED — the worker has not rendered it yet. Wait a moment and retry the download (this code is retryable).
EXPORT_FAILED	The render failed permanently; the render error code is shown on the job. Start a new export job — the failed one is terminal.
EXPORT_TOO_LARGE	The sheet exceeds the 2,000-row or 100-page bound. Narrow the request (a smaller date range) and queue again.
NOT_FOUND	Unknown export, not visible to your account, or past its 24-hour window. Request the export again.
PERMISSION_DENIED	Your role may not touch this kind — see the table above.

Every step is audited: requested, rendered and downloaded events record the kind and filters (field names only, never file contents).

The one reserved permission, stated plainly

The permission registry grants exports.download to the manager and finance tier, and the role matrix is release-enforced — but in the current version no command consumes that grant yet. Downloads today re-check the working permissions live: reporting.serviceSheet for the sheet, reporting.read for the metrics CSV and data.export for the future-bookings CSV. Treat exports.download as a reserved cell, not a working switch.