@nbt-dev/nbt 0.0.1 → 0.0.4

package/stdlib/chat/migrations/20260429222411_initial/migration.nbt

@@ -0,0 +1,59 @@
+migration initial {
+  add_entity Channel
+  add_field Channel name string default("")
+  add_field Channel description string default("")
+  add_field Channel creatorId string default("")
+  add_field Channel isPrivate bool default(false)
+  add_field Channel isArchived bool default(false)
+  add_field Channel lastActivityAt DateTime default(0)
+  add_unique Channel [name]
+  add_entity ChannelMember
+  add_field ChannelMember channelId string default("")
+  add_field ChannelMember userId string default("")
+  add_field ChannelMember joinedAt DateTime default(0)
+  add_index ChannelMember [userId]
+  add_index ChannelMember [channelId]
+  add_unique ChannelMember [channelId, userId]
+  add_entity DirectMessageRoom
+  add_field DirectMessageRoom participantA string default("")
+  add_field DirectMessageRoom participantAType string default("USER")
+  add_field DirectMessageRoom participantB string default("")
+  add_field DirectMessageRoom participantBType string default("USER")
+  add_field DirectMessageRoom lastActivityAt DateTime default(0)
+  add_index DirectMessageRoom [participantA]
+  add_index DirectMessageRoom [participantB]
+  add_unique DirectMessageRoom [participantA, participantB]
+  add_entity Message
+  add_field Message channelId string default("")
+  add_field Message dmRoomId string default("")
+  add_field Message parentMessageId string default("")
+  add_field Message senderType string default("")
+  add_field Message senderId string default("")
+  add_field Message content string default("")
+  add_field Message editedAt DateTime default(0)
+  add_field Message deletedAt DateTime default(0)
+  add_field Message replyCount u32 default(0)
+  add_index Message [channelId]
+  add_index Message [dmRoomId]
+  add_index Message [parentMessageId]
+  add_index Message [senderId]
+  add_entity ChatReadState
+  add_field ChatReadState userId string default("")
+  add_field ChatReadState scopeKey string default("")
+  add_field ChatReadState scopeType string default("")
+  add_field ChatReadState scopeId string default("")
+  add_field ChatReadState lastReadMessageId string default("")
+  add_field ChatReadState lastReadAt DateTime default(0)
+  add_index ChatReadState [userId]
+  add_index ChatReadState [scopeKey]
+  add_unique ChatReadState [userId, scopeKey]
+  add_entity User
+  add_field User name string default("")
+  add_field User username string default("")
+  add_field User email string default("")
+  add_field User emailVerified bool default(false)
+  add_field User externalId string default("")
+  add_field User capsVersion u32 default(0)
+  add_index User [email]
+  add_index User [externalId]
+}

package/stdlib/chat/migrations/20260429222411_initial/schema_snapshot.nbt

@@ -0,0 +1,71 @@
+entity Channel {
+  name: string
+  description?: string
+  creatorId: string
+  isPrivate: bool
+  isArchived: bool
+  lastActivityAt?: DateTime
+  @@unique([name])
+  @@collaborative([])
+}
+
+entity ChannelMember {
+  channelId: string
+  userId: string
+  joinedAt: DateTime
+  @@unique([channelId, userId])
+  @@index([userId])
+  @@index([channelId])
+}
+
+entity DirectMessageRoom {
+  participantA: string
+  participantAType: string
+  participantB: string
+  participantBType: string
+  lastActivityAt?: DateTime
+  @@unique([participantA, participantB])
+  @@index([participantA])
+  @@index([participantB])
+  @@collaborative([])
+}
+
+entity Message {
+  channelId?: string
+  dmRoomId?: string
+  parentMessageId?: string
+  senderType: string
+  senderId: string
+  content: string
+  editedAt?: DateTime
+  deletedAt?: DateTime
+  replyCount: u32
+  @@index([channelId])
+  @@index([dmRoomId])
+  @@index([parentMessageId])
+  @@index([senderId])
+}
+
+entity ChatReadState {
+  userId: string
+  scopeKey: string
+  scopeType: string
+  scopeId: string
+  lastReadMessageId: string
+  lastReadAt: DateTime
+  @@unique([userId, scopeKey])
+  @@index([userId])
+  @@index([scopeKey])
+}
+
+entity User {
+  name: string
+  username?: string
+  email?: string
+  emailVerified: bool
+  externalId?: string
+  capsVersion: u32
+  @@index([email])
+  @@index([externalId])
+}
+

