@nbt-dev/nbt 0.0.9 → 0.1.0

package/stdlib/workflows/schema.nbt

@@ -1,44 +1,92 @@
-
-# Question: How do we tie in cartridge metadata and workflow side effects into all this?
-
-enum WorkerStatus {
-  WAITING
-  RUNNING
-  TERMINATED
-}
-
-entity Worker {
+# An immutable, versioned workflow bundle (the JS artifact). Deploying new code
+# registers a new version; in-flight executions keep replaying against the version
+# they started on (the journal-header pin), so a code change can never corrupt a
+# running instance. A version's source is retained while ≥1 execution pins it and
+# dropped once the last drains (refcount drain-GC, in-memory). Durable so a pinned
+# version survives restart.
+entity WorkflowBundle {
   id: ulid
   createdAt: DateTime @default(now())
   updatedAt: DateTime @updatedAt
-  source: blob
+  version: u32
+  source: string
   contentHash: string
-  queue?: string
-  # TODO: We need some sort of termination options like a restart policy
 }
 
-# Stub — flesh out execution lifecycle fields later.
+# A single durable workflow instance. The journal is the WorkflowExecutionEvent
+# rows owned by this row (ordered by seq); status + result/error are the
+# materialized terminal state. cursor = number of resolved host commands
+# (== count of HOST_CALL_RESULT events) — the replay ordinal high-water mark.
 entity WorkflowExecution {
   id: ulid
   createdAt: DateTime @default(now())
   updatedAt: DateTime @updatedAt
-  status: string
+  status: string          # RUNNING (incl. async host call in flight) | SUSPENDED | COMPLETED | FAILED | CANCELLED
+  workflowName: string
+  args?: string           # JSON arguments passed to runWorkflow
+  result?: string         # JSON return value (COMPLETED)
+  error?: string          # message + stack (FAILED)
+  cursor: u32
+  lane?: string           # fairness lane; per-lane concurrency is capped so a burst of one lane can't starve others (default "default")
+  deployVersion: u32      # the bundle version this instance pins for its entire life (journal-header pin); replay always runs against this exact version
   events: WorkflowExecutionEvent[]
 }
 
-# Do we want this to be a string? 
+# A recurring trigger: fire `workflowName` whenever the cron expression matches.
+# Idempotent per minute-bucket via a deterministic execution id (schedule + bucket),
+# so a tick repeating within the same minute — or a restart mid-minute — never
+# double-fires. Evaluated leader-only by the executor tick.
+entity WorkflowSchedule {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  workflowName: string
+  cron: string            # 5-field: minute hour day-of-month month day-of-week
+  args?: string           # JSON arguments passed to each fired execution
+  lane?: string           # lane the fired executions run on
+  enabled: bool
+  lastFiredBucket: u32     # highest minute-bucket already fired; the durable idempotency watermark (no double-fire across ticks/restart)
+}
+
+# A durable record that a named event fired. Emissions ride the WAL (replicated
+# like any row); the leader-only executor reconcile drains the unprocessed ones,
+# looks up the event's triggers in the storage event registry, and fires each
+# triggered workflow exactly once cluster-wide (only the leader drains; the fired
+# id is derived from emission+index so a crash mid-drain re-fires idempotently).
+entity WorkflowEvent {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  event: string           # "<slug>:<event>" — the event-registry key
+  payload?: string        # JSON passed as args to each fired workflow
+  processed: bool         # set true once the leader has fired this emission's triggers
+}
+
 enum WorkflowExecutionEventKind {
-  WORKFLOW_EXECUTION_STARTED
-  WORKFLOW_STEP_SCHEDULED
-  WORKFLOW_STEP_STARTED
-  WORKFLOW_STEP_COMPLETED
-  WORKFLOW_EXECUTION_COMPLETED
+  HOST_CALL_INTENT        # recorded BEFORE a side effect is performed (durability)
+  HOST_CALL_RESULT        # the resolved value of a host command (replay source)
+  SUSPENDED               # parked awaiting an external command (e.g. a signal)
+  RESUMED                 # an external command arrived and re-drove the instance
+  COMPLETED               # workflow function returned
+  FAILED                  # workflow function threw
+  CANCELLED               # terminated by an explicit cancel request (cooperative)
+  RETRY                   # an async host call failed transiently and was retried (counter; payload = attempt)
+  CONTINUED               # ended via continue-as-new; payload = the child execution id carrying the work forward
 }
 
+# One journal entry. For HOST_CALL_* events seq is the command ordinal and
+# (capability, target, op) is the descriptor; payload carries the args (INTENT)
+# or the result JSON (RESULT). Lifecycle events (SUSPENDED/RESUMED/COMPLETED/
+# FAILED/CANCELLED/RETRY) carry payload only.
 entity WorkflowExecutionEvent {
   id: ulid
   createdAt: DateTime @default(now())
   updatedAt: DateTime @updatedAt
   execution: WorkflowExecution @relation(onDelete: Cascade)   # events are owned by their execution
+  seq: u32
   kind: WorkflowExecutionEventKind
+  capability?: string
+  target?: string
+  op?: string
+  payload?: string
 }

package/vendor/linux-x64/cartridges/auth/migrations/20260614000000_add_user_devtools_settings/migration.nbt

@@ -0,0 +1,4 @@
+migration add_user_devtools_settings {
+  add_field User devtoolsSettings string default("")
+  set_optional User devtoolsSettings true
+}

package/vendor/linux-x64/cartridges/auth/migrations/20260614000000_add_user_devtools_settings/schema_snapshot.nbt

@@ -0,0 +1,59 @@
+entity User {
+  name: string
+  username?: string
+  email?: string
+  emailVerified: bool
+  externalId?: string
+  capsVersion: u32
+  devtoolsSettings?: string
+  @@index([email])
+  @@index([externalId])
+  @@unique([email])
+}
+
+entity UserRole {
+  userId: string
+  cart: string
+  role: string
+  @@index([userId])
+}
+
+entity Session {
+  userId: string
+  token: string
+  expiresAt: DateTime
+  ipAddress?: string
+  userAgent?: string
+  @@index([token])
+  @@index([userId])
+}
+
+entity Account {
+  userId: string
+  providerId: string
+  password: string
+  accessToken: string
+  refreshToken: string
+  idToken: string
+  accessTokenExpiresAt: DateTime
+  refreshTokenExpiresAt: DateTime
+  scope: string
+  @@index([userId])
+}
+
+entity Verification {
+  identifier: string
+  value: string
+  expiresAt: DateTime
+  @@index([identifier])
+}
+
+entity ApiKey {
+  name: string
+  projectId: string
+  start: string
+  prefix: string
+  key: string
+  permissions: string
+  roles: string
+}

package/vendor/linux-x64/cartridges/auth/schema.nbt

@@ -1,6 +1,6 @@
 import crypto from "crypto"
 
-# Auth policy for the hand-written routes in native/runtime.jai (formerly the
+# Auth policy for the hand-written routes in modules/cart/auth.jai (formerly the
 # @public actions + the `authenticate` middleware block). These keep the
 # daemon's public-route + middleware manifest correct: public routes bypass the
 # /api/* auth gate; @middleware tells the proxy this cart exports the global
@@ -25,7 +25,8 @@ export entity User {
   email?: string
   emailVerified: bool
   externalId?: string
-  capsVersion: u32 # what is this?
+  capsVersion: u32  # capability version; bumped on every role change so cached authorizations invalidate
+  devtoolsSettings?: string  # per-operator devtools UI preferences, stored as a JSON blob
 
   @@index([email])
   @@index([externalId])
@@ -101,8 +102,8 @@ entity ApiKey {
 }
 
 # Console-operator SSH public keys. The console daemon authenticates SSH
-# connections by looking up rows here via modules/auth_lookup/ (in-process,
-# direct storage read — auth cart liveness is not required).
+# connections by reading these rows directly from storage (in-process —
+# auth cart liveness is not required).
 entity SshKey {
   id: ulid
   createdAt: DateTime @default(now())
@@ -114,29 +115,3 @@ entity SshKey {
   @@index([userId])
   @@unique([blob])
 }
-
-jai {
-find_synced_user :: (requestedId: string, email: string) -> (User, bool) {
-  if requestedId.count > 0 {
-    by_id, by_id_ok := get_user(requestedId);
-    if by_id_ok return by_id, true;
-
-    by_external := find_users_by_externalId(requestedId);
-    if by_external.count > 0 {
-      u, ok := get_user(by_external[0].id);
-      if ok return u, true;
-    }
-  }
-
-  if email.count > 0 {
-    by_email := find_users_by_email(email);
-    if by_email.count > 0 {
-      u, ok := get_user(by_email[0].id);
-      if ok return u, true;
-    }
-  }
-
-  empty: User;
-  return empty, false;
-}
-}

package/vendor/linux-x64/cartridges/calendar/schema.nbt

@@ -45,9 +45,8 @@ export entity Appointment {
 
   # Rendered embedding-template text. Persisted alongside the Appointment so
   # similarity search can score (target_text, candidate_text) pairs without
-  # re-rendering the customer's @embed template on every query. Populated at
-  # ingest by the customer's @embed binding
-  # (D09.10c). Generic surface — every customer composing similarity search
+  # re-rendering on every query. Populated at ingest by the customer's
+  # pipeline. Generic surface — every customer composing similarity search
   # over Appointments needs it; the *content* of the text is customer policy.
   embedText?: string
 

package/vendor/linux-x64/cartridges/crm/schema.nbt

@@ -77,11 +77,10 @@ export entity Deal {
   customData: document
 
   # Append-only suffix — fields below this comment must stay at the end
-  # of the entity declaration. Codegen serializes in declaration order;
+  # of the entity declaration. The row codec serializes in declaration order;
   # newly-added fields go *after* existing fields so the on-disk byte
   # layout stays forward-compatible (old records deserialize cleanly with
-  # trailing fields default-initialised). See the EOF-tolerant deserialize
-  # codegen in modules/nbt/codegen_serial.jai.
+  # trailing fields default-initialised).
 
   # D09.02 — generic lifecycle status, customer-domain. mylocalpro reacts
   # to `deal.status == "won"` to mark the source Appointment positive.
@@ -101,7 +100,7 @@ export entity Deal {
 
   # Date the deal closed (won or lost). Resolved at GHL adapter ingest
   # from Contact custom field "Date Sold" via CONTACT_LATEST_OPEN_DEAL.
-  # Append-only field — codegen serializes in declaration order, so
+  # Append-only field — the row codec serializes in declaration order, so
   # existing rows deserialize cleanly with this trailing default.
   closedDate?: DateTime
 }

package/vendor/linux-x64/cartridges/design/schema.nbt

@@ -136,5 +136,5 @@ entity Page {
 }
 
 # Behavior (former Design.create/save_version/get_head/list_versions actions +
-# tasks/parse.nbt @task) moved to native/runtime.jai over the generated ORM —
-# see design_register_extra_routes.
+# tasks/parse.nbt @task) moved to hand-written Jai over the generated ORM,
+# which also registers the HTTP routes.

package/vendor/linux-x64/cartridges/dns/schema.nbt

@@ -10,8 +10,8 @@
 #   - Future: TLS cart, custom gateway-domains cart.
 #
 # Schema only. All behavior (token verify, CF API calls, DNS record CRUD,
-# TXT verify polling) lives in native/runtime.jai as regular Jai over the
-# generated ORM — see domains_register_extra_routes.
+# TXT verify polling) lives in hand-written Jai over the generated ORM, which
+# also registers the HTTP routes.
 
 
 
@@ -21,7 +21,7 @@ entity DnsProvider {
   updatedAt: DateTime @updatedAt
   type: string               # "cloudflare"
   label: string              # user-facing name ("my CF account")
-  apiToken: string           # raw token (TODO: encrypt at rest — same status as phone cart's authToken)
+  apiToken: string           # provider API token (stored as-is)
   accountId: string          # CF account_id, needed for add_zone + registrar calls (optional)
   status: string             # "ACTIVE" | "INVALID" | "DISCONNECTED"
   lastCheckedAt: u64         # ms epoch — updated on connect + test

package/vendor/linux-x64/cartridges/email/schema.nbt

@@ -1,7 +1,7 @@
 # Email cartridge — transactional send + synthetic inboxes.
 #
-# Provider: SendGrid (modules/sendgrid). Nothing in the user-facing surface
-# mentions SendGrid; the cart is branded "Email".
+# Provider: SendGrid. Nothing in the user-facing surface mentions SendGrid;
+# the cart is branded "Email".
 #
 # Per-console model:
 #   - Every console auto-provisions `<console>.nbt.dev` as the default mail
@@ -13,21 +13,22 @@
 #     register with SendGrid Inbound Parse + Domain Authentication, poll
 #     until everything is green.
 #
-# Ops prerequisites (one-time, see plans/squishy-puzzling-spindle.md):
-#   - SENDGRID_API_KEY in console env.
-#   - SENDGRID_EVENT_PUBKEY in console env (base64 SPKI for event webhook verification).
+# Ops prerequisites (one-time):
+#   - Provider API key in console env.
+#   - Provider event-webhook public key in console env (base64 SPKI for event
+#     webhook signature verification).
 #   - `*.nbt.dev MX 10 mx.sendgrid.net` at zone level.
 #   - SendGrid Inbound Parse wildcard entry + per-console entries (latter are
 #     created programmatically by MailDomain.ensure_default).
 
-# Behavior (the former main.nbt actions) lives in native/runtime.jai over the
-# generated ORM — see email_register_extra_routes. These imports trigger the
-# #load of the native files into the cart module scope.
+# Behavior (the former main.nbt actions) lives in hand-written Jai over the
+# generated ORM, which also registers the HTTP routes. The import below pulls
+# the crypto module into the cart scope.
 import crypto from "crypto"
 
-# Auth policy for the hand-written routes (formerly @public actions). The
-# handlers live in native/runtime.jai; these keep the daemon's public-route
-# manifest correct so the /api/* auth gate is bypassed for SendGrid webhooks.
+# Auth policy for the hand-written routes (formerly @public actions). These
+# keep the daemon's public-route manifest correct so the /api/* auth gate is
+# bypassed for SendGrid webhooks.
 @public_route "/api/email/inbound"
 @public_route "/api/email/events"
 

package/vendor/linux-x64/cartridges/ingest/schema.nbt

@@ -1,7 +1,7 @@
-# Behavior (the former main.nbt actions) lives in native/runtime.jai over the
-# generated ORM — see
-# ingest_register_extra_routes. All routes stay auth-gated by the daemon
-# middleware (no @public_route), matching the pre-migration manifest.
+# Behavior (the former main.nbt actions) lives in hand-written Jai over the
+# generated ORM, which also registers the HTTP routes. All routes stay
+# auth-gated by the daemon middleware (no @public_route), matching the
+# pre-migration manifest.
 
 entity Endpoint {
   id: ulid

package/vendor/linux-x64/cartridges/notifications/schema.nbt

@@ -2,8 +2,8 @@
 # subscriptions. The portal owns browser permission prompts and service worker
 # registration; this cartridge owns the resulting state.
 #
-# Behavior (the former main.nbt actions) lives in native/runtime.jai as regular
-# Jai over the generated ORM — see notifications_register_extra_routes.
+# Behavior (the former main.nbt actions) lives in hand-written Jai over the
+# generated ORM, which also registers the HTTP routes.
 
 
 entity Notification {

package/vendor/linux-x64/cartridges/phone/schema.nbt

@@ -1,21 +1,20 @@
 # Phone cartridge — Twilio number management, SMS, click-to-call.
 #
-# Per-tenant model (see modules/twilio/module.jai for the rationale):
-#   - One master Twilio account owned by the platform (SID + auth token in
-#     env: TWILIO_MASTER_SID, TWILIO_MASTER_TOKEN).
+# Per-tenant model:
+#   - One master Twilio account owned by the platform (master SID + auth token
+#     supplied via env).
 #   - Each tenant gets a TwilioAccount row with its own subaccount SID and
 #     auth token. All per-tenant API calls authenticate as the subaccount.
 #   - Webhooks are configured to URLs under the tenant's public base
 #     (TwilioAccount.publicUrlBase), which the gateway routes back to this
 #     cart. Signature verification uses the subaccount's auth token.
 
-# Behavior (the former jai{} helper blocks + actions) lives in
-# native/runtime.jai over the generated ORM — see phone_register_extra_routes,
-# which registers the HTTP routes.
+# Behavior (the former actions) lives in hand-written Jai over the generated
+# ORM, which also registers the HTTP routes.
 
-# Auth policy for the hand-written routes (formerly @public actions). The
-# handlers live in native/runtime.jai; these keep the daemon's public-route
-# manifest correct so the /api/* auth gate is bypassed for Twilio webhooks.
+# Auth policy for the hand-written routes (formerly @public actions). These
+# keep the daemon's public-route manifest correct so the /api/* auth gate is
+# bypassed for Twilio webhooks.
 @public_route "/api/phone/webhook/sms"
 @public_route "/api/phone/webhook/status"
 
@@ -25,7 +24,7 @@ entity TwilioAccount {
   updatedAt: DateTime @updatedAt
   name: string               # operator-facing label
   subAccountSid: string      # AC... — populated by provision()
-  authToken: string          # subaccount auth token (TODO: encrypt at rest)
+  authToken: string          # subaccount auth token (stored as-is)
   publicUrlBase: string      # e.g. "https://acme.console.app"
   status: string             # PENDING | ACTIVE | SUSPENDED | CLOSED
   retentionDays: s32         # 0 = keep message bodies forever; N = null body after N days

package/vendor/linux-x64/cartridges/workflows/schema.nbt

@@ -1,44 +1,92 @@
-
-# Question: How do we tie in cartridge metadata and workflow side effects into all this?
-
-enum WorkerStatus {
-  WAITING
-  RUNNING
-  TERMINATED
-}
-
-entity Worker {
+# An immutable, versioned workflow bundle (the JS artifact). Deploying new code
+# registers a new version; in-flight executions keep replaying against the version
+# they started on (the journal-header pin), so a code change can never corrupt a
+# running instance. A version's source is retained while ≥1 execution pins it and
+# dropped once the last drains (refcount drain-GC, in-memory). Durable so a pinned
+# version survives restart.
+entity WorkflowBundle {
   id: ulid
   createdAt: DateTime @default(now())
   updatedAt: DateTime @updatedAt
-  source: blob
+  version: u32
+  source: string
   contentHash: string
-  queue?: string
-  # TODO: We need some sort of termination options like a restart policy
 }
 
-# Stub — flesh out execution lifecycle fields later.
+# A single durable workflow instance. The journal is the WorkflowExecutionEvent
+# rows owned by this row (ordered by seq); status + result/error are the
+# materialized terminal state. cursor = number of resolved host commands
+# (== count of HOST_CALL_RESULT events) — the replay ordinal high-water mark.
 entity WorkflowExecution {
   id: ulid
   createdAt: DateTime @default(now())
   updatedAt: DateTime @updatedAt
-  status: string
+  status: string          # RUNNING (incl. async host call in flight) | SUSPENDED | COMPLETED | FAILED | CANCELLED
+  workflowName: string
+  args?: string           # JSON arguments passed to runWorkflow
+  result?: string         # JSON return value (COMPLETED)
+  error?: string          # message + stack (FAILED)
+  cursor: u32
+  lane?: string           # fairness lane; per-lane concurrency is capped so a burst of one lane can't starve others (default "default")
+  deployVersion: u32      # the bundle version this instance pins for its entire life (journal-header pin); replay always runs against this exact version
   events: WorkflowExecutionEvent[]
 }
 
-# Do we want this to be a string? 
+# A recurring trigger: fire `workflowName` whenever the cron expression matches.
+# Idempotent per minute-bucket via a deterministic execution id (schedule + bucket),
+# so a tick repeating within the same minute — or a restart mid-minute — never
+# double-fires. Evaluated leader-only by the executor tick.
+entity WorkflowSchedule {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  workflowName: string
+  cron: string            # 5-field: minute hour day-of-month month day-of-week
+  args?: string           # JSON arguments passed to each fired execution
+  lane?: string           # lane the fired executions run on
+  enabled: bool
+  lastFiredBucket: u32     # highest minute-bucket already fired; the durable idempotency watermark (no double-fire across ticks/restart)
+}
+
+# A durable record that a named event fired. Emissions ride the WAL (replicated
+# like any row); the leader-only executor reconcile drains the unprocessed ones,
+# looks up the event's triggers in the storage event registry, and fires each
+# triggered workflow exactly once cluster-wide (only the leader drains; the fired
+# id is derived from emission+index so a crash mid-drain re-fires idempotently).
+entity WorkflowEvent {
+  id: ulid
+  createdAt: DateTime @default(now())
+  updatedAt: DateTime @updatedAt
+  event: string           # "<slug>:<event>" — the event-registry key
+  payload?: string        # JSON passed as args to each fired workflow
+  processed: bool         # set true once the leader has fired this emission's triggers
+}
+
 enum WorkflowExecutionEventKind {
-  WORKFLOW_EXECUTION_STARTED
-  WORKFLOW_STEP_SCHEDULED
-  WORKFLOW_STEP_STARTED
-  WORKFLOW_STEP_COMPLETED
-  WORKFLOW_EXECUTION_COMPLETED
+  HOST_CALL_INTENT        # recorded BEFORE a side effect is performed (durability)
+  HOST_CALL_RESULT        # the resolved value of a host command (replay source)
+  SUSPENDED               # parked awaiting an external command (e.g. a signal)
+  RESUMED                 # an external command arrived and re-drove the instance
+  COMPLETED               # workflow function returned
+  FAILED                  # workflow function threw
+  CANCELLED               # terminated by an explicit cancel request (cooperative)
+  RETRY                   # an async host call failed transiently and was retried (counter; payload = attempt)
+  CONTINUED               # ended via continue-as-new; payload = the child execution id carrying the work forward
 }
 
+# One journal entry. For HOST_CALL_* events seq is the command ordinal and
+# (capability, target, op) is the descriptor; payload carries the args (INTENT)
+# or the result JSON (RESULT). Lifecycle events (SUSPENDED/RESUMED/COMPLETED/
+# FAILED/CANCELLED/RETRY) carry payload only.
 entity WorkflowExecutionEvent {
   id: ulid
   createdAt: DateTime @default(now())
   updatedAt: DateTime @updatedAt
   execution: WorkflowExecution @relation(onDelete: Cascade)   # events are owned by their execution
+  seq: u32
   kind: WorkflowExecutionEventKind
+  capability?: string
+  target?: string
+  op?: string
+  payload?: string
 }

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

@@ -1,85 +0,0 @@
-# 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`.