# Lexicons

The canonical source is ATM's `app/src/lib/ticket-lexicons.ts`. This repo copies
ATM's generated `app/lexicons/tickets/atmosphere/` JSON; never hand-edit it here.
The 2026-10-12 refresh uses ATM main commit
`59432c22e2a6dc47d852165a7d1e67c30c4810a1` and contains 30 lexicons: three
records, shared definitions, and 26 service contracts.
[atm-source.json](atm-source.json) records the exact source revision.

## Public records

- `tickets.atmosphere.ticketType`: organizer-owned type metadata, public event
  strongRef, optional per-type `quantityTotal` display hint, and optional catalog
  refs. A paid service configuration requires an active organizer-owned
  `money.atmosphere.product` with `kind=ticket`; its current one-time
  `defaultPrice` must match the configured amount and currency. Free/RSVP types
  can omit Product. The record's `currency`, `unitAmount`, and direct
  `defaultPrice` are legacy display/pricing compatibility fields; when Product
  is present, economics resolve through that Product's default Price.
- `tickets.atmosphere.ticketedEvent`: public event anchor with an optional
  display-ordered array of exact `ticketTypes` strongRefs. Disclosure is not
  availability or buyer eligibility.
- `tickets.atmosphere.checkInList`: public event/list label only; staff grants,
  check-in logs and ticket tokens are private.

Community calendar event/RSVP records remain the public event graph. Checkout
lists on the ticketType record URI; Product and Price are catalog/economic refs.
No public capacity-pool record, exact event capacity, promo code, or issued
buyer ticket is part of the current catalog.

## Service contracts

Use the [generated reference](generated-reference.json) and raw schemas for
exact required fields, limits, and declared errors. GET methods use lexicon
`parameters`; POST procedures keep assertion JWTs in request bodies.

| Purpose | Methods (under `tickets.atmosphere.`) |
| --- | --- |
| Event config | `createTicketEvent`, `updateTicketEvent`, `cancelTicketEvent` |
| Type config | `createTicketType`, `updateTicketType`, `archiveTicketType`, `setTicketTypeForm` |
| Capacity | `setEventCapacity`, `getTicketAvailability` |
| Reservation/issuance | `createTicketHold`, `releaseTicketHold`, `claimFreeTicket`, `releaseFreeTicket` |
| Private ticket reads | `listBuyerTickets`, `listOrganizerTickets` |
| Scanner | `verifyTicket`, `checkInTicket` |
| Waitlists | `joinWaitlist`, `claimWaitlistOffer`, `listEventWaitlist` |
| Forms | `listTicketFormResponses` |
| Collaboration | `inviteOrganizerCollaboration`, `acceptCollaboration`, `revokeCollaboration`, `listCollaborations` |
| Public discovery | `listPublicConfig` on ATM AppView; no auth required |

`listBuyerTickets` takes exactly one of `buyer` (DID or handle) or `paymentId`.
`listOrganizerTickets` uses `organizer`, not `organizerDid`.
`listPublicConfig` requires `organizer`; optional `eventUri` must belong to that
organizer. It indexes ticketType/ticketedEvent records and is not live inventory.

## Re-sync and verify

First verify that ATM's remote main ref is current. Then copy its generated
artifacts and rebuild the reference/pages:

```sh
node scripts/sync-ticket-lexicons.mjs ../atmosphere-money origin/main
node scripts/generate-docs-reference.mjs
node scripts/generate-docs-pages.mjs
node scripts/check-docs-contracts.mjs
node scripts/check-examples.mjs
```

The sync script accepts an exact commit in place of `origin/main`, records that
commit, and removes obsolete generated schemas. Generation now includes query
parameters and per-method declared errors. Served JSON, authoritative namespace
publication, and deployed runtime readiness are separate checks; this refresh
does not assert a protocol publication or activate a release.

## Migration from the older docs

The old ticketTier APIs are replaced by ticketType APIs, `tierId`/
`ticketTierId` by `ticketTypeId`, and `tiers` output by `ticketTypes`.
`publicOffer` became `ticketedEvent`. Public `capacityGroup` records and
`createCapacityGroup`/`updateCapacityGroup` are retired: use type caps plus
`setEventCapacity`. `setTierForm` is now `setTicketTypeForm`.
These old names are historical migration guidance, not served aliases.

Private buyer PII, attendee answers, exact inventory, holds, ticket ids,
scan secrets, staff grants, check-ins and promo counters must stay off protocol.