package/stdlib/chat/migrations/20260430185225_add_messagereaction/migration.nbt

@@ -0,0 +1,9 @@
+migration add_messagereaction {
+  add_entity MessageReaction
+  add_field MessageReaction messageId string default("")
+  add_field MessageReaction emoji string default("")
+  add_field MessageReaction userId string default("")
+  add_index MessageReaction [messageId]
+  add_index MessageReaction [userId]
+  add_unique MessageReaction [messageId, emoji, userId]
+}

package/stdlib/chat/migrations/20260430185225_add_messagereaction/schema_snapshot.nbt

@@ -0,0 +1,78 @@
+entity Channel {
+  name: string
+  description?: string
+  creatorId: string
+  isPrivate: bool
+  isArchived: bool
+  lastActivityAt?: DateTime
+  @@unique([name])
+  @@collaborative([])
+}
+
+entity ChannelMember {
+  channelId: string
+  userId: string
+  joinedAt: DateTime
+  @@unique([channelId, userId])
+  @@index([userId])
+  @@index([channelId])
+}
+
+entity DirectMessageRoom {
+  participantA: string
+  participantB: string
+  lastActivityAt?: DateTime
+  @@unique([participantA, participantB])
+  @@index([participantA])
+  @@index([participantB])
+  @@collaborative([])
+}
+
+entity Message {
+  channelId?: string
+  dmRoomId?: string
+  parentMessageId?: string
+  senderType: string
+  senderId: string
+  content: string
+  editedAt?: DateTime
+  deletedAt?: DateTime
+  replyCount: u32
+  @@index([channelId])
+  @@index([dmRoomId])
+  @@index([parentMessageId])
+  @@index([senderId])
+}
+
+entity MessageReaction {
+  messageId: string
+  emoji: string
+  userId: string
+  @@unique([messageId, emoji, userId])
+  @@index([messageId])
+  @@index([userId])
+}
+
+entity ChatReadState {
+  userId: string
+  scopeKey: string
+  scopeType: string
+  scopeId: string
+  lastReadMessageId: string
+  lastReadAt: DateTime
+  @@unique([userId, scopeKey])
+  @@index([userId])
+  @@index([scopeKey])
+}
+
+entity User {
+  name: string
+  username?: string
+  email?: string
+  emailVerified: bool
+  externalId?: string
+  capsVersion: u32
+  @@index([email])
+  @@index([externalId])
+}
+

package/stdlib/chat/migrations/20260518191152_update_message/migration.nbt

@@ -0,0 +1,3 @@
+migration update_message {
+  add_search Message [content]
+}

package/stdlib/chat/migrations/20260518191152_update_message/schema_snapshot.nbt

@@ -0,0 +1,81 @@
+entity Channel {
+  name: string
+  description?: string
+  creatorId: string
+  isPrivate: bool
+  isArchived: bool
+  lastActivityAt?: DateTime
+  @@unique([name])
+  @@collaborative([])
+}
+
+entity ChannelMember {
+  channelId: string
+  userId: string
+  joinedAt: DateTime
+  @@unique([channelId, userId])
+  @@index([userId])
+  @@index([channelId])
+}
+
+entity DirectMessageRoom {
+  participantA: string
+  participantAType: string
+  participantB: string
+  participantBType: string
+  lastActivityAt?: DateTime
+  @@unique([participantA, participantB])
+  @@index([participantA])
+  @@index([participantB])
+  @@collaborative([])
+}
+
+entity Message {
+  channelId?: string
+  dmRoomId?: string
+  parentMessageId?: string
+  senderType: string
+  senderId: string
+  content: string
+  editedAt?: DateTime
+  deletedAt?: DateTime
+  replyCount: u32
+  @@index([channelId])
+  @@index([dmRoomId])
+  @@index([parentMessageId])
+  @@index([senderId])
+  @@search([content])
+}
+
+entity MessageReaction {
+  messageId: string
+  emoji: string
+  userId: string
+  @@unique([messageId, emoji, userId])
+  @@index([messageId])
+  @@index([userId])
+}
+
+entity ChatReadState {
+  userId: string
+  scopeKey: string
+  scopeType: string
+  scopeId: string
+  lastReadMessageId: string
+  lastReadAt: DateTime
+  @@unique([userId, scopeKey])
+  @@index([userId])
+  @@index([scopeKey])
+}
+
+entity User {
+  name: string
+  username?: string
+  email?: string
+  emailVerified: bool
+  externalId?: string
+  capsVersion: u32
+  @@index([email])
+  @@index([externalId])
+}
+

package/stdlib/chat/schema.nbt

@@ -0,0 +1,130 @@
+# Chat cart — channels, DMs, threaded messages.
+
+import {User} from "auth";
+
+entity Channel {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  name: string
+  description?: string
+  creatorId: string
+  isPrivate: bool
+  isArchived: bool
+  lastActivityAt?: DateTime
+
+  @@unique([name])
+}
+
+# Membership table for private channels. Public channels skip this — any
+# authed user can post. Membership = read+post; admin gates write metadata.
+entity ChannelMember {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  channelId: string
+  userId: string
+  joinedAt: DateTime @default(now())
+
+  @@unique([channelId, userId])
+  @@index([userId])
+  @@index([channelId])
+}
+
+# 1:1 DM room. Pair canonicalized in handler: participantA = lexicographic
+# min(ULID), participantB = max. Lookups normalize both args before hitting
+# the unique index.
+#
+# participantAType / participantBType ∈ "USER" | "AGENT". Required so DM
+# triggers (`on dm(<agent>)`) can identify the peer at message send time
+# without a cross-cart lookup. Existing rows default to USER/USER.
+entity DirectMessageRoom {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  participantA: string
+  participantAType: string
+  participantB: string
+  participantBType: string
+  lastActivityAt?: DateTime
+
+  @@unique([participantA, participantB])
+  @@index([participantA])
+  @@index([participantB])
+}
+
+# Single Message entity for both channel + DM scopes. Exactly one of
+# channelId / dmRoomId is non-empty per row. parentMessageId set => thread
+# reply (Google-Chat-style inline replies; only one level deep — replies
+# of replies coalesce to the top-level parent).
+#
+# senderType ∈ "USER" | "AGENT" | "SYSTEM". senderId points at the
+# corresponding entity in the appropriate cart (User/Agent/System). UI
+# renders a bot badge for non-USER senders. No fake User rows for bots.
+entity Message {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  channelId?: string
+  dmRoomId?: string
+  parentMessageId?: string
+
+  senderType: string
+  senderId: string
+
+  content: string
+
+  editedAt?: DateTime
+  deletedAt?: DateTime
+
+  # Denormalized — bumped by send_message handler when a reply is created.
+  # Keeps the parent row paginatable without a per-message COUNT scan.
+  replyCount: u32
+
+  @@index([channelId])
+  @@index([dmRoomId])
+  @@index([parentMessageId])
+  @@index([senderId])
+  @@search([content])
+}
+
+# Per-user emoji reaction on a message. Discord-style counts are computed from
+# these rows at read time; one user can react once per emoji per message.
+entity MessageReaction {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  messageId: string
+  emoji: string
+  userId: string
+
+  @@unique([messageId, emoji, userId])
+  @@index([messageId])
+  @@index([userId])
+}
+
+# Per-(user, scope) read pointer.
+#
+# scopeKey is "channel:<channel_id>" or "dm:<dm_room_id>" — collapses the two
+# parallel scope fields into a single composite-uniqueable key. Two parallel
+# @@unique constraints on nullable cols aren't currently exercised by NBT
+# codegen, so this is the safe shape.
+#
+# lastReadMessageId is a ULID; ULIDs sort lexicographically by creation time
+# so "msg.id > lastReadMessageId" (string compare) cleanly answers "unread?".
+entity ChatReadState {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  userId: string
+  scopeKey: string
+  scopeType: string
+  scopeId: string
+
+  lastReadMessageId: string
+  lastReadAt: DateTime @default(now())
+
+  @@unique([userId, scopeKey])
+  @@index([userId])
+  @@index([scopeKey])
+}

package/stdlib/crm/adapters/gohighlevel/README.md

@@ -0,0 +1,85 @@
+# GHL Adapter
+
+Webhook ingest → CRM persistence as composable tasks. The adapter classifies
+inbound GHL Workflow webhook payloads and upserts the corresponding Contact
+or Deal directly. Appointment persistence lives in the calendar cart's
+parallel adapter (`cartridges/core/calendar/adapters/gohighlevel/`) because
+Calendar/Appointment are calendar-cart entities.
+
+No transformation, normalization, geocoding, AI scoring, or write-back to
+GHL. Those are downstream client-cart concerns. Read-side tasks (backfill,
+sync recovery) come back when there's a real consumer.
+
+## Tasks (queue names = `crm.<task>`)
+
+| Task | Inputs | Outputs |
+|---|---|---|
+| `crm.ghl_classify_event_type` | `body_json` | `event_type`, `tenant_org`, `tenant_project` |
+| `crm.ghl_persist_contact` | `body_json` | `contact_id`, `created`, `ok`, `error` |
+| `crm.ghl_persist_opportunity` | `body_json` | `deal_id`, `created`, `ok`, `error` |
+
+Plus, in the calendar cart:
+
+| Task | Inputs | Outputs |
+|---|---|---|
+| `calendar.ghl_persist_appointment` | `body_json` | `appointment_id`, `calendar_id`, `ok`, `error` |
+
+`event_type` outputs from classify: `ContactCreate`, `ContactChange`,
+`OpportunityCreate`, `OpportunityChange`, `AppointmentCreate`,
+`AppointmentChange`, `Unknown`. The 7th GHL workflow "Pipeline Stage Changed
+Sync" aliases onto `OpportunityChange` because the payload shape is
+identical.
+
+## Webhook entry
+
+GHL POSTs to ingest:
+
+```
+POST /api/ingest/endpoint/receive?e=mylocalpro-ghl
+```
+
+The `Endpoint` row for slug `mylocalpro-ghl` carries `systemId` pointing at
+the per-client System graph. After Payload persistence, ingest fires
+`queue_exec_start("system.<systemId>", { payloadId, endpointSlug, endpointId, body_json })`.
+
+The first task in the per-client graph is `crm.ghl_classify_event_type`,
+followed by a `branch` on `event_type` to one of the persist tasks
+(`ghl_persist_contact`, `ghl_persist_opportunity`,
+`calendar.ghl_persist_appointment`).
+
+## Files
+
+```
+main.nbt                                  # composes the persist tasks
+native/persist.jai                        # ghl_apply_contact_payload, ghl_apply_opportunity_payload
+tasks/classify_event_type.nbt
+tasks/persist_contact.nbt
+tasks/persist_opportunity.nbt
+tests/fixtures/webhooks/                  # 4 real-shape fixtures (contact_*/opportunity_*)
+tests/README.md                           # fixture provenance + classifier expectations
+```
+
+Native imports are declared at the cart root (`crm/cartridge.nbt`) because
+the codegen's native-file copy step assumes paths are cart-root-relative.
+
+The calendar cart mirrors this layout for appointment persistence:
+`cartridges/core/calendar/adapters/gohighlevel/`.
+
+## External-PK = local-PK
+
+GHL ids are written into entity `id` directly: a Contact for
+`contact_id="ctc_xyz"` lives at `Contact.id="ctc_xyz"`, an Opportunity for
+`id="opp_001"` lives at `Deal.id="opp_001"`, an Appointment for
+`calendar.appointmentId="apt_xyz"` lives at `Appointment.id="apt_xyz"`. No
+`externalId` indirection — the next webhook update keys the same row.
+
+## Adding a persist branch
+
+1. Add the helper to `native/persist.jai` (or a calendar/agent/etc. cart's
+   `native/persist.jai` if the target entity lives there).
+2. Create `tasks/persist_<name>.nbt` with `input body_json: string` and the
+   handler delegating to the helper.
+3. Import the task in `main.nbt`.
+4. Update `tasks/classify_event_type.nbt` if a new `event_type` is needed.
+5. `jai first.jai` — task appears in the cart's `contract.json` and at
+   `/_console/task-catalog`.

package/stdlib/crm/adapters/gohighlevel/tests/README.md

@@ -0,0 +1,159 @@
+# GHL Adapter Tests
+
+Two fixture sets, two purposes. Both describe the same GHL tenant
+(`org=mlp, project=default, locationId=loc_test`) so a replay that uses
+either source converges on the same CRM entity graph.
+
+| Set | Role | Producer | Consumer | Discriminator |
+| --- | --- | --- | --- | --- |
+| `fixtures/webhooks/*.json` | Inbound delta stream | GHL workflow engine (or v2 native subscription) | `tasks/classify_event_type.nbt` + downstream user-cart systems | `body.workflow.name` (workflow shape) → fall back to `body.type` (v2 native) |
+| `fixtures/api/*.json`      | Backfill / sync recovery snapshot | Mocked GHL REST replies (when `GHL_MOCK_DIR` is set, `native/mock.jai` reads from disk instead of curl) | All `tasks/fetch_*` / `tasks/list_*` tasks | URL-derived filename (see "Mock key derivation" below) |
+
+The two sets carry **different shapes** because GHL emits different shapes:
+the workflow engine flattens custom fields onto the top-level payload (with
+`customFields[]` redundantly nested), while the REST API returns them under
+a typed envelope (`{contact: {...}}`, `{opportunities: [...], meta: {...}}`,
+etc.). The flattening logic and field classification live in the portal at
+`packages/api/src/services/ghl/field-classification.ts`.
+
+## Source of truth for shapes
+
+- **Webhook payload shapes** — derived from the portal handler at
+  `apps/portal/app/api/v1/[...route]/routes/webhooks/ghl.ts` (the consumer is
+  authoritative; GHL workflow webhook payloads are user-configurable and not
+  formally schema'd).
+- **API response shapes** — the GHL marketplace API docs are authoritative;
+  cross-check each API fixture against the corresponding endpoint page:
+  - `GET /contacts/:id` — https://marketplace.gohighlevel.com/docs/ghl/contacts/get-contact
+  - `GET /contacts/` — https://marketplace.gohighlevel.com/docs/ghl/contacts/get-contacts
+  - `GET /opportunities/:id` — https://marketplace.gohighlevel.com/docs/ghl/opportunities/get-opportunity
+  - `GET /opportunities/search` — https://marketplace.gohighlevel.com/docs/ghl/opportunities/search-opportunity
+  - `GET /opportunities/pipelines` — https://marketplace.gohighlevel.com/docs/ghl/opportunities/get-pipelines
+  - `GET /calendars/` — https://marketplace.gohighlevel.com/docs/ghl/calendars/get-calendars
+  - `GET /calendars/events` — https://marketplace.gohighlevel.com/docs/ghl/calendars/get-calendar-events
+  - `GET /calendars/blocked-slots` — https://marketplace.gohighlevel.com/docs/ghl/calendars/get-blocked-slots
+  - `GET /users/` — https://marketplace.gohighlevel.com/docs/ghl/users/get-user-by-location
+  - `GET /locations/:id/customFields` — https://marketplace.gohighlevel.com/docs/ghl/custom-fields/get-custom-fields
+
+## Shared CRM graph (referenced by both sets)
+
+| Entity | ID | Notes |
+| --- | --- | --- |
+| Contact | `ctc_alice_001` | Alice Anderson; full address + property custom fields. After `contact_changed`, last name → `Anderson-Smith`, address → `456 Updated Ave`, email → `alice.smith@example.com`. |
+| Contact | `ctc_bob_002` | Bob Builder; minimal — exists so `contacts__page1` is non-trivial. |
+| Opportunity | `opp_001` | Alice's 8 kW solar deal. `Created` lands at `pip_solar / ps_qualified` @ $24 500. `Changed` advances to `ps_proposal_sent` @ $28 500 with an `Appointment Outcome=showed`. |
+| Pipeline | `pip_solar` | 5 stages: `ps_lead → ps_qualified → ps_proposal_sent → ps_won / ps_lost`. |
+| Calendar | `cal_solar_consult` | `America/Toronto`, team `usr_001`/`usr_002`. |
+| Appointment | `apt_001` | Alice + cal_solar_consult. `Created` confirms for 2026-05-12 14:00 EDT. `Changed` reschedules to 2026-05-15 10:00 (timezone-naive) and transitions to `showed`. |
+| Users | `usr_001..003` | Bob Brown / Charlie Chen / Diana Davis — match the `Setter`/`Closer` strings in webhook payloads. |
+| Custom fields | `cf_utility`, `cf_avg_bill`, `cf_shade`, `cf_owner` (contact model); `cf_proposal`, `cf_inspection_date` (opportunity model); plus the deal-tracking projection (`cf_setter`, `cf_closer`, `cf_appt_outcome`, `cf_total_contract`, `cf_date_sold`). |
+
+## Webhook fixtures (`fixtures/webhooks/`)
+
+One fixture per real published GHL Workflow shape. Every payload mirrors
+something GHL actually posts; synthetic probes (unknown event, wrong
+tenant, v2 native subscriptions) have been dropped — they tested code
+paths that don't fire for the real tenant configuration.
+
+| File | `workflow.name` | `body.type` | Expected classifier output |
+| --- | --- | --- | --- |
+| `contact_created.json` | `Contact Created Sync` | `ContactCreate` | `event_type=ContactCreate, tenant_org=mlp, tenant_project=default` |
+| `contact_changed.json` | `Contact Changed Sync` | `ContactUpdate` | `event_type=ContactChange` |
+| `opportunity_created.json` | `Opportunity Created Sync` | `OpportunityCreate` | `event_type=OpportunityCreate` |
+| `opportunity_changed.json` | `Opportunity Changed Sync` | `OpportunityUpdate` | `event_type=OpportunityChange` |
+| `appointment_created.json` | `Appointment Created Sync` | `AppointmentCreate` | `event_type=AppointmentCreate` |
+| `appointment_changed.json` | `Appointment Changed Sync` | `AppointmentUpdate` | `event_type=AppointmentChange` |
+
+The 7th GHL workflow shown in the published list — **Pipeline Stage Changed
+Sync** — carries the same opportunity payload shape as Opportunity Changed
+Sync. The classifier aliases it onto `event_type=OpportunityChange`, so
+`opportunity_changed.json` covers it (replay with `workflow.name` swapped to
+verify).
+
+### Real-payload shape and quirks
+
+- **Custom fields are flat top-level keys, not a `customFields[]` array.**
+  Real GHL workflow webhooks emit every property field as a top-level body
+  key by display name (`"Closer": "..."`, `"Average Electric Bill": "245"`,
+  `"Shade?": "minimal"`). The `customFields[]` array shape only appears on
+  REST API responses (`fixtures/api/`), not on webhook bodies. Most
+  property keys come through as empty strings even when unset.
+- **Cross-domain spillage is normal.** Contact webhooks carry deal-tracking
+  fields (`Setter`, `Closer`, `Total Contract Price`); opportunity webhooks
+  carry property fields (`Average Electric Bill`, `Shade?`); appointment
+  webhooks carry both. Don't assume Contact-side keys imply contact intent.
+- **HVAC twin keys.** Many fields have `(HVAC)` variants
+  (`Closer` + `Closer (HVAC)`, `Setter Name` + `Setter Name (HVAC)`,
+  `# Touches` + `# Touches HVAC`). Both ship even when only one branch is
+  active.
+- **Numeric values can be raw JSON numbers**, not always strings
+  (e.g. `"Outbound Dials": 8`, `"# Touches": 3`).
+- `customData` carries `{org, project, type}` — `type` is one of
+  `"Contact"` / `"Opportunity"` / `"Appointment"`.
+- Top-level `attributionSource: {}` is typically empty; real attribution
+  lives under `contact.attributionSource` and `contact.lastAttributionSource`.
+- `appoinmentStatus` (GHL typo) is the canonical key on appointment
+  payloads. `appointment_changed.json` carries both `appoinmentStatus` and
+  `appointmentStatus` with conflicting values to exercise typo precedence.
+- `pipleline_stage` (GHL typo) — `opportunity_changed.json` uses it
+  instead of `pipeline_stage` to exercise handler/cart fallback
+  (ghl.ts:1308, 1313, 1392).
+- Naive vs offset timestamps — `appointment_created.json` uses
+  `-04:00`-offset times; `appointment_changed.json` uses naive
+  `"2026-05-15T10:00:00"` (no offset) so `parseGhlTime` falls into its
+  `fromZonedTime` branch.
+- `tags` on workflow webhooks is a comma-separated CSV string (with
+  possible spaces, apostrophes, special chars); v2-native shape is a JSON
+  array.
+
+API fixtures (`fixtures/api/`) keep the structured `customFields[]` array
+shape — that's the format the GHL REST API actually returns. The webhook
+flattening happens server-side inside GHL's workflow engine.
+
+## API fixtures (`fixtures/api/`)
+
+Filename is derived from URL path + selected query keys (see `native/mock.jai`).
+
+### Mock key derivation
+
+1. Strip leading `/`, replace remaining `/` with `_`, drop the query string.
+2. If query has `skip` + `limit`, append `_pageN` where `N = skip/limit + 1`.
+3. If query has `startTime` + `endTime`, append `_window`.
+4. Other query params (e.g. `model=contact|opportunity` on
+   `customFields`) **do not** affect the key — a single fixture serves all
+   variants of those query shapes.
+
+| Fixture | Endpoint | Notes |
+| --- | --- | --- |
+| `users_.json` | `GET /users/` | 3 users matching the `Setter`/`Closer` names in the webhook fixtures. |
+| `opportunities_pipelines.json` | `GET /opportunities/pipelines` | One pipeline (`pip_solar`) with 5 stages. |
+| `locations_loc_test_customFields.json` | `GET /locations/loc_test/customFields` | Union of contact-model and opportunity-model fields (mock dispatcher conflates the `?model=` query). |
+| `contacts__page1.json` | `GET /contacts/?skip=0&limit=100` | Alice + Bob with full scalars, `attributionSource`, `customFields[]`. |
+| `contacts__page2.json` | `GET /contacts/?skip=100&limit=100` | Empty terminator. |
+| `contacts_ctc_alice_001.json` | `GET /contacts/ctc_alice_001` | Single-contact envelope `{contact: {...}}`. |
+| `opportunities_search_page1.json` | `GET /opportunities/search?skip=0&limit=100` | One opp with custom fields and assignment metadata. |
+| `opportunities_search_page2.json` | `GET /opportunities/search?skip=100&limit=100` | Empty terminator. |
+| `opportunities_opp_001.json` | `GET /opportunities/opp_001` | Single-opp envelope `{opportunity: {...}}`. |
+| `calendars_.json` | `GET /calendars/` | One calendar with team members. |
+| `calendars_events_window.json` | `GET /calendars/events?calendarId=…&startTime=…&endTime=…` | One event matching `apt_001`'s **created** state, so an API-backfill replay sees the same starting point as the webhook stream's first appointment fixture. |
+| `calendars_blocked-slots_window.json` | `GET /calendars/blocked-slots?userId=…&startTime=…&endTime=…` | Empty `{slots: []}` so the task has a fixture instead of `mock_missing:`. |
+
+## Replay loop (smoke target — harness still pending)
+
+```sh
+GHL_MOCK_DIR=$(pwd)/cartridges/core/crm/adapters/gohighlevel/tests/fixtures \
+GHL_PIT_TOKEN=test GHL_LOCATION_ID=loc_test \
+./console &
+for f in cartridges/core/crm/adapters/gohighlevel/tests/fixtures/webhooks/*.json; do
+  curl -fsS -X POST -H 'Content-Type: application/json' --data-binary "@$f" \
+    "http://localhost:8080/api/ingest/endpoint/receive?e=mylocalpro-ghl"
+done
+```
+
+Assertion targets:
+- One `Payload` row per webhook fixture.
+- One `Execution` per `Payload`.
+- Classifier outputs match the table in "Webhook fixtures" above.
+- After running the API-fetch path against the same `GHL_MOCK_DIR`, the
+  resulting CRM entity graph is congruent with the webhook-replay state
+  (Alice's contact + Alice's opp at `ps_proposal_sent` + `apt_001` showed).